perf: integrate paged current-state catalog lookup

crates/crab-metadata/README.md

@@ -46,6 +46,12 @@ Catalog readers resolve only ref heads in that root's authority epoch, before
 loading multi-ref activation records. Restore can leave retired heads in storage;
 their checkpoint positions and dependencies must not enter the restored catalog.
 Current-epoch activation and checkpoint-chain errors still fail closed.
+`capture_ref_heads` and `resolve_referenced_activations` own that stable capture
+for metadata and read orchestration. Transactionless heads must match the
+compacted root; selected-ref capture reuses the same activation validator while
+keeping its targeted ETag probes. Current-state catalog lookups reuse that owner together with the shared
+control-selection and visibility machinery; full maintenance materialization
+remains explicit.
 Run controls retain each capsule's own pack directory in capsule-relative
 coordinates. The run directory keeps physical transport coordinates separately.
 Logical capsule equality compares authenticated visibility section identities
@@ -66,15 +72,25 @@ accepts captured lookup roots and resolves requested files with their authentica
 shard/xorb closure. Point and batch calls share the page cache and retain the
 session read guard through I/O, so close waits for active reads. Missing catalog
 pages remain errors rather than reopening the mutable file-index database.
-The current-state opener still materializes a complete v2 catalog; callers with
-an authenticated view should pass its captured roots. All 19 audited local release tags omit these
+A session caches at most 4,096 verified catalog bindings or authenticated misses,
+using the same result-cache owner as canonical shard lookup. Cold queries still
+validate the full selected dependency closure before publishing cache entries;
+errors are never cached as absence. Cached inputs retain the original admission
+charge. Catalog cache locks cover memory work only, so unrelated warm lookups can finish
+while a cold origin read is paused. Retention counts distinct file identities;
+duplicate occurrences do not consume additional entries or prevent caching.
+The current-state opener also captures authenticated catalog roots and leaves
+catalog bodies cold. Explicitly pinned callers pass their existing capture, while
+current-state sessions bind once to the first root they open. Catalog and Git
+views share stable ref capture, ref-frontier selection, visibility reconciliation
+and transaction ordering; neither path invents a separate precedence policy. All 19 audited local release tags omit these
 capsule checkpoint formats; unshipped format 6 is rejected without a fallback.
-Captured run-v4 roots provide the same selected lookup over exact logical
-capsule occurrences; catalog bodies remain cold until their keys are selected.
+Checkpoint and selected run catalog roots share one lookup budget and page cache.
 CLI and shared capsule-publication preparation use these captured queries.
 Protected receive selects from separately authorized source/filtered captures.
-Captured revision and remote-mount hydration pass the same paged lookup to the
-shared hydrator; current-state hydration still requires capture integration.
+Captured revision, remote-mount and current-state hydration use the shared paged
+lookup. Control capture and selected closure queries are measured separately;
+complete opening and history-amplification qualification remain required.
 
 External pointer catalogs use `CRBPCP01` authenticated pages. A bounded descriptor
 commits file, shard, xorb and reverse-chunk directories; nested shard closures and
@@ -83,12 +99,16 @@ ordering, including the previous lowest-xorb/first-occurrence placement rule.
 Complete inspection verifies the body hash, complete dependency closure and
 canonical page layout. Delta inspection defers base-owned closure to `apply`,
 which retains later file bindings at equal size and rejects immutable shard/xorb
-conflicts. Encoded catalogs are limited to 2 GiB and descriptors to 4 KiB.
+conflicts.
+Full inspection of a captured visible set uses `PointerCatalogAssembly`: binding
+order need not be dependency order across independent refs. Rows and immutable
+conflicts are checked while collecting deltas, then the complete closure is
+checked before returning the catalog. Publication-time `PointerCatalog::apply`
+still requires each delta's dependencies to exist in its base. Encoded catalogs are limited to 2 GiB and descriptors to 4 KiB.
 The retired monolithic JSON encoding was absent from all 19 audited release tags
-and is rejected. Foreground consumers must use captured selected lookups rather
-than infer bounded work from the page encoding alone. Maintenance retains explicit full
-inspection; shared/protected hydration and lifecycle qualification remain
-separate gates.
+and is rejected. Shared file lookup uses paged capture for pinned and current-state sessions.
+Complete catalog inspection remains explicit; consumer, historical amplification
+and lifecycle qualification must not be inferred from the page representation.
 
 `v2/browse-indexes` is a bounded, mutable derived record, not ref authority.
 Its version 3 record binds a durable immutable commit graph, optional complete