Design lookup-style relationship enumeration

[hardbyte]

Context

PR #18 deliberately removes the public LookupSource trait before v0.3 ships. The earlier draft reserved a paginated lookup_resources shape, but Gatehouse had no checker API, example, or contract test exercising it. Shipping an unconsumed public trait would freeze an unvalidated signature.

Goal

Design lookup-style authorization from a concrete consumer instead of reserving a trait shape in advance. This is the "what can this subject see?" complement to point checks and batch filtering.

Questions to answer

• What public checker API should consume lookup sources? For example, PermissionChecker::lookup_authorized(...), a policy-specific helper, or a separate query object.
• How should lookup compose with non-lookup policies in the same checker? A backend may enumerate relationship candidates, but in-memory RBAC/ABAC predicates still need to run over hydrated resources.
• What is the pagination contract? Cursor type, limit semantics, empty pages, duplicate resources, stable ordering, and backend errors all need explicit behavior.
• Should lookup return IDs only, caller-owned resources, or a stream/page abstraction that lets the caller hydrate resources between pages?
• How should tracing link one backend lookup page to the per-resource authorization decisions it informs?

Acceptance criteria

• Add one end-to-end consumer API in Gatehouse itself.
• Add an in-memory implementation used by tests.
• Add contract tests for paging, cursor semantics, duplicate handling, fail-closed backend errors, and composition with at least one non-lookup policy.
• Add one example showing the intended production shape.
• Only then make the lookup trait public and documented.

Related

• Deferred from PR Make ReBAC FactSource-backed #18.
• Builds on the v0.3 FactSource / EvaluationSession model from Reachitect to support bulk authz with FactSource the bottom of ReBAC #20.