@dreamboard-games/sdk 0.2.0

package/src/reducer/core/types.ts

@@ -0,0 +1,62 @@
+import type { RuntimeInstructionForState } from "./runtime-instruction";
+import type { TrustedRuntimeInput } from "./runtime-input";
+
+export type DispatchTraceEntry<
+  State,
+  PlayerId extends string = string,
+  Input extends TrustedRuntimeInput<PlayerId> = TrustedRuntimeInput<PlayerId>,
+> =
+  | {
+      type: "acceptedClientInput";
+      input: Input;
+    }
+  | {
+      type: "appliedInstruction";
+      instruction: RuntimeInstructionForState<State>;
+    }
+  | {
+      type: "rngConsumption";
+      operation: string;
+      traceEntry: string;
+    };
+
+export type TrustedReducerDispatchResult<State, PlayerId extends string> =
+  | {
+      type: "reject";
+      errorCode: string;
+      message?: string;
+    }
+  | {
+      type: "accept";
+      state: State;
+      trace: DispatchTraceEntry<State, PlayerId>[];
+    };
+
+export type TrustedInstructionResolutionResult<
+  State,
+  PlayerId extends string,
+  Input extends TrustedRuntimeInput<PlayerId> = TrustedRuntimeInput<PlayerId>,
+> = {
+  state: State;
+  queuedInputs: Input[];
+  queuedInstructions: RuntimeInstructionForState<State>[];
+  trace: DispatchTraceEntry<State, PlayerId, Input>[];
+};
+
+export type TrustedReducerEngine<State, PlayerId extends string> = {
+  dispatch: (
+    state: State,
+    input: TrustedRuntimeInput<PlayerId>,
+  ) => TrustedReducerDispatchResult<State, PlayerId>;
+  drainInstructions: (
+    state: State,
+    instructions: RuntimeInstructionForState<State>[],
+  ) => State;
+};
+
+export type {
+  DecodedReducerInput,
+  TrustedContinuationInput,
+  TrustedInteractionInput,
+  TrustedRuntimeInput,
+} from "./runtime-input";

package/src/reducer/definition-index.ts

