@dreamboard-games/sdk 0.2.0

package/src/reducer/bundle/trusted/runtime-scope.ts

@@ -0,0 +1,336 @@
+import { createDerivedResolver } from "../../derived";
+import type { DerivedResolver } from "../../derived";
+import { createReducerFx } from "../../effects";
+import { createReducerOps } from "../../ops";
+import { createReducerEdit } from "../../transaction";
+import { createStateQueries } from "../../table-queries";
+import type { TrustedRuntimeInput } from "../../core/types";
+import type { RuntimeInstructionForState } from "../../core/runtime-instruction";
+import type {
+  ActionContext,
+  AnyContinuationCallable,
+  AnyInteractionSpec,
+  BaseGameSessionOfContract,
+  BaseGameStateOfContract,
+  ManifestContractOf,
+  PhaseMapOf,
+  PhaseNamesOfDefinition,
+  PlayerIdOfState,
+  PlayerZoneIdOfManifest,
+  RandomHelpers,
+  ReducerGameContractLike,
+  ReducerGameDefinition,
+  StageSpec,
+  TableQueriesOfState,
+  ViewMapOf,
+} from "../../model";
+import {
+  collectTrustedRuntimeRegistry,
+  type TrustedErasedPhase,
+  type TrustedCardActionEntry,
+  type TrustedInteractionEntry,
+  type TrustedPhaseRegistry,
+  type TrustedRuntimeRegistry,
+} from "./runtime-registry";
+import {
+  buildContext as buildTrustedContext,
+  buildRuntimeArgs as buildTrustedRuntimeArgs,
+  fxForState as trustedFxForState,
+} from "./trusted-runtime-args";
+import {
+  normalizeResult,
+  rejectResult,
+  runtimeResultHelpers,
+} from "./trusted-runtime-result";
+import {
+  toCombinedState as codecToCombinedState,
+  toDomainState as codecToDomainState,
+  toSessionState as codecToSessionState,
+} from "./trusted-state-codec";
+import {
+  resolveDefaultInitialPhase,
+  resolveTrustedSetupProfiles,
+} from "./trusted-setup-profiles";
+
+export { normalizeResult, rejectResult } from "./trusted-runtime-result";
+
+export type TrustedDefinition<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = ReducerGameDefinition<Contract, Definitions, Views>;
+
+export type TrustedDomainState<Contract extends ReducerGameContractLike> =
+  BaseGameStateOfContract<Contract>;
+
+export type TrustedSessionState<Contract extends ReducerGameContractLike> =
+  BaseGameSessionOfContract<Contract>;
+
+export type TrustedState<Contract extends ReducerGameContractLike> =
+  TrustedDomainState<Contract> & {
+    runtime: TrustedSessionState<Contract>["runtime"];
+  };
+
+export type TrustedManifest<Contract extends ReducerGameContractLike> =
+  ManifestContractOf<Contract>;
+
+export type TrustedPhaseName<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = PhaseNamesOfDefinition<TrustedDefinition<Contract, Definitions, Views>>;
+
+export type TrustedPlayerId<Contract extends ReducerGameContractLike> =
+  PlayerIdOfState<TrustedDomainState<Contract>>;
+
+export type TrustedInput<Contract extends ReducerGameContractLike> =
+  TrustedRuntimeInput<TrustedPlayerId<Contract>>;
+
+export type { TrustedErasedPhase } from "./runtime-registry";
+
+export interface TrustedRuntimeHelpers<
+  Contract extends ReducerGameContractLike,
+> {
+  accept: (
+    state: TrustedDomainState<Contract>,
+    instructions?: Array<
+      RuntimeInstructionForState<TrustedDomainState<Contract>>
+    >,
+  ) => {
+    type: "accept";
+    state: TrustedDomainState<Contract>;
+    instructions: Array<
+      RuntimeInstructionForState<TrustedDomainState<Contract>>
+    >;
+  };
+  reject: typeof rejectResult;
+  ops: ReturnType<typeof createReducerOps<TrustedDomainState<Contract>>>;
+  edit: ReturnType<typeof createReducerEdit<TrustedDomainState<Contract>>>;
+}
+
+export interface TrustedRuntimeScope<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> {
+  definition: TrustedDefinition<Contract, Definitions, Views>;
+  registry: TrustedRuntimeRegistry<Contract, Definitions, Views>;
+  phaseEntries: ReadonlyArray<
+    readonly [
+      TrustedPhaseName<Contract, Definitions, Views>,
+      TrustedErasedPhase<Contract>,
+    ]
+  >;
+  defaultInitialPhase: TrustedPhaseName<Contract, Definitions, Views>;
+  manifestSetupProfilesById: TrustedManifest<Contract>["setupProfilesById"];
+  reducerSetupProfiles: NonNullable<
+    TrustedDefinition<Contract, Definitions, Views>["setupProfiles"]
+  >;
+  runtimeHelpers: TrustedRuntimeHelpers<Contract>;
+  toDomainState(state: TrustedState<Contract>): TrustedDomainState<Contract>;
+  toCombinedState(
+    session: TrustedSessionState<Contract>,
+  ): TrustedState<Contract>;
+  toSessionState(state: TrustedState<Contract>): TrustedSessionState<Contract>;
+  phaseRegistryByName(
+    phaseName: TrustedPhaseName<Contract, Definitions, Views>,
+  ): TrustedPhaseRegistry<Contract, Definitions, Views> | undefined;
+  phaseByName(
+    phaseName: TrustedPhaseName<Contract, Definitions, Views>,
+  ): TrustedErasedPhase<Contract>;
+  findInteractionInPhase(
+    phaseName: TrustedPhaseName<Contract, Definitions, Views>,
+    interactionId: string,
+  ):
+    | AnyInteractionSpec<
+        TrustedDomainState<Contract>,
+        TrustedManifest<Contract>
+      >
+    | undefined;
+  interactionEntriesForPhase(
+    phaseName: TrustedPhaseName<Contract, Definitions, Views>,
+  ): ReadonlyArray<TrustedInteractionEntry<Contract>>;
+  stagesForPhase(
+    phaseName: TrustedPhaseName<Contract, Definitions, Views>,
+  ): ReadonlyArray<
+    readonly [
+      string,
+      StageSpec<TrustedDomainState<Contract>, TrustedManifest<Contract>>,
+    ]
+  >;
+  zonesForPhase(
+    phaseName: TrustedPhaseName<Contract, Definitions, Views>,
+  ): ReadonlyArray<PlayerZoneIdOfManifest<TrustedManifest<Contract>>>;
+  cardActionEntriesForPhase(
+    phaseName: TrustedPhaseName<Contract, Definitions, Views>,
+  ): ReadonlyArray<TrustedCardActionEntry<Contract>>;
+  continuationById(
+    id: string,
+  ): AnyContinuationCallable<TrustedDomainState<Contract>> | undefined;
+  fxForState(
+    state: TrustedState<Contract>,
+  ): ReturnType<typeof createReducerFx<TrustedState<Contract>>>;
+  buildContext(
+    state: TrustedState<Contract>,
+  ): ActionContext<TrustedDomainState<Contract>, TrustedManifest<Contract>>;
+  buildRuntimeArgs<Extra extends object>(
+    state: TrustedState<Contract>,
+    extra: Extra,
+    options?: {
+      q?: TableQueriesOfState<TrustedDomainState<Contract>>;
+      derived?: DerivedResolver;
+      fx?: ReturnType<typeof createReducerFx<TrustedState<Contract>>>;
+      random?: RandomHelpers;
+    },
+  ): ActionContext<TrustedDomainState<Contract>, TrustedManifest<Contract>> &
+    TrustedRuntimeHelpers<Contract> & {
+      fx: ReturnType<typeof createReducerFx<TrustedState<Contract>>>;
+      q: ReturnType<typeof createStateQueries<TrustedDomainState<Contract>>>;
+      derived: ReturnType<
+        typeof createDerivedResolver<TrustedDomainState<Contract>>
+      >;
+      runtime: Omit<TrustedState<Contract>["runtime"], "rng">;
+      random: RandomHelpers;
+    } & Extra;
+}
+
+export function createTrustedRuntimeScope<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  definition: TrustedDefinition<Contract, Definitions, Views>,
+): TrustedRuntimeScope<Contract, Definitions, Views> {
+  type DomainState = TrustedDomainState<Contract>;
+  type SessionState = TrustedSessionState<Contract>;
+  type State = TrustedState<Contract>;
+  type Manifest = TrustedManifest<Contract>;
+  type PhaseName = TrustedPhaseName<Contract, Definitions, Views>;
+  const registry = collectTrustedRuntimeRegistry(definition);
+  const { phaseEntries } = registry;
+  const defaultInitialPhase = resolveDefaultInitialPhase(
+    definition.initialPhase as PhaseName | undefined,
+    phaseEntries,
+  );
+  const { manifestSetupProfilesById, reducerSetupProfiles } =
+    resolveTrustedSetupProfiles(definition);
+
+  function toDomainState(state: State): DomainState {
+    return codecToDomainState<State, DomainState>(state);
+  }
+
+  function toCombinedState(session: SessionState): State {
+    return codecToCombinedState<SessionState, State>(session);
+  }
+
+  function toSessionState(state: State): SessionState {
+    return codecToSessionState<State, DomainState, SessionState>(
+      state,
+      toDomainState,
+    );
+  }
+
+  function phaseRegistryByName(
+    phaseName: PhaseName,
+  ): TrustedPhaseRegistry<Contract, Definitions, Views> | undefined {
+    return registry.phasesByName.get(phaseName);
+  }
+
+  function phaseByName(phaseName: PhaseName): TrustedErasedPhase<Contract> {
+    const phaseRegistry = phaseRegistryByName(phaseName);
+    if (!phaseRegistry) {
+      throw new Error(`Unknown reducer phase '${phaseName}'.`);
+    }
+    return phaseRegistry.phase;
+  }
+
+  function findInteractionInPhase(
+    phaseName: PhaseName,
+    interactionId: string,
+  ): AnyInteractionSpec<DomainState, Manifest> | undefined {
+    const found = interactionEntriesForPhase(phaseName).find(
+      ([id]) => id === interactionId,
+    );
+    return found?.[1];
+  }
+
+  function interactionEntriesForPhase(phaseName: PhaseName) {
+    return phaseRegistryByName(phaseName)?.interactions ?? [];
+  }
+
+  function stagesForPhase(phaseName: PhaseName) {
+    return phaseRegistryByName(phaseName)?.stages ?? [];
+  }
+
+  function zonesForPhase(phaseName: PhaseName) {
+    return phaseRegistryByName(phaseName)?.zones ?? [];
+  }
+
+  function cardActionEntriesForPhase(phaseName: PhaseName) {
+    return phaseRegistryByName(phaseName)?.cardActions ?? [];
+  }
+
+  function continuationById(id: string) {
+    return registry.continuationsById.get(id);
+  }
+
+  const helpers: TrustedRuntimeHelpers<Contract> = {
+    ...runtimeResultHelpers,
+    ops: createReducerOps<DomainState>(),
+    edit: createReducerEdit<DomainState>(),
+  };
+
+  function fxForState(state: State) {
+    return trustedFxForState<Contract>(state);
+  }
+
+  function buildContext(state: State): ActionContext<DomainState, Manifest> {
+    return buildTrustedContext<Contract>(state, definition.contract.manifest);
+  }
+
+  function buildRuntimeArgs<Extra extends object>(
+    state: State,
+    extra: Extra,
+    options?: {
+      q?: TableQueriesOfState<DomainState>;
+      derived?: DerivedResolver;
+      fx?: ReturnType<typeof createReducerFx<State>>;
+      random?: RandomHelpers;
+    },
+  ) {
+    return buildTrustedRuntimeArgs<Contract, Extra>(
+      state,
+      definition.contract.manifest,
+      helpers,
+      toDomainState,
+      extra,
+      options,
+    );
+  }
+
+  return {
+    definition,
+    registry,
+    phaseEntries,
+    defaultInitialPhase,
+    manifestSetupProfilesById,
+    reducerSetupProfiles: reducerSetupProfiles as NonNullable<
+      TrustedDefinition<Contract, Definitions, Views>["setupProfiles"]
+    >,
+    runtimeHelpers: helpers,
+    toDomainState,
+    toCombinedState,
+    toSessionState,
+    phaseRegistryByName,
+    phaseByName,
+    findInteractionInPhase,
+    interactionEntriesForPhase,
+    stagesForPhase,
+    zonesForPhase,
+    cardActionEntriesForPhase,
+    continuationById,
+    fxForState,
+    buildContext,
+    buildRuntimeArgs,
+  };
+}

