Hospital Instancing Specification

Status

Current repository artifact for IARPG-OPS-2 2.0.13-wip. Claim-review status: reviewed with limitations. The preserved source body remains unchanged as provenance, while the Reviewed Synthesis section records the current publication decision. Only that reviewed synthesis may be reused as current factual or design guidance; archival source prose remains non-authoritative unless a claim is explicitly dispositioned below.

Purpose

Preserve the supplied research as a canonical durable report, make it individually addressable under /docs/long-term-memory/reports/, and connect its current design implications to compact .uai startup memory without duplicating the full body in hot memory.

Scope

This report covers the research and design questions contained in Hospital Instancing Specification.md. It is authoritative for repository provenance, routing, and preservation. It is not automatically authoritative for current law, clinical guidance, platform policy, market facts, technical capability, or production implementation.

Executive Summary

This report is retained as an instancing and session-design proposal. Its current publication value is limited to fictional design hypotheses that comply with dignity, non-stigmatization, consent, accessibility, and human-rights boundaries. The review applies claim-by-claim dispositions for current law, public institutions, clinical and rights guidance, age and consent, products, vendors, market assertions, software capabilities, design parameters, and comparative fairness. Unsupported or time-sensitive source statements are corrected, bounded, omitted, or retained only as design hypotheses.

Evidence Reviewed

