Pairing: build a rolling waiting room (room bucketing, ghost expiry, odd arrivals)

[htsukamoto5]

Update (2026-09-16): The proposed backend direction has changed from Firebase to JATOS. The original issue below is retained as historical context; see the latest comments for the current allocation, presence, DataPipe, and verification plan.
Phase 2 — BLOCKED on adapter-multiplayer-firebase publishing. Largest single piece of missing work in the audit.

Two participants must find each other. What exists today is a two-tab-on-one-machine pilot rig, not a waiting room.

Important: a rolling waiting room is not something the Firebase adapter gives us. plugin-multiplayer-sync and plugin-multiplayer-role are per-session barriers, not a matcher. Room assignment has to be written on top.

What has to be built

• Room bucketing — assign arrivals to two-person rooms as they show up, rather than assuming a private session that both partners already share via a pasted URL.
• Stale-room expiry / ghost handling. wait_for counts any group entry carrying a name, and the adapter only removes an entry on an explicit disconnect() — there is no heartbeat and no beforeunload anywhere in the four bundles. A tab closed in the lobby leaves its entry behind. With persistent Firebase room state a live participant will be matched with a ghost, assigned a role, and then time out on every single round. Silent, and frequent.
• Odd-arrival handling — currently the overflow spectator path is a dead end with no completion code.
• Concurrency policy. Pair-based studies need participants simultaneously, which Prolific does not guarantee. Launching in a tight burst rather than leaving the study open is the main lever, which makes the waiting room and its timeout policy load-bearing on cost, not just UX.

Related unblocked work: the lobby timeout and payment paths can be done now, independently.

See READINESS.md section 1.

[htsukamoto5]

Caution when fixing ghost entries: beforeunload → disconnect() would truncate transcripts

Flagging an interaction found while verifying the audit against the bundles, because the obvious fix for the ghost-entry bullet above has a non-obvious cost.

Chat messages are written into the sender's own group entry — the send path does T.push({...d, [M]: p}) against the local participant id — and chat_transcript is derived from the group snapshot at round end, not from a locally accumulated array. disconnect() in adapter-multiplayer-local.js removes the participant's entry outright.

So the partner's half of the dialogue survives a dropout today only because a closed tab never calls disconnect() — the same missing beforeunload that causes the ghost entries. The two behaviours are the same gap seen from opposite sides:

	ghost entries	transcript
today (no beforeunload)	❌ stale entry can satisfy wait_for	✅ full dialogue survives
naive beforeunload → disconnect()	✅ entry cleared	❌ partner's messages vanish from the survivor's data

That second failure is silent and lands on exactly the sessions #5 exists to salvage: the survivor's saved rows would carry their own messages and message_count computed over a truncated transcript, with no error.

Implication for the ghost-expiry work: expire entries by staleness (heartbeat/timestamp, ideally Firebase onDisconnect writing a tombstone) rather than by deleting them, so a departed participant's contributed data stays readable while no longer counting toward wait_for / ready. If any beforeunload → disconnect() handler does get added, the round data must be flushed (#3) before the entry goes.

Relates to #3, #5, #11.

[htsukamoto5]

No scheduling shortcut exists — and build this defensively

Two findings that bear on how this gets built.

Prolific has no appointment or slot-booking feature

Checked, because if it existed it would have reduced the scope of this issue. It does not. Prolific's position is explicit:

"Prolific cannot fully support studies that require participation or completion within a specific time window"

— including completion at a particular time of day, and such studies are "conducted at the researcher's own risk." (source, verified 2026-07-30)

The only scheduling control is schedule publish — choosing when the study goes live. That governs when participants can start, not when they do. So burst launch is the entire simultaneity lever, and none of the room-assignment work here can be delegated to the platform.

(For completeness: longitudinal projects provide scheduled waves with guaranteed participant ordering. Not slot booking, but it is the machinery a two-study panel approach would use if that is ever revisited.)

Build defensively — the concurrency test is weak by construction

Pre-launch validation (#12) covers waiting-room logic with 6–8 coordinated testers and scripted arrival patterns, which is genuinely good for correctness bugs. But the staged first tranche is only ~3–4 dyads, so real concurrency gets its first proper test on the first full run.

That asymmetry should shape the implementation rather than the test plan:

• Idempotent room assignment — assigning the same participant twice must be a no-op, not a second room.
• Tolerate duplicate and stale entries rather than assuming they cannot occur. Per the earlier comment on this issue, expire by staleness (timestamp / tombstone) rather than deletion, so a departed participant's contributed data stays readable while no longer counting toward wait_for / ready.
• Fail closed on ambiguity. If room state is inconsistent, route the participant to the no-match exit with a payment path (Pairing: lobby waits unbounded — add timeout, no-match exit, and payment path #6) rather than into a room that may be broken. A paid no-match is cheap; a silently broken dyad costs two payments and produces confounded data.

[htsukamoto5]

Proposed update: use JATOS allocation, retain DataPipe

The proposed architecture has changed since this issue was opened.

JATOS group studies can own rolling group allocation, so we no longer propose building Firebase room bucketing in this study. Configure a JATOS group-study batch for two active members, admit participants based on live group channels, and fix/seal the group at the lobby-to-game boundary so nobody can be inserted as a replacement after play begins.

Upstream jspsych-multiplayer PR #88 is the current review packet for the missing adapter capabilities. It keeps retained Group Session data separate from connection presence and adds a stable group ID, immutable membership/channel snapshots, lifecycle subscriptions, and an idempotent group-sealing operation. CI is green, but live JATOS verification remains required before the study should depend on it.

DataPipe remains the proposed authoritative incremental research-data destination. JATOS supplies allocation and live communication; it does not replace the tested per-round, retry-aware DataPipe pipeline. Revisit the cost of operating both services only after an infrastructure pilot, and do not remove DataPipe without equivalent partial-data retention and terminal-route flushing.

PR #18 already supplies the bounded participant-facing wait, paid no-match route, defensive overflow/pairing-timeout handling, and exactly-one-terminal-screen tests. Those study-specific policies remain here rather than moving into the adapter.

Next steps

1. Test PR #88 with live JATOS using maxActiveMembers = 2 and initially leave maxTotalMembers unset.
2. Verify ordinary pairing, pre-game timeout followed by reuse, simultaneous sealing, transient reconnect, abrupt close, post-seal non-replacement, and the timeout/join boundary race.
3. Request upstream review of the adapter API and semantics.
4. Based on observed behavior, design a reusable lobby layer upstream without embedding Prolific, DataPipe, or C&WG policy.
5. Consider an optional jsPsych-core presence capability only if the working lobby exposes a genuine cross-adapter need; matchmaking itself remains backend-specific.
6. Integrate JATOS into C&WG on a focused branch, derive DYAD_ID and SEED from the shared JATOS group ID, retain DataPipe, and coordinate saving/departure/completion through one idempotent terminal path.

The maxTotalMembers choice needs live verification. A limit of two may count a pre-game timeout as a historical member and prevent two later active participants from completing that group. The current hypothesis is unlimited total membership before admission, followed by sealGroup() as soon as two live participants enter the game.