Files
wikideck/server/game/engine-port.ts
claudeanderic dbb89ce9c5 Night 2: 40-card Magic-style duel, PvP with owned decks, polite Wikimedia client, Android mining (#23)
Night 2 (2026-11-17), from the `claude/wikideck` fork's `night/2026-11-17` branch. It follows Night 1 (#22).

## What's in it
- **Duel engine** (fork #72, #80): 40-card decks of cards you own, Notability/Citations, keywords, effects T1–T12, Connected, a hidden-information-safe `viewFor`/`logFor`, and replay. Balance v1 tuning (#84) gives the first player about 51%.
- **Card profiles** (#70, #82): Figure, Location, Event, Institution or Doctrine, plus stats, keywords and rules text, all derived from real article data. Templates only.
- **Design and story** (#66, #69, #83): DUEL_DESIGN.md, plus the match log and the encyclopedic "Battle of X (2026)" recap.
- **PvP** (#74, #77, #81, #76, #85):
  - The server checks ownership, and 40-card eligibility is enforced.
  - Modes: Classic (ranked), Draft and Trending.
  - Invites, quick match, Elo, a ladder and recap pages. Online matches render on the duel board.
- **Duel board UI** (#79): MTG-style card faces and combat declaration, built for 360 px first.
- **Polite Wikimedia client** (#73, #75): throttled, cached and identified requests, the mint-path fix, and a prefetch pool.
- **Android mining** (#78): native RandomX, as a sideload build. The emulator mined a testnet block.
- **Testnet ops** (#67, #68).

PR numbers refer to `claude/wikideck`.

## Status
- **Tests:** 423, of which 422 pass, 0 fail and 1 is skipped. The build is OK (`node:24-alpine`, `--network none`).
- **Testnet:** running this commit (036489c) on r350.
- **Untouched:** no changes to `server/testnet/consensus.ts`, `randomx.ts`, `native/` or the mainnet compose.
- **Review:** night-review reviewed fork #66–#79. #80–#85 came from the agents' unfinished branches and were not reviewed.
- **Known gaps:**
  - The PvP end-to-end test hasn't been run (it needs two eom.dev accounts).
  - Bot matches aren't reachable from Play.
  - Card identity pre-bake hasn't been done.
  - The RandomX verifier latch (`server/testnet/randomx.ts:140`) is still open.

This PR is for Eric to merge.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: WikiDeck/wikideck#23

Co-authored-by: Claude <claude@eom.dev>
2026-11-18 18:12:24 +00:00

74 lines
3.8 KiB
TypeScript

/**
* The slice of the engine API (docs/game/ENGINE_API.md) the mode host uses.
* The host is engine-agnostic behind this port: the real binding lives in engine-binding.ts,
* tests use a tiny stub. Card and state values are opaque to the host.
*/
export type Seat = 0 | 1;
export type MatchOutcome = { winner: Seat | null; reason?: string };
export interface EnginePort<Rules = unknown, Card = unknown, State = unknown, Action = unknown> {
readonly defaultRuleset: Rules;
/** Strict engine-side validation of a merged ruleset. Throws on anything invalid. */
parseRuleset(value: unknown): Rules;
deckSize(rules: Rules): number;
starterDeck(rules: Rules, seed: string): Card[];
/** Deterministic pool of non-NFT preview cards, for draft modes. */
previewPool(rules: Rules, seed: string, size: number): Card[];
/** Throws if the deck is not legal under the rules. */
validateDeck(rules: Rules, cards: Card[]): void;
cardPower(card: Card): number;
withPower(card: Card, power: number): Card;
/** Wikipedia page id of a card, if it has one (for live/trending mappings). */
cardPageId(card: Card): number | null;
/** Public, JSON-safe summary shown in a draft pool. */
cardSummary(card: Card): unknown;
createMatch(rules: Rules, decks: [Card[], Card[]], seed: string): State;
legalActions(state: State, seat: Seat): Action[];
applyAction(state: State, seat: Seat, action: Action): State;
/** Optional engine-level concede, so a resignation is part of the replayable action log. */
concedeAction?(seat: Seat): Action;
/** Optional host-only timeout action, applied when a seat runs out of turn time. */
timeoutAction?(seat: Seat): Action;
/** Optional per-turn time limit from the ruleset, in seconds. */
turnSeconds?(rules: Rules): number;
/** Optional per-seat time bank (seconds), spent once a turn runs past `turnSeconds`. */
bankSeconds?(rules: Rules): number;
/** Optional current turn number, so the host can time turns rather than actions. */
turnOf?(state: State): number;
/** Optional: freeze live data onto a card at match start (e.g. a trend arrow). */
applyLive?(rules: Rules, card: Card, live: { trendPercent: number | null }): Card;
isOver(state: State): boolean;
result(state: State): MatchOutcome;
/** What one seat may see (hides the opponent's hand and staged plays). */
viewFor(state: State, seat: Seat): unknown;
/**
* Build a match card from an owned NFT the ownership layer resolved from its block on the
* chain. Required for constructed and collection-draft modes. Must be deterministic: the
* same block gives the same card (derive once, freeze).
*/
fromChain?(rules: Rules, card: ChainCard): Card;
/** Copies of one Wikipedia page allowed in a deck (MTG-style 4); default 4. */
copyLimit?(rules: Rules): number;
/** Optional per-seat match log (past tense, no hidden information), stored with the record. */
logFor?(state: State, seat: Seat): unknown;
}
/** One owned NFT as built by server/game/ownership.ts from its block (never from client JSON). */
export type ChainCard = { tokenId: string; owner: string; confirmations: number; pageId: number; title: string; [k: string]: unknown };
/** An eom.dev (Dex) account, verified from an ID token. */
export type SeatAccount = { sub: string; issuer: string; name: string; username?: string };
/**
* What the host needs from server/game/ownership.ts (#57). Errors carry an HTTP `status`
* (400/401/403) and a player-facing message; the host passes both through.
*/
export interface OwnershipPort {
verifyAccount(idToken: unknown): Promise<SeatAccount>;
resolveDeck(account: SeatAccount, tokenIds: unknown,
opts: { deckSize: number; maxCopiesPerPage: number; minConfirmations: number }): Promise<ChainCard[]>;
/** Every card the account owns across its linked wallets. */
collection(account: SeatAccount): Promise<ChainCard[]>;
}