@dreamboard-games/sdk 0.2.1-alpha.1 → 0.3.0-alpha.1

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

@@ -1,57 +0,0 @@
-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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,30 +0,0 @@
-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

@@ -1,59 +0,0 @@
-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>
->;

package/src/reducer/core/types.ts

@@ -1,62 +0,0 @@
-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

@@ -1,277 +0,0 @@
-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

@@ -1,106 +0,0 @@
-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;
-}