@dreamboard-games/sdk 0.2.0

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

@@ -0,0 +1,356 @@
+import type {
+  PhaseMapOf,
+  ReducerGameContractLike,
+  ViewMapOf,
+} from "../../model";
+import type {
+  InteractionDescriptorShape,
+  createInteractionResolver,
+} from "./interaction-resolver";
+import type {
+  TrustedDomainState,
+  TrustedPhaseName,
+  TrustedPlayerId,
+  TrustedRuntimeScope,
+  TrustedSessionState,
+  TrustedState,
+} from "./runtime-scope";
+import {
+  createProjectionContext,
+  type ProjectionContext,
+} from "./projection-context";
+import { collectCardZoneIds } from "./interaction-collectors";
+import {
+  isSimultaneousPhase,
+  resolveSimultaneousActors,
+  SIMULTANEOUS_SUBMIT_INTERACTION_ID,
+  simultaneousSubmitInteraction,
+} from "./simultaneous-player";
+
+type ProjectionMode = "full" | "actionsOnly";
+type DescriptorRegistry = {
+  add(descriptor: InteractionDescriptorShape): string;
+  entries(): Record<string, InteractionDescriptorShape>;
+};
+
+type InteractionResolverFor<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> = ReturnType<typeof createInteractionResolver<Contract, Definitions, Views>>;
+
+export function createProjectionBuilder<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  scope: TrustedRuntimeScope<Contract, Definitions, Views>,
+  interactions: InteractionResolverFor<Contract, Definitions, Views>,
+) {
+  type SessionState = TrustedSessionState<Contract>;
+  type DomainState = TrustedDomainState<Contract>;
+  type State = TrustedState<Contract>;
+  type PhaseName = TrustedPhaseName<Contract, Definitions, Views>;
+  type PlayerId = TrustedPlayerId<Contract>;
+
+  function createDescriptorRegistry(): DescriptorRegistry {
+    const byRef: Record<string, InteractionDescriptorShape> = {};
+    const byHash = new Map<string, string>();
+    return {
+      add(descriptor) {
+        const fingerprint = stableStringify(descriptor);
+        const existing = byHash.get(fingerprint);
+        if (existing) return existing;
+        const base =
+          typeof descriptor.interactionId === "string" &&
+          descriptor.interactionId.length > 0
+            ? descriptor.interactionId
+            : "interaction";
+        const ref = `${base}:${fnv1a64(fingerprint)}`;
+        byHash.set(fingerprint, ref);
+        byRef[ref] = descriptor;
+        return ref;
+      },
+      entries() {
+        return byRef;
+      },
+    };
+  }
+
+  function resolveZoneHandlesFor(
+    combinedState: State,
+    playerId: PlayerId,
+    projection: ProjectionContext<DomainState, State>,
+    registry: DescriptorRegistry,
+  ) {
+    const phaseName = combinedState.flow.currentPhase as PhaseName;
+    const zoneIds = new Set<string>(scope.zonesForPhase(phaseName).map(String));
+    for (const [, interaction] of scope.interactionEntriesForPhase(phaseName)) {
+      for (const zoneId of collectCardZoneIds(interaction)) {
+        zoneIds.add(String(zoneId));
+      }
+    }
+    const zones = [...zoneIds];
+    if (zones.length === 0) return {};
+    const q = projection.q;
+    const result: Record<
+      string,
+      {
+        cardIds: string[];
+        cardViewsById: Record<string, string>;
+        playableByCardId: Record<string, string[]>;
+      }
+    > = {};
+    for (const zoneId of zones) {
+      const table = combinedState.table as {
+        decks?: Record<string, unknown>;
+        hands?: Record<string, unknown>;
+        zones?: {
+          shared?: Record<string, unknown>;
+          perPlayer?: Record<string, unknown>;
+        };
+      };
+      const isPlayerZone =
+        zoneId in (table.hands ?? {}) ||
+        zoneId in (table.zones?.perPlayer ?? {});
+      const cardIds = Array.from(
+        isPlayerZone
+          ? (q.zone.playerCards(
+              playerId as never,
+              zoneId as never,
+            ) as readonly string[])
+          : (q.zone.sharedCards(zoneId as never) as readonly string[]),
+      );
+      const cardInteractionIds = scope
+        .interactionEntriesForPhase(phaseName)
+        .filter(([, interaction]) =>
+          collectCardZoneIds(interaction).map(String).includes(zoneId),
+        )
+        .map(([interactionId]) => interactionId);
+      const cardViewsById: Record<string, string> = {};
+      const playableByCardId: Record<string, string[]> = {};
+      for (const cardId of cardIds) {
+        cardViewsById[cardId] = JSON.stringify(q.card.get(cardId as never));
+        const perCard: string[] = [];
+        for (const interactionId of cardInteractionIds) {
+          const interaction = scope.findInteractionInPhase(
+            phaseName,
+            interactionId,
+          );
+          if (!interaction) continue;
+          const cardKey = interactions.findCardInputKeyForZone(
+            interaction,
+            zoneId,
+          );
+          const params = cardKey ? { [cardKey]: cardId } : {};
+          const decision = interactions.resolveInteractionDecision({
+            state: combinedState,
+            playerId,
+            interactionId,
+            params,
+            mode: "card",
+            projection,
+          });
+          if (!decision.found || !decision.visible) continue;
+          const cardDomain = cardKey
+            ? decision.descriptor.inputs.find((input) => input.key === cardKey)
+                ?.domain
+            : undefined;
+          const cardTargets =
+            cardDomain?.type === "cardTarget" &&
+            cardDomain.projection === "resolved"
+              ? cardDomain.eligibleTargets
+              : undefined;
+          if (cardKey && !cardTargets?.includes(cardId)) {
+            continue;
+          }
+          perCard.push(
+            registry.add({
+              ...decision.descriptor,
+              zoneId,
+            }),
+          );
+        }
+        playableByCardId[cardId] = perCard;
+      }
+      result[zoneId] = {
+        cardIds,
+        cardViewsById,
+        playableByCardId,
+      };
+    }
+    return result;
+  }
+
+  function resolveCurrentStageFor(
+    combinedState: State,
+    projection?: ProjectionContext<DomainState, State>,
+  ): string {
+    const phaseName = combinedState.flow.currentPhase as PhaseName;
+    return (
+      interactions.resolveActiveStage(combinedState, phaseName, projection)
+        ?.id ?? phaseName
+    );
+  }
+
+  function resolveStageSeatsFor(state: SessionState): string[] {
+    const combinedState = scope.toCombinedState(state);
+    const phaseName = combinedState.flow.currentPhase as PhaseName;
+    const phase = scope.phaseByName(phaseName);
+    if (isSimultaneousPhase(phase)) {
+      return resolveSimultaneousActors(scope, combinedState, phase).map(String);
+    }
+    return [...state.domain.flow.activePlayers];
+  }
+
+  function resolveSimultaneousPhaseFor(state: SessionState) {
+    const combinedState = scope.toCombinedState(state);
+    const phaseName = combinedState.flow.currentPhase as PhaseName;
+    const phase = scope.phaseByName(phaseName);
+    if (!isSimultaneousPhase(phase)) return null;
+    const current = state.runtime.simultaneous?.current;
+    if (!current || current.phaseName !== phaseName) return null;
+    const submit = simultaneousSubmitInteraction(phase);
+    if (!submit) return null;
+    const actorIds = current.actors.map(String);
+    const sealedPlayerIds = actorIds.filter(
+      (playerId) => current.submissions[playerId as PlayerId] !== undefined,
+    );
+    const pendingPlayerIds = actorIds.filter(
+      (playerId) => current.submissions[playerId as PlayerId] === undefined,
+    );
+    return {
+      phaseName: String(current.phaseName),
+      interactionId: SIMULTANEOUS_SUBMIT_INTERACTION_ID,
+      actorIds,
+      sealedPlayerIds,
+      pendingPlayerIds,
+    };
+  }
+
+  function resolveViewFor(
+    combinedState: State,
+    playerId: PlayerId,
+    viewId: string,
+    projection: ProjectionContext<DomainState, State>,
+  ): unknown {
+    const views = scope.definition.views;
+    const view = views?.[viewId as keyof typeof views];
+    if (!view) {
+      return null;
+    }
+    const viewArgs = {
+      ...scope.buildContext(combinedState),
+      ...scope.runtimeHelpers,
+      fx: projection.fx,
+      q: projection.q,
+      derived: projection.derived,
+      state: projection.domainState,
+      playerId,
+    } as Parameters<typeof view.project>[0];
+    return view.project(viewArgs);
+  }
+
+  function projectSeatsDynamic({
+    state,
+    playerIds,
+    viewId = "player",
+    projectionMode = "full",
+  }: {
+    state: SessionState;
+    playerIds: PlayerId[];
+    viewId?: string;
+    projectionMode?: ProjectionMode;
+  }) {
+    const combinedState = scope.toCombinedState(state);
+    const projection = createProjectionContext({
+      combinedState,
+      domainState: scope.toDomainState(combinedState),
+    });
+    const registry = createDescriptorRegistry();
+    type SeatProjection = {
+      view?: ReturnType<typeof resolveViewFor>;
+      availableInteractionRefs: string[];
+      zones?: ReturnType<typeof resolveZoneHandlesFor>;
+    };
+    const seats: Record<string, SeatProjection> = {};
+    for (const playerId of playerIds) {
+      const availableInteractionRefs = interactions
+        .resolveAvailableInteractionsFor(combinedState, playerId, {
+          projection,
+        })
+        .map((descriptor) => registry.add(descriptor));
+      seats[playerId as unknown as string] = {
+        ...(projectionMode === "full"
+          ? {
+              view: resolveViewFor(combinedState, playerId, viewId, projection),
+              zones: resolveZoneHandlesFor(
+                combinedState,
+                playerId,
+                projection,
+                registry,
+              ),
+            }
+          : {}),
+        availableInteractionRefs,
+      };
+    }
+    return {
+      currentStage: resolveCurrentStageFor(combinedState, projection),
+      stageSeats: resolveStageSeatsFor(state),
+      simultaneousPhase: resolveSimultaneousPhaseFor(state),
+      interactionsByRef: registry.entries(),
+      seats,
+    };
+  }
+
+  function projectSeatViewDynamic({
+    state,
+    playerId,
+    viewId = "player",
+  }: {
+    state: SessionState;
+    playerId: PlayerId;
+    viewId?: string;
+  }) {
+    const combinedState = scope.toCombinedState(state);
+    const projection = createProjectionContext({
+      combinedState,
+      domainState: scope.toDomainState(combinedState),
+    });
+    return resolveViewFor(combinedState, playerId, viewId, projection);
+  }
+
+  return {
+    projectSeatsDynamic,
+    projectSeatViewDynamic,
+    resolveCurrentStageFor,
+    resolveStageSeatsFor,
+    resolveViewFor,
+    resolveZoneHandlesFor,
+  };
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+    .join(",")}}`;
+}
+
+function fnv1a64(value: string): string {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= BigInt(value.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * prime);
+  }
+  return hash.toString(16).padStart(16, "0");
+}

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

@@ -0,0 +1,39 @@
+import { createDerivedResolver, type DerivedResolver } from "../../derived";
+import { createReducerFx } from "../../effects";
+import { createStateQueries } from "../../table-queries";
+import type { RuntimeTableRecord, TableQueriesOfState } from "../../model";
+
+type ProjectionFxState = {
+  table: RuntimeTableRecord;
+  flow: { currentPhase: string };
+};
+
+export type ProjectionContext<
+  State extends { table: RuntimeTableRecord },
+  FxState extends ProjectionFxState = ProjectionFxState,
+> = {
+  readonly domainState: State;
+  readonly q: TableQueriesOfState<State>;
+  readonly derived: DerivedResolver;
+  readonly fx: ReturnType<typeof createReducerFx<FxState>>;
+  readonly eligibleTargets: Map<string, string[]>;
+  readonly stageAllowlists: Map<string, Set<string> | null>;
+};
+
+export function createProjectionContext<
+  State extends { table: RuntimeTableRecord },
+  FxState extends ProjectionFxState,
+>(options: {
+  domainState: State;
+  combinedState: FxState;
+}): ProjectionContext<State, FxState> {
+  const q = createStateQueries(options.domainState);
+  return {
+    domainState: options.domainState,
+    q,
+    derived: createDerivedResolver(options.domainState, { q }),
+    fx: createReducerFx(options.combinedState),
+    eligibleTargets: new Map(),
+    stageAllowlists: new Map(),
+  };
+}

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

@@ -0,0 +1,150 @@
+import type {
+  CollectorState,
+  InputCollector,
+  RandomHelpers,
+  RuntimeRngState,
+  SchemaLike,
+} from "../../model";
+import { nextRandomInt } from "../../rng";
+
+export type RngConsumption = {
+  operation: string;
+  traceEntry: string;
+};
+
+export type MutableRandomHelpers = {
+  random: RandomHelpers;
+  currentRng: () => RuntimeRngState;
+};
+
+export function sampleDieValue(
+  sides: number,
+  rng: RuntimeRngState,
+): {
+  value: number;
+  nextRng: RuntimeRngState;
+  consumption: RngConsumption;
+} {
+  const [offset, nextRng] = nextRandomInt(sides, rng);
+  return {
+    value: offset + 1,
+    nextRng,
+    consumption: {
+      operation: "rollDie",
+      traceEntry: nextRng.trace[nextRng.trace.length - 1] ?? "",
+    },
+  };
+}
+
+export function shuffleWithRng<T>(
+  values: readonly T[],
+  rng: RuntimeRngState,
+  operation:
+    | "shuffleSharedZone"
+    | "shufflePlayerZone"
+    | "randomSubset" = "shuffleSharedZone",
+): {
+  orderedValues: T[];
+  nextRng: RuntimeRngState;
+  consumptions: RngConsumption[];
+} {
+  const orderedValues = [...values];
+  let nextRng = rng;
+  const consumptions: RngConsumption[] = [];
+  for (
+    let lastIndex = orderedValues.length - 1;
+    lastIndex > 0;
+    lastIndex -= 1
+  ) {
+    const [swapIndex, updatedRng] = nextRandomInt(lastIndex + 1, nextRng);
+    consumptions.push({
+      operation,
+      traceEntry: updatedRng.trace[updatedRng.trace.length - 1] ?? "",
+    });
+    nextRng = updatedRng;
+    const current = orderedValues[lastIndex];
+    const swap = orderedValues[swapIndex];
+    if (current === undefined || swap === undefined) {
+      throw new Error(
+        `shuffleWithRng: invalid index (lastIndex=${lastIndex}, swapIndex=${swapIndex}, length=${orderedValues.length})`,
+      );
+    }
+    orderedValues[lastIndex] = swap;
+    orderedValues[swapIndex] = current;
+  }
+  return { orderedValues, nextRng, consumptions };
+}
+
+export function subsetWithRng<T>(
+  values: readonly T[],
+  count: number,
+  rng: RuntimeRngState,
+): {
+  values: readonly T[];
+  nextRng: RuntimeRngState;
+  consumptions: RngConsumption[];
+} {
+  if (!Number.isInteger(count) || count < 0) {
+    throw new Error("random.subset count must be a non-negative integer.");
+  }
+  if (count > values.length) {
+    throw new Error(
+      `random.subset count ${count} exceeds source length ${values.length}.`,
+    );
+  }
+  const shuffled = shuffleWithRng(values, rng, "randomSubset");
+  return {
+    values: shuffled.orderedValues.slice(0, count),
+    nextRng: shuffled.nextRng,
+    consumptions: shuffled.consumptions,
+  };
+}
+
+export function createMutableRandomHelpers(
+  rng: RuntimeRngState,
+): MutableRandomHelpers {
+  let current = rng;
+  return {
+    random: {
+      subset(options) {
+        const sampled = subsetWithRng(options.from, options.count, current);
+        current = sampled.nextRng;
+        return sampled.values;
+      },
+    },
+    currentRng: () => current,
+  };
+}
+
+export function sampleRngCollectorValue(
+  collector: InputCollector<SchemaLike<unknown>, CollectorState, "rng">,
+  rng: RuntimeRngState,
+): { value: unknown; nextRng: RuntimeRngState } {
+  const meta = collector.meta;
+  switch (meta.rng) {
+    case "d6": {
+      const count = meta.count > 0 ? meta.count : 1;
+      const values: number[] = [];
+      let nextRng = rng;
+      for (let i = 0; i < count; i += 1) {
+        const sampled = sampleDieValue(6, nextRng);
+        values.push(sampled.value);
+        nextRng = sampled.nextRng;
+      }
+      return { value: { values }, nextRng };
+    }
+    case "coin": {
+      const [offset, nextRng] = nextRandomInt(2, rng);
+      return {
+        value: { value: offset === 0 ? "heads" : "tails" },
+        nextRng,
+      };
+    }
+    default: {
+      const _exhaustive: never = meta;
+      throw new Error(
+        `Unknown rngInput kind '${String(_exhaustive)}'. Register a sampler in trusted rng-sampler.`,
+      );
+    }
+  }
+}

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

@@ -0,0 +1,120 @@
+import type {
+  AnyContinuationCallable,
+  BaseGameStateOfContract,
+  ManifestContractOf,
+  PhaseMapOf,
+  PhaseNamesOfDefinition,
+  ReducerGameContractLike,
+  ReducerGameDefinition,
+  ViewMapOf,
+} from "../../model";
+import {
+  collectReducerDefinitionIndex,
+  type ReducerDefinitionPhaseIndex,
+  type ReducerIndexedCardActionEntry,
+  type ReducerIndexedInteractionEntry,
+  type ReducerIndexedPhase,
+  type ReducerIndexedStageEntry,
+  type ReducerIndexedZoneEntry,
+} from "../../definition-index";
+
+export type TrustedErasedPhase<Contract extends ReducerGameContractLike> =
+  ReducerIndexedPhase<Contract>;
+
+export type TrustedInteractionEntry<Contract extends ReducerGameContractLike> =
+  ReducerIndexedInteractionEntry<Contract>;
+
+export type TrustedCardActionEntry<Contract extends ReducerGameContractLike> =
+  ReducerIndexedCardActionEntry<Contract>;
+
+export type TrustedStageEntry<Contract extends ReducerGameContractLike> =
+  ReducerIndexedStageEntry<Contract>;
+
+export type TrustedZoneEntry<Contract extends ReducerGameContractLike> =
+  ReducerIndexedZoneEntry<Contract>;
+
+export type TrustedContinuationRegistry<
+  Contract extends ReducerGameContractLike,
+> = ReadonlyMap<
+  string,
+  AnyContinuationCallable<BaseGameStateOfContract<Contract>>
+>;
+
+export interface TrustedPhaseRegistry<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> extends Omit<
+  ReducerDefinitionPhaseIndex<Contract, Definitions, Views>,
+  "effects"
+> {}
+
+export interface TrustedRuntimeRegistry<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+> {
+  readonly phaseEntries: ReadonlyArray<
+    readonly [
+      PhaseNamesOfDefinition<
+        ReducerGameDefinition<Contract, Definitions, Views>
+      >,
+      TrustedErasedPhase<Contract>,
+    ]
+  >;
+  readonly phasesByName: ReadonlyMap<
+    PhaseNamesOfDefinition<ReducerGameDefinition<Contract, Definitions, Views>>,
+    TrustedPhaseRegistry<Contract, Definitions, Views>
+  >;
+  readonly continuationsById: TrustedContinuationRegistry<Contract>;
+  readonly effectsById: ReadonlyMap<
+    string,
+    { readonly id: string; readonly type: string }
+  >;
+}
+
+export function collectTrustedRuntimeRegistry<
+  Contract extends ReducerGameContractLike,
+  Definitions extends PhaseMapOf<Contract>,
+  Views extends ViewMapOf<Contract>,
+>(
+  definition: ReducerGameDefinition<Contract, Definitions, Views>,
+): TrustedRuntimeRegistry<Contract, Definitions, Views> {
+  type State = BaseGameStateOfContract<Contract>;
+  type PhaseName = PhaseNamesOfDefinition<
+    ReducerGameDefinition<Contract, Definitions, Views>
+  >;
+
+  const index = collectReducerDefinitionIndex(definition);
+  const phasesByName = new Map<
+    PhaseName,
+    TrustedPhaseRegistry<Contract, Definitions, Views>
+  >();
+  const continuationsById = new Map<string, AnyContinuationCallable<State>>();
+  const effectsById = new Map<
+    string,
+    { readonly id: string; readonly type: string }
+  >();
+
+  for (const phaseIndex of index.phasesByName.values()) {
+    const { effects: _effects, ...trustedPhase } = phaseIndex;
+    phasesByName.set(phaseIndex.phaseName, trustedPhase);
+    for (const [, effect] of phaseIndex.effects) {
+      effectsById.set(effect.id, { id: effect.id, type: effect.type });
+      if (effect.continuation) {
+        const continuationId = effect.continuation.id ?? effect.id;
+        continuationsById.set(
+          continuationId,
+          effect.continuation as AnyContinuationCallable<State>,
+        );
+      }
+    }
+  }
+
+  return {
+    phaseEntries: index.phaseEntries,
+    phasesByName,
+    continuationsById,
+    effectsById,
+  };
+}