jam-cloud/web/ai/native-client-2p-recording/contract-matrix.md

Native 2P Contract Matrix (Join + Mute/Volume)

Sources:

• web/ai/native-client-2p-recording/20260228-210957-seth-native-2p-mute-volume.log
• web/ai/native-client-2p-recording/20260228-211006-david-native-2p-mute-volume.log

Intent

Define what web-client mode must preserve vs what can diverge while keeping frontend/backend control-plane behavior aligned with native.

Tier A: Must Implement (Behavioral)

These methods/events directly participate in join/session lifecycle, participant presence, and mute/volume controls.

Surface	Item	Baseline Evidence	Web-client Requirement
jamClient method	JoinSession	seen once per join	Must execute and transition session state; trigger equivalent downstream flow
jamClient method	LeaveSession	seen on session exit	Must execute and clean state/media
jamClient method	SessionPageEnter	seen on session page load	Must return compatible object shape for existing guards
jamClient method	SessionRegisterCallback	seen before runtime events	Must store callback name/handler and route bridge events
jamClient method	RegisterSessionJoinLeaveRequestCallBack	seen in david run	Must preserve callback registration behavior
jamClient method	ParticipantJoined / ParticipantLeft	seen in session lifecycle	Must keep participant state transitions consistent
jamClient method	ClientJoinedSession / ClientLeftSession	seen in david run	Must preserve per-client lifecycle notifications
jamClient method	SessionGetAllControlState	49/71 calls	Must provide control-state snapshot consumed by UI/stores
jamClient method	SessionSetControlState	54/46 calls	Must apply mute/volume changes and keep UI+server pattern aligned
jamClient method	getConnectionDetail	high-frequency polling	Must provide values needed by connection UI/presence logic
jamClient method	P2PMessageReceived	30/32 calls	Must process incoming signaling/control payloads
jamClient method	UpdateSessionInfo	periodic updates	Must keep session metadata refresh behavior
jamClient method	SessionSetConnectionStatusRefreshRate	seen twice each	Must preserve periodic status cadence behavior
REST	POST /api/sessions/:id/participants	once per join (both logs)	Must remain one POST per join action
REST	PUT /api/sessions/:id/tracks	repeated during mute/volume ops	Must keep same endpoint/method semantics for track control
REST	GET /api/sessions/:id	repeated polling/refresh	Must maintain session refresh cadence compatible with stores
REST	GET /api/sessions/:id/history	seen once	Must preserve join/session hydrate flow
REST	DELETE /api/participants/:client_id	seen once per leave	Must preserve leave teardown semantics
websocket receive	PEER_MESSAGE	dominant event type	Must preserve message class and dispatch path
websocket receive	TRACKS_CHANGED	seen during control updates	Must preserve track refresh trigger behavior
websocket receive	SESSION_JOIN / SESSION_DEPART	seen during presence changes	Must preserve participant presence events
websocket send	PEER_MESSAGE	dominant outbound type	Must preserve signaling/control channel pattern

Tier B: Must Exist, Stub/Approximation Acceptable

These are invoked but not critical to core web-to-web mute/volume MVP.

• IsNativeClient (web mode should return false; callsite guards required)
• getClientParentChildRole, getParentClientId
• SessionSetUserName, LastUsedProfileName, SetLastUsedProfileName
• FTUEGetExpectedLatency, FTUEGetChannels, FTUEGetAllAudioConfigurations
• FTUEGetGoodAudioConfigurations, FTUEGetConfigurationDevice, FTUEGetChatInputVolume
• FTUECurrentSelectedVideoDevice, FTUEGetVideoCaptureDeviceNames, FTUEGetVideoShareEnable
• FTUEGetStatus, FTUEGetCaptureResolution, FTUEGetCurrentCaptureResolution
• GetNetworkTestScore, NetworkTestResult, GetOSAsString, getOperatingMode
• SessionSetAlertCallback, RegisterVolChangeCallBack, setMetronomeOpenCallback
• OnLoggedIn, ClientUpdateVersion, ResetPageCounters, ReloadAudioSystem, SetLatencyTestBlocked, SetVURefreshRate, SetScoreWorkTimingInterval, SessionGetMacHash, IsAudioStarted, IsAppInWritableVolume

Tier C: Deferred / Native-Only (safe to keep null/no-op in web mode)

• VST and MIDI surface:
  • hasVstAssignment, IsVstLoaded, VSTListSearchPaths, VSTListTrackAssignments, VSTListVsts, VST_GetMidiDeviceList, VST_ScanForMidiDevices
• Legacy recording-manager hooks not needed for current web MVP:
  • RegisterRecordingCallbacks, RegisterRecordingManagerCallbacks

Parity Rules for Automated Comparison

1. Join cardinality: exactly one join-dedupe.create and one participant POST per user join action.
2. No duplicate in-flight join: no join-dedupe.reuse during normal single-click join.
3. Track-control behavior: mute/volume actions must produce PUT /api/sessions/:id/tracks updates and corresponding TRACKS_CHANGED/refresh behavior.
4. Control-plane continuity: websocket PEER_MESSAGE send/receive remains active during session runtime.
5. Leave behavior: one participant DELETE on leave and participant/session teardown events observed.

Immediate Build Order

1. Implement Tier A WebJamClient methods with stable return shapes.
2. Integrate WebRTC signaling over existing PEER_MESSAGE path for web-client mode.
3. Wire mute/volume UI actions to existing track control flow (SessionSetControlState -> REST + state updates).
4. Add parity checks against rules above using collected debug-log artifacts.