@@ -0,0 +1,277 @@
+import { cardInput } from "./inputs/cardInput";
+import { cardTarget } from "./inputs/cardTarget";
+import type {
+  AnyCardActionSpec,
+  AnyContinuationCallable,
+  AnyInteractionSpec,
+  BaseGameStateOfContract,
+  EffectMap,
+  InputCollector,
+  InteractionMap,
+  ManifestContractOf,
+  PhaseDefinition,
+  PhaseMapOf,
+  PhaseNamesOfDefinition,
+  ReducerGameContractLike,
+  ReducerGameDefinition,
+  SchemaLike,
+  StageMap,
+  StageSpec,
+  ViewMapOf,
+  PhaseZoneList,
+  PlayerZoneIdOfManifest,
+} from "./model";
+
+export type ReducerIndexedPhase<Contract extends ReducerGameContractLike> =
+  PhaseDefinition<
+    SchemaLike<object>,
+    BaseGameStateOfContract<Contract>,
+    ManifestContractOf<Contract>,
+    Record<string, InputCollector>,
+    EffectMap<BaseGameStateOfContract<Contract>, ManifestContractOf<Contract>>,
+    InteractionMap<
+      BaseGameStateOfContract<Contract>,
+      ManifestContractOf<Contract>
+    >,
+    StageMap<BaseGameStateOfContract<Contract>, ManifestContractOf<Contract>>,
+    PhaseZoneList<ManifestContractOf<Contract>>
+  >;
+
+export type ReducerIndexedInteractionEntry<
+  Contract extends ReducerGameContractLike,
+> = readonly [
+  string,
+  AnyInteractionSpec<
+    BaseGameStateOfContract<Contract>,
+    ManifestContractOf<Contract>
+  >,
+];
+
+export type ReducerIndexedStageEntry<Contract extends ReducerGameContractLike> =
+  readonly [
+    string,
+    StageSpec<BaseGameStateOfContract<Contract>, ManifestContractOf<Contract>>,
+  ];
+
+export type ReducerIndexedZoneEntry<Contract extends ReducerGameContractLike> =
+  PlayerZoneIdOfManifest<ManifestContractOf<Contract>>;
+
+export type ReducerIndexedCardActionEntry<
+  Contract extends ReducerGameContractLike,
+> = readonly [
+  string,
+  AnyCardActionSpec<
+    BaseGameStateOfContract<Contract>,
+    ManifestContractOf<Contract>
+  >,
+];
+
+export type ReducerIndexedEffectEntry<
+  Contract extends ReducerGameContractLike,
+> = readonly [
+  string,
+  {
+    readonly id: string;
+    readonly type: string;
+    readonly continuation?: AnyContinuationCallable<
+      BaseGameStateOfContract<Contract>
+    > & {
+      readonly id?: string;
+    };
+  },
+];
+
+export interface ReducerDefinitionPhaseIndex<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> {
+  readonly phaseName: PhaseNamesOfDefinition<
+    ReducerGameDefinition<Contract, Definitions, Views>
+  >;
+  readonly phase: ReducerIndexedPhase<Contract>;
+  readonly interactions: ReadonlyArray<
+    ReducerIndexedInteractionEntry<Contract>
+  >;
+  readonly stages: ReadonlyArray<ReducerIndexedStageEntry<Contract>>;
+  readonly zones: ReadonlyArray<ReducerIndexedZoneEntry<Contract>>;
+  readonly cardActions: ReadonlyArray<ReducerIndexedCardActionEntry<Contract>>;
+  readonly effects: ReadonlyArray<ReducerIndexedEffectEntry<Contract>>;
+}
+
+export interface ReducerDefinitionIndex<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> {
+  readonly phaseEntries: ReadonlyArray<
+    readonly [
+      PhaseNamesOfDefinition<
+        ReducerGameDefinition<Contract, Definitions, Views>
+      >,
+      ReducerIndexedPhase<Contract>,
+    ]
+  >;
+  readonly phasesByName: ReadonlyMap<
+    PhaseNamesOfDefinition<ReducerGameDefinition<Contract, Definitions, Views>>,
+    ReducerDefinitionPhaseIndex<Contract, Definitions, Views>
+  >;
+}
+
+type RawEffectEntry<Contract extends ReducerGameContractLike> = readonly [
+  string,
+  {
+    id?: string;
+    type?: string;
+    __continuation?: AnyContinuationCallable<
+      BaseGameStateOfContract<Contract>
+    > & {
+      id?: string;
+    };
+  },
+];
+
+function phaseEntriesOf<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  definition: ReducerGameDefinition<Contract, Definitions, Views>,
+): Array<
+  readonly [
+    PhaseNamesOfDefinition<ReducerGameDefinition<Contract, Definitions, Views>>,
+    ReducerIndexedPhase<Contract>,
+  ]
+> {
+  type PhaseName = PhaseNamesOfDefinition<
+    ReducerGameDefinition<Contract, Definitions, Views>
+  >;
+  return Object.entries(definition.phases) as unknown as Array<
+    readonly [PhaseName, ReducerIndexedPhase<Contract>]
+  >;
+}
+
+function interactionEntriesOf<Contract extends ReducerGameContractLike>(
+  phase: ReducerIndexedPhase<Contract>,
+): Array<ReducerIndexedInteractionEntry<Contract>> {
+  return Object.entries(
+    (phase as { interactions?: Record<string, unknown> }).interactions ?? {},
+  ) as Array<ReducerIndexedInteractionEntry<Contract>>;
+}
+
+function simultaneousSubmitEntriesOf<Contract extends ReducerGameContractLike>(
+  phase: ReducerIndexedPhase<Contract>,
+): Array<ReducerIndexedInteractionEntry<Contract>> {
+  const submit = (phase as { submit?: unknown }).submit;
+  if (!submit) return [];
+  return [
+    ["submit", submit] as unknown as ReducerIndexedInteractionEntry<Contract>,
+  ];
+}
+
+function cardActionEntriesOf<Contract extends ReducerGameContractLike>(
+  phase: ReducerIndexedPhase<Contract>,
+): Array<ReducerIndexedCardActionEntry<Contract>> {
+  return Object.entries(
+    (phase as { cardActions?: Record<string, unknown> }).cardActions ?? {},
+  ) as Array<ReducerIndexedCardActionEntry<Contract>>;
+}
+
+function stageEntriesOf<Contract extends ReducerGameContractLike>(
+  phase: ReducerIndexedPhase<Contract>,
+): Array<ReducerIndexedStageEntry<Contract>> {
+  return Object.entries(
+    (phase as { stages?: Record<string, unknown> }).stages ?? {},
+  ) as Array<ReducerIndexedStageEntry<Contract>>;
+}
+
+function zoneEntriesOf<Contract extends ReducerGameContractLike>(
+  phase: ReducerIndexedPhase<Contract>,
+): Array<ReducerIndexedZoneEntry<Contract>> {
+  return Array.from(
+    (phase as { zones?: readonly unknown[] }).zones ?? [],
+  ) as Array<ReducerIndexedZoneEntry<Contract>>;
+}
+
+function effectEntriesOf<Contract extends ReducerGameContractLike>(
+  phase: ReducerIndexedPhase<Contract>,
+): Array<RawEffectEntry<Contract>> {
+  return Object.entries(
+    (phase as { effects?: Record<string, unknown> }).effects ?? {},
+  ) as Array<RawEffectEntry<Contract>>;
+}
+
+export function collectReducerDefinitionIndex<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  definition: ReducerGameDefinition<Contract, Definitions, Views>,
+): ReducerDefinitionIndex<Contract, Definitions, Views> {
+  type State = BaseGameStateOfContract<Contract>;
+  type Manifest = ManifestContractOf<Contract>;
+  type PhaseName = PhaseNamesOfDefinition<
+    ReducerGameDefinition<Contract, Definitions, Views>
+  >;
+
+  const phaseEntries = phaseEntriesOf(definition);
+  const phasesByName = new Map<
+    PhaseName,
+    ReducerDefinitionPhaseIndex<Contract, Definitions, Views>
+  >();
+
+  for (const [phaseName, phase] of phaseEntries) {
+    const interactionEntries = [
+      ...interactionEntriesOf(phase),
+      ...simultaneousSubmitEntriesOf(phase),
+    ];
+    const cardActionEntries: Array<ReducerIndexedInteractionEntry<Contract>> =
+      cardActionEntriesOf(phase).map(([cardActionId, cardAction]) => [
+        cardActionId,
+        {
+          ...cardAction,
+          __steps: cardAction.__steps,
+          inputs: {
+            cardId: cardInput<State>({
+              target: cardTarget
+                .zones<State>([cardAction.playFrom])
+                .where({
+                  id: "card-type",
+                  errorCode: "WRONG_CARD_TYPE",
+                  message: `Card must be ${cardAction.cardType}.`,
+                  test: ({ q, targetId }) =>
+                    q.card.get(targetId).cardType === cardAction.cardType,
+                })
+                .build(),
+            }),
+            ...(cardAction.inputs ?? {}),
+          },
+        } satisfies AnyInteractionSpec<State, Manifest>,
+      ]);
+    const effects: Array<ReducerIndexedEffectEntry<Contract>> = effectEntriesOf(
+      phase,
+    ).map(([effectKey, effectValue]) => [
+      effectKey,
+      {
+        id: effectValue.id ?? effectKey,
+        type: effectValue.type ?? "rollDie",
+        continuation: effectValue.__continuation,
+      },
+    ]);
+
+    phasesByName.set(phaseName, {
+      phaseName,
+      phase,
+      interactions: [...interactionEntries, ...cardActionEntries],
+      stages: stageEntriesOf(phase),
+      zones: zoneEntriesOf(phase),
+      cardActions: cardActionEntriesOf(phase),
+      effects,
+    });
+  }
+
+  return {
+    phaseEntries,
+    phasesByName,
+  };
+}

