a7d846aa33
Capture the walk-with-me + qfd session: CONTEXT.md ubiquitous-language glossary, DESIGN.md goal-driven cascade (Beauty / Pride & Peace / public voice), and ADRs for Note identity (Path) and the two reference modes (Live vs Snapshot).
2.1 KiB
status
| status |
|---|
| accepted (refines ADR-0001) |
Two reference modes: Live (Path) and Snapshot (SHA)
A reference to a Note resolves in one of two deliberate modes. A Live reference (by Path) resolves to the Note's current content — this is a Backlink you follow in your own repo, and it reflects edits (Note identity = Path, per ADR-0001). A Snapshot reference (by SHA) resolves to that exact, immutable version — this is a shared or bookmarked stack link (?stackedNotes=sha), content-addressed so what was shared cannot change underneath a reader.
This refines ADR-0001, which framed SHA-keyed references as "a fragility." That framing was too absolute: SHA-pinning is the correct tool for a Snapshot reference. Pinning is an integrity feature — it guarantees a shared view can't be silently rewritten, so no reader is misled and no author is misrepresented.
Considered options
- Two explicit modes (chosen). Live=Path, Snapshot=SHA, each with a clear purpose. Cost: the resolver must support both, and the UI must make the mode legible (you should know whether you're reading "now" or "as shared").
- Single mode, Path only (rejected). Simpler, but a shared link would always re-resolve to current content — destroying the integrity guarantee that makes sharing safe.
- Single mode, SHA only (rejected by ADR-0001). In-repo navigation would break on every edit.
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.
- 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.)