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

package/dist/execution/blob-inputs.d.ts

@@ -0,0 +1,57 @@
+/**
+ * File-valued request fields (§6.12, 'File inputs').
+ *
+ * A request schema marks a string property as a file with the `blob` keyword:
+ *
+ *     "photo": { "type": "string", "blob": { "accept": ["image/*"], "maxBytes": 2097152 } }
+ *
+ * On the wire the field is a URI string, which is what lets one declaration
+ * serve every caller: a surface that has already uploaded sends the `blob:`
+ * reference `uploadBlob` gave it, and a caller with no upload of its own (a
+ * script, or an agent whose host cannot upload out of band) sends the bytes
+ * inline as an RFC 2397 `data:` URI. The handler only ever receives `blob:`,
+ * checked against the declaration, so it never parses base64 or wonders
+ * whether the caller told the truth about the type.
+ *
+ * The shape is the one MCP's file-upload proposals settle on (`x-mcp-file`
+ * over URI strings), so a platform exposing an endpoint as an MCP tool can
+ * translate the keyword rather than invent a second model.
+ */
+import type { JSONSchema7 } from 'json-schema';
+export interface BlobFieldSpec {
+    /** Media types, `type/*` wildcards allowed. Absent means any. */
+    accept?: string[];
+    maxBytes?: number;
+}
+/** What the resolver needs from a blob store. */
+export interface BlobInputStore {
+    /** The stored blob's type and size, or undefined when there is none. */
+    describe(id: string): Promise<{
+        mimeType: string;
+        size: number;
+    } | undefined>;
+    store(data: Uint8Array, name: string, mimeType: string): Promise<string>;
+}
+/**
+ * Bytes a `data:` URI may carry inline, whatever a field allows. Inline bytes
+ * cross the request as base64, and a model writing them spends its context
+ * doing it: past this, a caller uploads first and sends the reference.
+ */
+export declare const MAX_INLINE_BYTES: number;
+/**
+ * The type the bytes say they are, for the handful of formats a game commonly
+ * takes, or undefined for anything else. A caller's claimed type is checked
+ * against this rather than trusted: an endpoint told it has a PNG will hand it
+ * to a surface as one.
+ */
+export declare function sniffMimeType(data: Uint8Array): string | undefined;
+/**
+ * The request with every file field resolved to a checked `blob:` reference.
+ * Throws, naming the field, when a value is neither kind of URI, names a blob
+ * the store does not hold, or breaks the declaration's type or size.
+ *
+ * A `data:` URI is stored before the handler runs, so a call refused later,
+ * by the schema or by the handler, leaves its upload behind. That is the same
+ * as a surface that uploads and then never submits, and retention clears both.
+ */
+export declare function resolveBlobInputs(identifier: string, schema: JSONSchema7 | undefined, request: unknown, store: BlobInputStore): Promise<unknown>;