package/src/reducer/derived.ts

@@ -0,0 +1,106 @@
+import type { RuntimeTableRecord } from "./model/table";
+import type { TableQueriesOfState } from "./model/queries";
+import type { BaseGameStateOfContract } from "./model/definition";
+import { createStateQueries } from "./table-queries";
+
+/**
+ * A freestanding, memoized projection of immutable game state.
+ *
+ * Use `defineDerived` for values that are pure functions of component
+ * locations, zone contents, resources, or other state fields - and are
+ * consumed from multiple reducer or view call sites, or whose compute cost
+ * is non-trivial (graph walks, aggregate reductions).
+ *
+ * Do NOT cache derived values in `publicState`. State fields should be
+ * inputs to derivations, not mirrors of them.
+ */
+export type DerivedDefinition<Contract, Value> = {
+  /** Optional label for debugging. Does not affect caching. */
+  readonly name?: string;
+  readonly compute: (ctx: {
+    readonly state: BaseGameStateOfContract<Contract>;
+    readonly q: TableQueriesOfState<BaseGameStateOfContract<Contract>>;
+    readonly derived: DerivedResolver;
+  }) => Value;
+};
+
+/**
+ * Resolves a `DerivedDefinition` to its value. Callers do not need to know
+ * about memoization - the resolver handles caching internally.
+ */
+export type DerivedResolver = <Value>(
+  def: DerivedDefinition<never, Value>,
+) => Value;
+
+type AnyDerivedDefinition = DerivedDefinition<unknown, unknown>;
+
+/**
+ * Author-facing factory for creating a derived value tied to a game
+ * contract. Usage:
+ *
+ * ```ts
+ * export const longestRoad = defineDerived<GameContract>()({
+ *   name: "longestRoad",
+ *   compute: ({ q, derived }) => computeLongestRoad(q),
+ * });
+ * ```
+ */
+export function defineDerived<Contract>() {
+  return <Value>(def: {
+    name?: string;
+    compute: (ctx: {
+      state: BaseGameStateOfContract<Contract>;
+      q: TableQueriesOfState<BaseGameStateOfContract<Contract>>;
+      derived: DerivedResolver;
+    }) => Value;
+  }): DerivedDefinition<Contract, Value> => def;
+}
+
+/**
+ * Creates a resolver scoped to a single state snapshot. Each engine tick
+ * and each view projection call creates its own resolver; cache lifetime
+ * ends with the call. Cache key is the `DerivedDefinition` identity (the
+ * object reference).
+ *
+ * Re-entry on an in-flight definition throws a readable error.
+ */
+export function createDerivedResolver<
+  State extends { table: RuntimeTableRecord },
+>(
+  state: State,
+  options: { q?: TableQueriesOfState<State> } = {},
+): DerivedResolver {
+  const cache = new Map<AnyDerivedDefinition, unknown>();
+  const inflight = new Set<AnyDerivedDefinition>();
+  const q = options.q ?? createStateQueries(state);
+
+  const resolver: DerivedResolver = <Value>(
+    def: DerivedDefinition<never, Value>,
+  ): Value => {
+    const typedDef = def as unknown as AnyDerivedDefinition;
+    if (cache.has(typedDef)) {
+      return cache.get(typedDef) as Value;
+    }
+    if (inflight.has(typedDef)) {
+      throw new Error(
+        `Cyclic derived: '${def.name ?? "<anonymous>"}' depends on itself.`,
+      );
+    }
+    inflight.add(typedDef);
+    try {
+      const value = (
+        def.compute as unknown as (ctx: {
+          state: unknown;
+          q: unknown;
+          derived: DerivedResolver;
+        }) => Value
+      )({ state, q, derived: resolver });
+      cache.set(typedDef, value);
+      return value;
+    } finally {
+      inflight.delete(typedDef);
+    }
+  };
+
+  return resolver;
+}

