From 8f50259efe65e7984de54e7382fecc2d4b6c8047 Mon Sep 17 00:00:00 2001 From: Julien Calixte Date: Mon, 29 Jun 2026 00:31:04 +0200 Subject: [PATCH] docs: record two-key cache strategy for reference modes Decide the C3/C4 cache shape: content keyed by its own SHA (write-once, immutable snapshot store) plus a path key holding the latest content (live pointer). Notes the current immutability violation to fix. --- DESIGN.md | 1 + docs/adr/0002-two-reference-modes.md | 1 + 2 files changed, 2 insertions(+) diff --git a/DESIGN.md b/DESIGN.md index 245bc41..d08bdd1 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -407,6 +407,7 @@ Cells: link strength (9/3/1/blank). Importance row = Σ(weight × strength). - **Asymmetric file index:** `addFile` deduped by SHA only, `registerUploadedFile` by PATH — so an edit (same path, new SHA) left a stale duplicate entry. **Fixed** — `addFile` now dedups by SHA *and* path (a path is unique), with a regression test in `userRepo.store.spec.ts`. (Full bidirectional index C3 still the longer-term direction.) - **ADR-0001 over-absolute:** it called SHA-keyed references "a fragility". **Refined** by ADR-0002 into two intentional modes (Live/Snapshot). - **`CLAUDE.md` "edit history tracking"** mislabels the visited-repos History; no edit-history feature exists. (Flagged in CONTEXT.md.) +- **Snapshot cache not immutable:** editing writes new content under the *viewed* (old) SHA's cache key (`prepareNoteCache` keys by the viewed sha), so a re-opened old-SHA snapshot can serve new content from cache. **Decided fix (ADR-0002):** key the immutable store by the content's *own* SHA (write-once), keep the Path key as the latest pointer. *(Not yet implemented — the C3/C4 cache slice; unlocks the snapshot banner.)* - **Naming drift carried from the language session:** `Flux`→`Igarapé`, `HistoricNotes`→`Index`, `Repetition`→`Card`, `PublicNote*`→`PublishedNote*`, `useNotes()` returns Files not Notes. (Tracked in CONTEXT.md "Flagged ambiguities".) --- diff --git a/docs/adr/0002-two-reference-modes.md b/docs/adr/0002-two-reference-modes.md index 0a8d10b..dbbd022 100644 --- a/docs/adr/0002-two-reference-modes.md +++ b/docs/adr/0002-two-reference-modes.md @@ -17,4 +17,5 @@ This refines ADR-0001, which framed SHA-keyed references as "a fragility." That ## Consequences - The system **pre-caches** aggressively (content is cached by both SHA and Path on every fetch / freshness pull) so the pinned version is usually present, including offline. +- **Cache shape (C3/C4):** content is cached under two keys — its own **content SHA** (write-once, immutable → the snapshot store) and its **Path** (overwritten with the latest content → the live pointer). Both hold the full content, so the latest survives even if a SHA entry is evicted, maximizing offline availability for any version already encountered. (Today the code violates this by writing edited content under the *viewed* old SHA key; the fix is to write under the content's *new* SHA and never overwrite an existing SHA entry.) - When a Snapshot reference's pinned content is genuinely unavailable (never-fetched + offline — common on a flaky mobile connection), the system **falls back to the most up-to-date cached version and shows a banner** disclosing "this is the latest available, not the exact shared version." Integrity is preserved by **disclosure, not refusal**: the reader is never silently shown different content, but is also never dead-ended on the metro. (This chooses graceful continuity over a hard "unavailable" stop, given mobile is the primary read context.)