CMS events #

CE001 — Ownership. Each live site's SiteRuntime owns a broadcast channel. PostSaved reports durable source changes from explicit Save, browser autosave, file operations, and incoming collaborative changes: the resync actor reconciles room state into the source tree, releases its guards, enqueues a rebuild and emits PostSaved. The Git listener batches these events. GitCommitted tells the iroh listener to synchronize Git bundles with peers; it is a local completion receipt, not proof of a remote push or publication. SettingsChanged invalidates the server's settings/runtime slot. Producers include settings saves, API operations and PDS setup; the settings listener also invalidates on broadcast lag. See sync machinery and iroh ownership.

CE002 — Commit and push. Batched saves and every eligible ordinary Push call the same site-level commit function. It uses normal Git staging/ignore rules, then releases the tree transaction before build catch-up and GitCommitted. Save intentionally announces successful clean probes too; pre-push probes announce only actual commits. Failure announces neither. Managed publications catch up through the existing build lane, including clean probes whose Git bookkeeping advanced the source revision; bootstrap-only sites do not start a build for this bookkeeping. The commit helper never emits PostSaved, requests a push, or publishes.

The save listener requests push through a private capacity-one channel, not a CmsEvent. Its worker holds only weak site ownership while waiting. Requests coalesce; transport failures retry after 5/10/20/40/60/300 seconds and then every 300 seconds, stopping at one hour. Requests during backoff neither accelerate the retry nor extend that window. Preparation/commit failure ends the attempt; a later save can try again. Closing the sender ends waits. Retirement is checked before work when awakened, without periodic polling.

CE003 — Flow. Manual Push and publish-triggered Push await the same ordinary-push helper as the worker. It checks current policy, commits dirty files, refreshes auth and ensures PDS setup. Ordinary pushes serialize under the existing per-site gate, held through network completion without holding the tree transaction during the network wait. The existing Save/Publish local-history probe runs after pre-push commit and before queuing on the gate. Two callers can both observe pending history and perform redundant serialized pushes; Git may report the second as already up to date. Manual Push retains its awaited remote operation and upstream setup. There is no new tracking-based deduplication or remote-ref bookkeeping. Local history checks are not a fresh guarantee of remote state.

flowchart TD
  UI[Manual Save / browser autosave / file operations] --> Saved[PostSaved broadcast]
  Sync[Incoming room sync → resync actor → durable source] --> Saved
  Saved --> Batch[Batched save listener]
  Batch --> Commit[Shared commit → build catch-up → GitCommitted]
  Commit --> Iroh[Iroh bundle synchronization]
  Batch --> Request[Private capacity-one push channel]
  Request --> Worker[Coalescing worker]
  Worker --> Push[Shared ordinary push: commit → auth / PDS setup → serialized push]
  Push -- transport failure --> Backoff[Retry deadline, up to one hour]
  Backoff --> Worker
  Push -- preparation failure --> Idle[End attempt; wait for later request]
  Manual[Manual Push] --> Push
  Batch -- auto_publish: awaited --> Publish[Publish hook]
  Button[Manual Publish] --> Publish
  Publish --> Push
  Publish --> Standard[Optional standard.site]
  Publish --> Pages[Optional Pages]
  Push -- setup changed settings, Manual / Publish only --> Saved
  Push -- setup changed settings --> Settings[SettingsChanged → invalidate settings]

PDS setup's back-edge is conditional: adding/configuring its remote emits SettingsChanged and, for Manual/Publish, PostSaved. Save-triggered setup suppresses the extra PostSaved. Once configured, later setup probes do not repeat these notifications. Push success itself never invokes Publish.

CE004 — Limits. auto_publish still awaits its hook inside the save listener. Auto-push and publish-push requests can overlap but their ordinary network pushes serialize. The private channel/retry window is not durable across restart. There is no hung-process watchdog, separate commit-retry loop or coordination with force-push/compaction. See concurrency.