Skip to content

Commit 2f93eaf

Browse files
authored
feat(plugin): tombstone forgotten rules and record their scope (#37)
* feat(plugin): tombstone forgotten rules and record their scope Phase 0 of the central rules design (Alterspective-Intelligence PR anomalyco#1081): - forgetting a rule now marks it deleted (deletedAt/deletedBy) instead of removing the row, so a later merge or sync cannot resurrect it. - each record carries its scope (global | project). - re-recording a forgotten rule revives it in place, without duplicating. - listing and injection ignore tombstoned rows. * fix(plugin): keep tombstones past the cap and forget both stores atomically - Trimming now keeps live rules and tombstones under separate caps, so the record limit can no longer evict a tombstone (which would let a merge resurrect the rule). - forgetLearning runs both stores' tombstone writes in one mutation, so a record cannot interleave between them. * fix(plugin): report a forget only when every store succeeded - forgetLearning now returns 0 if any store could not be read or written, so it never claims a rule is gone while a copy stays live; an absent store is not a failure. - recordLearning returns the persisted (scoped) record. * fix(plugin): treat only a missing rule store as absent applyTombstones now reports ok only for ENOENT; any other read error, or valid JSON that is not an array, is unknown state and makes forgetLearning report nothing. Added a regression test.
1 parent 10337a5 commit 2f93eaf

2 files changed

Lines changed: 222 additions & 37 deletions

File tree

‎packages/opencode/src/plugin/observer.ts‎

Lines changed: 82 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,7 @@ class SessionObserverManager {
292292
let stored = entry
293293
await this.mutate(async () => {
294294
for (const file of files) {
295+
const scope: "global" | "project" = file === paths.project ? "project" : "global"
295296
try {
296297
await fs.mkdir(path.dirname(file), { recursive: true })
297298
let existing: SessionLearning[] = []
@@ -302,13 +303,18 @@ class SessionObserverManager {
302303
const found = existing.find((e) => e.lesson.trim().toLowerCase() === normalizedText)
303304
if (found) {
304305
// Re-recording refreshes recency AND moves the rule to the front, so it
305-
// re-enters the injection window; it never duplicates.
306+
// re-enters the injection window; it never duplicates. It also clears any
307+
// tombstone, which is how a forgotten rule is restored.
306308
found.timestamp = new Date().toISOString()
309+
found.scope = scope
310+
found.deletedAt = undefined
311+
found.deletedBy = undefined
307312
stored = found
308-
await writeJsonAtomic(file, [found, ...existing.filter((e) => e !== found)].slice(0, 100))
313+
await writeJsonAtomic(file, trimRules([found, ...existing.filter((e) => e !== found)]))
309314
continue
310315
}
311-
await writeJsonAtomic(file, [entry, ...existing].slice(0, 100))
316+
await writeJsonAtomic(file, trimRules([{ ...entry, scope }, ...existing]))
317+
stored = { ...entry, scope }
312318
} catch {}
313319
}
314320
})
@@ -337,7 +343,7 @@ class SessionObserverManager {
337343
// global note (AIMETH-008 - shared repo facts win). One entry per rule text.
338344
const seen = new Set<string>()
339345
const merged: SessionLearning[] = []
340-
for (const rule of [...(await read(paths.project)), ...(await read(paths.global))]) {
346+
for (const rule of [...(await read(paths.project)), ...(await read(paths.global))].filter(isLive)) {
341347
const key = learningKey(rule)
342348
if (seen.has(key)) continue
343349
seen.add(key)
@@ -379,8 +385,8 @@ class SessionObserverManager {
379385
}
380386
}
381387
const paths = learningStorePaths(workspaceDir)
382-
const global = await read(paths.global)
383-
const project = await read(paths.project)
388+
const global = (await read(paths.global)).filter(isLive)
389+
const project = (await read(paths.project)).filter(isLive)
384390
const globalKeys = new Set(global.map(learningKey))
385391
const merged = [
386392
...global.map((l) => ({ ...l, origin: "global" as const })),
@@ -393,49 +399,66 @@ class SessionObserverManager {
393399
}
394400

395401
/**
396-
* Remove rules whose text matches (case-insensitive substring) from memory and
397-
* from both persisted stores. Returns the number of distinct rules removed; a
398-
* rule present in both stores is counted once.
402+
* Forget rules whose text matches (case-insensitive substring): mark them deleted
403+
* (tombstone) in both persisted stores. Returns the number of distinct rules newly
404+
* forgotten; a rule present in both stores is counted once.
399405
*/
400406
public async forgetLearning(lessonText: string, workspaceDir?: string): Promise<number> {
401407
const needle = lessonText.trim().toLowerCase()
402408
if (!needle) return 0
403409
const matches = (l: SessionLearning) => String(l.lesson ?? "").toLowerCase().includes(needle)
404410
const paths = learningStorePaths(workspaceDir)
405411
const files = [paths.global, paths.project].filter((file): file is string => Boolean(file))
406-
const removed = new Set<string>()
407-
for (const file of files) {
408-
for (const key of await this.dropRules(file, matches)) removed.add(key)
409-
}
410-
return removed.size
412+
// One mutation for both stores, so a record cannot interleave between them.
413+
return this.mutate(async () => {
414+
const results: Array<{ keys: Set<string>; ok: boolean }> = []
415+
for (const file of files) results.push(await this.applyTombstones(file, matches))
416+
// If a store could not be read or written, we cannot claim its copy is gone, so
417+
// report nothing rather than a count that may be wrong.
418+
if (results.some((r) => !r.ok)) return 0
419+
const forgotten = new Set<string>()
420+
for (const result of results) for (const key of result.keys) forgotten.add(key)
421+
return forgotten.size
422+
})
411423
}
412424

413425
/**
414-
* Remove matching rules from one store atomically and count them. A removal is
415-
* only reported when the write landed; a failed write returns nothing and the
416-
* file is left untouched.
426+
* Mark matching live rules as deleted in one store. The rows are kept as
427+
* tombstones so a later merge or sync cannot resurrect them. Non-queuing: the
428+
* caller must already hold the mutation lock. Returns the keys acted on and
429+
* whether the read and write both succeeded; an absent store is not a failure.
417430
*/
418-
private dropRules(file: string, matches: (l: SessionLearning) => boolean): Promise<Set<string>> {
419-
return this.mutate(async () => {
420-
const found = new Set<string>()
421-
try {
422-
const parsed = JSON.parse(await fs.readFile(file, "utf8"))
423-
if (!Array.isArray(parsed)) return found
424-
const kept: SessionLearning[] = []
425-
for (const row of parsed as SessionLearning[]) {
426-
if (matches(row)) {
427-
found.add(String(row.lesson ?? "").trim().toLowerCase())
428-
continue
429-
}
430-
kept.push(row)
431-
}
432-
if (found.size === 0) return found
433-
await writeJsonAtomic(file, kept.slice(0, 100))
434-
} catch {
435-
return new Set<string>()
431+
private async applyTombstones(
432+
file: string,
433+
matches: (l: SessionLearning) => boolean,
434+
): Promise<{ keys: Set<string>; ok: boolean }> {
435+
const keys = new Set<string>()
436+
let raw: string
437+
try {
438+
raw = await fs.readFile(file, "utf8")
439+
} catch (error) {
440+
// Only a missing store is a successful absence; any other read error means we
441+
// cannot know what the store holds.
442+
const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined
443+
return { keys, ok: code === "ENOENT" }
444+
}
445+
try {
446+
const parsed = JSON.parse(raw)
447+
if (!Array.isArray(parsed)) return { keys, ok: false }
448+
const rows = parsed as SessionLearning[]
449+
let changed = false
450+
for (const row of rows) {
451+
if (!isLive(row) || !matches(row)) continue
452+
row.deletedAt = new Date().toISOString()
453+
row.deletedBy = process.env.USERNAME || process.env.USER || "local"
454+
keys.add(learningKey(row))
455+
changed = true
436456
}
437-
return found
438-
})
457+
if (changed) await writeJsonAtomic(file, trimRules(rows))
458+
return { keys, ok: true }
459+
} catch {
460+
return { keys, ok: false }
461+
}
439462
}
440463

441464
public getLatestRetrospectives(): SessionRetrospective[] {
@@ -461,6 +484,23 @@ export function learningStorePaths(workspaceDir?: string): { global?: string; pr
461484

462485
const learningKey = (l: SessionLearning) => String(l.lesson ?? "").trim().toLowerCase()
463486

487+
/** A rule is live unless it carries a tombstone. */
488+
const isLive = (l: SessionLearning) => !l.deletedAt
489+
490+
const MAX_LIVE_RULES = 100
491+
const MAX_TOMBSTONES = 100
492+
493+
/**
494+
* Bound file size without evicting tombstones: a dropped tombstone would let a
495+
* later merge resurrect the rule it records as deleted.
496+
*/
497+
function trimRules(rows: SessionLearning[]): SessionLearning[] {
498+
return [
499+
...rows.filter(isLive).slice(0, MAX_LIVE_RULES),
500+
...rows.filter((r) => !isLive(r)).slice(0, MAX_TOMBSTONES),
501+
]
502+
}
503+
464504
/** Write JSON via a temp file + rename so a reader never sees a half-written file. */
465505
async function writeJsonAtomic(file: string, rows: SessionLearning[]): Promise<void> {
466506
const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 7)}.tmp`
@@ -474,6 +514,11 @@ export interface SessionLearning {
474514
lesson: string
475515
context?: string
476516
source: "user_feedback" | "buddy_review" | "auto_correction" | "session_retro"
517+
/** Which store this row belongs to. */
518+
scope?: "global" | "project"
519+
/** Tombstone: set when the rule is forgotten, so a later merge cannot resurrect it. */
520+
deletedAt?: string
521+
deletedBy?: string
477522
}
478523

479524
export const sessionObserver = new SessionObserverManager()

‎packages/opencode/test/plugin/observer.test.ts‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,4 +168,144 @@ describe("rule visibility", () => {
168168
restoreUserProfile(prev)
169169
}
170170
})
171+
172+
test("forgetting keeps the row as a tombstone instead of deleting it", async () => {
173+
await using home = await tmpdir()
174+
const prev = process.env.USERPROFILE
175+
process.env.USERPROFILE = home.path
176+
try {
177+
const file = path.join(home.path, ".local", "share", "opencode", "learnings.json")
178+
await sessionObserver.recordLearning({ lesson: "tombstone me", source: "user_feedback" })
179+
expect(await sessionObserver.forgetLearning("tombstone me")).toBe(1)
180+
181+
expect((await sessionObserver.listLearnings()).find((r) => r.lesson === "tombstone me")).toBeUndefined()
182+
183+
const rows = JSON.parse(await fs.readFile(file, "utf8"))
184+
const row = rows.find((r: { lesson: string }) => r.lesson === "tombstone me")
185+
expect(row).toBeDefined()
186+
expect(typeof row.deletedAt).toBe("string")
187+
expect(row.scope).toBe("global")
188+
} finally {
189+
restoreUserProfile(prev)
190+
}
191+
})
192+
193+
test("re-recording a forgotten rule revives it without duplicating", async () => {
194+
await using home = await tmpdir()
195+
const prev = process.env.USERPROFILE
196+
process.env.USERPROFILE = home.path
197+
try {
198+
const file = path.join(home.path, ".local", "share", "opencode", "learnings.json")
199+
await sessionObserver.recordLearning({ lesson: "revive me", source: "user_feedback" })
200+
expect(await sessionObserver.forgetLearning("revive me")).toBe(1)
201+
expect((await sessionObserver.listLearnings()).find((r) => r.lesson === "revive me")).toBeUndefined()
202+
203+
await sessionObserver.recordLearning({ lesson: "revive me", source: "user_feedback" })
204+
205+
expect((await sessionObserver.listLearnings()).find((r) => r.lesson === "revive me")!.injected).toBe(true)
206+
const rows = JSON.parse(await fs.readFile(file, "utf8"))
207+
const rowsForLesson = rows.filter((r: { lesson: string }) => r.lesson === "revive me")
208+
expect(rowsForLesson.length).toBe(1)
209+
expect(rowsForLesson[0].deletedAt).toBeUndefined()
210+
} finally {
211+
restoreUserProfile(prev)
212+
}
213+
})
214+
215+
test("records the scope of each rule", async () => {
216+
await using home = await tmpdir()
217+
await using ws = await tmpdir()
218+
const prev = process.env.USERPROFILE
219+
process.env.USERPROFILE = home.path
220+
try {
221+
await sessionObserver.recordLearning({ lesson: "global rule", source: "user_feedback" })
222+
await sessionObserver.recordLearning({ lesson: "project rule", source: "user_feedback" }, ws.path)
223+
224+
const global = JSON.parse(
225+
await fs.readFile(path.join(home.path, ".local", "share", "opencode", "learnings.json"), "utf8"),
226+
)
227+
const project = JSON.parse(
228+
await fs.readFile(path.join(ws.path, ".system_generated", "logs", "learnings.json"), "utf8"),
229+
)
230+
expect(global.find((r: { lesson: string }) => r.lesson === "global rule").scope).toBe("global")
231+
expect(project.find((r: { lesson: string }) => r.lesson === "project rule").scope).toBe("project")
232+
} finally {
233+
restoreUserProfile(prev)
234+
}
235+
})
236+
237+
test("a tombstone survives the record cap", async () => {
238+
await using home = await tmpdir()
239+
const prev = process.env.USERPROFILE
240+
process.env.USERPROFILE = home.path
241+
try {
242+
const file = path.join(home.path, ".local", "share", "opencode", "learnings.json")
243+
const rows: Array<{
244+
id: string
245+
timestamp: string
246+
lesson: string
247+
source: string
248+
deletedAt?: string
249+
deletedBy?: string
250+
}> = Array.from({ length: 100 }, (_, i) => ({
251+
id: "r" + i,
252+
timestamp: "2026-09-01T00:00:00.000Z",
253+
lesson: "rule " + i,
254+
source: "user_feedback",
255+
}))
256+
rows.push({
257+
id: "dead",
258+
timestamp: "2026-09-01T00:00:00.000Z",
259+
lesson: "tombstoned rule",
260+
source: "user_feedback",
261+
deletedAt: "2026-09-02T00:00:00.000Z",
262+
deletedBy: "test",
263+
})
264+
await fs.mkdir(path.dirname(file), { recursive: true })
265+
await fs.writeFile(file, JSON.stringify(rows), "utf8")
266+
267+
await sessionObserver.recordLearning({ lesson: "one more", source: "user_feedback" })
268+
269+
const after = JSON.parse(await fs.readFile(file, "utf8"))
270+
const tomb = after.find((r: { lesson: string }) => r.lesson === "tombstoned rule")
271+
expect(tomb).toBeDefined()
272+
expect(tomb.deletedAt).toBe("2026-09-02T00:00:00.000Z")
273+
} finally {
274+
restoreUserProfile(prev)
275+
}
276+
})
277+
278+
test("forgetting still counts when the other store does not exist", async () => {
279+
await using home = await tmpdir()
280+
await using ws = await tmpdir()
281+
const prev = process.env.USERPROFILE
282+
process.env.USERPROFILE = home.path
283+
try {
284+
await sessionObserver.recordLearning({ lesson: "only global", source: "user_feedback" }, ws.path)
285+
// Remove the project store so only the global copy remains.
286+
await fs.rm(path.join(ws.path, ".system_generated", "logs", "learnings.json"), { force: true })
287+
288+
expect(await sessionObserver.forgetLearning("only global", ws.path)).toBe(1)
289+
} finally {
290+
restoreUserProfile(prev)
291+
}
292+
})
293+
294+
test("forgetting reports nothing when a store is unreadable data", async () => {
295+
await using home = await tmpdir()
296+
await using ws = await tmpdir()
297+
const prev = process.env.USERPROFILE
298+
process.env.USERPROFILE = home.path
299+
try {
300+
await sessionObserver.recordLearning({ lesson: "fragile", source: "user_feedback" })
301+
// The project store exists but holds valid JSON that is not the expected array.
302+
const wsFile = path.join(ws.path, ".system_generated", "logs", "learnings.json")
303+
await fs.mkdir(path.dirname(wsFile), { recursive: true })
304+
await fs.writeFile(wsFile, JSON.stringify("not a rules array"), "utf8")
305+
306+
expect(await sessionObserver.forgetLearning("fragile", ws.path)).toBe(0)
307+
} finally {
308+
restoreUserProfile(prev)
309+
}
310+
})
171311
})

0 commit comments

Comments
 (0)