package/src/reducer/bundle/trusted/simultaneous-player.ts

@@ -0,0 +1,97 @@
+import type {
+  AnyInteractionSpec,
+  PhaseMapOf,
+  ReducerGameContractLike,
+  ViewMapOf,
+} from "../../model";
+import type { ProjectionContext } from "./projection-context";
+import type {
+  TrustedDomainState,
+  TrustedManifest,
+  TrustedPlayerId,
+  TrustedRuntimeScope,
+  TrustedState,
+} from "./runtime-scope";
+
+export const SIMULTANEOUS_SUBMIT_INTERACTION_ID = "submit";
+
+type ErasedPhase<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = ReturnType<
+  TrustedRuntimeScope<Contract, Definitions, Views>["phaseByName"]
+>;
+
+export function isSimultaneousPhase<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(phase: ErasedPhase<Contract, Definitions, Views>): boolean {
+  return phase.kind === "simultaneousPlayer";
+}
+
+export function simultaneousSubmitInteraction<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  phase: ErasedPhase<Contract, Definitions, Views>,
+):
+  | AnyInteractionSpec<TrustedDomainState<Contract>, TrustedManifest<Contract>>
+  | undefined {
+  return (phase as { submit?: unknown }).submit as
+    | AnyInteractionSpec<
+        TrustedDomainState<Contract>,
+        TrustedManifest<Contract>
+      >
+    | undefined;
+}
+
+function resolvePromptToArray<PlayerId extends string>(
+  value: unknown,
+): PlayerId[] {
+  if (value === undefined || value === null) return [];
+  if (Array.isArray(value)) return value as PlayerId[];
+  if (typeof value === "string") return [value as PlayerId];
+  return [];
+}
+
+export function resolveSimultaneousActors<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  scope: TrustedRuntimeScope<Contract, Definitions, Views>,
+  state: TrustedState<Contract>,
+  phase: ErasedPhase<Contract, Definitions, Views>,
+  projection?: ProjectionContext<
+    TrustedDomainState<Contract>,
+    TrustedState<Contract>
+  >,
+): TrustedPlayerId<Contract>[] {
+  type PlayerId = TrustedPlayerId<Contract>;
+  const selector =
+    (phase as { actors?: unknown; actor?: unknown }).actors ??
+    (phase as { actor?: unknown }).actor;
+  if (typeof selector === "function") {
+    const selected = selector(
+      scope.buildRuntimeArgs(
+        state,
+        {
+          state: projection?.domainState ?? scope.toDomainState(state),
+        },
+        projection,
+      ),
+    );
+    const resolved = resolvePromptToArray<PlayerId>(selected);
+    if (resolved.length > 0) {
+      return resolved;
+    }
+  }
+  const active = state.flow.activePlayers as PlayerId[];
+  if (active.length > 0) {
+    return [...active];
+  }
+  return [...(state.table.playerOrder as PlayerId[])];
+}

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

