Repository navigation
doctor: API round-trip check fails against 202 materialization (file_write_status: pending) — and the run mutates config.json #1666
Description
Activity
@phernandez — would you mind reviewing our analysis here? Two questions after digging through
main:-
Materialization half — fixed on
main, any chance of a 0.23.x backport? We traced the fix to_read_materialized_api_note+note_content_materialization.drain_pending_materializationsinsrc/basic_memory/cli/commands/doctor.py(pinned bytest_doctor_waits_for_deferred_api_note_materialization). On the 0.23.0 release, however, the failure is deterministic (the immediatePath.exists()at the old check), which makesbm doctorunusable for anyone on that version — the version a freshuv tool install basic-memoryresolved for us this week. If a 0.23.3 patch release is planned, this would be a good candidate. -
Config rewrite half — intended? Even with the materialization fix, a doctor invocation rewrites
config.json(_delete_doctor_project_locally→save_config, plus the promo-flag stamps), so the net config effect of create-doctor-project + delete-doctor-project is non-zero bytes. We hit this concretely: our drift-detection tooling pins the config's sha256 across runs and a doctor invocation trips it (details in the issue body). If the byte churn is considered fine, no action needed — a yes/no here would let us close this half on our side.
Happy to open a PR for either half if useful (fork + DCO + CLA flow per CONTRIBUTING — just say which).
-
Bug Description
bm doctorfails deterministically at its first API round-trip check on 0.23.0: the entity-create endpoint returns 202 Accepted withfile_write_status: "pending"(the write is applied asynchronously by the background materialization worker, by design), but doctor checksPath.exists()immediately after the response — with no await point between, the queued write cannot have run yet, so the check can never pass.A secondary behavior on the same invocation:
bm doctorrewrites~/.basic-memory/config.json(project create + cleanup both callsave_config), stampingcloud_promo_first_run_shown/cloud_promo_last_version_shownand re-serializing the whole file. The four configured projects survive semantically, but the bytes change — anything pinning the config's hash (drift detection, benchmark runs comparing config-sha across a run) breaks after a doctor invocation.Steps To Reproduce
0.23.0viauv tool install basic-memory==0.23.0(also reproduced from a fresh checkout of the 0.23.0 tag)~/.basic-memory/config.json(sqlite backend)bm doctorExpected Behavior
Doctor completes its checks: the API-written note file is verified on disk, the manual note is indexed and searchable, the disposable project is cleaned up, and
config.jsonis left byte-identical to before the run (the doctor project was created and deleted — the net config effect should be zero apart from any intentionally persisted state).Actual Behavior
Reproduced 4/4 runs. The failure envelope itself carries the cause: the 202 response includes
"file_write_status": "pending". A live probe of the same client stack measured the file appearing on disk 11 ms after the response (exists_immediately=False, appeared_after=0.011s). After the failed run,config.jsonhas new bytes (promo flags stamped, full-model rewrite).Environment
uv tool install basic-memory==0.23.0(Follow-up note in the comments: the materialization half appears fixed on
mainvia_read_materialized_api_note+drain_pending_materializations; this report is against 0.23.0, where the failure is deterministic.)