Announce hosted rooms on the Statement Store

[knzeng-e]

Outcome

Hosted rooms are announced on the Statement Store, so a room can be discovered without Dotify's signaling server. Step 3 of the sequence in #116.

Off by default. Stacked on #118.

The constraint that shaped everything

This is discovery only, and that boundary is load-bearing rather than a limitation I settled for.

A WebRTC offer is 1.5–4 KB against a 512-byte statement ceiling, and the per-account total is 1024 bytes — so a peer cannot hold even one SDP. But the arithmetic is the lesser problem. A guest would have to publish an answer to complete a handshake, and publishing requires an identity and an Individuality allowance.

Moving the join path here would convert every listener into a registered person. That does not degrade the product — it deletes the gesture it exists to protect. So only the host publishes, because the host is already identified, and the share link stays the way in: no wallet, no account, no chain.

Design consequences of the byte budget

One account holds at most two full statements, so naive publishing would exhaust it in a couple of heartbeats.

• Per-room channel gives last-write-wins, so a hosted room occupies exactly one live statement no matter how often it refreshes.
• Budget checked against post-write state, so the beacon that would overflow is the one refused. The chain enforces this by silently rejecting the write, which a user experiences as a room that never appears — an explainable local refusal is strictly better.
• Byte length is authoritative, not character count. A 40-character host name of emoji is 160 bytes; the tests cover that.
• Optional fields shed first when space runs out, so discovery degrades to "a room exists here" rather than failing to announce.

Privacy is a choice here, not a default

A beacon carries the room code, host display name, and an aggregate listener count — never listener identities.

Now-playing is opt-in per host. A beacon is globally readable and outlives the room by up to the retention window, so publishing what someone is listening to is a materially different exposure than sharing a link with a friend. It stays a deliberate act.

Everything received is re-parsed as untrusted — statements come from arbitrary accounts, so a malformed beacon is dropped rather than allowed to break a discovery list, and remote values are clamped before display.

Host container and cost

Host mode signs through the product's allowance account via the RFC-10 sponsored path, so hosting does not require the listener to hold an Individuality allowance of their own.

The client runs only inside the Product host container, so validateProductionEnvironment rejects VITE_DOTIFY_ROOM_BEACONS=on without a host mode — otherwise the build ships chain code that can never connect.

Build	Total bytes
default (off)	4,586,410
VITE_DOTIFY_ROOM_BEACONS=on	4,611,051

Enabling costs ~24 KB. A build with it off still carries a ~69 KB statement-store chunk that is never fetched — Rollup emits a chunk for the nested dynamic import before it can prove the build-time guard makes it unreachable. That is ~1.5% of the bundle and never executes, but I said I would keep it at zero, so it is measured and documented rather than claimed away.

Review guide

1. web/src/features/rooms/roomBeacon.ts — the encoding and the budget rules.
2. web/src/features/rooms/roomBeaconPublisher.ts — scope limits and fail-quiet behaviour.
3. web/src/hooks/useRoomBeacon.ts — kept out of useSession so the room lifecycle stays readable; the ref is written in an effect, not during render.

Verify carefully

• A beacon can never carry SDP, chat, or listener identities.
• Now-playing genuinely stays opt-in.
• A statement-store failure cannot interrupt hosting.
• The 512 B / 1024 B bounds hold for multi-byte text.
• Whether the ~69 KB never-fetched chunk is acceptable.

Validation

Evidence	Result
cd web && npm run test:unit	269 pass (+32: 17 encoding, 12 publisher, 3 env guard)
cd web && npm run test:signal	49 pass
cd web && npm run lint	0 errors; the 3 pre-existing warnings remain
cd web && npm run build	pass — 4.4 MB
cd web && npm run build:product-devnet	pass — 4.4 MB
cd web && npm run smoke:production-env	pass
node scripts/backlog-sync.mjs --check --offline	pass
git diff --check	clean

Known limitations and follow-ups

Not exercised against a live Statement Store. Every path is tested through an injected transport; the SDK client cannot run outside a Product host container, so real publish/subscribe evidence needs a run inside the host — the same gate as the rest of the Product work.

Discovery is not yet surfaced in the UI. subscribeRoomBeacons exists and is tested, but nothing renders a discovered-rooms list. That is deliberate: the reading side should land with a real design for how a discovered room is presented, rather than a debug list.

Retention outlives the room. A beacon persists up to the store's retention window after a room closes, so a discovery list must treat entries as hints and confirm liveness on join. Refresh is 30 s against a 90 s TTL, so one missed beat does not drop a room.

---

Review round: all six comments addressed

Thanks — the two P1s were both real, and the second one would have shipped a visible bug.

[P1] The capability was unreachable through the documented deploy

