Scenario Selection

Scenario Selection is the gate in front of calendar synchronization. The service first chooses a scenario from the sync tokens, then this setting decides whether to run it, replace it with Initial, or leave the user for a later cycle. Full and Sensitive stay under Service__SyncType. One-way is Service__SyncDirection.

The scenario is chosen before the gate:

Tokens	Scenario
Both empty	Initial
Exactly one empty	BadSyncTokens
Both present	Incremental

If Incremental is already running and the change feed asks for a full resync, that pass is treated as BadSyncTokens and the gate is applied again.

The setting is read once at startup. The service reads appsettings.json, then appsettings.{Environment}.json, then exactly one environment file. It uses the first file it finds: .env.Development, then .env.development, then .env. An empty line in that file leaves the previous value in place. Restart the service after a change. After a restart, the === Startup === block shows the ScenarioSelection section with the active EnabledScenarios and UserDelaySeconds. An invalid value logs Event=ConfigInvalid and the process stops.

Settings

Parameter	Meaning & Usage	Example	Applies To
ScenarioSelection__EnabledScenarios	Which scenarios may run. This is a sum of flags, the same way as Service__SyncMode. Initial = 1, Incremental = 2, BadSyncTokens = 4.	7	Docker, Binary
ScenarioSelection__UserDelaySeconds	How many seconds a deferred user stays out of capture. The service sets Users.SyncDeferredUntilUtc. It does not pause the worker thread. A value below 0 is treated as 0. The default is 300.	300	Docker, Binary

In production, leave UserDelaySeconds in appsettings.json and override EnabledScenarios in .env when the value should differ from 7.

Warning: 0, an empty value, and 4 (BadSyncTokens alone) are invalid. The service does not start. At least Initial or Incremental is required.

Allowed values

Value	Enabled	Initial	Incremental	BadSyncTokens	Tokens
1	Initial	Run	Replace with Initial	Replace with Initial	Delete
5	Initial + BadSyncTokens	Run	Replace with Initial	Run	Delete
2	Incremental	Defer	Run	Defer	Keep
6	Incremental + BadSyncTokens	Defer	Run	Defer	Keep
3	Initial + Incremental	Run	Run	Defer	Keep
7	All three	Run	Run	Run	Keep

Run means the chosen scenario proceeds.

Replace with Initial happens when Initial is on and Incremental is off. The current pass runs as Initial, and the tokens are deleted so the next cycle sees empty tokens and stays on the snapshot.

Defer means this user's sync does not run. New tokens are not written, existing tokens are not deleted, and the user is left out of capture until UserDelaySeconds has passed.

Delete means both calendar tokens are erased after the pass whenever Incremental is off, including a pass that was allowed to run.

Keep means tokens are saved by the ordinary rule of a successful pass.

What each value does in practice

7 — all three, the default. A new user with no tokens runs Initial, keeps the tokens, and the next cycle runs Incremental. One empty token, or a feed that asks for a full resync, runs BadSyncTokens and keeps the tokens.

1 — Initial only. Every cycle runs as Initial, including a user who already has tokens. Tokens are deleted after the pass, so Incremental does not accumulate.

5 — Initial and BadSyncTokens. A normal pass and a bad-token pass both run. Tokens are still deleted, because Incremental is off, so the next cycle is Initial again.

2 — Incremental only. A user who already has both tokens runs Incremental and keeps them. A user with no tokens is deferred and never receives the first snapshot until Initial is added. A user with one empty token, or a feed that asks for a full resync, is deferred again until BadSyncTokens is enabled or both tokens are valid.

6 — Incremental and BadSyncTokens. Incremental and a bad-token snapshot both run, and tokens are kept. A new user with no tokens is deferred, because Initial is off.

3 — Initial and Incremental. A new user runs Initial and keeps the tokens. Later cycles run Incremental. A bad or half-empty token does not fall back to Initial while Incremental is on. That user is deferred, and the deferral repeats until BadSyncTokens is enabled or the tokens become both empty or both filled.

Deferral

While SyncDeferredUntilUtc is in the future, capture skips the user. After a later pass succeeds with no partial failures, the deferral is cleared on the next batch save. With UserDelaySeconds=0, the deferral moment is the current time, so the user can be picked up again on the next query.

Together with one-way sync

Scenario Selection decides which scenario starts. Service__SyncDirection=1 decides that the higher-priority client writes inside that scenario.

Service__SyncDirection	Service__SyncType	ScenarioSelection__EnabledScenarios	Result
1	0	7	All three scenarios run. The higher-priority client writes the full event.
1	0	1	Every cycle is an Initial snapshot under the one-way rules. Tokens are deleted.
1	0	2	One-way rules apply only to Incremental. A user without both tokens is deferred and does not get the first snapshot.
0	0	3	Two-way Full sync. Initial and Incremental run. A bad token defers the user.