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

package/dist/core/protocol.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a client may ask the session to do, and what it hears back.
+ *
+ * One closed command set and one closed event set, shared by every client:
+ * the browser console, the CLI, and an agent driving it over HTTP. There is no
+ * second vocabulary for the CLI, which is what let the two drift before.
+ *
+ * The event set is small on purpose. The old protocol had seventeen event
+ * kinds, most of which were a slice of session state with its own payload
+ * shape: `context-updated`, `config-reloaded`, `initialized`,
+ * `participants-updated`, `waiting-room-changed`, `timer-updated`. They are all
+ * the same sentence, so there is one {@link StateEvent} carrying the whole
+ * projection, and a client renders from it. What remains distinct is what is
+ * genuinely not state: diagnostics, transient signals, and correlated replies.
+ */
+import type { RunKind, ValidationRejection } from '@seriousgaming/sdk';
+import type { Actor, Command, MutationCommand, QueryCommand, QueryResult, TeamScope, ViewerRole } from '@seriousgaming/sdk/commands';
+import type { MutationResult, StateProjection } from '@seriousgaming/sdk/projection';
+export type { Actor, Command, MutationCommand, QueryCommand, QueryResult, TeamScope, ViewerRole };
+/** Whether a command reads rather than mutates, and so bypasses the queue. */
+export declare function isQuery(command: Command): command is QueryCommand;
+/**
+ * Whether a command, addressed to `run`, replaces the walkthrough rather than
+ * reaching it.
+ *
+ * A `reset` sent to the walkthrough is one: a walkthrough always starts at
+ * tick 0 with one team (§5.7), so rewinding it has nothing to offer over
+ * rebuilding it, and a rewind keeps the scenario, locale and configuration the
+ * run was first built on rather than following the session's current ones.
+ */
+export declare function rebuildsWalkthrough(command: Command, run: RunKind): boolean;
+/**
+ * The session's state, whole, after something changed it.
+ *
+ * One event rather than a family of partial ones. A client re-renders from the
+ * projection and never has to reconcile six differently-shaped updates into a
+ * picture of the same session.
+ */
+export interface StateEvent {
+    type: 'state';
+    state: StateProjection;
+    /**
+     * Why it changed, for diagnostics and for a console that wants to say so.
+     * Never load-bearing: a client that ignores it still renders correctly.
+     */
+    cause: string;
+}
+/** A failure the operator should see (§14.5, and tick failures). */
+export interface ErrorEvent {
+    type: 'error';
+    message: string;
+    /** Where it came from, e.g. `tick`, `hook:participantJoin`, `endpoint:narrate`. */
+    source: string;
+    teamId?: string;
+}
+/** Validators refused a UI-submitted write (§15). */
+export interface ValidationRejectedEvent {
+    type: 'validation-rejected';
+    rejections: ValidationRejection[];
+    teamIndex?: number;
+}
+/**
+ * A round is being processed, so a surface can say so rather than appearing to
+ * have stopped responding (§12.4.4). Transient, and never state: a client that
+ * missed it is not wrong about the session.
+ */
+export interface RoundProcessingEvent {
+    type: 'round-processing';
+    processing: boolean;
+    /** Absent for a cohort tick that genuinely covers every team. */
+    teamIndex?: number;
+}
+export type Event = StateEvent | ErrorEvent | ValidationRejectedEvent | RoundProcessingEvent;
+export type { MutationResult };
+/**
+ * Why this is not a command, or null when it is one.
+ *
+ * Deliberately names the field and what was expected. The failure this replaces
+ * was `{"type":"addParticipant","team":1}` being accepted for a command whose
+ * field is `teamId`, and then failing three steps later with nothing pointing
+ * back here.
+ */
+export declare function commandError(value: unknown): string | null;

