@dreamboard-games/sdk 0.2.0

package/src/reducer/bundle/trusted/interaction-resolver.ts

@@ -0,0 +1,95 @@
+import type {
+  PhaseMapOf,
+  ReducerGameContractLike,
+  ReducerReject,
+  ReducerValidationResult,
+  ViewMapOf,
+} from "../../model";
+import {
+  collectEligibleTargets,
+  collectFirstCardZoneId,
+  findCardInputKey,
+  findCardInputKeyForZone,
+  parseInteractionParams,
+} from "./interaction-collectors";
+import { createInteractionAuthorization } from "./interaction-authorization";
+import { createInteractionDecisionResolver } from "./interaction-decision";
+import { createStageResolver } from "./stage-resolver";
+import {
+  rejectResult,
+  type TrustedInput,
+  type TrustedPlayerId,
+  type TrustedRuntimeScope,
+  type TrustedState,
+} from "./runtime-scope";
+
+export type { InteractionDescriptorShape } from "./interaction-types";
+
+export function createInteractionResolver<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(scope: TrustedRuntimeScope<Contract, Definitions, Views>) {
+  type State = TrustedState<Contract>;
+  type PlayerId = TrustedPlayerId<Contract>;
+  type ReducerInput = TrustedInput<Contract>;
+
+  const stages = createStageResolver(scope);
+  const authorization = createInteractionAuthorization(scope);
+  const decisions = createInteractionDecisionResolver(
+    scope,
+    stages,
+    authorization,
+  );
+
+  function validateClientInput(
+    state: State,
+    input: ReducerInput,
+  ): ReducerValidationResult {
+    if (input.kind === "interaction") {
+      const decision = decisions.resolveInteractionDecision({
+        state,
+        playerId: input.playerId as PlayerId,
+        interactionId: input.interactionId,
+        params: (input.params ?? {}) as Record<string, unknown>,
+        mode: "submit",
+      });
+      return decision.validation;
+    }
+    return { valid: true };
+  }
+
+  function validateOrReject(
+    state: State,
+    input: ReducerInput,
+  ): ReducerReject | null {
+    const validation = validateClientInput(state, input);
+    if (validation.valid) {
+      return null;
+    }
+    const invalidValidation = validation as Exclude<
+      ReducerValidationResult,
+      { valid: true }
+    >;
+    return rejectResult(invalidValidation.errorCode, invalidValidation.message);
+  }
+
+  return {
+    collectEligibleTargets,
+    collectFirstCardZoneId,
+    evaluateInteractionCost: decisions.evaluateInteractionCost,
+    findCardInputKey,
+    findCardInputKeyForZone,
+    isActorAuthorized: authorization.isActorAuthorized,
+    isInteractionAllowedInStep: stages.isInteractionAllowedInStep,
+    parseInteractionParams,
+    resolveActiveStage: stages.resolveActiveStage,
+    resolveActiveStageAllowlist: stages.resolveActiveStageAllowlist,
+    resolveAvailableInteractionsFor: decisions.resolveAvailableInteractionsFor,
+    resolveInteractionActorAuthorization:
+      authorization.resolveInteractionActorAuthorization,
+    resolveInteractionDecision: decisions.resolveInteractionDecision,
+    validateClientInput,
+    validateOrReject,
+  };
+}

package/src/reducer/bundle/trusted/interaction-types.ts

