Skip to content
Cosella Cosella Engineering Docs

ADR 0005: Desktop Release Rules

Accepted

Status

Section titled “Status”

Accepted

Date

Section titled “Date”

2026-07-15

Context

Section titled “Context”

The desktop app is a live-call copilot. Updates that interrupt an active call could cause a user to lose a deal. The release process must prioritize call safety over deployment speed.

Decision

Section titled “Decision”

Versioning

Section titled “Versioning”

Semantic versioning: v{major}.{minor}.{patch} (stable), v{major}.{minor}.{patch}-beta.{N} (pre-release).

Channels

Section titled “Channels”

Two channels only: stable and beta. Canary deferred — not enough users for meaningful signal.

Call-Aware Update Gate (Headline Rule)

Section titled “Call-Aware Update Gate (Headline Rule)”

Updates download silently in the background. They never apply during an active call session (phases: connecting, active, summary). If a call is in progress when an update is ready:

  • Queue the update
  • Show a subtle non-intrusive indicator
  • Apply on transition back to idle, or on app quit

Promotion

Section titled “Promotion”

Manual beta to stable promotion: a deliberate human action after N stable days. Not automated, not time-based.

Minimum Version Handshake

Section titled “Minimum Version Handshake”
  • Client sends clientVersion on every WebSocket connection
  • Backend responds: ok | nudge (soft banner) | block (disable overlay)
  • Now: handle nudge only. Enable block on first breaking protocol change.
  • Backend-owned rule — the client obeys, does not decide.

Distribution

Section titled “Distribution”

Direct download + auto-update via electron-updater. Artifacts: NSIS (Windows), DMG (macOS).

No app stores. Microsoft Store and Mac App Store sandboxing is incompatible with:

  • System audio loopback (WASAPI requires unsandboxed access)
  • Content protection (setContentProtection / screen capture exclusion)

Store review would force crippling the product. Revisit only for a hypothetical deliberately-limited “lite” build.

Code Signing

Section titled “Code Signing”
  • Windows: EV Code Signing Certificate (eliminates SmartScreen)
  • macOS: Developer ID + Notarization
  • Both integrated into CI pipeline

Consequences

Section titled “Consequences”
  • autoInstallOnAppQuit = false — we control quit behavior via CallStateMachine
  • No staged rollout infra needed yet
  • Backend must implement the version handshake endpoint before hard-block is usable