package/dist/core/scenario-drafts.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The scenario editor's unsaved edits (§6.5), one draft per scenario being
+ * edited.
+ *
+ * A draft belongs to no session. The dev server runs a session beside the
+ * editor, and the editor's edits used to land in that session's override
+ * layer, so editing a scenario quietly reconfigured the session and an
+ * endpoint the editor called read the session's setup edits as the draft.
+ * Kept here instead, each draft is only its own edits, sparse as the session
+ * layer is (§8.2), and resolved over the scenario it was opened on. It
+ * reaches a session only once it is saved as that scenario.
+ *
+ * Held by the session object because the dev server has one process and one
+ * place for state, not because a draft is part of the session: nothing a
+ * session does, a restart included, touches one.
+ */
+import type { SessionSettingsOverrides } from '../execution/types';
+export declare class ScenarioDrafts {
+    private readonly drafts;
+    /** Open a draft of a scenario, keeping one already open on it. */
+    open(scenarioId: string | null): void;
+    isOpen(scenarioId: string | null): boolean;
+    /** The unsaved edits to a scenario, or null when no editor is open on it. */
+    edits(scenarioId: string | null): SessionSettingsOverrides | null;
+    /** Fold an edit, already reduced to what changed, into an open draft. */
+    record(scenarioId: string | null, changed: Record<string, unknown>): void;
+    /** Empty a draft once it has been saved: the scenario now holds its edits. */
+    saved(scenarioId: string | null): void;
+    /** Drop the drafts of scenarios the package no longer declares. */
+    retain(scenarioIds: ReadonlySet<string>): void;
+    scenarioIds(): (string | null)[];
+}

