refactor: coerce None metadatas at ChromaDB backend boundary (supersedes per-site guards from #999, #1013)

[bensig]

Context

Two PRs recently merged to guard against `None` metadata / document entries returned by ChromaDB `query()`:

• fix(searcher): guard against None metadata in CLI print path #999 — guards in `searcher.py` (`search`, `search_memories`), `miner.py` (`status`), `mcp_server.py` (4 sites) + regression tests. Merged at `1b89b49`.
• fix: guard Layer3.search_raw against None doc/meta from ChromaDB (#1011) #1013 — guards in `layers.py` (`Layer3.search`, `Layer3.search_raw`). Merged at `6426669`.

Both fix real user-visible crashes (`AttributeError: 'NoneType' object has no attribute 'get'`) that hit frequently on chromadb 1.5.x via the queue-stall in #1006.

Combined, these introduce ~9 per-site `meta = meta or {}` / `doc = doc or ""` guards across 5 files. During review of #999, @jphein proposed centralizing the coercion at the adapter boundary:

"Whack-a-mole across 8 call sites suggests the cleaner fix probably lives one layer down — either:

1. `_get_cached_metadata` / `_fetch_all_metadata` (in `mcp_server.py`) strip `None` entries as they build the cache, OR
2. `ChromaCollection.get()` / `ChromaCollection.query()` in `backends/chroma.py` coerce `None` metadatas to `{}` at the adapter boundary.

Option 2 is more general — every future call site would get the guard for free... Happy to convert this to the adapter-level fix if maintainers prefer."

This issue tracks the adapter-level consolidation jphein offered.

Proposal

Normalize `None` → `{}` (for metadatas) and `None` → `""` (for documents) inside `mempalace/backends/chroma.py`'s `ChromaCollection.query()` and `.get()` return paths. Every consumer inherits the guard; every per-site `meta or {}` / `doc or ""` guard introduced by #999 and #1013 gets deleted.

Alignment with RFC 001

This fits RFC 001's direction of formalizing backend return shapes (typed `QueryResult` / `GetResult`, normalized at the boundary). Arguably the coercion belongs in whatever the RFC 001 cleanup PR lands — merge coordination needed.

Scope

• Add `None` → `{}` / `""` coercion in `ChromaCollection.query()` return path
• Same for `.get()` return path
• Regression test at the adapter level (one test covers all callers)
• Delete per-site guards added by fix(searcher): guard against None metadata in CLI print path #999 in `searcher.py`, `miner.py`, `mcp_server.py`
• Delete per-site guards added by fix: guard Layer3.search_raw against None doc/meta from ChromaDB (#1011) #1013 in `layers.py`
• Keep the per-site regression tests from fix(searcher): guard against None metadata in CLI print path #999 — they still verify downstream behavior under the same input shape

Non-goals

• Handling `None` `distances` — not observed in practice; separate issue if it surfaces
• Full RFC 001 typed-result migration — that's docs: RFC 001 — storage backend plugin specification #743 / its cleanup PR

Offer to @jphein

You raised this during #999 review and offered to convert. If you have bandwidth, happy to have you drive this one — your diagnosis is clearest on what the failure mode looks like. Alternatively, any contributor can grab it.

Related

• fix(searcher): guard against None metadata in CLI print path #999, fix: guard Layer3.search_raw against None doc/meta from ChromaDB (#1011) #1013 — the per-site fixes this would supersede
• bug: fresh pip install mempalace silently broken on chromadb 1.5.x — writes queued but never flush, search returns ghosts #1006 — root cause (chromadb 1.5.x queue-stall)
• docs: RFC 001 — storage backend plugin specification #743 — RFC 001 storage backend plugin spec (adjacent)
• chromadb<0.7 pin breaks MCP server on Python 3.14 #487 — Python 3.13+ Pydantic V1 root cause

[jphein]

Happy to drive this — it was my suggestion during #999 review and the scope is clear. Will open a PR once the current #1021 review cycle closes.

One question on merge coordination: is RFC 001 (#743) likely to land before I start, or should I proceed independently and coordinate on merge order? If #743 is actively in progress, I'd rather align now than rebase later.