@dreamboard-games/sdk 0.2.0

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

@@ -0,0 +1,97 @@
+import { createDerivedResolver } from "../../derived";
+import type { DerivedResolver } from "../../derived";
+import { createReducerFx } from "../../effects";
+import { createStateQueries } from "../../table-queries";
+import type {
+  ActionContext,
+  BaseGameStateOfContract,
+  ManifestContractOf,
+  PlayerIdOfState,
+  RandomHelpers,
+  ReducerGameContractLike,
+  TableQueriesOfState,
+} from "../../model";
+import type { TrustedRuntimeHelpers, TrustedState } from "./runtime-scope";
+
+export function fxForState<Contract extends ReducerGameContractLike>(
+  state: TrustedState<Contract>,
+) {
+  return createReducerFx<TrustedState<Contract>>(state);
+}
+
+export function buildContext<Contract extends ReducerGameContractLike>(
+  state: TrustedState<Contract>,
+  manifest: ManifestContractOf<Contract>,
+): ActionContext<
+  BaseGameStateOfContract<Contract>,
+  ManifestContractOf<Contract>
+> {
+  type DomainState = BaseGameStateOfContract<Contract>;
+  type PlayerId = PlayerIdOfState<DomainState>;
+  type Manifest = ManifestContractOf<Contract>;
+  return {
+    currentPhase: state.flow.currentPhase as ActionContext<
+      DomainState,
+      Manifest
+    >["currentPhase"],
+    manifest,
+    playerOrder: [...state.table.playerOrder] as PlayerId[],
+    activePlayers: [...state.flow.activePlayers] as PlayerId[],
+    runtime: publicRuntime(state.runtime),
+    setup: (state.runtime.setup
+      ? {
+          profileId: state.runtime.setup.profileId,
+          optionValues: {
+            ...state.runtime.setup.optionValues,
+          },
+        }
+      : null) as ActionContext<DomainState, Manifest>["setup"],
+  };
+}
+
+function publicRuntime<Runtime extends { rng?: unknown }>(
+  runtime: Runtime,
+): Omit<Runtime, "rng"> {
+  const { rng: _rng, ...rest } = runtime;
+  return rest;
+}
+
+const DISABLED_RANDOM_HELPERS: RandomHelpers = {
+  subset() {
+    throw new Error(
+      "random helpers are only available in reducer mutation callbacks.",
+    );
+  },
+};
+
+export function buildRuntimeArgs<
+  Contract extends ReducerGameContractLike,
+  Extra extends object,
+>(
+  state: TrustedState<Contract>,
+  manifest: ManifestContractOf<Contract>,
+  helpers: TrustedRuntimeHelpers<Contract>,
+  toDomainState: (
+    state: TrustedState<Contract>,
+  ) => BaseGameStateOfContract<Contract>,
+  extra: Extra,
+  options: {
+    q?: TableQueriesOfState<BaseGameStateOfContract<Contract>>;
+    derived?: DerivedResolver;
+    fx?: ReturnType<typeof createReducerFx<TrustedState<Contract>>>;
+    random?: RandomHelpers;
+  } = {},
+) {
+  const domainState = toDomainState(state);
+  const q = options.q ?? createStateQueries(domainState);
+  return {
+    ...buildContext(state, manifest),
+    ...helpers,
+    fx: options.fx ?? fxForState(state),
+    q,
+    derived: options.derived ?? createDerivedResolver(domainState, { q }),
+    runtime: publicRuntime(state.runtime),
+    random: options.random ?? DISABLED_RANDOM_HELPERS,
+    ...extra,
+  };
+}

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