package/dist/core/session-endpoints.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Endpoint calls as the session serves them (§6.12): who may make one, what
+ * the handler is told about the session, and how its effects land.
+ *
+ * An endpoint is a read that may end in writes and actions, so it runs beside
+ * the mutation queue (§9.7) and only its effects go on it, as one job, checked
+ * first against the boards the handler read so that nothing lands on a board a
+ * tick replaced meanwhile. The caller's role and team are the host's
+ * bookkeeping, never the request's, and every call that changed something is
+ * kept in an audit, since afterwards an agent's change is otherwise
+ * indistinguishable from the game's own. Running the handler itself is the
+ * executor's.
+ */
+import type { EndpointAuditEntry } from '@seriousgaming/sdk/projection';
+import type { QueryCommand, QueryResult } from './protocol';
+import type { SessionHost } from './session-host';
+type CallEndpoint = Extract<QueryCommand, {
+    type: 'callEndpoint';
+}>;
+type EndpointHost = Pick<SessionHost, 'executor' | 'state' | 'participants' | 'faults' | 'clock' | 'timers' | 'pendingChanges' | 'mode' | 'settings' | 'scenarioBeingEdited' | 'waitingRoomOpen' | 'positionOf' | 'indexOfTeamId' | 'teamAt' | 'roster' | 'declaredSurface' | 'enqueue' | 'apply'>;
+export declare class SessionEndpoints {
+    private readonly host;
+    private readonly audit;
+    constructor(host: EndpointHost);
+    /** Endpoint calls that changed something, oldest first (§6.12). */
+    auditLog(): readonly EndpointAuditEntry[];
+    /**
+     * Answer an endpoint call. A failure is an answer, so every transport
+     * carries it as it stands rather than flattening a throw into a message.
+     */
+    answer(command: CallEndpoint): Promise<QueryResult>;
+    /** The endpoints a caller may see: every one, or the published ones outside the game. */
+    list(external: boolean | undefined): QueryResult;
+    /**
+     * Run one endpoint call (§6.12): who may make it, the handler, its effects
+     * and, for an endpoint that answers in two phases, `Respond`. Throws on any
+     * failure; {@link answer} turns the throw into an `EndpointFailure`.
+     */
+    private call;
+    /** Whether the scenario editor made this call, which runs with no session (§6.5). */
+    private fromScenarioEditor;
+    /**
+     * A call from the scenario editor (§6.5, §6.12). The editor edits a
+     * scenario rather than a session, so the handler is given the settings as
+     * that scenario would resolve them, the draft included, and nothing of the
+     * session this host happens to be running beside it: no board, no team, no
+     * roster, and a caller with no session. The build refuses an editor that
+     * lists an endpoint needing more, but the dev server runs a package the
+     * build refuses, so the call is refused here as well.
+     */
+    private callFromEditor;
+    /**
+     * What a call with no session is told of one (§6.12): the game's mode and
+     * the tick limit the scenario being edited resolves to, and nothing played.
+     */
+    private sessionless;
+    /**
+     * Carry out what an endpoint returned (§6.12): its write, then its per-team
+     * writes, then its actions, as one job on the queue, so no other mutation
+     * lands between them and none of them lands on a board a tick replaced
+     * while the handler ran.
+     *
+     * Everything that can be checked without applying is checked before the
+     * job is queued, so a bad team id or an undeclared action applies nothing. What cannot be checked in advance, such as an engine
+     * failing the tick an action asked for, stops the sequence where it fails:
+     * the steps before it have landed, and the caller is told how many.
+     */
+    private applyEffects;
+    /**
+     * The session command an endpoint's action stands for (§6.12), with its
+     * team resolved. An omitted `teamId` is the call's own team on a
+     * team-scoped endpoint and the whole session on a session-scoped one.
+     */
+    private actionCommand;
+    /**
+     * Keep a record of an endpoint call that changed something (§6.12): which
+     * endpoint, who called it, and what it changed. An agent's change is
+     * otherwise indistinguishable from the game's own after the fact.
+     */
+    private record;
+    /**
+     * The team a team-scoped endpoint call runs for (§6.12): by index, else by
+     * id, else the session's only team.
+     *
+     * Refused when a session of several teams names none. The handler is
+     * promised a `team`, and the only board left to hand it is whichever the
+     * executor last worked with, which is one team's figures under no name.
+     */
+    private position;
+    /** Whether this endpoint declared anything that lives on a team board. */
+    private readsTeams;
+    /**
+     * Every team's board, for a session-scoped endpoint's non-shared reads
+     * (§6.12). Stable-index order, with the display name resolved as the §20.1
+     * projection resolves it: an endpoint commonly answers its caller in words,
+     * and it has no other route to a team's name.
+     */
+    private teams;
+    /** The ticks every board stands at now, for an endpoint's read (§6.12, 6a). */
+    private boardTicks;
+    /**
+     * Where the session stands, for an endpoint's `session` (§6.12). Status
+     * only: no team's context, so its cost is the team count and not the
+     * size of anybody's board.
+     */
+    private session;
+}
+export {};

