fix(sdk/recall): harden supersede counters, slot key contract, and resolver path

[lIang70]

Summary

Hardens the slot supersede + LLM update resolver feature in sdk/recall after a code review that surfaced counter accounting bugs, a missing escape hatch, and several maintainability issues.

Bugs (correctness)

• B1 — supersedeBySlot only increments supersede_total{channel="slot"} after a successful Upsert, matching the vector / resolver channels. Previously the metric was bumped by len(resp.Items) before the loop's skip-list ran, over-reporting in dashboards.
• B2 — normalizeSubject lowercases unknown tokens so case-only differences ("Alice" vs "alice") collapse onto the same slot_key. The behaviour now mirrors normalizePredicate and is documented in godoc.
• B3 — Add Request.WithTombstoned so callers can surface tombstoned entries (debug resolver, stage Auditable.Rollback). MetaTombstone is now documented as a reserved metadata key.

Design / maintainability

• M1 / N6 — Centralise reserved metadata keys: new sdk/recall/metadata.go (MetaSubject, MetaPredicate, MetaSupersededBy, MetaSupersededAt, MetaTombstone, MetaContentHash, MetaSourceLabel, MetaEntities) plus sdk/retrieval/metadata.go (MetaSlotKey, SlotKeyOf). Pipeline's SlotCollapse and the recall package now share one lookup helper instead of duplicating it.
• M2 — slotEligible(fact) rejects subject/predicate values containing the slot delimiter | so ambiguous slot_keys are never written; such facts gracefully degrade to the vector / resolver channels.
• M3 — New WithoutSlotChannel() option separates the deterministic slot path from the noisy vector soft-merge. WithoutSoftMerge() now affects the vector channel only and the godoc spells the difference out.
• M4 — Resolver invocation opens its own span memory.recall.resolver_batch with n_facts / n_candidates attributes for cost attribution without enabling SearchDebug.
• M5 — WithUpdateResolver godoc explains the ordering relationship with the slot/vector supersede channels and the resulting candidate-count behaviour.

Polish

• N1 — Drop misleading "future-proofs" comment in save.go; replaced with a "single source of truth" rationale that actually matches the code.
• N2 — ResolveAction godoc clarifies that SourceID / TargetID are required for UPDATE / DELETE and informational/optional for ADD / NOOP.
• N4 — Expand PredicateAliases coverage for high-frequency CN/EN surface forms across all v1 predicates (住/住所/老家/故乡/供职/就职/出生/爱人/伴侣, based_in/married_to/born_on/son/daughter, …); table is now documented as curated rather than exhaustive, with WithPredicateAlias overrides retained as the per-namespace extension point.
• N5 — LLMUpdateResolver sends a strict resolverActionsSchema alongside WithJSONMode so providers that enforce JSON-schema (Azure OpenAI strict) accept the call.
• N7 — Drop now-stale references to docs/recall-update-resolution.md (file does not exist in tree); link to in-code symbols instead.

New tests

Test	File	Covers
TestTombstoneFilter_HidesByDefault_OptInReveals	memory_test.go	B3
TestSlotChannel_KeptWhenWithoutSoftMerge	merger_test.go	M3
TestSlotChannel_DisabledByWithoutSlotChannel	merger_test.go	M3 (new option)
TestSlotSupersede_MultipleStaleEntriesInOneSlot	merger_test.go	N3 (multiple stale entries)
TestSlotEligibility_RejectsDelimiterInSubject	merger_test.go	M2
TestSlotCollapse_EndToEnd_OnLegacyData	merger_test.go	N3 (end-to-end)
TestNormalizeSubject_LowercasesUnknownTokens	aliases_test.go	B2

Test plan

• go build ./sdk/...
• go vet ./sdk/...
• go test ./sdk/recall/...
• go test ./sdk/... ./sdkx/... ./voice/...

Made with Cursor