Correct, and worth stating plainly: .env.product-devnet omitted the flag and deploy:product-devnet always rebuilds in that mode, so the published build announced nothing.

Resolved by keeping it off — but as a deliberate, documented choice rather than an omission. Nothing reads beacons yet, so publishing room records to a public chain would be exposure with no consumer, and the publish path has no live host evidence. Enabling also costs ~24 KB against the Bulletin quota.

• VITE_DOTIFY_ROOM_BEACONS=off is now explicit in the tracked profile, with the reasoning inline
• npm run build:product-devnet:beacons / deploy:product-devnet:beacons give the opt-in path
• deployment-configuration.md carries the selected value and rollback
• the runbook has a Room Beacons (Dormant By Default) section: prerequisites, enabled-build command, a live evidence procedure that names each failure reason, and rollback

This PR is a dormant capability, not an active outcome.

[P1] Expired rooms were never evicted

You identified the mechanism exactly: the store removes an expired record but sends no deletion event, and BeaconClient was narrowing expiry away.

Expiry is now preserved and decoded (seconds in the upper 32 bits), entries are filtered on read and swept on an interval, onChange fires only when the visible set actually changes, and an already-expired statement is ignored on arrival rather than shown then swept. A transport that omits expiry falls back to an assumed lifetime instead of reintroducing the never-evicting behaviour. Three fake-timer tests cover it.

[P2] The budget check was over-claimed

Scoped honestly rather than defended. The comment now states it sees only this instance's writes. announce returns an outcome: quota-local is named as the per-instance guard, and a network refusal is reported separately as rejected with the account-wide quota called out. The hook logs refusals instead of discarding them. Kept the local check — it catches the one case this instance can cause — but the network is the authority and the code says so.

Naming, and the two code-quality points

Single-letter wire fields are gone: version, listenerCount, title, artist. They cost ~40 bytes of keys against a 512-byte ceiling, which the budget affords, and a wire format gets read by people debugging a live room. Noted in a comment so the trade-off is not silently reversed.

beaconByteLength is now the single measurement entry point, used via a tooLarge() helper. Not snapshotted into one variable, and that is deliberate: every shed step changes the serialized bytes, so a cached length would be stale by the next check. The reasoning is in the comment.

On the OR suggestion — not merged, and the reason is substantive: the two lines delete different fields and each condition must be re-evaluated after the previous deletion, so an OR would drop only one. The duplication you were pointing at is gone anyway, since both now read if (tooLarge(beacon)).

From the review body

• Hook lifecycle extracted into startRoomBeaconLoop, so start, refresh, cancellation, and the stop-during-connect race are testable as plain logic. Done this way rather than adding a renderer dependency for one file, matching the repo's existing hook-test convention.
• Roadmap and architecture no longer describe Statement Store presence as proposed.

Re-verified

Evidence	Result
npm run test:unit	278 pass (was 269)
npm run test:signal	49 pass
npm run lint	0 errors; 3 pre-existing warnings
npm run build	4,586,370 bytes
VITE_DOTIFY_ROOM_BEACONS=on npm run build:product-devnet	4,611,821 bytes
npm run smoke:production-env	pass
node scripts/backlog-sync.mjs --check --offline	pass
git diff --check	clean

[knzeng-e]

Careful review completed against the PR diff, the exact installed @parity/product-sdk-statement-store@0.6.2 implementation, the existing room lifecycle, and the Product deployment path.

The payload boundary is well scoped: it keeps SDP/ICE/chat/audio out, preserves wallet-free guest joining, validates untrusted JSON, and treats Statement Store failure as additive. Automated evidence also reproduces locally: 269 unit tests pass, 49 signaling tests pass, lint has 0 errors and the 3 existing warnings, git diff --check is clean, and VITE_DOTIFY_ROOM_BEACONS=on npm run build:product-devnet passes.

I would not treat the draft as merge-ready yet because the normal Product build leaves the capability disabled and the reader retains expired rooms indefinitely. I also left an inline note on the account-wide quota claim, which the local map cannot enforce.

Documentation is still out of sync with the architectural change: docs/operations/deployment-configuration.md and docs/operations/product-devnet-deployment.md do not contain the flag, operator prerequisites, enabled-build command, live publish/subscribe smoke, or rollback; web/.env.product-devnet omits the value; and the roadmap/public architecture material still describes Statement Store presence as proposed/future. Per AGENTS.md, this PR changes deployment settings and architecture narrative, so those sources should be updated in the same PR. A focused hook lifecycle test would also close the remaining timer/cancellation coverage gap. Live host evidence can remain a clearly stated draft prerequisite, but the runbook should say exactly how to collect it.

[knzeng-e]

