Add the three contract members one OpenHuman migration needs

[YellowSnnowmann]

Summary

Adds MemoryRetrieval::recall_namespace_recent(namespace, limit) — the recency path, which the contract has never had.

This is the gap openhuman's direct-engine-refs ratchet names as the next upstream ask, and it is the one where the obvious migration is actively harmful rather than merely absent.

Why recall_namespace_scored is not the twin

It looks like the same call with the query left blank. It is not.

	resolves to	orders by
recall_namespace_scored(ns, query, …)	query_namespace_hits_excluding_session	similarity to query
recall_namespace_recent(ns, limit)	recall_namespace_memories	freshness + priority

The two share a prefix — load_documents_for_scope + kv_records_for_scope — and diverge after it. Passing "" to the scored path does not degrade to recency: it runs the ranking with nothing to rank against and returns hits ordered by a similarity signal computed from nothing.

That is why this needed a member rather than a caller convention. The substitution compiles, returns plausible hits, and quietly changes what the user gets back — the worst shape a missing method can take. Two OpenHuman handlers (memory.recall_context, memory.recall_memories) are blocked on exactly this, and migrating them onto the scored path would have shipped that silent change.

Shape

• Required, not defaulted. Every other MemoryRetrieval member is required, and the null provider answers Unsupported(Retrieval). A default returning an empty vector would be indistinguishable from "this namespace is empty" — the silent-empty failure this contract has been bitten by before (see Module bus embedder advertises non-zero dimensions while embedding to empty vectors, so recall silently returns nothing #84).
• Returns NamespaceMemoryHit, the same shape as the scored path, so a host re-ranking on engine signals treats the two uniformly rather than special-casing one.
• An unknown namespace is an empty vector, not an error: a true statement about that namespace rather than a fault the caller can act on.

Registration

All four lists, per the lesson from #86 — the compiler checks only the array length:

• the #[tinybus::interface] block in tinymemory-module/src/service/mod.rs (size-checked like the other list-returning members)
• the module manifest's methods in tinymemory-module/src/lib.rs
• tinymemory_bus::METHODS, 94 → 95, and the crate doc naming the count
• the loader's EXPECTED_METHODS in tests/module_e2e.rs

Validation

• cargo fmt --all -- --check — both workspaces
• cargo clippy --all-targets --all-features -- -D warnings — root; module workspace likewise
• cargo test -p tinymemory-tinycortex --test full_provider_conformance — 14 passed, including the new recency_recall_answers_without_a_query
• cargo test --manifest-path crates/tinymemory-module/Cargo.toml --lib — 49 passed, including the_served_members_are_exactly_the_published_contract
• Loader E2E against the real dlopen'ed release cdylib, one process per test: every_declared_method_is_actually_routed, the_manifest_declares_every_method_the_module_serves, the_module_advertises_the_complete_tinymemory_api — all pass

No dependency changes, so neither lockfile moves.

---

Second commit: the queue's two compound operations

Extended rather than split into another PR, because these three members are what one OpenHuman PR needs to migrate its remaining queue and recall call sites — landing them separately would cost two releases and two registry re-pins for one migration.

reset_tree and flush_now are the last queue call sites in OpenHuman, and neither is a thin call over an existing family. Both drive raw SQL against mem_tree_*from the host — tables this engine owns — so a contract member means the logic moves here, not that a signature is added over it.

flush_pending() -> FlushOutcome

Deduplication is the driver's, keyed on date + three-hour block, so two presses of a "flush now" control inside one window schedule the work once.

FlushOutcome carries stale_buffers beside enqueued because either alone misleads: enqueued: false is ambiguous between nothing to flush and already scheduled, and a caller showing the first when it is the second is lying about state the user is watching. Pinned by flushing_twice_in_a_window_schedules_the_work_once.

reset_derived_index() -> ResetOutcome

Discards summaries, buffers, entity indexes and trees, then schedules re-derivation. One operation on purpose — deleting the derived rows without queueing the rebuild leaves a store that answers structural queries with nothing and looks healthy doing it.

mem_tree_chunks is deliberately not in the table list. The chunks are the source; they are never deleted. resetting_the_derived_index_keeps_the_chunks_it_derives_from asserts the chunk count is unchanged across a reset — a reset that took them too would be data loss wearing the word "reset".

Two transactions rather than one, also deliberate: the first drops the job table, so re-enqueueing inside it would race its own truncation.

ResetOutcome carries three counts because they are not a ratio. Rows deleted, chunks returned to scope, and jobs scheduled are independent; collapsing any pair loses the ability to tell nothing to re-derive from re-derivation was not scheduled. Jobs can be fewer than chunks — the enqueue is keyed.

Null provider

Refuses both rather than taking the trait defaults. The defaults are right for a real driver with nothing buffered or nothing derived; they are wrong for a provider that stores nothing, where "flushed nothing" and "reset nothing" read as work done rather than as a driver that cannot do it.

The registration order caught a real mismatch

the_served_members_are_exactly_the_published_contract compares sequences, not sets, and failed on the first run: the interface serves the two Maintenance members with their family, while METHODS listed them after the Retrieval one. Fixed in all three lists. This is the check #86's commit message said would be the one that matters, and it was.

Updated validation

• conformance: 16 passed — adds flushing_twice_in_a_window_schedules_the_work_once and resetting_the_derived_index_keeps_the_chunks_it_derives_from
• module lib: 49 passed
• loader E2E against the real cdylib, one process per test: every_declared_method_is_actually_routed, the_manifest_declares_every_method_the_module_serves, the_module_advertises_the_complete_tinymemory_api, query_and_maintenance_families_dispatch_typed_requests — all pass at 97 members
• fmt + clippy -D warnings, both workspaces

Still not here

The chunk-store and engine-handle buckets (~96 refs between them in OpenHuman). with_connection hands out a SQLite handle, which no engine-neutral contract can promise — that is a subsystem move behind the bus, not a member, and it is the multi-thousand-line pivot tracked separately.

Deliberately not in this PR

The other two gaps behind openhuman's remaining queue call sites — reset_tree and flush_now — are not thin methods over an existing family. Both are compound operations that today reach with_connection and drive raw SQL against mem_tree_* from the host. Giving them contract members means moving that logic into the engine, which is a design pass rather than a signature, and folding it in here would make neither half reviewable. Filed as follow-up work rather than half-done alongside this.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9da94988-e852-419a-8e6f-d775e7355f08

Warning

Your free Security trial is over. An organization admin can activate billing to continue.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[tinysweeper]

tinysweeper found nothing blocking. Approving.

$0.0000 · 0 in / 0 out · 486 embedded · openrouter/openai/text-embedding-3-small

[tinysweeper]

How this change flows

1 changed behaviour across 8 relationships. 6 surrounding behaviours are shown (60 graph nodes walked). 39 further behaviours left out to keep the diagram readable.

flowchart LR
n0["...hod_fails_with_its_advertised_family_name<br/>changed"]:::changed
n1["call"]:::impacted
n2["assert"]:::impacted
n3["Result"]:::impacted
n4["assert_unsupported"]:::impacted
n5["...nt_opens_reuse_the_registered_object_path"]:::impacted
n6["store"]:::impacted
n0 -->|calls| n2
n0 -->|calls| n4
n0 -->|tests| n4
n1 -->|uses| n3
n4 -->|uses| n3
n5 -->|calls| n1
n5 -->|tests| n1
n6 -->|uses| n3
classDef changed fill:#0d4429,stroke:#238636,color:#e6edf3
classDef impacted fill:#161b22,stroke:#6e7681,color:#c9d1d9
classDef flagged fill:#5a1e02,stroke:#d93f0b,color:#ffffff
classDef blocking fill:#67060c,stroke:#f85149,color:#ffffff

Loading

_{Green: changed behaviour. Grey: surrounding behaviour. Arrows name the call, use, implementation, or test relationship. Orange: has findings. Red: has a finding that blocks the merge.}