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

package/lib/projection.d.ts

@@ -0,0 +1,266 @@
+/**
+ * The one documented shape of a session's observable state.
+ *
+ * Served three ways and declared once: `sdk view --json`, `GET /api/state`, and
+ * the payload the console renders. It is a projection, not any runtime's
+ * internal state, so internals can change without breaking an agent that
+ * learned to read it, and it is versioned so one that has learned can tell when
+ * they have not.
+ *
+ * Everything a runtime exposes about a session belongs here, because a check
+ * made from outside a runtime can only read what the runtime exposes.
+ *
+ * Published from the SDK rather than declared inside a runtime, because a
+ * second runtime implementing it needs the shape, and a type it has to copy is
+ * a type the two halves are free to drift apart on.
+ */
+import type { Participant, TeamInfo } from './build/callbacks.js';
+import type { EndpointCallerRole } from './build/endpoints.js';
+import type { RunKind, SessionMode } from './build/signatures.js';
+import type { TimerState } from './build/timer.js';
+import type { MutationOutcome } from './ui/mutation-outcome.js';
+export type { Participant, TeamInfo, TimerState };
+/**
+ * Bumped when a field changes meaning or leaves.
+ *
+ * Adding a field is not a bump: a reader that ignores what it does not know
+ * keeps working. Renaming or removing one is.
+ */
+export declare const PROJECTION_VERSION = 4;
+/**
+ * A failure a runtime can produce that another otherwise cannot (§9.7, §12.5.1).
+ *
+ * Armed by name rather than provoked, so an author can verify a game's error
+ * handling without manufacturing the race that would otherwise be the only way
+ * to reach the state.
+ *
+ * @internal The SDK dev server's fault injection. Another runtime need not
+ * offer it, and the set may change without a major release.
+ */
+export type FaultKind = 
+/** The next UI mutation settles `{ kind: 'conflict' }` (§12.5.1). */
+'conflict'
+/** The next UI mutation settles `{ kind: 'denied' }` (§12.5.1). */
+ | 'denied'
+/** The next platform service call (`generateText`, `extractText`, `generateSpeech`) rejects (§17). */
+ | 'llm-failure'
+/** The next hook chain throws (§14.5). */
+ | 'hook-throw'
+/** The next `callEndpoint` exceeds its bound (§6.12). */
+ | 'endpoint-timeout'
+/** The next tick fails, atomically (§9.7). */
+ | 'tick-failure';
+/**
+ * One armed fault, as the state projection reports it.
+ *
+ * @internal See {@link FaultKind}.
+ */
+export interface ArmedFault {
+    kind: FaultKind;
+    /** How many more times it will fire. */
+    remaining: number;
+    /** Operator-supplied note, echoed back so a log says why. */
+    reason?: string;
+}
+/** Resolved settings, keyed by settings identifier (§8). */
+export type ResolvedSettings = Record<string, Record<string, unknown>>;
+/** The scenario editor's draft of one scenario (§6.5), resolved. */
+export interface ScenarioDraft {
+    /** The scenario being edited, or null for one started from the package's own settings. */
+    scenarioId: string | null;
+    /** The defaults, then that scenario's `settings`, then the unsaved edits. */
+    settings: ResolvedSettings;
+}
+export type { SessionMode };
+/** One team's observable state. */
+export interface ProjectedTeam extends TeamInfo {
+    /** Ticks this team has completed. Equal to the session's outside independent mode. */
+    completedTicks: number;
+    complete: boolean;
+    canUndo: boolean;
+    /** The composed view: the team's own context plus the shared store (§7.5). */
+    context: Record<string, Record<string, unknown>>;
+    /** §13.2: absence is reported (`connected: false`), never erased. */
+    participants: Participant[];
+    /**
+     * The timer this team's surfaces are sent (§12.3, `TimerState`). In
+     * independent mode each team has its own; otherwise every team carries the
+     * cohort's. Absent from a runtime that reports none.
+     */
+    timer?: TimerState;
+    /**
+     * The engine's private memory for this team (§10.2), absent until the
+     * engine first returns one. No surface is ever sent it; it is here for the
+     * operator's tools and for tests.
+     */
+    state?: unknown;
+}
+/**
+ * What changed on disk that a running session applies only when it next
+ * initialises. Each list is empty when nothing of its kind is waiting.
+ */
+export interface PendingChanges {
+    /** Settings resources whose resolved values differ from the session's. */
+    settings: string[];
+    /**
+     * Manifest fields read only at initialisation: `identifier`, `teams.mode`,
+     * and `setup` for the configuration step. The game's tick limit, team
+     * bounds and `openOnStart` are the `game` settings, listed in `settings`.
+     */
+    manifest: string[];
+    /** Capabilities removed from the package, or whose scope changed. */
+    capabilities: string[];
+}
+export interface StateProjection {
+    projectionVersion: number;
+    game: {
+        identifier: string;
+        /** The game's name in the session locale, which surfaces render. */
+        name: string;
+        /** The active scenario, or null when the game declares none. */
+        scenarioId: string | null;
+    };
+    session: {
+        /** Ticks the session has completed: the shared clock, or the furthest team's. */
+        completedTicks: number;
+        mode: SessionMode;
+        waitingRoomOpen: boolean;
+        /** True only once every team is complete (§12.4). */
+        complete: boolean;
+        /** Stable for the session, unchanged by a re-run of one tick (§10). */
+        seed: string;
+        /**
+         * What every surface of this run is sent on `init` to namespace its
+         * own storage by (§12.2): opaque, unique to the run, and not the
+         * session's address. Beyond §20.1's shape, as §20.1 permits: the
+         * console needs it to hand the frames it mounts.
+         */
+        sessionKey: string;
+        locale: string;
+        /**
+         * Whether this is the game being played or a walkthrough beside it
+         * (§5.7). The same value logic reads as `meta.runKind`.
+         */
+        runKind: RunKind;
+        /**
+         * The tick limit: the resolved `game` settings' `maxTicks`, or null when
+         * completion is the engine's or the tick controller's to decide.
+         */
+        maxTicks: number | null;
+        /**
+         * The team bounds a surface gates its controls on (§5.4).
+         *
+         * `max` is the **effective** maximum, already resolved as the lower of
+         * the game's declared maximum and this host's own ceiling. A surface
+         * that read the manifest value instead would disable its add-team
+         * control at the wrong point.
+         */
+        teamBounds: {
+            min?: number;
+            max: number;
+        };
+        /**
+         * True while the session is in its setup state (§8.3, §9.0): the game has a
+         * `setup` slot and nobody has started play yet.
+         *
+         * On the projection rather than only on a separate route because it
+         * decides what a client may render: a console that read it from a
+         * second request showed the setup UI for a frame after somebody
+         * pressed Play, and the player surfaces for a frame after somebody
+         * sent the session back to its setup state.
+         */
+        inSetup: boolean;
+        /**
+         * Edits on disk this session has not applied, because they take
+         * effect only when a session initialises. Absent when there are none.
+         *
+         * A local authoring host's own field, beyond §20.1's shape as §20.1
+         * permits: a host that reloads a package while it runs must say when
+         * the session no longer matches what is on disk, rather than run on
+         * a mixture of the two.
+         */
+        pending?: PendingChanges;
+    };
+    teams: ProjectedTeam[];
+    /** The canonical shared store (§7.5), empty outside shared-state mode. */
+    shared: Record<string, Record<string, unknown>>;
+    /**
+     * The engine's session-wide private memory (§10.2), absent until an
+     * aggregate function first returns one under `shared.state`.
+     */
+    sharedState?: unknown;
+    /**
+     * The cohort's automatic tick timer (§11.4), the same `TimerState` a
+     * surface is sent. Null in independent mode, where each team has its own
+     * on its entry.
+     */
+    timer: TimerState | null;
+    /**
+     * Every settings resource's resolved values (§8): defaults, the active
+     * scenario, then the session's overrides. Keyed by settings identifier.
+     */
+    settings: ResolvedSettings;
+    /**
+     * The same, without the session layer: defaults then the active scenario.
+     * What a surface shown outside the session reads, such as a presentation
+     * previewed with no session (§6.15.1).
+     */
+    settingsWithoutSession: ResolvedSettings;
+    /**
+     * Each scenario a scenario editor is open on, with its draft resolved:
+     * the defaults, that scenario, then the editor's unsaved edits (§6.5).
+     * What the editor is sent as `setSettings`. Absent while none is open.
+     */
+    scenarioDrafts?: ScenarioDraft[];
+    /**
+     * Faults armed for this session. Empty in a session nobody has armed one in.
+     *
+     * @internal See {@link FaultKind}.
+     */
+    faults: ArmedFault[];
+}
+/**
+ * One endpoint call that changed something (§6.12): who made it, and what it
+ * changed. Names only, never values, so the log does not become a second copy
+ * of the boards.
+ */
+export interface EndpointAuditEntry {
+    /** Epoch milliseconds, on the session's clock. */
+    at: number;
+    endpoint: string;
+    /** The caller's role, as the endpoint was told it. */
+    role: EndpointCallerRole;
+    /** Who was behind an external call, where the host said. */
+    principal?: {
+        kind: string;
+        id: string;
+        name?: string;
+    };
+    /** The team a team-scoped call ran for. */
+    teamId?: string;
+    /** Capabilities its own patch wrote. */
+    wrote: string[];
+    /** A session-scoped call's per-team writes: team id to capabilities. */
+    teams?: Record<string, string[]>;
+    /** The session actions it returned, in order. */
+    actions: string[];
+    /**
+     * Where the call stopped, when a step failed after earlier ones had
+     * landed: those stay applied, and everything from here on did not.
+     */
+    stoppedAt?: string;
+}
+/**
+ * What a mutation settled as (§12.5.1).
+ *
+ * The failure half is the SDK's own {@link MutationOutcome}, not a restatement
+ * of it: a projection that re-declared the vocabulary it reports would be free
+ * to drift from it.
+ */
+export type MutationResult = {
+    ok: true;
+    committedAtTick?: number;
+} | {
+    ok: false;
+    outcome: MutationOutcome;
+};

