@seriousgaming/sdk 0.0.0-stage → 1.0.0-alpha.1

package/lib/build/resource-schema.d.ts

@@ -0,0 +1,1048 @@
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+/**
+ * Runtime callback API (a service) a logic-bearing resource is permitted to invoke. A declared API is always present for that resource, and a runtime that cannot provide one a package declares refuses the package at load. Calling an undeclared API throws at runtime, in both dev and production. Resources that omit `uses` (or declare an empty array) cannot call any callbacks.
+ */
+export type ApiUse = "generateText" | "extractText" | "generateSpeech" | "writeBlob";
+/**
+ * List of locales supported by this game (e.g., ['en', 'es', 'fr'])
+ *
+ * @minItems 1
+ */
+export type GameSupportedLocales = [string, ...string[]];
+/**
+ * Interaction mode this game runs in. 'independent' = teams are isolated with independent tick progression. 'shared-state' = teams interact via shared capabilities with synchronized ticks. If omitted, defaults to 'independent'. Fixed at authoring time: no scenario or session varies it.
+ */
+export type GameTeamMode = "independent" | "shared-state";
+/**
+ * Whether a new session starts with the waiting room open, holding participants on this screen until the facilitator closes it. Seeds the session flag at creation only: the facilitator owns it from then on, and neither a reset nor a restart reapplies it.
+ */
+export type GameWaitingRoomOpenOnStart = boolean;
+/**
+ * Optional runtime features the game depends on, by name. A runtime that does not support every listed feature refuses the package at load, naming the feature, rather than running it half-working. This is how a feature arrives within a manifest version without a new one. Absent or empty means the game needs nothing beyond its manifest version.
+ */
+export type RequiredFeatures = string[];
+/**
+ * The format of the game's scenarios, which the author bumps whenever a custom scenario saved against an earlier value may no longer be correct: a setting removed, renamed or reshaped, a change in what a value means, or a change in how the game loads scenario assets. A purely additive change, such as a new setting with a default, needs no bump. A runtime stores it with each custom scenario it persists and refuses to apply a saved scenario whose format differs from the package's. Absent means 1.
+ */
+export type ScenarioFormat = number;
+/**
+ * A participant action a validator can gate, named after the surface message it gates: a context write, or a request for the next tick
+ */
+export type ValidatorGate = "updateData" | "requestTick";
+/**
+ * A session action an endpoint may return for the runtime to carry out after its write. Each is the operation a facilitator's session surface can perform, held to the same rules; an endpoint may return only the actions it declares.
+ */
+export type EndpointActionType = "tick" | "setWaitingRoom" | "pauseTimer" | "resumeTimer" | "extendTick" | "renameTeam" | "moveParticipant" | "addTeam" | "setLocale";
+/**
+ * Lifecycle signal a hook subscribes to. Hooks fire on out-of-tick events emitted by the runtime, after the runtime applies the change.
+ */
+export type HookSignal = "participantJoin" | "participantMove";
+export interface Schema {
+    PackageDefinition?: PackageDefinition;
+    EngineDefinition?: EngineDefinition;
+    CapabilityDefinition?: CapabilityDefinition;
+    SettingsDefinition?: SettingsDefinition;
+    SDKSettings?: SDKSettings;
+    SetupDefinition?: SetupDefinition;
+    ScenarioEditorDefinition?: ScenarioEditorDefinition;
+    ScenarioDefinition?: ScenarioDefinition;
+    UserInterfaceDefinition?: UserInterfaceDefinition;
+    GameDefinition?: GameDefinition;
+    SessionUserInterfaceDefinition?: SessionUserInterfaceDefinition;
+    SDKSessionUserInterface?: SDKSessionUserInterface;
+    WaitingRoomUserInterfaceDefinition?: WaitingRoomUserInterfaceDefinition;
+    SDKWaitingRoomUserInterface?: SDKWaitingRoomUserInterface;
+    PresentationDefinition?: PresentationDefinition;
+    SDKPresentation?: SDKPresentation;
+    GameSupportedLocales?: GameSupportedLocales;
+    GameLocales?: GameLocales;
+    GameCustomScenarios?: GameCustomScenarios;
+    GameTeams?: GameTeams;
+    GameTeamMode?: GameTeamMode;
+    GameSettings?: GameSettings;
+    GameSettingConstraint?: GameSettingConstraint;
+    GameSettingsConstraints?: GameSettingsConstraints;
+    GameWaitingRoomOpenOnStart?: GameWaitingRoomOpenOnStart;
+    GameWaitingRoomSettings?: GameWaitingRoomSettings;
+    FacilitatorGuideDefinition?: FacilitatorGuideDefinition;
+    SDKFacilitatorGuide?: SDKFacilitatorGuide;
+    ResolvedPackageManifest?: ResolvedPackageManifest;
+    LogicLayout?: LogicLayout;
+    SDKPackage?: SDKPackage;
+    SDKEngine?: SDKEngine;
+    SDKCapability?: SDKCapability;
+    SDKScenario?: SDKScenario;
+    SDKUserInterface?: SDKUserInterface;
+    SDKSetup?: SDKSetup;
+    SDKScenarioEditor?: SDKScenarioEditor;
+    SDKGame?: SDKGame;
+    PackageManifest?: PackageManifest;
+    TickControllerDefinition?: TickControllerDefinition;
+    SDKTickController?: SDKTickController;
+    ApiUse?: ApiUse;
+    EndpointActionType?: EndpointActionType;
+    GlobalSettings?: GlobalSettings;
+    HookSignal?: HookSignal;
+    HookDefinition?: HookDefinition;
+    SDKHook?: SDKHook;
+    ValidatorDefinition?: ValidatorDefinition;
+    SDKValidator?: SDKValidator;
+    EndpointDefinition?: EndpointDefinition;
+    SDKEndpoint?: SDKEndpoint;
+}
+/**
+ * Definition of a package
+ */
+export interface PackageDefinition {
+    /**
+     * Namespace-style identifier for the package
+     */
+    identifier: string;
+    /**
+     * Name of the package
+     */
+    name: string;
+    /**
+     * Semantic version of the package
+     */
+    version: string;
+}
+/**
+ * Definition of a game's engine: the logic that computes each tick
+ */
+export interface EngineDefinition {
+    /**
+     * Identifier for the engine. A game holds one, in the `engine` slot, and the slot is the identifier.
+     */
+    identifier: string;
+    /**
+     * Identifiers of the capabilities this engine reads
+     */
+    reads?: string[];
+    /**
+     * Identifiers of the capabilities this engine writes
+     */
+    writes?: string[];
+    /**
+     * Runtime callback APIs this engine is permitted to invoke. The runtime throws when this engine calls a callback whose name is not listed here.
+     */
+    uses?: ApiUse[];
+    /**
+     * Identifiers of the settings resources this engine reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+    /**
+     * Generated, not authored. True when the engine's logic exports InitAggregate and RunAggregate, in which case it runs once across all teams rather than per-team via Run, and may write to shared capabilities. The build derives this from the exports and writes it into the bundled manifest; authoring it in engine.sdk.json is an error.
+     */
+    aggregate?: boolean;
+}
+/**
+ * Definition of a capability
+ */
+export interface CapabilityDefinition {
+    /**
+     * Namespace-style identifier for the capability
+     */
+    identifier: string;
+    /**
+     * JSON Schema describing the variables provided by this capability
+     */
+    variablesSchema: {
+        [k: string]: unknown;
+    };
+    /**
+     * Visibility of this capability's state. 'team' (default): per team, delivered to that team's surfaces. 'team-readable': each team writes only its own copy, but user interfaces on other teams may observe every team's value live in shared-state games. 'shared': one value for all teams, written by an aggregate engine, a facilitator's shared write or a session-scoped endpoint, and synchronised between teams by the production coordinator. 'private': per team like 'team', but never delivered to any user interface, never included in session data or cross-team data; for engine bookkeeping no surface should depend on. A user interface declaring one in reads or writes fails the build.
+     */
+    scope?: "team" | "team-readable" | "shared" | "private";
+    /**
+     * How long a value lasts. 'tick' (default): part of each tick snapshot, so undo and reset rewind it with the round. 'session': kept out of tick snapshots, so neither undo nor reset touches it; seeded from its defaults once, when the session (or a team added later) is created, and persisted across restarts. For facilitator state such as setup completed, pacing gates, or an announcement. Read and written by surfaces, endpoints, hooks and validators; the build refuses one in the engine's reads or writes, because a tick must be replayable from its snapshot
+     */
+    lifetime?: "tick" | "session";
+}
+/**
+ * Definition of a settings resource: named, read-only parameters a game declares once and any resource may read by listing it in its settings. Overridden only by the active scenario and by the session's setup step, and fixed when play starts.
+ */
+export interface SettingsDefinition {
+    /**
+     * Namespace-style identifier for the settings resource
+     */
+    identifier: string;
+    /**
+     * JSON Schema describing these settings. A full object schema, and every property MUST declare a default. `readOnly: true` on a property, at any depth, fixes it and everything under it at the default: no scenario or session may change it
+     */
+    settingsSchema: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * Bundle containing a settings definition
+ */
+export interface SDKSettings {
+    definition: SettingsDefinition;
+}
+/**
+ * Definition of the game's setup user interface: a small form shown at session creation, whose changes become session overrides for that session only (§8.2, §8.3). Its presence is what gives a session its configuration step
+ */
+export interface SetupDefinition {
+    /**
+     * The slot, `setup`. A game holds one setup user interface, so it carries no name of its own
+     */
+    identifier: string;
+    /**
+     * Identifiers of the settings resources this setup user interface edits, the built-in `game` included. It is sent their resolved values through `setSettings`, keyed by identifier, and writes changes to them through `updateSettings`
+     */
+    configures?: string[];
+    /**
+     * Endpoint identifiers this setup user interface is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.
+     */
+    endpoints?: string[];
+}
+/**
+ * Definition of the game's scenario editor: an authoring screen, used at any time and with no session, whose output is a lasting scenario (§6.7.1). Optional: `customScenarios.supported` is what switches custom scenarios on
+ */
+export interface ScenarioEditorDefinition {
+    /**
+     * The slot, `scenario_editor`. A game holds one scenario editor, so it carries no name of its own
+     */
+    identifier: string;
+    /**
+     * Identifiers of the settings resources this scenario editor edits, the built-in `game` included. It is sent their resolved values through `setSettings`, keyed by identifier, and writes changes to them through `updateSettings`
+     */
+    configures?: string[];
+    /**
+     * Endpoint identifiers this scenario editor is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.
+     */
+    endpoints?: string[];
+}
+/**
+ * Definition of a scenario — a named flavour of a game bundling settings overrides and static assets
+ */
+export interface ScenarioDefinition {
+    /**
+     * Namespace-style identifier for the scenario
+     */
+    identifier: string;
+    /**
+     * Localized scenario fields with one entry per supported locale
+     */
+    locales: {
+        /**
+         * Localized fields for this locale
+         *
+         * This interface was referenced by `undefined`'s JSON-Schema definition
+         * via the `patternProperty` "^[a-z]{2}(-[A-Z]{2})?$".
+         */
+        [k: string]: {
+            /**
+             * Display name for this locale
+             */
+            name: string;
+            /**
+             * Short description for this locale
+             */
+            description?: string;
+        };
+    };
+    /**
+     * If true, this scenario is selected when no explicit scenario is chosen at init time. At most one scenario per package should set it.
+     */
+    default?: boolean;
+    /**
+     * If true, this scenario is built for a particular audience and a runtime must not offer, list, resolve or serve it to a caller it has not granted it to. The package never names that audience. Cannot be combined with `default`.
+     */
+    restricted?: boolean;
+    /**
+     * Settings overrides applied when this scenario is selected, keyed by settings identifier. Each value is a partial object of that settings resource's properties. The game-level settings (the number of rounds, the team bounds and names, and whether the waiting room opens with the session) are the built-in `game` settings resource, overridden here under `game` like any other.
+     */
+    settings?: {
+        [k: string]: {
+            [k: string]: unknown;
+        };
+    };
+}
+/**
+ * Definition of a user interface with internationalization support
+ */
+export interface UserInterfaceDefinition {
+    /**
+     * Namespace-style identifier for the user interface
+     */
+    identifier: string;
+    /**
+     * Identifiers of the capabilities this user interface reads
+     */
+    reads?: string[];
+    /**
+     * Identifiers of the capabilities this user interface receives every team's value of, live, rather than its own team's alone. Every entry MUST also appear in `reads`, and MUST name a capability with scope 'team-readable'. Only meaningful in shared-state games.
+     */
+    crossTeamReads?: string[];
+    /**
+     * Identifiers of the capabilities this user interface writes
+     */
+    writes?: string[];
+    /**
+     * Endpoint identifiers this user interface is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.
+     */
+    endpoints?: string[];
+    /**
+     * If true, this user interface may read the participant roster of every team via `callbacks.getAllTeamsParticipants()`, not just its own team. Only meaningful in shared-state games; a game that is not shared-state and references a UI declaring this MUST fail the build.
+     */
+    crossTeamParticipants?: boolean;
+    /**
+     * Identifiers of the settings resources this user interface reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+}
+/**
+ * Definition of a game with internationalization support
+ */
+export interface GameDefinition {
+    /**
+     * Namespace-style identifier for the game
+     */
+    identifier: string;
+    supportedLocales: GameSupportedLocales;
+    locales: GameLocales;
+    customScenarios?: GameCustomScenarios;
+    /**
+     * The game's interaction mode, fixed at authoring time. The team bounds, participant guidance and default names are game settings, in the built-in `game` settings resource.
+     */
+    teams?: {
+        mode?: GameTeamMode;
+    };
+}
+/**
+ * Localized game fields with one entry per supported locale
+ */
+export interface GameLocales {
+    /**
+     * Localized fields for this locale
+     *
+     * This interface was referenced by `GameLocales`'s JSON-Schema definition
+     * via the `patternProperty` "^[a-z]{2}(-[A-Z]{2})?$".
+     */
+    [k: string]: {
+        /**
+         * Display name for this locale
+         */
+        name: string;
+    };
+}
+/**
+ * Production-policy signal opting in to facilitator-authored, runtime-persisted scenarios. When supported is true, runtime hosts offer 'save as scenario' from the game's scenario editor, or through whatever other authoring route they provide, such as an agent editing the settings schemas directly, and list the resulting scenarios alongside built-in ones at init time. The scenario editor is optional: this flag, not the editor, is what switches custom scenarios on. Author-time hosts (e.g. the SDK dev server) surface their own save affordance regardless.
+ */
+export interface GameCustomScenarios {
+    /**
+     * If true, the runtime MAY persist scenarios authored at session time.
+     */
+    supported: boolean;
+}
+/**
+ * Definition of a session user interface with internationalization support
+ */
+export interface SessionUserInterfaceDefinition {
+    /**
+     * Namespace-style identifier for the session user interface
+     */
+    identifier: string;
+    /**
+     * Identifiers of the capabilities this session user interface reads
+     */
+    reads?: string[];
+    /**
+     * Identifiers of the capabilities this session user interface writes
+     */
+    writes?: string[];
+    /**
+     * Endpoint identifiers this session user interface is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.
+     */
+    endpoints?: string[];
+    /**
+     * Identifiers of the settings resources this session user interface reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+}
+/**
+ * Bundle containing a session user interface definition and entrypoint
+ */
+export interface SDKSessionUserInterface {
+    definition: SessionUserInterfaceDefinition;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+    /**
+     * Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies
+     */
+    ui: {
+        /**
+         * Entrypoint file, in the resource's own directory (e.g., 'index.html')
+         */
+        entrypoint: string;
+    };
+}
+/**
+ * Definition of a waiting room user interface (the holding screen shown to players while the session's waiting room is open)
+ */
+export interface WaitingRoomUserInterfaceDefinition {
+    /**
+     * Namespace-style identifier for the waiting room user interface
+     */
+    identifier: string;
+    /**
+     * Identifiers of the capabilities this waiting room user interface reads
+     */
+    reads?: string[];
+    /**
+     * Identifiers of the capabilities this waiting room user interface receives every team's value of, live, rather than its own team's alone. Every entry MUST also appear in `reads`, and MUST name a capability with scope 'team-readable'. Only meaningful in shared-state games.
+     */
+    crossTeamReads?: string[];
+    /**
+     * Identifiers of the capabilities this waiting room user interface writes
+     */
+    writes?: string[];
+    /**
+     * Endpoint identifiers this waiting room user interface is permitted to call via `callbacks.endpoints[<identifier>]`. The host throws when this UI requests an endpoint whose identifier is not listed here.
+     */
+    endpoints?: string[];
+    /**
+     * If true, this waiting room user interface may read the participant roster of every team via `callbacks.getAllTeamsParticipants()`, not just its own team. Only meaningful in shared-state games; a game that is not shared-state and references a UI declaring this MUST fail the build.
+     */
+    crossTeamParticipants?: boolean;
+    /**
+     * Identifiers of the settings resources this waiting room user interface reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+}
+/**
+ * Bundle containing a waiting room user interface definition and entrypoint
+ */
+export interface SDKWaitingRoomUserInterface {
+    definition: WaitingRoomUserInterfaceDefinition;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+    /**
+     * Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies
+     */
+    ui: {
+        /**
+         * Entrypoint file, in the resource's own directory (e.g., 'index.html')
+         */
+        entrypoint: string;
+    };
+}
+/**
+ * Definition of a presentation: the slides a facilitator shows the room, rendered from a UI bundle of the game's own. Read-only by construction: it declares no writes, no endpoints and no callback uses, and it may be shown with no session at all
+ */
+export interface PresentationDefinition {
+    /**
+     * Namespace-style identifier for the presentation
+     */
+    identifier: string;
+    /**
+     * Display name per locale, for the host to label the presentation with
+     */
+    locales?: {
+        [k: string]: {
+            name: string;
+        };
+    };
+    /**
+     * Identifiers of the capabilities this presentation reads, from every team and the shared store, when it is shown during a session
+     */
+    reads?: string[];
+    /**
+     * Identifiers of the settings resources this presentation reads. It receives exactly these, read-only, as settings.<identifier>, with or without a session
+     */
+    settings?: string[];
+}
+/**
+ * Bundle containing a presentation definition and entrypoint
+ */
+export interface SDKPresentation {
+    definition: PresentationDefinition;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+    /**
+     * Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies
+     */
+    ui: {
+        /**
+         * Entrypoint file, in the resource's own directory (e.g., 'index.html')
+         */
+        entrypoint: string;
+    };
+}
+/**
+ * Team configuration: the interaction mode, fixed at authoring time, and the game's own values for the team settings, which are the defaults of the built-in `game` settings resource. All fields are optional.
+ */
+export interface GameTeams {
+    mode?: GameTeamMode;
+    /**
+     * Minimum number of teams this game is designed for. The default for the `game` settings' `teams.min`
+     */
+    min?: number;
+    /**
+     * Maximum number of teams this game is designed for. The default for the `game` settings' `teams.max`
+     */
+    max?: number;
+    /**
+     * Per-team participant guidance. The default for the `game` settings' `teams.perTeam`
+     */
+    perTeam?: {
+        /**
+         * Minimum participants per team
+         */
+        minParticipants?: number;
+        /**
+         * Maximum participants per team
+         */
+        maxParticipants?: number;
+    };
+    /**
+     * Ordered, localised default names for teams. Entry N seeds the default name for the Nth team (team-1, team-2, …). Advisory: operators may rename teams at session setup, and teams beyond the list fall back to the runtime default. The default for the `game` settings' `teams.defaultNames`
+     *
+     * Items: Localised default name for one team, with one entry per supported locale
+     */
+    defaultNames?: {
+        /**
+         * Localised fields for this locale
+         *
+         * This interface was referenced by `undefined`'s JSON-Schema definition
+         * via the `patternProperty` "^[a-z]{2}(-[A-Z]{2})?$".
+         */
+        [k: string]: {
+            /**
+             * Display name for this locale
+             */
+            name: string;
+        };
+    }[];
+}
+/**
+ * The values of the built-in `game` settings resource: the game-level settings every game has. Its schema is the SDK's, not the game's: a game sets its own values in its manifest, which become this resource's defaults, and a scenario or a session overrides them under the identifier `game` like any other settings resource. Null means 'no limit' or 'no guidance'. A new game-level setting joins as a new optional property with a default.
+ */
+export interface GameSettings {
+    /**
+     * The number of ticks the game plays before it is complete. Null means no fixed limit: the game ends by its tick controller or its engine
+     */
+    maxTicks?: number | null;
+    /**
+     * How many teams a session may hold, how many participants each is meant for, and what the teams are called to begin with
+     */
+    teams?: {
+        /**
+         * The fewest teams a session may start play with. Null means no minimum
+         */
+        min?: number | null;
+        /**
+         * The most teams a session may hold at any point. Null means no maximum beyond the runtime's own ceiling
+         */
+        max?: number | null;
+        /**
+         * Advisory guidance on how many participants each team is meant for, shown to the facilitator. Never a gate on joining
+         */
+        perTeam?: {
+            /**
+             * The fewest participants a team is meant for. Null means no guidance
+             */
+            minParticipants?: number | null;
+            /**
+             * The most participants a team is meant for. Null means no guidance
+             */
+            maxParticipants?: number | null;
+        };
+        /**
+         * Ordered, localised default names for teams. Entry N names the team whose index is N; a team beyond the list is named by position. A facilitator or the team's players may rename it
+         *
+         * Items: Localised default name for one team, with one entry per supported locale
+         */
+        defaultNames?: {
+            /**
+             * Localised fields for this locale
+             *
+             * This interface was referenced by `undefined`'s JSON-Schema definition
+             * via the `patternProperty` "^[a-z]{2}(-[A-Z]{2})?$".
+             */
+            [k: string]: {
+                /**
+                 * Display name for this locale
+                 */
+                name: string;
+            };
+        }[];
+    };
+    /**
+     * How the waiting room starts
+     */
+    waitingRoom?: {
+        /**
+         * Whether a new session starts with the waiting room open. Seeds the session flag at creation, before any setup step, so only the game and its scenarios set it
+         */
+        openOnStart?: boolean;
+    };
+}
+/**
+ * How a game narrows one of its `game` settings. Each keyword may only narrow the SDK's schema: a `minimum` or `maximum` applies to a number and also rules out null, an `enum` lists values the SDK's schema accepts, and `readOnly` fixes the value at the game's own, so no scenario or session may change it.
+ */
+export interface GameSettingConstraint {
+    /**
+     * The smallest value a scenario or session may set. At or above the SDK's own minimum
+     */
+    minimum?: number;
+    /**
+     * The largest value a scenario or session may set. At or below the SDK's own maximum
+     */
+    maximum?: number;
+    /**
+     * The only values a scenario or session may set, each one the SDK's schema accepts
+     *
+     * @minItems 1
+     */
+    enum?: [unknown, ...unknown[]];
+    /**
+     * True fixes the value at the game's own: a scenario or session that sets it is refused
+     */
+    readOnly?: boolean;
+}
+/**
+ * Narrowing for the built-in `game` settings, in their shape. The build merges each constraint into the `game` settings schema it emits, so a runtime sees one ordinary schema. Adding a constraint is a scenario-format change.
+ */
+export interface GameSettingsConstraints {
+    maxTicks?: GameSettingConstraint;
+    teams?: {
+        min?: GameSettingConstraint;
+        max?: GameSettingConstraint;
+        perTeam?: {
+            minParticipants?: GameSettingConstraint;
+            maxParticipants?: GameSettingConstraint;
+        };
+        defaultNames?: GameSettingConstraint;
+    };
+    waitingRoom?: {
+        openOnStart?: GameSettingConstraint;
+    };
+}
+/**
+ * Waiting room settings. Which user interface fills the waiting room is the package's waiting room user interface; only its settings are authored.
+ */
+export interface GameWaitingRoomSettings {
+    openOnStart?: GameWaitingRoomOpenOnStart;
+}
+/**
+ * Definition of a facilitator guide — bundled markdown content rendered natively by the host on the facilitator's page
+ */
+export interface FacilitatorGuideDefinition {
+    /**
+     * Namespace-style identifier for the facilitator guide
+     */
+    identifier: string;
+    /**
+     * Localized facilitator guide fields with one entry per supported locale. Each declared locale must have a matching content/<locale>/ directory.
+     */
+    locales: {
+        /**
+         * Localized fields for this locale
+         *
+         * This interface was referenced by `undefined`'s JSON-Schema definition
+         * via the `patternProperty` "^[a-z]{2}(-[A-Z]{2})?$".
+         */
+        [k: string]: {
+            /**
+             * Display name for this locale, shown as the guide's title
+             */
+            name: string;
+        };
+    };
+}
+/**
+ * Bundle containing a facilitator guide definition and root directory for content and assets
+ */
+export interface SDKFacilitatorGuide {
+    definition: FacilitatorGuideDefinition;
+    /**
+     * Root directory where guide content and assets are located. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Every resource a package holds: the shape the loader builds from disk and the shape the build writes to seriousgaming.json. A game holds one of nine kinds, each in its own field; everything a package may hold more than one of is an array.
+ */
+export interface ResolvedPackageManifest {
+    /**
+     * Format version of this manifest. Absent means 1. Runtimes MUST treat an absent value as 1 and MUST reject a version they do not implement.
+     */
+    manifestVersion?: number;
+    requires?: RequiredFeatures;
+    scenarioFormat?: ScenarioFormat;
+    package: SDKPackage;
+    game: SDKGame;
+    engine?: SDKEngine;
+    ui?: SDKUserInterface;
+    session?: SDKSessionUserInterface;
+    waiting_room?: SDKWaitingRoomUserInterface;
+    presentation?: SDKPresentation;
+    setup?: SDKSetup;
+    scenario_editor?: SDKScenarioEditor;
+    tick_controller?: SDKTickController;
+    guide?: SDKFacilitatorGuide;
+    capabilities?: SDKCapability[];
+    settings?: SDKSettings[];
+    scenarios?: SDKScenario[];
+    hooks?: SDKHook[];
+    validators?: SDKValidator[];
+    endpoints?: SDKEndpoint[];
+}
+/**
+ * Bundle containing a package definition
+ */
+export interface SDKPackage {
+    definition: PackageDefinition;
+}
+/**
+ * Bundle containing a game definition
+ */
+export interface SDKGame {
+    definition: GameDefinition;
+    /**
+     * Root directory where game files are located (e.g., '.'). Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Bundle containing an engine definition and its logic layout
+ */
+export interface SDKEngine {
+    definition: EngineDefinition;
+    logic: LogicLayout;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Where a logic-bearing resource keeps its code, and what its entrypoint is called
+ */
+export interface LogicLayout {
+    /**
+     * Subdirectory containing logic files
+     */
+    directory: string;
+    /**
+     * Path to the TypeScript entrypoint file (e.g., logic.ts)
+     */
+    entrypoint: string;
+}
+/**
+ * Bundle containing a user interface definition and entrypoint
+ */
+export interface SDKUserInterface {
+    definition: UserInterfaceDefinition;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+    /**
+     * Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies
+     */
+    ui: {
+        /**
+         * Entrypoint file, in the resource's own directory (e.g., 'index.html')
+         */
+        entrypoint: string;
+    };
+}
+/**
+ * Bundle containing the setup user interface definition and entrypoint
+ */
+export interface SDKSetup {
+    definition: SetupDefinition;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+    /**
+     * Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies
+     */
+    ui: {
+        /**
+         * Entrypoint file, in the resource's own directory (e.g., 'index.html')
+         */
+        entrypoint: string;
+    };
+}
+/**
+ * Bundle containing the scenario editor definition and entrypoint
+ */
+export interface SDKScenarioEditor {
+    definition: ScenarioEditorDefinition;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+    /**
+     * Where this surface's entrypoint is. A UI's web files sit in the resource's own directory, so only the entrypoint's name varies
+     */
+    ui: {
+        /**
+         * Entrypoint file, in the resource's own directory (e.g., 'index.html')
+         */
+        entrypoint: string;
+    };
+}
+/**
+ * Bundle containing a tick controller definition and its logic layout
+ */
+export interface SDKTickController {
+    definition: TickControllerDefinition;
+    logic: LogicLayout;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Definition of a tick controller that determines automatic tick timing
+ */
+export interface TickControllerDefinition {
+    /**
+     * Namespace-style identifier for the tick controller
+     */
+    identifier: string;
+    /**
+     * Identifiers of the capabilities this tick controller reads
+     */
+    reads?: string[];
+    /**
+     * Runtime callback APIs this tick controller is permitted to invoke. The runtime throws when this tick controller calls a callback whose name is not listed here.
+     */
+    uses?: ApiUse[];
+    /**
+     * Identifiers of the settings resources this tick controller reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+}
+/**
+ * Bundle containing a capability definition
+ */
+export interface SDKCapability {
+    definition: CapabilityDefinition;
+}
+/**
+ * Bundle containing a scenario definition and root directory for assets
+ */
+export interface SDKScenario {
+    definition: ScenarioDefinition;
+    /**
+     * Root directory where scenario assets are located. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Bundle containing a hook definition and its logic layout
+ */
+export interface SDKHook {
+    definition: HookDefinition;
+    logic: LogicLayout;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Definition of a hook — a single-signal handler that runs in response to an out-of-tick lifecycle event
+ */
+export interface HookDefinition {
+    /**
+     * Namespace-style identifier for the hook
+     */
+    identifier: string;
+    /**
+     * Lifecycle signal this hook fires on
+     */
+    signal: "participantJoin" | "participantMove";
+    /**
+     * Identifiers of the capabilities this hook reads
+     */
+    reads?: string[];
+    /**
+     * Identifiers of the capabilities this hook writes
+     */
+    writes?: string[];
+    /**
+     * Runtime callback APIs this hook is permitted to invoke. The runtime throws when this hook calls a callback whose name is not listed here.
+     */
+    uses?: ApiUse[];
+    /**
+     * Identifiers of the settings resources this hook reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+}
+/**
+ * Bundle containing a validator definition and its logic layout
+ */
+export interface SDKValidator {
+    definition: ValidatorDefinition;
+    logic: LogicLayout;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Definition of a validator — a standalone, read-only gate on what a participant does from a player surface: a context write, or a request for the next tick. Reject-only; never modifies state.
+ */
+export interface ValidatorDefinition {
+    /**
+     * Namespace-style identifier for the validator
+     */
+    identifier: string;
+    /**
+     * Identifiers of the capabilities this validator reads. Also its trigger set: a validator runs when a mutation changes one of them, and one declaring none runs on every mutation
+     */
+    reads?: string[];
+    /**
+     * Generated, not authored. The participant actions this validator gates, one per gate function its logic exports: 'updateData' for an UpdateData export (a context write), 'requestTick' for a RequestTick export (a request for the next tick). The build derives this from the exports and writes it into the bundled manifest, and a runtime calls only these; authoring it in validator.sdk.json is an error
+     */
+    gates?: ValidatorGate[];
+    /**
+     * Identifiers of the settings resources this validator reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+}
+/**
+ * Bundle containing an endpoint definition and its logic layout
+ */
+export interface SDKEndpoint {
+    definition: EndpointDefinition;
+    logic: LogicLayout;
+    /**
+     * Directory containing this resource's files, relative to the bundle file. Must use forward slashes, not Windows separators
+     */
+    rootDirectory: string;
+}
+/**
+ * Definition of an endpoint — a named, server-side handler that user interfaces, and callers outside the game when its visibility is external, invoke by identifier. Endpoints validate structured requests and responses against declared schemas, and operate strictly within the bounds of their declared `reads`, `writes` and `uses`.
+ */
+export interface EndpointDefinition {
+    /**
+     * Namespace-style identifier for the endpoint
+     */
+    identifier: string;
+    /**
+     * Human-readable name for author-time tools
+     */
+    displayName?: string;
+    /**
+     * Short description of what this endpoint does, surfaced in author-time tools. Required when `visibility` is `external`, where it is also the text an outside caller, such as a facilitator's AI agent, reads to decide whether to call this endpoint.
+     */
+    description?: string;
+    /**
+     * Whether this endpoint acts on one team or on the session as a whole. A team-scoped endpoint receives that team's context and a `team` naming it, whoever calls it; a session-scoped one has neither. Absent means `team`.
+     */
+    scope?: "session" | "team";
+    /**
+     * JSON Schema describing the request payload accepted by this endpoint
+     */
+    requestSchema: {
+        [k: string]: unknown;
+    };
+    /**
+     * JSON Schema describing the response payload returned by this endpoint
+     */
+    responseSchema: {
+        [k: string]: unknown;
+    };
+    /**
+     * Identifiers of the capabilities this endpoint reads. The handler receives a scoped snapshot of these capabilities under `context`.
+     */
+    reads?: string[];
+    /**
+     * Identifiers of the settings resources this endpoint reads. It receives exactly these, read-only, as settings.<identifier>
+     */
+    settings?: string[];
+    /**
+     * Identifiers of the capabilities this endpoint may change. The context patch a handler returns is held to this list, and an endpoint declaring none cannot change state at all.
+     */
+    writes?: string[];
+    /**
+     * Runtime callback APIs this endpoint is permitted to invoke. The runtime throws when this endpoint calls a callback whose name is not listed here.
+     */
+    uses?: ApiUse[];
+    /**
+     * Session actions this endpoint may return beside its response, such as closing the waiting room or advancing a tick. The runtime carries them out, in order, after the endpoint's write.
+     */
+    actions?: EndpointActionType[];
+    /**
+     * Generated, not authored. Whether the endpoint answers in two phases: its logic exports `Plan`, which returns the effects alone, and `Respond`, which the runtime calls once they have been applied to write the response from the state they left. An endpoint that answers in one exports `Handle`. The build derives this from the exports and writes it into the bundled manifest; authoring it in endpoint.sdk.json is an error
+     */
+    responds?: boolean;
+    /**
+     * Whether the handler's `session` argument lists each team's participants. Off by default, because the list grows with the cohort and most endpoints do not need it.
+     */
+    roster?: boolean;
+    /**
+     * Who may invoke this endpoint. `internal` endpoints are reached only by the game's own user interfaces; `external` ones may also be invoked by callers outside the game, such as a facilitator's AI agent or a platform API, subject to the platform's own authorisation. Absent means `internal`, so an endpoint written for a game's own screens is never published unless its author says so.
+     */
+    visibility?: "internal" | "external";
+}
+/**
+ * A package, which is a game: its identifier and the game's settings. What it declares are the resources on disk under the conventional directories beside this file. The version comes from package.json, and the game's identifier is the package identifier with `.game` appended.
+ */
+export interface PackageManifest {
+    /**
+     * Namespace-style identifier for the package. Every resource identifier sits under it, and the game's identifier is it with `.game` appended.
+     */
+    identifier: string;
+    requires?: RequiredFeatures;
+    scenarioFormat?: ScenarioFormat;
+    supportedLocales: GameSupportedLocales;
+    locales: GameLocales;
+    /**
+     * The number of ticks (rounds) the game plays before it is complete. A tick can stand for an hour, a day, a week, or something more abstract. Omit it when the game ends by its tick controller or its engine instead. The default for the `game` settings' `maxTicks`, which a scenario or a session may override
+     */
+    maxTicks?: number;
+    teams?: GameTeams;
+    waitingRoom?: GameWaitingRoomSettings;
+    gameSettingsConstraints?: GameSettingsConstraints;
+    customScenarios?: GameCustomScenarios;
+}
+/**
+ * User-owned global settings file (~/.seriousgaming-sdk/config.json). Stores API keys and defaults once so every project picks them up. This is the lowest-priority configuration source: .env files, environment variables, and CLI flags all override it. The file is plaintext and must not be committed to git.
+ */
+export interface GlobalSettings {
+    /**
+     * ElevenLabs integration settings.
+     */
+    elevenLabs?: {
+        /**
+         * ElevenLabs API key.
+         */
+        apiKey?: string;
+    };
+    /**
+     * Serious Gaming platform settings used by `package publish` and LLM text generation.
+     */
+    platform?: {
+        /**
+         * Serious Gaming platform API host.
+         */
+        apiHost?: string;
+        /**
+         * Serious Gaming platform API key.
+         */
+        apiKey?: string;
+        /**
+         * Default publisher identifier used when publishing packages.
+         */
+        defaultPublisher?: string;
+    };
+}