fix(mental-models): last_refreshed_at records the refresh, not the source watermark

[nicoloboschi]

The bug

POST /banks/{bank}/mental-models/{id}/refresh runs, writes new content, reports completed — and leaves last_refreshed_at untouched. A reporter drove ~6,000 refreshes/day against an intended ~350, for four days, because their scheduler reads that field to answer "have I already refreshed this?" and it never moved.

update_mental_model persisted the refresh's source-data watermark into last_refreshed_at, and _mental_model_processed_watermark clamps that watermark so it never regresses:

return max(newest_in_scope, current_last_refreshed_at)

On a model whose scope gained no new memories, newest_in_scope <= current, so the max is the value already in the column. The refresh wrote it straight back over itself. The document changed; the timestamp did not.

That also explains why it looked non-deterministic ("not universal — some models do get a new last_refreshed_at, in the same bank, in the same window"): models whose scope was being written to had a genuinely newer watermark, so theirs advanced. Nothing to do with consolidation or cron — those were correctly ruled out.

Introduced by #2878, which needed a data watermark and reused the wall-clock column for it.

The fix

One column cannot answer both "did a refresh run?" and "is this behind the data?". Split them:

Field	Means	Answers
last_refreshed_at	Wall-clock time a refresh completed. Meaning restored — the name never changed.	"Have I already refreshed this?"
last_memory_seen_at	New. Newest in-scope memory the last refresh saw.	"Is this behind the data?"

The new column takes over the existing value and the existing computation, unchanged. Staleness, the delta window, the knowledge-tree flag and the reflect agent's is_stale all key off it, so refresh behaviour is identical — this is not a change to when models refresh, only to what the timestamps report.

last_memory_seen_at deliberately mirrors last_memory_write_at on GET /stats, so the cheap whole-list rule reads as a sentence: last_memory_seen_at >= last_memory_write_at → up to date.

A completed refresh always stamps the clock

Including a delta refresh that read the scope, found nothing new, and preserved the content — it ran, and a caller polling for it must see that. This matters for exactly the reported workload: a model with static sources is the one whose refresh has nothing to write. A refresh that failed still stamps neither, so a retry re-reads the same window.

Migration

last_memory_seen_at is backfilled from last_refreshed_at — which today already holds the watermark, so the copy is lossless. No bank changes staleness on deploy: nothing mass-refreshes, nothing mass-stops. The column is nullable and consumers COALESCE back to last_refreshed_at for rows no refresh has stamped yet, so a restored pre-migration backup behaves correctly too. PG + Oracle, both re-runnable.

Control plane

bank-stats-view.tsx implemented the documented "compare last_refreshed_at against last_memory_write_at" rule. Left alone it would have reported every recently-refreshed model as current — a false-fresh freshness card — so it now reads last_memory_seen_at.

Compatibility — read before releasing

Schema: additive. last_memory_seen_at is a new optional field. Nothing removed, no type changed, check-openapi-compatibility passes, old clients ignore it.

Semantics: last_refreshed_at's value changes. This is a deliberate break and needs a note in the release, not a silent ship. A client following the list heuristic documented in v0.9.0 — compare last_refreshed_at against last_memory_write_at — will start reading models as up to date that aren't, until it switches to last_memory_seen_at. False-fresh is the direction that fails quietly, so it should be called out by name.

What makes it the right call rather than a new break:

Period	last_refreshed_at meant
inception → 2026-07-21	wall clock (NOW())
v0.8.5 → v0.9.1 (4 weeks, 4 releases)	the source watermark ← #2866 / #2878
this PR	wall clock again

#2878 needed a data watermark and reused the wall-clock column for it without renaming — that was the break. This reverts it and gives the watermark its own column. The documented compare-rule only landed 2026-08-04 (#3156), so it has been correct for exactly two releases.

The upgrade for anyone affected is one field name, and the replacement ships in the same response.

Tests

• The reported bug, reproduced: two refreshes over a scope that gained no memories. The watermark is identical both times (correct — the data didn't move); last_refreshed_at must advance anyway. Fails on main.
• A refresh that preserves content stamps the clock; a failed one stamps neither.
• The inverse regression: a recent last_refreshed_at must not mask a memory the document has never seen — staleness still keys off what was seen.
• Updated the delta watermark tests to assert against the column that now carries the watermark.

746 tests pass across the mental-model, delta, dry-run, scheduled-refresh, knowledge-page, consolidation and reflect suites.

Also from the report: which model did this operation refresh?

refresh_mental_model operations return document_id: null and carried no model identifier, so the operations log could not say which model an operation acted on. On a bank with 270 models that makes the log useless for diagnosis — which is why this took a live controlled experiment instead of one query.

The id was always there, in result_metadata — but the operations list exposes no result_metadata at all. So the list gains mental_model_id, surfaced the same way document_id and filename already are. The single-operation read already returns result_metadata and gets no duplicate field.

Still not in this PR

total on GET /banks/{bank}/mental-models. The envelope is {"items": [...]} with limit defaulting to 100 and no count, so a consumer cannot tell "100 models" from "page 1 of 3". One of their clients read 100 of 270 and treated the other 170 as deleted; our own dashboard shows "100 mental models" for that bank for the same reason. Worth its own issue — it changes a widely-consumed envelope.

🤖 Generated with Claude Code