docs(rfc): RFC 0033 drafted — cached template-map artifact

[jensholdgaard]

What

Drafts RFC 0033 — cached template-map artifact, discharging the RFC 0005 §3.7.1 deferral ("a pure recovery/latency cache over this derivation", to be designed when it measurably matters).

The measured justification

RFC 0031 comparative run #8 (honest total-bytes metric) measured the registry derivation at a constant 513,862 bytes per body-rendering query: every query folds the tenant's entire audit stream (read_all_events) before answering. The tax is per-query, grows with tenant age (append-only stream) rather than query selectivity — the inverse of the pruning thesis — and now sits inside the RFC 0031 headline metric.

Design positions (all with alternatives recorded in §4)

• One artifact (template_map.json, registry + alias map together): same stream, same fold order, same validity domain; one frontier check, one atomic publish, no cross-frontier disagreement.
• Location: audit/tenant_id=<enc>/template_map.json (object storage per §3.6, tenant-scoped per §3.7). Verified additive-by-construction: both audit-scan branches select *.parquet only, so every existing reader is blind to it.
• Freshness = frontier set-equality (exact audit-file set folded vs live listing); every non-hit disposition (absent / stale / torn / unknown version / tenant mismatch) falls back to the fresh fold — re-derive, never serve stale. Incremental fold rejected in v1 (an appended file can carry earlier-timestamped events under the §3.7.1 total order); guarded fast path is an §7 open question.
• Atomic publish per the RFC 0009 §3.4 / manifest.rs precedent (.tmp+rename locally, publish_cas conditional-put on S3); a lost CAS race is discard-and-move-on since any published cache is a correct fold of some frontier, verified on every read.
• Writer = querier write-through after a cache-miss derivation, best-effort (publish failure never fails a query).

§5 acceptance criteria (each test-turnable)

cached≡fresh (property-tested), staleness detection both directions, crash/tear safety around the swap, additive/advisory (no artifact → byte-identical behaviour), tenant isolation, the RFC 0031 measurable (warm registry_bytes_read == artifact size; gate warm/cold ≤ 1/10 with run #8's 513,862 B as baseline), and OTel instruments via the weaver registry.

Invariants / hazards

Docs-only. Touches the §3.5/§3.6/§3.7 rule set on paper — the RFC's design is explicitly additive/advisory with the audit stream remaining the sole source of truth. Hazard 5 (template schema evolution): the artifact caches the fold, not new semantics.

Checks run

mdbook build (clean, pre-existing mermaid version warning only), Mermaid sequence diagram visually verified via mermaid-cli render, cargo fmt --all --check (trivially clean — no code).

Status ladder: lands as drafted; drafted → specified is the maintainer's call per docs/rfcs/README.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WQY9wfrfRggqSpMLH8Xj3Y

Summary by CodeRabbit

• Documentation
  • Added RFC 0033, documenting a cached template-map artifact for faster template and alias lookups.
  • Defined cache freshness validation, safe publishing, tenant isolation, failure handling, observability, and testing expectations.
  • Added the RFC to the documentation table of contents.

[coderabbitai]

Warning

Review limit reached

@jensholdgaard, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 52 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c4b581aa-349e-4ad8-bf57-a89cfa6c8ce9

📥 Commits

Reviewing files that changed from the base of the PR and between cca3d71 and e6407bf.

📒 Files selected for processing (1)

• docs/rfcs/0033-cached-template-map.md

📝 Walkthrough

Walkthrough

RFC 0033 documents a per-tenant template_map.json cache combining template registry and alias-map folds, with frontier-based freshness checks, atomic publication, telemetry, compatibility constraints, acceptance criteria, and testing plans.

Changes

Cached template-map design

Layer / File(s)	Summary
Artifact contract and design docs/SUMMARY.md, docs/rfcs/0033-cached-template-map.md	Adds RFC 0033 to the documentation index and defines the cached artifact schema, storage location, derivation, and validity invariants.
Freshness and publication lifecycle docs/rfcs/0033-cached-template-map.md	Specifies cache-hit and stale-miss behavior, invalid-cache handling, atomic publication for local and S3 backends, querier write-through, and back-compatibility constraints.
Observability and acceptance validation docs/rfcs/0033-cached-template-map.md	Defines metrics, evaluates alternatives, and documents acceptance scenarios, testing strategy, open questions, and references.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• jensholdgaard/ourios#264: Defines the read-time template registry that RFC 0033 folds into the cached template-map artifact.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description covers the design and rationale, but it misses the required Summary, Related, and Checklist sections from the template.	Add the template sections with a brief Summary, Related RFC/link, and a completed checklist for fmt, clippy, tests, docs, and RFC link.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and clearly describes the RFC draft for the cached template-map artifact.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rfc-cached-template-map

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Drafts RFC 0033 to introduce a per-tenant cached template_map.json artifact (template registry + alias map) stored alongside the audit parquet files, intended to eliminate the current per-query full audit-stream fold cost while remaining additive/advisory (fallback-to-fresh-fold on any non-hit).

Changes:

• Add new RFC document: RFC 0033 — Cached template-map artifact (design, alternatives, acceptance criteria, testing strategy, open questions, references).
• Register RFC 0033 in the mdBook table of contents (docs/SUMMARY.md).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
docs/SUMMARY.md	Adds RFC 0033 to the RFC list so it appears in the rendered docs book.
docs/rfcs/0033-cached-template-map.md	New RFC defining the cached template-map artifact design and associated acceptance criteria/testing strategy.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/rfcs/0033-cached-template-map.md`:
- Around line 171-178: Revise the “Size bound” section to remove the
unconditional “always strictly smaller” claim and present it as an expected,
measured reduction instead. Define cache abstention when the serialized artifact
exceeds the configured size threshold, while preserving the existing RFC 0023
bounds and noting that warm reads are not guaranteed to reduce bytes.
- Around line 264-268: Change the write-through publication flow described in
the querier cache-miss path so it never publishes a partially populated template
map after registry-only misses. Ensure the miss path obtains both the template
registry and alias map from the same captured scan, or defers publication until
both folds are available, without triggering a second audit scan; preserve
best-effort publication semantics and add an acceptance test covering a
body-rendering query followed by an alias-resolving query.
- Around line 327-330: Resolve the `QueryResult::registry_bytes_read` contract
before changing its accounting: either amend RFC 0031 and the `QueryResult`
documentation to define it as template-map acquisition bytes, or introduce a
separate artifact-byte field while preserving its existing audit-stream meaning.
Update the RFC 0033 cache-hit description and scenario RFC0033.6 so the selected
contract, accounting, and “no channel changes” claim are consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 93eda18d-52d3-492a-8e1d-6d22373adbe7

📥 Commits

Reviewing files that changed from the base of the PR and between 818395d and cca3d71.

📒 Files selected for processing (2)

• docs/SUMMARY.md
• docs/rfcs/0033-cached-template-map.md

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.