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

package/dist/execution/executor-callbacks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * createExecutorCallbacks - builds the raw runtime callbacks exposed to resource
+ * logic (the engine, hooks, validators, endpoints, tick controllers).
+ *
+ * This is the un-guarded callbacks object. Per-resource `uses` enforcement is
+ * layered on top by the executor via `createGuardedCallbacks`, which replaces
+ * any callback a resource did not declare with a throwing stub.
+ */
+import type { PastStateEntry, SDKGame, SignatureCallbacks } from '@seriousgaming/sdk';
+import { TtsClient } from '../services/tts/client';
+import { DocumentParserClient } from '../utils/document-parser-client';
+import { LLMClient } from '../utils/llm-client';
+export interface ExecutorCallbacksDeps {
+    /** Absolute path to the game package (asset resolution, blob storage). */
+    packagePath: string;
+    llmClient: LLMClient;
+    documentParserClient: DocumentParserClient;
+    ttsClient: TtsClient;
+    /** The currently loaded game, or null. Read lazily so a reload is picked up. */
+    getGame: () => SDKGame | null;
+    /** The active scenario's root directory (for scenario-scoped assets), or null. */
+    getActiveScenarioRoot: () => string | null;
+    /**
+     * Read committed past ticks (§12.5), or null before a host has supplied a
+     * history to read. The second argument is the team indexes the calling
+     * resource is scoped to, which the executor resolves from what is running.
+     */
+    readPastState: ((range: {
+        fromTick: number;
+        toTick?: number;
+        capabilityIds?: string[];
+    }, teamIndexes: number[]) => PastStateEntry[]) | null;
+    /**
+     * Team indexes the resource now running is scoped to, or null for one that
+     * is scoped to the whole session (a session-scoped endpoint, §6.12). Read
+     * lazily, like `getGame`, because one callbacks object serves a whole
+     * per-team loop.
+     */
+    getScopedTeamIndexes: () => number[] | null;
+    /** Every team index in the session, for a session-scoped read. */
+    getAllTeamIndexes: () => number[];
+    /** Test/host overrides spread over the built callbacks. */
+    callbackOverrides: Partial<SignatureCallbacks>;
+    /**
+     * Consume one occasion of an armed platform failure, returning it when one
+     * fires: the dev server's `llm-failure` fault. Null when nothing can arm one.
+     */
+    takePlatformFailure?: (() => {
+        reason?: string;
+    } | undefined) | null;
+}
+/**
+ * Build the raw callbacks object. Constructed fresh per resource invocation so
+ * `getGame` / `getActiveScenarioRoot` reflect the live executor state.
+ */
+export declare function createExecutorCallbacks(deps: ExecutorCallbacksDeps): SignatureCallbacks;

package/dist/execution/executor.d.ts

