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

package/dist/core/team-state-store.d.ts

@@ -0,0 +1,218 @@
+/**
+ * TeamStateStore - single owner of the dev server's per-session team state.
+ *
+ * The dev server juggles seven interdependent structures: the session tick, the
+ * per-team contexts, per-team tick counters, per-team stable indexes, per-team
+ * undo histories, the session-wide undo history, and the executor's own context.
+ * The load-bearing invariant is that the executor's context always mirrors team
+ * 0 (`executor.context === teamContexts[0]`); before this class that was
+ * hand-maintained at half a dozen call sites, and the stable-index↔array-position
+ * translation existed in as many variants.
+ *
+ * Everything the dev server needs to read or mutate that state now goes through
+ * one object. Mutators that touch team contexts keep the executor in step
+ * internally, and {@link withTeamContext} encapsulates the swap-run-restore
+ * dance a per-team operation performs, so callers never re-sync by hand.
+ */
+import type { PastStateEntry } from '@seriousgaming/sdk';
+import type { GameContext } from '../execution/types';
+import { HistoryManager, type ContextSnapshot } from './history';
+/** One team's committed state at a single past tick, before display names. */
+interface PastTickView {
+    tick: number;
+    context: Record<string, unknown>;
+    recordedAt: number;
+    complete: boolean;
+}
+/**
+ * The slice of the executor the store keeps in lockstep with team 0. The real
+ * {@link GameExecutor} satisfies it; tests can supply a stub.
+ */
+export interface ExecutorContextSync {
+    getContext(): GameContext;
+    setContext(context: GameContext): void;
+    /** Capabilities kept out of the tick's history (§7.6); none when absent. */
+    getSessionLifetimeCapabilityIds?(): string[];
+    /**
+     * Defaults of capabilities added while the session ran, composed under
+     * every board that lacks them; none when absent.
+     */
+    getAddedCapabilityDefaults?(): Map<string, Record<string, unknown>>;
+}
+export declare class TeamStateStore {
+    private readonly executor;
+    private currentTick;
+    private teamCount;
+    private independentMode;
+    private teamContexts;
+    private teamTicks;
+    /**
+     * Whether each team's tick controller has signalled completion. Completion
+     * is per-team because independent teams keep their own tick controller
+     * state (SPECIFICATION.md §9.4a); a lockstep or single-team session simply
+     * moves every entry together, so the session-wide notion collapses to
+     * {@link isSessionComplete}.
+     */
+    private teamComplete;
+    /**
+     * Stable team index for each array position, kept sorted ascending so every
+     * surfaced teams array is ordered by index. Indexes are assigned at team
+     * creation and never reassigned: a removal leaves a gap in the sequence, a
+     * later add takes the lowest unused index. Team ids are `team-${index + 1}`
+     * and never renumber.
+     */
+    private teamIndexes;
+    private teamHistories;
+    private readonly sessionHistory;
+    constructor(executor: ExecutorContextSync);
+    getCurrentTick(): number;
+    setCurrentTick(tick: number): void;
+    getTeamCount(): number;
+    setTeamCount(count: number): void;
+    getIsIndependentMode(): boolean;
+    setIsIndependentMode(independent: boolean): void;
+    /** The live team-context array. Callers treat it as read-only. */
+    getTeamContexts(): GameContext[];
+    /**
+     * Replace every team context, keeping the executor in step with team 0.
+     *
+     * The one place a board is built, so it is where a capability added while
+     * the session ran is seeded: every write, undo and reset reaches the
+     * boards through here, including an undo to a snapshot recorded before
+     * the capability existed (#640).
+     */
+    setTeamContexts(contexts: GameContext[]): void;
+    /** Replace a single team's context, keeping the executor in step. */
+    setTeamContext(position: number, context: GameContext): void;
+    /**
+     * Run a per-team operation with the executor's context swapped to the team
+     * at `position`, write the result back, then restore the executor to team
+     * 0. This is the one place the swap-run-restore dance lives, so a per-team
+     * tick or hook dispatch never leaks a non-team-0 context into the executor.
+     */
+    withTeamContext(position: number, run: () => Promise<GameContext>): Promise<GameContext>;
+    /**
+     * Run a read-only per-team operation with the executor swapped to the team
+     * at `position`, then restore team 0. Unlike {@link withTeamContext} the
+     * result is not a context, so nothing is written back. Used to evaluate a
+     * team's tick controller against that team's own state.
+     */
+    readWithTeamContext<T>(position: number, run: () => Promise<T>): Promise<T>;
+    private withoutSessionLifetime;
+    private syncExecutorToTeamZero;
+    getTeamTicks(): number[];
+    setTeamTick(position: number, tick: number): void;
+    setTeamTicks(ticks: number[]): void;
+    /** The furthest-advanced team tick, or 0 when there are no teams. */
+    maxTeamTick(): number;
+    getTeamComplete(): boolean[];
+    setTeamComplete(position: number, complete: boolean): void;
+    setTeamCompletes(flags: boolean[]): void;
+    /** Whether the team at array position `position` has completed. */
+    isTeamComplete(position: number): boolean;
+    /** Move every team's flag together: a lockstep or single-team completion. */
+    setAllTeamsComplete(complete: boolean): void;
+    /**
+     * Whether the whole session is done, which is true only once every team
+     * is. A game that is complete for one team of several is not complete: the
+     * others still tick.
+     */
+    isSessionComplete(): boolean;
+    /**
+     * Whether each team can tick no more, which is what `complete` reports
+     * (§9.0, §20.1): it signalled completion (§11.1) or played the tick limit
+     * (§9.6). The stored flags stay the signal alone, because undo and past
+     * state read the signal, not the limit.
+     */
+    teamsFinished(limit: number | null): boolean[];
+    /** Whether no team can tick again: every team is finished. */
+    isSessionFinished(limit: number | null): boolean;
+    getTeamIndexes(): number[];
+    setTeamIndexes(indexes: number[]): void;
+    /** Stable index for the team at array position `position`. */
+    teamIndexAt(position: number): number;
+    /** Team id for the team at array position `position`. */
+    teamIdAt(position: number): string;
+    /** Array position of the team with stable index `index`, or -1. */
+    positionOf(index: number): number;
+    /** The lowest stable index not currently in use (refills removal gaps). */
+    lowestUnusedTeamIndex(): number;
+    /**
+     * The stable indexes, falling back to array position when the index array
+     * is out of step with the team count (older snapshots, pre-init state).
+     */
+    resolvedTeamIndexes(): number[];
+    /** The session-wide undo history, which a shared-state undo rewinds. */
+    getSessionHistory(): HistoryManager;
+    getTeamHistory(position: number): HistoryManager;
+    getTeamHistories(): HistoryManager[];
+    setTeamHistories(histories: HistoryManager[]): void;
+    /** Undoable state of each team's history, in position order. */
+    teamCanUndo(): boolean[];
+    /**
+     * Push a session-history snapshot. Stamps the current stable indexes
+     * alongside team contexts so a later restore can map positions back.
+     */
+    historyPush(context: GameContext, tick: number, teamContexts?: GameContext[]): void;
+    historyUndo(): ContextSnapshot | null;
+    historyClear(): void;
+    /**
+     * Record the round every team just closed into its own history.
+     *
+     * Takes the pre-`Run` contexts rather than reading live state, because by
+     * the time a lockstep tick calls this the store already holds the engine's
+     * result: the boards to record are the ones the tick was handed.
+     *
+     * Every team or none. A session-history push that grows only some team
+     * histories breaks the lockstep a session-wide undo relies on, since that
+     * undoes every team once (#285).
+     */
+    pushAllTeamHistories(contexts: GameContext[], tick: number): void;
+    /** Step every team's history back one round, for a session-wide undo. */
+    undoAllTeamHistories(): void;
+    /**
+     * Compose a committed past tick's team view, the basis every `getPastState`
+     * row is built from (§19.2). Reads snapshot history only, never live state,
+     * and returns `null` for every tick that is not a reviewable closed round so
+     * the callback's null rule collapses to one place:
+     *
+     * - a negative, non-integer, or out-of-range tick;
+     * - a tick the team has not reached, its current head included: a team at
+     *   tick `N` recorded rounds up to `N - 1` and holds the rest live;
+     * - an undone or reset tick, which the history's cursor excludes;
+     * - an unknown or removed `teamIndex`, at any team count.
+     *
+     * The snapshot's own `context` already carries the shared store as it stood
+     * at that tick (facilitator shared writes land in the team contexts as they
+     * are made, and a snapshot is taken at the close of the round), so the
+     * point-in-time view needs no re-composition with the current store.
+     */
+    pastTickView(tick: number, teamIndex?: number): PastTickView | null;
+    /**
+     * Compose committed past state for the UI `getPastState` callback: one row
+     * per (tick, team) the query reaches, ascending by tick then by team index.
+     *
+     * Built on {@link pastTickView} per tick per team rather than by walking
+     * the snapshot array, so every null rule the single reader encodes — not
+     * yet reached, undone, reset, out of range — is inherited here rather than
+     * reimplemented. Teams in an independent session are at different ticks,
+     * which is reason enough: one range is a different set of rounds per team.
+     *
+     * Unreachable (tick, team) pairs are omitted rather than collapsing the
+     * call, so the result is dense and an empty array means the query reaches
+     * nothing reviewable. `toTick` is effectively clamped to the last
+     * reviewable tick, because anything a team has not closed is skipped.
+     *
+     * Each entry carries the team's `index` and its display name as it reads
+     * now, from `nameOf`: the store holds no names, which are the session's
+     * (a rename included). `teamIndexes` is already resolved by the caller,
+     * which is the only layer that knows whether the asking surface has an own
+     * team.
+     */
+    getPastStateView(range: {
+        fromTick: number;
+        toTick?: number;
+        capabilityIds?: string[];
+    }, teamIndexes: number[], nameOf: (index: number) => string): PastStateEntry[];
+}
+export {};

