fix(memory): warn on hidden owned-private matches in list/search

[coryzibell]

Closes #400

Summary

Implements option (a) from #400, per the Savorist's decision: list and search run public-only by default and silently drop the caller's own private matches (an ~85% undercount versus wake, which includes them). Rather than change the default visibility, we now emit a best-effort hint on stderr when the caller's own private matches are being hidden.

• Zero change to stdout, --json output, or exit codes — the hint is stderr only.
• Default visibility is unchanged (public-only stays the default).
• Option (b) — changing the default to include private — was explicitly rejected.
• The hint fires only when the context is public-only and an agent is set. --include-private and --mine both resolve to include_private=true and silence the hint.

Also documents the raw-vs-decayed --min-resonance divergence in the CLI help text: wake filters on raw stored resonance, while list/search filter on decayed effective resonance. This is a documentation-only clarification pending #404's explicit --resonance-basis flag.

Files affected

• src/store.rs — new trait method owned_private_matching.
• src/surreal_db/queries.rs — implementation; reuses build_resonance_filter / build_category_filter with an owner-scoped bound param (deliberately does not use build_visibility_filter, which would also admit public rows).
• src/surreal_db/trait_impl.rs — delegation.
• src/wake_ritual.rs — MockStore stub.
• src/helpers.rs — hidden_private_hint (pure, returns Option<String>) + warn_hidden_private (stderr wrapper).
• src/handlers/memory.rs — List/Search arms call the hint after stdout printing.
• src/cli.rs — --min-resonance help text (raw-vs-decayed note).
• CHANGELOG.md — new entry.

Test results

• cargo build — clean
• cargo clippy --all-targets — clean
• cargo test — 1174 lib passed + integration suites / 0 failed (16 new tests: 5 store-level, 11 hint-level; plus new integration suite tests/hidden_private_hint_cli.rs)
• E2E verified: hint appears on stderr only; --include-private silences it.

Review fixes

Addressing the review before merge:

• W1 — semantic-mode hint suppression. The hidden-private hint is now gated off under --semantic: semantic ranking does not run the owner-scoped count path, so the hint could misreport. Docstrings re-scoped to text search accordingly.
• S1 — hydration-cost comment. Added a comment documenting the hydration cost of the count query so future readers understand why it stays best-effort.
• S2 — stderr/stdout CLI integration test. New integration test asserts the hint lands on stderr and never contaminates stdout (tests/hidden_private_hint_cli.rs).
• N2 — MockStore unreachable comment. Clarifying comment on the MockStore stub explaining why the branch is unreachable in the mock.

Bonus fix

src/surreal_db/connection.rs — apply_schema now retries transient "read or write conflict" errors from concurrent embedded-SurrealDB schema init, using bounded jittered backoff. All schema statements are IF NOT EXISTS, so retries are idempotent and the happy path is untouched. This was a pre-existing flake surfaced by the new integration test running schema init concurrently.

Note

The count query is best-effort — any error is swallowed and never affects the exit code or stdout.

[coryzibell]

Code Review (Verdictia Stern)

Verdict: REQUEST CHANGES — C 0 · W 1 · S 2 · N 2. Privacy core is clean; one warning blocks.

Critical

None. owned_private_matching_async (src/surreal_db/queries.rs:598-607) is strictly scoped visibility = 'private' AND owner = $current_agent with bound params; category names validated; deliberately avoids build_visibility_filter (would admit public rows). Owner-scoping proven by test_owned_private_matching_scopes_to_caller_only. No injection, no cross-agent leak.

Warnings

W1 — Semantic-search parity gap; docstrings overclaim (src/handlers/memory.rs:571, src/surreal_db/queries.rs:592, src/store.rs:194, src/helpers.rs:191)
search --semantic uses vector similarity, but the hint count always uses the BM25 @@ predicate and is called unconditionally. Under --semantic:

• False negative: semantically-matching owned-private entry with no literal term overlap isn't counted — the exact silent undercount list/search silently omit the caller's own private entries — default-contract mismatch with wake #400 exists to fix persists on the semantic path.
• False positive: a literal @@ match absent from top-N vector results (or un-embedded) still triggers the hint; the user runs --include-private --semantic and the promised entry doesn't appear.

The store.rs:194 / helpers.rs:191 docs claim "the same BM25 @@ match search uses" — only true for the non-semantic branch. No test covers --semantic + hint. Fix: gate the hint off when semantic is true (or count with the semantic predicate), and scope the docstring claim to text search.

Suggestions

S1 — Hint runs a second full query with row hydration on every default list/search when an agent is set (queries.rs:618-624). Hydration is necessary for the in-memory tag/field filters, but it doubles DB work on the common path. Document as a known cost.
S2 — stdout/JSON invariance is argued structurally but not integration-tested. One stderr-vs-stdout capture test (especially on the --semantic path) would pin W1's regression surface.

Nitpicks

N1 — PR body says "4 store-level, 12 hint-level" tests; actual split is 5 + 11 (total 16 correct).
N2 — MockStore::owned_private_matching unreachable!() (src/wake_ritual.rs:818) is genuinely unreachable from wake paths and matches sibling stubs. Acceptable.

Cleared

Semantic neutrality (stderr-only, errors swallowed, hint after all stdout printing); filter parity for text search including limit-stripping; full trigger matrix; default visibility unchanged (decree-compliant — option (b) not implemented); CHANGELOG creation satisfies the repo's own documented convention, not scope creep; second commit is pure rustfmt.

[coryzibell]

Re-review (Verdictia Stern) — @ 57d668a

#	Finding	Status
W1	Semantic-mode hint suppression	RESOLVED — guard is the first thing the pure function does; Search passes the real destructured flag, List hardcodes false; docstrings re-scoped; hint_absent_under_semantic_mode flips only the flag on the same fixture, proving suppression is flag-driven
S1	Hydration-cost comment	RESOLVED — comment-only change, honest justification (COUNT can't project field-presence predicates; would over-count)
S2	CLI integration test	RESOLVED — drives real CARGO_BIN_EXE_mx against isolated MX_SURREAL_ROOT; proves stderr-only hint (list + search), hint-free valid --json stdout, --include-private suppression. Semantic suppression pinned at unit layer (ONNX model — correct call for a hermetic test)
N1	PR-body test split	RESOLVED
N2	MockStore unreachable!() comment	RESOLVED

Bonus fix (apply_schema retry): ACCEPTED. Bounded (12 attempts, ~4s worst case); narrow (all_retryable — one non-retryable error → fail-fast with the full error map); idempotency verified against the actual schema (IF NOT EXISTS/OVERWRITE/keyed UPSERT/guarded UPDATE, explicitly designed for replay); backoff math overflow-safe (shift capped, saturating mul, 320ms ceiling). No smuggling — all 8 touched files map 1:1 to findings + bonus + CHANGELOG.

New finding: N (nit) — jitter derives from SystemTime::now().subsec_nanos() % 40; on coarse-resolution clocks, lockstep processes could draw near-identical jitter. Fine on Linux, self-limiting via bounded attempts. Optional hardening: fold per-process entropy (PID) into the seed.

Overall: APPROVE

the smallest nod — the nut is good. Down the good chute.