@@ -0,0 +1,436 @@
+import type { ResolvedPackageManifest, EndpointOutcome, HookPayload, HookSignal, Participant, RunKind, SDKEndpoint, SDKGame, SDKScenario, SignatureCallbacks, TickControllerResult, ValidationRejection, ValidatorActor } from '@seriousgaming/sdk';
+import { type TtsClientConfig } from '../services/tts/client';
+import { type BundleReload } from './bundle-reload';
+import { ResolvedSettings } from './configuration-builder';
+import { type EndpointCallArgs, type EndpointRun } from './endpoint-runner';
+import type { ExecutorCallbacksDeps } from './executor-callbacks';
+import type { SessionSettingsOverrides, GameContext, ExecutorDependencies } from './types';
+export type { GameContext };
+export type { BundleReload };
+export type { EndpointCallArgs, EndpointRun } from './endpoint-runner';
+export declare class GameExecutor {
+    private packagePath;
+    private inMemory;
+    private config;
+    private game;
+    private activeScenario;
+    private context;
+    /**
+     * Canonical session-wide value of every shared-scope capability. Team
+     * contexts (and `this.context`) are views that mirror it; the store is
+     * the single source of truth for storage, undo, and persistence.
+     */
+    private sharedContext;
+    /** The game's engine. A game wires exactly one, and may wire none. */
+    private engine;
+    private logicLoader;
+    private configResolver;
+    private capabilityDefaults;
+    /** Capabilities a reload adopted since the context was last built (#640). */
+    private readonly addedCapabilities;
+    private lastTick;
+    /**
+     * Which teams the last tick's engine reported complete, by position in the
+     * contexts it was handed (§11). Read by the session straight after a tick.
+     */
+    private lastTickCompletion;
+    private waitingRoomOpen;
+    private deps;
+    /** `meta`, the roster, callbacks and bounds: what every logic call shares. */
+    private readonly calls;
+    /** What every runner below the executor is handed of it. */
+    private readonly host;
+    private readonly endpoints;
+    constructor(packagePath: string, options?: {
+        seriousGamingApiKey?: string;
+        seriousGamingApiHost?: string;
+        inMemory?: boolean;
+        callbacks?: Partial<SignatureCallbacks>;
+        tts?: TtsClientConfig;
+        /** The clock `meta.now` is read from. Defaults to the system clock. */
+        clock?: {
+            now(): number;
+        };
+    }, deps?: Partial<ExecutorDependencies>);
+    /**
+     * Set the active session locale. Session-wide, not per participant: it is
+     * surfaced to every logic function as `meta.locale`, so it can generate
+     * prose in the session language.
+     */
+    setLocale(locale: string): void;
+    getLocale(): string;
+    /**
+     * Set the session's random seed, surfaced to logic as `meta.seed`.
+     *
+     * The host owns it because it has to be stable for the life of the session
+     * and across a restart: a seed the executor drew on startup would give a
+     * restored session a different world than the one it was persisted from.
+     * The dev server keeps it in persisted state for exactly that reason.
+     */
+    setSeed(seed: string): void;
+    getSeed(): string;
+    /**
+     * Record whether the session's waiting room is open. Session-wide, and read
+     * by the tick controller so an author can stop the clock while players wait
+     * (§11). The executor itself changes no behaviour on it — that is the whole
+     * point: the flag swaps a UI surface, it does not pause the simulation.
+     */
+    setWaitingRoomOpen(open: boolean): void;
+    getWaitingRoomOpen(): boolean;
+    /**
+     * Record which kind of run this is, surfaced to logic as `meta.runKind`.
+     *
+     * Set once by the host that owns the run, before it starts. Changing it
+     * part way through would let one tick of a game see a different kind than
+     * the next, which is the one thing `runKind` promises cannot happen.
+     */
+    setRunKind(kind: RunKind): void;
+    getRunKind(): RunKind;
+    /**
+     * Where the roster logic receives as `participants` comes from (§10.2).
+     *
+     * The host's, like the history: the session owns who is on which team,
+     * and a second copy here would be a second copy to fall out of step.
+     */
+    setRosterSource(source: () => Participant[]): void;
+    /**
+     * Run `work` as one operation: every logic call inside it reads the same
+     * `meta.now`, taken from the clock as it starts (§10.2). Nested calls join
+     * the operation already running rather than starting their own, so a
+     * cohort tick that runs each independent team separately, and the tick
+     * controller evaluated after it, all read one instant.
+     */
+    inOperation<T>(work: () => Promise<T>): Promise<T>;
+    /** The instant the current operation started, or now when there is none. */
+    operationNow(): number;
+    /** How a result folds into a board, for the game as it is loaded now. */
+    private composition;
+    /**
+     * Fold an aggregate result into the team contexts and the canonical store.
+     * See {@link applyAggregateResult}.
+     */
+    private applyAggregateResult;
+    /** An aggregate function's store and team arguments. See {@link aggregateArgs}. */
+    private aggregateArgs;
+    /**
+     * Initialize the executor by loading config and initializing game
+     * @param generateConfiguration - Whether to generate configuration if it doesn't exist (default: true)
+     * @param reconfigure - Whether to regenerate invalid configuration (default: false)
+     * @param scenarioId - Optional scenario ID to activate. Pass null to skip
+     *                     the game's default scenario and use the settings defaults.
+     */
+    initialize(generateConfiguration?: boolean, reconfigure?: boolean, scenarioId?: string | null): Promise<void>;
+    /**
+     * Reset the game (re-initialize)
+     * @param reconfigure - Whether to regenerate invalid configuration (default: false)
+     */
+    reset(reconfigure?: boolean): Promise<void>;
+    /**
+     * Whether the saved configuration was built for a different scenario than
+     * the one about to run, and so cannot be reused (#439).
+     *
+     * An unrecorded scenario means the configuration predates this record or
+     * was written by hand; treat it as current rather than discarding it, since
+     * silently overwriting an author's configuration is the failure this guards
+     * against. A genuine scenario switch always records, so it is still caught.
+     */
+    private configuredScenarioIsStale;
+    /**
+     * Reinitialize the executor by reloading config and resetting
+     * @param reconfigure - Whether to regenerate invalid configuration (default: false)
+     */
+    reinitialize(reconfigure?: boolean): Promise<void>;
+    /**
+     * Execute a single tick.
+     *
+     * `team` identifies the team this tick runs for when the caller manages
+     * multiple teams itself (independent mode swaps each team's context in
+     * before calling). Aggregate functions receive it in their single-element
+     * `teams` array; when omitted, the default single-team identity is used.
+     */
+    executeTick(tick?: number, team?: {
+        teamId: string;
+        index: number;
+    }): Promise<GameContext>;
+    /**
+     * Execute a tick across multiple teams.
+     * For each engine in order:
+     *  - Run is called independently for each team's context
+     *  - RunAggregate is called once with all teams' contexts, for a declared
+     *    aggregate engine
+     * Returns the updated array of team contexts.
+     *
+     * `teamIndexes` carries each team's stable index (positions can have gaps
+     * after a removal); when omitted, indexes default to array position.
+     */
+    executeMultiTeamTick(teamContexts: GameContext[], tick: number, teamIndexes?: number[]): Promise<GameContext[]>;
+    /**
+     * The tick engine shared by {@link executeTick} and
+     * {@link executeMultiTeamTick}. For every engine in order it runs `Run` on
+     * each team's context (rejecting a shared-capability write from `Run`), then,
+     * for a declared aggregate engine, `RunAggregate` once across all teams,
+     * folding the aggregate's shared result back in. `identities` supplies the
+     * `teamId`/`index` each team presents to `RunAggregate`. The executor's own
+     * context is left mirroring team 0.
+     */
+    private runTick;
+    private runTickInOperation;
+    /**
+     * Upgrade a single-team initialisation to multi-team by running InitAggregate
+     * across all N teams simultaneously. Call this after initialize() when teamCount > 1.
+     *
+     * executeInit() runs Init per engine and InitAggregate with a single team (for
+     * single-team compatibility). This method then re-runs InitAggregate for each
+     * aggregate engine with all N teams' post-Init contexts, producing the correct
+     * multi-team initial state.
+     */
+    executeMultiTeamInit(teamCount: number, teamIndexes?: number[]): Promise<GameContext[]>;
+    /**
+     * Initialise independent teams, each on its own (§9.2a): `InitAggregate`
+     * is handed a one-element `teams` holding only that team (§5.3), as
+     * `RunAggregate` is at each team's tick.
+     */
+    executeIndependentInit(teamIndexes: number[]): Promise<GameContext[]>;
+    private executeMultiTeamInitInOperation;
+    /**
+     * One post-`Init` context per team, each built from the pristine initial
+     * context with that team's identity in `meta`.
+     *
+     * A game with no `Init` gets the initial context unchanged, which is what
+     * the clone produced before and what a game without one expects.
+     */
+    private initialiseTeamContexts;
+    /** Which teams the last tick's engine reported complete, by position (§11). */
+    getLastTickCompletion(): boolean[];
+    /**
+     * Get the current context.
+     *
+     * Cloned, as `getSharedContext` has always been: a spread leaves every
+     * capability value shared with the store, so a caller mutating one wrote
+     * game state without a validator, a write check or a persist (#491). A
+     * read hands back a value the caller owns.
+     */
+    getContext(): GameContext;
+    /**
+     * Set the context (used for undo)
+     */
+    setContext(context: GameContext): void;
+    /**
+     * Current value of the canonical shared store: one value per shared-scope
+     * capability, session-wide. Team contexts only ever carry views of it.
+     */
+    getSharedContext(): GameContext;
+    /**
+     * Merge values into the canonical shared store (the facilitator shared
+     * write path). The executor's own context view is kept in step; callers
+     * that hold team context views (dev server, runners) re-compose theirs.
+     */
+    setSharedContext(update: GameContext): void;
+    /**
+     * Get the configuration
+     */
+    getConfig(): ResolvedPackageManifest | null;
+    /**
+     * Hash of the fully resolved configuration (capability schemas included).
+     * Persisted with game state so a later load can detect that the
+     * configuration changed while the state sat on disk.
+     */
+    getConfigHash(): string;
+    /**
+     * Hash of the on-disk resolved configuration without mutating live state.
+     *
+     * {@link reinitialize} resets the executor (rebuilds context, re-runs Init),
+     * so it must not be used merely to learn whether the config changed: a no-op
+     * save would silently rewind a running session. The config watcher peeks the
+     * hash with this method and only reinitialises when it actually differs.
+     */
+    peekConfigHash(): Promise<string>;
+    /**
+     * Get the current game
+     */
+    getGame(): SDKGame | null;
+    reloadEngine(engineIdentifier: string): void;
+    /** Make the next run of every logic resource load what is on disk. */
+    clearLogicCache(): void;
+    /**
+     * Re-read the package's resource bundles without touching the session.
+     *
+     * Context, tick and session overrides are kept. What a running session can
+     * adopt, it adopts: logic, surfaces, endpoints, the game's locale names,
+     * and a capability it did not have, seeded with its schema defaults. What
+     * only applies when a session initialises is kept as the
+     * session started with it and reported as pending: settings whose
+     * resolved values changed, the manifest fields `Init` or session creation
+     * read, and a capability removed or moved to another scope. A bundle that
+     * fails to load or validate throws and leaves the previous configuration
+     * in force.
+     */
+    reloadBundles(): Promise<BundleReload>;
+    /**
+     * The schema defaults of each capability adopted by a reload since the
+     * session last initialised, for a host composing them under every board
+     * it builds. Only those: a board lacks one of them because it was built,
+     * or recorded, before the capability existed, which no other capability's
+     * absence means.
+     */
+    getAddedCapabilityDefaults(): Map<string, Record<string, unknown>>;
+    /**
+     * Build initial context from capabilities
+     */
+    private buildInitialContext;
+    /** Resolve the game's engine. A game wires exactly one. */
+    private resolveEngine;
+    private executeInit;
+    private executeInitInOperation;
+    /**
+     * Get the active scenario (if any)
+     */
+    getActiveScenario(): SDKScenario | null;
+    /** The scenario `initialize` would activate for this id, without activating it. */
+    findScenario(scenarioId?: string | null): SDKScenario | null;
+    /**
+     * Validate a prospective scenario's settings overrides without activating
+     * the scenario or mutating any state. Throws with the offending keys named
+     * when invalid.
+     *
+     * The dev server calls this at the scenario-select boundary before deleting
+     * the current session's state and configuration files, so an invalid target
+     * scenario is rejected up front and the last-good session survives (#239).
+     */
+    assertScenarioConfigurationValid(scenarioId: string | null): void;
+    /**
+     * Re-read the package manifest from disk and update only the scenario
+     * surface — `config.scenarios` and the active game's
+     * `definition.scenarios` reference list. Used by the author-time save
+     * flow (issue #101) to make a freshly-written `scenarios/<id>/` bundle
+     * visible without resetting context, history, or centralized
+     * configuration. Other resources are left untouched.
+     */
+    reloadPackageScenarios(): Promise<void>;
+    /**
+     * Set the active scenario by ID (used when restoring from persisted state)
+     */
+    setActiveScenarioId(scenarioId: string): void;
+    private loadEngine;
+    /**
+     * Execute the tick controller for the current game and return its result.
+     * Returns null if no tick controller is configured.
+     */
+    executeTickController(teams: {
+        teamId: string;
+        index: number;
+        context: Record<string, unknown>;
+    }[], identity?: {
+        teamId: string;
+        index: number;
+    }): Promise<TickControllerResult | null>;
+    /**
+     * Dispatch a lifecycle signal to all hooks subscribed to it. Each hook
+     * receives the previous hook's output as input, so the executor's context
+     * reflects the full chain of mutations after the call returns.
+     */
+    dispatchHook<S extends HookSignal>(signal: S, payload: HookPayload<S>): Promise<GameContext>;
+    /**
+     * Put a participant's context write to every validator exporting
+     * `UpdateData` whose `reads` it changes (§15.2.1). See
+     * {@link runUpdateDataGates}.
+     */
+    runValidators(previous: GameContext, next: GameContext, actor: ValidatorActor): Promise<ValidationRejection[]>;
+    /**
+     * Put a participant's request for the next tick to every validator
+     * exporting `RequestTick` (§15.1). A request changes nothing, so the
+     * changed-`reads` rule has nothing to look at: every such gate runs.
+     */
+    runTickGates(context: GameContext, actor: ValidatorActor, requestedTick: number): Promise<ValidationRejection[]>;
+    /**
+     * Directly set the session-override layer in memory. Used by the dev
+     * server in in-memory mode so config UI changes are captured without
+     * writing to disk.
+     */
+    setConfiguration(config: SessionSettingsOverrides): void;
+    /**
+     * Return the current in-memory session-override layer, if any.
+     */
+    getSessionOverrides(): SessionSettingsOverrides | null;
+    /**
+     * Every filled slot's configuration, resolved through the §8.2 layers now.
+     *
+     * Distinct from {@link getSessionOverrides}, which is the stored
+     * session-override layer and holds only what was overridden. A surface that
+     * wants values to render, seed a form with, or bake into a scenario wants
+     * this one.
+     */
+    resolveConfiguration(): ResolvedSettings;
+    /** The same, through the defaults and the active scenario only (§6.15.1). */
+    resolveConfigurationWithoutSession(): ResolvedSettings;
+    /** Every settings resource through the §8.2 layers, over any scenario and top layer. */
+    resolveLayers(scenario: SDKScenario | null, overrides: SessionSettingsOverrides | null): ResolvedSettings;
+    /**
+     * Every settings resource resolved as a scenario other than the session's
+     * would resolve it, under edits of its own rather than the session layer:
+     * the scenario editor's draft (§6.5). Null resolves the defaults alone.
+     * Throws when the package declares no such scenario.
+     */
+    resolveScenarioDraft(scenarioId: string | null, edits: SessionSettingsOverrides | null): ResolvedSettings;
+    /**
+     * Compute the default session-override layer for the current game,
+     * ignoring any cached user edits. Used by the dev server's 'Reset
+     * configuration' action so the operator can return to a clean slate without
+     * restarting the game. The caller persists the returned configuration.
+     */
+    buildResetConfiguration(): ResolvedSettings;
+    /**
+     * Get the identifiers of all shared capabilities referenced in the current game
+     */
+    getSharedCapabilityIds(): string[];
+    /**
+     * The capabilities declared `lifetime: 'session'` (§7.6): kept out of the
+     * tick's reach, so undo and reset leave them as they are.
+     */
+    getSessionLifetimeCapabilityIds(): string[];
+    /**
+     * Get the identifiers of all team-readable capabilities in the current game
+     */
+    getTeamReadableCapabilityIds(): string[];
+    /**
+     * Where `getPastState` reads from, and what 'every team' means to it.
+     *
+     * Both come from the host rather than being tracked here, because the
+     * history and the roster are the session's and a second copy of the team
+     * list in the executor is a second copy to fall out of step.
+     */
+    setHistoryAccess(access: {
+        read: NonNullable<ExecutorCallbacksDeps['readPastState']>;
+        allTeamIndexes: () => number[];
+    }): void;
+    /**
+     * Have the platform services logic calls (`generateText`, `extractText`,
+     * `generateSpeech`) fail whenever `take` returns a failure. The host owns
+     * what arms one: the dev server's `llm-failure` fault.
+     */
+    setPlatformFailures(take: NonNullable<ExecutorCallbacksDeps['takePlatformFailure']>): void;
+    /**
+     * Look up an endpoint by identifier in the loaded configuration.
+     */
+    getEndpoint(identifier: string): SDKEndpoint | undefined;
+    /**
+     * Invoke an endpoint's `Handle` function. The caller identity is sourced
+     * from host bookkeeping — iframe-supplied fields are never trusted. The
+     * returned value is validated against the endpoint's `responseSchema` by
+     * the dispatcher before being returned to the caller.
+     *
+     * Throws if the endpoint is unknown or its bundle does not export a
+     * `Handle` function.
+     */
+    runEndpoint(args: EndpointCallArgs): Promise<EndpointRun>;
+    /**
+     * Call `Respond` once an endpoint's effects have landed (§6.12). The
+     * arguments are built exactly as `Handle`'s were, from state the session
+     * has read afresh, with the plan `Handle` returned and what each of its
+     * actions came to. Its return is the response, held to `responseSchema`.
+     */
+    respondEndpoint(args: EndpointCallArgs & {
+        plan: EndpointRun;
+        outcomes: EndpointOutcome[];
+    }): Promise<unknown>;
+}

