perf(editor): ttl-refresh traject index snapshots, bound body cache, implements index

[tdjager]

Problem (audit advice #9)

Three staleness/perf problems on the editor-api read paths:

1. Stale-forever traject caches — TrajectCorpusCache entries were only invalidated on traject create/delete. The per-traject source-map index snapshot never picked up upstream changes (new laws merged, re-harvests, saves on another replica) until process restart, and the lazily-fetched body cache was unbounded and never refreshed either.
2. O(corpus) display names per request — GET /corpus/laws called resolve_display_name per law per request: a line scan of every body, plus a full serde_yaml_ng parse for name: '#ref' laws. For the unfiltered list that is O(total corpus bytes) per page load.
3. O(corpus) implementor discovery with serialized fetches — implementors_in_scope lazily fetched every metadata-only law's body sequentially under the per-source mutex on every request, and silently skipped fetch failures, so a throttled scan returned a silently incomplete list.

Changes

TTL + refresh on the per-traject index snapshot (TRAJECT_INDEX_TTL = 60s)

Follows the existing CHANGED_LAWS_TTL precedent (same 60s convergence target). The first request past the deadline re-enumerates the sources and swaps in a fresh SourceMap; concurrent requests keep serving the stale snapshot while one refresh is in flight (single-flighted per traject), and a failed refresh re-arms the stale snapshot for another TTL window instead of erroring reads. A refresh where any source fails to enumerate is treated as failed — serving the previous complete snapshot beats swapping in one with thousands of laws missing. The failed-refresh warn is rate-limited (first failure and every 10th consecutive one; the rest log at debug) so a permanently broken source doesn't re-warn every minute.

Why this is safe w.r.t. saves: the refreshed instance carries over

• the backend map (same Arc<Mutex<…>> instances — an in-flight save keeps excluding writers across the swap, and the writable-own → seed lock-ordering invariant from fix(editor): optimistic concurrency (ETag/If-Match) for law and scenario saves #790 is untouched);
• the post-save overlay (shared Arc) — a refresh never resurrects pre-save content, and a record_save racing the swap on the old instance is visible through the new one;
• the changed-laws cache (shared Arc) — a refresh cannot undo save_law's invalidation;
• the implements index (served stale while rebuilt) and its cross-snapshot memo — see below.

Overlay reconciliation at refresh (read-your-writes-or-newer)

The overlay is carried across refreshes, but no longer unconditionally: each refresh compares every overlay entry against its write-target branch file (one per-entry backend lock — never held across the loop, and no seed lock, so the writable-own → seed lock order can't be violated) and drops the entry when the branch content no longer equals the saved body. That is the cross-replica convergence story: a law saved on this process serves the saved body until someone else (another replica, a direct push) overwrites it on the branch, after which reads converge to the newer branch content within a TTL window — instead of this process pinning its own save forever, which made every cross-replica If-Match save 412 against content the loser could never fetch. A read error keeps the entry (a network blip must not drop a save), and removal is compare-and-remove so a save landing concurrently with the reconcile pass is never dropped.

Bounded, per-snapshot body cache (BODY_CACHE_MAX_ENTRIES = 1024)

The save overlay and the lazy-read cache used to share one unbounded map. They are now split: saves stay in the overlay (bounded by laws edited in the traject, survives refreshes), lazily fetched bodies live in a FIFO-bounded per-snapshot cache that the refresh discards — that is how upstream content changes (not just index changes) converge within the TTL. FIFO instead of LRU keeps cache hits on the cheap read guard; at ~tens of KB per body the cap bounds the cache at low tens of MB per traject.

Implements index: stale-while-revalidate + content-addressed memo

• LoadedLaw now carries display_name and implements, derived once (one shared YAML parse) at load / update_yaml_content time in regelrecht-corpus. The law list reads display_name straight off the entry; the global implementors lookup is an in-memory reverse scan.
• Traject scopes build an implements index on the first lookup of the process — the one O(corpus) body scan. A TTL refresh does not repeat it: the previous index is carried over flagged stale, the first post-refresh lookup rebuilds it under a try_lock (same single-flight pattern as the snapshot refresh) while concurrent lookups keep serving the carried index — the federated implementors hot path (fix(editor): stop scenario dependency-scan request storm + un-gate result buttons #762) never queues behind a rescan again.
• The rebuild itself is content-addressed: the GitHub Trees enumeration's blob shas are now plumbed through regelrecht-corpus onto metadata-only LoadedLaw entries (content_sha), and the editor keeps a cross-snapshot (source_id, blob_sha) → implements memo (shared Arc, like the overlay). A rebuild fetches/parses only bodies whose blob changed; an unchanged corpus rebuilds with zero Contents API calls. Overlay-saved laws are parsed from the overlay body (never memoized under the pre-save sha), loaded (local) laws reuse the corpus-parsed list, and each rebuild swaps the memo wholesale so it stays bounded by the current corpus size. record_save still updates the live index in place.
• Fetch failures during a scan are recorded and reported (the build warns once with skipped/indexed counts; the per-request signal is debug) instead of being indistinguishable from "no implementors"; the failed set is retried at the next rebuild. The response is a bare id array, so there was no non-breaking field for a partiality flag — left as a possible follow-up if the frontend wants to surface it.

Small fix

The global scenario GET leaked raw backend error text via e.to_string(); it now uses the same generic-message/log-details pattern as corpus_write_error.

Possible follow-up

A partial refresh (keep healthy sources' fresh enumeration when one source fails, instead of all-or-nothing serve-stale) would tighten convergence further for multi-source trajects with one flaky seed; deliberately out of scope here.

Tests

• corpus: display-name/implements precompute on local load, fetched files, metadata-only entries (incl. content_sha), and update_yaml_content recompute.
• editor-api lib: body-cache FIFO bound, TTL freshness rule, lazy-fetch caching + overlay precedence, implements-index build/reuse, fetch-failure reporting, record_save in-place index updates, refresh carry-over semantics (shared backends/overlay/changed-cache), SWR (carried index served while a rebuild holds the build lock), memo (unchanged corpus rebuilds with zero fetches; a changed sha refetches only that body), and overlay reconciliation (entry kept while branch == saved body, dropped when the branch moved past the save).
• editor-api integration (traject_reads_test, testcontainers): end-to-end TTL refresh through the real handlers — an upstream-added law appears after the refresh, a fresh save survives it (read-your-writes), and an external overwrite of a saved law converges to the external content instead of being pinned. All 11 tests green.

Note: save_annotations_test and trajects_test do not compile on origin/main either (stale imports like SESSION_KEY_ACTIVE_TRAJECT); untouched here.

just format, just lint, just build-check all green.

[github-actions]

Preview Deployment — harvester-admin

Your changes have been deployed to a preview environment:

URL: https://harvester-admin-pr794-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

[github-actions]

Preview Deployment — harvester-worker

Your changes have been deployed to a preview environment:

URL: https://harvester-worker-pr794-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

[github-actions]

Preview Deployment — enrichworker

Your changes have been deployed to a preview environment:

URL: https://enrichworker-pr794-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.

[github-actions]

Preview Deployment — editor — editor

Your changes have been deployed to a preview environment:

URL: https://editor-pr794-regel-k4c.rig.prd1.gn2.quattro.rijksapps.nl

This deployment will be automatically cleaned up when the PR is closed.