• Preserved source file
• Source collection: saudi-intelligence-security-apparatus-archive
• Source SHA-256: 8ca654dc486dffa0dd514fb9e248811fab292971fce9686964d25536bcd0d556
• Claim-review register
• [Claim-level review and comparative fairness audit](claim-level-review-and-comparative-fairness-audit.md#findings)
• WHO/OHCHR — Mental health, human rights and legislation
• NIMH — Understanding Psychosis
• WHO — Guidance on community mental health services
• Complete source-to-report map
• Provided-report intake audit

Reviewed Synthesis

Publication Decision

Retain this report as the canonical repository copy of Hospital Instancing Specification.md. The source body below remains preserved for provenance and research history, but its factual assertions do not steer current product or public claims unless they appear in this reviewed section. Review completed for 2.0.13-wip; re-check date-sensitive items before later publication.

Claim Dispositions

Comparative Fairness and Rights Boundary

Mental-health services, disability, diagnosis, and care vary across cultures and jurisdictions. Review must include people with lived experience, local terminology, rights law, and service context; no one system is treated as the global norm.

Reuse Rule

Use the smallest applicable corrected statement above, preserve its jurisdiction and date boundary, and cite the listed primary or authoritative source. Do not quote the archival source body as current fact without a new claim review.

Findings

Archival source boundary: The material below is preserved source-derived analysis. It may contain stale, unsupported, stigmatizing, culturally narrow, overly actionable, or product-specific claims. The Reviewed Synthesis above—not the archival prose below—is the current repository publication decision.

Preserved Source-Derived Analysis

Hospital Instancing Specification

A hospital instance is a self-contained copy of the game area (the hospital) with its own local state. Each instance has a unique identifier (e.g. a UUID), and tracks its human capacity (max 10 players) and current occupancy. It also manages an NPC population budget (e.g. a target NPC-to-player ratio) to sustain ambient “social density” without crowding. Instances have a story phase or difficulty band (e.g. tutorial, alert, emergency) that determines which narrative events and NPCs are active. Key instance fields include:

• InstanceId: unique ID (UUID or similar).
• Capacity: hard limit of 10 human players. (Beyond a soft cap, new players are funneled into new instances rather than filling the old.)
• NPCBudget: number/type of NPCs allowed (e.g. base core NPCs + rotating extras).
• StoryPhase: enumerated stage (e.g. Intro, Lockdown, Aftermath). New players can only join if their own progress is compatible with the instance’s phase.
• ProgressionBand: coarse difficulty or progression tier to match players (e.g. early-game vs late-game).
• CreationTime: UTC timestamp when instance was created.
• ActivityState: e.g. Active (players present), Idle (no players but not yet closed).
• Joinability: e.g. Open (under soft cap), SoftFull (at soft cap, may queue), Full (hard cap reached). GW2’s “soft cap” concept applies – once an instance is near capacity it may stop auto-filling.
• EventState: current global events (e.g. None, CodeBlueEmergency, PandemicAlert).
• CleanupState: e.g. Pending, InProgress when tearing down or resetting.
• Archival/Destruction: rules for shutting down an instance (e.g. “no players for 10 minutes after last exit” or “story completes and all players have left”).

By default instances are ephemeral (in-memory) and must load any persistent data from a database (e.g. inventory or world state) at creation. The system must never expose technical IDs in game language – use story terms instead (e.g. “Wing A” vs “Shard #12”).

Instances should also manage capacity backfilling: prefer to route new players into existing partially-filled instances rather than creating empty ones. For example, the Agones Kubernetes framework shows this approach: it “attempt[s] to find an already Allocated GameServer…with room for N players, and if one is not available, [allocates] a Ready one”. Similarly, our placement logic will check existing instances (in descending occupancy) before spinning up new ones.

Player Placement Decision Table

Condition,Action,Notes
Solo player arrives; compatible instance with open slot exists,Place player into that instance,"Preserves social density and avoids unnecessary new instances"
Solo player; no compatible instance or all are full,Create a new instance and place player,"Instance meets story and difficulty needs; new instance may inherit appropriate phase"
Party of 2–10; an existing instance has >=party size free and story-compatible,Place entire party in that instance,"Keeps party together; respects story compatibility"
Party of 2–10; no single instance has enough slots, but splitting allowed (party > remaining capacity),Split party into two instances or create new instance,"Prefer minimizing splits; if unavoidable, form two groups with minimal separation"
Party size >10 (above hard cap),Reject or split party,“Party exceeds capacity; offer to split into sub-parties or queue subset, ensuring no loss of progress”
Friend is already in a full instance; new player arrives,Move to a new compatible instance or ask friend to relocate,"Cannot join full instance; may create a new instance for both, or keep player in queue until spot opens"
Player reconnecting (reservation exists) and original instance has slot,Rejoin original instance,"Avoid duplicate avatar; use reservation token to restore state"
Player reconnecting; original instance is gone,Place into next suitable instance or create new one,"Personal progress persists; send player to equivalent story location"
Player is blocked by someone in instance,Skip that instance; try another or create new,"Ensure no blocked players occupy same instance; prevents harassment repeat"
Under tutorial/story phase, tutorial incomplete,Force placement in tutorial instance,"Ensure new players start appropriate content; do not skip tutorial prematurely"

This table summarizes key placement rules. Whenever possible, a party is kept intact and placed in one instance. New instances are only created when no existing instance can accommodate the group (size, story, blocking constraints).

Instance Lifecycle State Machine

We propose a finite-state model for each instance, with these primary states and transitions:

• CREATING – Instance is being set up (server allocated, world state initialized).
• WARMING – Instance is running but not yet open (loading assets, running startup events).
• JOINABLE – Players may join freely. (Default open state.)
• NEAR_CAPACITY – Instance has reached its soft capacity threshold; it may stop auto-filling and direct new players elsewhere (akin to a GW2 “soft cap”).
• FULL – Hard cap of 10 human players reached; no further joins allowed until someone leaves.
• DRAINING – Player count dropping (e.g. after story end or in-progress shutdown); no new joins except perhaps late re-entries.
• QUIESCENT – No players present (instance is idle).
• ARCHIVING – Cleaning up, persisting final state, and preparing to shut down.
• TERMINATED – Instance is fully closed and resources freed.
• RECOVERY – Special case (e.g. after a crash/restart) where the instance reloads saved state.

Transitions: On creation, instance → CREATING → WARMING → JOINABLE. As players join, if count hits soft cap, transition to NEARCAPACITY (semi-closed), then to FULL. When players leave, FULL→NEARCAPACITY→JOINABLE as slots free. When last player departs, JOINABLE→QUIESCENT. A scheduled shutdown or end-of-story moves JOINABLE→DRAINING (stop new joins) → ARCHIVING → TERMINATED. On errors (server crash), an instance may move from any state to RECOVERY, attempt reload, then back to JOINABLE or TERMINATED if unrecoverable.

Because container orchestration (e.g. Kubernetes/Agones) is eventually consistent (state changes may propagate with slight delay), the system must tolerate short delays in transitions. For example, it might take ~1 second for a change to register, so the design should avoid race conditions (e.g. double-check capacity before finalizing a join).

Language-Neutral Placement Pseudocode

// Attempt to place a party (size 1–10) of players into an instance.
function placeParty(party):
    if party.size > MAX_PLAYERS_PER_INSTANCE:
        // Party too large to fit; instruct splitting or queueing
        return handleOversizedParty(party)

    // If party members are already together in an instance, try to reuse that.
    if party.membersHaveCommonInstance():
        inst = party.commonInstance()
        if inst.hasSpaceFor(party.size) and inst.isStoryCompatible(party):
            if not inst.containsBlocked(party):
                assignPartyToInstance(party, inst)
                return

    // Sort candidate instances by occupancy descending (backfill fuller ones first).
    for inst in instances.sortedByDescending(occupancy):
        if inst.isAlive() and inst.isStoryCompatible(party) and inst.hasSpaceFor(party.size):
            if inst.noBlockedPlayers(party) and inst.matchesLanguage(party) and inst.matchesAccessibility(party):
                assignPartyToInstance(party, inst)
                return

    // No suitable existing instance found; create a new one.
    newInst = createNewInstance(phase=party.requiredPhase())
    assignPartyToInstance(party, newInst)
    return

Notes: We first try to keep parties intact (placing all members together). We prefer backfilling: by sorting instances by current occupancy (nearly full first), we avoid creating almost-empty instances if partly-filled ones exist (a concept similar to GW2’s “funnel” approach). We check story compatibility (the instance’s phase must allow these players to sensibly enter). We respect blocking lists, language, and accessibility needs. If no existing instance fits, we create a new one at the appropriate story phase.

Party and Reconnect Sequence

Party Joining:

• Solo player joining alone: The player sends a join request. The system runs the placement algorithm to find a suitable instance and adds the player. If all instances are full or incompatible, a new instance is created.
• 2–10 friends (party) joining together: The party leader requests matchmaking. The system treats the party as one unit and applies the placement algorithm above. All party members enter the same chosen instance.
• Party larger than remaining capacity: If an instance has space for only part of a party, we skip that instance (to avoid splitting). If no existing instance can fit the whole party, a new instance is created to hold them together. If the party itself exceeds 10, they are notified they must split (e.g. “Only up to 10 can play together; please split into multiple groups”).
• Party of more than 10: Notify the group that the party must split (e.g. top 10 go, rest wait or form another instance). This is a clear outcome, not destructive.
• Joining a friend whose hospital is full: Because the target instance is full, we cannot insert the new player there. We may either create a new instance for both (if the friend is willing to move), or simply place the newcomer elsewhere. The friend can be offered an exit/teleport option to join the new instance.
• Party member disconnecting: The disconnected player retains a reserved spot for a limited grace period. The avatar remains in the instance (invisible or safely queued) so another player doesn’t take their place. Other party members stay; when the player reconnects, the system tries to place them back in the same instance.
• Party member in different story phase: If one member has advanced further in story, they cannot remain in an instance incompatible with that phase. Options: either we split them off (e.g. create a new instance for the lagging member) or move the group to the later phase. Usually the system will split as needed, asking players to regroup at common progress.
• Party leader leaving: Leadership passes to a designated co-leader or next-in-line. The party remains intact under new leadership. If the leader was carrying certain responsibilities (like starting an event), those transfer or reset. If the party was migrating, we ensure continuity under the new leader.
• Player declines migration: If a planned migration (e.g. moving to a new instance) requires unanimous consent and someone declines, the system should handle it gracefully. For example, it could leave the declining player behind (if instance allows) and move others, or abort the move. All outcomes must be clear to players.
• Player blocking another: If two players have blocked each other, they must not be assigned to the same instance. The placement logic checks block lists (party or personal) before finalizing placement. If only option would pair them, one player is placed elsewhere or queued with an explanation.

Reconnect Handling:

• Upon disconnect, the server generates a short-lived reconnect reservation token tied to the player’s session. This token expires after a grace period (e.g. 5 minutes).
• If the player reconnects quickly using the token, the server checks if their original instance still exists. If so, and it has an open slot (or their old spot is held), the player is restored at the same position and state (inventory, location, conversation). This avoids creating a duplicate avatar.
• If the original instance was destroyed (e.g. cleaned up for inactivity) or full, the player is placed into a suitable new instance (preferably one that matches their progress). Personal progress (inventory, completed objectives) follows them.
• If the server itself restarted, the player’s token still allows reconnection; the backend should match them to the instance or create a safe fallback location (e.g. the instance entry point).
• In all cases, reconnect attempts that look suspicious (rapid disconnect-reconnect loops) are rate-limited to prevent abuse. Duplicate sessions from the same player are rejected (only one active avatar per account).

Persistence Domain Model

Game state is classified by scope and longevity:

• Personal Persistent: Data tied to an individual player and retained across sessions. Examples: inventory items, unlocked skills, read clues, personal quest progress, account settings, reputation. This data is stored in the player’s profile in the backend database. Personal persistent state must never be lost (even if the instance ends), and no amount of instance recycling should overwrite it without consent.
• Instance Persistent: Data local to one hospital instance that persists as long as the instance exists. Examples: which doors are locked/open, the current emergency level, items taken from the environment, NPC statuses changed by players (e.g. injured NPCs), or evidence discovered. When the instance is archived or terminated, this data is typically discarded (the world resets for next run), except that certain outcomes (e.g. communal evidence) might contribute to global state.
• Global Persistent: Data shared across all instances/worlds. Examples: the hospital-wide event calendar, economic factors (e.g. supply prices), narrative season or events affecting all players, long-term world consequences of events (if any). This would be stored centrally (e.g. in a master database or configuration service).
• Ephemeral: Short-lived state that only matters moment-to-moment. Examples: player characters’ instantaneous movements, transient animations, typing indicators, temporary buffs, or music cues. These are not stored persistently.

Conflict Resolution: If a player’s personal state conflicts with an instance’s state, personal state generally prevails for that player’s experience. For example, if the player has already collected a persistent personal item in another instance, the new instance should not require them to collect it again; the game can auto-grant it or skip that step. Conversely, instance state (like a locked door) is authoritative for everyone unless a player’s inventory key (personal) overrides it. In practice, instance resets do not erase personal unlocks. For new players joining a mid-progress instance, they may be auto-teleported past completed events or given equivalent progression so that their personal story remains coherent. In general, personal progress is sticky and carries over, while instance world state is local and separate.

NPC Population and Conversation Budget

NPCs (“doctors,” “nurses,” “patients,” etc.) serve to make each hospital feel alive without overwhelming the small player groups. We propose:

• Core NPCs: Essential characters that should always exist in every instance (e.g. at least one Doctor and one Nurse on duty). They provide continuity.
• Rotating NPCs: A pool of generic NPCs (visitors, minor staff) spawned to meet a target player-to-NPC ratio (e.g. 2–4 NPCs for every 5 players). They are cycled (added/removed) as player count changes, to avoid rooms feeling empty or too crowded.
• Story NPCs: Characters tied to specific story events or phases (e.g. an injured patient appearing only during an emergency). They spawn/despawn with the instance’s event state.
• Mobile NPCs: NPCs should move between rooms on a schedule (do rounds, shift changes) to share presence. For example, a Nurse might alternate between the ward and the lab over time.
• Max Active Conversations: Limit the number of NPCs actively conversing in a single room. For instance, allow at most 1–2 NPCs to engage in dialogue with players at once. If many players try to talk to the same NPC, queue their requests or split them across time slots.
• Ambient Behavior: When no humans are present, NPCs follow simple scripts or idle routines (e.g. reading charts, standing). We avoid expensive AI computations in empty rooms; NPC schedules can pause until a player enters.
• Shared Conversation Handling: If multiple players address the same NPC, have the NPC address one player at a time, or broadcast a shared answer if the question is identical. For example, if two players ask “what happened?”, either the NPC answers the first then the second, or gives one response that both hear.
• Fair Turn-Taking: Implement a brief cooldown per player-NPC pair. Once a player finishes talking to an NPC, they should “step aside” so others can talk. If one player monopolizes an NPC (excessively long dialogue), the system politely ends or defers that interaction.
• Critical NPC Protection: Key characters (e.g. the Head Doctor) should not be blocked by others. If one player is interacting with a critical NPC, and another tries to interrupt, the second player is placed in queue or given a message like “Dr. X is occupied.” Prevent griefing where a group gates a doorway or NPC.

No NPC should be presented as “another real player.” All NPC avatars or names must clearly indicate AI control (e.g. with a symbol or dialogue tag).

Privacy-Safe Telemetry Dictionary

All telemetry must be aggregated or anonymized; no personal identifiers or IPs should be collected. For each metric, we record counts or rates, not user IDs. Example metrics:

Metric,Definition,PrivacyConsiderations
current_human_occupancy,"Number of human players currently in each instance","Aggregate count; no PII recorded"
instance_creation_rate,"Instances created per minute/hour","Aggregate rate; not tied to individual users"
instance_closure_rate,"Instances terminated per minute/hour","Aggregate rate only"
queue_wait_time,"Time a player spends in queue (distribution)","Aggregate timing statistics; no user data"
party_split_rate,"Fraction of parties that had to be split","Aggregate percentage; no party ID"
reconnect_success_rate,"% of reconnect attempts that succeed","Aggregate ratio; per-instance aggregate"
migration_failure_rate,"% of forced migrations that fail or are declined","Aggregate count; no details on players"
empty_instance_duration,"Average time instances stay empty before closing","Aggregate duration metric"
npc_response_latency,"Average time NPC takes to respond to player","Aggregate latency; no transcripts"
blocked_collision_rate,"Rate of attempts to place blocked players together","Aggregate count of blocked conflicts"
onboarding_completion_rate,"% of new players completing tutorial","Aggregate percentage; no identity"
post-placement_dropoff,"% of players leaving after forced placement","Aggregate percentage; no player identities"
room_overcrowding_events,"Instances where player count exceeded limit (should be none)","Aggregate count of errors"
critical_npc_contention,"Number of times multiple players queued for same NPC","Aggregate count; anonymized"

Each metric is collected in aggregate (per-instance or per-server) with no linkage to user IDs. No raw chat or voice is logged. Telemetry focuses on system health (counts, rates, averages) only.

Concurrency and Failure Test Matrix

The table below estimates required instances and potential risks under various concurrent loads. We assume near-even distribution of players (max 10 per instance):

ConcurrentPlayers,EstimatedInstances,Notes
1,1,"Trivial: one instance with few NPC. Risk of empty-instance overhead."
9,1,"One instance (9 players). Healthy fill. Monitor for softcap not triggered."
10,1,"Full capacity. Next arrival must trigger new instance creation (transition to full state)."
11,2,"Two instances (10+1). System must auto-create second instance when 11th arrives."
21,3,"Three instances (10+10+1). Check party splits: if a party spans 11+, system should split or queue."
100,10,"Ten instances. Coordination needed to manage 10 separate worlds. Scale check: 10 server processes."
1,000,100,"Hundreds of instances. Backend must scale (autoscaling, load balancing). Risk: increased orchestration overhead."
10,000,1,000,"Thousands of instances. Must be on scalable cloud infra (Kubernetes, etc.). Risk: database throughput, monitoring granularity, distributed logging."

For extreme scales, leveraging cloud autoscaling and sharding is key. (For reference, Amazon’s New World MMO handles thousands of players with hundreds of server instances and ~800k database writes per 30s, so our design should similarly ensure horizontal scalability.)

Player-Facing Queue and Migration Copy

All player notifications use in-world language (no mention of “instances” or “servers”). Example UI copy:

• When Hospital is Full / Queuing:

“The hospital is at capacity. We’ve put you on a short waitlist. A room will open up soon. Hang tight!”

• Found a Spot:

“Good news: a spot opened up in [Ward Name]. You’re being escorted there now.”

• Creating New Hospital:

“All our rooms are occupied. We’re preparing a new wing of the hospital. Please stand by…”

• Forced Migration:

“Dr. [Name] has requested you in a different location. You’re being moved to [New Wing]. Safe travels!” “Your current area is closing for renovations. We’ll transfer you to a nearby room shortly.”

• Tutorial Inaccessible:

“The tutorial ward is now closed. We’re sending you to the main hospital to continue your orientation.”

• Blocked Player Info:

“For safety, we cannot place you in the same room as someone you’ve chosen to block. You’ll be matched elsewhere.”

• General Queue Timer:

“Estimated wait: {time} minutes.” (Updated periodically.)

This copy is friendly, avoids technical terms, and keeps the player informed of why they are waiting or moving. All messages reassure the player that their game progress is safe and that the system is simply finding the best place for them.

Decisions or Recommendations

• Use only the claim dispositions in Reviewed Synthesis as current guidance.
• Preserve the immutable source file and source checksum; corrections belong in this canonical wrapper and the claim-review register.
• Re-review legal, agency, clinical, age/consent, vendor, product, market, and software claims before each public release.
• Apply equal evidence burdens and explicit uncertainty across jurisdictions, institutions, cultures, and affected communities.
• Keep implementation decisions in active .uai memory and verified repository tests rather than treating research prose as executable authority.

Risks and Limitations

• The review is scoped to high-impact and publication-relevant claims; it is not legal advice, medical advice, a regulatory conformity assessment, or independent product certification.
• External sources and laws can change after the review date; later reuse requires freshness checks.
• The preserved source body may still contain claims that were not selected for public reuse. Their presence is provenance, not endorsement.
• Automated checks cannot establish human comprehension, lived-experience acceptability, native assistive-technology behavior, or real-world player outcomes.
• Archive provenance does not classify the report as Saudi-specific; its subject and claim boundaries remain independent of the container name.

Validation Performed

• Completed a structured claim register with 6 dispositions for this report.
• Compared date-sensitive governance, agency, accessibility, mental-health-rights, child-privacy, age-assurance, and local-inference claims with current primary or authoritative sources where applicable.
• Applied international comparative-fairness, dignity, consent, accessibility, non-stigmatization, and non-actionability review.
• Confirmed the preserved source file remains individually addressable and its recorded SHA-256 lineage is unchanged.
• Local report-template, backlink, pointer, checksum, link, anchor, syntax, discovery, and package checks are rerun during release finalization.

Memory References

• architecture.uai
• representation-safety.uai
• world-context.uai

Related Durable Documents

• [Claim-level review and comparative fairness audit](claim-level-review-and-comparative-fairness-audit.md#findings)
• [Hero Clarity, Report Integration, and UAI Routing Report](hero-clarity-report-integration-and-uai-routing-report.md#executive-summary)
• Provided-report intake audit
• Source-to-report map
• Split-memory architecture

Supersession Status

Current as the canonical durable repository copy and reviewed publication wrapper for 2.0.13-wip. The preserved source analysis is not deleted or rewritten. A later claim review may supersede individual dispositions while retaining this provenance and stable report identity.