@@ -0,0 +1,39 @@
+import type { RuntimeInstructionForState } from "../../core/runtime-instruction";
+import type { ReducerReject, ReducerResult } from "../../model";
+
+export function acceptResult<State>(
+  state: State,
+  instructions: Array<RuntimeInstructionForState<State>> = [],
+) {
+  return {
+    type: "accept" as const,
+    state,
+    instructions,
+  };
+}
+
+export function rejectResult(
+  errorCode: string,
+  message?: string,
+): ReducerReject {
+  return {
+    type: "reject",
+    errorCode,
+    message,
+  };
+}
+
+export function normalizeResult<State>(
+  result: ReducerResult<State> | void,
+  fallbackState: State,
+): ReducerResult<State> {
+  if (result === undefined || result === null) {
+    return acceptResult(fallbackState);
+  }
+  return result;
+}
+
+export const runtimeResultHelpers = {
+  accept: acceptResult,
+  reject: rejectResult,
+};

package/src/reducer/bundle/trusted/trusted-setup-profiles.ts

@@ -0,0 +1,43 @@
+import type {
+  PhaseMapOf,
+  ReducerGameContractLike,
+  ReducerGameDefinition,
+  ViewMapOf,
+} from "../../model";
+
+export function resolveTrustedSetupProfiles<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(definition: ReducerGameDefinition<Contract, Definitions, Views>) {
+  const manifestSetupProfilesById =
+    definition.contract.manifest.setupProfilesById;
+  const manifestSetupProfileIds = Object.keys(manifestSetupProfilesById).sort();
+  const reducerSetupProfiles = definition.setupProfiles ?? {};
+  const reducerSetupProfileIds = Object.keys(reducerSetupProfiles).sort();
+  if (
+    manifestSetupProfileIds.length !== reducerSetupProfileIds.length ||
+    manifestSetupProfileIds.some(
+      (profileId, index) => reducerSetupProfileIds[index] !== profileId,
+    )
+  ) {
+    throw new Error(
+      `Reducer setupProfiles must exactly match manifest setupProfiles. Manifest=[${manifestSetupProfileIds.join(", ")}], reducer=[${reducerSetupProfileIds.join(", ")}].`,
+    );
+  }
+  return {
+    manifestSetupProfilesById,
+    reducerSetupProfiles,
+  };
+}
+
+export function resolveDefaultInitialPhase<PhaseName extends string>(
+  explicitInitialPhase: PhaseName | undefined,
+  phaseEntries: ReadonlyArray<readonly [PhaseName, unknown]>,
+): PhaseName {
+  const defaultInitialPhase = explicitInitialPhase ?? phaseEntries[0]?.[0];
+  if (!defaultInitialPhase) {
+    throw new Error("Reducer-native games must define at least one phase.");
+  }
+  return defaultInitialPhase;
+}

package/src/reducer/bundle/trusted/trusted-state-codec.ts

@@ -0,0 +1,48 @@
+export function toDomainState<State extends { runtime: unknown }, DomainState>(
+  state: State,
+): DomainState {
+  const { runtime: _runtime, ...domain } = state;
+  attachPhaseAccessor(domain);
+  return domain as DomainState;
+}
+
+export function toCombinedState<
+  SessionState extends { domain: unknown; runtime: unknown },
+  State,
+>(session: SessionState): State {
+  const combined = {
+    ...(session.domain as object),
+    runtime: session.runtime,
+  };
+  attachPhaseAccessor(combined);
+  return combined as State;
+}
+
+export function toSessionState<
+  State extends { runtime: unknown },
+  DomainState,
+  SessionState,
+>(state: State, toDomain: (state: State) => DomainState): SessionState {
+  return {
+    domain: toDomain(state),
+    runtime: state.runtime,
+  } as SessionState;
+}
+
+function attachPhaseAccessor(state: unknown): void {
+  if (!state || typeof state !== "object") return;
+  const candidate = state as {
+    flow?: { currentPhase?: unknown };
+    phase?: unknown;
+  };
+  const phase = candidate.phase;
+  if (!phase || typeof phase !== "object") return;
+  const descriptor = Object.getOwnPropertyDescriptor(phase, "get");
+  if (descriptor && typeof descriptor.value === "function") return;
+  Object.defineProperty(phase, "get", {
+    enumerable: false,
+    configurable: true,
+    value: (phaseName: string) =>
+      candidate.flow?.currentPhase === phaseName ? phase : null,
+  });
+}

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