package/dist/execution/gates.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The validator gates (§15): every validator that exports a gate, put to the
+ * action that gate stands for, collecting every refusal.
+ *
+ * Two gates exist, `UpdateData` for a participant's write and `RequestTick`
+ * for a participant's request for the next tick, and they differ only in what
+ * each validator is handed and in whether it runs at all. Everything else,
+ * which validators have the gate, the manifest order, a throw or an abandoned
+ * call read as one more refusal, and collect-all, is one rule, so it is written
+ * once here and each gate is an `invoke` over it. Who counts as a participant,
+ * and so whether a gate runs, is the session's to decide; this module is only
+ * the running of them.
+ */
+import type { ValidationRejection, ValidatorActor } from '@seriousgaming/sdk';
+import type { LogicHost } from './logic-calls';
+import type { GameContext } from './types';
+/**
+ * Put a participant's context write to every validator exporting
+ * `UpdateData` whose `reads` it changes (§15.2.1).
+ *
+ * Collects every rejection (form-style UX) rather than short-circuiting, and
+ * returns an empty array when every validator that ran returned
+ * `{ ok: true }`. Validators are reject-only: callers must not apply the
+ * proposed `next` state unless the returned array is empty.
+ *
+ * **Only the validators the write could affect run** (§15.2), on the rule
+ * §11.1a already applies to the tick controller: a validator runs when the
+ * write changes the value of a capability in its `reads`, and one that
+ * declares no reads runs on every write. Every validator running on every
+ * keystroke from every participant is the hottest path in the runtime, and
+ * most of those runs cannot change the verdict — a validator now receives
+ * only its declared reads (§7.4), so a write touching none of them cannot
+ * alter anything it can see.
+ *
+ * The comparison is by value, not by payload key. A full-context sender
+ * names every capability on every write, so gating on the keys present
+ * would re-run everything for exactly the chattiest callers.
+ */
+export declare function runUpdateDataGates(host: LogicHost, previous: GameContext, next: GameContext, actor: ValidatorActor): Promise<ValidationRejection[]>;
+/**
+ * Put a participant's request for the next tick to every validator
+ * exporting `RequestTick` (§15.1). A request changes nothing, so the
+ * changed-`reads` rule has nothing to look at: every such gate runs.
+ */
+export declare function runRequestTickGates(host: LogicHost, context: GameContext, actor: ValidatorActor, requestedTick: number): Promise<ValidationRejection[]>;

package/dist/execution/hook-chain.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Running the hooks subscribed to one lifecycle signal (§14), as a chain.
+ *
+ * Each hook receives the board the hook before it left, so the chain is one
+ * sequence of folds over one team's board rather than several independent
+ * calls, and the roster they read is taken once for all of them (§14.3). The
+ * executor owns the board; the chain reads it and writes it back after every
+ * hook, so a hook that throws leaves the ones before it applied, exactly as a
+ * runtime that stops a chain part way must.
+ */
+import type { HookPayload, HookSignal } from '@seriousgaming/sdk';
+import type { LogicHost } from './logic-calls';
+import type { GameContext } from './types';
+export interface HookChainHost extends LogicHost {
+    /** The board the chain runs against: the team the host swapped in. */
+    board(): GameContext;
+    setBoard(context: GameContext): void;
+    capabilityDefaults(): ReadonlyMap<string, Record<string, unknown>>;
+}
+/**
+ * Dispatch a lifecycle signal to all hooks subscribed to it. Each hook
+ * receives the previous hook's output as input, so the host's board
+ * reflects the full chain of mutations after the call returns.
+ */
+export declare function runHookChain<S extends HookSignal>(host: HookChainHost, signal: S, payload: HookPayload<S>): Promise<GameContext>;