package/src/reducer/effects.ts

@@ -0,0 +1,92 @@
+import type {
+  AnyContinuationToken,
+  EffectSpecLike,
+  ReducerFx,
+  RuntimeTableRecord,
+} from "./model";
+
+type FxState = {
+  table: RuntimeTableRecord;
+  flow: { currentPhase: string };
+};
+
+type InternalEffectDefinition = EffectSpecLike;
+
+function buildResume(
+  effect: InternalEffectDefinition,
+  context: unknown,
+): AnyContinuationToken | undefined {
+  if (!effect.__continuation) {
+    return undefined;
+  }
+  return (effect.__continuation as unknown as (data: unknown) => unknown)(
+    context ?? {},
+  ) as AnyContinuationToken;
+}
+
+function invokeEffect(
+  effect: InternalEffectDefinition,
+  options: Record<string, unknown>,
+) {
+  const continuation = buildResume(effect, options.context);
+  if (effect.type === "rollDie") {
+    return continuation === undefined
+      ? {
+          kind: "engine.rollDie" as const,
+          dieId: options.dieId as string,
+        }
+      : {
+          kind: "engine.rollDie" as const,
+          dieId: options.dieId as string,
+          continuation,
+        };
+  }
+  if (effect.type === "shuffleSharedZone") {
+    return continuation === undefined
+      ? {
+          kind: "engine.shuffleSharedZone" as const,
+          zoneId: options.zoneId as string,
+        }
+      : {
+          kind: "engine.shuffleSharedZone" as const,
+          zoneId: options.zoneId as string,
+          continuation,
+        };
+  }
+  if (effect.type === "shufflePlayerZone") {
+    return continuation === undefined
+      ? {
+          kind: "engine.shufflePlayerZone" as const,
+          zoneId: options.zoneId as string,
+          playerId: options.playerId as string,
+        }
+      : {
+          kind: "engine.shufflePlayerZone" as const,
+          zoneId: options.zoneId as string,
+          playerId: options.playerId as string,
+          continuation,
+        };
+  }
+  throw new Error(
+    `fx.effect: unsupported effect type '${(effect as InternalEffectDefinition).type}'.`,
+  );
+}
+
+export function createReducerFx<State extends FxState>(
+  _state: State,
+): ReducerFx<State> {
+  const fx: ReducerFx<State> = {
+    transition(to) {
+      return { kind: "flow.transition", to } as ReturnType<
+        ReducerFx<State>["transition"]
+      >;
+    },
+    effect(effect, options) {
+      return invokeEffect(
+        effect as unknown as InternalEffectDefinition,
+        options as Record<string, unknown>,
+      ) as ReturnType<ReducerFx<State>["effect"]>;
+    },
+  } as ReducerFx<State>;
+  return fx;
+}

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