@@ -0,0 +1,87 @@
+import type {
+  AnyInteractionSpec,
+  PhaseMapOf,
+  ReducerGameContractLike,
+  StageSpec,
+  ViewMapOf,
+} from "../../model";
+import type {
+  TrustedDomainState,
+  TrustedManifest,
+  TrustedPhaseName,
+  TrustedRuntimeScope,
+  TrustedState,
+} from "./runtime-scope";
+import type { ProjectionContext } from "./projection-context";
+
+export function createStageResolver<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(scope: TrustedRuntimeScope<Contract, Definitions, Views>) {
+  type DomainState = TrustedDomainState<Contract>;
+  type Manifest = TrustedManifest<Contract>;
+  type State = TrustedState<Contract>;
+  type PhaseName = TrustedPhaseName<Contract, Definitions, Views>;
+
+  function resolveActiveStage(
+    state: State,
+    phaseName: PhaseName,
+    projection?: ProjectionContext<DomainState, State>,
+  ): { id: string; stage: StageSpec<DomainState, Manifest> } | null {
+    const stages = scope.stagesForPhase(phaseName);
+    if (stages.length === 0) return null;
+    const domainState = projection?.domainState ?? scope.toDomainState(state);
+    const context = scope.buildContext(state);
+    for (const [stageId, stage] of stages) {
+      const matches = stage.when
+        ? stage.when({
+            ...context,
+            state: domainState,
+          })
+        : true;
+      if (matches) return { id: stageId, stage };
+    }
+    return null;
+  }
+
+  function resolveActiveStageAllowlist(
+    state: State,
+    phaseName: PhaseName,
+    projection?: ProjectionContext<DomainState, State>,
+  ): Set<string> | null {
+    const cacheKey = String(phaseName);
+    if (projection?.stageAllowlists.has(cacheKey)) {
+      return projection.stageAllowlists.get(cacheKey) ?? null;
+    }
+    const activeStage = resolveActiveStage(state, phaseName, projection);
+    const allowlist = activeStage ? new Set(activeStage.stage.allow) : null;
+    projection?.stageAllowlists.set(cacheKey, allowlist);
+    return allowlist;
+  }
+
+  function isInteractionAllowedInStep(
+    state: State,
+    interaction: AnyInteractionSpec<DomainState, Manifest>,
+    projection?: ProjectionContext<DomainState, State>,
+  ): boolean {
+    const allowedSteps = interaction.__steps ?? [];
+    if (allowedSteps.length === 0) {
+      return true;
+    }
+    const currentStep = (
+      (projection?.domainState ?? scope.toDomainState(state)).phase as {
+        step?: unknown;
+      }
+    ).step;
+    return (
+      typeof currentStep === "string" && allowedSteps.includes(currentStep)
+    );
+  }
+
+  return {
+    isInteractionAllowedInStep,
+    resolveActiveStage,
+    resolveActiveStageAllowlist,
+  };
+}

