Goodbye and operational state: default reason, external_source API, delta updates

[balloob]

This issue comes out of a cross-SDK conformance audit comparing every Sendspin client/server implementation (aiosendspin, sendspin-cli, sendspin-cpp, sendspin-dotnet, sendspin-go, sendspin-js, sendspin-jvm, sendspin-rs, SendspinKit) against the spec. sendspin-cpp is treated as the reference implementation throughout — it most closely matches the spec's language and is the only SDK that runs on the constrained-embedded target the spec was originally written for.

Most SDKs implement the message envelopes correctly but only one
(SendspinKit) implements external_source as a client API, and
several SDKs default to the wrong goodbye reason in common situations.
For external_source, SendspinKit is the reference —
enterExternalSource() / exitExternalSource() route through
transitionOperationalState(to:) with rollback on
server-notification failure. For goodbye-reason plumbing,
sendspin-cpp is the reference (SendspinGoodbyeReason enum,
auto-another_server from ConnectionManager).

1. Pick a default goodbye reason and make it consistent

When a client disconnects without specifying a reason in its SDK API,
the SDK SHOULD send reason: 'restart', matching the server's
no-goodbye assumption.

Today defaults are unprincipled: sendspin-js → shutdown,
sendspin-dotnet → user_request, SendspinKit → shutdown. All
three suppress server-side auto-reconnect for a user who simply
closes a laptop lid — the opposite of what the spec implies.

2. Add a normative note about the external_source SDK API

Client SDKs SHOULD expose API methods for entering and leaving
external_source state and SHOULD roll back the local state on
server-notification failure.

SendspinKit's rollback pattern
(SendspinClient+Commands.swift:27-45) is the model. Eight of nine
SDKs have no embedder-facing handle today — so a Sonos-style "input
switched to TV" event cannot be relayed to the server, and the
server keeps streaming audio into silence.

3. Document or relax delta client/state merge behavior

The spec says: "for subsequent updates, only include fields that have
changed; the server will merge these updates into existing state".
No SDK actually sends delta updates — everyone sends the full
payload every time. Either:

• add normative test cases (e.g., "if the client previously sent
  static_delay_ms: 100 and now sends {volume: 50}, the server's
  view of static_delay_ms MUST remain 100"), or
• relax to "clients MAY send partial state updates; servers MUST
  handle full updates and SHOULD handle partial updates".

Today there are zero tests for either case.

---

Source audit doc: docs/goodbye-and-operational-state.md
Full audit branch: claude/stream-sync-correction-sdks-AWoNC
Per-SDK digest: sdk-issues digest

[balloob]

Re-audited against the current spec.

3. Delta client/state merge — done, verbatim as requested. messaging.md now reads: "The initial message MUST include all state fields. In subsequent messages, the client MAY send only the fields that have changed; the server MUST merge each update into existing state, retaining the last value of any field that is absent. A client MAY instead resend unchanged fields, up to its full state." That is the relax option from this issue, plus the merge semantics spelled out. (#149 proposes unifying this rule with server/state and group/update.)

2. external_source — obsolete as written. There is no external_source state in the spec any more; it was replaced by available: false plus the External Source Handling section, which also distinguishes interruptible from non-interruptible activity and specifies the server's group-move behavior. The underlying ask — that SDKs expose enter/leave methods with rollback on notification failure — is an SDK API concern, not a wire-protocol one.

1. Default goodbye reason — partially addressed at the protocol level: clients SHOULD send shutdown when powering off, and servers assume restart when a client disconnects without a goodbye on a playback connection. What remains is the SDK-side default, which is again an SDK concern.

Closing: the spec-level item is done and the other two have either been superseded or belong outside this repo. The two SDK asks would be better tracked in the SDK repos or Sendspin/conformance — they're real, just not spec text.

---

Generated by Claude Code