From 8ec856c1ecd2d88a2ba3a8517da746857a1c57b9 Mon Sep 17 00:00:00 2001 From: neal <130699270+possiblyneal@users.noreply.github.com> Date: Sat, 21 Nov 2026 15:39:39 -0500 Subject: [PATCH 1/3] fix: remove facets when their targets are deleted Generated-By: gpt-6.1-terra --- CLAUDE.md | 7 ++ src/functions/auto-forget.ts | 11 ++- src/functions/evict.ts | 21 ++++-- src/functions/facets.ts | 106 ++++++++++++++++++++--------- src/functions/governance.ts | 17 +++-- src/functions/lessons.ts | 12 +++- src/functions/observe.ts | 29 +++++--- src/functions/remember.ts | 60 +++++++++------- src/functions/retention.ts | 6 +- test/auto-forget.test.ts | 22 ++++++ test/facets.test.ts | 81 +++++++++++++++++++++- test/forget-by-id-surfaces.test.ts | 11 +++ test/governance.test.ts | 17 +++++ test/lessons.test.ts | 10 +++ test/observe-session-cap.test.ts | 11 +++ 15 files changed, 335 insertions(+), 86 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 07afc76354..7b498027c6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -257,6 +257,13 @@ before any store mutation. Rows without string keys are dropped and counted in ` legacy keyless Session stubs do not prevent restoring the rest. Access logs and legacy Memory session IDs retain their normal normalization. This preflight does not make replacement transactional. +### Facet cleanup +Ordinary hard deletes of Observations, Memories and Lessons use `deleteWithFacets()` +(`src/functions/facets.ts`), which serializes deletion with Facet tag and untag mutations and +best-effort removes Facets for the IDs actually deleted. A later tag on a missing ID remains +allowed. Import replacement and snapshot restore keep their own replacement semantics; this is +not an orphan sweep. Memory writers take `MEMORY_WRITE_LOCK` before the Facet lock. + ### Graph Eviction Every path that hard-deletes Observations or Memories (`mem::evict`, `mem::observe` session-cap eviction, `mem::auto-forget`, `mem::forget`, `mem::retention-evict`, `mem::governance-delete`, diff --git a/src/functions/auto-forget.ts b/src/functions/auto-forget.ts index 3479726c25..45966745a6 100644 --- a/src/functions/auto-forget.ts +++ b/src/functions/auto-forget.ts @@ -1,3 +1,4 @@ +import { deleteWithFacets } from "./facets.js"; import type { ISdk } from "../engine/types.js"; import type { Memory, CompressedObservation, Session } from "../types.js"; import { KV } from "../state/schema.js"; @@ -73,7 +74,10 @@ export function registerAutoForgetFunction(sdk: ISdk, kv: StateKV): void { await withKeyedLock(MEMORY_WRITE_LOCK, async () => { const current = await kv.get(KV.memories, mem.id); if (!current) return; - await deleteIndexed(kv, KV.memories, mem.id); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, KV.memories, mem.id); + removed.push(mem.id); + }); if (current.imageRef) { await decrementImageRef(kv, sdk, current.imageRef).catch((error) => { logger.warn("Auto-forget could not release image reference", { memoryId: current.id, error: String(error) }); @@ -181,7 +185,10 @@ export function registerAutoForgetFunction(sdk: ISdk, kv: StateKV): void { if (!dryRun) { let deletedOk = false; try { - await deleteIndexed(kv, KV.observations(sessions[i].id), obs.id); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, KV.observations(sessions[i].id), obs.id); + removed.push(obs.id); + }); deletedOk = true; } catch { deletedOk = false; diff --git a/src/functions/evict.ts b/src/functions/evict.ts index b4067969f7..7ae2ca869e 100644 --- a/src/functions/evict.ts +++ b/src/functions/evict.ts @@ -1,3 +1,4 @@ +import { deleteWithFacets } from "./facets.js"; import type { ISdk } from "../engine/types.js"; import type { Session, @@ -275,7 +276,10 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { lowImportanceIds.add(o.id); } else { try { - await deleteIndexed(kv, KV.observations(session.id), o.id); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, KV.observations(session.id), o.id); + removed.push(o.id); + }); stats.lowImportanceObs++; lowImportanceIds.add(o.id); countRemoval(session.id); @@ -321,7 +325,10 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { } else { for (const o of toEvict) { try { - await deleteIndexed(kv, KV.observations(o.sessionId), o.id); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, KV.observations(o.sessionId), o.id); + removed.push(o.id); + }); stats.capEvictions++; countRemoval(o.sessionId); evictedSourceIds.push(o.id); @@ -363,7 +370,10 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { const removed = await withKeyedLock(MEMORY_WRITE_LOCK, async () => { const current = await kv.get(KV.memories, mem.id); if (!current) return false; - await deleteIndexed(kv, KV.memories, mem.id); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, KV.memories, mem.id); + removed.push(mem.id); + }); if (current.imageRef) { await decrementImageRef(kv, sdk, current.imageRef).catch((err: unknown) => { logger.warn("Eviction could not release image reference", { @@ -410,7 +420,10 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { const removed = await withKeyedLock(MEMORY_WRITE_LOCK, async () => { const current = await kv.get(KV.memories, mem.id); if (!current) return false; - await deleteIndexed(kv, KV.memories, mem.id); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, KV.memories, mem.id); + removed.push(mem.id); + }); if (current.imageRef) { await decrementImageRef(kv, sdk, current.imageRef).catch((err: unknown) => { logger.warn("Eviction could not release image reference", { diff --git a/src/functions/facets.ts b/src/functions/facets.ts index 12087421c5..ecae3e8a64 100644 --- a/src/functions/facets.ts +++ b/src/functions/facets.ts @@ -2,8 +2,42 @@ import type { ISdk } from "../engine/types.js"; import type { StateKV } from "../state/kv.js"; import { KV, generateId } from "../state/schema.js"; import type { Facet } from "../types.js"; +import { withKeyedLock } from "../state/keyed-mutex.js"; +import { logger } from "../logger.js"; import { scrubFields } from "./privacy.js"; +const FACET_LOCK = "mem:facet:mutate"; + +export async function deleteWithFacets(kv: StateKV, remove: (deleted: string[]) => Promise): Promise { + return withKeyedLock(FACET_LOCK, async () => { + const deleted: string[] = []; + try { + return await remove(deleted); + } finally { + if (deleted.length) { + try { + const targets = new Set(deleted); + let after: string | undefined; + for (;;) { + const page = await kv.listPage(KV.facets, after, 256); + for (const row of page) { + if (targets.has(row.value.targetId)) { + await kv.delete(KV.facets, row.key).catch((error) => { + logger.warn("Facet cleanup failed", { facetId: row.key, error: String(error) }); + }); + } + } + if (page.length < 256) break; + after = page[page.length - 1].key; + } + } catch (error) { + logger.warn("Facet cleanup failed", { error: String(error) }); + } + } + } + }); +} + export function registerFacetsFunction(sdk: ISdk, kv: StateKV): void { sdk.registerFunction("mem::facet-tag", async (data: { @@ -44,28 +78,30 @@ export function registerFacetsFunction(sdk: ISdk, kv: StateKV): void { const dimension = data.dimension.trim(); const value = data.value.trim(); - const existing = await kv.list(KV.facets); - const duplicate = existing.find( - (f) => - f.targetId === data.targetId && - f.dimension === dimension && - f.value === value, - ); - if (duplicate) { - return { success: true, facet: duplicate, skipped: true }; - } + return withKeyedLock(FACET_LOCK, async () => { + const existing = await kv.list(KV.facets); + const duplicate = existing.find( + (f) => + f.targetId === data.targetId && + f.dimension === dimension && + f.value === value, + ); + if (duplicate) { + return { success: true, facet: duplicate, skipped: true }; + } - const facet: Facet = { - id: generateId("fct"), - targetId: data.targetId, - targetType: data.targetType as Facet["targetType"], - dimension, - value, - createdAt: new Date().toISOString(), - }; + const facet: Facet = { + id: generateId("fct"), + targetId: data.targetId, + targetType: data.targetType as Facet["targetType"], + dimension, + value, + createdAt: new Date().toISOString(), + }; - await kv.set(KV.facets, facet.id, facet); - return { success: true, facet }; + await kv.set(KV.facets, facet.id, facet); + return { success: true, facet }; + }); }, ); @@ -82,22 +118,24 @@ export function registerFacetsFunction(sdk: ISdk, kv: StateKV): void { return { success: false, error: "dimension is required" }; } - const all = await kv.list(KV.facets); - const matches = all.filter((f) => { - if (f.targetId !== data.targetId || f.dimension !== data.dimension) { - return false; - } - if (data.value !== undefined) { - return f.value === data.value; - } - return true; - }); + return withKeyedLock(FACET_LOCK, async () => { + const all = await kv.list(KV.facets); + const matches = all.filter((f) => { + if (f.targetId !== data.targetId || f.dimension !== data.dimension) { + return false; + } + if (data.value !== undefined) { + return f.value === data.value; + } + return true; + }); - for (const f of matches) { - await kv.delete(KV.facets, f.id); - } + for (const f of matches) { + await kv.delete(KV.facets, f.id); + } - return { success: true, removed: matches.length }; + return { success: true, removed: matches.length }; + }); }, ); diff --git a/src/functions/governance.ts b/src/functions/governance.ts index af7afc777a..220b0c63d0 100644 --- a/src/functions/governance.ts +++ b/src/functions/governance.ts @@ -4,6 +4,7 @@ import { KV } from "../state/schema.js"; import type { StateKV } from "../state/kv.js"; import { recordAudit, safeAudit, queryAudit } from "./audit.js"; import { deleteIndexed } from "./search.js"; +import { deleteWithFacets } from "./facets.js"; import { withKeyedLock } from "../state/keyed-mutex.js"; import { MEMORY_WRITE_LOCK } from "../state/memory-utils.js"; import { evictGraphForSources } from "./graph-eviction.js"; @@ -31,7 +32,10 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { if (!mem) { notFound.push(id); } else { - await deleteIndexed(kv, KV.memories, id); + await deleteWithFacets(kv, async (deleted) => { + await deleteIndexed(kv, KV.memories, id); + deleted.push(id); + }); // The same teardown mem::forget does, so the two single-item // delete paths cannot diverge in what they release. if (mem.imageRef) { @@ -129,11 +133,12 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { const failures: Array<{ id: string; error: string }> = []; for (let i = 0; i < candidates.length; i += BATCH_SIZE) { const batch = candidates.slice(i, i + BATCH_SIZE); - const results = await Promise.allSettled( - batch.map((mem) => - withKeyedLock(MEMORY_WRITE_LOCK, () => - deleteIndexed(kv, KV.memories, mem.id), - ), + const results = await withKeyedLock(MEMORY_WRITE_LOCK, () => + deleteWithFacets(kv, async (deleted) => + Promise.allSettled(batch.map(async (mem) => { + await deleteIndexed(kv, KV.memories, mem.id); + deleted.push(mem.id); + })), ), ); results.forEach((result, j) => { diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 579d1316ba..729979b644 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -1,3 +1,4 @@ +import { deleteWithFacets } from "./facets.js"; import type { ISdk } from "../engine/types.js"; import type { StateKV } from "../state/kv.js"; import { KV, fingerprintId, jaccardOverlap, jaccardText } from "../state/schema.js"; @@ -348,7 +349,10 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { return { success: false, error: "lesson not found" }; } - await kv.delete(KV.lessons, lesson.id); + await deleteWithFacets(kv, async (removed) => { + await kv.delete(KV.lessons, lesson.id); + removed.push(lesson.id); + }); lessonRecords.delete(lesson.id); if (lessonIndex) lessonIndex.remove(lesson.id); noteLessonMutation(); @@ -369,7 +373,11 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { reason: string, ): Promise { if (expired.length === 0) return []; - const deletedIds = await kv.deleteManyIfUnchanged(KV.lessons, expired); + const deletedIds = await deleteWithFacets(kv, async (removed) => { + const ids = await kv.deleteManyIfUnchanged(KV.lessons, expired); + removed.push(...ids); + return ids; + }); for (const id of deletedIds) { lessonRecords.delete(id); if (lessonIndex) lessonIndex.remove(id); diff --git a/src/functions/observe.ts b/src/functions/observe.ts index eed07e2a7a..d118963070 100644 --- a/src/functions/observe.ts +++ b/src/functions/observe.ts @@ -1,3 +1,4 @@ +import { deleteWithFacets } from "./facets.js"; import { TriggerAction, type ISdk } from "../engine/types.js"; import type { CompressedObservation, RawObservation, HookPayload, Origin, Session } from "../types.js"; @@ -108,18 +109,24 @@ async function evictOverCap( ) .slice(0, excess); const evictedIds: string[] = []; - for (const obs of victims) { - try { - await deleteIndexed(kv, scope, obs.id); - evictedIds.push(obs.id); - } catch (err) { - logger.warn("Session cap eviction failed", { - sessionId, - obsId: obs.id, - error: err instanceof Error ? err.message : String(err), - }); - continue; + await deleteWithFacets(kv, async (removed) => { + for (const obs of victims) { + try { + await deleteIndexed(kv, scope, obs.id); + removed.push(obs.id); + evictedIds.push(obs.id); + } catch (err) { + logger.warn("Session cap eviction failed", { + sessionId, + obsId: obs.id, + error: err instanceof Error ? err.message : String(err), + }); + } } + }); + const evictedSet = new Set(evictedIds); + for (const obs of victims) { + if (!evictedSet.has(obs.id)) continue; // The row is gone, so it counts as evicted even if releasing its image // fails; a failed release is retried with the others. for (const filePath of new Set([obs.imageData, obs.imageRef].filter((p): p is string => !!p))) { diff --git a/src/functions/remember.ts b/src/functions/remember.ts index 20520a995b..e227def155 100644 --- a/src/functions/remember.ts +++ b/src/functions/remember.ts @@ -1,3 +1,4 @@ +import { deleteWithFacets } from "./facets.js"; import { TriggerAction, type ISdk } from "../engine/types.js"; import type { Memory } from "../types.js"; import { KV, generateId, jaccardSimilarity, fingerprintId } from "../state/schema.js"; @@ -397,7 +398,10 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void { await withKeyedLock(MEMORY_WRITE_LOCK, async () => { const mem = await kv.get(KV.memories, memoryId); if (mem) { - await deleteIndexed(kv, KV.memories, memoryId); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, KV.memories, memoryId); + removed.push(memoryId); + }); if (mem.imageRef) { await decrementImageRef(kv, sdk, mem.imageRef); } @@ -412,23 +416,26 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void { data.observationIds && data.observationIds.length > 0 ) { - for (const obsId of data.observationIds) { - const obs = await kv.get<{ imageData?: string; imageRef?: string }>( - KV.observations(data.sessionId), - obsId, - ); - // An id that is not there is not an error, but it is also not a - // removal: counting it would tell the caller their record is - // gone when nothing of theirs was ever found. - if (!obs) continue; - await deleteIndexed(kv, KV.observations(data.sessionId), obsId); - if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData); - if (obs.imageRef && obs.imageRef !== obs.imageData) { - await decrementImageRef(kv, sdk, obs.imageRef); + await deleteWithFacets(kv, async (removed) => { + for (const obsId of data.observationIds!) { + const obs = await kv.get<{ imageData?: string; imageRef?: string }>( + KV.observations(data.sessionId!), + obsId, + ); + // An id that is not there is not an error, but it is also not a + // removal: counting it would tell the caller their record is + // gone when nothing of theirs was ever found. + if (!obs) continue; + await deleteIndexed(kv, KV.observations(data.sessionId!), obsId); + removed.push(obsId); + if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData); + if (obs.imageRef && obs.imageRef !== obs.imageData) { + await decrementImageRef(kv, sdk, obs.imageRef); + } + deletedObservationIds.push(obsId); + deleted++; } - deletedObservationIds.push(obsId); - deleted++; - } + }); } if ( @@ -439,15 +446,18 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void { const observations = await kv.list<{ id: string; imageData?: string; imageRef?: string }>( KV.observations(data.sessionId), ); - for (const obs of observations) { - await deleteIndexed(kv, KV.observations(data.sessionId), obs.id); - if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData); - if (obs.imageRef && obs.imageRef !== obs.imageData) { - await decrementImageRef(kv, sdk, obs.imageRef); + await deleteWithFacets(kv, async (removed) => { + for (const obs of observations) { + await deleteIndexed(kv, KV.observations(data.sessionId!), obs.id); + removed.push(obs.id); + if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData); + if (obs.imageRef && obs.imageRef !== obs.imageData) { + await decrementImageRef(kv, sdk, obs.imageRef); + } + deletedObservationIds.push(obs.id); + deleted++; } - deletedObservationIds.push(obs.id); - deleted++; - } + }); // Counted only where a record was actually there, the same rule // the memory and observation branches follow. const [session, summary] = await Promise.all([ diff --git a/src/functions/retention.ts b/src/functions/retention.ts index 0b9b86d2f7..ca48ecf3fb 100644 --- a/src/functions/retention.ts +++ b/src/functions/retention.ts @@ -1,3 +1,4 @@ +import { deleteWithFacets } from "./facets.js"; import type { ISdk } from "../engine/types.js"; import type { Memory, @@ -350,7 +351,10 @@ export function registerRetentionFunctions( const evictScope = scope; const remove = async () => { const mem = await kv.get(evictScope, candidate.memoryId); - await deleteIndexed(kv, evictScope, candidate.memoryId); + await deleteWithFacets(kv, async (removed) => { + await deleteIndexed(kv, evictScope, candidate.memoryId); + removed.push(candidate.memoryId); + }); if (mem && mem.imageRef) { await decrementImageRef(kv, sdk, mem.imageRef).catch((error) => { logger.warn("Retention could not release image reference", { memoryId: mem.id, error: String(error) }); diff --git a/test/auto-forget.test.ts b/test/auto-forget.test.ts index be70d35088..7deaf81545 100644 --- a/test/auto-forget.test.ts +++ b/test/auto-forget.test.ts @@ -37,6 +37,7 @@ function mockKV() { } return row; }, + listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), list: async (scope: string): Promise => { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; @@ -90,6 +91,27 @@ describe("Auto-Forget Function", () => { registerAutoForgetFunction(sdk as never, kv as never); }); + it("cleans Facets of expired Memories without changing the indexed deletion", async () => { + const memory = makeMemory({ id: "mem_expired", forgetAfter: "2020-01-01T00:00:00Z" }); + await kv.set("mem:memories", memory.id, memory); + await kv.set("mem:facets", "facet", { id: "facet", targetId: memory.id }); + getSearchIndex().add(memoryToObservation(memory)); + await sdk.trigger("mem::auto-forget", {}); + expect(await kv.get("mem:facets", "facet")).toBeNull(); + expect(await kv.get("mem:memories", memory.id)).toBeNull(); + expect(getSearchIndex().has(memory.id)).toBe(false); + }); + + it("keeps deletion and index cleanup when Facet lookup fails", async () => { + const memory = makeMemory({ id: "mem_failed_cleanup", forgetAfter: "2020-01-01T00:00:00Z" }); + await kv.set("mem:memories", memory.id, memory); + getSearchIndex().add(memoryToObservation(memory)); + kv.listPage = async () => { throw new Error("Facet lookup failed"); }; + await sdk.trigger("mem::auto-forget", {}); + expect(await kv.get("mem:memories", memory.id)).toBeNull(); + expect(getSearchIndex().has(memory.id)).toBe(false); + }); + it("detects and deletes TTL-expired memories", async () => { const expired = makeMemory({ id: "mem_expired", diff --git a/test/facets.test.ts b/test/facets.test.ts index 061dc52068..448699af3a 100644 --- a/test/facets.test.ts +++ b/test/facets.test.ts @@ -4,7 +4,7 @@ vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, })); -import { registerFacetsFunction } from "../src/functions/facets.js"; +import { deleteWithFacets, registerFacetsFunction } from "../src/functions/facets.js"; import type { Facet } from "../src/types.js"; function mockKV() { @@ -21,6 +21,8 @@ function mockKV() { delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); }, + listPage: async (scope: string, after: string | undefined, limit: number) => + [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), list: async (scope: string): Promise => { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; @@ -56,6 +58,83 @@ describe("Facets Functions", () => { registerFacetsFunction(sdk as never, kv as never); }); + it("removes tags of deleted targets but preserves unrelated tags", async () => { + for (const targetId of ["gone", "kept"]) { + await sdk.trigger("mem::facet-tag", { targetId, targetType: "memory", dimension: "kind", value: "test" }); + } + await deleteWithFacets(kv as never, async (deleted) => { deleted.push("gone"); }); + const result = await sdk.trigger("mem::facet-query", { matchAny: ["kind:test"] }) as { results: Array<{ targetId: string }> }; + expect(result.results.map((item) => item.targetId)).toEqual(["kept"]); + }); + + it("orders a concurrent tag before deletion and allows a later tag", async () => { + let release!: () => void; + const wait = new Promise((resolve) => { release = resolve; }); + let entered!: () => void; + const started = new Promise((resolve) => { entered = resolve; }); + const originalSet = kv.set; + kv.set = async (...args) => { entered(); await wait; return originalSet(...args); }; + const data = { targetId: "gone", targetType: "memory", dimension: "kind", value: "test" }; + const tag = sdk.trigger("mem::facet-tag", data); + await started; + const deletion = deleteWithFacets(kv as never, async (deleted) => { deleted.push("gone"); }); + release(); + await Promise.all([tag, deletion]); + expect((await sdk.trigger("mem::facet-get", { targetId: "gone" })).dimensions).toEqual([]); + await sdk.trigger("mem::facet-tag", data); + expect((await sdk.trigger("mem::facet-get", { targetId: "gone" })).dimensions).toHaveLength(1); + }); + + it("cleans successful IDs when a batch fails", async () => { + for (const targetId of ["one", "two"]) await sdk.trigger("mem::facet-tag", { targetId, targetType: "memory", dimension: "kind", value: "test" }); + await expect(deleteWithFacets(kv as never, async (deleted) => { deleted.push("one"); throw new Error("delete failed"); })).rejects.toThrow("delete failed"); + const result = await sdk.trigger("mem::facet-query", { matchAny: ["kind:test"] }); + expect(result.results.map((item: { targetId: string }) => item.targetId)).toEqual(["two"]); + }); + + it("preserves deletion results when Facet cleanup fails", async () => { + await sdk.trigger("mem::facet-tag", { targetId: "gone", targetType: "memory", dimension: "kind", value: "test" }); + kv.listPage = async () => { throw new Error("cleanup failed"); }; + const result = await deleteWithFacets(kv as never, async (deleted) => { deleted.push("gone"); return "removed"; }); + expect(result).toBe("removed"); + }); + + it("keeps a tag ordered after a deletion already in progress", async () => { + let release!: () => void; + const wait = new Promise((resolve) => { release = resolve; }); + let entered!: () => void; + const started = new Promise((resolve) => { entered = resolve; }); + const data = { targetId: "gone", targetType: "memory", dimension: "kind", value: "test" }; + await sdk.trigger("mem::facet-tag", data); + const deletion = deleteWithFacets(kv as never, async (removed) => { entered(); await wait; removed.push("gone"); }); + await started; + const tag = sdk.trigger("mem::facet-tag", data); + release(); + await Promise.all([deletion, tag]); + expect((await sdk.trigger("mem::facet-get", { targetId: "gone" })).dimensions).toHaveLength(1); + }); + + it("continues cleanup when one Facet cannot be removed", async () => { + for (const targetId of ["one", "two"]) await sdk.trigger("mem::facet-tag", { targetId, targetType: "memory", dimension: "kind", value: "test" }); + const originalDelete = kv.delete; + let failed = false; + kv.delete = async (scope, key) => { if (!failed) { failed = true; throw new Error("delete failed"); } await originalDelete(scope, key); }; + await deleteWithFacets(kv as never, async (removed) => { removed.push("one", "two"); }); + const result = await sdk.trigger("mem::facet-query", { matchAny: ["kind:test"] }); + expect(result.results).toHaveLength(1); + }); + + it("cleans a batch across Facet pages without skipping survivors", async () => { + for (let i = 0; i < 520; i++) { + const id = String(i).padStart(4, "0"); + await kv.set("mem:facets", id, { id, targetId: i % 2 ? "keep" : "remove", dimension: "kind", value: "test" }); + } + await deleteWithFacets(kv as never, async (removed) => { removed.push("remove"); }); + const remaining = await kv.list("mem:facets"); + expect(remaining).toHaveLength(260); + expect(remaining.every((facet) => facet.targetId === "keep")).toBe(true); + }); + describe("mem::facet-tag", () => { it("tags a target with a facet", async () => { const result = (await sdk.trigger("mem::facet-tag", { diff --git a/test/forget-by-id-surfaces.test.ts b/test/forget-by-id-surfaces.test.ts index f68187975d..a92b75b5d1 100644 --- a/test/forget-by-id-surfaces.test.ts +++ b/test/forget-by-id-surfaces.test.ts @@ -8,6 +8,7 @@ vi.mock("../src/state/keyed-mutex.js", () => ({ withKeyedLock: (_key: string, fn: () => Promise) => fn(), })); +import { registerFacetsFunction } from "../src/functions/facets.js"; import { registerRememberFunction } from "../src/functions/remember.js"; import { registerGovernanceFunction } from "../src/functions/governance.js"; import { registerApiTriggers } from "../src/triggers/api.js"; @@ -38,6 +39,7 @@ function mockKV() { delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); }, + listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), update: async () => {}, list: async (scope: string): Promise => Array.from(store.get(scope)?.values() ?? []) as T[], @@ -93,6 +95,7 @@ function surfaces(): Surfaces { const kv = mockKV(); const sdk = mockSdk(); registerRememberFunction(sdk as never, kv as never); + registerFacetsFunction(sdk as never, kv as never); registerGovernanceFunction(sdk as never, kv as never); registerApiTriggers(sdk as never, kv as never, SECRET); registerMcpEndpoints(sdk as never, kv as never, SECRET); @@ -133,6 +136,14 @@ describe("memory_forget MCP tool", () => { getSearchIndex().clear(); }); + it("removes Facets when forgetting a memory", async () => { + const { kv, sdk, callTool } = surfaces(); + await kv.set(KV.memories, "mem_a", makeMemory("mem_a")); + await sdk._fns.get("mem::facet-tag")!({ targetId: "mem_a", targetType: "memory", dimension: "kind", value: "test" }); + await callTool("memory_forget", { memoryId: "mem_a" }); + expect((await sdk._fns.get("mem::facet-get")!({ targetId: "mem_a" })).dimensions).toEqual([]); + }); + it("removes one memory by id, from search as well as the store", async () => { const { kv, callTool } = surfaces(); const mem = makeMemory("mem_a"); diff --git a/test/governance.test.ts b/test/governance.test.ts index 9522b6ebc9..48a06ab5b2 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -4,6 +4,7 @@ vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, })); +import { registerFacetsFunction } from "../src/functions/facets.js"; import { registerGovernanceFunction } from "../src/functions/governance.js"; import { getSearchIndex, @@ -27,6 +28,7 @@ function mockKV() { delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); }, + listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), list: async (scope: string): Promise => { const entries = store.get(scope); return entries ? (Array.from(entries.values()) as T[]) : []; @@ -96,12 +98,27 @@ describe("Governance Functions", () => { sdk = mockSdk(); kv = mockKV(); registerGovernanceFunction(sdk as never, kv as never); + registerFacetsFunction(sdk as never, kv as never); await kv.set("mem:memories", "mem_1", makeMemory("mem_1", "pattern")); await kv.set("mem:memories", "mem_2", makeMemory("mem_2", "bug")); await kv.set("mem:memories", "mem_3", makeMemory("mem_3", "pattern")); }); + it("governance-delete removes the deleted memory's Facets", async () => { + await sdk.trigger("mem::facet-tag", { targetId: "mem_1", targetType: "memory", dimension: "kind", value: "test" }); + await sdk.trigger("mem::governance-delete", { memoryIds: ["mem_1"], reason: "outdated" }); + const result = await sdk.trigger("mem::facet-get", { targetId: "mem_1" }); + expect(result.dimensions).toEqual([]); + }); + + it("governance-bulk removes Facets for every deleted memory", async () => { + for (const targetId of ["mem_1", "mem_3"]) await sdk.trigger("mem::facet-tag", { targetId, targetType: "memory", dimension: "kind", value: "test" }); + await sdk.trigger("mem::governance-bulk", { type: ["pattern"] }); + const result = await sdk.trigger("mem::facet-query", { matchAny: ["kind:test"] }); + expect(result.results).toEqual([]); + }); + it("governance-delete removes specified memories", async () => { const result = (await sdk.trigger("mem::governance-delete", { memoryIds: ["mem_1"], diff --git a/test/lessons.test.ts b/test/lessons.test.ts index 457e473d9f..627012fc9b 100644 --- a/test/lessons.test.ts +++ b/test/lessons.test.ts @@ -4,6 +4,7 @@ vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, })); +import { registerFacetsFunction } from "../src/functions/facets.js"; import { registerLessonsFunctions, resetLessonIndex } from "../src/functions/lessons.js"; import { recordProjectActivity } from "../src/state/project-time.js"; import type { Lesson } from "../src/types.js"; @@ -50,6 +51,7 @@ function mockKV() { delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); }, + listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), list: async (scope: string): Promise => { const entries = store.get(scope); return entries ? (Array.from(entries.values(), (v) => structuredClone(v)) as T[]) : []; @@ -84,11 +86,19 @@ describe("Lessons", () => { kv = mockKV(); resetLessonIndex(); registerLessonsFunctions(sdk as never, kv as never); + registerFacetsFunction(sdk as never, kv as never); for (const project of ["/test", "/app", "/other"]) { await kv.set("mem:sessions", `ses${project}`, { id: `ses${project}`, project }); } }); + it("removes Facets when a Lesson is deleted", async () => { + const saved = await sdk.trigger("mem::lesson-save", { content: "Test lesson for Facet deletion", project: "/app" }); + await sdk.trigger("mem::facet-tag", { targetId: saved.lesson.id, targetType: "memory", dimension: "kind", value: "test" }); + await sdk.trigger("mem::lesson-delete", { lessonId: saved.lesson.id }); + expect((await sdk.trigger("mem::facet-get", { targetId: saved.lesson.id })).dimensions).toEqual([]); + }); + describe("mem::lesson-save near-twin re-save (#378)", () => { const ORIGINAL = "Wrap commit body lines at about ninety columns because commitlint rejects body lines over one hundred characters"; diff --git a/test/observe-session-cap.test.ts b/test/observe-session-cap.test.ts index 66b81107ba..3176db173e 100644 --- a/test/observe-session-cap.test.ts +++ b/test/observe-session-cap.test.ts @@ -35,6 +35,7 @@ function mockKV() { } return row; }, + listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), list: async (scope: string): Promise => { lists.push(scope); return Array.from(store.get(scope)?.values() ?? []) as T[]; @@ -110,6 +111,16 @@ describe("mem::observe at MAX_OBS_PER_SESSION (PR#1174)", () => { ); }); + it("removes Facets of observations evicted by the session cap", async () => { + const kv = mockKV(); + const sdk = mockSdk(); + await kv.set(KV.observations(SESSION), "drop", stored("drop", 2, "2026-01-01T00:00:00Z")); + await kv.set(KV.facets, "facet", { id: "facet", targetId: "drop", targetType: "observation", dimension: "kind", value: "test" }); + registerObserveFunction(sdk as never, kv as never, undefined, 1); + await sdk.trigger({ function_id: "mem::observe", payload: { sessionId: SESSION, hookType: "post_tool_use", timestamp: "2026-05-01T00:00:00Z", data: { tool_name: "Read", tool_input: { file_path: "new.ts" } } } }); + expect(await kv.get(KV.facets, "facet")).toBeNull(); + }); + it("deletes the evicted observation's obs-nodes row", async () => { const kv = mockKV(); await kv.set(KV.graphObsNodes, "drop", ["n1"]); From b12cf7c0698967a46a0947ebf093bfd90a232c48 Mon Sep 17 00:00:00 2001 From: neal <130699270+possiblyneal@users.noreply.github.com> Date: Sat, 21 Nov 2026 15:54:43 -0500 Subject: [PATCH 2/3] fix: cache facet targets across deletions Generated-By: gpt-6.1-terra --- CLAUDE.md | 9 ++- src/functions/export-import.ts | 25 ++++---- src/functions/facets.ts | 95 ++++++++++++++++++++++++------ src/functions/snapshot.ts | 5 +- test/auto-forget.test.ts | 4 ++ test/facets.test.ts | 72 +++++++++++++++++++++- test/forget-by-id-surfaces.test.ts | 4 ++ test/governance.test.ts | 4 ++ test/lessons.test.ts | 4 ++ test/observe-session-cap.test.ts | 4 ++ 10 files changed, 194 insertions(+), 32 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7b498027c6..e0edb7202c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -260,9 +260,12 @@ session IDs retain their normal normalization. This preflight does not make repl ### Facet cleanup Ordinary hard deletes of Observations, Memories and Lessons use `deleteWithFacets()` (`src/functions/facets.ts`), which serializes deletion with Facet tag and untag mutations and -best-effort removes Facets for the IDs actually deleted. A later tag on a missing ID remains -allowed. Import replacement and snapshot restore keep their own replacement semantics; this is -not an orphan sweep. Memory writers take `MEMORY_WRITE_LOCK` before the Facet lock. +best-effort removes Facets for the IDs actually deleted. It caches a per-`StateKV` target-to-key +lookup, rebuilding in pages when `KV.facets`'s write generation changes; successful cleanup +updates the cache without a rescan. A later tag on a missing ID remains allowed. Import and +snapshot restore hold the same Facet lock around their Facet mutations, while retaining their +replacement semantics; this is not an orphan sweep. Memory writers take `MEMORY_WRITE_LOCK` +before the Facet lock. ### Graph Eviction Every path that hard-deletes Observations or Memories (`mem::evict`, `mem::observe` session-cap diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index b1981f00f6..268ea47000 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -1,3 +1,4 @@ +import { withFacetLock } from "./facets.js"; import type { ISdk } from "../engine/types.js"; import type { Session, @@ -450,10 +451,12 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { await kv.list(KV.signals).catch(() => []), (s) => kv.delete(KV.signals, s.id), ); - await runChunked( - await kv.list(KV.facets).catch(() => []), - (f) => kv.delete(KV.facets, f.id), - ); + await withFacetLock(async () => { + await runChunked( + await kv.list(KV.facets).catch(() => []), + (f) => kv.delete(KV.facets, f.id), + ); + }); await runChunked( await kv.list(KV.lessons).catch(() => []), (l) => kv.delete(KV.lessons, l.id), @@ -637,12 +640,14 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void { }); } if (importData.facets) { - await runChunked(importData.facets, async (facet) => { - if (strategy === "skip") { - const existing = await kv.get(KV.facets, facet.id).catch(() => null); - if (existing) { stats.skipped++; return; } - } - await kv.set(KV.facets, facet.id, facet); + await withFacetLock(async () => { + await runChunked(importData.facets!, async (facet) => { + if (strategy === "skip") { + const existing = await kv.get(KV.facets, facet.id).catch(() => null); + if (existing) { stats.skipped++; return; } + } + await kv.set(KV.facets, facet.id, facet); + }); }); } if (importData.lessons) { diff --git a/src/functions/facets.ts b/src/functions/facets.ts index ecae3e8a64..9d64dba325 100644 --- a/src/functions/facets.ts +++ b/src/functions/facets.ts @@ -8,29 +8,90 @@ import { scrubFields } from "./privacy.js"; const FACET_LOCK = "mem:facet:mutate"; +export function withFacetLock(fn: () => Promise): Promise { + return withKeyedLock(FACET_LOCK, fn); +} + +type FacetIndex = { generation: number; targets: Map> }; +const facetIndexes = new WeakMap(); + +async function facetIndex(kv: StateKV): Promise { + for (let attempt = 0; attempt < 3; attempt++) { + const generation = await kv.writeGeneration(KV.facets); + const cached = facetIndexes.get(kv); + if (cached?.generation === generation) return cached; + const targets = new Map>(); + let after: string | undefined; + for (;;) { + const page = await kv.listPage(KV.facets, after, 256); + for (const row of page) { + let keys = targets.get(row.value.targetId); + if (!keys) targets.set(row.value.targetId, keys = new Set()); + keys.add(row.key); + } + if (page.length < 256) break; + after = page[page.length - 1].key; + } + if (generation === await kv.writeGeneration(KV.facets)) { + const index = { generation, targets }; + facetIndexes.set(kv, index); + return index; + } + } + throw new Error("Facet scope changed during index rebuild"); +} + +async function cleanupFacets(kv: StateKV, deleted: string[]): Promise { + for (let attempt = 0; attempt < 3; attempt++) { + const index = await facetIndex(kv); + let stale = false; + for (const target of new Set(deleted)) { + const keys = index.targets.get(target); + if (!keys) continue; + for (const key of keys) { + const facet = await kv.get(KV.facets, key); + if (await kv.writeGeneration(KV.facets) !== index.generation) { + stale = true; + break; + } + if (facet?.targetId !== target) { + keys.delete(key); + continue; + } + try { + await kv.delete(KV.facets, key); + keys.delete(key); + const generation = await kv.writeGeneration(KV.facets); + if (generation !== index.generation + 1) { + stale = true; + break; + } + index.generation = generation; + } catch (error) { + facetIndexes.delete(kv); + logger.warn("Facet cleanup failed", { facetId: key, error: String(error) }); + } + } + if (stale) break; + if (keys.size === 0) index.targets.delete(target); + } + if (!stale) return; + facetIndexes.delete(kv); + } + throw new Error("Facet scope changed during cleanup"); +} + export async function deleteWithFacets(kv: StateKV, remove: (deleted: string[]) => Promise): Promise { - return withKeyedLock(FACET_LOCK, async () => { + return withFacetLock(async () => { const deleted: string[] = []; try { return await remove(deleted); } finally { if (deleted.length) { try { - const targets = new Set(deleted); - let after: string | undefined; - for (;;) { - const page = await kv.listPage(KV.facets, after, 256); - for (const row of page) { - if (targets.has(row.value.targetId)) { - await kv.delete(KV.facets, row.key).catch((error) => { - logger.warn("Facet cleanup failed", { facetId: row.key, error: String(error) }); - }); - } - } - if (page.length < 256) break; - after = page[page.length - 1].key; - } + await cleanupFacets(kv, deleted); } catch (error) { + facetIndexes.delete(kv); logger.warn("Facet cleanup failed", { error: String(error) }); } } @@ -78,7 +139,7 @@ export function registerFacetsFunction(sdk: ISdk, kv: StateKV): void { const dimension = data.dimension.trim(); const value = data.value.trim(); - return withKeyedLock(FACET_LOCK, async () => { + return withFacetLock(async () => { const existing = await kv.list(KV.facets); const duplicate = existing.find( (f) => @@ -118,7 +179,7 @@ export function registerFacetsFunction(sdk: ISdk, kv: StateKV): void { return { success: false, error: "dimension is required" }; } - return withKeyedLock(FACET_LOCK, async () => { + return withFacetLock(async () => { const all = await kv.list(KV.facets); const matches = all.filter((f) => { if (f.targetId !== data.targetId || f.dimension !== data.dimension) { diff --git a/src/functions/snapshot.ts b/src/functions/snapshot.ts index 63487eff89..fd80835a8a 100644 --- a/src/functions/snapshot.ts +++ b/src/functions/snapshot.ts @@ -1,3 +1,4 @@ +import { withFacetLock } from "./facets.js"; import type { ISdk } from "../engine/types.js"; import { execFile } from "node:child_process"; import { promisify } from "node:util"; @@ -346,7 +347,9 @@ export function registerSnapshotFunction( } else if (store.graph && graphWritesDisabled()) { skipped.push(store.field); } else { - counts[store.field] = await replaceStore(kv, store, rows); + counts[store.field] = store.scope === KV.facets + ? await withFacetLock(() => replaceStore(kv, store, rows)) + : await replaceStore(kv, store, rows); } } diff --git a/test/auto-forget.test.ts b/test/auto-forget.test.ts index 7deaf81545..1abf3b2885 100644 --- a/test/auto-forget.test.ts +++ b/test/auto-forget.test.ts @@ -13,17 +13,21 @@ import type { Memory, CompressedObservation, Session } from "../src/types.js"; function mockKV() { const store = new Map>(); + let facetGeneration = 0; return { + writeGeneration: async () => facetGeneration, get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; }, set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); + if (scope === "mem:facets") facetGeneration++; return data; }, delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); + if (scope === "mem:facets") facetGeneration++; }, update: async ( scope: string, diff --git a/test/facets.test.ts b/test/facets.test.ts index 448699af3a..84feb662a9 100644 --- a/test/facets.test.ts +++ b/test/facets.test.ts @@ -4,22 +4,26 @@ vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, })); -import { deleteWithFacets, registerFacetsFunction } from "../src/functions/facets.js"; +import { deleteWithFacets, registerFacetsFunction, withFacetLock } from "../src/functions/facets.js"; import type { Facet } from "../src/types.js"; function mockKV() { const store = new Map>(); + let generation = 0; return { + writeGeneration: async () => generation, get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; }, set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); + if (scope === "mem:facets") generation++; return data; }, delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); + if (scope === "mem:facets") generation++; }, listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), @@ -122,6 +126,9 @@ describe("Facets Functions", () => { await deleteWithFacets(kv as never, async (removed) => { removed.push("one", "two"); }); const result = await sdk.trigger("mem::facet-query", { matchAny: ["kind:test"] }); expect(result.results).toHaveLength(1); + kv.delete = originalDelete; + await deleteWithFacets(kv as never, async (removed) => { removed.push("one", "two"); }); + expect((await sdk.trigger("mem::facet-query", { matchAny: ["kind:test"] })).results).toEqual([]); }); it("cleans a batch across Facet pages without skipping survivors", async () => { @@ -135,6 +142,69 @@ describe("Facets Functions", () => { expect(remaining.every((facet) => facet.targetId === "keep")).toBe(true); }); + it("reuses a target lookup for repeated unmatched and matched deletes", async () => { + for (const targetId of ["one", "two"]) await sdk.trigger("mem::facet-tag", { targetId, targetType: "memory", dimension: "kind", value: "test" }); + const listPage = vi.spyOn(kv, "listPage"); + for (const id of ["missing", "one", "two", "another-missing"]) { + await deleteWithFacets(kv as never, async (removed) => { removed.push(id); }); + } + expect(listPage).toHaveBeenCalledTimes(1); + expect((await kv.list("mem:facets"))).toEqual([]); + }); + + it("rebuilds when an external write invalidates the lookup", async () => { + await deleteWithFacets(kv as never, async (removed) => { removed.push("missing"); }); + await kv.set("mem:facets", "new", { id: "new", targetId: "gone" }); + await deleteWithFacets(kv as never, async (removed) => { removed.push("gone"); }); + expect(await kv.get("mem:facets", "new")).toBeNull(); + }); + + it("rebuilds a lookup changed during pagination", async () => { + await kv.set("mem:facets", "a", { id: "a", targetId: "keep" }); + const page = kv.listPage; + let changed = false; + kv.listPage = async (...args) => { + const result = await page(...args); + if (!changed) { changed = true; await kv.set("mem:facets", "b", { id: "b", targetId: "gone" }); } + return result; + }; + await deleteWithFacets(kv as never, async (removed) => { removed.push("gone"); }); + expect(await kv.get("mem:facets", "b")).toBeNull(); + }); + + it("does not delete a replacement Facet for a different target", async () => { + await kv.set("mem:facets", "a", { id: "a", targetId: "gone" }); + await deleteWithFacets(kv as never, async (removed) => { removed.push("missing"); }); + const get = kv.get; + let replaced = false; + kv.get = async (...args) => { + const result = await get(...args); + if (!replaced && args[0] === "mem:facets") { + replaced = true; + await kv.set("mem:facets", "a", { id: "a", targetId: "keep" }); + } + return result; + }; + await deleteWithFacets(kv as never, async (removed) => { removed.push("gone"); }); + expect(await kv.get("mem:facets", "a")).toMatchObject({ targetId: "keep" }); + }); + + it("orders a replacement for a different target after cleanup", async () => { + await kv.set("mem:facets", "a", { id: "a", targetId: "gone" }); + let release!: () => void; + const wait = new Promise((resolve) => { release = resolve; }); + let entered!: () => void; + const started = new Promise((resolve) => { entered = resolve; }); + const remove = kv.delete; + kv.delete = async (...args) => { entered(); await wait; await remove(...args); }; + const deletion = deleteWithFacets(kv as never, async (removed) => { removed.push("gone"); }); + await started; + const replacement = withFacetLock(async () => { await kv.set("mem:facets", "a", { id: "a", targetId: "keep" }); }); + release(); + await Promise.all([deletion, replacement]); + expect(await kv.get("mem:facets", "a")).toMatchObject({ targetId: "keep" }); + }); + describe("mem::facet-tag", () => { it("tags a target with a facet", async () => { const result = (await sdk.trigger("mem::facet-tag", { diff --git a/test/forget-by-id-surfaces.test.ts b/test/forget-by-id-surfaces.test.ts index a92b75b5d1..6d395bbe9f 100644 --- a/test/forget-by-id-surfaces.test.ts +++ b/test/forget-by-id-surfaces.test.ts @@ -28,16 +28,20 @@ const SECRET = "forget-test-secret"; function mockKV() { const store = new Map>(); + let facetGeneration = 0; return { + writeGeneration: async () => facetGeneration, get: async (scope: string, key: string): Promise => (store.get(scope)?.get(key) as T) ?? null, set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); + if (scope === "mem:facets") facetGeneration++; return data; }, delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); + if (scope === "mem:facets") facetGeneration++; }, listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), update: async () => {}, diff --git a/test/governance.test.ts b/test/governance.test.ts index 48a06ab5b2..e4f5408220 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -14,8 +14,10 @@ import type { Memory, AuditEntry } from "../src/types.js"; function mockKV() { const store = new Map>(); + let facetGeneration = 0; const listNewestCalls: Array<{ scope: string; opts: Record }> = []; return { + writeGeneration: async () => facetGeneration, listNewestCalls, get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; @@ -23,10 +25,12 @@ function mockKV() { set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); + if (scope === "mem:facets") facetGeneration++; return data; }, delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); + if (scope === "mem:facets") facetGeneration++; }, listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), list: async (scope: string): Promise => { diff --git a/test/lessons.test.ts b/test/lessons.test.ts index 627012fc9b..7dac6ef0c5 100644 --- a/test/lessons.test.ts +++ b/test/lessons.test.ts @@ -11,13 +11,16 @@ import type { Lesson } from "../src/types.js"; function mockKV() { const store = new Map>(); + let facetGeneration = 0; return { + writeGeneration: async () => facetGeneration, get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; }, set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); + if (scope === "mem:facets") facetGeneration++; return data; }, setManyIfUnchanged: async ( @@ -50,6 +53,7 @@ function mockKV() { }, delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); + if (scope === "mem:facets") facetGeneration++; }, listPage: async (scope: string, after: string | undefined, limit: number) => [...(store.get(scope)?.entries() ?? [])].sort(([a], [b]) => a.localeCompare(b)).filter(([key]) => !after || key > after).slice(0, limit).map(([key, value]) => ({ key, value: value as T })), list: async (scope: string): Promise => { diff --git a/test/observe-session-cap.test.ts b/test/observe-session-cap.test.ts index 3176db173e..51e24f3f48 100644 --- a/test/observe-session-cap.test.ts +++ b/test/observe-session-cap.test.ts @@ -12,16 +12,20 @@ import { KV } from "../src/state/schema.js"; function mockKV() { const lists: string[] = []; const store = new Map>(); + let facetGeneration = 0; return { + writeGeneration: async () => facetGeneration, get: async (scope: string, key: string): Promise => (store.get(scope)?.get(key) as T) ?? null, set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); + if (scope === "mem:facets") facetGeneration++; return data; }, delete: async (scope: string, key: string) => { store.get(scope)?.delete(key); + if (scope === "mem:facets") facetGeneration++; }, update: async ( scope: string, From e22c0730d43356c943f4ee42b79a8478d8433f19 Mon Sep 17 00:00:00 2001 From: neal <130699270+possiblyneal@users.noreply.github.com> Date: Sat, 21 Nov 2026 16:19:19 -0500 Subject: [PATCH 3/3] fix(facets): clean up only committed target deletions Keep tags on missing targets when a delete candidate is stale. Update Lesson Recall before cleanup can yield and retain deleted IDs across purge chunks. Include empty stored keys on the first SQLite page. Refs: #475 Generated-By: gpt-6.2-sol --- CLAUDE.md | 3 ++- src/engine/inproc/state.ts | 8 +++--- src/functions/auto-forget.ts | 3 ++- src/functions/evict.ts | 6 +++-- src/functions/governance.ts | 3 ++- src/functions/lessons.ts | 39 ++++++++++++++------------- src/functions/observe.ts | 3 ++- src/functions/remember.ts | 3 ++- src/functions/retention.ts | 7 ++--- test/governance.test.ts | 17 ++++++++++++ test/inproc-state.test.ts | 14 ++++++++++ test/lessons.test.ts | 52 ++++++++++++++++++++++++++++++++++++ test/retention.test.ts | 27 +++++++++++++++++++ 13 files changed, 154 insertions(+), 31 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d514e57550..b0d4f5b36d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -275,7 +275,8 @@ validate relation entries before replacing any scope, preserve present endpoint (including explicit nulls and non-strings accepted by mesh), retain string relation types, map non-string types to `related`, and omit nonnumeric or nonfinite confidence from backup data without changing the source row. `StateKV.listPage` returns complete SQLite keys, including embedded NULs, -so those keys remain valid paging cursors and can be restored exactly. +so those keys remain valid paging cursors and can be restored exactly. Its first page includes the +empty key; a supplied cursor, including `""`, is exclusive. ### Graph Eviction Every path that hard-deletes Observations or Memories (`mem::evict`, `mem::observe` session-cap diff --git a/src/engine/inproc/state.ts b/src/engine/inproc/state.ts index 3ef2666a8b..4087e4a30b 100644 --- a/src/engine/inproc/state.ts +++ b/src/engine/inproc/state.ts @@ -305,9 +305,11 @@ export class SqliteState { } listPage(scope: string, after: string | undefined, limit: number): Array<{ key: string; value: unknown }> { - const rows = this.db - .prepare("SELECT CAST(key AS BLOB) AS key, value FROM kv WHERE scope = ? AND key > ? ORDER BY kv.key LIMIT ?") - .all(scope, after ?? "", limit) as Array<{ key: Uint8Array; value: string }>; + const rows = (after === undefined + ? this.db.prepare("SELECT CAST(key AS BLOB) AS key, value FROM kv WHERE scope = ? ORDER BY kv.key LIMIT ?") + .all(scope, limit) + : this.db.prepare("SELECT CAST(key AS BLOB) AS key, value FROM kv WHERE scope = ? AND key > ? ORDER BY kv.key LIMIT ?") + .all(scope, after, limit)) as Array<{ key: Uint8Array; value: string }>; return rows.map((r) => ({ key: Buffer.from(r.key).toString("utf8"), value: JSON.parse(r.value) })); } diff --git a/src/functions/auto-forget.ts b/src/functions/auto-forget.ts index 45966745a6..7418f4a90c 100644 --- a/src/functions/auto-forget.ts +++ b/src/functions/auto-forget.ts @@ -186,8 +186,9 @@ export function registerAutoForgetFunction(sdk: ISdk, kv: StateKV): void { let deletedOk = false; try { await deleteWithFacets(kv, async (removed) => { + const existed = await kv.get(KV.observations(sessions[i].id), obs.id); await deleteIndexed(kv, KV.observations(sessions[i].id), obs.id); - removed.push(obs.id); + if (existed) removed.push(obs.id); }); deletedOk = true; } catch { diff --git a/src/functions/evict.ts b/src/functions/evict.ts index 7ae2ca869e..69cf5b9bea 100644 --- a/src/functions/evict.ts +++ b/src/functions/evict.ts @@ -277,8 +277,9 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { } else { try { await deleteWithFacets(kv, async (removed) => { + const existed = await kv.get(KV.observations(session.id), o.id); await deleteIndexed(kv, KV.observations(session.id), o.id); - removed.push(o.id); + if (existed) removed.push(o.id); }); stats.lowImportanceObs++; lowImportanceIds.add(o.id); @@ -326,8 +327,9 @@ export function registerEvictFunction(sdk: ISdk, kv: StateKV): void { for (const o of toEvict) { try { await deleteWithFacets(kv, async (removed) => { + const existed = await kv.get(KV.observations(o.sessionId), o.id); await deleteIndexed(kv, KV.observations(o.sessionId), o.id); - removed.push(o.id); + if (existed) removed.push(o.id); }); stats.capEvictions++; countRemoval(o.sessionId); diff --git a/src/functions/governance.ts b/src/functions/governance.ts index 220b0c63d0..8f54eddca6 100644 --- a/src/functions/governance.ts +++ b/src/functions/governance.ts @@ -136,8 +136,9 @@ export function registerGovernanceFunction(sdk: ISdk, kv: StateKV): void { const results = await withKeyedLock(MEMORY_WRITE_LOCK, () => deleteWithFacets(kv, async (deleted) => Promise.allSettled(batch.map(async (mem) => { + const existed = await kv.get(KV.memories, mem.id); await deleteIndexed(kv, KV.memories, mem.id); - deleted.push(mem.id); + if (existed) deleted.push(mem.id); })), ), ); diff --git a/src/functions/lessons.ts b/src/functions/lessons.ts index 729979b644..71ac5a91e7 100644 --- a/src/functions/lessons.ts +++ b/src/functions/lessons.ts @@ -1,6 +1,6 @@ import { deleteWithFacets } from "./facets.js"; import type { ISdk } from "../engine/types.js"; -import type { StateKV } from "../state/kv.js"; +import { SET_MANY_CHUNK, type StateKV } from "../state/kv.js"; import { KV, fingerprintId, jaccardOverlap, jaccardText } from "../state/schema.js"; import { capBehindNewer, RESTATEMENT_OVERLAP } from "./recency-cap.js"; import type { Lesson, Session } from "../types.js"; @@ -344,19 +344,20 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { return { success: false, error: "lessonId is required" }; } - const lesson = await kv.get(KV.lessons, data.lessonId); + const lesson = await deleteWithFacets(kv, async (removed) => { + const current = await kv.get(KV.lessons, data.lessonId); + if (!current) return null; + await kv.delete(KV.lessons, current.id); + removed.push(current.id); + lessonRecords.delete(current.id); + if (lessonIndex) lessonIndex.remove(current.id); + noteLessonMutation(); + return current; + }); if (!lesson) { return { success: false, error: "lesson not found" }; } - await deleteWithFacets(kv, async (removed) => { - await kv.delete(KV.lessons, lesson.id); - removed.push(lesson.id); - }); - lessonRecords.delete(lesson.id); - if (lessonIndex) lessonIndex.remove(lesson.id); - noteLessonMutation(); - try { await recordAudit(kv, "lesson_delete", "mem::lesson-delete", [ lesson.id, @@ -374,16 +375,18 @@ export function registerLessonsFunctions(sdk: ISdk, kv: StateKV): void { ): Promise { if (expired.length === 0) return []; const deletedIds = await deleteWithFacets(kv, async (removed) => { - const ids = await kv.deleteManyIfUnchanged(KV.lessons, expired); - removed.push(...ids); - return ids; + for (let i = 0; i < expired.length; i += SET_MANY_CHUNK) { + const ids = await kv.deleteManyIfUnchanged(KV.lessons, expired.slice(i, i + SET_MANY_CHUNK)); + removed.push(...ids); + for (const id of ids) { + lessonRecords.delete(id); + if (lessonIndex) lessonIndex.remove(id); + } + if (ids.length > 0) noteLessonMutation(); + } + return removed; }); - for (const id of deletedIds) { - lessonRecords.delete(id); - if (lessonIndex) lessonIndex.remove(id); - } if (deletedIds.length > 0) { - noteLessonMutation(); await recordAudit(kv, "lesson_delete", functionId, deletedIds, { action: "delete", actor: "system", diff --git a/src/functions/observe.ts b/src/functions/observe.ts index d118963070..fc10159ed3 100644 --- a/src/functions/observe.ts +++ b/src/functions/observe.ts @@ -112,8 +112,9 @@ async function evictOverCap( await deleteWithFacets(kv, async (removed) => { for (const obs of victims) { try { + const existed = await kv.get(scope, obs.id); await deleteIndexed(kv, scope, obs.id); - removed.push(obs.id); + if (existed) removed.push(obs.id); evictedIds.push(obs.id); } catch (err) { logger.warn("Session cap eviction failed", { diff --git a/src/functions/remember.ts b/src/functions/remember.ts index e227def155..0bcedf5ad2 100644 --- a/src/functions/remember.ts +++ b/src/functions/remember.ts @@ -448,8 +448,9 @@ export function registerRememberFunction(sdk: ISdk, kv: StateKV): void { ); await deleteWithFacets(kv, async (removed) => { for (const obs of observations) { + const existed = await kv.get(KV.observations(data.sessionId!), obs.id); await deleteIndexed(kv, KV.observations(data.sessionId!), obs.id); - removed.push(obs.id); + if (existed) removed.push(obs.id); if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData); if (obs.imageRef && obs.imageRef !== obs.imageData) { await decrementImageRef(kv, sdk, obs.imageRef); diff --git a/src/functions/retention.ts b/src/functions/retention.ts index ca48ecf3fb..967eb31fcd 100644 --- a/src/functions/retention.ts +++ b/src/functions/retention.ts @@ -350,10 +350,11 @@ export function registerRetentionFunctions( const evictScope = scope; const remove = async () => { - const mem = await kv.get(evictScope, candidate.memoryId); - await deleteWithFacets(kv, async (removed) => { + const mem = await deleteWithFacets(kv, async (removed) => { + const current = await kv.get(evictScope, candidate.memoryId); await deleteIndexed(kv, evictScope, candidate.memoryId); - removed.push(candidate.memoryId); + if (current) removed.push(candidate.memoryId); + return current; }); if (mem && mem.imageRef) { await decrementImageRef(kv, sdk, mem.imageRef).catch((error) => { diff --git a/test/governance.test.ts b/test/governance.test.ts index e4f5408220..cec2067794 100644 --- a/test/governance.test.ts +++ b/test/governance.test.ts @@ -123,6 +123,23 @@ describe("Governance Functions", () => { expect(result.results).toEqual([]); }); + it("governance-bulk keeps Facets for a candidate deleted after selection", async () => { + const list = kv.list; + kv.list = async (scope: string): Promise => { + const rows = await list(scope); + if (scope === "mem:memories") { + await kv.delete(scope, "mem_1"); + await sdk.trigger("mem::facet-tag", { targetId: "mem_1", targetType: "memory", dimension: "kind", value: "test" }); + } + return rows; + }; + + await sdk.trigger("mem::governance-bulk", { type: ["pattern"] }); + + const result = await sdk.trigger("mem::facet-get", { targetId: "mem_1" }); + expect(result.dimensions).toHaveLength(1); + }); + it("governance-delete removes specified memories", async () => { const result = (await sdk.trigger("mem::governance-delete", { memoryIds: ["mem_1"], diff --git a/test/inproc-state.test.ts b/test/inproc-state.test.ts index 93329705b6..a4d50cc602 100644 --- a/test/inproc-state.test.ts +++ b/test/inproc-state.test.ts @@ -123,6 +123,20 @@ describe("inproc state store", () => { expect(next).toEqual([{ key: "c", value: "c" }, { key: "d", value: "d" }]); }); + it("includes an empty key on the first page and resumes after it", async () => { + const fns = stateFunctions(store); + for (const key of ["b", "", "a"]) { + await fns["state::set"]({ scope: "facets", key, value: { id: key } }); + } + await fns["state::set"]({ scope: "other", key: "", value: { id: "other" } }); + + expect(await fns["state::list-page"]({ scope: "facets", limit: 1 })).toEqual([{ key: "", value: { id: "" } }]); + expect(await fns["state::list-page"]({ scope: "facets", after: "", limit: 2 })).toEqual([ + { key: "a", value: { id: "a" } }, + { key: "b", value: { id: "b" } }, + ]); + }); + it("pages keys containing NUL without truncating the cursor", async () => { const fns = stateFunctions(store); for (const key of ["a", "a\u0000b", "a\u0000c", "b"]) { diff --git a/test/lessons.test.ts b/test/lessons.test.ts index 7dac6ef0c5..0ff8f4f53d 100644 --- a/test/lessons.test.ts +++ b/test/lessons.test.ts @@ -103,6 +103,40 @@ describe("Lessons", () => { expect((await sdk.trigger("mem::facet-get", { targetId: saved.lesson.id })).dimensions).toEqual([]); }); + it("keeps a Facet tagged between two deletes of the same Lesson", async () => { + const { lesson } = await sdk.trigger("mem::lesson-save", { content: "Lesson for concurrent deletes", project: "/app" }); + const firstDelete = sdk.trigger("mem::lesson-delete", { lessonId: lesson.id }); + await Promise.resolve(); + const tag = sdk.trigger("mem::facet-tag", { targetId: lesson.id, targetType: "memory", dimension: "kind", value: "test" }); + const secondDelete = sdk.trigger("mem::lesson-delete", { lessonId: lesson.id }); + + const [first, , second] = await Promise.all([firstDelete, tag, secondDelete]); + expect(first.success).toBe(true); + expect(second).toEqual({ success: false, error: "lesson not found" }); + expect((await sdk.trigger("mem::facet-get", { targetId: lesson.id })).dimensions).toHaveLength(1); + }); + + it("keeps a Lesson re-saved while deletion cleans up Facets searchable", async () => { + const content = "Unique searchable lesson during cleanup"; + const saved = await sdk.trigger("mem::lesson-save", { content, project: "/app" }); + await sdk.trigger("mem::facet-tag", { targetId: saved.lesson.id, targetType: "memory", dimension: "kind", value: "test" }); + const listPage = kv.listPage; + let resaved = false; + kv.listPage = async (scope: string, after: string | undefined, limit: number) => { + if (scope === "mem:facets" && !resaved) { + resaved = true; + await sdk.trigger("mem::lesson-save", { content, project: "/app" }); + } + return listPage(scope, after, limit); + }; + + await sdk.trigger("mem::lesson-delete", { lessonId: saved.lesson.id }); + + expect(await kv.get("mem:lessons", saved.lesson.id)).not.toBeNull(); + const recalled = await sdk.trigger("mem::lesson-recall", { query: "unique searchable lesson", project: "/app" }); + expect(recalled.lessons.map((lesson: Lesson) => lesson.id)).toContain(saved.lesson.id); + }); + describe("mem::lesson-save near-twin re-save (#378)", () => { const ORIGINAL = "Wrap commit body lines at about ninety columns because commitlint rejects body lines over one hundred characters"; @@ -673,6 +707,24 @@ describe("Lessons", () => { expect(await kv.get("mem:lessons", live.lesson.id)).not.toBeNull(); }); + it("cleans Facets of committed tombstone chunks if a later chunk fails", async () => { + const tomb = await tombstone("chunked tombstone"); + await sdk.trigger("mem::facet-tag", { targetId: tomb.id, targetType: "memory", dimension: "kind", value: "test" }); + for (let i = 0; i < 100; i++) { + await kv.set("mem:lessons", `extra-${i}`, { ...tomb, id: `extra-${i}` }); + } + const deleteMany = kv.deleteManyIfUnchanged; + let calls = 0; + kv.deleteManyIfUnchanged = async (scope, entries) => { + if (++calls === 2) throw new Error("later chunk failed"); + return deleteMany(scope, entries); + }; + + await expect(sdk.trigger("mem::lesson-purge-tombstones", {})).rejects.toThrow("later chunk failed"); + expect(await kv.get("mem:lessons", tomb.id)).toBeNull(); + expect((await sdk.trigger("mem::facet-get", { targetId: tomb.id })).dimensions).toEqual([]); + }); + it("strengthening a tombstone reports it not found and leaves it unreinforced", async () => { const tomb = await tombstone("strengthened tombstone"); diff --git a/test/retention.test.ts b/test/retention.test.ts index 9e5ebaa783..591b982da9 100644 --- a/test/retention.test.ts +++ b/test/retention.test.ts @@ -4,6 +4,8 @@ import { } from "../src/functions/search.js"; import { memoryToObservation } from "../src/state/memory-utils.js"; import type { Memory, SemanticMemory } from "../src/types.js"; +import { KV } from "../src/state/schema.js"; +import { pagedReads } from "./helpers/mocks.js"; vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() }, @@ -25,17 +27,23 @@ function mockKV( store.set("mem:retention", new Map()); + const { listPage } = pagedReads(store); + let facetGeneration = 0; return { + listPage, + writeGeneration: async () => facetGeneration, get: async (scope: string, key: string): Promise => { return (store.get(scope)?.get(key) as T) ?? null; }, set: async (scope: string, key: string, data: T): Promise => { if (!store.has(scope)) store.set(scope, new Map()); store.get(scope)!.set(key, data); + if (scope === KV.facets) facetGeneration++; return data; }, delete: async (scope: string, key: string): Promise => { store.get(scope)?.delete(key); + if (scope === KV.facets) facetGeneration++; }, list: async (scope: string): Promise => { const entries = store.get(scope); @@ -534,6 +542,25 @@ describe("RetentionScoring", () => { }); }); + it("keeps Facets for missing targets while clearing stale retention scores", async () => { + const { registerRetentionFunctions } = await import("../src/functions/retention.js"); + const present = makeMemory("mem_present", "fact", 500); + const missing = makeMemory("mem_missing", "fact", 500); + const sdk = mockSdk(); + const kv = mockKV([present, missing]); + registerRetentionFunctions(sdk as never, kv as never); + await sdk.trigger({ function_id: "mem::retention-score", payload: {} }); + await kv.delete(KV.memories, missing.id); + await kv.set(KV.facets, "present", { targetId: present.id }); + await kv.set(KV.facets, "missing", { targetId: missing.id }); + + await sdk.trigger({ function_id: "mem::retention-evict", payload: { threshold: 0.9 } }); + + expect(await kv.get(KV.facets, "present")).toBeNull(); + expect(await kv.get(KV.facets, "missing")).toEqual({ targetId: missing.id }); + expect(await kv.get(KV.retentionScores, missing.id)).toBeNull(); + }); + it("mem::retention-evict keeps the image ref when the delete fails (#437)", async () => { const { registerRetentionFunctions } = await import( "../src/functions/retention.js"