package/src/reducer/bundle/trusted/static-projection.ts

@@ -0,0 +1,116 @@
+import type {
+  ManifestContract,
+  PhaseMapOf,
+  ReducerGameContractLike,
+  RuntimeTableRecord,
+  StaticViewQueries,
+  ViewMapOf,
+} from "../../model";
+import type { TrustedRuntimeScope } from "./runtime-scope";
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries
+    .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+    .join(",")}}`;
+}
+
+function hashProjection(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0");
+}
+
+function readManifestVersion(manifest: unknown): string {
+  const m = manifest as { version?: unknown; literals?: unknown };
+  if (typeof m.version === "string" && m.version.length > 0) {
+    return m.version;
+  }
+  if (m.literals && typeof m.literals === "object") {
+    return hashProjection(stableStringify(m.literals));
+  }
+  return "0";
+}
+
+function createStaticViewQueries<
+  Manifest extends ManifestContract<RuntimeTableRecord>,
+>(manifest: Manifest): StaticViewQueries<Manifest> {
+  const staticBoards = manifest.staticBoards ?? {
+    byId: {},
+    hex: {},
+    square: {},
+  };
+  const requireBoard = (
+    boards: Record<string, unknown>,
+    boardId: string,
+    layout: "board" | "hex" | "square",
+  ) => {
+    const board = boards[boardId];
+    if (!board) {
+      throw new Error(`Unknown static ${layout} board '${boardId}'.`);
+    }
+    return board;
+  };
+
+  return {
+    board: {
+      get: (boardId) =>
+        requireBoard(
+          staticBoards.byId as Record<string, unknown>,
+          boardId,
+          "board",
+        ) as never,
+      hex: (boardId) =>
+        requireBoard(
+          staticBoards.hex as Record<string, unknown>,
+          boardId,
+          "hex",
+        ) as never,
+      square: (boardId) =>
+        requireBoard(
+          staticBoards.square as Record<string, unknown>,
+          boardId,
+          "square",
+        ) as never,
+    },
+  };
+}
+
+export function createStaticProjectionBuilder<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(scope: TrustedRuntimeScope<Contract, Definitions, Views>) {
+  return {
+    projectStatic(): {
+      view: unknown;
+      hash: string;
+      manifestVersion: string;
+    } | null {
+      const staticView = scope.definition.staticView;
+      if (!staticView) return null;
+      const manifest = scope.definition.contract.manifest;
+      const view = staticView.project({
+        manifest,
+        q: createStaticViewQueries(manifest),
+      });
+      const serialized = stableStringify(view);
+      return {
+        view: JSON.parse(serialized) as unknown,
+        hash: hashProjection(serialized),
+        manifestVersion: readManifestVersion(manifest),
+      };
+    },
+  };
+}