@@ -0,0 +1,171 @@
+import type {
+  AnyInteractionSpec,
+  InputCollectorKind,
+  InputDomainDescriptor,
+  InteractionIdOfDefinition,
+  InteractionKind,
+  PhaseMapOf,
+  ReducerGameContractLike,
+  ReducerValidationResult,
+  ViewMapOf,
+} from "../../model";
+import type {
+  TrustedDefinition,
+  TrustedDomainState,
+  TrustedManifest,
+  TrustedPhaseName,
+  TrustedPlayerId,
+  TrustedState,
+} from "./runtime-scope";
+import type { ProjectionContext } from "./projection-context";
+
+export type TrustedInteractionId<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = InteractionIdOfDefinition<TrustedDefinition<Contract, Definitions, Views>>;
+
+export type InteractionDescriptorContext<PlayerId extends string = string> = {
+  to: PlayerId;
+  title?: string;
+  options?: Array<{ id: string; label?: string }>;
+};
+
+export type InteractionCommitPolicyShape =
+  | { mode: "manual" }
+  | { mode: "autoWhenReady" };
+
+export type InteractionAvailabilityShape =
+  | { status: "available" }
+  | { status: "notYourTurn"; reason: string }
+  | {
+      status: "insufficientResources";
+      reason: string;
+      missingResources: Record<string, number>;
+    }
+  | { status: "blocked"; reason: string; code?: string };
+
+type InteractionDescriptorBaseShape<
+  PhaseName extends string = string,
+  InteractionId extends string = string,
+  ZoneId extends string = string,
+> = {
+  phaseName: PhaseName;
+  interactionKey: `${PhaseName}.${InteractionId}`;
+  interactionId: InteractionId;
+  commit: InteractionCommitPolicyShape;
+  zoneId?: ZoneId;
+  zoneIds?: readonly ZoneId[];
+  inputs: InteractionInputDescriptorShape[];
+  cost?: Record<string, number>;
+  currentResources?: Record<string, number>;
+  availability: InteractionAvailabilityShape;
+};
+
+export type ActionInteractionDescriptorShape<
+  PhaseName extends string = string,
+  InteractionId extends string = string,
+  ZoneId extends string = string,
+> = InteractionDescriptorBaseShape<PhaseName, InteractionId, ZoneId> & {
+  kind: "action";
+};
+
+export type PromptInteractionDescriptorShape<
+  PhaseName extends string = string,
+  InteractionId extends string = string,
+  PlayerId extends string = string,
+  ZoneId extends string = string,
+> = InteractionDescriptorBaseShape<PhaseName, InteractionId, ZoneId> & {
+  kind: "prompt";
+  context: InteractionDescriptorContext<PlayerId>;
+};
+
+export type InteractionDescriptorShape<
+  PhaseName extends string = string,
+  InteractionId extends string = string,
+  PlayerId extends string = string,
+  ZoneId extends string = string,
+> =
+  | ActionInteractionDescriptorShape<PhaseName, InteractionId, ZoneId>
+  | PromptInteractionDescriptorShape<
+      PhaseName,
+      InteractionId,
+      PlayerId,
+      ZoneId
+    >;
+
+export type TrustedInteractionDescriptorShape<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = InteractionDescriptorShape<
+  TrustedPhaseName<Contract, Definitions, Views>,
+  TrustedInteractionId<Contract, Definitions, Views>,
+  TrustedPlayerId<Contract>
+>;
+
+export type InteractionInputDescriptorShape = {
+  key: string;
+  kind: InputCollectorKind;
+  domain: InputDomainDescriptor;
+  defaultValue?: unknown;
+};
+
+export type InteractionActorAuthorization<PlayerId extends string> =
+  | { readonly mode: "addressees"; readonly addressees: ReadonlySet<PlayerId> }
+  | { readonly mode: "actors"; readonly actors: ReadonlySet<PlayerId> }
+  | { readonly mode: "active" };
+
+export type ResolveDecisionMode = "descriptor" | "card" | "submit";
+
+export type ResolveDecisionInput<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = {
+  state: TrustedState<Contract>;
+  playerId: TrustedPlayerId<Contract>;
+  interactionId: string;
+  params?: Record<string, unknown>;
+  mode: ResolveDecisionMode;
+  projection?: ProjectionContext<
+    TrustedDomainState<Contract>,
+    TrustedState<Contract>
+  >;
+};
+
+export type InteractionDecisionResult<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> =
+  | {
+      found: false;
+      validation: ReducerValidationResult;
+    }
+  | {
+      found: true;
+      interaction: AnyInteractionSpec<
+        TrustedDomainState<Contract>,
+        TrustedManifest<Contract>
+      >;
+      parsedParams: Record<string, unknown>;
+      visible: boolean;
+      descriptor: TrustedInteractionDescriptorShape<
+        Contract,
+        Definitions,
+        Views
+      >;
+      validation: ReducerValidationResult;
+    };
+
+export function makeValidationError(
+  errorCode: string,
+  message?: string,
+): ReducerValidationResult {
+  return {
+    valid: false,
+    errorCode,
+    message,
+  };
+}

package/src/reducer/bundle/trusted/lifecycle-runner.ts

