castle-web-sdk 0.4.45 → 0.4.46

package/dist/multiplayer.d.ts

@@ -1,4 +1,4 @@
-import type { MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
+import type { HubHandoffResult, MultiplayerDestinationAudience, MultiplayerJoinHint, MultiplayerSoloReason } from "./commands";
 import { CastleError } from "./errors";
 import type { Json } from "./types";
 import { type MultiplayerPlayer, type MultiplayerCharacterDisclosure, type MultiplayerCharacterTurnStatus } from "./multiplayerProtocol";
@@ -11,6 +11,9 @@ export type MultiplayerJoinOptions = {
     mode: "party";
 } | {
     mode: "public";
+} | {
+    mode: "hub";
+    handoff: HubHandoffResult;
 };
 export interface MultiplayerDestinationOptions {
     routeId: string;
@@ -79,7 +82,45 @@ export type MultiplayerWorldCharacterCommand = {
     type: "record_event";
     eventTypeId: string;
     data?: Json;
+    /** Characters that saw it (at most 4); each may act on its own about the recorder. */
+    witnesses?: string[];
+} | MultiplayerEvaluateBeatsCommand | MultiplayerCompleteScheduledBeatCommand;
+export type MultiplayerStoryOpportunity = {
+    type: "approach" | "room_entry" | "world_action";
+    id: string;
 };
+export interface MultiplayerEvaluateBeatsCommand {
+    type: "evaluate_beats";
+    opportunityId: string;
+    opportunity: MultiplayerStoryOpportunity;
+    presentCharacterIds: string[];
+}
+export interface MultiplayerCompleteScheduledBeatCommand {
+    type: "complete_scheduled_beat";
+    deliveryId: string;
+    outcomeId: string;
+}
+export interface MultiplayerScheduledBeatSelection {
+    deliveryId: string;
+    beatId: string;
+    characterId: string;
+    openingText: string;
+}
+export interface MultiplayerScheduledBeatReason {
+    beatId: string;
+    status: "selected" | "expired" | "eligible" | "blocked";
+    reasonCodes: string[];
+}
+export interface MultiplayerEvaluateBeatsResult {
+    selection: MultiplayerScheduledBeatSelection | null;
+    reasons?: MultiplayerScheduledBeatReason[];
+}
+export interface MultiplayerCompleteScheduledBeatResult {
+    deliveryId: string;
+    outcomeId: string;
+    completed: true;
+}
+export type MultiplayerWorldCharacterCommandResultValue<Command extends MultiplayerWorldCharacterCommand> = Command extends MultiplayerEvaluateBeatsCommand ? MultiplayerEvaluateBeatsResult : Command extends MultiplayerCompleteScheduledBeatCommand ? MultiplayerCompleteScheduledBeatResult : Json;
 export type MultiplayerWorldCharacterQuery = {
     type: "inspect";
 } | {
@@ -90,7 +131,33 @@ export type MultiplayerWorldCharacterQuery = {
     characterId?: string;
     limit?: number;
     cursor?: string;
+}
+/** Autonomous-action notices after a cursor (world-visible). */
+ | {
+    type: "actions";
+    after?: string;
 };
+/** One autonomous character decision in a shared world. */
+export interface MultiplayerCharacterActionNotice {
+    characterId: string;
+    /** The participant the character acted about: the one whose deed it witnessed. */
+    participantId: string;
+    trigger: {
+        type: "witnessed";
+        id: string;
+    };
+    outcome: "acted" | "declined" | "failed";
+    actionId?: string;
+    variantId?: string;
+    eventOccurrenceId?: string;
+    probability?: number;
+    /** Feed cursor; pass the last one as `after` to read only newer notices. */
+    sequence: string;
+}
+export interface MultiplayerWorldCharacterActionsResult {
+    notices: MultiplayerCharacterActionNotice[];
+    after: string;
+}
 /** Authenticated, participant-scoped projection of a shared character world. */
 export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, SharedState = unknown, PrivateState = unknown, Source = unknown> {
     /** Durable identity used by gameplay holders and promise debtors. */
@@ -106,11 +173,11 @@ export interface MultiplayerWorldCharacterInspectResult<Gameplay = unknown, Shar
     }>;
     sources: Source[];
 }
-export interface MultiplayerWorldCharacterCommandResult {
+export interface MultiplayerWorldCharacterCommandResult<Result = unknown> {
     operationId: string;
     status: "applied" | "ineligible";
     replayed: boolean;
-    result: unknown;
+    result: Result;
     worldRevision: string;
 }
 export interface MultiplayerConnection {
@@ -123,17 +190,24 @@ export interface MultiplayerConnection {
      * `private_deck` and `no_server_bundle` are the creator's to fix.
      */
     readonly soloReason: MultiplayerSoloReason | null;
+    /**
+     * Whether the host brokers shared characters into this session (its hello
+     * advertised them): a shared-character world, or a hub place's layer with
+     * place characters. The character calls below refuse while this is false.
+     * Read it when needed: a reconnect can land on a host that says otherwise.
+     */
+    readonly sharedCharacters: boolean;
     /** Sends byte payloads as binary frames and all other payloads as JSON. */
     send(data: unknown): void;
     /** Requests one billed character turn through this authenticated world socket. */
     requestCharacterTurn(request: MultiplayerCharacterTurnRequest): Promise<MultiplayerCharacterTurnAdmission>;
     /** Recovers the durable status of a prior operation after reconnecting. */
     getCharacterTurnStatus(operationId: string): Promise<MultiplayerCharacterTurnStatusResult>;
-    requestCharacterCommand(request: {
+    requestCharacterCommand<Command extends MultiplayerWorldCharacterCommand>(request: {
         requestId: string;
         operationId: string;
-        command: MultiplayerWorldCharacterCommand;
-    }): Promise<MultiplayerWorldCharacterCommandResult>;
+        command: Command;
+    }): Promise<MultiplayerWorldCharacterCommandResult<MultiplayerWorldCharacterCommandResultValue<Command>>>;
     readCharacters(request: {
         requestId: string;
         query: {
@@ -153,6 +227,12 @@ export interface MultiplayerConnection {
     leave(): void;
 }
 export interface CastleMultiplayerApi {
+    /**
+     * True on an SDK whose session server can address a hub place's shared
+     * characters from a layer (`session.characters` without `session.world`).
+     * Absent on older SDKs, so a kit can tell before joining.
+     */
+    readonly placeCharacters: true;
     join(options: MultiplayerJoinOptions): Promise<MultiplayerConnection>;
     joinHint(): Promise<MultiplayerJoinHint | null>;
     joinDestination(options: MultiplayerDestinationOptions): Promise<MultiplayerDestinationJoinResult>;

package/dist/multiplayer.js

@@ -18,7 +18,12 @@ let nextCharacterStatusRequestId = 1;
 let activeConnection = null;
 let latestJoinAttempt = 0;
 let pendingDestinationJoin = null;
-export const Multiplayer = { join, joinHint, joinDestination };
+export const Multiplayer = {
+    placeCharacters: true,
+    join,
+    joinHint,
+    joinDestination,
+};
 async function joinHint() {
     try {
         return await hostRequest("multiplayer.getJoinHint", {});
@@ -30,18 +35,71 @@ async function joinHint() {
     }
 }
 async function join(options) {
-    const params = joinParams(options);
+    const hub = hubJoin(options);
+    const request = hub
+        ? { command: "hub", nonce: hub.nonce }
+        : { command: "multiplayer.getSession", params: joinParams(options) };
     latestJoinAttempt += 1;
     cancelPendingDestinationJoin();
     activeConnection?.leave();
-    const connection = new MultiplayerConnectionImpl({ command: "multiplayer.getSession", params }, () => {
+    const connection = new MultiplayerConnectionImpl(request, () => {
         if (activeConnection === connection)
             activeConnection = null;
     });
     activeConnection = connection;
-    await connection.start();
+    await connection.start(hub ?? undefined);
+    // The host moves its place (and every place-scoped command with it) when the
+    // trip commits; the deck gets the connection once it has. A trip that did not
+    // commit leaves the player where they were, so its connection is closed.
+    if (!(await connection.hubCommitted())) {
+        connection.leave();
+        throw multiplayerError("MULTIPLAYER_UNAVAILABLE", "The hub trip could not be completed; the player is still where they were.", "Multiplayer.join");
+    }
+    connection.handedOver();
     return connection;
 }
+// A hub handoff is joined as it was acquired; it cannot be acquired again.
+// The host answers `unavailable` while ghost is busy with this player; the
+// trip stays pending there, so asking again is safe.
+const HUB_COMMIT_RETRY_MS = [1_000, 2_000, 4_000, 8_000];
+async function commitHubTrip(nonce, sessionId) {
+    for (let attempt = 0;; attempt++) {
+        let status;
+        try {
+            status = (await hostRequest("hub.commit", { nonce })).status;
+        }
+        catch (error) {
+            status = error instanceof CastleError ? error.code : "unavailable";
+        }
+        if (status === "committed")
+            return true;
+        const delay = HUB_COMMIT_RETRY_MS[attempt];
+        if ((status !== "unavailable" && status !== "CASTLE_HOST_UNAVAILABLE") || delay === undefined) {
+            console.warn(`Castle hub trip to ${sessionId} was not committed: ${status}`);
+            return false;
+        }
+        await pause(delay);
+    }
+}
+function hubJoin(options) {
+    if (!options || typeof options !== "object" || options.mode !== "hub")
+        return null;
+    const handoff = options.handoff;
+    if (!handoff ||
+        handoff.status !== "ok" ||
+        typeof handoff.url !== "string" ||
+        typeof handoff.nonce !== "string" ||
+        typeof handoff.sessionId !== "string") {
+        throw multiplayerError("INVALID_ARGUMENT", "Multiplayer.join({ mode: \"hub\" }) requires an ok result from Hub.go or Hub.back.", "Multiplayer.join");
+    }
+    return {
+        status: "ok",
+        url: handoff.url,
+        nonce: handoff.nonce,
+        sessionId: handoff.sessionId,
+        soloReason: null,
+    };
+}
 async function joinDestination(options) {
     const params = destinationParams(options);
     const attempt = ++latestJoinAttempt;
@@ -112,6 +170,8 @@ async function joinDestination(options) {
     activeConnection = connection;
     return { status: "joined", connection, audience: acquired.audience };
 }
+// How many messages are kept for a deck that has not attached a listener yet.
+const EARLY_MESSAGES_MAX = 512;
 class MultiplayerConnectionImpl {
     request;
     onClosed;
@@ -129,10 +189,22 @@ class MultiplayerConnectionImpl {
     keepalive = null;
     reAcquisitionUsed = false;
     recovering = false;
+    hubSettled = false;
+    hubCommit = Promise.resolve(true);
     roster = null;
     sharedCharactersSupported = false;
     pendingCharacterRequests = new Map();
     messages = new Set();
+    // Messages that arrived before the deck had a listener, on a hub join only.
+    // A hub join resolves some tasks after the socket's hello (it first commits
+    // with the host), and a place greets a player with a snapshot in that gap:
+    // with nobody listening it was dropped, and the deck never saw the state it
+    // joined into. They are kept, in order, for a listener attached as soon as
+    // the deck is handed the connection (`handedOver`); a deck that attaches one
+    // later gets only what arrives from then on. Null on every other join, which
+    // resolves in the hello's own task: nothing is kept there and delivery is
+    // exactly what it always was.
+    early = null;
     rosters = new Set();
     states = new Set();
     voiceImpl = new MultiplayerVoiceImpl({
@@ -160,6 +232,9 @@ class MultiplayerConnectionImpl {
     get soloReason() {
         return this.currentSoloReason;
     }
+    get sharedCharacters() {
+        return this.sharedCharactersSupported;
+    }
     get voice() {
         return this.voiceImpl;
     }
@@ -168,6 +243,7 @@ class MultiplayerConnectionImpl {
             await this.acquire(initial);
         }
         catch (error) {
+            this.settleHub("cancel");
             const castleError = asCastleError(error);
             if (this.currentState !== "closed") {
                 this.finish({ type: "error", error: castleError });
@@ -249,8 +325,43 @@ class MultiplayerConnectionImpl {
     }
     onMessage(callback) {
         this.messages.add(callback);
+        const early = this.early;
+        if (early) {
+            // The first listener takes what arrived before it; later ones get only
+            // what arrives from now on, as before.
+            this.early = null;
+            for (const data of early) {
+                // A listener that leaves part-way hears no more.
+                if (this.currentState === "closed")
+                    break;
+                callListener(callback, data);
+            }
+        }
         return () => this.messages.delete(callback);
     }
+    /**
+     * The deck is being handed this connection. Whatever arrived before that is
+     * kept through the deck's own next step (the code after its `await`), where
+     * a kit attaches its listener; after that, nothing more is kept.
+     */
+    handedOver() {
+        if (!this.early)
+            return;
+        setTimeout(() => {
+            if (this.messages.size === 0)
+                this.early = null;
+        }, 0);
+    }
+    deliver(data) {
+        if (this.early && this.messages.size === 0) {
+            // Bounded: a deck that never listens does not grow this forever.
+            if (this.early.length < EARLY_MESSAGES_MAX)
+                this.early.push(data);
+            return;
+        }
+        for (const callback of this.messages)
+            callListener(callback, data);
+    }
     onRoster(callback) {
         this.rosters.add(callback);
         if (this.roster)
@@ -265,8 +376,27 @@ class MultiplayerConnectionImpl {
     leave() {
         if (this.currentState === "closed")
             return;
+        this.settleHub("cancel");
         this.finish({ type: "left" });
     }
+    // A hub trip is the host's to commit or cancel, once: committed when the
+    // destination first says hello, cancelled if the join ends before that. The
+    // acquisition is named by its nonce, which no other acquisition shares.
+    settleHub(outcome) {
+        if (this.request.command !== "hub" || this.hubSettled)
+            return;
+        this.hubSettled = true;
+        const nonce = this.request.nonce;
+        if (outcome === "cancel") {
+            hostRequest("hub.cancel", { nonce }).catch(() => { });
+            return;
+        }
+        this.early = [];
+        this.hubCommit = commitHubTrip(nonce, this.currentSessionId);
+    }
+    hubCommitted() {
+        return this.hubCommit;
+    }
     matchesDestination(params) {
         return (this.currentState !== "closed" &&
             this.request.command === "multiplayer.joinDestination" &&
@@ -329,6 +459,8 @@ class MultiplayerConnectionImpl {
     }
     connectSolo(result) {
         this.solo = true;
+        // A solo session has no host, so no characters, whatever the last socket's hello offered.
+        this.sharedCharactersSupported = false;
         this.currentSoloReason = result.soloReason ?? "unavailable";
         this.currentPlayerId = "solo";
         this.currentSessionId = result.sessionId ?? "solo";
@@ -422,6 +554,7 @@ class MultiplayerConnectionImpl {
         // is backgrounded many times in a play, and each of those is its own outage;
         // without this the second one finds the budget spent and closes for good.
         this.reAcquisitionUsed = false;
+        this.settleHub("commit");
         this.transition("connected");
         this.startKeepalive();
         void this.voiceImpl.attach();
@@ -432,8 +565,7 @@ class MultiplayerConnectionImpl {
                 this.acceptRoster(frame);
                 break;
             case "m":
-                for (const callback of this.messages)
-                    callListener(callback, frame.d);
+                this.deliver(frame.d);
                 break;
             case "worldCharacterResult":
                 this.acceptWorldCharacterResult(frame);
@@ -458,8 +590,7 @@ class MultiplayerConnectionImpl {
         if (bytes.byteLength < 1 || bytes[0] !== BINARY_MESSAGE_TAG)
             return;
         const payload = new Uint8Array(buffer, 1);
-        for (const callback of this.messages)
-            callListener(callback, payload);
+        this.deliver(payload);
     }
     acceptRoster(frame) {
         const players = frame.players.slice();
@@ -569,6 +700,7 @@ class MultiplayerConnectionImpl {
         this.socketAttempt += 1;
         closeSocket(socket, 1000, "session closed");
         this.currentState = "closed";
+        this.early = null;
         this.voiceImpl.dispose();
         for (const callback of this.states)
             callStateListener(callback, "closed", metadata);
@@ -685,6 +817,11 @@ function cancelPendingDestinationJoin() {
     pending?.connection?.leave();
 }
 async function requestAcquisition(request) {
+    if (request.command === "hub") {
+        // The nonce was single-use and the trip is the host's; a hub session that
+        // cannot be reconnected to is left by going back through the door.
+        throw multiplayerError("MULTIPLAYER_CONNECTION_LOST", "A hub session cannot be acquired again. Go back through the door.");
+    }
     if (request.command === "multiplayer.getSession") {
         return hostRequest(request.command, request.params);
     }
@@ -778,6 +915,42 @@ function normalizeWorldCharacterCommandRequest(request) {
                 type: "record_event",
                 eventTypeId: boundedCharacterText(command.eventTypeId, 128, "command.eventTypeId", WORLD_CHARACTER_ID_MAX_CHARACTERS),
                 ...(command.data === undefined ? {} : { data: normalizeJson(command.data, "command.data") }),
+                ...(command.witnesses === undefined ? {} : { witnesses: normalizeWitnesses(command.witnesses) }),
+            },
+        };
+    }
+    if (command.type === "evaluate_beats") {
+        const opportunity = command.opportunity;
+        if (!opportunity || typeof opportunity !== "object") {
+            throw characterError("INVALID_ARGUMENT", "command.opportunity must be an opportunity object.");
+        }
+        if (opportunity.type !== "approach" &&
+            opportunity.type !== "room_entry" &&
+            opportunity.type !== "world_action") {
+            throw characterError("INVALID_ARGUMENT", "command.opportunity.type is invalid.");
+        }
+        return {
+            requestId,
+            operationId,
+            command: {
+                type: "evaluate_beats",
+                opportunityId: boundedCharacterSafeKey(command.opportunityId, "command.opportunityId"),
+                opportunity: {
+                    type: opportunity.type,
+                    id: boundedCharacterSafeKey(opportunity.id, "command.opportunity.id"),
+                },
+                presentCharacterIds: boundedCharacterSafeKeys(command.presentCharacterIds, 16, "command.presentCharacterIds"),
+            },
+        };
+    }
+    if (command.type === "complete_scheduled_beat") {
+        return {
+            requestId,
+            operationId,
+            command: {
+                type: "complete_scheduled_beat",
+                deliveryId: boundedCharacterSafeKey(command.deliveryId, "command.deliveryId"),
+                outcomeId: boundedCharacterSafeKey(command.outcomeId, "command.outcomeId"),
             },
         };
     }
@@ -808,8 +981,20 @@ function normalizeWorldCharacterReadRequest(request) {
             },
         };
     }
+    if (query.type === "actions") {
+        if (query.after !== undefined && (typeof query.after !== "string" || !/^\d{1,18}$/.test(query.after))) {
+            throw characterError("INVALID_ARGUMENT", "Character actions cursor must be a sequence string.");
+        }
+        return { requestId, query: { type: "actions", ...(query.after === undefined ? {} : { after: query.after }) } };
+    }
     throw characterError("INVALID_ARGUMENT", "Unknown shared character query type.");
 }
+function normalizeWitnesses(value) {
+    if (!Array.isArray(value) || value.length > 4) {
+        throw characterError("INVALID_ARGUMENT", "command.witnesses must be at most 4 character ids.");
+    }
+    return value.map((item, index) => boundedCharacterText(item, 128, `command.witnesses[${index}]`, WORLD_CHARACTER_ID_MAX_CHARACTERS));
+}
 function normalizeJson(value, field) {
     try {
         const text = JSON.stringify(value);
@@ -831,6 +1016,22 @@ function boundedCharacterIds(value, maxItems, field, maxCharacters = 128) {
     }
     return ids;
 }
+function boundedCharacterSafeKeys(value, maxItems, field) {
+    if (!Array.isArray(value) || value.length > maxItems) {
+        throw characterError("INVALID_ARGUMENT", `${field} may contain at most ${maxItems} ids.`);
+    }
+    const ids = value.map((item) => boundedCharacterSafeKey(item, field));
+    if (new Set(ids).size !== ids.length) {
+        throw characterError("INVALID_ARGUMENT", `${field} may not contain duplicate ids.`);
+    }
+    return ids;
+}
+function boundedCharacterSafeKey(value, field) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) {
+        throw characterError("INVALID_ARGUMENT", `${field} must be a safe key of at most 64 characters.`);
+    }
+    return value;
+}
 function boundedCharacterText(value, maxBytes, field, maxCharacters = maxBytes) {
     if (typeof value !== "string" ||
         value.length === 0 ||

package/dist/save.d.ts

@@ -0,0 +1,197 @@
+import { CastleError } from "./errors";
+import type { Json } from "./types";
+export type SaveScope = "deck" | "user" | "private";
+export interface SaveTarget {
+    scope: SaveScope;
+    /** A user target's player. Omitted means the current player. */
+    subject?: string;
+    prefix: string;
+}
+/** Opaque. A reset of the deck's storage makes every older revision stale. */
+export type SaveRevision = string;
+/** Opaque proof of the latest claim on a target. */
+export type SaveWriter = string;
+export type SaveRows = Record<string, Json>;
+export type SaveSelection = {
+    prefix: string;
+} | {
+    keys: string[];
+};
+export interface SaveReadTarget {
+    target: SaveTarget;
+    /** Omitted reads the whole target. */
+    select?: SaveSelection;
+}
+export interface SaveSnapshot {
+    access: string;
+    targets: {
+        target: SaveTarget;
+        /** Null means the target has never been initialized. */
+        revision: SaveRevision | null;
+        rows: SaveRows;
+        /** True when the rows cover the whole target, not a selection of it. */
+        complete: boolean;
+    }[];
+}
+export interface SaveReceipt {
+    operationId: string;
+    access: string;
+    revisions: {
+        target: SaveTarget;
+        revision: SaveRevision;
+    }[];
+    writer?: SaveWriter;
+}
+export interface SaveCheck {
+    target: SaveTarget;
+    expectedRevision?: SaveRevision;
+    writer?: SaveWriter;
+}
+export interface SaveChange {
+    target: SaveTarget;
+    /** Null creates a target that has never been initialized. */
+    expectedRevision: SaveRevision | null;
+    writer?: SaveWriter;
+    put?: SaveRows;
+    remove?: string[];
+    /** Replaces every row of the target. Cannot be combined with put or remove. */
+    replace?: SaveRows;
+}
+export interface SaveTransactionInput {
+    operationId: string;
+    expectedAccess: string;
+    checks?: SaveCheck[];
+    changes: SaveChange[];
+}
+export interface SaveInitial {
+    target: SaveTarget;
+    rows: SaveRows;
+}
+export interface SaveClaimInput {
+    operationId: string;
+    expectedAccess?: string;
+    target: SaveTarget;
+    initial?: SaveInitial[];
+    /** Omitted loads the claimed and initial targets. */
+    load?: SaveReadTarget[];
+}
+export interface SaveInitializeInput {
+    operationId: string;
+    expectedAccess?: string;
+    initial: SaveInitial[];
+    /** Omitted loads the initial targets. */
+    load?: SaveReadTarget[];
+}
+export interface SaveOpened {
+    receipt: SaveReceipt;
+    snapshot: SaveSnapshot;
+}
+export interface SaveClaimed extends SaveOpened {
+    writer: SaveWriter;
+}
+export type SaveOperation = {
+    state: "committed";
+    receipt: SaveReceipt;
+} | {
+    state: "unknown";
+};
+export type SaveVerb = "snapshot" | "transaction" | "claim" | "initialize" | "operation";
+export interface SaveApi {
+    snapshot(input: {
+        targets: SaveReadTarget[];
+    }): Promise<SaveSnapshot>;
+    transaction(input: SaveTransactionInput): Promise<SaveReceipt>;
+    claim(input: SaveClaimInput): Promise<SaveClaimed>;
+    initialize(input: SaveInitializeInput): Promise<SaveOpened>;
+    operation(operationId: string): Promise<SaveOperation>;
+}
+export interface SaveBucketRead {
+    prefix: string;
+    select?: SaveSelection;
+}
+export interface SaveBucketApi {
+    /** This bucket's target for a prefix, for the root's multi-bucket calls. */
+    target(prefix: string): SaveTarget;
+    snapshot(input: SaveBucketRead): Promise<SaveSnapshot>;
+    transaction(input: {
+        operationId: string;
+        expectedAccess: string;
+        checks?: (Omit<SaveCheck, "target"> & {
+            prefix: string;
+        })[];
+        changes: (Omit<SaveChange, "target"> & {
+            prefix: string;
+        })[];
+    }): Promise<SaveReceipt>;
+    claim(input: {
+        operationId: string;
+        expectedAccess?: string;
+        prefix: string;
+        initial?: {
+            prefix: string;
+            rows: SaveRows;
+        }[];
+        load?: SaveBucketRead[];
+    }): Promise<SaveClaimed>;
+    initialize(input: {
+        operationId: string;
+        expectedAccess?: string;
+        initial: {
+            prefix: string;
+            rows: SaveRows;
+        }[];
+        load?: SaveBucketRead[];
+    }): Promise<SaveOpened>;
+    operation(operationId: string): Promise<SaveOperation>;
+}
+/** What a failed save says about itself, as the platform reports it. */
+export interface SaveErrorEnvelope {
+    code: string;
+    message: string;
+    operationId?: string;
+    retryable: boolean;
+    /** "unknown" means the request may still have committed. */
+    committed: boolean | "unknown";
+    /** The stored receipt, when the operation committed earlier. */
+    receipt?: SaveReceipt;
+    retryAfterMs?: number;
+    target?: SaveTarget;
+    [detail: string]: unknown;
+}
+export declare class SaveError extends CastleError {
+    readonly operationId?: string;
+    readonly retryable: boolean;
+    readonly committed: boolean | "unknown";
+    readonly receipt?: SaveReceipt;
+    readonly retryAfterMs?: number;
+    readonly target?: SaveTarget;
+    constructor(envelope: SaveErrorEnvelope);
+}
+/**
+ * Reads the envelope out of whatever a host or platform threw. A failure that
+ * does not say whether it committed is treated as one that might have.
+ */
+export declare function asSaveError(error: unknown, operationId?: string): SaveError;
+/**
+ * A session server has no current player, so it names a user target's player
+ * and cannot reach private storage.
+ */
+export declare function validateSaveTarget(target: SaveTarget, server?: boolean): SaveTarget;
+export declare function saveTargetKey(target: SaveTarget): string;
+/**
+ * Finds the caller's own target for one the platform names. The platform
+ * fills in the current player as a user target's subject, so a target the
+ * caller left without a subject matches any subject.
+ */
+export declare function matchSaveTarget(target: SaveTarget, candidates: readonly SaveTarget[]): SaveTarget;
+/** Validates and copies a request; the result is what goes on the wire. */
+export declare function encodeSaveInput(verb: SaveVerb, input: Record<string, unknown>, server?: boolean): Record<string, unknown>;
+/** Sends one encoded request; the transport behind it is the caller's. */
+export type SaveCall = (verb: SaveVerb, input: Record<string, unknown>) => Promise<unknown>;
+export declare function createSaveApi(call: SaveCall, server?: boolean): SaveApi;
+export declare function createSaveBucket(api: SaveApi, scope: SaveScope, subject?: string): SaveBucketApi;
+/**
+ * Refuses a request bigger than a transport carries. An atomic save is never
+ * split, so the whole encoded request has to fit.
+ */
+export declare function preflightSaveRequest(verb: SaveVerb, request: unknown, limitBytes: number): void;