---
title: Feed the availability engine
editUrl: https://github.com/Cratis/Showrunner/edit/main/Documentation/GuestList/feed-the-availability-engine.md
description: Hand the audiences a product recorded to the Cratis Choreography availability engine so gates resolve from local state and open sessions update on changes.
---


Use this in a product that evaluates availability with [Cratis Choreography](https://github.com/Cratis/Choreography). It adds the part of GuestList that implements the engine's `IAudienceSource`; a product that does not use Choreography does not reference it and is unaffected.

## Add it

1. Reference `Cratis.Showrunner.GuestList.Availability` next to `Cratis.Showrunner.GuestList`. It is a separate package so GuestList itself takes no dependency on Choreography.
2. Register it after `AddGuestList`:

```csharp
builder.AddGuestList(guestList =>
{
    guestList.Product = "ledger";
    guestList.DeclaredAudiences = ["Plus", "Preview", "Internal"];
});
builder.Services.AddGuestListAvailability(options => options.EnvironmentName = builder.Environment.EnvironmentName);
```

`AddGuestListAvailability` calls the engine's `AddAvailability` with the options you pass, and registers:

| Registration | What it is |
| --- | --- |
| `IAudienceSource` | `GuestListAudienceSource`, which answers from the local read models |
| `IDeclaredAudiences` | The audiences named by `GuestListOptions.DeclaredAudiences` |
| `IUndeclaredAudienceObserver` | `LoggingUndeclaredAudienceObserver`, which logs a warning once per grant |
| `AudienceChangeWatcher` | A hosted service that watches the read models and tells open sessions what changed |

Registrations you made earlier win. A model that declares its own audiences, for example one generated by Stage, registers its own `IDeclaredAudiences` and `AvailabilityCatalog` first.

## What the engine reads

`GetGrants` returns the union of three levels, each tagged with the level it is held at:

| Level | Read for | Held in |
| --- | --- | --- |
| System | every request | the product's own namespace |
| Tenant | `AudienceSubject.Tenant` | the tenant's namespace |
| User | `AudienceSubject.User`, when the subject has a tenant | the tenant's namespace |

A system grant applies to every tenant, as it does everywhere in GuestList, so it is part of every answer. Withdrawing a grant removes it at its own level only: an audience granted to the tenant and to one user stays with the user when the tenant's grant is withdrawn.

### A named system

`AudienceSubject` carries the client id of the calling system in `SystemClientId`, so the engine needs nothing more than the subject: `IAudienceSource.GetGrants(subject)` answers a system caller that names a client id with the grants of every system and the grants of that system, tagged `System` like the others, and never another system's. A caller that names no client id, or one the product holds nothing for, gets the grants of every system only, so a missing or unknown client id never opens a gate that a named grant would open. A subject that is not a system caller never gets a system's own grants, whatever client id it carries. This needs `Cratis.Choreography` 2.9.0 or later.

Nothing is asked of the operator. The answer is what the product recorded, so while the link to the operator is down the last known state stays in force.

## Undeclared audiences

A grant for an audience the deployed model does not declare is returned like any other. The engine keeps it in `EffectiveAudiences.Undeclared`, never matches a gate with it, and tells the `IUndeclaredAudienceObserver`. The default observer logs a warning for each subject and grant once while the process runs. The `UndeclaredGrant` query lists the same grants for an operator. Declaring the audience later makes the grant live without a replay.

## Open sessions

`IAudienceSource.OnChanged` subscribes to changes. The watcher observes the `AudienceHoldings` read model in the product's own namespace and in every tenant's, and publishes an `AudienceChange` when one changes: the tenant for a tenant grant, the user for a user grant, nothing for the system. A tenant added later is picked up on the next `PollingInterval`, and a watch that ends is opened again then.

## Lag

The meter `Cratis.Showrunner.GuestList` has a gauge, `cratis.showrunner.guestlist.audience_lag`, with the time in seconds since the product last received a change to its audiences. It grows while nothing arrives, so a value that climbs past what the operator normally takes between decisions suggests the link is down. Nothing is reported until the first change has been received since the product started. Add the meter to your OpenTelemetry configuration to export it.