package/lib/projection.js

@@ -0,0 +1,23 @@
+/**
+ * The one documented shape of a session's observable state.
+ *
+ * Served three ways and declared once: `sdk view --json`, `GET /api/state`, and
+ * the payload the console renders. It is a projection, not any runtime's
+ * internal state, so internals can change without breaking an agent that
+ * learned to read it, and it is versioned so one that has learned can tell when
+ * they have not.
+ *
+ * Everything a runtime exposes about a session belongs here, because a check
+ * made from outside a runtime can only read what the runtime exposes.
+ *
+ * Published from the SDK rather than declared inside a runtime, because a
+ * second runtime implementing it needs the shape, and a type it has to copy is
+ * a type the two halves are free to drift apart on.
+ */
+/**
+ * Bumped when a field changes meaning or leaves.
+ *
+ * Adding a field is not a bump: a reader that ignores what it does not know
+ * keeps working. Renaming or removing one is.
+ */
+export const PROJECTION_VERSION = 4;

package/lib/testing/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Helpers for unit-testing a game's logic without a runtime.
+ *
+ * `logicArgs` builds the arguments object a logic function takes, filling
+ * everything the test does not name. `createStubCallbacks` is the offline,
+ * deterministic set of callbacks it uses, and the stubs behind it are the ones
+ * `createTestSession` answers service callbacks with.
+ *
+ * To test a game as a whole (hooks, validators, endpoints, undo, timers), use
+ * `createTestSession` from `@seriousgaming/sdk-tools/client`.
+ */
+export { logicArgs, TEST_NOW, TEST_SEED, type AggregateArgsInput, type EndpointArgsInput, type EngineArgsInput, type HookArgsInput, type RequestTickArgsInput, type TickControllerArgsInput, type ValidatorArgsInput, } from './logic-args.js';
+export { createStubCallbacks, STUB_SPEECH_DURATION_MS, stubExtractText, stubGenerateText, stubSpeechAudio, } from './stub-services.js';