@@ -0,0 +1,97 @@
+import type { TrustedReducerBundle } from "./types";
+import type {
+  PhaseMapOf,
+  ReducerGameContractLike,
+  ReducerGameDefinition,
+  ViewMapOf,
+} from "../model";
+import { createTrustedInstructionRunner } from "./trusted/instruction-runner";
+import { createInteractionResolver } from "./trusted/interaction-resolver";
+import { createLifecycleRunner } from "./trusted/lifecycle-runner";
+import { createProjectionBuilder } from "./trusted/projection-builder";
+import { createTrustedRuntimeScope } from "./trusted/runtime-scope";
+import { createStaticProjectionBuilder } from "./trusted/static-projection";
+
+export function createTrustedReducerBundle<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  definition: ReducerGameDefinition<Contract, Definitions, Views>,
+): TrustedReducerBundle<Contract, Definitions, Views> {
+  const scope = createTrustedRuntimeScope(definition);
+  const interactions = createInteractionResolver(scope);
+  const lifecycle = createLifecycleRunner(scope, interactions);
+  const instructions = createTrustedInstructionRunner(
+    scope,
+    interactions,
+    lifecycle,
+  );
+  const staticProjection = createStaticProjectionBuilder(scope);
+  const projection = createProjectionBuilder(scope, interactions);
+
+  return {
+    async initialize(input) {
+      return lifecycle.initializeSession(input, instructions.drainInstructions);
+    },
+    async initializePhase({ state, to }) {
+      const initialized = lifecycle.initializePhaseResult(
+        scope.toCombinedState(state),
+        to,
+      );
+      return scope.toSessionState(
+        instructions.drainInstructions(
+          initialized.state,
+          initialized.instructions,
+        ),
+      );
+    },
+    async validateInput({ state, input }) {
+      return interactions.validateClientInput(
+        scope.toCombinedState(state),
+        input,
+      );
+    },
+    async reduce({ state, input }) {
+      const combinedState = scope.toCombinedState(state);
+      const reject = interactions.validateOrReject(combinedState, input);
+      if (reject) {
+        return reject;
+      }
+      const result = instructions.reduceOnce(combinedState, input);
+      if (result.type === "reject") {
+        return result;
+      }
+      return {
+        type: "accept" as const,
+        state: scope.toSessionState(result.state),
+        instructions: result.instructions ?? [],
+      };
+    },
+    async dispatch({ state, input }) {
+      const combinedState = scope.toCombinedState(state);
+      const reject = interactions.validateOrReject(combinedState, input);
+      if (reject) {
+        return reject;
+      }
+      const result = instructions.dispatch(combinedState, input);
+      if (result.type === "reject") {
+        return result;
+      }
+      return {
+        type: "accept" as const,
+        state: scope.toSessionState(result.state),
+        trace: result.trace,
+      };
+    },
+    projectStatic() {
+      return staticProjection.projectStatic();
+    },
+    projectSeatsDynamic(input) {
+      return projection.projectSeatsDynamic(input);
+    },
+    projectSeatViewDynamic(input) {
+      return projection.projectSeatViewDynamic(input);
+    },
+  };
+}

package/src/reducer/bundle/types.ts

