feat(docs): add policy ADR for LIST limit and pagination

[jakedoublev]

Resolves #55

[strantalis]

What work needs to be done on the SDK side here.

• Will there be a way to say just give me all items?
• Do we need to add a layer of abstraction to the list operation so we have some type of iterator pattern. This way a user doesn't need to worry about offsets and pages and just could be like .Next()?

[jakedoublev]

Will there be a way to say just give me all items?

This is the current state, and I don't think it's realistic if we're assuming at-scale deployment with policy data we don't control as the platform. I think as a platform there are only limited assumptions we can make about the number of any given policy object that will exist (Hyrum's Law: "With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."). If an administrator of a platform decides to add 5,000,000 attributes, it's not feasible for the platform to be expected to bear a ListAttributes call that has 5M attributes and all they entail in a single response.

I think it's a safer approach to enforce a limit now and decide on an approach to satisfy pagination beyond the limit.

That said, with an offset approach, it would be possible to make an SDK function for any policy object like ListAllAttributes that opens 5 "workers" (language agnostic) to concurrently fetch all the policy attributes until exhausted and streams the response LIST. With a cursor approach, we would be dependent upon each response's cursor to get the next, so we would be limited in concurrency and the helpfulness of streaming.

Do we need to add a layer of abstraction to the list operation so we have some type of iterator pattern. This way a user doesn't need to worry about offsets and pages and just could be like .Next()?

This is actually what the cursor approach would look like. You can imagine a social media feed with infinite scroll where you can scroll up or down but never "skip" forward/backward 4 pages either direction.

I think there are two use cases for policy LIST calls:

1. administration of platform policy

• "I am looking at a GUI and need to navigate a table or some kind of UX displaying my attributes or subject mappings to CRUD them"
• "I know the object I need to see is last on the list, but I need to click/tab X number of times to get there"
• "I don't know where the object I need to see is in the list, but I want to find out and navigate there again fast after I do something else"

2. service-based needs as consumers of policy

• authorization service calling ListAttributes to check entitlements
• PEPs/PDPs retrieving policy to drive feature behaviors
• the SDKs checking KAS grants (not open-ended LIST calls as the value FQNs are known on TDF create)