@anweather/game-plugin-ssdk 1.16.0 → 1.18.0

package/dist-types/runtime/live/rooms.d.ts

@@ -0,0 +1,302 @@
+import { type PlatformFrame, type PluginFrame, type PresenceState, type Role, type RoomScope, type SpaceMember } from "./protocol";
+import { Outbox, type LinkWriter, type OutboxOptions, type OutboxStats } from "./outbox";
+type Awaitable<T> = T | Promise<T>;
+/** Why a room was discarded, as RoomHandlers.onClose hears it. */
+export type RoomCloseReason = 
+/** The platform closed the last link with 1000: no client for its idle grace. */
+"idle"
+/** The platform closed with 4410: the Game behind the scope is over. */
+ | "ended"
+/** This process is stopping (SIGTERM or RunningPlugin.close()). The
+ * checkpoint hook: clients are still connected and will get a fresh room
+ * from the next container (design §8.4). */
+ | "shutdown"
+/** Every link dropped without a planned close, and none came back within
+ * reattachGraceMs. */
+ | "lost"
+/** The room called room.close() itself. */
+ | "closed"
+/** onRoom threw, or the room fell maxPendingEvents behind. */
+ | "error";
+export interface Conn {
+    /** Unique within the room (the platform's conn id, namespaced by link). */
+    readonly id: string;
+    readonly participantId: string;
+    readonly playerId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    /** The participant's own Game; in a Space room each player has their own. */
+    readonly gameId: string;
+    /** The X-Live-Epoch of the link that carries this connection: the
+     * platform channel's incarnation. A new epoch means the platform
+     * restarted and every client is resyncing. */
+    readonly epoch: string;
+    /** The player appears offline (design §3.2): a room must not reveal them
+     * to the other members. Fixed for the connection's life: a player who
+     * toggles "Appear offline" reconnects, and the new conn carries the new
+     * value. */
+    readonly hidden: boolean;
+    readonly presence: PresenceState;
+    /** False once the connection has left. Sends to it are then dropped. */
+    readonly open: boolean;
+    send(data: unknown, opts?: SendOptions): void;
+    kick(opts: KickOptions): void;
+}
+export interface SendOptions {
+    /** Coalescing key: under backpressure a newer frame with the same key
+     * replaces an undelivered older one, here and on the platform. */
+    k?: string;
+}
+export interface BroadcastOptions extends SendOptions {
+    /** Connections to leave out (typically the sender of what is echoed). */
+    except?: Conn | readonly Conn[];
+    /** Leave spectators out. */
+    participantsOnly?: boolean;
+}
+export interface KickOptions {
+    /** Required, so "may this client come back" is always an explicit
+     * choice: 4403 keeps it out (terminal); 4900-4999 are the plugin's own
+     * and the client reconnects after them. */
+    code: number;
+    reason?: string;
+}
+export interface RoomTimer {
+    cancel(): void;
+}
+export interface Room {
+    readonly scope: RoomScope;
+    readonly gameType: string;
+    /** True once the room has been discarded; every call becomes a no-op. */
+    readonly closed: boolean;
+    /** Open connections, in join order. */
+    conns(): readonly Conn[];
+    /** Participant ids with at least one open connection (spectators excluded). */
+    participants(): string[];
+    connsOf(participantId: string): readonly Conn[];
+    /** The latest `members` frame (Space scope only), else undefined. */
+    members(): readonly SpaceMember[] | undefined;
+    broadcast(data: unknown, opts?: BroadcastOptions): void;
+    send(to: Conn | readonly Conn[], data: unknown, opts?: SendOptions): void;
+    /** Every open connection of one participant (several tabs are allowed). */
+    sendToParticipant(participantId: string, data: unknown, opts?: SendOptions): void;
+    kick(conn: Conn, opts: KickOptions): void;
+    /** Runs `fn` through the room's queue after `ms`; cancelled with the room. */
+    setTimeout(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    /** Runs `fn` through the queue every `ms`. A tick is skipped while the
+     * previous one is still queued or running, so a slow room never builds a
+     * backlog of ticks. */
+    setInterval(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    /** Runs `fn` through the room's queue as soon as it is free: the way to act
+     * on the room from outside a handler (a blob read finishing, a message
+     * from elsewhere in the process) without racing its handlers. Dropped if
+     * the room has closed. */
+    post(fn: () => Awaitable<void>): void;
+    /** Discard this room: onClose("closed"), then its links close with 1000.
+     * The platform reopens a link while clients remain, and that gets a fresh
+     * room -- so this is "restart from durable state", not "end the game"
+     * (only a Move ends a Game). */
+    close(reason?: string): void;
+}
+export interface RoomHandlers {
+    onJoin?(conn: Conn): Awaitable<void>;
+    /** `reason` is the platform's (closed, kicked, timeout, removed...), or
+     * the runtime's own: "link" when the link that carried the connection
+     * closed or was superseded, "rejoined" when the platform sent a second
+     * `join` for a conn id it had already joined (the old Conn leaves, the new
+     * one joins). Not debounced: apply a grace with room.setTimeout if a party
+     * should survive a blip. */
+    onLeave?(conn: Conn, reason: string): Awaitable<void>;
+    /** A client's Signal. `data` is untrusted: the sender is `conn`, anything
+     * inside `data` is a claim (design §7.2). In a Space room, a signal from a
+     * member removed a moment ago can still be queued ahead of their `leave`;
+     * check room.members() before letting it change shared state. */
+    onMessage?(conn: Conn, data: unknown): Awaitable<void>;
+    onPresence?(conn: Conn, state: PresenceState): Awaitable<void>;
+    /** A Move was committed on a Game in this scope. */
+    onGame?(gameId: string, revision: number): Awaitable<void>;
+    /** Space membership changed. Removed members' connections leave right after. */
+    onMembers?(members: readonly SpaceMember[]): Awaitable<void>;
+    /** The room is being discarded; the last chance to write a checkpoint. */
+    onClose?(reason: RoomCloseReason): Awaitable<void>;
+}
+export interface LiveOptions {
+    /** Called once per room, when the first link for its scope arrives. Load
+     * state here (from blobs); the runtime answers `ready` when it resolves and
+     * holds every event until then. Per-room state lives in this closure. */
+    onRoom(room: Room): Awaitable<RoomHandlers | void>;
+    /** How long a room whose links all dropped unexpectedly (a platform
+     * restart, a network cut) is kept for a new link to the same scope.
+     * Default 60 s. */
+    reattachGraceMs?: number;
+    /** Events queued behind a slow room before it is failed with 1011 (the
+     * platform then opens a fresh one). Default 4096. */
+    maxPendingEvents?: number;
+    /** How long a discarded room gets to finish the handler in flight, drain
+     * and run onClose, whatever the reason (shutdown included); also how long
+     * a successor room for the same scope waits for that before loading
+     * anyway. A handler that never resolves can delay a scope by this much,
+     * never brick it. Default 5 s. */
+    shutdownTimeoutMs?: number;
+    /** A handler still running after this long is reported through onError
+     * (once per call) as a stall. It is not cancelled: JS can't. Default 10 s;
+     * 0 turns the watchdog off. */
+    stallWarningMs?: number;
+    /** Plugin -> platform backpressure, per link. */
+    outbox?: OutboxOptions;
+    /** A handler threw or stalled. Default: log it. The room carries on. An
+     * onError that throws is itself caught and logged. */
+    onError?(error: unknown, where: {
+        scope: string;
+        handler: string;
+    }): void;
+}
+export interface LinkInfo {
+    scope: RoomScope;
+    epoch: string;
+}
+/** The socket side of a link, supplied by server.ts or the harness. */
+export interface LinkTransport extends LinkWriter {
+    close(code: number, reason: string): void;
+}
+/** What the transport calls back into. */
+export interface LinkHandle {
+    receive(text: string): void;
+    /** The socket closed (either side). Idempotent. */
+    closed(code: number): void;
+}
+export interface RoomHostOptions {
+    gameType: string;
+    live: LiveOptions;
+    log?: Pick<Console, "log" | "error">;
+}
+declare class Link {
+    readonly serial: number;
+    readonly info: LinkInfo;
+    readonly transport: LinkTransport;
+    readonly outbox: Outbox;
+    readonly conns: Map<string, ConnImpl>;
+    ready: boolean;
+    detached: boolean;
+    constructor(serial: number, info: LinkInfo, transport: LinkTransport, outbox: OutboxOptions | undefined);
+    write(frame: PluginFrame, key?: string): void;
+}
+declare class ConnImpl implements Conn {
+    readonly link: Link;
+    readonly wire: string;
+    readonly participantId: string;
+    readonly playerId: string;
+    readonly displayName: string;
+    readonly role: Role;
+    readonly gameId: string;
+    readonly hidden: boolean;
+    private readonly room;
+    open: boolean;
+    presence: PresenceState;
+    constructor(link: Link, wire: string, participantId: string, playerId: string, displayName: string, role: Role, gameId: string, hidden: boolean, presence: PresenceState, room: RoomImpl);
+    get epoch(): string;
+    get id(): string;
+    send(data: unknown, opts?: SendOptions): void;
+    kick(opts: KickOptions): void;
+}
+declare class RoomImpl implements Room {
+    readonly scope: RoomScope;
+    readonly gameType: string;
+    private readonly host;
+    private readonly live;
+    readonly links: Set<Link>;
+    private readonly order;
+    private handlers;
+    private latestMembers;
+    private readonly queue;
+    private processing;
+    private loaded;
+    private disposing;
+    private readonly timers;
+    private graceTimer;
+    private idleWaiters;
+    private loading;
+    closed: boolean;
+    constructor(scope: RoomScope, gameType: string, host: RoomHost, live: LiveOptions);
+    load(previous: Promise<void> | undefined): Promise<void>;
+    private runLoad;
+    linkWithEpoch(epoch: string): Link | undefined;
+    markReady(link: Link): void;
+    attach(link: Link): void;
+    /** A newer link with the same epoch replaced `old` (PROTOCOL.md §5.4): the
+     * platform has abandoned it, so close it now and let its conns leave. */
+    supersede(old: Link): void;
+    /** A link's socket went away. Its connections leave through the queue. */
+    detach(link: Link, code: number): void;
+    /** Discard the room: stop timers, let pending events finish (unless
+     * failing), run onClose, close any remaining links. Idempotent.
+     *
+     * Everything after the timers stop is bounded by closeTimeout(): a
+     * handler or onClose that never resolves delays the links' close by that
+     * much, never forever. A failing room ("error") closes its links first,
+     * at once, so the platform can open a fresh room while this one winds
+     * down. */
+    dispose(reason: RoomCloseReason, code?: number, closeReason?: string, opts?: {
+        runOnClose?: boolean;
+        drainFirst?: boolean;
+    }): Promise<void>;
+    private closeLinks;
+    closeTimeout(): number;
+    enqueue(name: string, run: () => Awaitable<void>): void;
+    private drain;
+    /** Resolves when nothing is queued or running. */
+    whenIdle(): Promise<void>;
+    isIdle(): boolean;
+    /** Loaded (or discarded) with nothing queued or running: for the harness. */
+    isSettled(): boolean;
+    private call;
+    onFrame(link: Link, frame: PlatformFrame): void;
+    private removeConn;
+    conns(): readonly Conn[];
+    participants(): string[];
+    connsOf(participantId: string): readonly Conn[];
+    members(): readonly SpaceMember[] | undefined;
+    broadcast(data: unknown, opts?: BroadcastOptions): void;
+    send(to: Conn | readonly Conn[], data: unknown, opts?: SendOptions): void;
+    sendToParticipant(participantId: string, data: unknown, opts?: SendOptions): void;
+    kick(conn: Conn, opts: KickOptions): void;
+    setTimeout(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    setInterval(fn: () => Awaitable<void>, ms: number): RoomTimer;
+    close(reason?: string): void;
+    post(fn: () => Awaitable<void>): void;
+    private timer;
+    private assertReady;
+    private write;
+    outboxStats(): OutboxStats[];
+}
+/** Every room this process hosts. One per servePlugin({live}). */
+export declare class RoomHost {
+    private readonly options;
+    private readonly rooms;
+    /** Rooms being discarded, by scope, so a successor waits for onClose. */
+    private readonly disposing;
+    private serial;
+    private shuttingDown;
+    private readonly log;
+    constructor(options: RoomHostOptions);
+    get gameType(): string;
+    /** A new link. Returns the callbacks its socket drives. */
+    attach(info: LinkInfo, transport: LinkTransport): LinkHandle;
+    /** Rooms currently hosted (not ones being discarded). */
+    list(): Room[];
+    room(scopeKey: string): Room | undefined;
+    /** Every room's outbox counters, for metrics and tests. */
+    outboxStats(scopeKey: string): OutboxStats[];
+    /** Resolves once every room has loaded and has nothing queued or
+     * running, and every discarded room has finished its onClose. For tests:
+     * real code never needs to wait for a room. */
+    settled(): Promise<void>;
+    /** SIGTERM: every room checkpoints (onClose "shutdown", bounded), then its
+     * links close with 1012 so the platform reopens them on the next task. */
+    shutdown(): Promise<void>;
+    /** @internal A room is being discarded: a new link for its scope gets a
+     * fresh room, which waits for `done` before loading. */
+    forget(room: RoomImpl, done: Promise<void>): void;
+    /** @internal */
+    reportError(error: unknown, scope: string, handler: string): void;
+}
+export {};

package/dist-types/runtime/live/server.d.ts

@@ -0,0 +1,36 @@
+import type { Server } from "node:http";
+import { type LiveOptions, type Room } from "./rooms";
+import type { OutboxStats } from "./outbox";
+export interface AttachLiveOptions {
+    gameType: string;
+    /** The X-Plugin-Auth bearer token; absent accepts every caller (local
+     * dev), exactly like the RPC routes. */
+    authToken?: string;
+    live: LiveOptions;
+    /** Protocol ping interval; the link closes after `linkTimeoutMs` with no
+     * frame, ping or pong from the platform. Defaults 20 s and 45 s (design
+     * §7.4). */
+    pingIntervalMs?: number;
+    linkTimeoutMs?: number;
+    log?: Pick<Console, "log" | "error">;
+}
+export interface LiveServer {
+    /** Rooms currently hosted. */
+    rooms(): Room[];
+    room(scopeKey: string): Room | undefined;
+    outboxStats(scopeKey: string): OutboxStats[];
+    /** Number of open room links. */
+    links(): number;
+    /** Text frames read off every link so far, handed to their rooms. Lets a
+     * test know the socket has delivered what it sent before it waits for
+     * the rooms to settle. */
+    framesReceived(): number;
+    /** Resolves once every room has loaded and drained its queue (tests). */
+    settled(): Promise<void>;
+    /** Checkpoint every room (onClose "shutdown"), close links with 1012, and
+     * stop accepting upgrades. */
+    close(): Promise<void>;
+}
+/** Serve room links on `server`'s /v1/live. servePlugin calls this when
+ * given `live`; a plugin with its own http.Server can call it directly. */
+export declare function attachLive(server: Server, options: AttachLiveOptions): LiveServer;

package/dist-types/runtime/servePlugin.d.ts

@@ -4,6 +4,8 @@ import type { ValidationCustomizer } from "@aws-smithy/server-common";
 import type { GamePluginService, GamePluginServiceOperations } from "../src/server/GamePluginService";
 import type { OptionalGamePluginService, RequiredGamePluginService } from "./defaultService";
 import { type RegistrationLoop } from "./registration";
+import { type LiveServer } from "./live/server";
+import type { LiveOptions } from "./live/rooms";
 /** What a plugin supplies: every operation createGamePluginService requires,
  * except Health, which servePlugin answers itself unless overridden. */
 export type PluginServiceDefinition<Context> = Omit<RequiredGamePluginService<Context>, "Health"> & Partial<Pick<GamePluginService<Context>, "Health">> & OptionalGamePluginService<Context>;
@@ -41,6 +43,10 @@ export interface ServePluginOptions<Context = Record<string, never>> {
     retryDelaySeconds?: number;
     log?: Pick<Console, "log" | "error">;
     fetchImpl?: typeof fetch;
+    /** Host live rooms (Hosted mode, plugin-protocol/live/PROTOCOL.md): the
+     * platform opens one room link per active channel to /v1/live on this
+     * same server, behind the same X-Plugin-Auth token. Absent: no /v1/live. */
+    live?: LiveOptions;
 }
 export interface PluginApp {
     app: Express;
@@ -52,6 +58,8 @@ export interface PluginApp {
 }
 export interface RunningPlugin extends PluginApp {
     server: Server;
+    /** Present when `live` was given. */
+    live?: LiveServer;
     /** The port actually bound (differs from the configured one only for 0). */
     port: number;
     /** Stop renewing, deregister, close the listener. */

package/dist-types/runtime/spaceClient.d.ts

@@ -0,0 +1,159 @@
+export type SpaceRole = "OWNER" | "MEMBER";
+export type SpaceMemberStatus = "ACTIVE" | "LEFT" | "REMOVED";
+/** A member as GetSpace lists one: ACTIVE only, so status is always
+ * "ACTIVE". Whoever left or was removed is simply absent. */
+export interface PluginSpaceMember {
+    playerId: string;
+    /** The platform's display name; absent if the Player is gone. */
+    displayName?: string;
+    role: SpaceRole;
+    status: "ACTIVE";
+}
+/** A Space as `config.space` carries it, plus `archived` and `revision`. */
+export interface PluginSpace<S = Record<string, unknown>> {
+    id: string;
+    name: string;
+    ownerId: string;
+    settings: S;
+    /** ACTIVE members only, owner first, then by first join. */
+    members: PluginSpaceMember[];
+    /** Closed by the owner: no new joins or Games; running Games carry on. */
+    archived: boolean;
+    /** Goes up with every change to the Space. */
+    revision: number;
+}
+export interface SpaceImportMember {
+    playerId: string;
+    role: SpaceRole;
+    /** A member who left and later rejoined is ACTIVE. */
+    status: SpaceMemberStatus;
+    /** ISO-8601: first join. */
+    joinedAt: string;
+    /** ISO-8601: latest status change. */
+    statusAt: string;
+}
+/** What ImportSpace takes: everyone who ever joined, owner included, with
+ * exactly one OWNER who is ownerId and ACTIVE. The game type is always
+ * this client's. */
+export interface SpaceImport {
+    name: string;
+    ownerId: string;
+    /** "K7QM-4XPA" in any case/spacing; null or absent: closed to joins. */
+    inviteCode?: string | null;
+    /** A JSON object; absent: {}. */
+    settings?: Record<string, unknown>;
+    members: SpaceImportMember[];
+}
+export interface SpaceImportResult {
+    /** False: an identical import had already landed; nothing was written. */
+    created: boolean;
+    space: PluginSpace;
+}
+export type SpaceErrorType = "SpaceNotFound" | "InvalidSpaceImport" | "SpaceImportDisabled" | "SpaceAlreadyExists" | "InviteCodeTaken" | "PluginUnauthorized";
+/** A refusal from PluginSpaces. `details` is the error body (for
+ * InvalidSpaceImport, `unknownPlayerIds` when that was the reason). Any
+ * other failure (network, timeout, a 5xx) is a plain Error. */
+export declare class SpaceApiError extends Error {
+    readonly type: SpaceErrorType;
+    readonly status: number;
+    readonly details: Record<string, unknown>;
+    constructor(type: SpaceErrorType, status: number, details: Record<string, unknown>);
+}
+/** A 409 SpaceAlreadyExists on import: it already is a Space, and the
+ * platform's copy wins (§3.5.6). Use its membership; don't retry. */
+export declare function isAlreadyASpace(e: unknown): e is SpaceApiError;
+export interface SpaceClient {
+    /** null when there is no Space with this id of this game type. */
+    get(spaceId: string): Promise<PluginSpace | null>;
+    /** Create-only; idempotent for an identical body. */
+    import(spaceId: string, body: SpaceImport): Promise<SpaceImportResult>;
+    /** This game type's Spaces, invite codes and ACTIVE members, counted:
+     * what a backfill reads back to verify its real run against its dry run. */
+    counts(): Promise<SpaceCounts>;
+}
+export interface SpaceCounts {
+    spaces: number;
+    inviteCodes: number;
+    activeMembers: number;
+}
+export interface SpaceClientOptions {
+    /** The platform's base URL, e.g. http://platform:8080. */
+    platformUrl: string;
+    gameType: string;
+    /** The token this plugin registered with; sent as X-Plugin-Auth. */
+    authToken: string | undefined;
+    /** Per-request timeout. Default 5000. */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function createSpaceClient(options: SpaceClientOptions): SpaceClient;
+/** The platform's ceiling on how stale a membership check may be. */
+export declare const MAX_MEMBERSHIP_AGE_MS = 15000;
+/** The writer is not (or no longer) an ACTIVE member of the Space, or
+ * there is no such Space. Refuse the write. */
+export declare class NotASpaceMemberError extends Error {
+    readonly spaceId: string;
+    readonly playerId: string;
+    constructor(spaceId: string, playerId: string);
+}
+export interface MembershipGuardOptions {
+    /** How old a cached read may be. Default and ceiling: 15000 (§3.5.4). */
+    maxAgeMs?: number;
+    /** Clock, for tests. */
+    now?: () => number;
+}
+export interface MembershipGuard {
+    /** The Space, read at most maxAgeMs ago; null when there is none. */
+    space(spaceId: string): Promise<PluginSpace | null>;
+    /** Whether playerId is an ACTIVE member as of a read at most maxAgeMs old. */
+    isActiveMember(spaceId: string, playerId: string): Promise<boolean>;
+    /** Call before every durable write to the Space's shared state: returns
+     * the Space, or throws NotASpaceMemberError. A failed read throws too
+     * (fail closed), and is not cached. */
+    assertActiveMember(spaceId: string, playerId: string): Promise<PluginSpace>;
+    /** Drop the cached read for one Space, or for all. */
+    invalidate(spaceId?: string): void;
+}
+/** The plugin obligation of LIVE_CHANNELS_DESIGN.md §3.5.4 as one call:
+ * a cached Space read (never older than 15 s, concurrent misses share one
+ * request; a missing Space and a failed read are never cached) and the
+ * ACTIVE-member check on top of it. */
+export declare function createMembershipGuard(client: Pick<SpaceClient, "get">, options?: MembershipGuardOptions): MembershipGuard;
+/** An in-memory SpaceClient for a plugin's own tests: the platform's
+ * rules for import (create-only, idempotent for the same body, 409 for a
+ * different one or a taken code, one ACTIVE OWNER who is ownerId, known
+ * players only when `players` is given) and an ACTIVE-only read. Change
+ * membership with `setStatus` the way a player would on the platform. */
+export declare class FakeSpaceClient implements SpaceClient {
+    private readonly options;
+    /** What the platform holds, every status included. */
+    readonly spaces: Map<string, {
+        space: Omit<PluginSpace, "members">;
+        inviteCode: string | null;
+        members: Map<string, SpaceImportMember>;
+        imported?: string;
+    }>;
+    /** Every call, as "get <id>" / "import <id>". */
+    readonly calls: string[];
+    /** Display names by playerId, used by reads. */
+    readonly names: Map<string, string>;
+    importEnabled: boolean;
+    constructor(options?: {
+        players?: Iterable<string>;
+    });
+    /** A Space as if created on the platform. */
+    add(space: {
+        id: string;
+        name?: string;
+        ownerId: string;
+        settings?: Record<string, unknown>;
+        inviteCode?: string | null;
+    }): void;
+    /** A join, leave or removal, as the platform's player routes make them. */
+    setStatus(spaceId: string, playerId: string, status: SpaceMemberStatus): void;
+    archive(spaceId: string): void;
+    get(spaceId: string): Promise<PluginSpace | null>;
+    import(spaceId: string, body: SpaceImport): Promise<SpaceImportResult>;
+    counts(): Promise<SpaceCounts>;
+    private view;
+}

package/dist-types/src/models/models_0.d.ts

@@ -201,6 +201,23 @@ export declare namespace GameStatusOutput {
      */
     const validate: (obj: GameStatusOutput, path?: string) => __ValidationFailure[];
 }
+/**
+ * A game type's Spaces: shared contexts above individual Games, whose
+ * membership the platform owns (LIVE_CHANNELS_DESIGN.md §3.5).
+ * @public
+ */
+export interface SpaceCapability {
+    maxMembers: number | undefined;
+    label?: string | undefined;
+    settingsSchema?: __DocumentType | undefined;
+    gameConfig?: __DocumentType | undefined;
+}
+export declare namespace SpaceCapability {
+    /**
+     * @internal
+     */
+    const validate: (obj: SpaceCapability, path?: string) => __ValidationFailure[];
+}
 /**
  * @public
  */
@@ -220,6 +237,12 @@ export interface GameTypeMetadata {
     hasSaveFiles?: boolean | undefined;
     hasSaveSummary?: boolean | undefined;
     hasSaveFileEditor?: boolean | undefined;
+    /**
+     * A game type's Spaces: shared contexts above individual Games, whose
+     * membership the platform owns (LIVE_CHANNELS_DESIGN.md §3.5).
+     * @public
+     */
+    spaces?: SpaceCapability | undefined;
 }
 export declare namespace GameTypeMetadata {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@anweather/game-plugin-ssdk",
     "description": "Generated GamePlugin RPC types/server (plugin-protocol/model/game-plugin.smithy) plus a hand-written Express bridge and default-handler wrapper (./runtime) -- see plugin-protocol/CLAUDE.md's \"Publishing for cross-repo plugins\".",
-    "version": "1.16.0",
+    "version": "1.18.0",
     "scripts": {
         "build": "concurrently 'npm:build:cjs' 'npm:build:es' 'npm:build:types'",
         "build:cjs": "tsc -p tsconfig.cjs.json",
@@ -60,7 +60,8 @@
         "@smithy/util-defaults-mode-browser": "^4.0.20",
         "@smithy/util-defaults-mode-node": "^4.0.20",
         "@smithy/util-endpoints": "^3.0.6",
-        "@smithy/util-utf8": "^4.0.0"
+        "@smithy/util-utf8": "^4.0.0",
+        "ws": "^8.18.0"
     },
     "devDependencies": {
         "@tsconfig/node18": "18.2.4",
@@ -71,7 +72,9 @@
         "rimraf": "^3.0.0",
         "typescript": "~5.8.3",
         "@types/node": "^18.19.69",
-        "tsx": "^4.19.2"
+        "tsx": "^4.19.2",
+        "@types/ws": "^8.5.12",
+        "ajv": "^8.17.1"
     },
     "engines": {
         "node": ">=18.0.0"