@@ -0,0 +1,171 @@
+import type { DispatchTraceEntry, TrustedRuntimeInput } from "../core/types";
+import type {
+  BaseGameStateOfContract,
+  BaseGameSessionOfContract,
+  ManifestContractOf,
+  PhaseMapOf,
+  PhaseNamesOfDefinition,
+  PlayerIdOfState,
+  ReducerGameContractLike,
+  ReducerGameDefinition,
+  ReducerReject,
+  ReducerValidationResult,
+  RuntimeSetupSelectionInput,
+  ViewMapOf,
+} from "../model";
+import type { RuntimeInstructionForState } from "../core/runtime-instruction";
+import type { ReducerBundleContract } from "../../infrastructure/reducer-contract/bundle.js";
+
+type TrustedSessionState<Contract extends ReducerGameContractLike> =
+  BaseGameSessionOfContract<Contract>;
+
+type TrustedCombinedState<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+> = BaseGameStateOfContract<Contract> & {
+  runtime: TrustedSessionState<Contract>["runtime"];
+};
+
+type TrustedPlayerId<
+  Contract extends ReducerGameContractLike,
+  _Definitions extends PhaseMapOf<Contract>,
+> = PlayerIdOfState<BaseGameStateOfContract<Contract>>;
+
+export type TrustedReducerBundle<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = {
+  initialize(input: {
+    table: BaseGameStateOfContract<Contract>["table"];
+    playerIds: TrustedPlayerId<Contract, Definitions>[];
+    rngSeed?: number | null;
+    setup?: RuntimeSetupSelectionInput<ManifestContractOf<Contract>> | null;
+  }): Promise<TrustedSessionState<Contract>>;
+  initializePhase(input: {
+    state: TrustedSessionState<Contract>;
+    to: PhaseNamesOfDefinition<
+      ReducerGameDefinition<Contract, Definitions, Views>
+    >;
+  }): Promise<TrustedSessionState<Contract>>;
+  validateInput(input: {
+    state: TrustedSessionState<Contract>;
+    input: TrustedRuntimeInput<TrustedPlayerId<Contract, Definitions>>;
+  }): Promise<ReducerValidationResult>;
+  reduce(input: {
+    state: TrustedSessionState<Contract>;
+    input: TrustedRuntimeInput<TrustedPlayerId<Contract, Definitions>>;
+  }): Promise<
+    | ReducerReject
+    | {
+        type: "accept";
+        state: TrustedSessionState<Contract>;
+        instructions: RuntimeInstructionForState<
+          TrustedCombinedState<Contract, Definitions>
+        >[];
+      }
+  >;
+  dispatch(input: {
+    state: TrustedSessionState<Contract>;
+    input: TrustedRuntimeInput<TrustedPlayerId<Contract, Definitions>>;
+  }): Promise<
+    | ReducerReject
+    | {
+        type: "accept";
+        state: TrustedSessionState<Contract>;
+        trace: DispatchTraceEntry<
+          TrustedCombinedState<Contract, Definitions>,
+          TrustedPlayerId<Contract, Definitions>
+        >[];
+      }
+  >;
+  projectStatic(): {
+    view: unknown;
+    hash: string;
+    manifestVersion: string;
+  } | null;
+  projectSeatsDynamic(input: {
+    state: TrustedSessionState<Contract>;
+    playerIds: TrustedPlayerId<Contract, Definitions>[];
+    viewId?: string;
+    projectionMode?: "full" | "actionsOnly";
+  }): {
+    currentStage: string | null;
+    stageSeats: string[];
+    simultaneousPhase: {
+      phaseName: string;
+      interactionId: string;
+      actorIds: string[];
+      sealedPlayerIds: string[];
+      pendingPlayerIds: string[];
+    } | null;
+    seats: Record<
+      string,
+      {
+        view?: unknown;
+        availableInteractionRefs: unknown;
+        zones?: unknown;
+      }
+    >;
+    interactionsByRef: Record<string, unknown>;
+  };
+  projectSeatViewDynamic(input: {
+    state: TrustedSessionState<Contract>;
+    playerId: TrustedPlayerId<Contract, Definitions>;
+    viewId?: string;
+  }): unknown;
+};
+
+export type ReducerBundle = ReducerBundleContract & {
+  createInProcessRuntime(): {
+    initialize(input: {
+      table: unknown;
+      playerIds: string[];
+      rngSeed?: number | null;
+      setup?: unknown;
+    }): Promise<void>;
+    hydrate(input: { state: unknown }): void;
+    dispatch(input: {
+      input: unknown;
+    }): Promise<
+      | { kind: "accept" }
+      | { kind: "accept"; state: unknown; trace: unknown[] }
+      | { kind: "reject"; errorCode: string; message?: string }
+    >;
+    projectSeatViewDynamic(input: {
+      playerId: unknown;
+      viewId?: string;
+    }): unknown;
+    projectSeatsDynamic(input: {
+      playerIds: unknown[];
+      viewId?: string;
+      projectionMode?: "full" | "actionsOnly";
+    }): {
+      currentStage: string | null;
+      stageSeats: string[];
+      simultaneousPhase: {
+        phaseName: string;
+        interactionId: string;
+        actorIds: string[];
+        sealedPlayerIds: string[];
+        pendingPlayerIds: string[];
+      } | null;
+      seats: Record<
+        string,
+        {
+          view?: unknown;
+          availableInteractionRefs: unknown;
+          zones?: unknown;
+        }
+      >;
+      interactionsByRef: Record<string, unknown>;
+    };
+    snapshot(): unknown;
+    unsafeState(): unknown;
+  };
+  projectSeatViewDynamic(input: {
+    state: unknown;
+    playerId: unknown;
+    viewId?: string;
+  }): unknown;
+};