@@ -0,0 +1,427 @@
+import { safeParseOrThrow } from "../../parse-utils";
+import { applySetupBootstrap } from "../../setup-bootstrap";
+import { createStateQueries } from "../../table-queries";
+import type {
+  ExactManifestContractOf,
+  PhaseMapOf,
+  ReducerGameContractLike,
+  RuntimeSetupSelection,
+  RuntimeSetupSelectionInput,
+  ViewMapOf,
+} from "../../model";
+import type { RuntimeInstructionForState } from "../../core/runtime-instruction";
+import { isPerPlayer } from "../../per-player";
+import { normalizeResult } from "./runtime-scope";
+import { createMutableRandomHelpers } from "./rng-sampler";
+import type { createInteractionResolver } from "./interaction-resolver";
+import type {
+  TrustedDomainState,
+  TrustedManifest,
+  TrustedPhaseName,
+  TrustedPlayerId,
+  TrustedRuntimeScope,
+  TrustedSessionState,
+  TrustedState,
+} from "./runtime-scope";
+
+type InteractionResolverFor<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = ReturnType<typeof createInteractionResolver<Contract, Definitions, Views>>;
+
+export function createLifecycleRunner<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  scope: TrustedRuntimeScope<Contract, Definitions, Views>,
+  interactions: InteractionResolverFor<Contract, Definitions, Views>,
+) {
+  type DomainState = TrustedDomainState<Contract>;
+  type SessionState = TrustedSessionState<Contract>;
+  type State = TrustedState<Contract>;
+  type Manifest = TrustedManifest<Contract>;
+  type ExactManifest = ExactManifestContractOf<Contract>;
+  type PhaseName = TrustedPhaseName<Contract, Definitions, Views>;
+  type PlayerId = TrustedPlayerId<Contract>;
+
+  function resolveSelectedSetup(
+    setup: RuntimeSetupSelectionInput<Manifest> | null | undefined,
+  ): State["runtime"]["setup"] {
+    if (!setup) {
+      return null;
+    }
+    const manifestProfile = scope.manifestSetupProfilesById[setup.profileId];
+    if (!manifestProfile) {
+      throw new Error(`Unknown setup profile '${setup.profileId}'.`);
+    }
+    const resolvedOptionValues: Record<string, string | null> =
+      Object.fromEntries(
+        scope.definition.contract.manifest.literals.setupOptionIds.map(
+          (optionId: string) => [optionId, null] as const,
+        ),
+      );
+
+    for (const [optionId, choiceId] of Object.entries(
+      manifestProfile.optionValues ?? {},
+    ) as Array<[string, string]>) {
+      resolvedOptionValues[optionId] = choiceId;
+    }
+    for (const [optionId, choiceId] of Object.entries(
+      setup.optionValues ?? {},
+    ) as Array<[string, string]>) {
+      resolvedOptionValues[optionId] = choiceId ?? null;
+    }
+
+    return {
+      profileId: setup.profileId,
+      optionValues:
+        resolvedOptionValues as RuntimeSetupSelection<Manifest>["optionValues"],
+    };
+  }
+
+  function resolveInitialPhase(setup: State["runtime"]["setup"]): PhaseName {
+    const setupProfile = setup
+      ? scope.reducerSetupProfiles[setup.profileId]
+      : null;
+    const resolvedPhase = (setupProfile?.initialPhase ??
+      scope.defaultInitialPhase ??
+      scope.phaseEntries[0]?.[0]) as PhaseName | undefined;
+    if (!resolvedPhase) {
+      throw new Error("Reducer-native games must define at least one phase.");
+    }
+    if (!scope.definition.phases[resolvedPhase]) {
+      throw new Error(`Unknown initial phase '${resolvedPhase}'.`);
+    }
+    return resolvedPhase;
+  }
+
+  function applySelectedSetupBootstrap(state: State): State {
+    const setup = state.runtime.setup;
+    if (!setup) {
+      return state;
+    }
+
+    const bootstrap = scope.reducerSetupProfiles[setup.profileId]?.bootstrap;
+    if (!bootstrap || bootstrap.length === 0) {
+      return state;
+    }
+
+    return applySetupBootstrap(state, bootstrap) as State;
+  }
+
+  function initPhaseState(
+    state: State,
+    phaseName: PhaseName,
+    playerIds: PlayerId[],
+  ): State {
+    const phase = scope.phaseByName(phaseName);
+    const phaseState = phase.initialState
+      ? phase.initialState({
+          manifest: scope.definition.contract.manifest,
+          state,
+          playerIds,
+          setup: state.runtime.setup,
+        })
+      : safeParseOrThrow(phase.state, {}, `phase:${phaseName}:initialState`);
+    return {
+      ...state,
+      phase: safeParseOrThrow(
+        phase.state,
+        phaseState,
+        `phase:${phaseName}`,
+      ) as State["phase"],
+      flow: {
+        ...state.flow,
+        currentPhase: phaseName as State["flow"]["currentPhase"],
+      },
+    };
+  }
+
+  function enterPhase({
+    state,
+    phaseName,
+    playerIds,
+    event,
+  }: {
+    state: State;
+    phaseName: PhaseName;
+    playerIds: PlayerId[];
+    event: "initialize" | "transition";
+  }): {
+    state: State;
+    instructions: RuntimeInstructionForState<State>[];
+  } {
+    const workingState = initPhaseState(state, phaseName, playerIds);
+    const phase = scope.phaseByName(phaseName);
+    let nextState: State = workingState;
+    const instructions: RuntimeInstructionForState<State>[] = [];
+    if (phase.enter) {
+      const random = createMutableRandomHelpers(workingState.runtime.rng);
+      const entered = normalizeResult(
+        phase.enter(
+          scope.buildRuntimeArgs(
+            workingState,
+            {
+              event,
+              state: scope.toDomainState(workingState),
+            },
+            { random: random.random },
+          ),
+        ),
+        scope.toDomainState(workingState),
+      );
+      if (entered.type === "reject") {
+        throw new Error(
+          entered.message ??
+            (event === "initialize"
+              ? `Reducer phase '${phaseName}' rejected during initialization.`
+              : `Reducer phase '${phaseName}' rejected during phase initialization.`),
+        );
+      }
+      nextState = {
+        ...entered.state,
+        runtime: { ...workingState.runtime, rng: random.currentRng() },
+      } as State;
+      if (entered.instructions) instructions.push(...entered.instructions);
+    }
+
+    const activeStage = interactions.resolveActiveStage(nextState, phaseName);
+    if (activeStage?.stage.onEnter) {
+      const random = createMutableRandomHelpers(nextState.runtime.rng);
+      const stageEntered = normalizeResult(
+        activeStage.stage.onEnter(
+          scope.buildRuntimeArgs(
+            nextState,
+            {
+              event,
+              state: scope.toDomainState(nextState),
+            },
+            { random: random.random },
+          ),
+        ),
+        scope.toDomainState(nextState),
+      );
+      if (stageEntered.type === "reject") {
+        throw new Error(
+          stageEntered.message ??
+            (event === "initialize"
+              ? `Reducer stage '${phaseName}.${activeStage.id}' rejected during initialization.`
+              : `Reducer stage '${phaseName}.${activeStage.id}' rejected during stage initialization.`),
+        );
+      }
+      nextState = {
+        ...stageEntered.state,
+        runtime: { ...nextState.runtime, rng: random.currentRng() },
+      } as State;
+      if (stageEntered.instructions) {
+        instructions.push(...stageEntered.instructions);
+      }
+    }
+    return { state: nextState, instructions };
+  }
+
+  function initializePhaseResult(
+    state: State,
+    phaseName: PhaseName,
+  ): {
+    state: State;
+    instructions: RuntimeInstructionForState<State>[];
+  } {
+    return enterPhase({
+      state,
+      phaseName,
+      playerIds: scope.buildContext(state).playerOrder as PlayerId[],
+      event: "transition",
+    });
+  }
+
+  function createInitialState({
+    table,
+    playerIds,
+    rngSeed,
+    setup,
+  }: {
+    table: State["table"];
+    playerIds: PlayerId[];
+    rngSeed?: number | null;
+    setup?: RuntimeSetupSelectionInput<Manifest> | null;
+  }): { state: State; initialPhase: PhaseName } {
+    const tableWithManifestDefaults = applyManifestTableDefaults(
+      table,
+      playerIds,
+    );
+    const parsedTable = safeParseOrThrow(
+      scope.definition.contract.manifest.tableSchema,
+      tableWithManifestDefaults,
+      "table",
+    ) as State["table"];
+    const selectedSetup = resolveSelectedSetup(setup);
+    const initialSetup =
+      selectedSetup as RuntimeSetupSelection<ExactManifest> | null;
+    const initialPhase = resolveInitialPhase(selectedSetup);
+    const initialQueries = createStateQueries({ table: parsedTable });
+    return {
+      initialPhase,
+      state: {
+        table: parsedTable,
+        publicState: safeParseOrThrow(
+          scope.definition.contract.state.public,
+          scope.definition.initial?.public?.({
+            manifest: scope.definition.contract.manifest,
+            table: parsedTable,
+            playerIds,
+            rngSeed,
+            setup: initialSetup,
+            q: initialQueries,
+          }) ?? {},
+          "publicState",
+        ) as State["publicState"],
+        privateState: Object.fromEntries(
+          playerIds.map((playerId) => [
+            playerId,
+            safeParseOrThrow(
+              scope.definition.contract.state.private,
+              scope.definition.initial?.private?.({
+                manifest: scope.definition.contract.manifest,
+                table: parsedTable,
+                playerIds,
+                playerId,
+                rngSeed,
+                setup: initialSetup,
+                q: initialQueries,
+              }) ?? {},
+              `privateState:${playerId}`,
+            ),
+          ]),
+        ) as State["privateState"],
+        hiddenState: safeParseOrThrow(
+          scope.definition.contract.state.hidden,
+          scope.definition.initial?.hidden?.({
+            manifest: scope.definition.contract.manifest,
+            table: parsedTable,
+            playerIds,
+            rngSeed,
+            setup: initialSetup,
+            q: initialQueries,
+          }) ?? {},
+          "hiddenState",
+        ) as State["hiddenState"],
+        flow: {
+          currentPhase: initialPhase as State["flow"]["currentPhase"],
+          turn: 0,
+          round: 0,
+          activePlayers: [],
+        },
+        phase: {} as State["phase"],
+        runtime: {
+          rng: {
+            seed: rngSeed ?? null,
+            cursor: 0,
+            trace: [],
+          },
+          setup: selectedSetup,
+          simultaneous: { current: null },
+          lastTransition: null,
+        } as State["runtime"],
+      },
+    };
+  }
+
+  function applyManifestTableDefaults(
+    table: State["table"],
+    playerIds: PlayerId[],
+  ): State["table"] {
+    const manifest = scope.definition.contract.manifest;
+    const defaultZones = manifest.defaults.zones(playerIds);
+    const tableZones = table.zones ?? {};
+    const tableResources = table.resources;
+    return {
+      ...table,
+      playerOrder:
+        table.playerOrder && table.playerOrder.length > 0
+          ? table.playerOrder
+          : playerIds,
+      zones: {
+        ...defaultZones,
+        ...tableZones,
+        shared: {
+          ...(defaultZones.shared ?? {}),
+          ...(tableZones.shared ?? {}),
+        },
+        perPlayer: {
+          ...(defaultZones.perPlayer ?? {}),
+          ...(tableZones.perPlayer ?? {}),
+        },
+        visibility: {
+          ...(defaultZones.visibility ?? {}),
+          ...(tableZones.visibility ?? {}),
+        },
+        cardSetIdsByZoneId: {
+          ...(defaultZones.cardSetIdsByZoneId ?? {}),
+          ...(tableZones.cardSetIdsByZoneId ?? {}),
+        },
+      },
+      decks: {
+        ...manifest.defaults.decks(playerIds),
+        ...table.decks,
+      },
+      hands: {
+        ...manifest.defaults.hands(playerIds),
+        ...table.hands,
+      },
+      handVisibility: {
+        ...manifest.defaults.handVisibility(playerIds),
+        ...table.handVisibility,
+      },
+      ownerOfCard: {
+        ...manifest.defaults.ownerOfCard(playerIds),
+        ...table.ownerOfCard,
+      },
+      visibility: {
+        ...manifest.defaults.visibility(playerIds),
+        ...table.visibility,
+      },
+      resources:
+        isPerPlayer(tableResources) && tableResources.entries.length > 0
+          ? tableResources
+          : manifest.defaults.resources(playerIds),
+    } as State["table"];
+  }
+
+  function initializeSession(
+    input: {
+      table: State["table"];
+      playerIds: PlayerId[];
+      rngSeed?: number | null;
+      setup?: RuntimeSetupSelectionInput<Manifest> | null;
+    },
+    drainInstructions: (
+      state: State,
+      instructions: RuntimeInstructionForState<State>[],
+    ) => State,
+  ): SessionState {
+    const initial = createInitialState(input);
+    const bootstrappedState = applySelectedSetupBootstrap(initial.state);
+    const entered = enterPhase({
+      state: bootstrappedState,
+      phaseName: initial.initialPhase,
+      playerIds: input.playerIds,
+      event: "initialize",
+    });
+    return scope.toSessionState(
+      drainInstructions(entered.state, entered.instructions),
+    );
+  }
+
+  return {
+    createInitialState,
+    enterPhase,
+    initializePhaseResult,
+    initializeSession,
+    initPhaseState,
+    resolveInitialPhase,
+    resolveSelectedSetup,
+  };
+}