From f39905455e89ec26b7da300635c4009dfccad601 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Tejero=20Cantero?= Date: Thu, 13 Aug 2026 20:22:13 +0200 Subject: [PATCH] :books: Describe the listing summary cache --- docs/technical-guide/developer/branching.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/technical-guide/developer/branching.md b/docs/technical-guide/developer/branching.md index f612363616..c83816750c 100644 --- a/docs/technical-guide/developer/branching.md +++ b/docs/technical-guide/developer/branching.md @@ -242,6 +242,16 @@ there is a two-level gate (`branch-diff-counts`): branch: count errors degrade to zeros with a warning (the merge itself still refuses loudly). +The computed `[ahead behind conflicts]` summary is cached in-memory +(`files-branch::branch-summary-cache`) keyed by +`(base-snapshot-id, source-revn, branch-revn)`. The key names exactly the +inputs the computation reads, so a stale entry cannot exist and the cache +needs no invalidation logic: a cache miss is the cold path, and a repeated +listing with no intervening save performs no comparison work. The cache +bounds memory (`max-size`, `keepalive`) and never decides correctness, and +a failed computation is not stored, so a broken branch keeps degrading to +zeros with a warning on every listing. + ## The three-way diff engine `app.common.files.branch-merge` is the heart of the feature. It is a pure,