Skip to content

How GuestList works

An operator decides, a product records, and the product answers from what it recorded.

operator store product store
-------------- -------------
GrantAudience / WithdrawAudience
-> AudienceGrantDecided tenant namespace "acme":
-> outbox: AudienceGranted ----------> tenant stream, user streams
default namespace:
system stream
queries answer from these
Level Held in Applies to
Tenant the tenant’s own namespace, stream tenant everyone in that tenant
User the user’s tenant namespace, stream user:<id> one user of that tenant
System the product’s default namespace, stream system the system and every tenant: automation and callers that are not a person
Named system the product’s default namespace, stream system:<client id> one system, identified by its client id, and every tenant it works for; it adds to what every system holds

A request made by a named system gets what every system holds plus its own, never another system’s. The audiences of a request are the three added together: its tenant’s, its user’s and the system’s. A grant and a withdrawal touch one level. If Plus is granted to the tenant and to one user, withdrawing it from the tenant leaves that user in it.

Each level folds its decisions into the last one per audience, ordered by when the operator decided. A withdrawal is kept as a decision too, so an older grant that is delivered late cannot undo it. Two decisions at the same instant resolve to the one recorded last. A grant that arrives twice, for example after a retry, is recorded once: the product derives an idempotency key from the event itself.

The commands help from the operator side. Granting an audience that is already held, or withdrawing one that is not, records nothing, so the outbox does not publish the same decision again.

The product never calls the operator when it answers. Its read models are in its own store, so the last known state stays while the operator is down, restarting or has not been deployed yet. When the link is back, Chronicle delivers what was missed and the product catches up.

An application declares the audiences its model has. A grant of any other name is not refused, because a decision is a fact, and declaring the audience later should make the old grant live. It never matches a gate in the meantime, and both sides can list it: the product with the UndeclaredGrant query and the operator with the UndeclaredAudienceGrant query.

A decision never creates a tenant. The operator’s command refuses a tenant its IKnownTenants does not know, and the product ignores a decision whose tenant namespace it does not have, logging a warning. Once the tenant exists, the operator repeats the decision.