package/src/reducer/bundle.ts

@@ -0,0 +1,2 @@
+export { createReducerBundle } from "./bundle/ingress-bundle";
+export type { ReducerBundle } from "./bundle/types";

package/src/reducer/client-param-schemas.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { collectReducerDefinitionIndex } from "./definition-index";
+import type {
+  InputCollector,
+  PhaseMapOf,
+  ReducerGameContractLike,
+  ReducerGameDefinition,
+  ViewMapOf,
+} from "./model";
+
+export type ClientParamSchema = {
+  safeParse: (value: unknown) =>
+    | { success: true; data: Record<string, unknown> }
+    | {
+        success: false;
+        error: { issues: Array<{ path: PropertyKey[]; message: string }> };
+      };
+};
+
+export type ClientParamSchemasByPhase = Readonly<
+  Record<string, Readonly<Record<string, ClientParamSchema>>>
+>;
+
+function schemaForCollectors(
+  collectors: Record<string, InputCollector>,
+): ClientParamSchema {
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const [key, collector] of Object.entries(collectors)) {
+    if (collector.kind === "rng") continue;
+    const schema = collector.schema as z.ZodTypeAny;
+    shape[key] =
+      "defaultValue" in collector
+        ? schema.default(collector.defaultValue)
+        : schema;
+  }
+  return z.object(shape) as unknown as ClientParamSchema;
+}
+
+export function createClientParamSchemasByPhase<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  definition: ReducerGameDefinition<Contract, Definitions, Views>,
+): ClientParamSchemasByPhase {
+  const index = collectReducerDefinitionIndex(definition);
+  const out: Record<string, Record<string, ClientParamSchema>> = {};
+  for (const phaseIndex of index.phasesByName.values()) {
+    const phaseSchemas: Record<string, ClientParamSchema> = {};
+    for (const [id, interaction] of phaseIndex.interactions) {
+      phaseSchemas[id] =
+        interaction.paramsSchema ?? schemaForCollectors(interaction.inputs);
+    }
+    out[String(phaseIndex.phaseName)] = phaseSchemas;
+  }
+  return out;
+}

package/src/reducer/compose.ts

