veratown-prototype

Shower System

Runtime configuration receipts

A real shower entry applies validated settings to the eligibility gate and the new session’s timing, then reports that settings revision/time through the room-scoped heartbeat. Disabled settings count as applying a disabled entry gate. Initial position seeds, startup and repository reads alone do not count. Settings-read failures retain the historical receipt and report only a fixed safe identifier; later successful real entries clear the error. There is no settings watcher, so no pending-next-interaction revision is inferred from writes. Mid-session enabled-only checks do not report adopting changed timing, existing sessions keep their timing, and song revisions remain outside this receipt. It does not confirm clothing actions or live BC state.

The shower feature runs an optional, room-scoped sequence when another room participant enters an enabled point location with type: "shower". It uses the existing world-location store, permission-checked appearance actions, the single BC connection, and BC room updates as appearance observations. The feature and all songs are disabled until an administrator configures them.

Requirements

1. Create an enabled point location. Use !world location create and answer:
   • a unique key, such as bath-house
   • a descriptive name
   • shower for the type
   • the actual X/Y tile
   • skip region geometry
   • optional label and description
   • yes to enable it
2. BC must provide the participant’s room/appearance state and grant wardrobe access. Local inbound room updates are sufficient; a separate helper bot and cross-process observation sharing are not required.
3. Add administrator-provided original or public-domain song text and enable the song. No song text or lyrics are seeded by the application.
4. Explicitly enable the shower feature after reviewing the dedicated-account qualification caveat below.

shower_bot_home is unrelated and is not required. Region locations do not trigger the shower system; a shower is a point location with a real map tile.

Room-admin commands

All commands are available as /bot world ... or !world ...; replies are private whispers. Room-admin permission is checked before each command.

!world shower show
!world shower song add morning | Morning song | Original or public-domain text
!world shower song list
!world shower song enable morning
!world shower set enabled true
!world shower set stepDelayMs 1500
!world shower set singDelayMs 2000

Song text is stored only in the room-scoped song collection; it is omitted from song listings, logs, and action journals. Song IDs are lowercase letters, digits, underscores, and hyphens (up to 40 characters). Titles are at most 80 characters and text is at most 500 characters. A room can have at most 50 songs. New songs start disabled.

stepDelayMs accepts 250-10,000 ms. singDelayMs accepts 0-30,000 ms. The settings document is revisioned and room-scoped; startup inserts no enabled configuration.

Optional starter catalog

npm run seed:shower-songs previews 50 original, humorous songs for the main room. It fills the catalog to 50 total songs, preserves existing entries, and never enables songs or shower settings. Review the dry-run list before applying:

RUNTIME_TARGET=production npm run seed:shower-songs
RUNTIME_TARGET=production npm run seed:shower-songs -- --apply --confirm-production

The script only connects to the database pinned by RUNTIME_TARGET; production writes require both --apply and --confirm-production. New songs are inserted through the shower repository so the room’s atomic capacity counter is used.

Runtime behavior and safety

• A startup/reconnect position seed, disabled location, region, self-entry by the bot, or disabled shower setting does not start a sequence.
• The current BC-derived room snapshot supplies the starting appearance. Each clothing step accepts the shared appearance action’s observed or already_satisfied result without an additional helper read-back. Matching inbound room updates are loosely correlated convergence evidence: sufficient for operation, not proof that this bot caused the change or that it persisted to the target account. No request ID, particular source member, independent observer, or second confirmation is required. Optional helper observations remain available to the shared action.
• The feature asks BC to authorize wardrobe access for the target. A denied, missing, or timed-out permission result stops the sequence. Every clothing change uses the existing serialized BcAppearanceAction; no raw packet sender or second socket is introduced. A removal rejected before emission because its BC observation became stale gets one fresh permission check and re-planned attempt, with both attempts journaled. No other failure or unobserved write is blindly retried.
• Only supported, unlocked clothing is considered; the Jewelry group is deliberately excluded from shower changes. Body/cosplay and otherwise unsupported items are left unchanged. CocktailDress is supported using its observed ClothOuter slot despite its pinned DynamicGroupName metadata. HasBreasts prerequisites are evaluated only from an observed BodyUpper asset named Small, Normal, Large, or XLarge; absent, flat, or unknown body state fails closed. Catalogued crafted clothing is removed and restored with its exact observed craft metadata; that metadata remains process-local and is never journaled or persisted. Each candidate must pass the shared codec’s removal and restoration preflight, including a round-trip appearance comparison. The comparison accounts for BC omitting default typed or modular selections, but does not waive differences in non-default selections or other observed appearance state. Dynamic or otherwise unsupported BC rules, unsupported configurations, or unsafe restoration leave that item untouched and report a warning with safe asset identifiers; supported clothing can still be processed. The complete planned restoration is also checked before any clothing change. Each mutation is journaled; appearance payloads and song text are not journaled.
• A successful run narrates the shower start, selected song, rinse, and wind-down, restores supported clothing, then sends a private completion whisper. Completion is not claimed if restoration fails or the sequence is interrupted.
• The shower sequence stops if the participant leaves, the connection changes, settings are disabled, or an action has no matching BC observation. During a graceful stop or tile departure it attempts permission-checked restoration only while the participant remains observed in the same room and the connection remains usable. A disconnect, room departure, process crash, or unconfirmed action may require manual recovery. Original clothing snapshots exist only in bounded process memory; they are never persisted.
• The feature is registered after helper bots and stops before BC closes, so graceful restoration can still use live room updates and optional helper observations.

Persistence

The runtime-selected isolated database owns:

• prototypeShowerConfig: one strict, revisioned settings document per room.
• prototypeShowerSongs: bounded room-scoped song catalog.
• prototypeShowerSongCounts: atomic room-level song-capacity counters.

Locations remain in veratownLocations. None of these collections is included in the source-database configuration-copy allowlist. Existing database target guards continue to restrict production and test runtime databases.

Qualification status

Unit and fake-socket tests cover the permission gate, third-party action payload, observation matching, sequence ordering, and restoration. They do not prove that the live BC server grants a particular target permission or accepts an appearance update.

On 2026-10-23, the operator reported that all live qualification cases passed on commit 928f6f9, using a dedicated test account, a non-production room, RUNTIME_TARGET=test, and veratown_prototype_test. Reported cases included denied/unknown permission, normal removal and restoration, tile departure, timeout/unconfirmed action, graceful shutdown, disconnect/reconnect, and settings changes. The assistant did not observe the run. No account details or credentials are recorded. This test-runtime qualification does not qualify a production account or database. The feature remains disabled by default.