castle-web-sdk 0.4.47 → 0.4.48

package/dist/multiplayer.js

@@ -46,13 +46,17 @@ async function join(options) {
     const request = hub
         ? { command: "hub", nonce: hub.nonce }
         : { command: "multiplayer.getSession", params: joinParams(options) };
+    const pongTimeoutMs = options.pongTimeoutMs ?? 0;
+    if (!Number.isFinite(pongTimeoutMs) || pongTimeoutMs < 0 || pongTimeoutMs > 2_147_483_647) {
+        throw new RangeError("pongTimeoutMs must be between 0 and 2147483647 milliseconds");
+    }
     latestJoinAttempt += 1;
     cancelPendingDestinationJoin();
     activeConnection?.leave();
     const connection = new MultiplayerConnectionImpl(request, () => {
         if (activeConnection === connection)
             activeConnection = null;
-    });
+    }, null, pongTimeoutMs);
     activeConnection = connection;
     await connection.start(hub ?? undefined);
     // The host moves its place (and every place-scoped command with it) when the
@@ -183,9 +187,12 @@ class MultiplayerConnectionImpl {
     request;
     onClosed;
     destinationAudience;
+    pongTimeoutMs;
     currentState = "acquiring";
     currentPlayerId = "";
     currentSessionId = "";
+    currentServerBundleSha256 = null;
+    currentServerBundleId = null;
     solo = false;
     currentSoloReason = null;
     baseUrl = "";
@@ -194,6 +201,8 @@ class MultiplayerConnectionImpl {
     socket = null;
     socketAttempt = 0;
     keepalive = null;
+    pongExtensionUsed = false;
+    pongDeadline = null;
     reAcquisitionUsed = false;
     recovering = false;
     hubSettled = false;
@@ -219,10 +228,11 @@ class MultiplayerConnectionImpl {
         players: () => this.roster?.players ?? [],
         isSolo: () => this.solo,
     });
-    constructor(request, onClosed, destinationAudience = null) {
+    constructor(request, onClosed, destinationAudience = null, pongTimeoutMs = 0) {
         this.request = request;
         this.onClosed = onClosed;
         this.destinationAudience = destinationAudience;
+        this.pongTimeoutMs = pongTimeoutMs;
     }
     get state() {
         return this.currentState;
@@ -233,6 +243,12 @@ class MultiplayerConnectionImpl {
     get sessionId() {
         return this.currentSessionId;
     }
+    get serverBundleSha256() {
+        return this.currentState === "connected" && !this.solo ? this.currentServerBundleSha256 : null;
+    }
+    get serverBundleId() {
+        return this.currentState === "connected" && !this.solo ? this.currentServerBundleId : null;
+    }
     get isSolo() {
         return this.solo;
     }
@@ -553,6 +569,10 @@ class MultiplayerConnectionImpl {
     acceptHello(frame) {
         this.currentPlayerId = frame.playerId;
         this.currentSessionId = frame.sessionId;
+        // Diagnostics never decide whether a hello is accepted. Missing or malformed
+        // metadata clears the previous host's identity on every reconnect.
+        this.currentServerBundleSha256 = typeof frame.serverBundleSha256 === "string" && /^[0-9a-f]{64}$/.test(frame.serverBundleSha256) ? frame.serverBundleSha256 : null;
+        this.currentServerBundleId = typeof frame.serverBundleId === "string" && /^[A-Za-z0-9_-]{10}$/.test(frame.serverBundleId) ? frame.serverBundleId : null;
         this.reconnectToken = frame.reconnectToken;
         this.sharedCharactersSupported = frame.capabilities?.sharedCharactersV1 === true;
         if (this.devReconnectStorageKey)
@@ -587,6 +607,8 @@ class MultiplayerConnectionImpl {
                 this.acceptHello(frame);
                 break;
             case "pong":
+                this.pongExtensionUsed = false;
+                this.clearPongDeadline();
                 break;
         }
     }
@@ -676,10 +698,14 @@ class MultiplayerConnectionImpl {
     }
     startKeepalive() {
         this.stopKeepalive();
+        this.pongExtensionUsed = false;
         this.keepalive = setInterval(() => {
             if (this.socket?.readyState === WebSocket.OPEN) {
+                if (this.pongDeadline !== null)
+                    return;
                 try {
                     this.socket.send('{"t":"ping"}');
+                    this.expectPong(this.socket);
                 }
                 catch {
                     closeSocket(this.socket, 1000, "keepalive failed");
@@ -688,11 +714,46 @@ class MultiplayerConnectionImpl {
         }, KEEPALIVE_INTERVAL_MS);
     }
     stopKeepalive() {
+        this.clearPongDeadline();
         if (this.keepalive === null)
             return;
         clearInterval(this.keepalive);
         this.keepalive = null;
     }
+    clearPongDeadline() {
+        if (this.pongDeadline === null)
+            return;
+        clearTimeout(this.pongDeadline);
+        this.pongDeadline = null;
+    }
+    expectPong(socket) {
+        if (!this.pongTimeoutMs)
+            return;
+        const due = Date.now() + this.pongTimeoutMs;
+        this.pongDeadline = setTimeout(() => {
+            this.pongDeadline = null;
+            if (this.socket !== socket || this.currentState !== "connected")
+                return;
+            // A suspended page can run an overdue timer before queued socket events.
+            // Verify liveness with a fresh ping instead of condemning that socket.
+            if (!this.pongExtensionUsed && Date.now() - due > 1_000 && socket.readyState === WebSocket.OPEN) {
+                this.pongExtensionUsed = true;
+                try {
+                    socket.send('{"t":"ping"}');
+                    this.expectPong(socket);
+                    return;
+                }
+                catch { /* Fall through to recovery if the fresh probe cannot send. */ }
+            }
+            // A half-open transport may never emit close. Fence its queued callbacks
+            // and enter recovery directly rather than waiting for that close event.
+            this.socketAttempt += 1;
+            this.socket = null;
+            this.stopKeepalive();
+            closeSocket(socket, 1000, "pong timeout");
+            this.beginRecovery();
+        }, this.pongTimeoutMs);
+    }
     transition(state, metadata) {
         if (this.currentState === "closed" || this.currentState === state)
             return;

package/dist/multiplayerProtocol.d.ts

@@ -14,6 +14,8 @@ export interface SessionPlayer extends PlayerIdentity {
     playerId: string;
 }
 export interface ClientHelloFrame {
+    serverBundleSha256?: string;
+    serverBundleId?: string;
     t: "hello";
     playerId: string;
     reconnectToken: string;

package/dist/party.d.ts

@@ -0,0 +1,23 @@
+import type { PartyMember, PartyMessage, PartyMessagesResult, PartySummary } from './commands';
+export type { PartyMember, PartyMessage, PartyMessagesResult, PartyStatus, PartySummary, } from './commands';
+export interface CastlePartyApi {
+    /** The party this play was launched with, or null when it has none. */
+    current(): Promise<PartySummary | null>;
+    /** Create a party containing these users and the signed-in player. */
+    create(userIds: string[]): Promise<PartySummary>;
+    invite(partyId: string, userIds: string[]): Promise<{
+        ok: true;
+    }>;
+    respond(partyId: string, accept: boolean): Promise<{
+        ok: true;
+    }>;
+    members(partyId: string): Promise<PartyMember[]>;
+    leave(partyId: string): Promise<{
+        ok: true;
+    }>;
+    /** Newest first. Pass `cursor` to load older history. */
+    messages(partyId: string, cursor?: string): Promise<PartyMessagesResult>;
+    /** Send plain text; the host trims it to Castle's 1,000-character limit. */
+    say(partyId: string, text: string): Promise<PartyMessage>;
+}
+export declare const Party: CastlePartyApi;

package/dist/party.js

@@ -0,0 +1,91 @@
+import { CastleError } from './errors';
+import { hostRequest } from './transport';
+export const Party = {
+    current,
+    create,
+    invite,
+    respond,
+    members,
+    leave,
+    messages,
+    say,
+};
+const ID_MAX = 128;
+const CURSOR_MAX = 512;
+const PARTY_USERS_MAX = 32;
+function id(value, field, operation) {
+    return boundedText(value, field, operation, ID_MAX);
+}
+function boundedText(value, field, operation, max) {
+    if (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= max &&
+        !value.includes('\0')) {
+        return value;
+    }
+    throw new CastleError({
+        code: 'INVALID_ARGUMENT',
+        message: `${operation} requires a valid ${field}.`,
+        operation,
+    });
+}
+function ids(value, operation) {
+    if (!Array.isArray(value) || value.length > PARTY_USERS_MAX) {
+        throw new CastleError({
+            code: 'INVALID_ARGUMENT',
+            message: `${operation} requires at most ${PARTY_USERS_MAX} user ids.`,
+            operation,
+        });
+    }
+    return value.map((value) => id(value, 'userId', operation));
+}
+async function current() {
+    return hostRequest('party.current', {});
+}
+async function create(userIds) {
+    return hostRequest('party.create', { userIds: ids(userIds, 'Party.create') });
+}
+async function invite(partyId, userIds) {
+    return hostRequest('party.invite', {
+        partyId: id(partyId, 'partyId', 'Party.invite'),
+        userIds: ids(userIds, 'Party.invite'),
+    });
+}
+async function respond(partyId, accept) {
+    if (typeof accept !== 'boolean') {
+        throw new CastleError({
+            code: 'INVALID_ARGUMENT',
+            message: 'Party.respond requires accept to be a boolean.',
+            operation: 'Party.respond',
+        });
+    }
+    return hostRequest('party.respond', {
+        partyId: id(partyId, 'partyId', 'Party.respond'),
+        accept,
+    });
+}
+async function members(partyId) {
+    return hostRequest('party.members', { partyId: id(partyId, 'partyId', 'Party.members') });
+}
+async function leave(partyId) {
+    return hostRequest('party.leave', { partyId: id(partyId, 'partyId', 'Party.leave') });
+}
+async function messages(partyId, cursor) {
+    const params = {
+        partyId: id(partyId, 'partyId', 'Party.messages'),
+    };
+    if (cursor !== undefined) {
+        params.cursor = boundedText(cursor, 'cursor', 'Party.messages', CURSOR_MAX);
+    }
+    return hostRequest('party.messages', params);
+}
+async function say(partyId, text) {
+    if (typeof text !== 'string' || text.length === 0) {
+        throw new CastleError({
+            code: 'INVALID_ARGUMENT',
+            message: 'Party.say requires text.',
+            operation: 'Party.say',
+        });
+    }
+    return hostRequest('party.say', { partyId: id(partyId, 'partyId', 'Party.say'), text });
+}

package/dist/save.d.ts

@@ -63,6 +63,13 @@ export interface SaveTransactionInput {
     checks?: SaveCheck[];
     changes: SaveChange[];
 }
+export interface SaveConditionalCheck extends Omit<SaveCheck, "expectedRevision"> {
+    /** Null checks absence without creating the target. */
+    expectedRevision: SaveRevision | null;
+}
+export interface SaveConditionalWriteInput extends Omit<SaveTransactionInput, "checks"> {
+    checks?: SaveConditionalCheck[];
+}
 export interface SaveInitial {
     target: SaveTarget;
     rows: SaveRows;
@@ -95,8 +102,24 @@ export type SaveOperation = {
 } | {
     state: "unknown";
 };
-export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation";
+export interface SaveRecentOperationsInput {
+    limit?: number;
+    cursor?: string;
+}
+export interface SaveRecentOperationsPage {
+    operations: {
+        operationId: string;
+        committedAt: string;
+        receipt: SaveReceipt;
+    }[];
+    cursor: string | null;
+}
+export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation" | "conditionalWrite" | "recentOperations";
 export interface SaveApi {
+    /** Gated atomic revision check and write, up to eight targets and two players. */
+    conditionalWrite(input: SaveConditionalWriteInput): Promise<SaveReceipt>;
+    /** Gated caller-scoped receipt discovery after losing local operation IDs. */
+    recentOperations(input?: SaveRecentOperationsInput): Promise<SaveRecentOperationsPage>;
     snapshot(input: {
         targets: SaveReadTarget[];
     }): Promise<SaveSnapshot>;
@@ -156,6 +179,7 @@ export interface SaveErrorEnvelope {
     receipt?: SaveReceipt;
     retryAfterMs?: number;
     target?: SaveTarget;
+    current?: SaveSnapshot;
     [detail: string]: unknown;
 }
 export declare class SaveError extends CastleError {
@@ -165,6 +189,7 @@ export declare class SaveError extends CastleError {
     readonly receipt?: SaveReceipt;
     readonly retryAfterMs?: number;
     readonly target?: SaveTarget;
+    readonly current?: SaveSnapshot;
     constructor(envelope: SaveErrorEnvelope);
 }
 /**

package/dist/save.js

@@ -7,6 +7,7 @@ export class SaveError extends CastleError {
     receipt;
     retryAfterMs;
     target;
+    current;
     constructor(envelope) {
         super({
             code: envelope.code,
@@ -20,6 +21,7 @@ export class SaveError extends CastleError {
         this.receipt = envelope.receipt;
         this.retryAfterMs = envelope.retryAfterMs;
         this.target = envelope.target;
+        this.current = envelope.current;
     }
 }
 /**
@@ -241,12 +243,14 @@ function encodeChange(change, server) {
         ...(remove === undefined ? {} : { remove }),
     };
 }
-function encodeCheck(check, server) {
+function encodeCheck(check, server, conditional = false) {
     const target = validateSaveTarget(check.target, server);
+    if (conditional && check.expectedRevision === undefined)
+        invalid("Every conditional check needs an expected revision.");
     if (check.expectedRevision === undefined && check.writer === undefined) {
         invalid("A check needs an expected revision or a writer.");
     }
-    if (check.expectedRevision !== undefined) {
+    if (check.expectedRevision !== undefined && !(conditional && check.expectedRevision === null)) {
         checkText(check.expectedRevision, "expected revision");
     }
     if (check.writer !== undefined)
@@ -259,7 +263,7 @@ function encodeCheck(check, server) {
         ...(check.writer === undefined ? {} : { writer: check.writer }),
     };
 }
-function encodeTransaction(input, server) {
+function encodeTransaction(input, server, conditional = false) {
     const changes = checkList(input.changes, "changes").map((change) => encodeChange(change, server));
     const keys = changes.map((change) => saveTargetKey(change.target));
     if (new Set(keys).size !== keys.length) {
@@ -271,7 +275,7 @@ function encodeTransaction(input, server) {
         ...(input.checks === undefined
             ? {}
             : {
-                checks: checkList(input.checks, "checks").map((check) => encodeCheck(check, server)),
+                checks: checkList(input.checks, "checks").map((check) => encodeCheck(check, server, conditional)),
             }),
         changes,
     };
@@ -283,12 +287,26 @@ export function encodeSaveInput(verb, input, server = false) {
     }
     if (verb === "snapshot")
         return { targets: encodeReads(input.targets, server) };
+    if (verb === "recentOperations") {
+        const limit = input.limit ?? 16;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 32)
+            invalid("Recovery limit must be 1 to 32.");
+        if (input.cursor !== undefined)
+            checkText(input.cursor, "recovery cursor", 2048);
+        return { limit, ...(input.cursor === undefined ? {} : { cursor: input.cursor }) };
+    }
     checkText(input.operationId, "operation id", MAX_KEY_BYTES);
     if (verb === "operation")
         return { operationId: input.operationId };
-    if (verb === "transaction") {
+    if (verb === "transaction" || verb === "conditionalWrite") {
+        if (verb === "conditionalWrite") {
+            const changes = input.changes;
+            const checks = input.checks ?? [];
+            if (!Array.isArray(changes) || !changes.length || changes.length + checks.length > 8)
+                invalid("Conditional writes require 1 to 8 targets.");
+        }
         return {
-            ...encodeTransaction(input, server),
+            ...encodeTransaction(input, server, verb === "conditionalWrite"),
         };
     }
     if (input.expectedAccess !== undefined) {
@@ -423,6 +441,34 @@ export function createSaveApi(call, server = false) {
         }
     }
     return {
+        async conditionalWrite(input) {
+            const result = await send("conditionalWrite", { ...input });
+            return decodeReceipt(result, input.operationId, input.changes.map((change) => change.target));
+        },
+        async recentOperations(input = {}) {
+            const page = (await send("recentOperations", {
+                ...input,
+            }));
+            if (!page ||
+                !Array.isArray(page.operations) ||
+                page.operations.length > (input.limit ?? 16) ||
+                (page.cursor !== null && typeof page.cursor !== "string"))
+                invalidResponse();
+            return {
+                operations: page.operations.map((operation) => {
+                    if (!operation ||
+                        typeof operation.operationId !== "string" ||
+                        typeof operation.committedAt !== "string")
+                        invalidResponse();
+                    return {
+                        operationId: operation.operationId,
+                        committedAt: operation.committedAt,
+                        receipt: decodeReceipt(operation.receipt, operation.operationId, []),
+                    };
+                }),
+                cursor: page.cursor,
+            };
+        },
         async snapshot(input) {
             return decodeSnapshot(await send("snapshot", { ...input }), input.targets);
         },

package/dist/server/hub.d.ts

@@ -184,8 +184,27 @@ export interface MultiplayerHubResultsRead {
  * and for a deck that declares no hub block.
  */
 export interface MultiplayerServerHub {
+    /** Durably appends NPC words to a private platform archive. No read operation. */
+    archiveText(playerId: string, entry: {
+        npcId: string;
+        characterId?: string;
+        conversationId?: string;
+        operationId: string;
+        input?: string;
+        reply?: string;
+    }): Promise<void>;
+    /** Numeric hub telemetry; unavailable/refused delivery returns false, never blocks play. */
+    track(playerId: string, event: {
+        kind: number;
+        subject?: number;
+        value?: number;
+        result?: number;
+        flags?: number;
+    }): Promise<boolean>;
     /** The owner user id, only in an owner door instance. */
     readonly owner?: string;
+    /** Host-pinned inclusive reconnect grace for this hub place, in milliseconds. */
+    readonly reconnectWindowMs?: number;
     readonly place: string | null;
     readonly title: string | null;
     readonly result: MultiplayerHubResultShape | null;
@@ -236,9 +255,13 @@ export interface MultiplayerServerHub {
     /**
      * The connected player's mutual friends and follows in either direction among
      * these candidates, in one host read. Missing lists are empty; refusals reject.
+     * Optional strict mode rejects malformed raw lists and marks the result validated.
      * These relations belong to this player only; never send them to another client.
      */
-    relationsAmong(playerId: string, userIds: readonly string[]): Promise<{
+    relationsAmong(playerId: string, userIds: readonly string[], options?: {
+        strict: true;
+    }): Promise<{
+        validated?: true;
         friends: string[];
         follows: string[];
         followedBy: string[];

package/dist/server/hub.js

@@ -46,6 +46,11 @@ function unavailable(op, what) {
         operation: `session.hub.${op}`,
     });
 }
+function reconnectMetadata(pinned) {
+    const value = pinned.reconnectWindowMs;
+    return pinned.result === null && typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 180_000
+        ? { reconnectWindowMs: value } : {};
+}
 export function createServerHub(platformHandle, arrivals, hiddenPair = () => false) {
     const pinned = platformHandle.hub;
     if (!pinned ||
@@ -72,17 +77,35 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
         }
         return parsed;
     };
-    return Object.freeze({
+    const hub = {
+        async archiveText(playerId, entry) {
+            if (platformHandle.hubTextArchiveEnabled !== true || typeof platformHandle.storage !== "function")
+                throw unavailable("archiveText", "archive NPC transcripts");
+            const raw = await platformHandle.storage("hubTextArchive", JSON.stringify({ ...entry, playerId }));
+            if (JSON.parse(raw)?.recorded !== true)
+                throw unavailable("archiveText", "archive NPC transcripts");
+        },
         place: typeof pinned.place === "string" ? pinned.place : null,
         title: typeof pinned.title === "string" ? pinned.title : null,
         result: pinned.result ?? null,
         ...(typeof pinned.owner === "string" && pinned.owner.length > 0 ? { owner: pinned.owner } : {}),
+        ...reconnectMetadata(pinned),
         arrival(playerId) {
             return arrivals.get(playerId) ?? null;
         },
         hiddenPair(playerIdA, playerIdB) {
             return hiddenPair(playerIdA, playerIdB);
         },
+        async track(playerId, event) {
+            try {
+                const json = JSON.stringify({ ...event, playerId });
+                const raw = await platformHandle.storage?.("hubTrack", json);
+                return JSON.parse(raw ?? "null")?.recorded === true;
+            }
+            catch {
+                return false;
+            }
+        },
         async friendsAmong(playerId, userIds) {
             const json = JSON.stringify({ playerId, userIds: [...userIds] });
             const raw = typeof platformHandle.hubFriendsAmong === "function"
@@ -91,7 +114,7 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
             const answer = JSON.parse(raw ?? "null");
             return Array.isArray(answer?.userIds) ? answer.userIds : [];
         },
-        async relationsAmong(playerId, userIds) {
+        async relationsAmong(playerId, userIds, options = undefined) {
             const asked = new Set(userIds);
             const json = JSON.stringify({ playerId, userIds: [...userIds] });
             let raw;
@@ -102,10 +125,14 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
                 raw = await platformHandle.storage?.("hubFriendsAmong", json);
             }
             const answer = JSON.parse(raw ?? "null");
+            if (options?.strict === true && (!answer || ["userIds", "follows", "followedBy"].some((key) => !Array.isArray(answer[key]) || answer[key].length > 100 || answer[key].some((id) => typeof id !== "string" || !/^\d{1,20}$/.test(id) || !asked.has(id))))) {
+                throw new CastleError({ code: "CAULDRON_HUB_INVALID_RESPONSE", message: "The platform returned an invalid friends response.", operation: "session.hub.relationsAmong" });
+            }
             const list = (value) => Array.isArray(value)
                 ? value.filter((id) => typeof id === "string" && asked.has(id))
                 : [];
             return {
+                ...(options?.strict === true ? { validated: true } : {}),
                 friends: list(answer?.userIds),
                 follows: list(answer?.follows),
                 followedBy: list(answer?.followedBy),
@@ -191,5 +218,10 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
                 players: (read.players ?? {}),
             };
         },
-    });
+    };
+    // Preserve the enumerable API shape and diagnostic serialization of existing
+    // places. Opted-in kits call this method explicitly; it adds no wire field.
+    Object.defineProperty(hub, "track", { enumerable: false });
+    Object.defineProperty(hub, "archiveText", { enumerable: false });
+    return Object.freeze(hub);
 }

package/dist/server/platformHandle.d.ts

@@ -6,6 +6,8 @@ export interface PlayerIdentity {
     username: string;
     isAnonymous: boolean;
     scopedUserId?: string;
+    /** Trusted hub age boundary; omitted by older hosts. Never client supplied. */
+    under13?: boolean;
 }
 export interface PlatformSessionConfig {
     readonly sessionId: string;
@@ -66,11 +68,16 @@ export interface PlatformHandle {
     storage?(op: string, argsJson: string): Promise<string>;
     /** False when the host cannot broker storage, so a call can fail at once. */
     readonly storageEnabled?: boolean;
+    readonly hubTextArchiveEnabled?: boolean;
     /** Persistent-world checkpoint broker. The host stamps the hidden world binding. */
     worldCheckpointRead?(): Promise<string>;
     worldCheckpointCommit?(argsJson: string): Promise<string>;
     /** `tools` is the turn's place tools, passed only when non-empty. */
-    worldCharacterSend?(grantId: string, tools?: readonly PlatformPlaceTool[]): Promise<string>;
+    worldCharacterSend?(grantId: string, tools?: readonly PlatformPlaceTool[], hubTextArchive?: {
+        npcId: string;
+        conversationId?: string;
+        input: string;
+    }): Promise<string>;
     worldCharacterCommand?(grantId: string): Promise<string>;
     worldCharacterRead?(grantId: string): Promise<string>;
     worldCharacterRuntimeCreate?(argsJson: string): Promise<string>;
@@ -114,6 +121,7 @@ export interface PlatformHubResultShape {
 }
 export interface PlatformHubPlace {
     owner?: string;
+    reconnectWindowMs?: number;
     place?: string;
     title?: string | null;
     result?: PlatformHubResultShape | null;

package/dist/server/storage.d.ts

@@ -51,6 +51,8 @@ export interface ServerStorageBoard {
  */
 export interface ServerPlaythrough {
     readonly generation: number;
+    /** Present only after an administrator reset this player's deck progress. */
+    readonly resetGeneration?: number;
     /** Explicit narrative changes for this same player and generation. */
     readonly characters: ServerPlaythroughCharacters;
     get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;

package/dist/server/storage.js

@@ -100,11 +100,11 @@ export function createServerStorage(platformHandle) {
         async playthrough(userId) {
             const subject = assertUserId(userId, "session.storage.playthrough");
             const opened = await call("playthroughOpen", { subject });
-            return createPlaythrough(call, subject, assertGeneration(opened?.generation));
+            return createPlaythrough(call, subject, assertGeneration(opened?.generation), optionalResetGeneration(opened?.resetGeneration));
         },
     };
 }
-function createPlaythrough(call, subject, generation) {
+function createPlaythrough(call, subject, generation, resetGeneration) {
     const characters = Object.freeze({
         async send(input) {
             const characterId = assertNarrativeId(input?.characterId, "characterId");
@@ -220,6 +220,7 @@ function createPlaythrough(call, subject, generation) {
     });
     return Object.freeze({
         generation,
+        ...(resetGeneration === undefined ? {} : { resetGeneration }),
         characters,
         async get(keys) {
             const entries = await call("playthroughGet", { subject, generation, keys: assertKeys(keys, "session.storage.playthrough.get") });
@@ -242,7 +243,7 @@ function createPlaythrough(call, subject, generation) {
                 generation,
                 operationId: assertOperationId(operationId),
             });
-            return createPlaythrough(call, subject, assertGeneration(reset?.generation));
+            return createPlaythrough(call, subject, assertGeneration(reset?.generation), resetGeneration);
         },
     });
 }
@@ -417,6 +418,13 @@ function assertGeneration(value) {
     }
     return value;
 }
+function optionalResetGeneration(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (Number.isSafeInteger(value) && value >= 1 && value <= MAX_GENERATION)
+        return value;
+    throw storageError("CAULDRON_STORAGE_INVALID_RESPONSE", "The platform returned an invalid progress reset generation.", "session.storage.playthrough");
+}
 function assertOperationId(value) {
     if (typeof value !== "string" ||
         value.length === 0 ||