diff --git a/crates/ourios-querier/src/alias_store.rs b/crates/ourios-querier/src/alias_store.rs index 36f835a15..13b3cde5e 100644 --- a/crates/ourios-querier/src/alias_store.rs +++ b/crates/ourios-querier/src/alias_store.rs @@ -16,9 +16,10 @@ //! The derived map reflects exactly the alias events durably flushed //! to the audit stream at scan time — the RFC 0001 §6.7 //! eventual-consistency stance, with the staleness window being -//! audit-flush visibility. A future materialized per-tenant cache -//! (the RFC 0009 §3.4 manifest fork) would accelerate, not change, -//! this derivation. +//! audit-flush visibility. The RFC 0033 cached template map +//! accelerates this derivation at the query call sites (an +//! exactly-fresh artifact skips the scan); this fold remains the +//! semantics owner and the fallback for every non-hit disposition. use ourios_core::alias::AliasMap; use ourios_core::audit::AuditPayload; diff --git a/crates/ourios-querier/src/audit_scan.rs b/crates/ourios-querier/src/audit_scan.rs index 779a8994e..5ab318996 100644 --- a/crates/ourios-querier/src/audit_scan.rs +++ b/crates/ourios-querier/src/audit_scan.rs @@ -124,6 +124,160 @@ pub(crate) struct CapturedScan { pub(crate) frontier: Vec, } +/// A resolved audit file set **plus** its frontier, from **one** listing — +/// the RFC 0033 §3.3 ordering requirement (LIST-before-GET-is-compared) +/// made structural: the freshness comparison and the fallback fold consume +/// this same listing, so a file appearing mid-query affects a cached and an +/// uncached query identically. The remote variant carries its [`Store`] +/// borrow, so a resolved set can never be read against the wrong backend. +pub(crate) enum ResolvedAuditSet<'a> { + Local { + /// Absolute, canonical local file paths (lexicographically sorted, + /// unique — [`local_audit_files`]'s output). + paths: Vec, + frontier: Vec, + }, + Remote { + store: &'a Store, + /// Store-relative object keys (lexicographically sorted, unique). + keys: Vec, + frontier: Vec, + }, +} + +/// Resolve `tenant`'s live audit `*.parquet` set together with its frontier +/// — the single LIST both the RFC 0033 §3.3 freshness check and the fold +/// consume. A tenant with no audit files is an empty set, not an error. +pub(crate) fn resolve_audit_set<'a>( + backend: StoreRef<'a>, + tenant: &TenantId, +) -> Result, QueryError> { + match backend { + StoreRef::Local(root) => { + let paths = local_audit_files(root, tenant, None)?; + // The canonical tenant root every file was validated against — + // recomputed only when there are files, so an absent tree stays + // a valid empty scan — relativizes the frontier the same way + // the S3 branch's keys already are. + let mut frontier = Vec::with_capacity(paths.len()); + if !paths.is_empty() { + let tenant_root = canonical_tenant_root(root, tenant)?; + for path in &paths { + frontier.push(tenant_relative(path, &tenant_root)?); + } + } + frontier.sort_unstable(); + Ok(ResolvedAuditSet::Local { paths, frontier }) + } + StoreRef::Remote(store) => { + let enc = percent_encode_tenant(tenant.as_str()); + let prefix = format!("audit/tenant_id={enc}/"); + let keys = remote_audit_files(store, tenant, None)?; + // The listing is prefix-scoped, so the strip always applies; + // keeping the full key on a (can't-happen) miss stays + // consistent for set-equality as long as both sides use this + // same rule. + let mut frontier: Vec = keys + .iter() + .map(|key| key.strip_prefix(&prefix).unwrap_or(key).to_owned()) + .collect(); + frontier.sort_unstable(); + Ok(ResolvedAuditSet::Remote { + store, + keys, + frontier, + }) + } + } +} + +impl ResolvedAuditSet<'_> { + /// The frontier: the resolved audit `*.parquet` set as tenant-root- + /// relative keys, sorted lexicographically — the right-hand side of the + /// RFC 0033 §3.3 set-equality freshness check. + pub(crate) fn frontier(&self) -> &[String] { + match self { + Self::Local { frontier, .. } | Self::Remote { frontier, .. } => frontier, + } + } + + /// Read every [`AuditEvent`] from this resolved set, in the §3.7.1 fold + /// order, applying the **row-level tenant backstop** (`CLAUDE.md` §3.7 / + /// RFC 0005 §3.9 row-vs-path): the listing/walk is already + /// tenant-scoped, so a row claiming another tenant is a corrupt or + /// foreign file — fail loudly rather than fold (or silently drop) it. A + /// local file is read with [`AuditReader::open_file`], an S3 key via + /// [`Store::get_blocking`] → [`AuditReader::open_bytes`]. + /// + /// Also returns (in the [`CapturedScan`]) the **bytes fetched** reading + /// the set (RFC 0031 §3.6). The remote branch pays a full-object GET + /// per key, so the local branch counts each file's length to keep the + /// two backends' figures equal for identical data. + pub(crate) fn read_events(self, tenant: &TenantId) -> Result { + let mut bytes_read: u64 = 0; + let mut events: Vec = Vec::new(); + let mut push_validated = |label: &str, read: Vec| -> Result<(), QueryError> { + for event in read { + if event.tenant_id != *tenant { + return Err(QueryError::Storage { + detail: format!( + "audit file {label} carries a row for tenant {} under tenant {}'s \ + partition root", + event.tenant_id.as_str(), + tenant.as_str(), + ), + }); + } + events.push(event); + } + Ok(()) + }; + let frontier = match self { + Self::Local { paths, frontier } => { + for path in &paths { + let len = std::fs::metadata(path) + .map_err(|e| QueryError::Storage { + detail: format!("audit file metadata {}: {e}", path.display()), + })? + .len(); + bytes_read = add_measured(bytes_read, len)?; + let read = AuditReader::open_file(path) + .and_then(AuditReader::read_all) + .map_err(|e| QueryError::Storage { + detail: format!("audit file {}: {e}", path.display()), + })?; + push_validated(&path.display().to_string(), read)?; + } + frontier + } + Self::Remote { + store, + keys, + frontier, + } => { + for key in &keys { + let bytes = store.get_blocking(key).map_err(|e| QueryError::Storage { + detail: format!("audit file {key}: {e}"), + })?; + bytes_read = add_measured(bytes_read, bytes.len() as u64)?; + let read = AuditReader::open_bytes(bytes::Bytes::from(bytes)) + .and_then(AuditReader::read_all) + .map_err(|e| QueryError::Storage { + detail: format!("audit file {key}: {e}"), + })?; + push_validated(key, read)?; + } + frontier + } + }; + Ok(CapturedScan { + events, + bytes_read, + frontier, + }) + } +} + /// Read every [`AuditEvent`] from `tenant`'s resolved audit file set (the /// `None`-window full history), in the §3.7.1 fold order, applying the /// **row-level tenant backstop** (`CLAUDE.md` §3.7 / RFC 0005 §3.9 row-vs-path): @@ -152,82 +306,7 @@ pub(crate) fn read_all_events_captured( backend: StoreRef<'_>, tenant: &TenantId, ) -> Result { - let mut bytes_read: u64 = 0; - let mut events: Vec = Vec::new(); - let mut frontier: Vec = Vec::new(); - let mut push_validated = |label: &str, read: Vec| -> Result<(), QueryError> { - for event in read { - if event.tenant_id != *tenant { - return Err(QueryError::Storage { - detail: format!( - "audit file {label} carries a row for tenant {} under tenant {}'s \ - partition root", - event.tenant_id.as_str(), - tenant.as_str(), - ), - }); - } - events.push(event); - } - Ok(()) - }; - match backend { - StoreRef::Local(root) => { - let files = local_audit_files(root, tenant, None)?; - // The canonical tenant root `local_audit_files` validated every - // file against — recomputed here (only when there are files, so - // an absent tree stays a valid empty scan) to relativize the - // frontier the same way the S3 branch's keys already are. - let tenant_root = match files.first() { - Some(_) => Some(canonical_tenant_root(root, tenant)?), - None => None, - }; - for path in &files { - let len = std::fs::metadata(path) - .map_err(|e| QueryError::Storage { - detail: format!("audit file metadata {}: {e}", path.display()), - })? - .len(); - bytes_read = add_measured(bytes_read, len)?; - let read = AuditReader::open_file(path) - .and_then(AuditReader::read_all) - .map_err(|e| QueryError::Storage { - detail: format!("audit file {}: {e}", path.display()), - })?; - push_validated(&path.display().to_string(), read)?; - if let Some(tenant_root) = &tenant_root { - frontier.push(tenant_relative(path, tenant_root)?); - } - } - } - StoreRef::Remote(store) => { - let enc = percent_encode_tenant(tenant.as_str()); - let prefix = format!("audit/tenant_id={enc}/"); - for key in &remote_audit_files(store, tenant, None)? { - let bytes = store.get_blocking(key).map_err(|e| QueryError::Storage { - detail: format!("audit file {key}: {e}"), - })?; - bytes_read = add_measured(bytes_read, bytes.len() as u64)?; - let read = AuditReader::open_bytes(bytes::Bytes::from(bytes)) - .and_then(AuditReader::read_all) - .map_err(|e| QueryError::Storage { - detail: format!("audit file {key}: {e}"), - })?; - push_validated(key, read)?; - // The listing is prefix-scoped, so the strip always applies; - // keeping the full key on a (can't-happen) miss stays - // consistent for set-equality as long as both sides use - // this same rule. - frontier.push(key.strip_prefix(&prefix).unwrap_or(key).to_owned()); - } - } - } - frontier.sort_unstable(); - Ok(CapturedScan { - events, - bytes_read, - frontier, - }) + resolve_audit_set(backend, tenant)?.read_events(tenant) } /// The canonical `audit/tenant_id=` root under `bucket_root` — the same diff --git a/crates/ourios-querier/src/lib.rs b/crates/ourios-querier/src/lib.rs index 4bcfc326d..c4a1fac1c 100644 --- a/crates/ourios-querier/src/lib.rs +++ b/crates/ourios-querier/src/lib.rs @@ -51,8 +51,8 @@ pub use audit_scan::StoreRef; pub use drift::{DriftResult, DriftRow}; pub use log_row::{LogBody, LogRow, render_log_body}; pub use template_map::{ - ArtifactRead, PublishOutcome, TEMPLATE_MAP_FILENAME, TEMPLATE_MAP_FORMAT_VERSION, TemplateMap, - derive_template_map, + ArtifactRead, CacheOutcome, MissReason, PublishOutcome, TEMPLATE_MAP_FILENAME, + TEMPLATE_MAP_FORMAT_VERSION, TemplateMap, derive_template_map, load_or_derive, }; pub use template_registry::{TemplateRegistry, derive_template_registry}; @@ -197,10 +197,16 @@ pub struct QueryResult { /// metrics depend on that semantics) — a caller wanting the honest /// total IO for one query sums the three components. pub materialize_bytes_read: u64, - /// Bytes fetched from the tenant's audit stream deriving the read-time - /// template registry that rendered the returned `records` (RFC 0017 - /// §3.2 / RFC 0031 §3.6). `0` when no rows were rendered. Same additive - /// contract as `materialize_bytes_read`. + /// **Template-map acquisition bytes** (RFC 0033 §3.6, amending the + /// pre-0033 audit-stream-only meaning): the total bytes fetched to + /// obtain the body-rendering capability behind the returned `records`, + /// whatever the source — the audit-stream fold on a cache miss + /// (byte-for-byte the pre-0033 RFC 0017 §3.2 registry derivation) or + /// the `template_map.json` artifact GET on a cache hit. One + /// per-query acquisition serves both the registry and, for + /// `resolves_to` queries, the alias map. `0` when no rows were + /// rendered. Same additive contract as `materialize_bytes_read` + /// (RFC 0031 §3.6). pub registry_bytes_read: u64, } @@ -650,6 +656,18 @@ struct CollectedRecords { registry_bytes_read: u64, } +/// One per-query template-map acquisition (RFC 0033): the artifact-or-fold +/// [`TemplateMap`] plus the bytes fetched acquiring it +/// ([`QueryResult::registry_bytes_read`]). Acquired at most once per query +/// — at compile time when the DSL uses `resolves_to` (the alias fold), +/// otherwise lazily by [`Querier::collect_records`] when there are rows to +/// render — so the alias map and the registry can never come from +/// different frontiers within one query (§3.1's one-artifact rationale). +struct AcquiredTemplateMap { + map: TemplateMap, + acquisition_bytes: u64, +} + impl Querier { /// Create a querier reading the RFC 0005 store under the **local** /// `bucket_root` (the same root the `ourios-parquet` writer writes @@ -707,9 +725,14 @@ impl Querier { let tenant = request.tenant.clone(); let window = request.time_range; let row_limit = request.limit; - self.execute(&tenant, window, row_limit, QueryOptions::default(), |df| { - apply_request_filters(df, &request) - }) + self.execute( + &tenant, + window, + row_limit, + QueryOptions::default(), + None, + |df| apply_request_filters(df, &request), + ) .await } @@ -727,9 +750,11 @@ impl Querier { /// unbounded scan). /// /// `alias_map` selects where the RFC 0001 §6.7 alias projection comes - /// from. `None` — the production default — derives the requesting - /// tenant's map from its audit stream at compile time per RFC 0005 - /// §3.7.1 (the audit stream is the alias store in v1; the scan is + /// from. `None` — the production default — resolves the requesting + /// tenant's map at compile time per RFC 0005 §3.7.1 through the + /// RFC 0033 cached template map (the audit stream stays the source of + /// truth: an artifact hit reflects exactly the fresh fold, and every + /// non-hit disposition *is* the fresh fold; the acquisition is /// skipped entirely when the query has no `resolves_to`). /// `Some(map)` injects a caller-held projection instead — the /// test/operator override, bypassing storage. Either way, @@ -788,22 +813,34 @@ impl Querier { // pure validation internally — one source of truth, negligible // cost. compile::validate(query, now_unix_nano, default_window_nanos)?; + let mut acquired: Option = None; let derived; let map = match alias_map { Some(map) => map, None if compile::uses_resolves_to(&query.predicate) => { - // Offload the blocking audit derivation (S3 `get_blocking` / - // the local `std::fs` reads) off the runtime worker, mirroring - // `run_drift` — the derivation is deeply sync, so clone the - // cheap backend handle into the blocking task. - derived = self + // The alias fold comes from the cached template map + // (RFC 0033): artifact hit or fresh fold + write-through. + // Offload the blocking IO (S3 GETs / the local `std::fs` + // reads) off the runtime worker, mirroring `run_drift` — + // the derivation is deeply sync, so clone the cheap + // backend handle into the blocking task. The acquired map + // is handed down to the row-rendering pass, so the alias + // map and the registry share one acquisition (and one + // frontier) per query. + let (template_map, acquisition_bytes, _outcome) = self .spawn_blocking_audit({ let backend = self.backend.clone(); let tenant = tenant.clone(); - move || alias_store::derive_alias_map(backend.store_ref(), &tenant) + move || template_map::load_or_derive(backend.store_ref(), &tenant) }) .await?; - &derived + acquired + .insert(AcquiredTemplateMap { + map: template_map, + acquisition_bytes, + }) + .map + .alias_map() } // No `resolves_to` ⇒ the map is never consulted; an empty // projection avoids the audit-tree scan. @@ -816,9 +853,14 @@ impl Querier { // The DSL `limit` (RFC 0002) doubles as the RFC 0017 row cap; read it // before `plan` moves into the filter closure. let row_limit = plan.limit; - self.execute(tenant, Some(plan.window), row_limit, options, move |df| { - compile::apply(df, plan) - }) + self.execute( + tenant, + Some(plan.window), + row_limit, + options, + acquired, + move |df| compile::apply(df, plan), + ) .await } @@ -891,6 +933,11 @@ impl Querier { // limited result. row_limit: Option, query_options: QueryOptions, + // A template map already acquired at query-compile time (the + // `resolves_to` alias fold, RFC 0033) — handed to the row-rendering + // pass so one acquisition serves both folds. `None` ⇒ rendering + // acquires lazily. + mut acquired: Option, build_filter: F, ) -> Result where @@ -976,7 +1023,7 @@ impl Querier { && query_options.elide_count_scan { let collected = self - .collect_records(df.clone(), n, tenant, ctx.task_ctx()) + .collect_records(df.clone(), n, tenant, ctx.task_ctx(), acquired.take()) .await?; if collected.records.len() < n { return Ok(QueryResult { @@ -1019,7 +1066,10 @@ impl Querier { // truncated single-pass run already materialised — reuse it. let collected = match (early, row_limit) { (Some(collected), _) => collected, - (None, Some(n)) => self.collect_records(df, n, tenant, ctx.task_ctx()).await?, + (None, Some(n)) => { + self.collect_records(df, n, tenant, ctx.task_ctx(), acquired.take()) + .await? + } (None, None) => CollectedRecords::default(), }; Ok(QueryResult { @@ -1033,16 +1083,20 @@ impl Querier { /// Materialise up to `limit` matching rows from the filtered `df`, decode /// them, and render each into a [`LogRow`] (RFC 0017 §3.3). The template - /// registry is derived once (from the tenant's audit stream) only when - /// there are rows to render. Returns the rows plus this pass's own IO - /// accounting (RFC 0031 §3.6), kept out of [`QueryStats`] so the - /// count-scan figures B1/B2 assert on stay exactly the count scan. + /// map is acquired once — reusing `acquired` when the query-compile + /// alias fold already paid for it, otherwise through the RFC 0033 + /// cached read path (artifact hit, or fresh fold + write-through) — + /// and only when there are rows to render. Returns the rows plus this + /// pass's own IO accounting (RFC 0031 §3.6), kept out of + /// [`QueryStats`] so the count-scan figures B1/B2 assert on stay + /// exactly the count scan. async fn collect_records( &self, df: datafusion::dataframe::DataFrame, limit: usize, tenant: &TenantId, task_ctx: Arc, + acquired: Option, ) -> Result { // Filter pushdown ("late materialization", off by default in // DataFusion 54): the scan evaluates the predicate during Parquet @@ -1125,27 +1179,36 @@ impl Querier { }); } } - // The single registry derivation, measured (RFC 0031 §3.6) — the - // same blocking-pool offload as [`Self::template_registry`]. - let (registry, registry_bytes_read) = self - .spawn_blocking_audit({ - let backend = self.backend.clone(); - let tenant = tenant.clone(); - move || { - template_registry::derive_template_registry_measured( - backend.store_ref(), - &tenant, - ) - } - }) - .await?; + // The single per-query template-map acquisition, measured + // (RFC 0031 §3.6 / RFC 0033): reuse the compile-time alias fold's + // map when the query already acquired one, else resolve through + // the cached read path — the same blocking-pool offload as + // [`Self::template_registry`]. + let AcquiredTemplateMap { + map, + acquisition_bytes, + } = if let Some(acquired) = acquired { + acquired + } else { + let (map, acquisition_bytes, _outcome) = self + .spawn_blocking_audit({ + let backend = self.backend.clone(); + let tenant = tenant.clone(); + move || template_map::load_or_derive(backend.store_ref(), &tenant) + }) + .await?; + AcquiredTemplateMap { + map, + acquisition_bytes, + } + }; Ok(CollectedRecords { records: mined .iter() - .map(|record| LogRow::from_record(record, ®istry)) + .map(|record| LogRow::from_record(record, map.registry())) .collect(), scan, - registry_bytes_read, + registry_bytes_read: acquisition_bytes, }) } diff --git a/crates/ourios-querier/src/template_map.rs b/crates/ourios-querier/src/template_map.rs index 922e5d6de..0c776020c 100644 --- a/crates/ourios-querier/src/template_map.rs +++ b/crates/ourios-querier/src/template_map.rs @@ -15,8 +15,10 @@ //! registry-at-frontier-F1 / alias-map-at-F2 split is unrepresentable. //! [`TemplateMap::publish`] commits the artifact atomically (tmp+rename //! locally, conditional put on the store — §3.4, the RFC 0009 manifest -//! precedent); the freshness check (§3.3) and the write-through are the -//! follow-up slices. +//! precedent). [`load_or_derive`] is the cached read path the query +//! layer consumes: one listing, the §3.3 frontier check, fallback to +//! the fresh fold on every non-hit disposition, and the §3.5 +//! best-effort write-through. //! //! JSON follows the `manifest.json` precedent //! (`ourios_parquet::Manifest`, RFC 0009 §3.4): small, human- @@ -103,18 +105,195 @@ pub enum PublishOutcome { LostRace, } +/// Why a [`load_or_derive`] lookup missed — the RFC 0033 §3.3 +/// dispositions that resolve to the fresh fold, distinguished for the +/// §3.7 lookup-outcome telemetry. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[non_exhaustive] +pub enum MissReason { + /// No artifact under the tenant's audit root. + Absent, + /// Torn: unreadable, unparseable, or internally invalid artifact — + /// treated as absent. A parsed-but-invalid artifact is overwritten + /// by the write-through at its observed `ETag` (the store + /// self-heals); a failed GET observes no `ETag`, so on the remote + /// backend its publish is create-only and the heal waits for a + /// readable fetch — the fold answers the query either way. + Torn, + /// A future writer's `format_version` — treated as absent (forward + /// compatibility), republished at this reader's version. + UnknownVersion, +} + +/// Outcome of one [`load_or_derive`] lookup (RFC 0033 §3.3/§3.7). Every +/// variant's answer is correct — the outcome distinguishes what IO paid +/// for it, never what was served. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[non_exhaustive] +pub enum CacheOutcome { + /// The artifact's frontier equals the live listing: served from the + /// artifact, zero audit GETs. + Hit, + /// No usable artifact (§3.3 dispositions): fresh fold, + /// write-through. + Miss { + /// The disposition that voided the artifact. + reason: MissReason, + }, + /// A valid artifact at a different frontier — never served (§3.3: + /// re-derive, never serve stale): fresh fold over the live listing, + /// write-through republish at the new frontier. + StaleRefreshed, +} + +/// The cached read path (RFC 0033 §3.3/§3.5): resolve `tenant`'s +/// [`TemplateMap`] through the published artifact when it is exactly +/// fresh, and by the fresh fold — today's behaviour, then a best-effort +/// write-through publish — on **every** other disposition. +/// +/// IO per outcome (the freshness LIST is never byte-counted, matching +/// both backends' existing accounting): +/// +/// - [`CacheOutcome::Hit`] — one LIST (the live frontier) + one GET +/// (the artifact); **zero** audit GETs. Acquisition bytes = the +/// artifact GET's bytes. +/// - [`CacheOutcome::Miss`] — one LIST + one artifact GET that found +/// nothing usable + the full audit fold over that same listing + one +/// best-effort publish. Acquisition bytes = the fold's audit bytes, +/// plus the failed GET's bytes if it returned any (torn / unknown +/// version). +/// - [`CacheOutcome::StaleRefreshed`] — as a miss, with the stale +/// artifact's GET bytes counted (they were fetched and discarded). +/// +/// The listing is taken **once**, before the artifact GET is compared, +/// and the fallback fold consumes that same listing (§3.3's +/// LIST-before-GET-is-compared rule), so a file appearing mid-query +/// affects a cached and an uncached query identically. +/// +/// The write-through publishes the fold it already holds at the frontier +/// it already listed — both folds, never a partial artifact (§3.5) — +/// with the CAS expectation observed by this read (the artifact's `ETag`, +/// or create-if-absent). A publish failure or lost race is never a query +/// failure; it abstains entirely when the serialized artifact would not +/// be smaller than the audit bytes just folded (§3.2 — nothing to win, +/// and the no-artifact path is today's behaviour). +/// +/// # Errors +/// +/// [`QueryError::Storage`] as [`derive_template_map`], and when a +/// fetched artifact's body `tenant_id` differs from `tenant` (the +/// row-vs-path stance — a loud failure, not a fresh-fold fallback). +pub fn load_or_derive( + backend: StoreRef<'_>, + tenant: &TenantId, +) -> Result<(TemplateMap, u64, CacheOutcome), QueryError> { + let resolved = audit_scan::resolve_audit_set(backend, tenant)?; + let (fetched_bytes, expected, outcome) = match fetch_artifact(backend, tenant) { + FetchedArtifact::Absent => ( + 0, + None, + CacheOutcome::Miss { + reason: MissReason::Absent, + }, + ), + FetchedArtifact::Unreadable => ( + 0, + None, + CacheOutcome::Miss { + reason: MissReason::Torn, + }, + ), + FetchedArtifact::Present { bytes, e_tag } => { + let len = bytes.len() as u64; + match TemplateMap::from_json(&bytes, tenant)? { + ArtifactRead::Valid(map) if map.folded_files() == resolved.frontier() => { + return Ok((map, len, CacheOutcome::Hit)); + } + ArtifactRead::Valid(_) => (len, e_tag, CacheOutcome::StaleRefreshed), + ArtifactRead::Torn { .. } => ( + len, + e_tag, + CacheOutcome::Miss { + reason: MissReason::Torn, + }, + ), + ArtifactRead::UnknownVersion { .. } => ( + len, + e_tag, + CacheOutcome::Miss { + reason: MissReason::UnknownVersion, + }, + ), + } + } + }; + let (map, fold_bytes) = fold_template_map(resolved, tenant)?; + let acquisition_bytes = + fold_bytes + .checked_add(fetched_bytes) + .ok_or_else(|| QueryError::Storage { + detail: format!( + "template-map acquisition bytes overflow u64 (fold={fold_bytes}, \ + artifact={fetched_bytes})" + ), + })?; + map.write_through(backend, expected.as_deref(), fold_bytes); + Ok((map, acquisition_bytes, outcome)) +} + +/// One GET of `tenant`'s artifact, classified. Infallible by design: a +/// failed (non-not-found) GET is `Unreadable` — RFC 0033 §1 pins that an +/// unreadable artifact is *bypassed* (the fresh fold is always a correct +/// answer), never a query failure the audit fold wouldn't itself hit. +enum FetchedArtifact { + Absent, + Unreadable, + Present { + bytes: Vec, + /// The `ETag` observed (S3 backend) — the CAS expectation a + /// write-through publish carries. `None` on the local backend + /// (its publish is last-writer-wins, §3.4). + e_tag: Option, + }, +} + +fn fetch_artifact(backend: StoreRef<'_>, tenant: &TenantId) -> FetchedArtifact { + let enc = percent_encode_tenant(tenant.as_str()); + match backend { + StoreRef::Local(root) => { + let path = root + .join("audit") + .join(format!("tenant_id={enc}")) + .join(TEMPLATE_MAP_FILENAME); + match std::fs::read(&path) { + Ok(bytes) => FetchedArtifact::Present { bytes, e_tag: None }, + Err(e) if e.kind() == std::io::ErrorKind::NotFound => FetchedArtifact::Absent, + Err(_) => FetchedArtifact::Unreadable, + } + } + StoreRef::Remote(store) => { + let key = format!("audit/tenant_id={enc}/{TEMPLATE_MAP_FILENAME}"); + match store.get_with_etag_blocking_opt(&key) { + Ok(Some((bytes, e_tag))) => FetchedArtifact::Present { bytes, e_tag }, + Ok(None) => FetchedArtifact::Absent, + Err(_) => FetchedArtifact::Unreadable, + } + } + } +} + /// Fold `tenant`'s [`TemplateMap`] from its audit stream — **one** -/// `audit_scan::read_all_events_captured` pass, both folds from the -/// captured events (RFC 0033 §3.5: the marginal cost of the second fold -/// is CPU over in-memory events, zero extra IO), and the frontier taken -/// from that same scan. Also returns the **bytes fetched** deriving it -/// (RFC 0031 §3.6 — on a cache miss this is exactly what template-map -/// acquisition cost). +/// `audit_scan` listing + read pass, both folds from the captured events +/// (RFC 0033 §3.5: the marginal cost of the second fold is CPU over +/// in-memory events, zero extra IO), and the frontier taken from that +/// same scan. Also returns the **bytes fetched** deriving it (RFC 0031 +/// §3.6 — on a cache miss this is exactly what template-map acquisition +/// cost). /// /// Each fold is byte-for-byte the fresh derivation it caches: -/// the registry filter + `template_registry::fold_registry` matches +/// the registry filter + `fold_registry` matches /// [`crate::derive_template_registry`], and the alias filter + stable -/// timestamp sort + [`AliasMap::from_events`] matches +/// timestamp sort + `AliasMap::from_events` matches /// [`crate::derive_alias_map`] (RFC0033.1 pins this by property test). /// /// # Errors @@ -127,7 +306,18 @@ pub fn derive_template_map( backend: StoreRef<'_>, tenant: &TenantId, ) -> Result<(TemplateMap, u64), QueryError> { - let scan = audit_scan::read_all_events_captured(backend, tenant)?; + fold_template_map(audit_scan::resolve_audit_set(backend, tenant)?, tenant) +} + +/// [`derive_template_map`] from a pre-resolved audit set — the fallback +/// arm of [`load_or_derive`], which must fold the **same** listing its +/// freshness comparison used (RFC 0033 §3.3: one listing, taken once, +/// for both). +fn fold_template_map( + resolved: audit_scan::ResolvedAuditSet<'_>, + tenant: &TenantId, +) -> Result<(TemplateMap, u64), QueryError> { + let scan = resolved.read_events(tenant)?; let mut alias_events: Vec<&AuditEvent> = scan .events @@ -378,6 +568,42 @@ impl TemplateMap { let bytes = self.to_json().map_err(|e| QueryError::Storage { detail: format!("serialize {TEMPLATE_MAP_FILENAME}: {e}"), })?; + self.publish_bytes(backend, expected, bytes) + } + + /// The RFC 0033 §3.5 write-through: publish this fresh fold + /// best-effort after a cache miss. Never fails the caller — a + /// serialization or backend failure and a lost race are all + /// telemetry-only outcomes (the §3.7 slice) — and **abstains** when + /// the serialized artifact would not be smaller than + /// `folded_audit_bytes`, the audit bytes the fold just read (§3.2: + /// nothing to win; on a tiny or empty tenant the JSON envelope can + /// exceed the stream it caches, and the no-artifact path is exactly + /// today's behaviour). + fn write_through( + &self, + backend: StoreRef<'_>, + expected: Option<&str>, + folded_audit_bytes: u64, + ) { + let Ok(bytes) = self.to_json() else { + return; + }; + if bytes.len() as u64 >= folded_audit_bytes { + return; + } + // Best-effort by contract: Published and LostRace are both fine, + // and an error must not fail the query answered from the fold in + // hand. + let _ = self.publish_bytes(backend, expected, bytes); + } + + fn publish_bytes( + &self, + backend: StoreRef<'_>, + expected: Option<&str>, + bytes: Vec, + ) -> Result { let enc = percent_encode_tenant(self.tenant.as_str()); match backend { StoreRef::Local(root) => { diff --git a/crates/ourios-querier/src/template_registry.rs b/crates/ourios-querier/src/template_registry.rs index 45b55cfb4..37e315152 100644 --- a/crates/ourios-querier/src/template_registry.rs +++ b/crates/ourios-querier/src/template_registry.rs @@ -1,12 +1,14 @@ //! v1 reader-side template-registry derivation (RFC 0017 §3.2). //! -//! There is **no persisted per-tenant template-registry artifact** in v1 -//! (the cached map is the deferred RFC 0005 §3.7.1 / manifest-fork -//! optimisation): the audit stream *is* the registry, and the querier -//! derives the requesting tenant's `(template_id, template_version) → -//! tokens` map at query time by folding the tenant's `template_created` / -//! `template_widened` / `template_type_expanded` events (RFC 0001 §6.4, -//! RFC 0017 §3.1) off the RFC 0005 §3.7 audit Parquet stream. +//! The audit stream *is* the registry: the querier derives the requesting +//! tenant's `(template_id, template_version) → tokens` map at query time +//! by folding the tenant's `template_created` / `template_widened` / +//! `template_type_expanded` events (RFC 0001 §6.4, RFC 0017 §3.1) off the +//! RFC 0005 §3.7 audit Parquet stream. The RFC 0033 cached template map +//! (`template_map.json`, discharging the RFC 0005 §3.7.1 deferral) +//! accelerates this derivation at the query call sites; this fold remains +//! the source-of-truth derivation and the fallback for every non-hit +//! disposition. //! //! This mirrors [`crate::alias_store::derive_alias_map`] exactly — the same //! shared [`crate::audit_scan`] walk and the same total, deterministic fold diff --git a/crates/ourios-querier/tests/it/rfc0033_cached_template_map.rs b/crates/ourios-querier/tests/it/rfc0033_cached_template_map.rs index 7933da21b..a351169a4 100644 --- a/crates/ourios-querier/tests/it/rfc0033_cached_template_map.rs +++ b/crates/ourios-querier/tests/it/rfc0033_cached_template_map.rs @@ -1,11 +1,12 @@ //! RFC 0033 §5 — the cached template-map artifact, all seven scenarios. //! -//! `.1` (the artifact-format + fold green slice) and `.3` (the publish -//! green slice) are live; the remaining stubs are `#[ignore]`d so the -//! default run stays green while their slices land, each naming the -//! slice that discharges it. The `.3` S3 `If-Match` half runs in the -//! `s3-integration` CI job (`template_map_publish_cas_on_s3`, the -//! RFC 0013 localstack pattern). +//! `.1` (the artifact-format + fold green slice), `.3` (the publish +//! green slice) and `.2`/`.4`/`.5` (the freshness + write-through green +//! slice — the cached read path wired into the query surface) are live; +//! the remaining stubs are `#[ignore]`d so the default run stays green +//! while their slices land, each naming the slice that discharges it. +//! The `.3` S3 `If-Match` half runs in the `s3-integration` CI job +//! (`template_map_publish_cas_on_s3`, the RFC 0013 localstack pattern). //! //! Placement note: all seven stubs live here because the artifact's //! machinery — the folds (`template_registry.rs` / `alias_store.rs` / @@ -26,8 +27,9 @@ use ourios_core::audit::{AuditEvent, AuditPayload, TemplateChange, hash_triggeri use ourios_core::tenant::TenantId; use ourios_parquet::Store; use ourios_querier::{ - ArtifactRead, PublishOutcome, Querier, StoreRef, TEMPLATE_MAP_FILENAME, TemplateMap, - derive_alias_map, derive_template_map, derive_template_registry, + ArtifactRead, CacheOutcome, PublishOutcome, Querier, QueryError, QueryResult, StoreRef, + TEMPLATE_MAP_FILENAME, TemplateMap, derive_alias_map, derive_template_map, + derive_template_registry, load_or_derive, }; use proptest::prelude::*; use tempfile::TempDir; @@ -135,11 +137,17 @@ fn arb_history() -> impl Strategy> { ) } +/// A tenant's audit root under `bucket` (plain tenant names only — no +/// percent-encoding needed for these fixtures). +fn audit_root(bucket: &Path, tenant: &str) -> std::path::PathBuf { + bucket.join("audit").join(format!("tenant_id={tenant}")) +} + /// The tenant's live audit `*.parquet` set as tenant-root-relative, /// `/`-joined, sorted keys — an independent walk the artifact's /// `folded_files` frontier must match exactly. -fn live_audit_set(bucket: &Path) -> Vec { - let root = bucket.join("audit").join(format!("tenant_id={TENANT}")); +fn live_audit_set(bucket: &Path, tenant: &str) -> Vec { + let root = audit_root(bucket, tenant); let mut out = Vec::new(); let mut stack = vec![root.clone()]; while let Some(dir) = stack.pop() { @@ -222,7 +230,7 @@ proptest! { // The frontier is exactly the audit file set that was folded, // in canonical (tenant-root-relative, sorted) form. - let live_set = live_audit_set(bucket.path()); + let live_set = live_audit_set(bucket.path(), TENANT); prop_assert_eq!(cached.folded_files(), live_set.as_slice()); // The query answer through either path is identical: probe an @@ -258,33 +266,138 @@ proptest! { } } +/// An `alias_asserted` audit event — the freshness probe: whether a +/// `resolves_to` answer reflects it is exactly whether the fold that +/// answered the query saw the audit file it landed in. +fn alias_asserted( + tenant: &str, + representative_id: u64, + member_ids: Vec, + ts_ns: u64, +) -> AuditEvent { + AuditEvent { + tenant_id: TenantId::new(tenant), + timestamp: at(ts_ns), + payload: AuditPayload::AliasAsserted { + representative_id, + member_ids, + actor: ActorId::new("op-it").expect("non-empty actor"), + reason: String::new(), + }, + } +} + /// Scenario RFC0033.2 — staleness is detected and never served. /// See `docs/rfcs/0033-cached-template-map.md` §5. +/// +/// The freshness probe is the query *answer*: `resolves_to(1)` counts 1 +/// row until the alias assertion `{1, 2}` is folded and 3 rows after, so +/// a stale artifact served would be visible as a wrong count — no cache +/// internals needed to detect it. #[test] -#[ignore = "RFC0033.2 stub — implemented in the freshness + write-through green slice"] fn rfc0033_2_staleness_detected_never_served() { - todo!( - "RFC0033.2 — artifact published at frontier S, then new audit \ - files appear: the frontier check fails, the artifact is \ - bypassed, the answer equals the no-cache fold over the live \ - set incl. the new files; the querier republishes at the new \ - frontier and a subsequent unchanged-store query is a hit; \ - same when files DISAPPEAR from the live set (set equality, \ - not subset)" + let bucket = TempDir::new().expect("temp dir"); + let tenant = TenantId::new(TENANT); + let backend = StoreRef::Local(bucket.path()); + write_audit( + bucket.path(), + &[widened(TENANT, 1, 1, TS0), widened(TENANT, 2, 1, TS0 + 1)], + ); + write_all( + bucket.path(), + &[ + simple(TENANT, 1, TS0 + 10), + simple(TENANT, 2, TS0 + 11), + simple(TENANT, 2, TS0 + 12), + ], + ); + + // The first query misses (no artifact), folds fresh, and its + // write-through publishes at frontier S. + assert_eq!(next_query_rows(bucket.path(), &tenant), 1); + let artifact = audit_root(bucket.path(), TENANT).join(TEMPLATE_MAP_FILENAME); + assert!(artifact.exists(), "the miss write-through published at S"); + let frontier_s = live_audit_set(bucket.path(), TENANT); + + // New audit files appear after the publish: the operator asserts the + // alias class {1, 2}. + write_audit( + bucket.path(), + &[alias_asserted(TENANT, 1, vec![2], TS0 + HOUR_NS)], ); + let live_wide = live_audit_set(bucket.path(), TENANT); + assert!( + live_wide.len() > frontier_s.len(), + "the assertion landed in a new audit file", + ); + + // The frontier check fails, the artifact is bypassed, and the answer + // equals the no-cache fold over the live set — including the new + // file's alias event (an artifact served stale would still say 1). + assert_eq!(next_query_rows(bucket.path(), &tenant), 3); + + // ...and the querier republished at the new frontier, both folds. + let bytes = std::fs::read(&artifact).expect("read artifact"); + let read = TemplateMap::from_json(&bytes, &tenant).expect("read"); + let ArtifactRead::Valid(republished) = read else { + panic!("the republished artifact must be Valid, got {read:?}"); + }; + assert_eq!(republished.folded_files(), live_wide.as_slice()); + assert_eq!( + republished.alias_map().classes(&tenant), + vec![std::collections::BTreeSet::from([1u64, 2])], + ); + + // A subsequent unchanged-store lookup is a cache hit: the acquisition + // is exactly the artifact GET (frontier equal — zero audit GETs). + let (held, acquisition_bytes, outcome) = load_or_derive(backend, &tenant).expect("lookup"); + assert_eq!(outcome, CacheOutcome::Hit); + assert_eq!( + acquisition_bytes, + std::fs::metadata(&artifact).expect("stat artifact").len(), + "a hit's acquisition bytes are the artifact GET's bytes", + ); + assert_eq!(held.folded_files(), live_wide.as_slice()); + + // The removal direction: frontier validity is SET equality, not + // subset. Delete the alias event's audit file — the artifact (now a + // superset frontier) must be detected stale and the fold over the + // shrunken live set must answer. + for rel in live_wide.iter().filter(|k| !frontier_s.contains(k)) { + std::fs::remove_file(audit_root(bucket.path(), TENANT).join(rel)) + .expect("remove the appended audit file"); + } + assert_eq!(live_audit_set(bucket.path(), TENANT), frontier_s); + assert_eq!( + next_query_rows(bucket.path(), &tenant), + 1, + "files disappeared ⇒ stale ⇒ the fold over the live set answers", + ); + let bytes = std::fs::read(&artifact).expect("read artifact"); + let read = TemplateMap::from_json(&bytes, &tenant).expect("read"); + let ArtifactRead::Valid(reshrunk) = read else { + panic!("the shrink republish must be Valid, got {read:?}"); + }; + assert_eq!(reshrunk.folded_files(), frontier_s.as_slice()); + assert!(reshrunk.alias_map().classes(&tenant).is_empty()); } -/// The scenario's "next query": `resolves_to(1)` through the public -/// query surface. Returns the matching-row count; the `expect` is the -/// no-error-surfaced arm of RFC0033.3. -fn next_query_rows(bucket: &Path, tenant: &TenantId) -> u64 { +/// `resolves_to(1)` through the public query surface — the shared +/// "next query" of RFC0033.2/.3/.5. +fn resolves_query(bucket: &Path, tenant: &TenantId) -> Result { let query = ourios_querier::dsl::parse("resolves_to(1)").expect("parse"); let querier = Querier::new(bucket); let runtime = tokio::runtime::Builder::new_current_thread() .build() .expect("runtime"); - runtime - .block_on(querier.run_query(&query, tenant, NOW, DEFAULT_WINDOW_NS, None)) + runtime.block_on(querier.run_query(&query, tenant, NOW, DEFAULT_WINDOW_NS, None)) +} + +/// The scenario's "next query": `resolves_to(1)` through the public +/// query surface. Returns the matching-row count; the `expect` is the +/// no-error-surfaced arm of RFC0033.3. +fn next_query_rows(bucket: &Path, tenant: &TenantId) -> u64 { + resolves_query(bucket, tenant) .expect("the query must succeed, publish debris notwithstanding") .rows } @@ -514,35 +627,171 @@ async fn template_map_publish_cas_on_s3() { assert_eq!(held.folded_files(), map_b.folded_files()); } +/// A body-rendering query (`severity >= 0 | limit 10`) through the +/// public query surface — the RFC0033.4 probe. +fn body_query(bucket: &Path, tenant: &TenantId) -> QueryResult { + let query = ourios_querier::dsl::parse("severity >= 0 | limit 10").expect("parse"); + let querier = Querier::new(bucket); + let runtime = tokio::runtime::Builder::new_current_thread() + .build() + .expect("runtime"); + runtime + .block_on(querier.run_query(&query, tenant, NOW, DEFAULT_WINDOW_NS, None)) + .expect("body-rendering query") +} + /// Scenario RFC0033.4 — additive and advisory (back-compat). /// See `docs/rfcs/0033-cached-template-map.md` §5. +/// +/// The pre-RFC behaviour is byte-precise on the local backend: the fold +/// counts each audit `*.parquet` file's length, so "reads the audit +/// stream exactly as today" is `registry_bytes_read == the summed file +/// sizes on disk` — the figure the pre-0033 registry derivation +/// reported. #[test] -#[ignore = "RFC0033.4 stub — implemented in the freshness + write-through green slice"] fn rfc0033_4_additive_and_advisory() { - todo!( - "RFC0033.4 — store with no artifact: a body-rendering query's \ - result is identical to the pre-RFC binary's and the fold \ - reads the audit stream exactly as today; deleting the \ - artifact between two queries changes neither answer; the \ - artifact's presence changes nothing a *.parquet scan sees \ - (audit walk/listing returns the same file set with and \ - without it)" + let bucket = TempDir::new().expect("temp dir"); + let tenant = TenantId::new(TENANT); + write_audit(bucket.path(), &[widened(TENANT, 1, 1, TS0)]); + write_all( + bucket.path(), + &[simple(TENANT, 1, TS0 + 1), simple(TENANT, 1, TS0 + 2)], + ); + let live_before = live_audit_set(bucket.path(), TENANT); + let audit_bytes: u64 = live_before + .iter() + .map(|rel| { + std::fs::metadata(audit_root(bucket.path(), TENANT).join(rel)) + .expect("stat audit file") + .len() + }) + .sum(); + + // Store with no artifact (old data): the result is the pre-RFC + // binary's — every row rendered from the audit-stream fold, and the + // fold reads the audit stream exactly as today, byte for byte. + let first = body_query(bucket.path(), &tenant); + assert_eq!(first.rows, 2); + assert_eq!(first.records.len(), 2); + assert_eq!( + first.registry_bytes_read, audit_bytes, + "no artifact ⇒ the acquisition is exactly today's audit-stream fold", + ); + + // The miss write-through published — and the artifact's presence + // changes nothing a `*.parquet` scan sees: the audit walk returns + // the same file set as without it. + let artifact = audit_root(bucket.path(), TENANT).join(TEMPLATE_MAP_FILENAME); + assert!(artifact.exists(), "the miss write-through published"); + assert_eq!(live_audit_set(bucket.path(), TENANT), live_before); + + // Artifact present: identical answer (the cache is advisory), the + // acquisition now one small GET. + let second = body_query(bucket.path(), &tenant); + assert_eq!(second.rows, first.rows); + assert_eq!(second.records, first.records); + assert_eq!( + second.registry_bytes_read, + std::fs::metadata(&artifact).expect("stat artifact").len(), + "a hit's acquisition is exactly the artifact GET", ); + + // Deleting the artifact between two queries changes neither query's + // answer — the only cost is re-derivation (the acquisition returns + // to today's fold figure). + std::fs::remove_file(&artifact).expect("delete artifact"); + let third = body_query(bucket.path(), &tenant); + assert_eq!(third.rows, first.rows); + assert_eq!(third.records, first.records); + assert_eq!(third.registry_bytes_read, audit_bytes); } /// Scenario RFC0033.5 — tenant isolation. /// See `docs/rfcs/0033-cached-template-map.md` §5. #[test] -#[ignore = "RFC0033.5 stub — implemented in the freshness + write-through green slice"] fn rfc0033_5_tenant_isolation() { - todo!( - "RFC0033.5 — two tenants with distinct histories and published \ - artifacts: each cache hit serves only that tenant's registry \ - and alias map (paths under tenant_id=); an artifact \ - whose body tenant_id differs from the tenant of the path it \ - was fetched from fails the query loudly (the row-vs-path \ - stance), never silently serving or ignoring foreign data" + let bucket = TempDir::new().expect("temp dir"); + let backend = StoreRef::Local(bucket.path()); + let alpha = TenantId::new("alpha"); + let beta = TenantId::new("beta"); + // Distinct histories: alpha has one template and no aliases; beta has + // two templates and the alias class {1, 2} — the same probe query + // answers differently per tenant, so a cross-read would be visible. + write_audit(bucket.path(), &[widened("alpha", 1, 1, TS0)]); + write_audit( + bucket.path(), + &[ + widened("beta", 1, 1, TS0), + widened("beta", 2, 1, TS0 + 1), + alias_asserted("beta", 1, vec![2], TS0 + 2), + ], + ); + write_all( + bucket.path(), + &[ + simple("alpha", 1, TS0 + 10), + simple("beta", 1, TS0 + 10), + simple("beta", 2, TS0 + 11), + ], + ); + + // Each tenant's first query warms its own artifact, under its own + // `tenant_id=` audit root — and answers only from its own fold: + // alpha resolves 1 → {1} (1 row); beta resolves 1 → {1, 2} (2 rows). + assert_eq!(next_query_rows(bucket.path(), &alpha), 1); + assert_eq!(next_query_rows(bucket.path(), &beta), 2); + let alpha_artifact = audit_root(bucket.path(), "alpha").join(TEMPLATE_MAP_FILENAME); + let beta_artifact = audit_root(bucket.path(), "beta").join(TEMPLATE_MAP_FILENAME); + assert!(alpha_artifact.exists(), "alpha's write-through published"); + assert!(beta_artifact.exists(), "beta's write-through published"); + + // Each cache hit serves only that tenant's registry and alias map. + let (alpha_map, _, outcome) = load_or_derive(backend, &alpha).expect("alpha lookup"); + assert_eq!(outcome, CacheOutcome::Hit); + assert_eq!( + alpha_map.registry(), + &derive_template_registry(backend, &alpha).expect("alpha registry"), + ); + assert!(alpha_map.alias_map().classes(&alpha).is_empty()); + let (beta_map, _, outcome) = load_or_derive(backend, &beta).expect("beta lookup"); + assert_eq!(outcome, CacheOutcome::Hit); + assert_eq!( + beta_map.registry(), + &derive_template_registry(backend, &beta).expect("beta registry"), ); + assert_eq!( + beta_map.alias_map().classes(&beta), + vec![std::collections::BTreeSet::from([1u64, 2])], + ); + assert_eq!( + alpha_map.folded_files(), + live_audit_set(bucket.path(), "alpha").as_slice() + ); + assert_eq!( + beta_map.folded_files(), + live_audit_set(bucket.path(), "beta").as_slice() + ); + + // The queries stay isolated cache-warm too. + assert_eq!(next_query_rows(bucket.path(), &alpha), 1); + assert_eq!(next_query_rows(bucket.path(), &beta), 2); + + // An artifact whose body `tenant_id` differs from the tenant of the + // path it was fetched from fails the query LOUDLY — end to end + // through the public surface — never silently serving or ignoring + // foreign data (the row-vs-path stance). + std::fs::copy(&beta_artifact, &alpha_artifact).expect("plant beta's artifact under alpha"); + match resolves_query(bucket.path(), &alpha) + .expect_err("a foreign artifact under alpha's root must fail alpha's query") + { + QueryError::Storage { detail } => assert!( + detail.contains("claims tenant beta under tenant alpha"), + "the failure must name the row-vs-path mismatch: {detail}", + ), + other => panic!("expected Storage, got {other:?}"), + } + // Beta is untouched by alpha's corruption. + assert_eq!(next_query_rows(bucket.path(), &beta), 2); } /// Scenario RFC0033.6 — the measured tax collapses (RFC 0031 channel). diff --git a/docs/rfcs/0031-comparative-evaluation-loki.md b/docs/rfcs/0031-comparative-evaluation-loki.md index 0ba7716ec..92ddfb733 100644 --- a/docs/rfcs/0031-comparative-evaluation-loki.md +++ b/docs/rfcs/0031-comparative-evaluation-loki.md @@ -353,6 +353,17 @@ Per query, per system, the harness records: > B1/B2 gates and the RFC 0016 metrics depend on it); the two new > components are additive `QueryResult` fields the harness sums. > +> **Template-map acquisition (amendment, 2026-07-13, RFC 0033).** +> Since RFC 0033's cached template-map artifact, the third component +> is the **template-map acquisition bytes**: the total bytes fetched +> to obtain body-rendering capability, whatever the source — the +> audit-stream fold on a cache miss (byte-for-byte the registry +> derivation described above) or the `template_map.json` artifact GET +> on a cache hit. `QueryResult::registry_bytes_read` keeps its name +> and its additive place in the three-component sum; only the source +> of the bytes changes. One field, one honest meaning — the harness +> needs no code change. +> > **Channel definitions (amendment, 2026-07-13).** The Loki > comparator is recorded on two channels, and each frozen gate names > which it uses (§7): the **storage-side channel**