[P1] The standard Product deployment never enables this feature. web/.env.product-devnet does not set VITE_DOTIFY_ROOM_BEACONS, and npm run deploy:product-devnet always rebuilds in product-devnet mode, so the documented deploy command produces the off build and no host ever announces a room. Either enable the flag in the tracked Product profile, or document an explicit opt-in build/deploy command and describe this PR as a dormant capability rather than an active outcome. The selected value and rollback/smoke procedure also belong in docs/operations/deployment-configuration.md and the Product deployment runbook under the repository's env/config rule.

[knzeng-e]

Addressed. You were right that the documented deploy could never enable this. Resolved by keeping it off but making that a deliberate, documented choice rather than an omission: nothing reads beacons yet, so publishing room records to a public chain would be exposure with no consumer, and the publish path has no live host evidence. VITE_DOTIFY_ROOM_BEACONS=off is now explicit in .env.product-devnet with the reasoning, npm run build:product-devnet:beacons / deploy:product-devnet:beacons provide the opt-in path, and both deployment-configuration.md and the runbook now carry the selected value, prerequisites, enabled-build command, live evidence procedure, and rollback. The PR is described as a dormant capability.

[knzeng-e]

[P1] Expired statements remain in this map forever. In SDK 0.6.2 the subscription callback includes the statement's expiry, but BeaconClient narrows the callback to { data }, so this listener cannot prune by TTL. The Statement Store removes an expired record; it does not send this code a deletion event. Consequently, after one beacon is received, beacons() and onChange can continue returning that room for the lifetime of the page even if the host stops and the 90-second statement expires. Preserve the expiry metadata, evict records at expiry (and notify onChange), and cover it with a fake-timer test before this is used by discovery UI.

[knzeng-e]

Fixed, and you identified the mechanism exactly: the store removes an expired record but sends no deletion event, and BeaconClient was narrowing expiry away. Expiry is now preserved and decoded (seconds live in the upper 32 bits), entries are filtered on read and swept on an interval, onChange fires only when the visible set actually changes, and an already-expired statement is ignored on arrival rather than shown then swept. A transport that omits expiry falls back to an assumed lifetime instead of reintroducing the never-evicting behaviour. Three fake-timer tests cover it.

[knzeng-e]

[P2] This is not an account-budget preflight. live only knows about successful writes made through this one publisher instance; it cannot see statements from another tab, another Dotify instance, or any other use of the same allowance account. In the shipped hook this publisher owns at most one current room, so the 12-room test exercises a state the app cannot create while real account-wide contention remains invisible. The reason is also discarded and the hook ignores false, so the refusal is not explainable to an operator or user. Please either replace this with account-aware evidence from the host/SDK, or scope it honestly as a per-instance heuristic and add observability for network quota rejection.

[knzeng-e]

Agreed on all three points, and I have scoped it honestly rather than claiming more.

The comment now states plainly that this only sees writes from this instance and cannot observe another tab, another Dotify instance, or any other use of the same allowance account. announce returns an outcome instead of a bare boolean: quota-local is named as the per-instance guard, and a network refusal is reported separately as rejected, with the account-wide quota called out as the likely cause. The hook logs refusals rather than discarding them, so an operator debugging an undiscoverable room has something to read.

I kept the local check because it does catch the one case this instance can cause, but the network is the authority and the code now says so.

[knzeng-e]

Better to use meaningful fields/variable names (ex: listenerCount or nbListeners - maybe the first one, to have accurate naming across RoomBeaconInput as well). This should be a rule of thumb

[knzeng-e]

Agreed, and applied as a rule rather than a one-off: v/n/t/a are now version/listenerCount/title/artist across the type, builder, parser, and tests. The names cost roughly 40 bytes of keys against the 512-byte ceiling, which the budget can afford — and a wire format is read by people debugging a live room, so the saving was not worth the opacity. Noted in a comment so the trade-off is not silently reversed later.

[knzeng-e]

Couldn't those two line be rewritten in a single || (OR) conditioned one ?

[knzeng-e]

Not merged, and I want to explain why rather than just decline. The two lines delete different fields, and each condition must be re-evaluated after the previous deletion — an OR would collapse them into one branch and drop only one field. What I did instead is remove the duplication you were pointing at: both now read if (tooLarge(beacon)), so the repeated measurement expression is gone even though the two statements stay separate.

[knzeng-e]

we called several times byteLength(beacon) in this code. Maybe worth extract/snapshot it in a single variable at the beginning ? unless this is a dynamic value we need to keep track of ?

Furthermore, why not reusing the beaconByteLength function ?

[knzeng-e]

Both applied. beaconByteLength is now the single measurement entry point — the call sites use a tooLarge() helper built on it, and assertBeaconBudget uses it too. It is deliberately not snapshotted into one variable: every shed step changes the serialized bytes, so a cached length would be stale by the next check. That reasoning is now in the comment so it does not look like an oversight.

[knzeng-e]

reviewed