BE-848: atlas: visibility resolution and the request scene

[indietyp]

🌟 What is the purpose of this PR?

Add visibility resolution and the request scene. A resolver turns a request's visibility into a mask once, a cache keeps it under one budget shared across all generations, and a Scene captures it together with the world, the epoch and the delivery schedule. Every document a request produces comes from that one snapshot.

The module stays dead code under the lib.rs attribute until the read API consumes it (BE-815).

For review, the properties this stands on:

• One visibility-cache budget across all generations. Entries key on the requested generation and its DeltaId, so a retired generation's misses cannot resolve a fresh scope.
• A cached mask and schedule may predate the request's epoch within the same delta lifetime; scene geometry, identity and topology lookups still use only the request's captured publication.
• A request captures its Scene once and every read goes through it.

🔍 What does this change?

• serve/visibility/resolver/: ScopeResolver and VisibilityActor, resolving an actor's filter into a VisibilityMask.
• serve/visibility/cache/: VisibilityCache with CacheKey, CacheEntry, the pending entry for an in-flight resolution, and FilterDigest.
• serve/scene.rs: Scene over a world, an epoch, a mask and a delivery schedule.
• serve/membership/ and serve/neighbourhood/: ontology membership and selection, and the NeighbourhoodProvider behind edge delivery.

❓ How to test this?

1. cargo nextest run -p hash-graph-atlas --all-features serve::visibility:: runs the resolver and cache tests.
2. Reading order: serve/scene.rs, then serve/visibility/cache/mod.rs.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• are internal and do not require a docs change

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 14, 2026 9:20pm UTC
petrinaut	Ready	Preview	Sep 14, 2026 9:20pm UTC
petrinaut-docs	Ready	Preview	Sep 14, 2026 9:20pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 14, 2026 9:20pm UTC

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 114 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.13%. Comparing base (25c1a14) to head (8db3ec5).

Files with missing lines	Patch %	Lines
...local/graph/atlas/src/serve/membership/ontology.rs	0.00%	46 Missing ⚠️
libs/@local/graph/atlas/src/serve/scene.rs	0.00%	22 Missing ⚠️
...ocal/graph/atlas/src/serve/visibility/cache/mod.rs	89.23%	20 Missing and 1 partial ⚠️
...l/graph/atlas/src/serve/visibility/resolver/mod.rs	67.27%	18 Missing ⚠️
...al/graph/atlas/src/serve/visibility/cache/error.rs	0.00%	4 Missing ⚠️
.../@local/graph/atlas/src/serve/neighbourhood/mod.rs	97.54%	3 Missing ⚠️

Additional details and impacted files

@@                                      Coverage Diff                                       @@
##           bm/be-847-atlas-store-hydration-and-the-generation-runtime    #9712      +/-   ##
==============================================================================================
+ Coverage                                                       68.99%   69.13%   +0.14%     
==============================================================================================
  Files                                                            1134     1141       +7     
  Lines                                                          103804   104260     +456     
  Branches                                                         5127     5147      +20     
==============================================================================================
+ Hits                                                            71615    72084     +469     
+ Misses                                                          31300    31290      -10     
+ Partials                                                          889      886       -3     

Flag	Coverage Δ
apps.hash-api	15.35% <ø> (ø)
apps.hash-graph	13.62% <ø> (ø)
rust.hash-graph-atlas	81.00% <75.00%> (+0.20%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

PR Summary

High Risk
Introduces authorization visibility caching with intentional staleness across delta revisions within a lifetime; incorrect expiry, refresh, or keying would change what rows an actor receives.

Overview
Adds the request-scene pipeline for Atlas serving: resolve an actor’s visibility once, cache it under a shared budget, then bind world + epoch + mask + schedule into a Scene for coherent reads.

ScopeResolver and VisibilityCache turn Postgres permission checks into a retained VisibilityMask and ViewSchedule, keyed by generation, DeltaId, actor, and optional FilterDigest. Entries support soft-stale background refresh and hard expiry; retired generations/lifetimes do not get fresh scopes. Filter-only requests can recover the cached JSON document by digest.

Scene::of applies a density zoom cut to the cached schedule while topology/identity reads stay on the request’s captured epoch.

Also adds membership (ontology type → per-row membership for response marking) and neighbourhood (visibility-aware incident edges and capacity-limited induced edges ranked by endpoint importance), with Scene implementing the neighbourhood provider.

^{Reviewed by Cursor Bugbot for commit 8db3ec5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.