castle-web-sdk 0.4.44 → 0.4.46

package/dist/server/wrapper.js

@@ -1,6 +1,9 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
-import { encodeStorageValue } from "../storageJson";
+import { encodeStorageValue, storageError } from "../storageJson";
 import { createServerStorage } from "./storage";
+import { createServerHub, hubArrival, recordHiddenUserIds, } from "./hub";
+export { createSaveCoordinator } from "../saveCoordinator";
+export { SaveError } from "../save";
 // The publish bundler binds the author's default callbacks export once and
 // exports the returned one-argument function as `__castleBootSession`.
 export function createCastleSessionBoot(callbacks) {
@@ -10,21 +13,26 @@ export function createCastleSessionBoot(callbacks) {
 }
 async function bootSession(platformHandle, callbacks) {
     const players = new Map();
-    const session = createAuthorSession(platformHandle, players);
+    const arrivals = new Map();
+    // playerId -> users a block hides from them; never on the player object.
+    const hidden = new Map();
+    // playerId -> their A/B arms while connected; never on the player object.
+    const variants = new Map();
+    const session = createAuthorSession(platformHandle, players, arrivals, hidden, variants);
     let tickTimer = null;
-    platformHandle.on("join", async (connId, identity) => {
-        // The compatibility branch accepts the current Node shim's legacy
-        // single-argument SessionPlayer event while the public handle contract uses
-        // the runtime-agnostic (connId, trusted identity) pair.
-        const player = joinedPlayer(connId, identity);
-        players.set(player.playerId, player);
-        await callbacks.onPlayerJoin?.(session, player);
+    platformHandle.on("join", async (connId, identity, handleArrival, handleVariants) => {
+        const { player, arrival } = admitPlayer({ players, arrivals, hidden, variants }, connId, identity, handleArrival, handleVariants);
+        await callbacks.onPlayerJoin?.(session, player, arrival);
     });
     platformHandle.on("leave", async (connId) => {
         const player = players.get(connId);
         players.delete(connId);
-        if (player)
+        arrivals.delete(connId);
+        hidden.delete(connId);
+        variants.delete(connId);
+        if (player) {
             await callbacks.onPlayerLeave?.(session, player);
+        }
     });
     platformHandle.on("message", async (connId, text) => {
         const player = players.get(connId);
@@ -53,12 +61,12 @@ async function bootSession(platformHandle, callbacks) {
             const turn = Object.freeze({
                 requestId: request.requestId,
                 operationId: request.operationId,
-                speaker: Object.freeze({ ...request.speaker }),
+                speaker: Object.freeze(joinedPlayer(request.speaker.playerId, request.speaker)),
                 characterId: request.characterId,
                 input: request.input,
                 audience: Object.freeze({
                     disclosure: request.audience.disclosure,
-                    players: Object.freeze(request.audience.players.map((player) => Object.freeze({ ...player }))),
+                    players: Object.freeze(request.audience.players.map((player) => Object.freeze(joinedPlayer(player.playerId, player)))),
                     characterIds: Object.freeze([...request.audience.characterIds]),
                 }),
                 async send() {
@@ -102,9 +110,10 @@ async function bootSession(platformHandle, callbacks) {
             let settled = false;
             const brokerFailure = { rejection: null };
             const command = Object.freeze({
+                type: request.command.type,
                 requestId: request.requestId,
                 operationId: request.operationId,
-                speaker: Object.freeze({ ...request.speaker }),
+                speaker: Object.freeze(joinedPlayer(request.speaker.playerId, request.speaker)),
                 command: deepFreezeJsonObject(request.command),
                 async apply() {
                     if (settled)
@@ -148,7 +157,7 @@ async function bootSession(platformHandle, callbacks) {
             const brokerFailure = { rejection: null };
             const read = Object.freeze({
                 requestId: request.requestId,
-                speaker: Object.freeze({ ...request.speaker }),
+                speaker: Object.freeze(joinedPlayer(request.speaker.playerId, request.speaker)),
                 query: deepFreezeJsonObject(request.query),
                 async read() {
                     if (settled)
@@ -201,7 +210,22 @@ async function bootSession(platformHandle, callbacks) {
         }, 1_000 / platformHandle.config.tickRate);
     }
 }
-function createAuthorSession(platformHandle, players) {
+function createAuthorSession(platformHandle, players, arrivals, hidden, variants) {
+    // Lenient about what it is handed: an unknown player is in no experiment.
+    const variantsOf = (player) => variants.get(typeof player === "string"
+        ? player
+        : (player?.playerId ?? ""));
+    // The pinned place counts only where the host services the hub ops.
+    const hub = createServerHub(platformHandle, arrivals, (a, b) => {
+        if (hidden.size === 0 || a === b)
+            return false;
+        const userA = players.get(a)?.userId;
+        const userB = players.get(b)?.userId;
+        if (!userA || !userB)
+            return false;
+        return Boolean(hidden.get(a)?.has(userB) || hidden.get(b)?.has(userA));
+    });
+    const world = createServerWorld(platformHandle);
     return {
         get players() {
             return Array.from(players.values());
@@ -209,8 +233,20 @@ function createAuthorSession(platformHandle, players) {
         sessionId: platformHandle.config.sessionId,
         deckId: platformHandle.config.deckId,
         mode: platformHandle.config.mode,
+        place: typeof platformHandle.config.place === "string"
+            ? platformHandle.config.place
+            : hub?.place ?? null,
         storage: createServerStorage(platformHandle),
-        world: createServerWorld(platformHandle),
+        world,
+        characters: world?.characters ?? createPlaceCharacters(platformHandle),
+        hub,
+        experiment(player, name) {
+            const known = variantsOf(player);
+            return known && Object.hasOwn(known, name) ? known[name] : null;
+        },
+        experiments(player) {
+            return { ...variantsOf(player) };
+        },
         send(playerId, data) {
             if (isBinaryPayload(data)) {
                 requireSendBinary(platformHandle);
@@ -252,6 +288,35 @@ function createAuthorSession(platformHandle, players) {
 const WORLD_OPERATION_ID_MAX_BYTES = 128;
 const WORLD_OPERATION_ID_MAX_CHARACTERS = 120;
 const WORLD_CHECKPOINT_VERSION_MAX = 2_147_483_647;
+const WORLD_JOURNAL_MAX_ENTRIES = 16;
+const WORLD_JOURNAL_MAX_KIND_CHARACTERS = 64;
+const WORLD_JOURNAL_MAX_PARTICIPANT_BYTES = 128;
+const WORLD_JOURNAL_MAX_PARTICIPANTS_PER_ENTRY = 16;
+const WORLD_JOURNAL_MAX_PARTICIPANT_FILTERS = 64;
+const WORLD_JOURNAL_MAX_DATA_BYTES = 2_048;
+const WORLD_JOURNAL_MAX_REQUEST_BYTES = 16 * 1_024;
+const WORLD_JOURNAL_MAX_READ_LIMIT = 128;
+const WORLD_PARTICIPANTS_MAX_READ_LIMIT = 256;
+const WORLD_JOURNAL_MAX_SEQUENCE = "9223372036854775807";
+const SAFE_WORLD_JOURNAL_KIND = /^[A-Za-z0-9_.:-]+$/;
+const WORLD_NOTIFICATIONS_MAX_PARTICIPANTS = 16;
+const WORLD_NOTIFICATIONS_MAX_SLOTS = 4;
+const WORLD_NOTIFICATIONS_MAX_SLOT_CHARACTERS = 40;
+const WORLD_NOTIFICATIONS_MAX_SCHEDULE_MS = 30 * 24 * 60 * 60 * 1_000;
+const WORLD_NOTIFICATIONS_PAST_TOLERANCE_MS = 60 * 1_000;
+const WORLD_CATCH_UP_DEFAULT_MAX_ELAPSED_MS = 7 * 24 * 60 * 60 * 1_000;
+const SAFE_WORLD_NOTIFICATION_KEY = /^[A-Za-z0-9_-]+$/;
+const CANONICAL_WORLD_NOTIFICATION_TIME = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,3}))?Z$/;
+const URL_IN_WORLD_NOTIFICATION_TEXT = /(?:https?:\/\/|www\.|\b[a-z0-9-]+\.(?:app|com|dev|gg|io|net|org|xyz)\b)/i;
+// A hub place's layer has no world of its own, but the host may still broker
+// the place's shared characters into it (`placeCharacters` in the runtime
+// init). The character API is the world one; only the binding differs, and the
+// host stamps that.
+function createPlaceCharacters(platformHandle) {
+    if (platformHandle.config.placeCharacters !== true)
+        return null;
+    return createServerWorldCharacters(platformHandle);
+}
 function createServerWorld(platformHandle) {
     if (!platformHandle.config.world)
         return null;
@@ -260,34 +325,632 @@ function createServerWorld(platformHandle) {
         throw worldError("The persistent-world checkpoint broker is unavailable.", "read");
     }
     const initial = parseWorldSnapshot(platformHandle.config.world, "read");
+    const read = async () => {
+        const result = await platformHandle.worldCheckpointRead();
+        return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
+    };
+    const commit = async (input) => {
+        const expectedRevision = assertWorldRevision(input?.expectedRevision);
+        const operationId = assertWorldOperationId(input?.operationId);
+        const checkpoint = assertWorldCheckpoint(input?.checkpoint);
+        const raw = await platformHandle.worldCheckpointCommit(JSON.stringify({
+            expectedRevision,
+            operationId,
+            checkpoint,
+        }));
+        const result = parsePlatformJson(raw, "commit");
+        if (typeof result.replayed !== "boolean") {
+            throw worldError("The platform returned an invalid commit receipt.", "commit");
+        }
+        return Object.freeze({
+            revision: assertWorldRevision(result.revision),
+            replayed: result.replayed,
+            operationId,
+        });
+    };
     return Object.freeze({
         snapshot: initial,
+        journal: createServerWorldJournal(platformHandle),
+        participants: createServerWorldParticipants(platformHandle),
+        notifications: createServerWorldNotifications(platformHandle),
         characters: createServerWorldCharacters(platformHandle),
-        async read() {
-            const result = await platformHandle.worldCheckpointRead();
-            return parseWorldSnapshot(parsePlatformJson(result, "read"), "read");
+        read,
+        commit,
+        async catchUp(options) {
+            return catchUpWorld(platformHandle.config.world?.worldTime, read, commit, options);
         },
-        async commit(input) {
-            const expectedRevision = assertWorldRevision(input?.expectedRevision);
-            const operationId = assertWorldOperationId(input?.operationId);
-            const checkpoint = assertWorldCheckpoint(input?.checkpoint);
-            const raw = await platformHandle.worldCheckpointCommit(JSON.stringify({
-                expectedRevision,
-                operationId,
+    });
+}
+async function catchUpWorld(worldTime, read, commit, options) {
+    const operation = "session.world.catchUp";
+    if (worldTime?.advance !== "wallClock") {
+        throw worldJournalArgumentError('The destination must opt in with worldTime.advance set to "wallClock".', operation);
+    }
+    assertOnlyKeys(options, ["key", "maxElapsedMs", "apply"], operation, "options");
+    const key = options.key === undefined
+        ? "advancedThroughMs"
+        : assertWorldCatchUpKey(options.key, operation);
+    const maxElapsedMs = options.maxElapsedMs === undefined
+        ? WORLD_CATCH_UP_DEFAULT_MAX_ELAPSED_MS
+        : assertBoundedInteger(options.maxElapsedMs, 0, Number.MAX_SAFE_INTEGER, "maxElapsedMs", operation);
+    if (typeof options.apply !== "function") {
+        throw worldJournalArgumentError("apply must be a function.", operation);
+    }
+    const now = Date.now();
+    let snapshot = await read();
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const state = worldCatchUpState(snapshot.checkpoint, key, now, maxElapsedMs, operation);
+        if (state.markerExists && state.elapsedMs === 0) {
+            if (state.markerMs >= now) {
+                return Object.freeze({ applied: false, elapsedMs: 0, revision: snapshot.revision });
+            }
+            const checkpoint = checkpointWithCatchUpMarker(snapshot.checkpoint, key, state.markerMs, now, operation);
+            try {
+                const receipt = await commit({
+                    expectedRevision: snapshot.revision,
+                    operationId: `catchUp:${snapshot.revision}`,
+                    checkpoint,
+                });
+                return Object.freeze({ applied: false, elapsedMs: 0, revision: receipt.revision });
+            }
+            catch (error) {
+                if (attempt !== 0 || !isWorldRevisionConflict(error))
+                    throw error;
+                snapshot = await read();
+                continue;
+            }
+        }
+        const returned = await options.apply(Object.freeze({
+            elapsedMs: state.elapsedMs,
+            now,
+            checkpoint: snapshot.checkpoint,
+        }));
+        const normalized = assertWorldCheckpoint(returned, "commit");
+        if (!isRecord(normalized.value)) {
+            throw worldJournalArgumentError("apply must return a checkpoint whose value is an object.", operation);
+        }
+        const checkpoint = checkpointWithCatchUpMarker(normalized, key, state.markerMs, now, operation);
+        try {
+            const receipt = await commit({
+                expectedRevision: snapshot.revision,
+                operationId: `catchUp:${snapshot.revision}`,
                 checkpoint,
-            }));
-            const result = parsePlatformJson(raw, "commit");
-            if (typeof result.replayed !== "boolean") {
-                throw worldError("The platform returned an invalid commit receipt.", "commit");
+            });
+            return Object.freeze({
+                applied: !receipt.replayed,
+                elapsedMs: state.elapsedMs,
+                revision: receipt.revision,
+            });
+        }
+        catch (error) {
+            if (attempt !== 0 || !isWorldRevisionConflict(error))
+                throw error;
+            snapshot = await read();
+        }
+    }
+    throw new TypeError(`${operation}: unreachable catch-up state.`);
+}
+function assertWorldCatchUpKey(value, operation) {
+    if (typeof value !== "string") {
+        throw worldJournalArgumentError("key must be a string.", operation);
+    }
+    return value;
+}
+function worldCatchUpState(checkpoint, key, now, maxElapsedMs, operation) {
+    if (!checkpoint ||
+        !isRecord(checkpoint.value) ||
+        !Object.prototype.hasOwnProperty.call(checkpoint.value, key)) {
+        return { markerExists: false, markerMs: now, elapsedMs: 0 };
+    }
+    const advancedThroughMs = checkpoint.value[key];
+    if (!Number.isSafeInteger(advancedThroughMs) || advancedThroughMs < 0) {
+        throw worldJournalArgumentError(`checkpoint.value.${key} must be a non-negative integer timestamp in milliseconds.`, operation);
+    }
+    const markerMs = advancedThroughMs;
+    return {
+        markerExists: true,
+        markerMs,
+        elapsedMs: Math.min(maxElapsedMs, Math.max(0, now - markerMs)),
+    };
+}
+function checkpointWithCatchUpMarker(checkpoint, key, existingMarkerMs, now, operation) {
+    if (!isRecord(checkpoint.value)) {
+        throw worldJournalArgumentError("apply must return a checkpoint whose value is an object.", operation);
+    }
+    return Object.freeze({
+        version: checkpoint.version,
+        value: Object.freeze({
+            ...checkpoint.value,
+            [key]: Math.max(existingMarkerMs, now),
+        }),
+    });
+}
+function isWorldRevisionConflict(error) {
+    return isRecord(error) && error.code === "CAULDRON_WORLD_REVISION_CONFLICT";
+}
+function createServerWorldJournal(platformHandle) {
+    return Object.freeze({
+        async append(input) {
+            const operation = "session.world.journal.append";
+            assertOnlyKeys(input, ["operationId", "entries"], operation, "input");
+            const operationId = assertWorldJournalOperationId(input?.operationId, operation);
+            if (!Array.isArray(input?.entries) ||
+                input.entries.length < 1 ||
+                input.entries.length > WORLD_JOURNAL_MAX_ENTRIES) {
+                throw worldJournalArgumentError(`entries must contain from 1 through ${WORLD_JOURNAL_MAX_ENTRIES} entries.`, operation);
+            }
+            const entries = input.entries.map((entry, index) => normalizeWorldJournalAppendEntry(entry, index, operation));
+            const args = { operationId, entries };
+            if (utf8Length(JSON.stringify(args)) > WORLD_JOURNAL_MAX_REQUEST_BYTES) {
+                throw worldJournalArgumentError(`The serialized request may be at most ${WORLD_JOURNAL_MAX_REQUEST_BYTES} bytes.`, operation);
+            }
+            const result = parseWorldJournalJson(await callWorldJournalStorage(platformHandle, "worldJournalAppend", args, operation), operation);
+            if (!isRecord(result) || result.operationId !== operationId ||
+                typeof result.replayed !== "boolean") {
+                throw invalidWorldJournalResponse(operation);
             }
             return Object.freeze({
-                revision: assertWorldRevision(result.revision),
-                replayed: result.replayed,
                 operationId,
+                replayed: result.replayed,
+                firstSeq: parseWorldJournalSequence(result.firstSeq, operation, true),
+                lastSeq: parseWorldJournalSequence(result.lastSeq, operation, true),
+            });
+        },
+        async read(options = {}) {
+            const operation = "session.world.journal.read";
+            assertOnlyKeys(options, ["afterSeq", "limit", "participantId"], operation, "options");
+            const args = {};
+            if (options.afterSeq !== undefined) {
+                args.afterSeq = assertWorldJournalSequence(options.afterSeq, operation, "afterSeq");
+            }
+            if (options.limit !== undefined) {
+                args.limit = assertBoundedInteger(options.limit, 1, WORLD_JOURNAL_MAX_READ_LIMIT, "limit", operation);
+            }
+            if (options.participantId !== undefined) {
+                args.participantId = assertWorldParticipantId(options.participantId, "participantId", operation);
+            }
+            const result = parseWorldJournalJson(await callWorldJournalStorage(platformHandle, "worldJournalRead", args, operation), operation);
+            if (!isRecord(result) || !Array.isArray(result.entries) ||
+                result.entries.length > WORLD_JOURNAL_MAX_READ_LIMIT) {
+                throw invalidWorldJournalResponse(operation);
+            }
+            const entries = result.entries.map((entry) => parseWorldJournalEntry(entry, operation));
+            return Object.freeze({
+                entries: Object.freeze(entries),
+                nextSeq: parseWorldJournalSequence(result.nextSeq, operation),
+                oldestRetainedSeq: result.oldestRetainedSeq === null
+                    ? null
+                    : parseWorldJournalSequence(result.oldestRetainedSeq, operation, true),
+            });
+        },
+    });
+}
+function createServerWorldParticipants(platformHandle) {
+    return Object.freeze({
+        async read(options = {}) {
+            const operation = "session.world.participants.read";
+            assertOnlyKeys(options, ["participantIds", "limit"], operation, "options");
+            const args = {};
+            if (options.participantIds !== undefined) {
+                args.participantIds = normalizeParticipantIds(options.participantIds, WORLD_JOURNAL_MAX_PARTICIPANT_FILTERS, "participantIds", operation);
+            }
+            if (options.limit !== undefined) {
+                args.limit = assertBoundedInteger(options.limit, 1, WORLD_PARTICIPANTS_MAX_READ_LIMIT, "limit", operation);
+            }
+            const result = parseWorldJournalJson(await callWorldJournalStorage(platformHandle, "worldParticipantsRead", args, operation), operation);
+            if (!isRecord(result) || !Array.isArray(result.participants) ||
+                result.participants.length > WORLD_PARTICIPANTS_MAX_READ_LIMIT) {
+                throw invalidWorldJournalResponse(operation);
+            }
+            return Object.freeze({
+                participants: Object.freeze(result.participants.map((participant) => parseWorldParticipant(participant, operation))),
             });
         },
     });
 }
+function createServerWorldNotifications(platformHandle) {
+    return Object.freeze({
+        async notify(input) {
+            const operation = "session.world.notifications.notify";
+            assertOnlyKeys(input, ["key", "participantIds", "templateId", "slots", "at", "expiresAt"], operation, "input");
+            const now = Date.now();
+            const key = assertWorldNotificationSafeKey(input.key, "key", operation);
+            const participantIds = normalizeParticipantIds(input.participantIds, WORLD_NOTIFICATIONS_MAX_PARTICIPANTS, "participantIds", operation);
+            const templateId = assertWorldNotificationSafeKey(input.templateId, "templateId", operation);
+            const slots = input.slots === undefined
+                ? undefined
+                : normalizeWorldNotificationSlots(input.slots, operation);
+            const at = input.at === undefined
+                ? undefined
+                : assertWorldNotificationTime(input.at, "at", operation);
+            const atMs = at?.milliseconds ?? now;
+            if (atMs < now - WORLD_NOTIFICATIONS_PAST_TOLERANCE_MS ||
+                atMs > now + WORLD_NOTIFICATIONS_MAX_SCHEDULE_MS) {
+                throw worldJournalArgumentError("at must be no more than 60 seconds in the past and at most 30 days ahead.", operation);
+            }
+            // Ghost clamps a tolerated past `at` to its own now, so expiry is judged
+            // against that effective time, not the original timestamp.
+            const effectiveAtMs = Math.max(atMs, now);
+            const expiresAt = input.expiresAt === undefined
+                ? undefined
+                : assertWorldNotificationTime(input.expiresAt, "expiresAt", operation);
+            if (expiresAt &&
+                (expiresAt.milliseconds <= effectiveAtMs ||
+                    expiresAt.milliseconds > effectiveAtMs + WORLD_NOTIFICATIONS_MAX_SCHEDULE_MS)) {
+                throw worldJournalArgumentError("expiresAt must be after at and at most 30 days after it.", operation);
+            }
+            const args = {
+                key,
+                participantIds,
+                templateId,
+                ...(slots === undefined ? {} : { slots }),
+                ...(at === undefined ? {} : { at: at.value }),
+                ...(expiresAt === undefined ? {} : { expiresAt: expiresAt.value }),
+            };
+            const result = parseWorldNotificationResult(await callWorldNotificationStorage(platformHandle, "worldNotify", args, operation), operation);
+            if (result.key !== key)
+                throw invalidWorldNotificationResponse(operation);
+            return Object.freeze({
+                key,
+                accepted: parseWorldNotificationCount(result.accepted, operation),
+                skipped: parseWorldNotificationCount(result.skipped, operation),
+                limited: parseWorldNotificationCount(result.limited, operation),
+            });
+        },
+        async cancel(input) {
+            const operation = "session.world.notifications.cancel";
+            assertOnlyKeys(input, ["key", "participantIds"], operation, "input");
+            const key = assertWorldNotificationSafeKey(input.key, "key", operation);
+            const participantIds = input.participantIds === undefined
+                ? undefined
+                : normalizeParticipantIds(input.participantIds, WORLD_NOTIFICATIONS_MAX_PARTICIPANTS, "participantIds", operation);
+            const args = {
+                key,
+                ...(participantIds === undefined ? {} : { participantIds }),
+            };
+            const result = parseWorldNotificationResult(await callWorldNotificationStorage(platformHandle, "worldNotifyCancel", args, operation), operation);
+            return Object.freeze({
+                cancelled: parseWorldNotificationCount(result.cancelled, operation),
+            });
+        },
+    });
+}
+function assertWorldNotificationSafeKey(value, field, operation) {
+    if (typeof value !== "string" ||
+        worldNotificationCharacters(value) < 1 ||
+        worldNotificationCharacters(value) > 64 ||
+        !SAFE_WORLD_NOTIFICATION_KEY.test(value)) {
+        throw worldJournalArgumentError(`${field} must be a safe key of at most 64 characters.`, operation);
+    }
+    return value;
+}
+function normalizeWorldNotificationSlots(value, operation) {
+    if (!isRecord(value)) {
+        throw worldJournalArgumentError("slots must be an object.", operation);
+    }
+    const entries = Object.entries(value);
+    if (entries.length > WORLD_NOTIFICATIONS_MAX_SLOTS) {
+        throw worldJournalArgumentError(`slots may contain at most ${WORLD_NOTIFICATIONS_MAX_SLOTS} values.`, operation);
+    }
+    const normalized = {};
+    for (const [key, slotValue] of entries.sort(([left], [right]) => left.localeCompare(right))) {
+        assertWorldNotificationSafeKey(key, `slots.${key}`, operation);
+        if (typeof slotValue !== "string" ||
+            worldNotificationCharacters(slotValue) < 1 ||
+            worldNotificationCharacters(slotValue) > WORLD_NOTIFICATIONS_MAX_SLOT_CHARACTERS ||
+            slotValue.includes("\0") ||
+            hasUnpairedSurrogate(slotValue) ||
+            slotValue.includes("\n") ||
+            slotValue.includes("\r") ||
+            URL_IN_WORLD_NOTIFICATION_TEXT.test(slotValue)) {
+            throw worldJournalArgumentError(`slots.${key} must be 1 through ${WORLD_NOTIFICATIONS_MAX_SLOT_CHARACTERS} ` +
+                "characters of single-line text without a URL.", operation);
+        }
+        normalized[key] = slotValue;
+    }
+    return Object.freeze(normalized);
+}
+function worldNotificationCharacters(value) {
+    return Array.from(value).length;
+}
+function assertWorldNotificationTime(value, field, operation) {
+    if (typeof value !== "string") {
+        throw worldJournalArgumentError(`${field} must be a canonical ISO 8601 time with at most millisecond precision.`, operation);
+    }
+    const match = CANONICAL_WORLD_NOTIFICATION_TIME.exec(value);
+    const milliseconds = Date.parse(value);
+    if (!match || !Number.isFinite(milliseconds)) {
+        throw worldJournalArgumentError(`${field} must be a canonical ISO 8601 time with at most millisecond precision.`, operation);
+    }
+    const normalized = new Date(milliseconds).toISOString();
+    const normalizedFraction = normalized.slice(20, 23);
+    if (normalized.slice(0, 19) !== match[1] ||
+        (match[2] === undefined
+            ? normalizedFraction !== "000"
+            : normalizedFraction !== match[2].padEnd(3, "0"))) {
+        throw worldJournalArgumentError(`${field} must be a canonical ISO 8601 time with at most millisecond precision.`, operation);
+    }
+    return { value, milliseconds };
+}
+async function callWorldNotificationStorage(platformHandle, op, args, operation) {
+    if (typeof platformHandle.storage !== "function" || platformHandle.storageEnabled === false) {
+        throw worldNotificationsUnavailable(operation);
+    }
+    try {
+        return await platformHandle.storage(op, JSON.stringify(args));
+    }
+    catch (error) {
+        if (isUnknownStorageOperation(error))
+            throw worldNotificationsUnavailable(operation);
+        throw error;
+    }
+}
+function worldNotificationsUnavailable(operation) {
+    return storageError("CAULDRON_WORLD_NOTIFICATIONS_UNAVAILABLE", "This Castle host does not support persistent-world notifications.", operation);
+}
+function parseWorldNotificationResult(value, operation) {
+    let result;
+    try {
+        result = JSON.parse(value);
+    }
+    catch {
+        throw invalidWorldNotificationResponse(operation);
+    }
+    if (!isRecord(result))
+        throw invalidWorldNotificationResponse(operation);
+    return result;
+}
+function parseWorldNotificationCount(value, operation) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw invalidWorldNotificationResponse(operation);
+    }
+    return value;
+}
+function invalidWorldNotificationResponse(operation) {
+    return new TypeError(`${operation}: The platform returned an invalid response.`);
+}
+function normalizeWorldJournalAppendEntry(value, index, operation) {
+    const field = `entries[${index}]`;
+    assertOnlyKeys(value, ["kind", "disclosure", "participantIds", "data"], operation, field);
+    const entry = value;
+    if (typeof entry.kind !== "string" ||
+        entry.kind.length < 1 ||
+        entry.kind.length > WORLD_JOURNAL_MAX_KIND_CHARACTERS ||
+        !SAFE_WORLD_JOURNAL_KIND.test(entry.kind)) {
+        throw worldJournalArgumentError(`${field}.kind must be a safe key of at most ${WORLD_JOURNAL_MAX_KIND_CHARACTERS} characters.`, operation);
+    }
+    if (entry.disclosure !== "world" && entry.disclosure !== "participants") {
+        throw worldJournalArgumentError(`${field}.disclosure must be "world" or "participants".`, operation);
+    }
+    let participantIds;
+    if (entry.disclosure === "participants") {
+        participantIds = normalizeParticipantIds(entry.participantIds, WORLD_JOURNAL_MAX_PARTICIPANTS_PER_ENTRY, `${field}.participantIds`, operation);
+    }
+    else if (Object.prototype.hasOwnProperty.call(entry, "participantIds")) {
+        throw worldJournalArgumentError(`${field}.participantIds must be absent when disclosure is "world".`, operation);
+    }
+    let data;
+    if (Object.prototype.hasOwnProperty.call(entry, "data")) {
+        data = normalizeWorldJournalData(entry.data, field, operation);
+    }
+    return Object.freeze({
+        kind: entry.kind,
+        disclosure: entry.disclosure,
+        ...(participantIds === undefined ? {} : { participantIds }),
+        ...(data === undefined ? {} : { data }),
+    });
+}
+function normalizeWorldJournalData(value, field, operation) {
+    let encoded;
+    try {
+        encoded = encodeStorageValue(value, operation);
+    }
+    catch {
+        throw worldJournalArgumentError(`${field}.data must be JSON.`, operation);
+    }
+    const normalized = canonicalizeJson(JSON.parse(encoded));
+    assertWorldJournalDataText(normalized, `${field}.data`, operation);
+    if (utf8Length(JSON.stringify(normalized)) > WORLD_JOURNAL_MAX_DATA_BYTES) {
+        throw worldJournalArgumentError(`${field}.data may be at most ${WORLD_JOURNAL_MAX_DATA_BYTES} bytes when serialized.`, operation);
+    }
+    return normalized;
+}
+function assertWorldJournalDataText(value, field, operation) {
+    if (typeof value === "string") {
+        if (value.includes("\0") || hasUnpairedSurrogate(value)) {
+            throw worldJournalArgumentError(`${field} must contain valid text.`, operation);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertWorldJournalDataText(item, `${field}[${index}]`, operation));
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [key, item] of Object.entries(value)) {
+            if (key.includes("\0") || hasUnpairedSurrogate(key)) {
+                throw worldJournalArgumentError(`${field} must contain valid text.`, operation);
+            }
+            assertWorldJournalDataText(item, `${field}.${key}`, operation);
+        }
+    }
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalizeJson(value[key])]));
+    }
+    return value;
+}
+function normalizeParticipantIds(value, max, field, operation) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > max) {
+        throw worldJournalArgumentError(`${field} must contain from 1 through ${max} ids.`, operation);
+    }
+    const ids = [...new Set(value.map((id, index) => assertWorldParticipantId(id, `${field}[${index}]`, operation)))].sort();
+    if (ids.length > max) {
+        throw worldJournalArgumentError(`${field} must contain from 1 through ${max} ids.`, operation);
+    }
+    return Object.freeze(ids);
+}
+function assertWorldParticipantId(value, field, operation) {
+    if (typeof value !== "string" || value.length === 0 ||
+        value.includes("\0") || hasUnpairedSurrogate(value) ||
+        utf8Length(value) > WORLD_JOURNAL_MAX_PARTICIPANT_BYTES) {
+        throw worldJournalArgumentError(`${field} must be valid non-empty text of at most ${WORLD_JOURNAL_MAX_PARTICIPANT_BYTES} bytes.`, operation);
+    }
+    return value;
+}
+function assertWorldJournalOperationId(value, operation) {
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        value.length > WORLD_OPERATION_ID_MAX_CHARACTERS ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value) ||
+        utf8Length(value) > WORLD_OPERATION_ID_MAX_BYTES) {
+        throw worldJournalArgumentError(`operationId must be valid text of at most ${WORLD_OPERATION_ID_MAX_CHARACTERS} characters and ${WORLD_OPERATION_ID_MAX_BYTES} bytes.`, operation);
+    }
+    return value;
+}
+function assertWorldJournalSequence(value, operation, field, positive = false) {
+    if (!isWorldJournalSequence(value, positive)) {
+        throw worldJournalArgumentError(`${field} must be a canonical decimal string no greater than ${WORLD_JOURNAL_MAX_SEQUENCE}.`, operation);
+    }
+    return value;
+}
+function assertBoundedInteger(value, min, max, field, operation) {
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw worldJournalArgumentError(`${field} must be an integer from ${min} through ${max}.`, operation);
+    }
+    return value;
+}
+async function callWorldJournalStorage(platformHandle, op, args, operation) {
+    if (typeof platformHandle.storage !== "function" || platformHandle.storageEnabled === false) {
+        throw worldJournalUnavailable(operation);
+    }
+    try {
+        return await platformHandle.storage(op, JSON.stringify(args));
+    }
+    catch (error) {
+        if (isUnknownStorageOperation(error))
+            throw worldJournalUnavailable(operation);
+        throw error;
+    }
+}
+function isUnknownStorageOperation(error) {
+    if (!isRecord(error) ||
+        (error.code !== "CAULDRON_STORAGE_INVALID_ARGUMENT" &&
+            error.code !== "CAULDRON_STORAGE_BAD_REQUEST"))
+        return false;
+    const message = error.message;
+    return typeof message === "string" && /unknown (?:storage )?operation/i.test(message);
+}
+function worldJournalUnavailable(operation) {
+    return storageError("CAULDRON_WORLD_JOURNAL_UNAVAILABLE", "This Castle host does not support persistent-world journals.", operation);
+}
+function worldJournalArgumentError(message, operation) {
+    return storageError("INVALID_ARGUMENT", message, operation);
+}
+function parseWorldJournalJson(value, operation) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw invalidWorldJournalResponse(operation);
+    }
+}
+function invalidWorldJournalResponse(operation) {
+    return new TypeError(`${operation}: The platform returned an invalid response.`);
+}
+function parseWorldJournalEntry(value, operation) {
+    if (!isRecord(value) ||
+        (value.disclosure !== "world" && value.disclosure !== "participants") ||
+        !Array.isArray(value.participantIds) ||
+        typeof value.kind !== "string" ||
+        typeof value.createdAt !== "string") {
+        throw invalidWorldJournalResponse(operation);
+    }
+    const participantIds = value.participantIds.map((id) => {
+        if (typeof id !== "string")
+            throw invalidWorldJournalResponse(operation);
+        return id;
+    });
+    if ((value.disclosure === "world" && participantIds.length !== 0) ||
+        (value.disclosure === "participants" && participantIds.length < 1)) {
+        throw invalidWorldJournalResponse(operation);
+    }
+    let data;
+    try {
+        data = JSON.parse(encodeStorageValue(value.data, operation));
+    }
+    catch {
+        throw invalidWorldJournalResponse(operation);
+    }
+    return Object.freeze({
+        seq: parseWorldJournalSequence(value.seq, operation, true),
+        kind: value.kind,
+        disclosure: value.disclosure,
+        participantIds: Object.freeze(participantIds),
+        data,
+        createdAt: value.createdAt,
+    });
+}
+function parseWorldJournalSequence(value, operation, positive = false) {
+    if (!isWorldJournalSequence(value, positive)) {
+        throw invalidWorldJournalResponse(operation);
+    }
+    return value;
+}
+function isWorldJournalSequence(value, positive) {
+    if (typeof value !== "string" || !/^(?:0|[1-9][0-9]*)$/.test(value))
+        return false;
+    if (positive && value === "0")
+        return false;
+    return value.length < WORLD_JOURNAL_MAX_SEQUENCE.length ||
+        (value.length === WORLD_JOURNAL_MAX_SEQUENCE.length &&
+            value <= WORLD_JOURNAL_MAX_SEQUENCE);
+}
+function parseWorldParticipant(value, operation) {
+    if (!isRecord(value) || typeof value.participantId !== "string" ||
+        typeof value.firstSeenAt !== "string" || typeof value.lastSeenAt !== "string" ||
+        (value.lastLeftAt !== null && typeof value.lastLeftAt !== "string") ||
+        !Number.isSafeInteger(value.visitCount) || value.visitCount < 0) {
+        throw invalidWorldJournalResponse(operation);
+    }
+    return Object.freeze({
+        participantId: value.participantId,
+        firstSeenAt: value.firstSeenAt,
+        lastSeenAt: value.lastSeenAt,
+        lastLeftAt: value.lastLeftAt,
+        visitCount: value.visitCount,
+    });
+}
+function assertOnlyKeys(value, allowed, operation, field) {
+    if (!isRecord(value) || Object.keys(value).some((key) => !allowed.includes(key))) {
+        throw worldJournalArgumentError(`${field} contains an unsupported field.`, operation);
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasUnpairedSurrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return true;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return true;
+        }
+    }
+    return false;
+}
+function utf8Length(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
 function createServerWorldCharacters(platformHandle) {
     return Object.freeze({
         async create(input) {
@@ -637,15 +1300,59 @@ function requireBroadcastBinary(platformHandle) {
 function unsupportedBinaryRuntime() {
     throw new TypeError("This Castle runtime does not support binary multiplayer messages yet.");
 }
+// The compatibility branch accepts the current Node shim's legacy
+// single-argument SessionPlayer event while the public handle contract uses the
+// runtime-agnostic (connId, trusted identity) pair. Either form may carry the hub
+// arrival after the player and the player's A/B arms after that, and a hub
+// player's block list on the player itself.
+function admitPlayer(state, connId, identity, handleArrival, handleVariants) {
+    const player = joinedPlayer(connId, identity);
+    const arrival = hubArrival(typeof connId === "string" ? handleArrival : identity);
+    const known = experimentVariants(typeof connId === "string" ? handleVariants : handleArrival);
+    state.players.set(player.playerId, player);
+    if (known) {
+        state.variants.set(player.playerId, known);
+    }
+    else {
+        state.variants.delete(player.playerId);
+    }
+    recordHiddenUserIds(state.hidden, player.playerId, typeof connId === "string" ? identity : connId);
+    if (arrival) {
+        state.arrivals.set(player.playerId, arrival);
+    }
+    else {
+        state.arrivals.delete(player.playerId);
+    }
+    return { player, arrival };
+}
+// Absent on a host that predates experiments, and for a player who is in none.
+function experimentVariants(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length > 0 ? Object.freeze(Object.fromEntries(entries)) : null;
+}
 function joinedPlayer(connId, identity) {
-    if (typeof connId === "string")
-        return { ...identity, playerId: connId };
+    if (typeof connId === "string") {
+        const player = {
+            ...identity,
+            playerId: connId,
+            participantId: identity.scopedUserId ?? identity.userId,
+        };
+        // A hub player's block list stays in the wrapper (`session.hub.hiddenPair`):
+        // decks broadcast player objects.
+        delete player.hiddenUserIds;
+        // A/B arms arrive beside the player; one a host put on it stays off it too.
+        delete player.experimentVariants;
+        return player;
+    }
     const legacy = connId;
     return {
         playerId: legacy.playerId,
         userId: legacy.userId,
         username: legacy.username,
         isAnonymous: legacy.isAnonymous,
+        participantId: legacy.scopedUserId ?? legacy.userId,
         ...(legacy.scopedUserId ? { scopedUserId: legacy.scopedUserId } : {}),
     };
 }