Cache invalidation hooks when Brain/Messages collections split

[atomantic]

Cache invalidation hooks in brainStorage.js / messageSync.js / meatspacePostDrillCache.js — needed only when their backing collections split into per-record collectionStore layouts. These caches don't touch universe data so they were safe to skip for PR #458. When a future PR splits Brain (or Messages) into per-record collectionStore dirs, audit each cache for "cache key ↔ split-record-id" consistency: per-id writes are visible to other readers without going through the cache, so any cache that fronts the now-split file needs an invalidation event hook (or a switch to read-through against store.loadOne).

---

Triage 2026-06-05 — still parked, trigger NOT met

Re-confirmed the precondition is unmet on main, and measured why it isn't worth doing yet:

• brainStorage.js and messageSync.js both still use the monolithic readJSONFile/tryReadFile + in-memory cache pattern — neither uses createCollectionStore.

• The split has no performance justification at current scale. Migration 034 (the worked-example split) was driven by universes hitting "30+ records at ~50KB each → 1.4MB whole-file rewrite per edit." Brain's stores are nowhere near that:

  store	size	records
  projects.json	18 KB	12
  links.json	14 KB	22
  ideas.json	6 KB	6
  admin.json	1.3 KB	2
  people.json	0.5 KB	1
  memories.json	0.5 KB	1
  buckets.json	absent	0

  Largest store ≈ 1/80th of a single universe record. The monolithic-rewrite cost collectionStore exists to eliminate is negligible here.

• Brain is federated (applyRemoteRecord, brainSyncLog, peer-synced). A split would also require a new brain wire-category + schema-version gate in server/lib/schemaVersions.js with dual-read tolerance, plus rewiring ~12 consumer modules. That's real risk spent against a scale problem that doesn't exist yet — premature abstraction.

• Messages is NOT a collectionStore candidate regardless of size: its sync path rewrites the whole per-account file in bulk (push new / prune stale / trim to max), so per-record write isolation buys ~nothing, and it's already sharded per-account. Drop it from this issue's scope when the split eventually happens.

Concrete trigger to revisit

Do the Brain split (and then these cache hooks) when ANY of:

• a single brain entity store exceeds ~500 KB or ~few-hundred records, OR
• per-record brain edits show noticeable latency (whole-file rewrite contention), OR
• a feature requires concurrent writes to different brain records that currently serialize on the shared file.

Until one of those is true, keep parked.

Migrated from PLAN.md by /do:replan --issues. Plan slug: data-versioning-cache-invalidation-on-split.

[atomantic]

Re-labeled plan → future: this work is explicitly gated on Brain/Messages collections being split into per-record collectionStore layouts, but on main both brainStorage.js and messageSync.js still use the monolithic readJSONFile + in-memory cache pattern (no createCollectionStore). Cache-invalidation hooks only make sense once the split exists, so parking as future until that precondition is met.

[atomantic]

Triage 2026-06-10 — keep parked; target is the documented trigger (no calendar date)

Reviewed against "make actionable / close / solidify+target." This issue is the exemplary case: it is already fully solidified and its "target" is a precise, measured condition, not a date. Doing it now would be premature abstraction (the prior triage measured the largest brain store at ~1/80th of a single universe record — the monolithic-rewrite cost collectionStore eliminates is negligible here).

Deliberately NOT assigned a milestone — its trigger to revisit is condition-based (any of):

• a single brain entity store exceeds ~500 KB or ~few-hundred records, OR
• per-record brain edits show noticeable latency, OR
• a feature requires concurrent writes to different brain records that currently serialize on the shared file.

Keeping future until one of those is true. (Scope reminder for when it fires: Messages is NOT a collectionStore candidate regardless of size — drop it from scope.)

[atomantic]

Triage 2026-06-23 — keep future; precondition still unmet

Re-confirmed in the future-tag sweep. The exemplary condition-gated issue: already fully solidified, trigger is a measured condition (not a date). On main both brainStorage.js and messageSync.js still use the monolithic readJSONFile/tryReadFile + in-memory cache pattern — neither uses createCollectionStore, so the split this work hangs off of does not exist. Doing it now is premature abstraction (largest brain store ≈ 1/80th of a single universe record).

Blocker: Brain/Messages have not been split into per-record collectionStore layouts. Revisit when ANY of:

• a single brain entity store exceeds ~500 KB or ~few-hundred records, OR
• per-record brain edits show noticeable latency (whole-file rewrite contention), OR
• a feature requires concurrent writes to different brain records that currently serialize on the shared file.

Stays future, no milestone (condition-gated). Scope reminder when it fires: Messages is NOT a collectionStore candidate regardless of size — drop it from scope.