Files
headroom/tests/test_memory/test_metadata_matching.py
xiaoheiai4719-collabandJerrettDavis b50b3eb5ed fix(memory): match compound and null SQLite metadata filters (#4373)
## Description

SQLite metadata filters bind arrays/objects as whitespace-containing
JSON text while `json_extract` returns compact JSON, so matching records
disappear from both query() and count(). Empty compounds can instead
match JSON-looking strings. A None filter matches the string "null"
rather than an explicit JSON null.

Normalize compound values with SQLite's json() and require matching JSON
types. Match None through json_type = 'null', distinguishing an explicit
null from a missing key. String filters require JSON text as well, so
the inverse query cannot select an array/object. Native numeric/boolean
equality is unchanged. Compound comparison remains JSON-text equality:
array order and object member order matter, now documented and tested;
this does not introduce deep structural equality.

This addresses the follow-up identified in [the review of the earlier
scalar-only fix
#3240](https://github.com/headroomlabs-ai/headroom/pull/3240#pullrequestreview-5022019065).
Actual all-state PR searches for metadata/non-scalar,
metadata/json_extract, and metadata/filters/null found that earlier fix
and unrelated changes, not a compound/null fix. metadata_filters issue
search found no match. Base e995eb9f1d.

## Type of Change

- [x] Bug fix

## Changes Made

- Normalize serialized compound filters to the representation SQLite
extracts.
- Require JSON type equality for compound values, excluding JSON-looking
strings.
- Match explicit JSON null without selecting missing keys or the string
"null".
- Restrict string filters to JSON text, preventing the inverse
compound/string confusion.
- Add real-file SQLite query/count regressions and ordering/isolation
controls; retain existing numeric/boolean equality and key-validation
behavior.

## Testing

- [x] Fifteen execution-level regressions fail before and pass after the
fix.
- [x] Existing ordering control and adjacent memory tests pass.
- [x] Security validations, including metadata key-injection handling,
pass.
- [x] Changed-file Ruff lint/format and SQLite adapter mypy pass.
- [x] Standalone real-store persistence proof executed outside pytest.
- [ ] Full repository and optional model/vector qualification completed.

### Test Output

```text
python -m pytest tests/test_memory/test_metadata_matching.py -q -rs -o addopts=''
# Original source: 15 failed, 8 passed, 178 existing warnings

python -m pytest tests/test_memory/test_metadata_matching.py tests/test_memory/test_hierarchical.py tests/test_memory/test_query_conditions.py tests/test_memory/test_supersession_repair.py tests/test_security_validations.py -q -rs -o addopts=''
77 passed, 8 skipped, 354 warnings in 0.71s

ruff check headroom/memory/adapters/sqlite.py tests/test_memory/test_metadata_matching.py
All checks passed!
ruff format --check headroom/memory/adapters/sqlite.py tests/test_memory/test_metadata_matching.py
2 files already formatted
mypy --follow-imports=silent headroom/memory/adapters/sqlite.py
Success: no issues found in 1 source file
git diff --check
exit 0
```

Eight skips are four hnswlib-dependent and four
sentence-transformers-dependent tests. Warnings are existing
datetime.utcnow deprecations. Focused mypy reports unused configuration
sections; dependency-wide static analysis is not claimed.

## Real Behavior Proof

- Environment: Linux, CPython 3.12.14, real file-backed
SQLiteMemoryStore. Public save/query/count operations, reopening the
database before queries. No mocks, model inference, provider service, or
network traffic.
- Exact command / steps: Save the script below outside the checkout,
then run `PYTHONPATH=. python /path/to/proof.py` from original and
patched checkouts:

```python
import asyncio
import json
import tempfile
from pathlib import Path

from headroom.memory.adapters.sqlite import SQLiteMemoryStore
from headroom.memory.models import Memory
from headroom.memory.ports import MemoryFilter


async def main():
    with tempfile.TemporaryDirectory() as directory:
        store = SQLiteMemoryStore(Path(directory) / 'memory.db')
        cases = {
            'array': ['a', 'b'],
            'object': {'priority': 5},
            'nested': {'items': ['café', 'space within a string']},
            'empty': [],
            'null': None,
        }
        for name, value in cases.items():
            await store.save(Memory(id=f'{name}-value', user_id='alice', content='saved', metadata={name: value}))
            await store.save(Memory(id=f'{name}-text', user_id='alice', content='text control', metadata={name: json.dumps(value, separators=(',', ':'))}))
        await store.save(Memory(id='missing', user_id='alice', content='no metadata'))
        # Reopen the real database to exercise persisted serialization and reads.
        store = SQLiteMemoryStore(Path(directory) / 'memory.db')
        observed = {}
        for name, value in cases.items():
            query = MemoryFilter(user_id='alice', metadata_filters={name: value})
            observed[name] = {'ids': [item.id for item in await store.query(query)], 'count': await store.count(query)}
            text_query = MemoryFilter(user_id='alice', metadata_filters={name: json.dumps(value, separators=(',', ':'))})
            observed[f'{name}-inverse'] = {'ids': [item.id for item in await store.query(text_query)], 'count': await store.count(text_query)}
        print(json.dumps(observed, indent=2), flush=True)
        assert all(observed[name] == {'ids': [f'{name}-value'], 'count': 1} for name in cases)
        assert all(observed[f'{name}-inverse'] == {'ids': [f'{name}-text'], 'count': 1} for name in cases)


asyncio.run(main())

```

- Observed result: Before, array/object/nested filters returned no
records; an empty-array filter selected both the array and its string
representation; None selected the string "null". Inverse JSON-looking
string queries also selected compound values. After, each filter returns
exactly its persisted typed value and count() returns 1; inverse string
queries select only the corresponding string. Missing metadata and
JSON-looking strings do not match compound/null filters. The original
proof exits 1; the patched proof exits 0.
- Not tested: Full repository suites, optional model/vector
integrations, live production databases, or alternate memory backends.
Object-member ordering remains significant; no schema/data migration or
structural JSON equality is introduced.

## Runtime Rollout Safety

- Rollout-managed feature(s): None; existing SQLite memory query/count
API.
- Minimum rollout channel: Normal release after maintainer
qualification.
- Stable/default behavior changed: Compound/null filters match their
typed persisted values rather than missing records or matching
JSON-looking strings. Numeric/boolean equality is unchanged;
JSON-looking string filters now match only stored JSON strings.
- Kill switch / disable path: No new flag; omit compound/null metadata
filters if rolling back.
- Unsafe override required: No.
- Qualification impact: Real-store regressions, persistence proof,
security checks, and adjacent suites pass; full repository and optional
model/vector qualification remain outstanding.
- Rollback path: Revert this commit. No schema, dependency,
configuration, or persisted-data changes.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

Ready for human review. The current PR delta was re-reviewed with AI
assistance after upstream main was synchronized; the contributor patch
is unchanged. Historical tests and reviewer-reported checks remain
scoped as documented below; this is not a claim of
full-suite/native/provider qualification or merge approval.

## Checklist

- [x] Regression cases demonstrate the original failures.
- [x] Changed source and tests pass lint and formatting.
- [x] CHANGELOG.md was not edited.
- [ ] Full repository qualification completed.

## Additional Notes

Implemented and tested with OpenAI AI assistance. Checked test items
describe executed verification, not a claim that the publication owner
personally ran it.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-10-28 21:22:21 -05:00

124 lines
4.1 KiB
Python

"""Execute JSON-valued metadata filters against the real SQLite memory store."""
import json
import pytest
from headroom.memory.adapters.sqlite import SQLiteMemoryStore
from headroom.memory.models import Memory
from headroom.memory.ports import MemoryFilter
@pytest.mark.asyncio
@pytest.mark.parametrize(
"value",
[
["a", "b"],
{"priority": 5},
{"nested": ["a", "b"]},
["café", {"note": "spaces within strings remain"}],
[],
{},
["single"],
],
)
async def test_compound_metadata_matches_without_matching_json_strings(tmp_path, value):
store = SQLiteMemoryStore(tmp_path / "memory.db")
await store.save(
Memory(id="match", user_id="alice", content="saved", metadata={"value": value})
)
await store.save(
Memory(
id="string",
user_id="alice",
content="not a compound value",
metadata={"value": json.dumps(value, separators=(",", ":"))},
)
)
await store.save(
Memory(id="other-user", user_id="bob", content="saved", metadata={"value": value})
)
query = MemoryFilter(user_id="alice", metadata_filters={"value": value})
assert [memory.id for memory in await store.query(query)] == ["match"]
assert await store.count(query) == 1
@pytest.mark.asyncio
async def test_null_metadata_matches_explicit_null_not_missing_or_text(tmp_path):
store = SQLiteMemoryStore(tmp_path / "memory.db")
for name, metadata in [("null", {"value": None}), ("missing", {}), ("text", {"value": "null"})]:
await store.save(Memory(id=name, user_id="alice", content="saved", metadata=metadata))
query = MemoryFilter(user_id="alice", metadata_filters={"value": None})
assert [memory.id for memory in await store.query(query)] == ["null"]
assert await store.count(query) == 1
@pytest.mark.asyncio
async def test_compound_metadata_preserves_array_and_object_member_order(tmp_path):
store = SQLiteMemoryStore(tmp_path / "memory.db")
await store.save(
Memory(
id="saved",
user_id="alice",
content="saved",
metadata={"array": [1, 2], "object": {"a": 1, "b": 2}},
)
)
for metadata in [{"array": [2, 1]}, {"object": {"b": 2, "a": 1}}]:
query = MemoryFilter(user_id="alice", metadata_filters=metadata)
assert await store.query(query) == []
assert await store.count(query) == 0
@pytest.mark.asyncio
@pytest.mark.parametrize(
"value",
[
["a", "b"],
{"priority": 5},
{"nested": ["a", "b"]},
["café", {"note": "spaces within strings remain"}],
[],
{},
["single"],
None,
],
)
async def test_json_looking_string_filter_matches_only_text(tmp_path, value):
store = SQLiteMemoryStore(tmp_path / "memory.db")
text = json.dumps(value, separators=(",", ":"))
for name, saved in [("text", text), ("json", value)]:
await store.save(
Memory(id=name, user_id="alice", content="saved", metadata={"value": saved})
)
query = MemoryFilter(user_id="alice", metadata_filters={"value": text})
assert [memory.id for memory in await store.query(query)] == ["text"]
assert await store.count(query) == 1
@pytest.mark.asyncio
@pytest.mark.parametrize("value", [True, False, 1, 0, 1.0, 0.0])
async def test_numeric_and_boolean_metadata_retains_native_sqlite_equality(tmp_path, value):
store = SQLiteMemoryStore(tmp_path / "memory.db")
for name, saved in [
("true", True),
("false", False),
("one", 1),
("zero", 0),
("float-one", 1.0),
("float-zero", 0.0),
("text-one", "1"),
("text-zero", "0"),
]:
await store.save(
Memory(id=name, user_id="alice", content="saved", metadata={"value": saved})
)
query = MemoryFilter(user_id="alice", metadata_filters={"value": value})
expected = {"true", "one", "float-one"} if value else {"false", "zero", "float-zero"}
assert {memory.id for memory in await store.query(query)} == expected
assert await store.count(query) == 3