package/dist/core/tick-timer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * One automatic tick schedule (§11.2–§11.4).
+ *
+ * A session holds one per team in independent mode and one for the cohort
+ * otherwise. Everything here is bookkeeping over a {@link Clock}: the session
+ * decides when to ask the tick controller, and this decides when that answer
+ * says the next tick is due.
+ */
+import type { TickControllerResult, TimerState } from '@seriousgaming/sdk';
+import type { Clock } from './clock';
+export declare const IDLE_TIMER: TimerState;
+/** When a result says the next tick is due, and whether that had to be clamped. */
+export interface Schedule {
+    delayMs: number;
+    /** The display interval: the result's own when valid, the clamped one otherwise. */
+    intervalMs: number;
+    usedNextTickAt: boolean;
+    /** Why the result could not be honoured as returned, or null. */
+    clamped: string | null;
+}
+/**
+ * Where a tick controller result puts the next tick (§11.2, §11.8, §11.9).
+ *
+ * An out-of-range or malformed result is clamped to the nearest bound and the
+ * reason returned, never honoured and never turned into a disabled timer. A
+ * `nextTickAt` already past is due now, which the floor does not apply to
+ * (§11.3).
+ */
+export declare function scheduleFor(result: TickControllerResult, now: number): Schedule;
+export type ResumeOutcome = 'resumed' | 're-evaluate' | 'idle';
+export declare class TickTimer {
+    private readonly clock;
+    private readonly fire;
+    private pending;
+    private dueAt;
+    private intervalMs;
+    private enabled;
+    private paused;
+    private usedNextTickAt;
+    private pausedAt;
+    private remainingMs;
+    private pausedMs;
+    private scheduleStartedAt;
+    private extendedMs;
+    /** The answer the current schedule was built from, to tell a re-evaluation that changed nothing. */
+    private answer;
+    constructor(clock: Clock, fire: () => void);
+    /**
+     * Apply a tick controller's answer (§11.1). A disabled timer, a completed
+     * game or a spent tick limit schedules nothing. Returns the clamp reason
+     * when the result had to be clamped, for the caller to report.
+     *
+     * A re-evaluation (§11.1a) that returns the answer the schedule was built
+     * from keeps that schedule, extension and paused remainder included;
+     * only a tick, or a different answer, starts a new window.
+     */
+    apply(result: TickControllerResult | null, canTick: boolean, reevaluation?: boolean): string | null;
+    pause(): void;
+    /**
+     * Resume (§11.4). Interval mode continues from the time that was left;
+     * scheduled mode tells the caller to re-evaluate, because the target may
+     * have passed during the pause and the missed tick is not fired.
+     */
+    resume(): ResumeOutcome;
+    /**
+     * Move the scheduled tick by `ms` (§12.5): only this window, clamped at
+     * now, and never bounded by §11.8. Returns why it was refused, or null.
+     */
+    extend(ms: number): string | null;
+    /** Stop everything, as when the team is removed or the session stops. */
+    cancel(): void;
+    state(): TimerState;
+    private arm;
+    private cancelPending;
+}

package/dist/dev/blob-links.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Every `blob:` reference in an endpoint's response, resolved to a URL (§6.12).
+ *
+ * A game surface turns a reference into something it can fetch with
+ * `getAssetUrl`. A caller outside the game has no such callback, so a report an
+ * endpoint wrote with `writeBlob` reached it as an id it could do nothing with.
+ * The transport answering the call is the one that knows where blobs are
+ * served, so it resolves them here rather than in the session.
+ */
+export declare function blobLinks(response: unknown, urlFor: (blobId: string) => string): Record<string, string>;