@@ -0,0 +1,34 @@
+/**
+ * State composition primitives.
+ *
+ * `pipe` threads a seed state through a sequence of `State -> State`
+ * transformations, left to right. It is the preferred way to compose curried
+ * writers (the `ops.*` namespace) in reducers:
+ *
+ *     return accept(
+ *       pipe(state,
+ *         ops.spendPlayerResources({ playerId, resources: cost }),
+ *         ops.placePieceOnVertex({ boardId, vertexId, pieceId, ownerId: playerId }),
+ *       ),
+ *     );
+ */
+/**
+ * A state-preserving transformation.
+ *
+ * `Op<State>` is polymorphic in the exact input subtype — given a state `S`
+ * that extends `State`, it returns the same `S`. This lets curried writers
+ * from `ops.*` and author-written helpers thread through phase-scoped `pipe`
+ * calls without losing the narrowed phase state type.
+ */
+export type Op<State> = <S extends State>(state: S) => S;
+
+export function pipe<State>(
+  state: State,
+  ...ops: ReadonlyArray<Op<NoInfer<State>>>
+): State {
+  let result = state;
+  for (const op of ops) {
+    result = op(result);
+  }
+  return result;
+}

package/src/reducer/core/runtime-input.ts

@@ -0,0 +1,30 @@
+import type { RuntimePayload } from "../model";
+
+export type TrustedInteractionInput<PlayerId extends string> = {
+  // Canonical single-kind player-originated input. `interactionId` addresses
+  // either an ordinary action or an addressed prompt; the trusted bundle
+  // disambiguates from the interaction spec.
+  kind: "interaction";
+  playerId: PlayerId;
+  interactionId: string;
+  params: RuntimePayload;
+};
+
+export type TrustedContinuationInput = {
+  // Engine-internal input produced by resolved runtime instructions
+  // (e.g. after fx.rollDie) to route a typed continuation back through reduce.
+  // External clients never send this kind.
+  kind: "continuation";
+  continuationId: string;
+  resumeData: RuntimePayload;
+  source: "effect";
+  effectKind: "rollDie" | "shuffleSharedZone" | "shufflePlayerZone";
+  response: RuntimePayload;
+};
+
+export type TrustedRuntimeInput<PlayerId extends string> =
+  | TrustedInteractionInput<PlayerId>
+  | TrustedContinuationInput;
+
+export type DecodedReducerInput<PlayerId extends string> =
+  TrustedRuntimeInput<PlayerId>;

package/src/reducer/core/runtime-instruction.ts

@@ -0,0 +1,59 @@
+import type {
+  DeckIdOfState,
+  PhaseNameOfState,
+  PlayerIdOfState,
+  PlayerZoneIdOfState,
+} from "../model/extract";
+import type { AnyContinuationToken } from "../model/runtime";
+
+export type FlowInstruction<PhaseName extends string> = {
+  kind: "flow.transition";
+  to: PhaseName;
+};
+
+export type EngineRollDieInstruction = {
+  kind: "engine.rollDie";
+  dieId: string;
+  continuation?: AnyContinuationToken;
+};
+
+export type EngineShuffleSharedZoneInstruction<DeckId extends string> = {
+  kind: "engine.shuffleSharedZone";
+  zoneId: DeckId;
+  continuation?: AnyContinuationToken;
+};
+
+export type EngineShufflePlayerZoneInstruction<
+  PlayerZoneId extends string,
+  PlayerId extends string,
+> = {
+  kind: "engine.shufflePlayerZone";
+  zoneId: PlayerZoneId;
+  playerId: PlayerId;
+  continuation?: AnyContinuationToken;
+};
+
+export type EngineInstruction<
+  DeckId extends string,
+  PlayerZoneId extends string = string,
+  PlayerId extends string = string,
+> =
+  | EngineRollDieInstruction
+  | EngineShuffleSharedZoneInstruction<DeckId>
+  | EngineShufflePlayerZoneInstruction<PlayerZoneId, PlayerId>;
+
+export type RuntimeInstruction<
+  PhaseName extends string,
+  DeckId extends string,
+  PlayerZoneId extends string = string,
+  PlayerId extends string = string,
+> =
+  | FlowInstruction<PhaseName>
+  | EngineInstruction<DeckId, PlayerZoneId, PlayerId>;
+
+export type RuntimeInstructionForState<State> = RuntimeInstruction<
+  PhaseNameOfState<State>,
+  DeckIdOfState<State>,
+  PlayerZoneIdOfState<State>,
+  PlayerIdOfState<State>
+>;