package/dist/execution/bundle-reload.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What a package edited while its session runs may change live, and what has
+ * to wait for the session to initialise again (#640).
+ *
+ * A running session reloads the package's bundles and adopts what it can: new
+ * logic, surfaces, endpoints and the game's locale names. What it
+ * cannot adopt is anything `Init` or session creation already acted on, since
+ * applying that mid-session produces a state no real session can reach: a
+ * setting `Init` read keeps its old effect while the next tick reads the new
+ * value. Those parts are kept as the session started with them and reported,
+ * so the session runs on one consistent package and says that the one on disk
+ * differs.
+ */
+import type { ResolvedPackageManifest } from '@seriousgaming/sdk';
+import type { PendingChanges } from '@seriousgaming/sdk/projection';
+/** What one reload of the bundles did. */
+export interface BundleReload {
+    /** Changes on disk the session applies only when it next initialises. */
+    pending: PendingChanges;
+    /** Capabilities adopted live and seeded with their schema defaults. */
+    added: string[];
+}
+/** A reloaded package with its init-only parts held as they were. */
+export interface PinnedReload {
+    config: ResolvedPackageManifest;
+    /** Manifest fields that differ on disk and apply at the next init. */
+    manifest: string[];
+    /** Capabilities removed on disk, or whose scope changed. */
+    capabilities: string[];
+}
+/**
+ * `reloaded`, with everything a session cannot change mid-flight taken from
+ * `previous`, and a note of each part that differs.
+ */
+export declare function pinInitOnly(previous: ResolvedPackageManifest, reloaded: ResolvedPackageManifest): PinnedReload;
+/**
+ * The settings resources whose resolved values differ between two
+ * resolutions, including one present in only one of them.
+ */
+export declare function changedSettings(before: Record<string, unknown>, after: Record<string, unknown>): string[];
+/** `config`, with the settings resources and scenarios of `from`. */
+export declare function withSettingsOf(config: ResolvedPackageManifest, from: ResolvedPackageManifest): ResolvedPackageManifest;

package/dist/execution/config-resolver.d.ts

@@ -0,0 +1,127 @@
+/**
+ * ConfigResolver - owns the runtime's settings layering and persistence.
+ *
+ * Every settings resource is resolved the same way, through the §8.2 layers in
+ * order: its schema defaults, the active scenario's overrides, then the session
+ * overrides. Every layer contributes and none replaces. This class owns the
+ * session-override layer, that layering, its disk persistence, scenario
+ * resolution, and the pre-flight validation of the partial-override sources.
+ *
+ * It reads the executor's live `game` / `config` / `activeScenario` through
+ * injected accessors, so it always sees current state without owning it.
+ */
+import type { ResolvedPackageManifest, SDKGame, SDKScenario } from '@seriousgaming/sdk';
+import type { ResolvedSettings } from './configuration-builder';
+import type { SessionSettingsOverrides, ExecutorDependencies } from './types';
+/** The layered-config state the resolver needs from the executor. */
+export interface ConfigResolverContext {
+    packagePath: string;
+    inMemory: boolean;
+    deps: Pick<ExecutorDependencies, 'loadConfig' | 'fs' | 'configStore'>;
+    getGame: () => SDKGame | null;
+    getConfig: () => ResolvedPackageManifest | null;
+    getActiveScenario: () => SDKScenario | null;
+}
+export declare class ConfigResolver {
+    private readonly ctx;
+    private sessionOverrides;
+    constructor(ctx: ConfigResolverContext);
+    hasSessionOverrides(): boolean;
+    /**
+     * 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;
+    /** Drop the cached session-override layer so the next load rebuilds it. */
+    clearSessionOverrides(): void;
+    /**
+     * Start the session-override layer for an in-memory session.
+     *
+     * Empty, because nobody has overridden anything yet (§8.2). The resolved
+     * values a surface needs come from {@link resolveConfiguration}, which
+     * re-layers on demand; storing them here instead would freeze the layers
+     * beneath and make the active scenario unchangeable.
+     */
+    regenerateInMemoryConfiguration(): void;
+    /**
+     * Resolve the active scenario from a provided ID or the game's default.
+     * Returns null if the game declares no scenarios, or when null is passed
+     * to explicitly opt out of the default scenario (the settings defaults).
+     */
+    resolveScenario(scenarioId?: string | null): SDKScenario | null;
+    /**
+     * Reject undeclared keys in the given scenario's overrides, validating them
+     * against each settings resource's `settingsSchema` exactly as
+     * `configuration.json` is validated on load.
+     *
+     * Mutates nothing and reads no disk, so dev-server boundaries (file-watch
+     * reload, scenario switch) can call it before committing and keep the
+     * last-good session running when it throws. Throws with the offending keys
+     * named and remediation guidance when invalid.
+     */
+    assertLayeredSettingsValid(scenario: SDKScenario | null): void;
+    /**
+     * Resolve every settings resource through the §8.2 layers, in order: its
+     * schema defaults, then the active scenario's overrides, then the session
+     * overrides.
+     *
+     * Every layer contributes and none replaces. The session layer used to
+     * short-circuit the others, which worked only because it was a generated
+     * snapshot containing them all; the moment it held what a facilitator
+     * actually changed, everything they had not touched went missing (§8.2).
+     *
+     * Without the session layer, it is what a surface shown outside the
+     * session reads, such as a presentation with no session (§6.15.1).
+     */
+    resolveSettings({ sessionLayer }?: {
+        sessionLayer?: boolean;
+    }): Record<string, Record<string, unknown>>;
+    /**
+     * The same layering over any scenario and any top layer, touching neither
+     * the active scenario nor the session's own layer. What the scenario
+     * editor's draft resolves through (§6.5): the scenario being edited, then
+     * the editor's unsaved edits.
+     */
+    resolveLayers(scenario: SDKScenario | null, overrides: SessionSettingsOverrides | null): Record<string, Record<string, unknown>>;
+    /**
+     * The settings a resource receives: exactly the ones it lists in
+     * `settings`, keyed by identifier (§8). A resource that lists none
+     * receives none, on the same terms as an undeclared capability (§7.4).
+     */
+    settingsFor(declaration: {
+        settings?: string[];
+    }): Record<string, Record<string, unknown>>;
+    /**
+     * Load session-override layer from disk.
+     * @param reconfigure - If true, regenerate an invalid configuration rather
+     * than throwing. Reserved for a caller that knows the file is disposable.
+     */
+    loadSessionSettingsOverrides(reconfigure?: boolean): Promise<void>;
+    /**
+     * The settings with the session-override layer ignored: defaults and the
+     * active scenario alone. Used by the dev server's 'Reset configuration'
+     * action so the operator can return to a clean slate without restarting.
+     */
+    buildResetConfiguration(): ResolvedSettings;
+    /**
+     * Every settings resource's resolved values, right now: what a settings
+     * editor is seeded with (§8.3), what a save-as-scenario flow
+     * bakes in, and what an operator surface displays. Recomputed on demand
+     * precisely so a scenario change is reflected in it.
+     */
+    resolveConfiguration(): ResolvedSettings;
+    /**
+     * Establish the session-override layer for a fresh session (§8.2).
+     *
+     * It starts empty and stays empty until something session-scoped writes to
+     * it, which for a game with no `setup` slot is never (§8.3). This
+     * used to persist a resolved snapshot instead, and because the session layer
+     * outranks the scenario, every value the snapshot carried down from one
+     * scenario then suppressed the next: selecting a different scenario changed
+     * the label and nothing else.
+     */
+    saveGameConfiguration(): Promise<void>;
+}

package/dist/execution/configuration-builder.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Configuration builder - generates and saves session-override layer
+ */
+/**
+ * Settings values keyed by settings identifier (#597): `{ pricing: {...} }`.
+ *
+ * The two aliases below share this shape and mean different things. Keeping
+ * one name for both is how §12.3 came to type a settings editor's seed as the
+ * override layer while §8.3 said it carries the resolved values — which, read
+ * literally, seeds a fresh session's form with `{}`.
+ */
+type SettingsKeyedValues = Record<string, Record<string, unknown>>;
+/**
+ * The session-override layer (§8.2 layer 3): what a facilitator changed for
+ * this session, and nothing else.
+ *
+ * **Sparse by contract.** It holds only the keys something session-scoped
+ * actually supplied, never a resolved snapshot of the layers beneath it. A
+ * value copied down from a scenario would be indistinguishable from one a
+ * facilitator typed, and because this layer outranks the scenario, the
+ * scenario could then never be changed (#439).
+ */
+export type SessionSettingsOverrides = SettingsKeyedValues;
+/**
+ * Settings after §8.2 layering: schema defaults → scenario overrides →
+ * session overrides.
+ *
+ * Complete rather than sparse, because every `settingsSchema` property
+ * declares a default (§8.2). This is what logic and surfaces actually receive,
+ * what seeds a settings editor (§8.3), and what the state projection reports
+ * (§20.1) — deliberately not the override layer, which for a session nobody
+ * has configured is empty.
+ */
+export type ResolvedSettings = SettingsKeyedValues;
+/**
+ * Get the path to the session-override layer file
+ */
+export declare function getConfigurationFilePath(packagePath: string): string;
+/**
+ * Path to the record of which scenario the saved configuration was built for.
+ *
+ * `configuration.json` is the sparse session-override layer (§8.2), so it no
+ * longer carries values down from the scenario it was built under. The record
+ * survives from when it did: a snapshot built under one scenario could not be
+ * reused under another, and this let a load tell "for the scenario about to
+ * run" from "stale" rather than regenerating and discarding whatever
+ * `sdk configure` had just written (#439).
+ */
+export declare function getConfigurationScenarioPath(packagePath: string): string;
+/** Record the scenario a saved configuration was built for. `null` means none. */
+export declare function saveConfigurationScenario(packagePath: string, scenarioId: string | null): Promise<void>;
+/**
+ * The scenario the saved configuration was built for: an identifier, `null` for
+ * none, or `undefined` when nothing was recorded (no configuration has been
+ * saved, or it predates this record).
+ */
+export declare function readConfigurationScenario(packagePath: string): string | null | undefined;
+/**
+ * Save session-override layer to disk
+ */
+export declare function saveSessionSettingsOverrides(packagePath: string, configuration: SessionSettingsOverrides): Promise<void>;
+/**
+ * Load session-override layer from disk
+ */
+export declare function loadSessionSettingsOverrides(packagePath: string): Promise<SessionSettingsOverrides | null>;
+export {};

package/dist/execution/context-composition.d.ts

@@ -0,0 +1,161 @@
+/**
+ * How a context is cut down for logic and how what logic returns is folded
+ * back into it (§7.4, §7.5, §10.5).
+ *
+ * Logic receives only the capabilities it declared, and returns a patch rather
+ * than a replacement, so the input projection and the result fold are two
+ * halves of one contract: projecting is safe only because folding carries
+ * through what a resource never saw. The shared store is the other half of the
+ * composition: one value per shared capability, written by an aggregate's
+ * `shared` slice alone and mirrored into every team's view. These are pure
+ * functions over the boards and the store they are handed, so the executor
+ * owns the state and this module owns the rules, and each can be read without
+ * the other's bookkeeping in the way.
+ */
+import type { ResolvedPackageManifest, ContextDeletePath, Participant } from '@seriousgaming/sdk';
+import { type EngineResultRead } from './logic-result';
+import type { GameContext } from './types';
+/** A resource's capability declaration, which projection and write checks read. */
+export interface Declaration {
+    reads?: string[];
+    writes?: string[];
+}
+/** What folding a result needs to know about the game it lands in. */
+export interface CompositionScope {
+    /** Each capability's schema defaults, the base a returned capability merges over. */
+    defaults: ReadonlyMap<string, Record<string, unknown>>;
+    /** The shared-scope capabilities, which a team's board cannot write (§10.5). */
+    sharedIds: ReadonlySet<string>;
+    /** The engine's declaration, which an engine result's `deletes` are held to. */
+    engine: Declaration;
+}
+/**
+ * Whether a proposed mutation changes the value of any capability in
+ * `reads`.
+ *
+ * An empty or absent declaration answers `true`: with nothing declared the
+ * runtime cannot tell which writes matter, and a resource whose answer
+ * comes from somewhere other than context is exactly the one that must run
+ * on every write. That is the honest default rather than an oversight, and
+ * it is the same default §11.1a gives the tick controller.
+ */
+export declare function mutationAffects(reads: string[] | undefined, previous: GameContext, next: GameContext): boolean;
+/**
+ * Refuse a change to any capability the resource does not declare in
+ * `writes` (§10.5), whether it reads it or never declared it at all.
+ *
+ * `writes` is the authorisation for a logic result. The comparison is by
+ * value, not by key. Author logic returns its whole projected context by
+ * spreading, so every declared capability comes back on every call whether
+ * or not it was touched; rejecting on presence would reject the ordinary
+ * idiom. A capability that comes back unchanged is the spread doing its job,
+ * and only a changed one is a write.
+ */
+export declare function enforceDeclaredWrites(identifier: string, declaration: Declaration, contextBefore: GameContext, contextAfter: GameContext, phase: string): void;
+/**
+ * Refuse a shared-capability write from a per-team `Init` or `Run` (§10.5).
+ *
+ * A per-team call runs against one team's board, so a shared value it
+ * changed would be a team-addressed write to a value every team reads
+ * (§7.5). Only the matching aggregate function writes the store. Compared by
+ * value, as {@link enforceDeclaredWrites} compares, so a shared capability
+ * returned unchanged by a spread is not a write.
+ */
+export declare function enforceSharedWrites(engineIdentifier: string, sharedCapabilityIds: readonly string[], contextBefore: GameContext, contextAfter: GameContext, phase: 'Init' | 'Run'): void;
+/**
+ * The capabilities a logic-bearing resource receives (§7.4): its `reads`
+ * and its `writes`, and nothing else.
+ *
+ * No scope filter is applied. `private` reaches logic on the same terms as
+ * `team` (§6.1) — only a UI surface withholds it — so this is the union of
+ * the two declarations and nothing more. A resource that declares nothing
+ * receives nothing, which is what a declaration saying it needs nothing
+ * means.
+ *
+ * Projecting the input is only safe because the result is folded back as a
+ * patch ({@link mergeCapabilityFields}): the capabilities a resource never
+ * saw are carried through from the context it was called with, not dropped
+ * because its return value did not mention them.
+ */
+export declare function projectForLogic(context: GameContext, declaration: Declaration): GameContext;
+/**
+ * Fold a logic result back into the whole context.
+ *
+ * Logic receives only the capabilities it declared (§7.4), so what it
+ * returns is a **patch** over the rest of the context rather than a
+ * replacement for it: the base is `contextBefore`, and only the
+ * capabilities the result actually carries are overwritten. An undeclared
+ * capability the resource never saw survives untouched, which is what
+ * makes projecting the input safe.
+ *
+ * Within each returned capability the merge order is (last wins): schema
+ * defaults → previous values → returned values, so a result that replaces
+ * a capability with a subset of its fields does not drop the rest.
+ */
+export declare function mergeCapabilityFields(context: GameContext, contextBefore: GameContext, defaults: ReadonlyMap<string, Record<string, unknown>>): GameContext;
+/**
+ * Fold a logic result's `capabilities`, then remove each path in its
+ * `deletes` (§7.4). The order is §9.5's, and the removal is the very one a
+ * UI's `deletes` gets, so a result can replace an entry of a keyed map by
+ * writing the new key and dropping the old one in either order.
+ */
+export declare function foldLogicResult(capabilities: GameContext, deletes: readonly ContextDeletePath[], contextBefore: GameContext, defaults: ReadonlyMap<string, Record<string, unknown>>): GameContext;
+/**
+ * The arguments an aggregate function receives besides config, meta and
+ * callbacks: the shared store once, and each team's own capabilities.
+ *
+ * Both halves are projected onto what the engine declared (§7.4). The
+ * store is not repeated inside each team: a game that read it from
+ * `teams[0]` had nothing to read in a session with no teams, and at a
+ * hundred teams was handed a hundred copies of one value.
+ */
+export declare function aggregateArgs(contexts: GameContext[], identities: {
+    teamId: string;
+    index: number;
+}[], declaration: Declaration, store: GameContext, sharedIds: ReadonlySet<string>, participants: Participant[]): {
+    shared: {
+        context: GameContext;
+        state: unknown;
+    };
+    teams: {
+        teamId: string;
+        index: number;
+        context: GameContext;
+        state: unknown;
+    }[];
+    participants: Participant[];
+};
+/**
+ * Fold an engine result into the context it was called with: its
+ * capabilities as a patch, and its `state`, when it returned one, as the
+ * team's new engine state whole.
+ */
+export declare function applyEngineResult(label: string, result: EngineResultRead, contextBefore: GameContext, scope: CompositionScope): GameContext;
+/**
+ * Fold an aggregate result into the team contexts it was called with, write
+ * its shared slice to the canonical store, and mirror the store into every
+ * team's view.
+ *
+ * A shared capability is written through `shared` alone. One in a `teams`
+ * entry fails the operation: the entry is a per-team patch, and a per-team
+ * value for a capability with one value per session cannot be represented.
+ * Earlier revisions adopted it when every team agreed, which is how games
+ * came to write shared state by returning a copy per team.
+ *
+ * Every team entry and the shared slice are held to the engine's `writes`
+ * before anything lands (§10.5), so a refused result leaves the store as it
+ * was. `store` is then written in place, as the canonical store is; the store
+ * to keep is returned beside the contexts, because a `deletes` replaces it.
+ */
+export declare function applyAggregateResult(read: {
+    shared: EngineResultRead;
+    teams: EngineResultRead[];
+}, contextsBefore: GameContext[], engineIdentifier: string, phase: 'InitAggregate' | 'RunAggregate', scope: CompositionScope, store: GameContext): {
+    contexts: GameContext[];
+    store: GameContext;
+};
+/**
+ * The schema defaults of every capability a resource of the package reads
+ * or writes, keyed by capability.
+ */
+export declare function computeCapabilityDefaults(config: ResolvedPackageManifest | null): Map<string, Record<string, unknown>>;

package/dist/execution/endpoint-actions.d.ts

@@ -0,0 +1,9 @@
+import type { EndpointAction, EndpointActionType } from '@seriousgaming/sdk';
+/**
+ * The actions an endpoint returned, checked against what it declared (§6.12).
+ *
+ * All or nothing, like a patch naming an undeclared capability: one bad action
+ * fails the call before anything is applied, because carrying out the good
+ * ones would leave the response describing a session the caller never gets.
+ */
+export declare function readEndpointActions(identifier: string, declared: readonly EndpointActionType[], returned: unknown): EndpointAction[];

package/dist/execution/endpoint-payloads.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Request and response validation for endpoint calls (§6.12, rules 1 and 5).
+ *
+ * The schemas an endpoint declares were only ever compiled into types, which
+ * binds the surface an author writes against and binds nothing at run time. A
+ * caller sending a value the schema forbids reached the handler, and the
+ * handler's return reached the caller unchecked.
+ *
+ * That was survivable while every caller was a screen built from those same
+ * generated types. An external endpoint's requests come from outside the game,
+ * often from a model, so the schema is the boundary rather than a description
+ * of one.
+ */
+import type { JSONSchema7 } from 'json-schema';
+/**
+ * A failure only an endpoint call can have (§6.12), carrying the
+ * `EndpointFailure` kind the caller is told: the request was refused before the
+ * handler ran, the handler threw, or what it returned broke its declaration.
+ */
+export declare class EndpointFault extends Error {
+    readonly kind: 'invalid-request' | 'handler-error' | 'invalid-response';
+    constructor(kind: 'invalid-request' | 'handler-error' | 'invalid-response', message: string);
+}
+/**
+ * Run `work`, reporting anything it throws as `kind`. A fault already
+ * classified keeps its own kind.
+ */
+export declare function faultAs<T>(kind: EndpointFault['kind'], work: () => T | Promise<T>): Promise<T>;
+/** Throws when `request` does not satisfy the endpoint's `requestSchema`. */
+export declare function assertValidEndpointRequest(identifier: string, schema: JSONSchema7 | undefined, request: unknown): void;
+/** Throws when `response` does not satisfy the endpoint's `responseSchema`. */
+export declare function assertValidEndpointResponse(identifier: string, schema: JSONSchema7 | undefined, response: unknown): void;

package/dist/execution/endpoint-runner.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Running an endpoint's logic (§6.12): building its arguments, calling
+ * `Handle`, or `Plan` and later `Respond`, and holding what it returns to its
+ * declaration.
+ *
+ * Everything here is about the call itself and none of it about the session:
+ * what the endpoint is handed is cut down to its `reads` and `writes`, file
+ * fields in the request become stored `blob:` references, and a returned patch,
+ * per-team patch or action list is checked against what the bundle declares
+ * before anything is allowed to act on it. Applying those effects is the
+ * session's, on its mutation queue with every other write (§9.7), so a run
+ * ends in an {@link EndpointRun} describing them rather than in any change.
+ */
+import type { ContextDeletePath, EndpointAction, EndpointCaller, EndpointOutcome, EndpointSession, Participant, SDKEndpoint, TeamInfo } from '@seriousgaming/sdk';
+import type { LogicHost } from './logic-calls';
+import type { GameContext } from './types';
+/**
+ * The call-shaped half of `runEndpoint`'s arguments: everything a handler's
+ * arguments are built from. `respondEndpoint` takes the same, read afresh.
+ */
+export interface EndpointCallArgs {
+    identifier: string;
+    request: unknown;
+    caller: EndpointCaller;
+    context?: GameContext;
+    teams?: readonly {
+        teamId: string;
+        index: number;
+        name: string;
+        context: GameContext;
+    }[];
+    team?: TeamInfo;
+    scopedTeamIndex?: number;
+    session: EndpointSession;
+    /**
+     * When the call started (`meta.now`, §10.2). The host takes it once, so
+     * `Plan` and `Respond` read the same instant. Read from the executor's
+     * clock when absent.
+     */
+    now?: number;
+    /**
+     * The participants the call covers (§6.12): the team's, or every one for a
+     * session-scoped endpoint. Taken from the roster source when absent.
+     */
+    participants?: Participant[];
+    /**
+     * Every settings resource's resolved values, where the call resolves them
+     * other than the session does: a call from the scenario editor, which
+     * reads the draft it is editing (§6.12). The endpoint is handed its
+     * declared ones. The session's when absent.
+     */
+    settings?: Record<string, Record<string, unknown>>;
+}
+/**
+ * One endpoint call's outcome: the response its caller receives, and, for an
+ * endpoint that declares `writes`, the board change it asks for. The patch is
+ * applied by the session rather than here, so it lands on the mutation queue
+ * with every other write (§9.7).
+ */
+export interface EndpointRun {
+    response: unknown;
+    patch?: GameContext;
+    /**
+     * Paths the endpoint removes after `patch` lands, from the same board:
+     * the team's for a team-scoped endpoint, the shared store for a
+     * session-scoped one. Already held to its `writes`.
+     */
+    deletes?: ContextDeletePath[];
+    /**
+     * A session-scoped endpoint's changes to individual teams' boards, keyed
+     * by team id, each already held to its non-shared `writes`.
+     */
+    teamPatches?: Record<string, GameContext>;
+    /** Session actions to carry out after the writes, already checked. */
+    actions?: EndpointAction[];
+    /**
+     * The request as the handler received it, file fields resolved to `blob:`
+     * references. `Respond` is given this one, so an inline upload is stored
+     * once rather than again for the second phase.
+     */
+    request?: unknown;
+    /**
+     * True when the endpoint exports `Plan` and `Respond`: `response` is then
+     * absent, and the session calls `respondEndpoint` once the effects land.
+     */
+    responds?: boolean;
+}
+export interface EndpointRunnerHost extends LogicHost {
+    packagePath: string;
+    /** The executor's own board, for a team-scoped call that names none. */
+    board(): GameContext;
+    /** The canonical shared store, as a copy. */
+    sharedContext(): GameContext;
+}
+export declare class EndpointRunner {
+    private readonly host;
+    constructor(host: EndpointRunnerHost);
+    /** Look up an endpoint by identifier in the loaded configuration. */
+    find(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.
+     */
+    run(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`.
+     */
+    respond(args: EndpointCallArgs & {
+        plan: EndpointRun;
+        outcomes: EndpointOutcome[];
+    }): Promise<unknown>;
+    /** Load endpoint logic (with caching). */
+    private load;
+    /** Hold what `Handle` or `Plan` returned to the endpoint's declaration (§6.12). */
+    private readRun;
+    /**
+     * Build an endpoint function's arguments and call it, bounded (§6.12).
+     * Shared by `Handle`, `Plan` and `Respond`, which see the same shape.
+     */
+    private invoke;
+}

package/dist/execution/engine-state.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The engine's private memory (§10.2): what `Init` and `Run` return under
+ * `state`, handed back to the engine alone on its next call.
+ *
+ * It is held inside the stored context, under a key no capability identifier
+ * can take, rather than beside it. Everything that already carries a team's
+ * context therefore carries its state for free — tick snapshots, undo, a
+ * per-team reset to the initial board, a team added mid-session — and
+ * everything that already projects a context onto declared capabilities, which
+ * is every path to a surface, a hook, a validator or an endpoint, drops it for
+ * free. The two places that hand context out whole, the state projection and
+ * past-state rows, strip it explicitly.
+ *
+ * The session-wide half, `shared.state`, lives in the shared store under a key
+ * of its own and is mirrored into every team's view like a shared capability,
+ * so a shared-state undo rewinds it with the store.
+ */
+import type { GameContext } from './types';
+/** A team's engine state, inside that team's stored context. */
+export declare const ENGINE_STATE_KEY = "$engineState";
+/** The session-wide engine state, inside the shared store and every view. */
+export declare const SHARED_ENGINE_STATE_KEY = "$sharedEngineState";
+/** Whether a context key is engine state rather than a capability. */
+export declare function isReservedKey(key: string): boolean;
+/** A context with the engine's state removed, for anything that is not the engine. */
+export declare function withoutEngineState(context: GameContext): GameContext;
+/**
+ * Fail unless `value` survives a JSON round trip unchanged: plain objects,
+ * arrays, strings, finite numbers, booleans and `null`.
+ *
+ * The runtime asks nothing else of engine state, and a hosted runtime persists
+ * it as JSON, so a `Date`, a `Map` or a `NaN` that the dev server would happily
+ * hold in memory would come back different after a restart. Checked here so it
+ * fails on the first tick rather than on the day.
+ *
+ * Realm-safe: logic runs in its own V8 context, so a plain object it built has
+ * that realm's `Object.prototype`, and an `instanceof` or prototype identity
+ * check would call it a class instance (#394).
+ */
+export declare function assertJsonSerialisable(label: string, value: unknown): void;