castle-web-sdk 0.4.45 → 0.4.47

package/dist/server/wrapper.js

@@ -1,6 +1,9 @@
 import { isBinaryPayload, toUint8Array, } from "../multiplayerProtocol";
 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,19 +13,23 @@ 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);
+        arrivals.delete(connId);
+        hidden.delete(connId);
+        variants.delete(connId);
         if (player) {
             await callbacks.onPlayerLeave?.(session, player);
         }
@@ -62,18 +69,15 @@ async function bootSession(platformHandle, callbacks) {
                     players: Object.freeze(request.audience.players.map((player) => Object.freeze(joinedPlayer(player.playerId, player)))),
                     characterIds: Object.freeze([...request.audience.characterIds]),
                 }),
-                async send() {
+                async send(options) {
                     if (settled)
                         throw new TypeError("This shared character request is already settled.");
                     settled = true;
-                    let rawReceipt;
-                    try {
-                        rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
-                    }
-                    catch (error) {
+                    const rawReceipt = await sendWorldCharacterTurn(platformHandle, request.grantId, options)
+                        .catch((error) => {
                         brokerFailure.rejection = { error };
                         throw error;
-                    }
+                    });
                     return parseWorldCharacterAdmission(rawReceipt, request.operationId);
                 },
                 reject(code) {
@@ -96,6 +100,7 @@ async function bootSession(platformHandle, callbacks) {
             }
         });
     }
+    listenForWorldCharacterTools(platformHandle, callbacks, session);
     if (callbacks.onWorldCharacterCommand &&
         hasWorldCharacterPlatform(platformHandle, "worldCharacterCommand")) {
         platformHandle.on("worldCharacterCommand", async (raw) => {
@@ -103,6 +108,7 @@ 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(joinedPlayer(request.speaker.playerId, request.speaker)),
@@ -202,7 +208,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());
@@ -210,8 +231,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);
@@ -264,6 +297,24 @@ 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;
@@ -272,36 +323,149 @@ 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,
-                checkpoint,
-            }));
-            const result = parsePlatformJson(raw, "commit");
-            if (typeof result.replayed !== "boolean") {
-                throw worldError("The platform returned an invalid commit receipt.", "commit");
+    });
+}
+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,
+            });
             return Object.freeze({
-                revision: assertWorldRevision(result.revision),
-                replayed: result.replayed,
-                operationId,
+                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) {
@@ -382,6 +546,167 @@ function createServerWorldParticipants(platformHandle) {
         },
     });
 }
+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);
@@ -754,12 +1079,13 @@ function assertRuntimeCharacterCapabilities(value) {
     }
     return Object.freeze({ actionIds: Object.freeze([...normalized].sort()) });
 }
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
 function assertRuntimeCharacterText(value, field, maxCharacters, maxBytes) {
     if (typeof value !== "string" ||
         value.length === 0 ||
         value.length > maxCharacters ||
         value.includes("\0") ||
-        /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value) ||
+        LONE_SURROGATE.test(value) ||
         new TextEncoder().encode(value).byteLength > maxBytes) {
         throw new TypeError(`session.world.characters.create: ${field} must be valid non-empty text of at most ${maxCharacters} characters.`);
     }
@@ -863,6 +1189,82 @@ function assertPlatformWorldCharacterRead(value) {
     }
     return value;
 }
+// Tools ride only to a host that can answer them (an older host refuses a send
+// carrying anything beyond the grant); otherwise this is exactly the tool-less send.
+function sendWorldCharacterTurn(platformHandle, grantId, options) {
+    const tools = options?.tools;
+    return Array.isArray(tools) && tools.length > 0 &&
+        typeof platformHandle.worldCharacterToolResult === "function"
+        ? platformHandle.worldCharacterSend(grantId, tools)
+        : platformHandle.worldCharacterSend(grantId);
+}
+// Only a handler on a host that answers place tools listens; without one the
+// host times the lookup out and the character answers without it.
+function listenForWorldCharacterTools(platformHandle, callbacks, session) {
+    const handler = callbacks.onWorldCharacterTool;
+    const answer = platformHandle.worldCharacterToolResult?.bind(platformHandle);
+    if (!handler || !answer)
+        return;
+    try {
+        platformHandle.on("worldCharacterTool", async (raw) => {
+            const call = platformWorldCharacterTool(raw);
+            if (!call)
+                return;
+            const result = await worldCharacterToolResult(handler, call.request, session);
+            try {
+                await answer(call.requestId, result);
+            }
+            catch {
+                // The host has stopped waiting (or refused); the character answers without it.
+            }
+        });
+    }
+    catch {
+        // Older shims may reject event names they do not recognize.
+    }
+}
+const MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES = 1024;
+const WORLD_CHARACTER_TOOL_TOO_LARGE = '{"error":"result too large"}';
+const WORLD_CHARACTER_TOOL_FAILED = '{"error":"tool failed"}';
+function platformWorldCharacterTool(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        typeof value.requestId !== "string" ||
+        typeof value.operationId !== "string" ||
+        typeof value.characterId !== "string" ||
+        typeof value.playerId !== "string" ||
+        typeof value.name !== "string" ||
+        !value.input ||
+        typeof value.input !== "object" ||
+        Array.isArray(value.input)) {
+        return null;
+    }
+    return {
+        requestId: value.requestId,
+        request: Object.freeze({
+            operationId: value.operationId,
+            characterId: value.characterId,
+            playerId: value.playerId,
+            name: value.name,
+            input: deepFreezeJsonObject(value.input),
+        }),
+    };
+}
+async function worldCharacterToolResult(handler, request, session) {
+    let result;
+    try {
+        const value = await handler(request, session);
+        result = typeof value === "string" ? value : JSON.stringify(value);
+    }
+    catch {
+        return WORLD_CHARACTER_TOOL_FAILED;
+    }
+    if (typeof result !== "string")
+        return WORLD_CHARACTER_TOOL_FAILED;
+    return new TextEncoder().encode(result).byteLength > MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES
+        ? WORLD_CHARACTER_TOOL_TOO_LARGE
+        : result;
+}
 function hasWorldCharacterPlatform(platformHandle, operation) {
     return (typeof platformHandle[operation] === "function" &&
         typeof platformHandle.worldCharacterReject === "function");
@@ -973,13 +1375,51 @@ 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 {
+        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 {

package/dist/store.d.ts

@@ -1,5 +1,6 @@
 import type { StoreAllowance } from "./commands";
 import type { Json } from "./types";
+import { type SaveApi, type SaveBucketApi } from "./save";
 export interface StoreListOptions {
     /** Only keys beginning with this. Omit for every key in the scope. */
     prefix?: string;
@@ -21,7 +22,7 @@ export interface StoreListPage<T extends Json = Json> {
      */
     cursor: string | null;
 }
-export interface StoreScopeApi {
+export interface StoreScopeApi extends SaveBucketApi {
     /** Reads keys. Keys with no value are absent from the result. */
     get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
     /**
@@ -63,7 +64,7 @@ export interface StoreUsage {
     /** `Store.deck`: one allowance shared by every player of the deck. */
     shared: StoreAllowance;
 }
-export interface CastleStoreApi {
+export interface CastleStoreApi extends SaveApi {
     /** Shared by everyone playing the deck. */
     readonly deck: StoreScopeApi;
     /** The current player's data, which other players can read. */