feat(querier): RFC 0033 green (artifact) — template_map format + one-scan dual fold

[jensholdgaard]

What

RFC 0033's first green slice: the artifact format + one-scan dual fold, discharging scenario RFC0033.1 (cached fold ≡ fresh fold, property-tested).

• TemplateMapJson wire format (manifest.rs house style): canonical-sorted folded_files frontier (tenant-root-relative, validated against ../absolute/foreign names so a hostile artifact cannot point outside the tenant subtree), registry entries in the miner's canonical format_template form (the exact representation the audit stream stores — no second token encoding), alias classes canonical (ascending members, min-representative).
• §3.3 dispositions implemented: two-pass parse so a future-version artifact classifies UnknownVersion (not Torn); parse/validation failures → Torn { detail }; both treated-as-absent by callers and distinguishable for the §3.7 telemetry slice; body-tenant mismatch fails loudly (row-vs-path stance).
• No-partial-artifact at the type level (§3.5 rule): TemplateMap has private fields and exactly two constructors — derive_template_map (ONE read_all_events_captured scan, both folds from the captured events + the frontier from the same listing) and from_json. A one-fold or split-frontier artifact is unrepresentable.
• RFC0033.1 green: proptest over generated audit histories (tie-heavy timestamps, all event kinds), flushed through the production ParquetAuditSink one file per event so the §3.7.1 cross-file order is exercised; asserts registry, alias classes, frontier, and end-to-end resolves_to answers identical between cached and fresh folds. Six stubs stay red.

Invariants / hazards

Hazard 5 adjacency (template evolution): the artifact caches the fold, not new semantics; the audit stream remains the source of truth (nothing reads the artifact yet — read-path wiring is the freshness + write-through slice). read_all_events delegates to the new captured variant with byte-identical behavior for existing folds.

Checks run

cargo fmt --all --check, cargo clippy --all-targets --all-features -- -D warnings (workspace-wide), cargo nextest run -p ourios-querier -p ourios-core -p ourios-bench (386 passed, 16 skipped) — re-verified after rebase onto the merged red.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WQY9wfrfRggqSpMLH8Xj3Y

Summary by CodeRabbit

• New Features

  • Added support for generating and serializing a tenant template map containing template registry data, alias classes, and the audit files used to build them.
  • Added validation and clear handling for valid, corrupted, or unsupported template map artifacts.
  • Added alias class export and reconstruction capabilities.
  • Added tenant isolation checks and deterministic audit file tracking.

• Tests

  • Added round-trip, validation, corruption handling, and end-to-end coverage for cached template maps.

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 21 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: 59d8c12d-ea2b-4dad-bcf4-479bf99c703d

📥 Commits

Reviewing files that changed from the base of the PR and between 1b43a2f and 3f76476.

📒 Files selected for processing (2)

• crates/ourios-querier/src/audit_scan.rs
• crates/ourios-querier/src/template_map.rs

📝 Walkthrough

Walkthrough

Adds RFC 0033.1 cached template-map artifacts containing registry and alias folds plus audit frontiers. It introduces canonical JSON read/write validation, captured audit scanning, alias projection APIs, public exports, and property-based integration coverage.

Changes

Cached template map artifact

Layer / File(s)	Summary
Alias projection APIs crates/ourios-core/src/alias.rs	Adds canonical alias-class extraction and reconstruction, ignoring empty and singleton classes.
Captured audit frontier crates/ourios-querier/src/audit_scan.rs, crates/ourios-querier/src/alias_store.rs	Captures deterministic tenant-relative audit frontiers alongside folded events and bytes read, with documented storage errors.
Template map derivation and JSON crates/ourios-querier/src/template_map.rs, crates/ourios-querier/src/template_registry.rs	Derives registry and alias folds from one scan, serializes canonical JSON, distinguishes torn artifacts from unknown versions, and validates tenant, ordering, alias, registry, and frontier invariants.
Public API and property coverage crates/ourios-querier/src/lib.rs, crates/ourios-querier/tests/it/rfc0033_cached_template_map.rs	Exports the new APIs and adds generated end-to-end checks comparing cached artifacts with fresh folds and query results.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Querier
  participant AuditStore
  participant TemplateMap
  participant AliasMap
  Querier->>AuditStore: scan tenant audit files
  AuditStore-->>Querier: events, bytes_read, folded_files
  Querier->>AliasMap: fold alias events
  Querier->>TemplateMap: combine registry, aliases, and frontier
  TemplateMap-->>Querier: serialize or validate artifact JSON

Loading

Possibly related PRs

• jensholdgaard/ourios#153: Extends the same per-tenant AliasMap model used by the new projection APIs.
• jensholdgaard/ourios#274: Adds the template registry derivation path used by the new artifact.
• jensholdgaard/ourios#484: Specifies the cached template_map.json behavior implemented here.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is informative, but it does not use the required Summary/Related/Checklist template and omits the RFC link and checklist items.	Rewrite it with ## Summary, ## Related (including the RFC/issue link), and ## Checklist entries for fmt, clippy, tests, docs, and RFC linkage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: RFC 0033 template_map artifact work and one-scan dual-fold derivation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 rfc0033-green-artifact

---

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

Implements the first “green” slice of RFC 0033 for the querier by introducing a cached per-tenant template-map artifact format and a one-scan derivation path that folds both the template registry and alias map from a single captured audit scan, plus a property test for scenario RFC0033.1.

Changes:

• Adds TemplateMap + ArtifactRead with JSON serialization/deserialization, canonicalization, and validation rules.
• Extends audit scanning with read_all_events_captured to return a frontier (folded_files) consistent with the folded events.
• Adds alias-class projection/rebuild helpers (AliasMap::{classes, from_classes}) and a proptest-based integration test for cached-vs-fresh fold equivalence.

Reviewed changes

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

Show a summary per file

File	Description
crates/ourios-querier/tests/it/rfc0033_cached_template_map.rs	Replaces RFC0033.1 stub with a property test comparing derived vs artifact-carried folds and frontier.
crates/ourios-querier/src/template_registry.rs	Exposes fold_registry at pub(crate) for reuse by template-map derivation.
crates/ourios-querier/src/template_map.rs	New module defining the artifact wire format, derivation, and read dispositions/validation.
crates/ourios-querier/src/lib.rs	Wires in the new module and re-exports TemplateMap/ArtifactRead/derive_template_map (+ derive_alias_map).
crates/ourios-querier/src/audit_scan.rs	Adds captured scans with frontier and refactors read_all_events to delegate to it.
crates/ourios-querier/src/alias_store.rs	Makes derive_alias_map public and documents error semantics.
crates/ourios-core/src/alias.rs	Adds canonical classes() projection and from_classes() inverse + tests.

---

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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