fix(forget): delete across every substrate holding the content (#366)

[cdeust]

Closes #366.

PRIVACY.md tells users "The forget tool deletes individual memories." A hard delete issued a single DELETE FROM memories. Two substrates kept the content:

• the raw full text of an oversized auto-capture, in its content-addressed artifact under ~/.claude/methodology/artifacts/ — artifact_store.py had no removal path at all, so the row's gist went and the complete original stayed readable on disk;
• wiki claim events derived from the memory, which survive by design: pg_schema.py:221 declares wiki.claim_events.memory_id ON DELETE SET NULL, so after the row goes the claim persists and can no longer be found by id.

Root cause, not just the symptom

The missing unlink was downstream of a missing contract: the artifact pointer format was duplicated as an f-string in hooks/post_tool_capture and handlers/backfill_helpers, so nothing could parse it back safely and a drift in either writer would have broken any deleter silently. format_artifact_pointer / parse_artifact_pointer now own that format in core, and both writers call it.

Three things that would have made a naive fix wrong

1. Artifacts are content-addressed with dedup — byte-identical captures map to ONE file, so unlinking it for the first of two referrers strips the survivor's content. artifact_gc counts referrers first and fails closed: an unknown count keeps the file.
2. Claims must be deleted BEFORE the row — the FK nulls the link, after which the claim cannot be found by memory_id.
3. The reference count must be taken AFTER the row is gone — otherwise the memory being forgotten counts itself and nothing is ever collected.

Neither ordering is visible from the happy path; each has its own test.

soft=true keeps the artifact (a soft delete is recoverable by design) and reports artifact_deleted: false rather than omitting it, so a caller can tell kept on purpose from we forgot to look.

Completion Ledger

Test names below are enumerated from git diff origin/main...HEAD — not recalled.

Diff paths → asserting test

Path in the diff	Asserting test
hard delete removes the artifact	test_hard_delete_removes_the_artifact_file
the removal is reported in the result (§13 F1)	test_hard_delete_reports_artifact_removal
soft delete retains the artifact	test_soft_delete_keeps_the_artifact
refused (protected) delete touches nothing	test_refused_delete_keeps_the_artifact
shared artifact survives while another referrer lives	test_shared_artifact_survives_while_another_memory_references_it
no-artifact memory reports false, not None	test_memory_without_artifact_reports_false_not_none
derived wiki claims removed + count reported	test_hard_delete_removes_derived_claims_and_reports_the_count
zero-claims case	test_memory_with_no_claims_reports_zero
already-absent artifact emits an actionable signal naming the path	test_already_absent_artifact_logs_the_path_it_expected
pointer format/parse round trip	test_round_trip_recovers_the_path, test_round_trip_inside_a_full_memory_body
path containing spaces not clipped	test_path_containing_spaces_survives
char-count suffix not absorbed into the path	test_char_count_suffix_is_not_absorbed_into_the_path
absent / empty / malformed pointer → None (never a guessed path)	test_absent_pointer_returns_none, test_empty_content_returns_none, test_malformed_pointer_returns_none_rather_than_a_bad_path
two pointers in one body → first wins	test_first_pointer_wins_when_a_body_carries_two

§13.1 checklist

Item	Evidence
A1 happy paths, output quoted	Full suite 7,090 passed, 81 skipped, 123 subtests, 0 failures (229s, post-rebase)
A2 edge cases	shared artifact, absent file, no pointer, malformed pointer, two pointers, zero claims
A3 every failure arm asserted incl. the signal	reference-count failure fails closed; already-absent path asserts the log names the path
A5 partial failure	delete_artifact_if_unreferenced never raises; each non-removal path logs why and returns False
B1–B3 concurrency	N/A — no new concurrency; deletion is a single request path
C2 resource lifecycle	this PR adds the only artifact-reclaim path; the store previously only grew
D1–D3 security	parameterised SQL only; no secrets; deletion narrows exposure
E1 API additive	artifact_deleted / claims_deleted added to the result; no field removed
E3 persisted-data compat	no schema change
F1 signals asserted	above
G3 determinism	tests use the conftest-isolated CORTEX_CLAUDE_DIR + throwaway DB
G4 negative assertions	soft/refused/shared cases assert the artifact is still present
G5 lint	ruff check + ruff format --check clean on all changed files
H1 rules	sizes 110/176/234 lines; core/ imports no os/pathlib/infrastructure
H4 docs	PRIVACY.md scope + both exceptions, docs/mcp-tools.md, CHANGELOG
§12 mutation	0 surviving mutants, 347/347 on artifact_gc.py, gist_extraction.py, forget.py
H7 boy-scout (§14)	the run surfaced 5 pre-existing gaps in extract_gist/_fill_tail — a reversed step made the tail range EMPTY (the end of every dump vanished) and break-instead-of-continue truncated it; all fixed here, not deferred

Verification honesty

The first mutation run reported 3 survivors and I treated it as trustworthy. It was not: the run that matters reported 8, six of them in this PR's own new code, including _delete_derived_claims — where no test proved claims were actually deleted, so half of #366's purpose was unasserted while the suite stayed green. All 8 are now killed.

🤖 Generated with Claude Code