package/dist/core/session-gates.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Who stands behind an action, and so whether the validators see it (§15).
+ *
+ * A validator gates a write or a tick request from a surface a participant or
+ * an observer is looking at, and nothing else: the CLI, the session surface,
+ * the engine, a hook and an endpoint are system-trusted. Telling those apart
+ * from a player surface that lost its participant is the whole difficulty
+ * (#566), so the attribution, the refusal of what cannot be attributed, and
+ * the putting of an attributed action to its gate live together here, where
+ * one reading of an actor serves both gates. Running the validators
+ * themselves is the executor's.
+ */
+import type { ValidatorActor } from '@seriousgaming/sdk';
+import type { GameContext } from '../execution/executor';
+import type { ParticipantRecord } from './participant-registry';
+import type { Actor, TeamScope } from './protocol';
+import type { SessionHost } from './session-host';
+type ActorHost = Pick<SessionHost, 'participants' | 'state'>;
+type GateHost = Pick<SessionHost, 'executor' | 'participants' | 'state' | 'mode' | 'positionOf' | 'emit'>;
+/**
+ * The participant behind a write, or `undefined` where there honestly is
+ * none.
+ *
+ * §15.1 gates validators on a write being participant-bearing, and three
+ * callers bear no participant legitimately: the CLI, a session surface,
+ * and an observer (§13.3). Absence on its own cannot say which, so a
+ * player surface whose slot the console had failed to resolve was read as
+ * one more of them, and its writes were applied unvalidated (#566).
+ *
+ * `viewerRole` is what separates them. A surface the host holds as a
+ * participant's, arriving with nobody on it, is a write the session cannot
+ * attribute, and an unattributable write is refused rather than trusted:
+ * the runtime cannot run an actor-aware check without an actor, so the
+ * honest outcome is to refuse rather than to skip.
+ *
+ * §13.2 step 3 is the same refusal reached from the other side, and is
+ * resolved here too. The team is the one the write names, or the one it
+ * would land on when it names none, so a write cannot walk past the check
+ * by omitting the team.
+ */
+export declare function resolveActor(host: ActorHost, command: Actor, position: number): ParticipantRecord | undefined;
+/**
+ * Who a validator is told submitted this write, or `undefined` for a write
+ * no validator sees.
+ *
+ * The test is the surface, not the participant (§15.1). An observer is
+ * rendered the same play surface a participant is, with the same controls
+ * on it, so its writes go to validators on the same terms and the game
+ * decides what an observer may do (§13.3). What stays ungated is a caller
+ * looking at something else: the session surface, the CLI, the engine, a
+ * hook, an endpoint. None of those carries a viewer role.
+ *
+ * The participant record is already the shape a validator wants (§13.1),
+ * so it is passed as it stands rather than rebuilt as a reduced copy.
+ */
+export declare function submitterOf(host: ActorHost, command: Actor, position: number): ValidatorActor | undefined;
+/**
+ * Put a participant's tick request to the validators that gate it (§15).
+ *
+ * Only a request from a surface a participant or observer is looking at
+ * names a participant or a viewer role, so a facilitator's tick, the CLI's
+ * and a timer's pass straight through, exactly as their writes do: pacing is the facilitator's to set, not to be
+ * held to. The validators judge the requesting team's board as it stands,
+ * which is where a gate such as a `MaxOpenWeek` the facilitator writes
+ * lives, and the tick the request would run.
+ */
+export declare function gateTickRequest(host: GateHost, command: TeamScope & Actor): Promise<void>;
+/**
+ * Put a write to the validators it could affect (§15), refusing it when any
+ * of them rejects. Reject-only, and only for a write from a surface a
+ * participant is looking at: an engine, endpoint or system-trusted mutation
+ * has no `submitter` and is not gated.
+ */
+export declare function gateWrite(host: GateHost, before: GameContext, merged: GameContext, submitter: ValidatorActor | undefined, scope: TeamScope): Promise<void>;
+export {};

package/dist/core/session-host.d.ts

@@ -0,0 +1,94 @@
+/**
+ * What a session shows the parts it is built from.
+ *
+ * The session is split by concern (timers, endpoints, validator gates, writes,
+ * the roster, ticks and rewinds), and each part needs some of the session's
+ * state and some of its operations, never all of them. This is the one list
+ * of what may be reached, so each part declares the slice it uses as a `Pick`
+ * of it, and what one part can touch is read off its own signature rather
+ * than off the whole session. The session builds a single object satisfying
+ * it, from its own fields, and hands each part that.
+ */
+import type { Participant, RunKind, TeamInfo } from '@seriousgaming/sdk';
+import type { MutationResult, SessionMode } from '@seriousgaming/sdk/projection';
+import type { GameContext, GameExecutor } from '../execution/executor';
+import type { BlobRetention } from '../storage/blob-store';
+import type { Clock } from './clock';
+import type { FaultInjector } from './faults';
+import type { ResolvedGameSettings } from './game-settings';
+import type { ParticipantRegistry } from './participant-registry';
+import type { PendingChanges } from './pending-changes';
+import type { Event, MutationCommand } from './protocol';
+import type { ParticipantCounts } from './session-roster';
+import type { SurfaceBundle } from './session-surfaces';
+import type { SessionTimers } from './session-timers';
+import type { TeamStateStore } from './team-state-store';
+/** A team-count range as a game declares it, either end optional (§5.4). */
+export interface TeamBounds {
+    min?: number;
+    max?: number;
+}
+export interface SessionHost {
+    readonly executor: GameExecutor;
+    readonly state: TeamStateStore;
+    readonly participants: ParticipantRegistry;
+    readonly faults: FaultInjector;
+    readonly clock: Clock;
+    /** Which kind of run this is (§5.7), fixed for the session's life. */
+    readonly runKind: RunKind;
+    /** The automatic tick timers (§11), which ticks and rewinds re-evaluate. */
+    timers(): SessionTimers;
+    /** The teams and seeds the session was asked to start with. */
+    startingShape(): {
+        teams?: number;
+        participants?: ParticipantCounts;
+    };
+    locale(): string;
+    waitingRoomOpen(): boolean;
+    /** True while the game's `setup` slot still owes a Play (§8.3). */
+    inSetup(): boolean;
+    /** Edits on disk the session has not applied, as a copy (#640). */
+    pendingChanges(): PendingChanges;
+    mode(): SessionMode;
+    /** The `game` settings as they resolve now, through every layer (§6.10, §8.2). */
+    settings(): ResolvedGameSettings;
+    /**
+     * What a call from the scenario editor resolves against (§6.5, §6.12):
+     * the scenario it is editing, and its draft over that scenario's
+     * settings, the `game` settings included. Absent names the one in force.
+     */
+    scenarioBeingEdited(scenarioId: string | null | undefined): {
+        settings: Record<string, Record<string, unknown>>;
+    };
+    teamBounds(): TeamBounds;
+    tickLimit(): number | null;
+    /** Whether any tick has been committed and not since rewound. */
+    hasTicked(): boolean;
+    /** The position of a stable team index, or a refusal when it names no team. */
+    positionOf(teamIndex: number): number;
+    /** The stable index behind a team id, or undefined when it names no team. */
+    indexOfTeamId(teamId: string): number | undefined;
+    /** A team's display name as it reads now, a rename included (§5.4). */
+    teamNameAt(index: number): string;
+    /** The team at a position, as an endpoint is told it (§6.12). */
+    teamAt(position: number): TeamInfo;
+    /** Every participant, in stable-index order and then join order. */
+    roster(): Participant[];
+    declaredSurface(identifier: string): SurfaceBundle;
+    /** Build tick-0 state for every team, and seed the histories. */
+    buildInitialState(preserveShared?: GameContext): Promise<void>;
+    /** §14.4: re-fire `participantJoin` for everyone after a rebuild. */
+    replayParticipantJoins(): Promise<void>;
+    /** Start over from the package as it is on disk (#640). */
+    applyPendingChanges(): Promise<number>;
+    /** Delete this run's blobs of the given retentions (§16.2). */
+    clearBlobs(retentions: readonly BlobRetention[]): Promise<void>;
+    /** Queue `work` as one operation (§9.7, §10.2). */
+    enqueue<T>(work: () => Promise<T>): Promise<T>;
+    /** Run one command now, inside whatever job is already running. */
+    apply(command: MutationCommand): Promise<MutationResult>;
+    submit(command: MutationCommand): Promise<MutationResult>;
+    report(message: string, source: string, teamId?: string): void;
+    emit(event: Event): void;
+    emitState(cause: string): void;
+}

package/dist/core/session-refusals.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The ways a session operation says no, and how each reaches the caller.
+ *
+ * A refusal is an answer rather than a crash: nothing reached the session's
+ * state, and the outcome is the one every surface is told (§12.5.1). Two
+ * kinds carry more beside it for the author's tools, where game logic threw
+ * (#639) and which edits on disk refused it (#640), and they ride beside the
+ * outcome rather than in it so a surface sees the same shape either way.
+ * Shared by every part of the session that refuses, so that one refusal reads
+ * the same whichever operation raised it.
+ */
+import type { MutationResult } from '@seriousgaming/sdk/projection';
+import { type LogicFailure } from '../execution/logic-failure';
+import type { FaultInjector, FaultKind } from './faults';
+import { type PendingChanges } from './pending-changes';
+/** The failure half of a settled mutation (§12.5.1). */
+export type Refusal = Extract<MutationResult, {
+    ok: false;
+}>['outcome'];
+/**
+ * A failed result carrying where game logic threw, when it did (#639). Beside
+ * the outcome rather than in it: the outcome is what every surface is told,
+ * and a source path is for the author's tools alone.
+ */
+export type WithLogicError<T> = T & {
+    logicError?: LogicFailure;
+};
+export declare function withLogicError<T extends object>(result: T, logicError: LogicFailure | undefined): WithLogicError<T>;
+/** Nothing reached the session's own state; the caller sees why. */
+export declare class RefusedError extends Error {
+    readonly outcome: Refusal;
+    constructor(message: string, outcome: Refusal);
+}
+/**
+ * A failed result carrying the edits on disk that refused it (#640). Beside
+ * the outcome for the same reason as {@link WithLogicError}: a surface is told
+ * it was denied, and the author's tools are told why in a form they can act on.
+ */
+export type WithStale<T> = T & {
+    stale?: PendingChanges;
+};
+/** Refused because an edit on disk is pending, and running it would mix the two. */
+export declare class StaleError extends RefusedError {
+    readonly pending: PendingChanges;
+    constructor(pending: PendingChanges);
+}
+export declare function withStale<T extends object>(result: T, error: unknown): WithStale<T>;
+/** `error`, marked as thrown by game logic when `failure` says it was. */
+export declare function markIfLogic(error: Error, failure: LogicFailure | undefined): unknown;
+/**
+ * Fire an armed fault as the refusal it stands in for (§3.3 of the design).
+ *
+ * The point is that the surface takes the same path it would on the real
+ * thing, so the outcome has to be the real outcome rather than a marker.
+ */
+export declare function refuseIfArmed(faults: FaultInjector, fault: FaultKind, outcome: Refusal): void;

package/dist/core/session-rewind.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Undo and reset (§9.4, §19.3): putting a team, or the whole session, back
+ * where it was.
+ *
+ * A rewind restores boards from history, and history holds whole boards, so
+ * left alone it would also restore what a rewind must never touch: the shared
+ * store other teams still read, and every capability declared
+ * `lifetime: 'session'` (§7.6). The rules for what a per-team rewind may
+ * reach, when one is refused outright because the cohort moves as one, and
+ * how session-lifetime values are carried across, sit here together so that
+ * undo and reset cannot come to disagree about them.
+ */
+import type { TeamScope } from './protocol';
+import type { SessionHost } from './session-host';
+type RewindHost = Pick<SessionHost, 'executor' | 'state' | 'mode' | 'positionOf' | 'pendingChanges' | 'applyPendingChanges' | 'buildInitialState' | 'replayParticipantJoins' | 'clearBlobs'>;
+/**
+ * Run an undo or a reset without letting it touch any `lifetime:
+ * 'session'` capability (§7.6).
+ *
+ * Those values ride the team contexts and the shared store like any other,
+ * so a restored snapshot or a rebuilt initial board would carry them back
+ * to what they were. Capturing them first and putting them back after is
+ * what keeps them out of the tick's reach: facilitator state such as
+ * 'setup completed' survives the rewind that would otherwise wipe it.
+ * A refused operation changed nothing, so there is nothing to put back.
+ */
+export declare function keepingSessionLifetime(host: Pick<SessionHost, 'executor' | 'state'>, run: () => Promise<number>): Promise<number>;
+/** Step back one round, for one team or the session (§9.4). Returns the tick it lands on. */
+export declare function undo(host: RewindHost, scope: TeamScope): Promise<number>;
+/** Return a team, or the session, to tick 0 (§9.4). */
+export declare function reset(host: RewindHost, scope: TeamScope): Promise<number>;
+export {};

package/dist/core/session-roster.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Who is in the session: its teams, the participants on them, and the hooks
+ * their arrivals and moves fire (§5.4, §5.6, §13, §14).
+ *
+ * The roster is declarative in a local session rather than the residue of a
+ * join flow, because a player surface is addressed directly and somebody has
+ * to exist for it to be. So the team count and seed counts are resolved here
+ * against the game's bounds, every team is filled to its seats, and the same
+ * rules decide when a team may be added or removed mid-session. Participant
+ * signals fire from here too, always after the change they describe, since
+ * every one of them is a consequence of a roster change and nothing else.
+ */
+import type { Participant } from '@seriousgaming/sdk';
+import type { ResolvedGameSettings } from './game-settings';
+import type { ParticipantRecord } from './participant-registry';
+import type { MutationCommand } from './protocol';
+import type { SessionHost, TeamBounds } from './session-host';
+/**
+ * How many participants to seed each team with: one count for every team, or
+ * one per team in stable index order.
+ */
+export type ParticipantCounts = number | number[];
+/**
+ * Why a participant count cannot seed `teams` teams, or null when it can.
+ *
+ * Zero is a count, not an error: every team is under-full at the start of a
+ * session by definition (§5.4), and in a hosted session every team starts
+ * empty and fills as people join.
+ */
+export declare function participantCountsError(counts: ParticipantCounts, teams: number): string | null;
+export declare function boundsOf({ teams }: ResolvedGameSettings): TeamBounds;
+export declare function refuseTeamCountOutsideBounds(count: number, { min, max }: TeamBounds): void;
+/**
+ * Refuse to start play with a team count outside the bounds the settings
+ * resolved to (§5.4). Setup can move them after the teams were created, so
+ * this is checked again as play starts, and the facilitator adds or removes
+ * teams, or changes the setting, before trying again.
+ */
+export declare function refuseTeamCountAtPlay(count: number, { min, max }: TeamBounds): void;
+type RosterHost = Pick<SessionHost, 'executor' | 'state' | 'participants' | 'faults' | 'runKind' | 'startingShape' | 'mode' | 'hasTicked' | 'teamBounds' | 'settings' | 'positionOf' | 'buildInitialState' | 'report'>;
+export declare class SessionRoster {
+    private readonly host;
+    /** Seed counts chosen for one team, by stable index, over the session-wide one. */
+    private readonly seats;
+    constructor(host: RosterHost);
+    /** Every participant, in stable-index order and then join order. */
+    list(): Participant[];
+    /** Every participant's record, in stable-index order and then join order. */
+    records(): ParticipantRecord[];
+    /**
+     * Mark exactly these participants connected, and every other one not
+     * (§13.2). True when anybody's presence changed.
+     */
+    syncPresence(connected: ReadonlySet<string>): boolean;
+    /** Settle the team count and seed counts the session starts with (§5.4, §5.7). */
+    resolveTeamCount(): void;
+    /**
+     * Give every team the participants it is declared to have.
+     *
+     * The roster is declarative here, not the residue of a join flow: a player
+     * surface is addressed directly (`/team/2/player/1`) rather than joined, so
+     * somebody has to exist for it to be. A surface with no participant never
+     * receives `setParticipant`, which is one of the six messages a player
+     * surface blocks its first paint on (§12.6), so it sits on its loading
+     * state forever.
+     *
+     * Seeded to {@link seatsFor}, which may be none: a test of what a game does
+     * before anybody joins needs a team with nobody on it.
+     */
+    materialise(): Promise<void>;
+    /**
+     * §14.4: `participantJoin` re-fires for every registered participant
+     * whenever context is rebuilt, so a hook's contribution is not lost to a
+     * reset.
+     */
+    replayJoins(): Promise<void>;
+    /**
+     * §5.6. An independent team joins the session as it stands; a shared-state
+     * cohort cannot be enlarged, because `InitAggregate` ran over the teams
+     * present at initialisation and a late arrival's per-team state and share
+     * of the store cannot be retrofitted.
+     *
+     * An authoring host may relax that before the first tick by re-initialising,
+     * so the aggregate observes the enlarged cohort, and this is an authoring
+     * host. The relaxation is not part of the runtime contract: a production
+     * runtime refuses throughout, and the conformance suite asserts the refusal
+     * after a tick, where every reading agrees.
+     *
+     * 'Before the first tick' is read off the clock rather than latched, so a
+     * session returned to tick 0 by a reset can still be enlarged. The price is
+     * the same either way: re-initialisation rebuilds every team's context from
+     * `Init`, so anything written into the board beforehand goes with it. The
+     * configuration does not — it is an input to `Init`, not state.
+     */
+    addTeam(name?: string, participants?: number): Promise<undefined>;
+    /**
+     * §5.6. Independent mode only: a shared-state engine initialised over the
+     * whole cohort, so a team leaving it cannot be retrofitted, before the
+     * first tick or after. And only an empty team: participant records are
+     * permanent (§13.2), so a team holding one, connected or not, would leave
+     * it pointing at nothing.
+     */
+    removeTeam(teamIndex: number): Promise<undefined>;
+    renameTeam(teamId: string, name: string): undefined;
+    renameOwnTeam(command: Extract<MutationCommand, {
+        type: 'renameOwnTeam';
+    }>): undefined;
+    addParticipant(teamId: string, name?: string): Promise<undefined>;
+    renameParticipant(participantId: string, name: string): undefined;
+    moveParticipant(participantId: string, toTeamId: string): Promise<undefined>;
+    findParticipantTeam(participantId: string): string | undefined;
+    /**
+     * How many participants a team is seeded with.
+     *
+     * At least one unless somebody asked otherwise, and the game's declared
+     * `perTeam.minParticipants` where it has one, because that is the cohort
+     * the author designed for.
+     */
+    private seatsFor;
+    /**
+     * Run `signal`'s hooks against a team's context: the participant's own
+     * team unless `dispatch.teamId` names another, with any signal-specific
+     * fields in `dispatch.payload` handed to the hook beside the participant.
+     */
+    private fireHook;
+    private hasHook;
+}
+export {};

package/dist/core/session-surfaces.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The surfaces a package declares, as the session looks them up (§12).
+ *
+ * A surface's identifier arrives from the host, which names what it mounted,
+ * and every check the session makes against a surface (what it may read back,
+ * what it may write, which endpoints it may call) starts by finding its bundle.
+ * One lookup over every `kind: 'ui'` resource, so a new surface kind is found
+ * without being listed here by hand, and one refusal for an identifier the
+ * package does not declare, so no check can treat it as a lesser surface.
+ */
+import type { ResolvedPackageManifest } from '@seriousgaming/sdk';
+export type SurfaceBundle = NonNullable<ResolvedPackageManifest['ui' | 'session' | 'waiting_room' | 'presentation' | 'setup' | 'scenario_editor']>;
+/**
+ * The UI bundle this package declares under `identifier`, of any kind.
+ *
+ * Every `kind: 'ui'` resource is searched, so a new surface kind is found
+ * without being added here by hand: one left out would be refused as a
+ * surface the package does not declare.
+ */
+export declare function userInterfaceBundle(config: ResolvedPackageManifest | null, identifier: string): SurfaceBundle | undefined;
+/**
+ * The surface a caller names, or a refusal. An identifier is the host's to
+ * supply from what it mounted, so one the package does not declare is not
+ * a lesser surface: nothing it may be held to exists, and it is refused.
+ */
+export declare function declaredSurface(config: ResolvedPackageManifest | null, identifier: string): SurfaceBundle;
+/**
+ * What a surface may read back: its declared reads and writes, less any
+ * private capability (§7.4). `undefined` for a caller that names no UI,
+ * which is system-trusted and unbounded.
+ */
+export declare function readableCapabilities(config: ResolvedPackageManifest | null, uiIdentifier: string | undefined): Set<string> | undefined;