@@ -0,0 +1,155 @@
+import type {
+  DispatchTraceEntry,
+  TrustedReducerDispatchResult,
+  TrustedRuntimeInput,
+} from "../core/types";
+import type { RuntimeInstructionForState } from "../core/runtime-instruction";
+
+export function createRuntimeInstructionEngine<
+  State,
+  PlayerId extends string,
+  Input extends TrustedRuntimeInput<PlayerId>,
+>({
+  reduce,
+  resolveInstruction,
+  afterInput,
+}: {
+  reduce: (
+    state: State,
+    input: Input,
+  ) =>
+    | { type: "reject"; errorCode: string; message?: string }
+    | {
+        type: "accept";
+        state: State;
+        instructions?: RuntimeInstructionForState<State>[];
+      };
+  resolveInstruction: (
+    state: State,
+    instruction: RuntimeInstructionForState<State>,
+  ) => {
+    state: State;
+    queuedInputs: Input[];
+    queuedInstructions: RuntimeInstructionForState<State>[];
+    trace: DispatchTraceEntry<State, PlayerId, Input>[];
+  };
+  afterInput?: (
+    state: State,
+    input: Input,
+  ) => {
+    state: State;
+    trace: DispatchTraceEntry<State, PlayerId, Input>[];
+  };
+}) {
+  function drainInstructions(
+    state: State,
+    instructionsToDrain: RuntimeInstructionForState<State>[],
+  ): State {
+    let workingState = state;
+    const instructionQueue = [...instructionsToDrain];
+    const systemQueue: Input[] = [];
+
+    while (instructionQueue.length > 0 || systemQueue.length > 0) {
+      while (instructionQueue.length > 0) {
+        const instruction = instructionQueue.shift();
+        if (instruction === undefined) break;
+        const resolved = resolveInstruction(workingState, instruction);
+        workingState = resolved.state;
+        if (resolved.queuedInstructions.length > 0) {
+          instructionQueue.unshift(...resolved.queuedInstructions);
+        }
+        systemQueue.push(...resolved.queuedInputs);
+      }
+
+      while (systemQueue.length > 0) {
+        const input = systemQueue.shift();
+        if (input === undefined) break;
+        const result = reduce(workingState, input);
+        if (result.type === "reject") {
+          throw new Error(
+            result.message ??
+              `Reducer rejected internal input '${input.kind}'.`,
+          );
+        }
+        workingState = result.state;
+        instructionQueue.push(...(result.instructions ?? []));
+      }
+    }
+
+    return workingState;
+  }
+
+  function dispatch(
+    state: State,
+    input: Input,
+  ): TrustedReducerDispatchResult<State, PlayerId> {
+    let workingState = state;
+    const pendingInputs: Input[] = [input];
+    const trace: DispatchTraceEntry<State, PlayerId, Input>[] = [
+      {
+        type: "acceptedClientInput",
+        input,
+      },
+    ];
+
+    while (pendingInputs.length > 0) {
+      const pendingInput = pendingInputs.shift();
+      if (pendingInput === undefined) break;
+      const result = reduce(workingState, pendingInput);
+      if (result.type === "reject") {
+        if (pendingInput === input) {
+          return result;
+        }
+        throw new Error(
+          result.message ??
+            `Reducer rejected internal input '${pendingInput.kind}'.`,
+        );
+      }
+
+      workingState = result.state;
+
+      if (afterInput) {
+        const afterInputResult = afterInput(workingState, pendingInput);
+        workingState = afterInputResult.state;
+        trace.push(...afterInputResult.trace);
+      }
+
+      const instructionQueue = [...(result.instructions ?? [])];
+      const continuationQueue: Input[] = [];
+      while (instructionQueue.length > 0 || continuationQueue.length > 0) {
+        while (instructionQueue.length > 0) {
+          const instruction = instructionQueue.shift();
+          if (instruction === undefined) break;
+          trace.push({
+            type: "appliedInstruction",
+            instruction,
+          });
+          const resolved = resolveInstruction(workingState, instruction);
+          workingState = resolved.state;
+          trace.push(...resolved.trace);
+          if (resolved.queuedInstructions.length > 0) {
+            instructionQueue.unshift(...resolved.queuedInstructions);
+          }
+          continuationQueue.push(...resolved.queuedInputs);
+        }
+
+        while (continuationQueue.length > 0) {
+          const queued = continuationQueue.shift();
+          if (queued === undefined) break;
+          pendingInputs.push(queued);
+        }
+      }
+    }
+
+    return {
+      type: "accept",
+      state: workingState,
+      trace,
+    };
+  }
+
+  return {
+    dispatch,
+    drainInstructions,
+  };
+}

package/src/reducer/ingress/decode-runtime-input.ts

@@ -0,0 +1,7 @@
+export {
+  createIngressRuntimeCodec,
+  runtimePayloadSchema,
+  safeParseOrThrow,
+  type IngressRuntimeCodec,
+  type UntrustedRuntimeInput,
+} from "./runtime-codec";

package/src/reducer/ingress/decode-session-state.ts

@@ -0,0 +1,9 @@
+export {
+  createIngressRuntimeCodec,
+  runtimePayloadSchema,
+  safeParseOrThrow,
+  type DecodedReducerSession,
+  type IngressRuntimeCodec,
+  type UntrustedReducerSessionState,
+  type UntrustedRuntimeTable,
+} from "./runtime-codec";