package/lib/testing/index.js

@@ -0,0 +1,13 @@
+/**
+ * Helpers for unit-testing a game's logic without a runtime.
+ *
+ * `logicArgs` builds the arguments object a logic function takes, filling
+ * everything the test does not name. `createStubCallbacks` is the offline,
+ * deterministic set of callbacks it uses, and the stubs behind it are the ones
+ * `createTestSession` answers service callbacks with.
+ *
+ * To test a game as a whole (hooks, validators, endpoints, undo, timers), use
+ * `createTestSession` from `@seriousgaming/sdk-tools/client`.
+ */
+export { logicArgs, TEST_NOW, TEST_SEED, } from './logic-args.js';
+export { createStubCallbacks, STUB_SPEECH_DURATION_MS, stubExtractText, stubGenerateText, stubSpeechAudio, } from './stub-services.js';

package/lib/testing/logic-args.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Arguments for calling a logic function directly in a unit test.
+ *
+ * Every logic function takes one arguments object, and most of it is the
+ * runtime's to supply: `meta`, the roster, the callbacks, a session summary.
+ * A test cares about the context and perhaps one setting. Each builder here
+ * takes what the test cares about and fills the rest with fixed, deterministic
+ * values, typed so the result passes straight to the function with no cast.
+ *
+ * ```ts
+ * import { logicArgs } from '@seriousgaming/sdk/testing';
+ * import { defaultContext, defaultSettings } from './defaults';
+ * import { Run } from './logic';
+ *
+ * const result = await Run(
+ *     logicArgs.run({ context: defaultContext, settings: defaultSettings, meta: { tick: 3 } })
+ * );
+ * ```
+ *
+ * Settings are not read from disk: there is no runtime here. Pass the
+ * resource's generated `defaultSettings`, spread with any value the test
+ * changes. A resource that declares no settings may leave `settings` out.
+ */
+import type { AggregateFunctionShared, AggregateFunctionTeam, EndpointCaller, EndpointHandlerArgs, EndpointScope, EndpointSession, EndpointTeamEntry, EngineFunctionArgs, HookFunctionArgs, HookPayloadMap, LogicMeta, Participant, RequestTickFunctionArgs, RunAggregateFunctionArgs, RunMeta, SignatureCallbacks, TeamInfo, TeamRunMeta, TickControllerFunctionArgs, ValidatorActor, ValidatorFunctionArgs } from '../build/index.js';
+import type { HookSignal } from '../build/resource-schema.js';
+/** The `meta.seed` every builder uses unless told otherwise. */
+export declare const TEST_SEED = "test-seed";
+/** The `meta.now` every builder uses unless told otherwise: 2026-01-01T00:00:00Z. */
+export declare const TEST_NOW: number;
+/** A type with no members, which an empty object satisfies. */
+type Empty = Record<never, never>;
+/** The settings a resource that declares none receives. */
+type NoSettings = Record<string, never>;
+/** The callbacks of any logic-bearing resource: some subset of {@link SignatureCallbacks}. */
+type AnyCallbacks = Partial<SignatureCallbacks>;
+/**
+ * `settings`, optional only where the type has nothing a test could leave
+ * out: a resource that declares no settings resources. Anything else needs its
+ * values, since a builder cannot read the schema defaults from disk.
+ */
+type SettingsInput<TSettings> = Empty extends TSettings ? {
+    settings?: TSettings;
+} : {
+    settings: TSettings;
+};
+/** What every team-scoped builder takes beyond its own arguments. */
+interface CommonInput<TCallbacks> {
+    /**
+     * The roster the call sees. Defaults to one connected participant on the
+     * call's team (two teams' worth for a builder with several teams).
+     */
+    participants?: readonly Readonly<Participant>[];
+    /**
+     * Callbacks to use instead of the stubs. Anything not named keeps its stub
+     * (see `createStubCallbacks`).
+     */
+    callbacks?: NoInfer<Partial<TCallbacks>>;
+}
+/** Input to {@link logicArgs.init} and {@link logicArgs.run}. */
+export type EngineArgsInput<TContext, TSettings, TCallbacks, TState> = CommonInput<TCallbacks> & SettingsInput<TSettings> & {
+    context: TContext;
+    /** Any of `meta`; the rest is filled. `teamId` follows `index` when only `index` is given. */
+    meta?: Partial<TeamRunMeta>;
+    state?: TState;
+};
+/** Input to {@link logicArgs.aggregate}. */
+export type AggregateArgsInput<TTeamContext, TSharedContext, TSettings, TCallbacks, TTeamState, TSharedState> = CommonInput<TCallbacks> & SettingsInput<TSettings> & (Empty extends TSharedContext ? {
+    shared?: AggregateFunctionShared<TSharedContext, TSharedState>;
+} : {
+    shared: AggregateFunctionShared<TSharedContext, TSharedState>;
+}) & {
+    /** Every team the call covers. A team's `teamId` follows its `index` when left out. */
+    teams: (Omit<AggregateFunctionTeam<TTeamContext, TTeamState>, 'teamId'> & {
+        teamId?: string;
+    })[];
+    meta?: Partial<RunMeta>;
+};
+/** Input to {@link logicArgs.hook}. */
+export type HookArgsInput<S extends HookSignal, TContext, TSettings, TCallbacks> = CommonInput<TCallbacks> & SettingsInput<TSettings> & HookPayloadMap[S] & {
+    /**
+     * The signal the hook subscribes to, which decides the payload it
+     * needs. Defaults to `participantJoin`; name it for any other.
+     */
+    signal?: S;
+    context: TContext;
+    meta?: Partial<LogicMeta>;
+};
+/** Input to {@link logicArgs.endpoint}. */
+export type EndpointArgsInput<TRequest, TContext, TCallbacks, TTeamContext, TSettings> = CommonInput<TCallbacks> & SettingsInput<TSettings> & {
+    request: TRequest;
+    context: TContext;
+    /**
+     * Who is calling. `role` defaults to `participant`; the rest follows the
+     * role: a participant is the first on the roster, through `ui`; a
+     * facilitator calls from `session`; an author calls from `scenario_editor`
+     * with no session; an external caller names no surface.
+     */
+    caller?: Partial<EndpointCaller>;
+    /** The team a team-scoped call acts on. Defaults to `team-1`, index 0. */
+    team?: Partial<TeamInfo>;
+    /** A session-scoped call's per-team values. */
+    teams?: EndpointTeamEntry<TTeamContext>[];
+    /** Where the session stands. Defaults to an independent session with no ticks completed. */
+    session?: Partial<EndpointSession>;
+    meta?: Partial<LogicMeta>;
+};
+/** Input to {@link logicArgs.tickController}. */
+export type TickControllerArgsInput<TContext, TSettings, TCallbacks> = CommonInput<TCallbacks> & SettingsInput<TSettings> & {
+    context: TContext;
+    meta?: Partial<TeamRunMeta>;
+    /** Defaults to the one team `meta` names, with `context`. */
+    teams?: AggregateFunctionTeam<TContext>[];
+    waitingRoomOpen?: boolean;
+};
+/** Input to {@link logicArgs.validator}. */
+export type ValidatorArgsInput<TContext, TSettings> = SettingsInput<TSettings> & {
+    previous: TContext;
+    next: TContext;
+    /** Defaults to the first participant on the roster. */
+    actor?: ValidatorActor;
+    meta?: Partial<LogicMeta>;
+    participants?: readonly Readonly<Participant>[];
+};
+/** Input to {@link logicArgs.requestTick}. */
+export type RequestTickArgsInput<TContext, TSettings> = SettingsInput<TSettings> & {
+    context: TContext;
+    /** Defaults to 1, a team's first request. */
+    requestedTick?: number;
+    /** Defaults to the first participant on the roster. */
+    actor?: ValidatorActor;
+    meta?: Partial<LogicMeta>;
+    participants?: readonly Readonly<Participant>[];
+};
+declare function init<TContext, TSettings = NoSettings, TCallbacks extends AnyCallbacks = Required<SignatureCallbacks>, TState = never>(input: EngineArgsInput<TContext, TSettings, TCallbacks, TState>): EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>;
+declare function run<TContext, TSettings = NoSettings, TCallbacks extends AnyCallbacks = Required<SignatureCallbacks>, TState = never>(input: EngineArgsInput<TContext, TSettings, TCallbacks, TState>): EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>;
+declare function aggregate<TTeamContext, TSharedContext = NoSettings, TSettings = NoSettings, TCallbacks extends AnyCallbacks = Required<SignatureCallbacks>, TTeamState = never, TSharedState = never>(input: AggregateArgsInput<TTeamContext, TSharedContext, TSettings, TCallbacks, TTeamState, TSharedState>): RunAggregateFunctionArgs<TTeamContext, TSharedContext, TSettings, TCallbacks, TTeamState, TSharedState>;
+declare function hook<S extends HookSignal = 'participantJoin', TContext = unknown, TSettings = NoSettings, TCallbacks extends AnyCallbacks = Required<SignatureCallbacks>>(input: HookArgsInput<S, TContext, TSettings, TCallbacks>): HookFunctionArgs<S, TContext, TSettings, TCallbacks>;
+declare function endpoint<TRequest, TContext, TCallbacks extends AnyCallbacks = Required<SignatureCallbacks>, TTeamContext = never, TScope extends EndpointScope = 'team', TSettings = NoSettings>(input: EndpointArgsInput<TRequest, TContext, TCallbacks, TTeamContext, TSettings>): EndpointHandlerArgs<TRequest, TContext, TCallbacks, TTeamContext, TScope, TSettings>;
+declare function tickController<TContext, TSettings = NoSettings, TCallbacks extends AnyCallbacks = Required<SignatureCallbacks>>(input: TickControllerArgsInput<TContext, TSettings, TCallbacks>): TickControllerFunctionArgs<TContext, TSettings, TCallbacks>;
+declare function validator<TContext, TSettings = NoSettings>(input: ValidatorArgsInput<TContext, TSettings>): ValidatorFunctionArgs<TContext, TSettings>;
+declare function requestTick<TContext, TSettings = NoSettings>(input: RequestTickArgsInput<TContext, TSettings>): RequestTickFunctionArgs<TContext, TSettings>;
+/**
+ * Builders for each logic function's arguments. Each takes what the test
+ * names and fills the rest:
+ *
+ * - `meta`: `locale: 'en'`, `seed: 'test-seed'`, `runKind: 'session'`,
+ *   `now` 2026-01-01T00:00:00Z, and where the function runs for a team,
+ *   `index: 0` and `teamId: 'team-1'`. `tick` is 0 for `init` and 1 for the
+ *   rest; `InitAggregate` passes `meta: { tick: 0 }`
+ * - `participants`: one connected participant on each team the call covers
+ * - `callbacks`: the offline stubs of `createStubCallbacks`, with any the
+ *   test passes in their place
+ * - `settings`: required unless the resource declares none, since there is no
+ *   runtime to resolve them. Pass the generated `defaultSettings`
+ *
+ * | Builder          | For                                             |
+ * | ---------------- | ----------------------------------------------- |
+ * | `init`           | the engine's `Init`                             |
+ * | `run`            | the engine's `Run`, and the steps it calls      |
+ * | `aggregate`      | `RunAggregate` and `InitAggregate`              |
+ * | `hook`           | a hook's `Run`                                  |
+ * | `endpoint`       | an endpoint's `Handle` or `Plan`                |
+ * | `tickController` | `GetTickController`                             |
+ * | `validator`      | a validator's `UpdateData`                      |
+ * | `requestTick`    | a validator's `RequestTick`                     |
+ */
+export declare const logicArgs: {
+    init: typeof init;
+    run: typeof run;
+    aggregate: typeof aggregate;
+    hook: typeof hook;
+    endpoint: typeof endpoint;
+    tickController: typeof tickController;
+    validator: typeof validator;
+    requestTick: typeof requestTick;
+};
+export {};