Compare commits

..
Author SHA1 Message Date
claude 2285f49903 Merge night/2026-11-17 into #77 (resolve server/game/index.ts with #74)
# Conflicts:
#	server/game/index.ts
2026-11-18 11:12:44 -05:00
claude 4c85cc865d Merge pull request '[ownership] Server-side deck ownership, collection API, 40-card eligibility (#57)' (#74) from night2/ownership/collection into night/2026-11-17 2026-11-18 16:12:32 +00:00
claude c2ea57966e Merge pull request '[wikimedia] Polite Wikimedia client, mint-path fix, disk cache, mining prefetch pool (#62)' (#73) from night2/wikimedia/client into night/2026-11-17 2026-11-18 16:12:26 +00:00
claude 1c22ad1df5 Merge pull request '[duel-design] shared/duel/story: match log + "Battle of X (2026)" recap' (#69) from night2/duel-design/story into night/2026-11-17 2026-11-18 16:12:19 +00:00
claude c12e792dcb Merge pull request '[duel-cards] Card profiles: type, Portal, stats, keywords, effects, rules text (shared/duel)' (#70) from night2/duel-cards/profiles into night/2026-11-17 2026-11-18 16:12:11 +00:00
claude 9aba28f59e Merge pull request '[duel-design] DUEL_DESIGN.md v1 (contract for 22:15)' (#66) from night2/duel-design/design-v1 into night/2026-11-17 2026-11-18 16:12:02 +00:00
claude 52551ba9aa Merge pull request '[duel-core] Duel contracts: shared/duel/types.ts, ruleset.ts, DUEL_API.md' (#72) from night2/duel-core/contracts into night/2026-11-17 2026-11-18 16:11:53 +00:00
claudeandClaude Opus 5.5 5076299e7c [duel-cards] classify: on-chain fallback (extract definition, title, mint category) before Doctrine
An empty profile typed every card as Doctrine (night-review on #61). derive() now passes
chain.article to classify/subtypeFor; full-profile results are unchanged (fixture identical).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:50:13 -05:00
claudeandClaude Opus 5.5 f881e2cd54 DUEL_DESIGN: list secondPlayerCitations among house-rule keys
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:03:44 -05:00
claudeandClaude Opus 5.5 5121fd0418 DUEL_DESIGN v1.3: balance v1 = secondPlayerCitations 1 + turnCap 40; Location rider rejected (#64)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 00:03:38 -05:00
claudeandClaude Opus 5.5 6e97e2c8ee DUEL_DESIGN v1.2: secondPlayerCitations 1 (balance v1, #64), targets, Location finding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:43:18 -05:00
claudeandClaude Opus 5.5 067de837a8 [duel-cards] Doctrines: attach + static pump on attached (DUEL_API encoding); the buff was ignored by the engine
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:23:29 -05:00
claudeandClaude Opus 5.5 ae14bc7b89 [duel-cards] connect.qid is optional (omitted without a Wikidata item), matching #72's ConnectKeys
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:52:35 -05:00
claudeandClaude Opus 5.5 3da3e5ab84 host-pvp: quick match skips stale lobbies; draft pool only for seats (review on #77)
Re-resolve the creator's deck before seating the joiner, so a stale lobby
expires without listing the joiner, and quick match moves on to the next
candidate (or opens a lobby) instead of failing the quick-matcher.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:39:00 -05:00
claudeandClaude Opus 5.5 adc78409fe host-pvp: multi-engine host, owned-deck seats, invites, quick match, Elo, ?v= polling (#56)
- Mode schema wikideck.mode/2: required `engine` (editwar | duel); Night 1
  wikideck.mode/1 documents are rejected with a clear message. Deck policies:
  constructed (owned NFT token ids, minConfirmations), starter (Edit War only),
  draft with source preview (Edit War only) or collections. limits.rated and
  limits.accountsOnly.
- ModeHost runs every engine it is given, chosen per mode. Duel modes refuse
  loaner policies at startup (BRIEF decision 1).
- Seats: eom.dev account via Dex ID token (body or JWT bearer on seat-creating
  routes), player id sha256('acct:'+iss+'\n'+sub); guests only in Edit War.
- Constructed decks resolved through an injected OwnershipPort (#57), cards built
  by the engine's fromChain; creator's deck re-resolved at join.
- Private lobbies + invite codes (GET /invites/:code, POST /invites/:code/join),
  quick match (POST /modes/:id/quick), lobby state version with 204 on ?v=.
- Elo (1200, K 24) per mode for rated account-vs-account matches, recomputed
  from matches.jsonl; records carry engine, rated, tokens. /modes/:id/ladder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:27:37 -05:00
claudeandClaude Opus 5.5 39ffe409cb story: lifeGain event, authoritative gameOver.life, document story seed (night-review #69 notes)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:16:56 -05:00
claudeandClaude Opus 5.5 79041990ed duel-core: ConnectKeys qid/cites for claim-based Linked; seed secrecy rule
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:10:16 -05:00
claudeandClaude Opus 5.5 83a3afef1b story: tokens (never cited) and drawn matches, for duel-core's LogEvent shape
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:04:39 -05:00
claudeandClaude Opus 5.5 9943de3b53 [ownership] collectionRouter: optional injected duelCard hook (#57)
Attaches duel: DuelCard to collection cards when the server has a frozen
profile (requested by ui-duel); omitted while pending, never fetches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 22:02:50 -05:00
claudeandClaude Opus 5.5 57d2fc2fc7 [duel-cards] Match duel-core's contract (#72): template ids, description, maxTokens = fewer than N
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:58:37 -05:00
claudeandClaude Opus 5.5 0ca7704767 story: public discards, factual rivalry wording, Portal ties, fixture Portals per duel-cards #70
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:55:25 -05:00
claudeandClaude Opus 5.5 6182dff1cd DUEL_DESIGN v1.1: night-review nits (public Deleted, Garrison vs Featured, clock, rivalry wording), align with duel-cards #70
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:54:35 -05:00
claudeandClaude Opus 5.5 5d5eaa5488 duel-core: adopt duel-cards card/effect shape and DUEL_DESIGN log kinds
Connected computed by the engine from frozen connect keys; tokens, fight,
multi-target plays, locationsPerTurn, timeoutsToConcede.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:49:52 -05:00
claudeandClaude Opus 5.5 a8468dd96c [duel-cards] profile.ts: build the frozen CardProfile from enrichment + wbgetentities (pure, no fetch)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:47:00 -05:00
claudeandClaude Opus 5.5 3c70f643f2 [duel-cards] Card profiles: classify, derive, effects, rules text from real data
shared/duel/classify.ts: Q-id anchors -> P31 label regex (^human$) -> P279 -> categories -> description -> Doctrine.
shared/duel/derive.ts: pure derive(chain, profile) -> DuelCard: fame cost 1-6, P+T budget per cost,
DUEL_DESIGN §4 keywords (<=2, Figures only, taxed), Portals, Connected keys and tiers, flavour.
shared/duel/effects.ts + text.ts: T1-T12 templates as EffectSpec data, MTG-register rules text.
shared/duel/sample.ts + docs/game/duel-card-sample.json: 236-card DuelCard fixture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:43:59 -05:00
claudeandClaude Opus 5.5 26ca8e2f27 shared/duel/story: deterministic match log and Battle of X recap, golden tests
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:43:32 -05:00
claudeandClaude Opus 5.5 fcdd05f2b1 [ownership] Server-side deck ownership, collection API, 40-card eligibility (#57)
- server/game/ownership.ts: verifyAccount, resolveDeck (token ids only; canonical
  owner in linked wallets, confirmations, exact deckSize, 4 copies per pageId,
  cards rebuilt from their block), collection (all linked wallets, paged at one
  tip, no 128-block cap). Signature agreed with host-pvp on #57.
- server/game/collection.ts: GET /api/game/collection (Dex bearer) with owned,
  playable, needed, eligible.
- account router exports accountVerifier; http.ts shares one AccountStore and
  DexKeys between the account and game routes and passes gameRouter({ownership}).
- App.tsx: My collection counts cards in every wallet linked to the account.
- tests/ownership-deck.test.ts: in-memory ledger fixture, no network.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:42:28 -05:00
claudeandClaude Opus 5.5 4daf87edde duel-core: monotonic attack/block declarations; optional permanent counters
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:36:41 -05:00
claudeandClaude Opus 5.5 5365611c4a duel-core: shared/duel contracts (types, ruleset) and DUEL_API.md
Refs #55.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:35:37 -05:00
claudeandClaude Opus 5.5 bac186470d DUEL_DESIGN.md v1: rules, keywords, templates, Connected, modes, tone, worked cards
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 21:35:07 -05:00
44 changed files with 15602 additions and 141 deletions
+89
View File
@@ -0,0 +1,89 @@
# WikiDeck Duel: engine API (v1, Night 2)
Owner: **duel-core** (claude/wikideck#55). Rules: `docs/game/DUEL_DESIGN.md` (duel-design). This file: how code talks to the engine.
- Types: `shared/duel/types.ts`. Ruleset: `shared/duel/ruleset.ts`. Function surface: `DuelEngineApi` in `shared/duel/index.ts`, implemented by `shared/duel/engine.ts` (engine-alpha PR).
- `shared/game/` (Edit War) is untouched. Change requests: comment on #55 with `[from <agent>]`.
## Principles
- **Pure and deterministic.** `(rules, decks, seed, actions)` → identical state and log. RNG: `shared/game/rng.ts` (mulberry32); its uint32 state lives in `DuelState.rng`.
- **Plain JSON.** `DuelState` round-trips through `JSON.stringify`/`parse`; `serialize`/`deserialize` are thin wrappers.
- **Clone-on-apply.** `applyAction` never mutates its input and throws on an illegal action.
- **Atomic actions.** `legalActions(state, seat)` is small, and `[]` for the seat that is not to act. The host checks an action by deep-equal against that list (`concede` and `timeout` excepted).
- **Off-chain.** Matches never move or burn cards. Cards arrive derived and frozen; the engine does no I/O.
## Cards (`DuelCard`)
Built by duel-cards (`derive()`), frozen by the host at match start. Shape agreed with duel-cards on #55.
| Field | Notes |
|---|---|
| `cardId` | unique in a deck (NFT tokenId; sample id in sims; `token:` for tokens) |
| `pageId`, `revisionId?`, `title`, `description?` | `pageId` matches Linked pairs; `revisionId` for recap references |
| `type`, `subtype?` | `Figure` · `Location` · `Event` · `Institution` · `Doctrine` |
| `portal` | `Arts, Earth, History, Science, Society, Neutral`; no deckbuilding restriction |
| `cost` | 1–6 (Locations 1–3) |
| `power`, `toughness` | Figures: body. Locations: 0 / Garrison (0 = can't block). Others: `null` or 0 |
| `keywords` | ≤ `maxKeywords` (2). Figures only |
| `territory?` | Location: +N max Citations while controlled (total from all sources ≤ `territoryCap`) |
| `effects` | `EffectSpec[]` (below), ≤ 4 |
| `rulesText`, `flavor` | display only |
| `connect?` | `{countries, centuries, links, p31}` frozen claims; the engine computes Connected |
| `rarity?`, `deriveVersion?`, `token?` | |
### Keywords (DUEL_DESIGN §4), as the engine applies them
- **Protected**: can't be the target of Events or Doctrines an opponent controls (abilities of other permanents and combat still apply).
- **Featured**: can be blocked only by Featured, Translated or Multilingual Figures.
- **Multilingual**: can block Featured; can't be blocked by Local Figures.
- **Translated**: can block Featured.
- **Legacy**: when destroyed, its controller draws a card.
- **Well-sourced**: prevent the first 1 damage dealt to it each turn.
- **Stub**: at the start of your turn, a +1/+1 counter, up to `stubMax` (2).
- **Local**: +1/+1 while you control a Location sharing a `connect.countries` value.
- **Trending** (Trending mode, set by the host via `applyLive`): no Pending review, +`trendingPower`/+0.
### Effects (`EffectSpec`)
`{ trigger, op, target?, amount?, power?, toughness?, duration?, token?, condition?, grant?, template? }`
- **Triggers:** `onPlay` (Event resolves; on a permanent same as `onEnter`), `onEnter`, `onAttack`, `onDestroyed`, `startOfTurn`, `onCombatDamageToPlayer` (on a Figure, or on a Doctrine for its attached Figure), `static`.
- **Ops:** `damage`, `damageEach`, `createToken`, `pump`, `fight`, `draw`, `attach`, `gainLife`, `drain`, `destroy`, `bounce`, `tap`.
- **Targets:** chosen: `figure`, `figureOrLocation`, `ownFigure`, `opponentFigure`, `anyTarget`; automatic: `each`, `self`, `attached`, `ownFigures`, `opponentFigures`, `opponent`, `controller`. Defaults: damage → `anyTarget`, pump → `self`, draw/gainLife/createToken → `controller`, drain → `opponent`.
- **Chosen targets:** each `onPlay`/`onEnter` effect with a chosen target consumes the next entry of `play.targets`, in effect order; `legalActions` enumerates the combinations. An Event or Doctrine with no legal target can't be played; a Figure/Location/Institution enters and its targeted effect fizzles (`targets` omitted).
- **fight:** the previous chosen target in the same card (else the source permanent) and this target deal damage equal to their power to each other. T6 = `[{op:'pump', target:'ownFigure', power:k, toughness:0}, {op:'fight', target:'opponentFigure'}]`.
- **Doctrine:** its `attach` effect's target is the Figure it attaches to (`ownFigure` for T11, `figure` for T12). Its `static` effects with `target: 'attached'` apply to that Figure; `condition.samePortal` on a Doctrine means "other Figures you control of the attached Figure's Portal". When the Figure leaves, the Doctrine is Deleted.
- **static pump** applies while the source is in play; conditions use **printed** power (no feedback loops). `condition.connected` = the affected Figure is Connected to the source (T9).
- **createToken:** `amount` tokens of `token` (a fresh `DuelCard` with `token: true`, uid `t:<n>`); `condition.maxTokens` = only if you control fewer tokens than that. Tokens leaving play cease to exist.
- Triggers resolve immediately: the active player's first, then in entry order.
## Rules (defaults: `DEFAULT_DUEL_RULESET`; details in DUEL_DESIGN §2)
- 40-card decks (`deckSize`), ≤ 4 per `pageId`, unique `cardId`s, no tokens. 20 Notability. Drawing from an empty library loses (`libraryEmpty: 'lose'`; `'reshuffle'` and `'fatigue'` exist as data).
- Opening hand 7. Up to `mulligans` (1): shuffle in, draw 7, then on `keep` put one card per mulligan on the bottom (the last in hand order). Seat 0 decides first, then seat 1.
- First player (from the seed) skips their first draw.
- **Turn:** refresh (base max +1 to 10, plus Territory ≤ 2; refill; untap; Pending review ends; Stub and `startOfTurn` triggers) → draw → **main** → **attack** → **block** → damage → end (damage and "until end of turn" clear; discard down to `handSize` 7, **highest cost first**, automatically).
- Locations: `locationsPerTurn` (1), can't attack. Garrison Locations (toughness > 0) block as 0-power.
- Combat: attack the opponent only; each blocker blocks one attacker, at most one blocker per attacker; simultaneous damage; destroy triggers after all combat damage. No trample, first strike, stack or instants.
- **Connected** (engine, from `connect`, tiers in `connectedTiers`): Linked (either `links` contains the other's `pageId`, or either `cites` contains the other's `qid`), Compatriot (shared country), Contemporary (shared century, different types), Kin (shared P31, not Q5/Q16521). A Figure gets the single best bonus among other permanents its controller controls: `+linkedBonus` (2) if Linked, else `+connectedBonus` (1). Logged once (`connected`). Opposing Connected pairs are logged once as `rivalry`.
- **Timeouts:** `timeout` passes (mulligan: keep; main/attack: end the turn without attacking; block: confirm current blocks). `timeoutsToConcede` (3) consecutive timeouts by one seat lose (`reason: 'timeout'`).
- `turnCap` (null by default): after that many total turns, higher Notability wins, then higher total power in play, then the second player.
## Phases and actions
| Phase | Who acts | Listed actions |
|---|---|---|
| `mulligan` | seat 0 until ready, then seat 1 | `keep`, `mulligan` |
| `main` | active | `play {uid, targets?}`, `endPhase` |
| `attack` | active | `toggleAttacker {uid}` (untapped, not Pending review, not yet declared), `confirmAttack` |
| `block` | defender | `block {blocker, attacker}` (unassigned blocker, unblocked attacker, evasion allowing), `confirmBlocks` |
| any | either seat | `concede` (not listed) |
| any | host, for the seat to act | `timeout` (not listed) |
Declarations are **monotonic** (no un-declare), so every turn has a bounded number of actions; UIs stage choices locally and send them on confirm. If the defender has no legal block, damage resolves at `confirmAttack` with no block phase. `confirmAttack` with no attackers ends the turn.
## Views and log
- `viewFor(state, seat): PlayerView`: your hand; the opponent's hand and library **sizes** only; both graveyards; the battlefield with current power/toughness, keywords and Connected badge; combat; `toAct`; `version`; `result`. Never the RNG or library order.
- **The seed is secret until the match ends.** `seed` plus the deck lists reproduce every shuffle, so the host never sends `seed` or `rng` (or the raw `DuelState`) to clients before `gameOver`. Live log rendering picks template variants from a derived `storySeed = sha256(seed + ':story')`.
- `state.log` is omniscient (server, and the recap after the match). Clients get **`logFor(state, seat)`**: the opponent's `draw` events have no `card`. Every other event is public information.
- Every event has `seq` and `turn`. `CardRef` carries `uid, cardId, title, pageId, type` plus `power`/`toughness` right after the event.
- Kinds (DUEL_DESIGN §10 names): `start, mulligan, keep, turnStart, draw, deploy, cast, adopt, tokenCreated, connected, rivalry, effect, attack, block, effectDamage, combatDamage, playerDamage, lifeGain, destroyed, bounced, discard, fatigue, concede, timeout, gameOver`. `destroyed` = the recap's casualties. Prose templates live with duel-design / ui-pvp, not in the engine.
## Host binding
`duelEnginePort` (engine.ts) is structurally an `EnginePort<DuelRuleset, DuelCard, DuelState, DuelAction>` (`server/game/engine-port.ts`; `shared/` doesn't import `server/`, so host-pvp types it there). `concedeAction`, `timeoutAction`, `turnSeconds`, `turnOf`, `applyLive` included. `starterDeck` and `previewPool` throw: there are no starters (BRIEF decision 2); draft pools come from both players' collections.
## Stability
These types are the contract for duel-cards, host-pvp, ui-duel, ui-pvp and sim-balance. Additive changes (optional fields, new log kinds) can land with the engine; breaking ones get a `[duel-core] contract change` comment on #55 first.
+279
View File
@@ -0,0 +1,279 @@
# WikiDeck Duel: design v1
**Status:** v1.3, Night 2 (2026-11-17): v1 plus night-review's nits on PR #66, duel-cards' implementation choices from PR #70, and the balance v1 rules `secondPlayerCitations` 1 and `turnCap` 40 (#64). Owner: duel-design (issue #60).
**Base:** `docs/night2/BRIEF.md` (Eric's locked decisions). Where this file and BRIEF disagree, BRIEF wins. Reviews used: designer (rules), data §2–4 (derivation), critic S7 (tone).
**Consumers:** duel-core (`shared/duel/` engine and `types.ts`), duel-cards (`classify/derive/effects/text.ts`), sim-balance (bots, `DUEL_BALANCE.md`), ui-duel / ui-pvp (faces, recap), host-pvp (rulesets).
Every number in this file is a **ruleset key or a derivation table value**, not code. sim-balance tunes them in data-only PRs.
---
## 1. The game in one paragraph
Two players each bring **40 cards they own on-chain**. Each card is a Wikipedia article turned into a Magic-style card by fixed rules over real data. You start at **20 Notability**. Every turn your **Citations** (mana) maximum rises by one. You deploy Figures, attack with them, block with yours, cast Events, adopt Doctrines onto Figures. The first player to 0 Notability, or unable to draw, loses. The match is written up afterwards as an encyclopedic "Battle of X (2026)" page.
---
## 2. Rules
### 2.1 Decks and eligibility (BRIEF decisions 1–2)
| Key | Default | Rule |
|---|---|---|
| `deckSize` | **40** | Exactly this many cards. Every card is an NFT the player owns (server-verified by `ownership.ts`). No Basics, loaners, proxies or tokens in decks. |
| `maxCopiesPerPage` | **4** | Different mints of the same `pageId` may appear up to 4 times (each mint once: it is unique). |
| colour/Portal rules | none | Any mix of Portals. |
| Eligibility | owns ≥ `deckSize` | Below it, the UI shows "23 / 40 cards" and how to mine. No practice with borrowed cards. Bot matches need eligibility too. |
Testnet end-to-end mode files may lower `deckSize`. Production stays at 40.
### 2.2 Setup
- **Notability** (life): `startingLife` **20**. At 0 you lose.
- **Empty library:** drawing from an empty library loses (`libraryEmpty: 'lose'`).
- **Opening hand:** `openingHand` **7**. One mulligan (`mulligans: 1`): shuffle, draw 7, put 1 on the bottom.
- **First player** (seeded coin flip) skips their first draw.
- **Second player** gets +1 Citation maximum on their first turn only (`secondPlayerCitations` **1**). Balance v1: this moved the first-player win rate from 60.1% to 54.4% in 1,500 heuristic-mirror matches (engine 4623930, #64). Neither an extra opening card (washed out by the mulligan and the hand limit) nor `firstPlayerDraws` worked.
### 2.3 Turn structure: refresh → draw → main → combat → end
1. **Refresh.** Citation maximum +1 (to `maxCitations` **10**), plus Territory (§2.5). Citations refill to the maximum. Your permanents untap. "Pending review" ends for your Figures. Start-of-turn triggers (Stub, Institutions) resolve in the order the permanents entered.
2. **Draw** 1 card.
3. **Main.** Play cards in any order while you can pay their cost in Citations: Figures, Locations (one per turn: `locationsPerTurn` 1), Institutions, Doctrines (attach to a Figure), Events (resolve immediately).
4. **Combat** (§2.4).
5. **End.** Damage on permanents clears. "Until end of turn" effects end. Discard down to `handLimit` **7** (the player chooses; bots discard highest cost first).
**Zones.** Library and hand are hidden (a hand's size is public). The battlefield and **Deleted** (the graveyard) are **public**: a discarded card is revealed and named once it reaches Deleted.
There is **no second main phase, no stack, no priority and nothing at instant speed.** Events are sorcery-speed. Triggers resolve immediately, in a fixed order: the active player's first, in the order the cards entered.
### 2.4 Combat
- **Attack:** the active player chooses any untapped Figures without Pending review and taps them. They attack the opponent only, never permanents.
- **Block:** the defender assigns **at most one blocker per attacker**, and each blocker blocks one attacker. Untapped Figures and Garrison Locations may block. Evasion (Featured) restricts who may block: **a Garrison Location can't block a Featured attacker** (only Featured, Translated or Multilingual Figures can).
- **Damage:** simultaneous. A blocked pair deal their power to each other. An unblocked attacker deals its power to the defending player's Notability.
- A permanent with damage ≥ toughness is **destroyed** (goes to the Deleted pile, the graveyard). Destroy triggers (Legacy) fire after all combat damage.
- No trample, no first strike, no deathtouch, no lifelink in v1.
### 2.5 Card types (BRIEF; classifier in data §1, built by duel-cards)
| Type | MTG analogue | Rules |
|---|---|---|
| **Figure** | creature | Power/toughness. Enters with **Pending review** (summoning sickness): can't attack until your next turn. |
| **Location** | land-ish permanent | Cost `ceil(derivedCost/2)` (1–3). **Territory:** +1 Citation maximum while you control it; at most **+2 in total** from Territory (`territoryCap` 2). **Garrison 0/T:** can block like a 0-power Figure (T = 1 + floor(pct_depth / 25), so 1–4). Can't attack. Damage clears at end of turn as usual; a Location destroyed in a block goes to Deleted. One per turn. |
| **Event** | sorcery | Resolves at once, then goes to Deleted. |
| **Institution** | artifact | A permanent with a static or triggered ability. |
| **Doctrine** | Aura | **Adopt:** attach to target Figure (yours or the opponent's for negative Doctrines). If the Figure leaves play, the Doctrine goes to Deleted. |
Classification order (duel-cards owns it): P31 → P279 anchor classes → P31 label regex (`^human$`, fixing the `\bhuman\b` bug) → categories → description → **Doctrine**. The derived profile is **frozen** the first time a card is seen.
### 2.6 Clock and length
- `turnSeconds` **60** per turn plus `bankSeconds` **300** per player. The turn timer runs first; when it expires, the player's bank drains; when the bank is also empty, the turn passes (`timeout` action). The bank does not refill. Three timeouts in a row concede.
- **`turnCap` 40** (20 turns each, balance v1). At the cap the higher Notability wins, then the higher total power in play, then the second player. In sims it decides about 4% of games and removes every game past 20 turns each, without moving the median.
- **Sim targets** (agreed with sim-balance, #64): median 8–12 turns each; first-player win rate 48–54%; < 5% of games past 20 turns each. **Balance v1 result** (`secondPlayerCitations` 1 + `turnCap` 40; 3,000 heuristic-mirror matches, engine 4623930, duel-cards 067de83; run by ui-duel for sim-balance, #64): first player **54.7%** [53–57], turns each 6 / 8 / 12, 0% past 20, about 8 minutes median.
### 2.7 Determinism
All randomness (shuffles, coin flip, template variants) comes from the match seed via `shared/game/rng.ts`. The same seed and actions always replay to the same state, log and recap.
---
## 3. Derivation summary (duel-cards implements; data §2)
- **Percentiles** `pct_a`, `pct_d`, `pct_r` from the sample cut points (DESIGN.md §1.1 counting). **fame** = mean of the three, rounded.
- **Cost** 1–6 by `costThresholds` [26, 39, 51, 63, 78].
- **Figure body budget** P+T = [3, 4, 6, 8, 10, 12] for cost 1–6 (MTG vanilla curve). Subtract **1 per taxed keyword** (§4). At cost 1, a second taxed keyword is skipped, so a body never drops below 1/1. Then `power = clamp(round(budget × pct_a / (pct_a + pct_d)), 1, budget − 1)`, toughness = the rest. Famous cards are bigger and pricier, never more efficient.
- **Magnitude** for non-Figures: `k = ceil(cost / 2)` (1–3).
- **Portal** (faction): Arts, Earth, History, Science, Society, or Neutral, scored by regex hits (designer §3.2); ties go to the type default (Figure → Society, Location → Earth, Event → History, Institution → Arts, Doctrine → Science). No deckbuilding restriction.
- **Flavour text:** first sentence of on-chain `article.extract`; if absent (the sample has none), the Wikidata `description`; if that is empty too, none.
---
## 4. Keywords (10)
Eight card keywords, each triggered only by real data and applied **to Figures only**, at most **2 per card** in the priority order below. Plus two rules keywords. Thresholds are measured on the 236-card sample (86 Figures); sim-balance may move them.
| # | Keyword | Trigger (real data) | Rules text | Body tax | Rate among Figures |
|---|---|---|---|---|---|
| 1 | **Protected** | category `Living people` | Can't be the target of Events or Doctrines an opponent controls. | 1 | 38% |
| 2 | **Featured** (flying) | pct_attention ≥ 85 | Can't be blocked except by Featured, Translated or Multilingual Figures. | 1 | 15% |
| 3 | **Legacy** | a `<year> deaths` category (or P570 in the frozen profile) | When this is destroyed, draw a card. | 1 | 33% |
| 4 | **Multilingual** | pct_reach ≥ 90 | Can block Featured Figures. Can't be blocked by Local Figures. | 1 | ~5% |
| 5 | **Translated** (reach) | 75 ≤ pct_reach < 90 | Can block Featured Figures. | 0 | 19% |
| 6 | **Well-sourced** | pct_depth ≥ 85 | Prevent the first 1 damage that would be dealt to this each turn. | 1 | ~13% before cap |
| 7 | **Stub** | pageBytes < 3000 or a `…stubs` category | At the start of your turn, put a +1/+1 counter on this, to a maximum of 2. | 0 | 33% |
| 8 | **Local** | raw reach = 0 (no other language editions) | Gets +1/+1 while you control a Compatriot Location (same P17). | 0 | 7% before cap |
| 9 | **Connected** | the card pair's frozen claims and links (§6) | +1/+1 while you control another card Connected to it; +2/+2 if Linked. | – | target 15–30% of pairs |
| 10 | **Trending** (haste) | Trending mode only: frozen live ▲ (trend ≥ +25% and daily ≥ 20) | Can attack the turn it enters. Gets +1/+0. | – | ~2% of cards |
Rule words that are not keywords: **Pending review** (summoning sickness), **Territory**, **Garrison**, **Adopt**, **Deleted** (the graveyard).
Notes:
- Protected deliberately sits first: living people are the most targeted, and the rule that matters most for them is mechanical, not a tone rule. It doesn't stop combat.
- Multilingual and Translated are two bands of the same reach axis, so a card never has both.
- A card's face shows at most 2 keyword words; the reminder text is behind a tap.
---
## 5. Effect templates (12, MTG register)
Subtype regexes run over the frozen P31/P279 labels, then the description, then categories. First match wins, in the order listed. `k = ceil(cost/2)`.
| # | Type / subtype | Trigger regex (labels, description) | Rules text |
|---|---|---|---|
| T1 | Figure | (all Figures) | Vanilla body + keywords. No other text. |
| T2 | Location | (all Locations) | Territory. Garrison 0/T. |
| T3 | Event: conflict | `battle\|war\|siege\|annexation\|protest\|riot\|uprising\|massacre\|coup` | Deal k+1 damage to target Figure or Location. |
| T4 | Event: disaster | `storm\|nor.easter\|cyclone\|hurricane\|earthquake\|flood\|tornado\|wildfire\|eruption\|famine\|epidemic` | Deal k−1 damage (minimum 1) to each Figure and each Location. |
| T5 | Event: election | `election\|referendum\|straw poll` | Create k 1/1 Society Figure tokens named Elected Member. |
| T6 | Event: sport | `match\|final\|season\|tournament\|championship\|grand prix\|race` | Target Figure you control gets +k/+0 until end of turn, then fights target Figure you don't control. |
| T7 | Event: default (period, ceremony, scandal, other) | anything else | Draw k cards. |
| T8 | Institution: organisation | `company\|organi[sz]ation\|party\|agency\|studio\|military\|university\|diocese\|council\|band\|musical group\|association\|business\|school\|college\|institute\|manufacturer` | Cost ≥ 4: "At the start of your turn, if you control fewer than 3 tokens, create a 1/1 Figure token named Staff Member." Cost ≤ 3: "When this enters, create a 1/1 Figure token named Staff Member." |
| T9 | Institution: creative work | `film\|album\|song\|book\|novel\|series\|video game\|painting\|software\|typeface\|newspaper\|magazine` | When this enters, draw a card. Figures you control that are Connected to this get +1/+1. |
| T10 | Institution: team, award, vehicle, other | anything else | Figures you control with power 2 or less get +1/+0. |
| T11 | Doctrine: Adopt | (all non-Pathology Doctrines) | Attach to target Figure you control. It gets +k/+k. Rider by subtype, checked in the order pathology (→ T12) > language/software > mathematics, so "functional programming language" is not maths: mathematics → "and has Well-sourced"; language/software → "Whenever it deals combat damage to a player, draw a card"; ideology/religion → "Other Figures you control of its Portal get +1/+0"; otherwise none. |
| T12 | Doctrine: Pathology | `disease\|clinical sign\|pathogen\|syndrome\|disorder\|toxin\|poison` | Attach to target Figure. It gets −k/−k. |
Elected Member tokens are Society; Staff Member tokens have no Portal ("1/1 Figure token"). Tokens are not cards: they never appear in decks, are created only by T5/T8, and are removed when they leave play. Token names are fixed generic strings, never real people.
Rules-text style:
- Second person, present tense, MTG terse register: "Deal 3 damage to target Figure."
- Card names appear in rules text only as "this" (never the article title), so text stays the same length on a 360 px face.
- No adjectives, no puns, no exclamation marks.
---
## 6. Connected (data §4 tiers)
Computed by the host at match start from frozen card profiles. No network calls during a match; the edge list is written into the match record.
| Tier | Test | Bonus | Cut order |
|---|---|---|---|
| **Linked** | either article links to the other (cached outlinks), or one card's claims cite the other's Q-id | +2/+2 | keep |
| **Compatriot** | share a P17 (country) or P27 (citizenship) value | +1/+1 | keep |
| **Contemporary** | same century from P569/P570/P571/P580/P585, **only between different types** | +1/+1 | cut 4th (BRIEF) |
| **Kin** | same P31 class, excluding Q5 human and Q16521 taxon | +1/+1 | cut 4th (BRIEF) |
- A Figure gets the **single best** bonus among its Connected cards you control (no stacking): +2/+2 if any is Linked, else +1/+1.
- A Connected creative-work Institution (T9) gives its +1/+1 on top.
- **Target:** 15–30% of random card pairs connected (text proxies measured 21.5% for country OR century). If sims show more, drop the noisiest keys first (P17 = United States, then France); if fewer, add P131.
- The card shows why: "Connected — *Pathrail Mosque* (country: Bangladesh)".
- **Rivalry** (log only): when two opposing cards are Connected, the log may note it once (§8.3). No mechanical effect.
---
## 7. Modes (on the duel engine)
| Mode | Decks | Notes |
|---|---|---|
| **Classic** | constructed from your own 40+ owned cards | Ranked (Elo, keyed to the eom.dev account). Invite links and quick match. |
| **Bot** | your own 40 | Only for eligible players. Not ranked. |
| **Draft** | both players eligible | Pool drawn from both players' collections (e.g. 30 cards from each, shuffled into one pool). Snake-pick until each has `deckSize`. Drafted cards are used for that match only; nothing moves on-chain. Ownership is credited in the recap ("from the collection of bob"). |
| **Trending** | any | Live pageview trend from the daily cache, frozen at match start: ▲ (≥ +25%, daily ≥ 20) gives Trending (haste, +1/+0); ▼ (≤ −50%, daily ≥ 20) gives −1/−0. Cut 3rd. |
| **House rules** | peer-hosted | Data-only, versioned schema. Keys: `deckSize`, `maxCopiesPerPage`, `startingLife`, `openingHand`, `mulligans`, `maxCitations`, `territoryCap`, `handLimit`, `turnSeconds`, `bankSeconds`, `turnCap`, `secondPlayerCitations`, `connectedTiers`, `keywordThresholds`. Night 1 mode files are rejected cleanly with a message. |
---
## 8. Tone and story text
### 8.1 Tone rules (BRIEF decision 5, critic S7)
1. **Lean in.** Living people, tragedies, wars, disasters, crimes, diseases and dictators are ordinary cards with full mechanics. No `solemn` flags, no special cases, no softened verbs. "Casualties" is fine. A protester shot in 1970 is a 6/3 with Legacy like anything else.
2. **Deadpan.** The text takes itself completely seriously. It **never winks** and **never comments on the matchup** ("in a surprising twist", "unlikely", "ironically" are banned). The comedy lives in the nouns: "*Heart rot* was adopted by *Tom Ewell*."
3. **Encyclopedic texture.** Past tense, third person, passive where Wikipedia would use it, dates and turn numbers, and `[n]` citations linking each card's real article at its revision.
4. **No adjectives about cards or players** (no "brutal", "heroic", "humiliating", "bloodiest"). Mechanical verbs only: deployed, attacked, blocked, was destroyed, was adopted by, took N damage, was cited.
5. **Never invent facts about real people.** All generated text is a deterministic template filled **only** with real card data (title, description, dates, categories, revision id) and real match data (turn, players, numbers). No LLM prose. No made-up quotes, crimes, acts, motives or feelings. The template verbs describe **game events of the card**, and every narrative paragraph is framed as a WikiDeck engagement; the footer says so.
6. **Allowed real data in text:** title, Wikidata `description`, birth/death years parsed from the description or frozen claims, the first extract sentence (flavour), Portal, type. Nothing else about a person.
7. **Dull guard:** 3–4 synonymous variants per event, chosen by the match seed (§8.2).
| DO | DON'T |
|---|---|
| "Turn 6. *Zbyszek Godlewski* (6/3) attacked. *Pallas's cat* (5/5) blocked. *Zbyszek Godlewski* was destroyed.[3][4]" | "Godlewski got mauled by a cat lol" |
| "The *April 2021 nor'easter* dealt 1 damage to each Figure. *Dichromorpha viridis* was destroyed.[5][6]" | "Mother Nature wiped out the poor grasshopper!" |
| "*Heart rot* was adopted by *Tom Ewell*, which became a 2/2.[7][8]" | "Ewell caught a tree disease, how embarrassing" (adjective + invented claim) |
| "The **Battle of Pathrail Mosque (2026)** was a WikiDeck engagement fought on 17 November 2026 between the forces of alice and bob." | "the bloodiest battle in WikiDeck history" |
### 8.2 Match-log templates (`shared/duel/story/log.ts`)
- One template group per engine `LogEvent` kind, each with **3–4 variants**. Variant = `rng(seed, turn, eventIndex) mod n`, using the match seed, so `replay` regenerates the log exactly.
- First mention of a card in a match adds its description in parentheses: "*Tom Ewell* (American actor, 1909–1994)". Later mentions use the title only.
- Each first mention of a card assigns it the next reference number `[n]`; later mentions reuse it.
- `logFor(seat)` hides the opponent's hand: their draws read "bob drew a card." and mulligans are not named. Discards are named, because Deleted is public (§2.3).
| Event | Variants (`{card}` italic, `{player}` the seat name) |
|---|---|
| deploy (Figure/Location/Institution) | "{player} deployed {card}." · "{card} was deployed by {player}." · "{player} brought {card} into play." · "{card} entered play under {player}." |
| event cast | "{player} cited {card}." · "{card} was cited by {player}." · "{player} invoked {card}." |
| adopt | "{doctrine} was adopted by {figure}, which became a {p}/{t}." · "{figure} adopted {doctrine} and became a {p}/{t}." · "{player} attached {doctrine} to {figure} ({p}/{t})." |
| attack | "{card} ({p}/{t}) attacked." · "{player} sent {card} ({p}/{t}) into combat." · "{card} ({p}/{t}) advanced on {opponent}." |
| block | "{blocker} ({p}/{t}) blocked {attacker}." · "{attacker} was blocked by {blocker} ({p}/{t})." · "{blocker} ({p}/{t}) intercepted {attacker}." |
| player damage | "{opponent} lost {n} Notability ({life} remaining)." · "{card} dealt {n} damage to {opponent}, leaving {life} Notability." · "{opponent}'s Notability fell to {life}." |
| destroyed | "{card} was destroyed." · "{card} was moved to Deleted." · "{card} was removed from play." · "{card} did not survive the turn." |
| effect damage | "{source} dealt {n} damage to {target}." · "{target} took {n} damage from {source}." · "{source} inflicted {n} damage on {target}." |
| token created | "{source} produced {n} {token}." · "{n} {token} were created by {source}." · "{source} created {n} {token}." |
| draw (own) | "{player} drew {card}." · "{card} was drawn." · "{player} added {card} to their hand." |
| draw (hidden) | "{player} drew a card." · "{player} drew {n} cards." |
| Connected | "{a} and {b} were Connected ({reason})." · "{a} was Connected to {b} through {reason}." · "Records link {a} and {b} ({reason})." |
| discard | "{player} discarded {card}." · "{card} was discarded by {player}." · "{player} moved {card} from hand to Deleted." |
| rivalry (opposing Connected pair, once) | "{a} and {b} are both listed under {reason}." · "{a} and {b} share {reason}." · "The two sides were linked through {reason}." |
| turn start | "Turn {n}." (fixed) |
| game over | "{loser} was nominated for deletion. The result was **delete**." · "{loser} was reduced to 0 Notability. {winner} won." · "{winner} won on turn {n}." · (library) "{loser} could not draw a card and lost." · (concede) "{loser} withdrew." |
### 8.3 Battle recap (`shared/duel/story/recap.ts`)
A deterministic function `recap(matchRecord) → RecapDoc` (structured data; ui-pvp renders it). Inputs are the match record only: seed, players, decks' frozen card profiles, the event list, the date. No network, no clock.
**Title:** "{Prefix} {Name} ({year})"
- **Name:** the winner's highest-cost Location that entered play; else the loser's; else the highest-cost Event cast in the match; else the winner's highest-cost card deployed; ties broken by first played. Living people and tragedies are eligible like any card ("Battle of Zbyszek Godlewski (2026)" is valid).
- **Prefix:** "Skirmish at" (≤ 6 turns each), "Battle of" (7–12), "Siege of" (≥ 13). For a Figure name: "Battle of" becomes "{Name} campaign" (no prefix).
- **Year:** the match date's year (2026).
**Infobox:**
| Field | Value |
|---|---|
| Date | the match date, "17 November 2026" |
| Location | the Name card if it's a Location, else "WikiDeck host {hostName}" |
| Result | "Decisive {winner} victory" (margin ≥ 10 Notability) · "Pyrrhic {winner} victory" (winner ≤ 3) · "{winner} victory" · "{winner} victory by withdrawal" (concession/timeout) · "{winner} victory by attrition" (empty library) · "Victory by decision" (turn cap) |
| Belligerents | the two seat names (account display names) |
| Commanders | each side's highest-cost Figure deployed |
| Strength | cards deployed per side ("14 cards") |
| Casualties and losses | cards destroyed per side, count, then the titles |
**Sections:**
1. **Lead** (1 paragraph): "The {title} was a WikiDeck engagement fought on {date} between the forces of {a} and {b}. It lasted {n} turns and ended in {result-lowercase}.[1]" + one sentence on the first Figure deployed: "Contemporary accounts note the deployment of {card} in the {ordinal} turn.[n]"
2. **Background:** each side's Portal mix ("History was the largest Portal in the force of alice (eleven of twenty cards played)").
3. **Course of the battle:** the 3–5 largest Notability swings and every destroyed card with cost ≥ 4, in turn order, as log sentences (variants from §8.2, but seeded with `seed ⊕ 'recap'` so the recap doesn't repeat the log word for word).
4. **Aftermath:** final Notability, turns, rating change if ranked.
5. **See also:** Connected pairs and rivalries.
6. **References:** every card played by either side, in first-mention order: "{n}. ^ "{title}". Wikipedia. Revision {revisionId}. Minted as token {tokenId}." linking `https://en.wikipedia.org/w/index.php?title={title}&oldid={revisionId}`.
**Branding and footer:** WikiDeck masthead, never the Wikipedia/Wikimedia name or logo. Footer: "This page records a WikiDeck match. Card names refer to Wikipedia articles; the events described are game events." Shareable at `/recap/{matchId}`.
---
## 9. Worked examples (12 cards from `docs/game/card-sample.json`)
Computed with the rules above (data §2 budget, §4 keyword priority, §5 templates) by a script over the sample, and checked by hand. duel-cards' implementation (PR #70) agrees on all 12, with the two Portal corrections now applied (#9, #11). Flavour is the `description` because the sample has no extracts. Final numbers come from duel-cards' implementation; if they differ, the implementation and its golden test win and this table is updated.
| # | Card | Derivation | Card |
|---|---|---|---|
| 1 | **Marc Fesneau** (living person) | P31 human → Figure. "politician" → Society. pct 76/68/63 → fame 69 → cost 5, budget 10. Living people → Protected (−1) → 9 split 76:68 → 5/4. | **Marc Fesneau** · 5 · Figure — Society · **5/4** · *Protected.* "French politician (born 1971)." |
| 2 | **Tom Ewell** | human → Figure, Arts. 94/83/93 → fame 90 → cost 6, budget 12. Featured (−1), Legacy (−1); Multilingual dropped by the cap. 10 → 5/5. | **Tom Ewell** · 6 · Figure — Arts · **5/5** · *Featured. Legacy.* "American actor (1909–1994)." |
| 3 | **Zbyszek Godlewski** (killed at a 1970 protest) | human → Figure, History. 77/48/78 → fame 68 → cost 5. Legacy (1970 deaths, −1), Translated (pct_r 78, 0). 9 split 77:48 → 6/3. | **Zbyszek Godlewski** · 5 · Figure — History · **6/3** · *Legacy. Translated.* "Polish protester (1952–1970)." |
| 4 | **Pallas's cat** | taxon → Figure, Earth. 99/97/99 → fame 98 → cost 6. Featured (−1), Multilingual (−1); Well-sourced dropped. 10 → 5/5. | **Pallas's cat** · 6 · Figure — Earth · **5/5** · *Featured. Multilingual.* "Species of small wild cat." |
| 5 | **Dichromorpha viridis** | taxon → Figure, Earth. 58/3/53 → fame 38 → cost 2, budget 4. Stub (1,347 bytes, untaxed). Split clamps to 3/1. | **Dichromorpha viridis** · 2 · Figure — Earth · **3/1** · *Stub.* "Species of grasshopper." |
| 6 | **Monoid** (maths) | no P31; category "Algebraic structures" → Doctrine, Science. fame 96 → cost 6, k = 3. Maths rider. | **Monoid** · 6 · Doctrine — Science · Attach to target Figure you control. It gets +3/+3 and has Well-sourced. "Algebraic structure with an associative operation and an identity element." |
| 7 | **Heart rot** (disease) | P31 plant disease → Doctrine, Pathology (T12). Science. fame 68 → cost 5, k = 3. | **Heart rot** · 5 · Doctrine — Science · Attach to target Figure. It gets −3/−3. "Fungal disease of trees." |
| 8 | **April 2021 nor'easter** (disaster) | P31 nor'easter → Event, disaster (T4). Earth. fame 50 → cost 3, k = 2. | **April 2021 nor'easter** · 3 · Event — Earth · Deal 1 damage to each Figure and each Location. "Slow-moving nor'easter in April 2021." |
| 9 | **2025 Tehreek-e-Labbaik Pakistan protests** (conflict) | P31 protest → Event, conflict (T3). Society (protest/riot hits outnumber "war"). fame 64 → cost 5, k = 3. | **2025 Tehreek-e-Labbaik Pakistan protests** · 5 · Event — Society · Deal 4 damage to target Figure or Location. "Gaza war protests in Pakistan." |
| 10 | **1954 Gold Coast general election** | P31 legislative election → Event, election (T5). Society. fame 45 → cost 3, k = 2. | **1954 Gold Coast general election** · 3 · Event — Society · Create two 1/1 Society Figure tokens named Elected Member. *(no flavour: empty description)* |
| 11 | **Pathrail Mosque** | P31 mosque → Location, Society ("mosque" hits in P31, the description and two categories outnumber 15th-century + Sultanate). fame 49 → cost 3 → Location cost 2. pct_d 54 → Garrison 0/3. | **Pathrail Mosque** · 2 · Location — Society · Territory. Garrison 0/3. "Mosque in Faridpur, Bangladesh." |
| 12 | **Tatsunoko Production** | P31 animation studio → Institution, organisation (T8). Arts. fame 93 → cost 6. | **Tatsunoko Production** · 6 · Institution — Arts · At the start of your turn, if you control fewer than 3 tokens, create a 1/1 Figure token named Staff Member. "Japanese animation studio." |
Interactions these cards show:
- *Heart rot* on *Marc Fesneau* is illegal (Protected stops opponents' Doctrines). On *Tom Ewell* it makes a 2/2 Featured Legacy.
- *Monoid* on *Dichromorpha viridis* makes a 6/4 Well-sourced Stub that keeps growing to 8/6.
- *April 2021 nor'easter* destroys *Dichromorpha viridis* and both Elected Members, and leaves *Pathrail Mosque* at 0/3 with 1 damage.
- *Pathrail Mosque* and *2025 Tehreek-e-Labbaik Pakistan protests* are not Compatriots (Bangladesh vs Pakistan); *Pathrail Mosque* and *Zbyszek Godlewski* are not Contemporary (15th vs 20th century).
Sample log:
> Turn 5. alice deployed *Zbyszek Godlewski* (Polish protester, 1952–1970).[1]
> Turn 6. bob cited the *April 2021 nor'easter* (Slow-moving nor'easter in April 2021).[2] The *April 2021 nor'easter* dealt 1 damage to *Zbyszek Godlewski*.
> Turn 7. *Zbyszek Godlewski* (6/3) attacked. *Pallas's cat* (5/5) blocked *Zbyszek Godlewski*.[3] *Zbyszek Godlewski* was destroyed. alice drew a card.
---
## 10. Hand-offs
- **duel-core:** §2 rules and ruleset keys; `LogEvent` kinds needed by §8.2 (deploy, cast, adopt, attack, block, playerDamage, destroyed, effectDamage, tokenCreated, draw, connected, turnStart, gameOver with reason `life|library|concede|timeout|turnCap`). Each event carries card ids, P/T after the event, and Notability where relevant.
- **duel-cards:** §3 derivation, §4 thresholds and priority, §5 templates T1–T12, §6 tiers; the §9 table as golden tests.
- **sim-balance:** §2.6 targets; tune `keywordThresholds`, `connectedTiers`, T4's k−1, the Stub cap and the T8 token rate; report the first-player win rate and the cost-6 dominance check.
- **ui-pvp:** renders `RecapDoc` from §8.3.
## 11. Open questions for the sim (not blockers)
1. Disaster T4 at k−1 may be weak against 40-card boards; try k.
2. Stub at +2 counters on cheap bodies may be too strong (33% of Figures); try max 1.
3. **Locations (balance v1 finding):** Location-heavy decks win ~20% and Locations are the weakest cards. `territoryCap` 3, `locationsPerTurn` 2 and `garrisonStep` 15 move them ±3 points at most. Tested and **rejected for v1**: a T2 rider "When this enters, draw a card". It lifts the Location card (47 → 52%) but not Location-heavy decks (18 → 17%), pushes the first player back to 58.4%, and brings back library-out losses. Open for v1.1: a lever that helps Location-heavy decks without extra card flow, e.g. Territory that scales (+1 Citation per two Locations) or Garrison Locations that can block Featured.
+18 -7
View File
@@ -18,12 +18,13 @@ A mode is a JSON document, at most 8 KiB:
```json
{
"schema": "wikideck.mode/1",
"schema": "wikideck.mode/2",
"id": "trending",
"version": 1,
"name": "Trending",
"description": "Live Wikipedia pageview trends power cards up or down.",
"tags": ["live-data"],
"engine": "editwar",
"rules": { "trendUp": 25, "trendDown": -25 },
"cards": { "preset": "trending", "percentPerPoint": 25, "maxBonus": 3, "penalise": true },
"decks": { "kind": "starter" },
@@ -33,12 +34,14 @@ A mode is a JSON document, at most 8 KiB:
| Field | Meaning |
|---|---|
| `schema` | `wikideck.mode/2`. Night 1 documents (`wikideck.mode/1`) are rejected with a message saying what to change. |
| `engine` | Required: `editwar` (the Night 1 simultaneous-reveal game, `shared/game`) or `duel` (the Night 2 Magic-style duel, `shared/duel`). Duel modes only allow `constructed` and `draft` with `source: "collections"`: every card is one the players own. |
| `id`, `version` | Lowercase slug and a version integer. Bump `version` whenever the rules change, so old match records and leaderboards stay attributable (`<origin>#<id>@<version>`). |
| `name`, `description`, `tags` | Plain text only: no control characters or `<` `>`. |
| `rules` | **Overrides** on top of the engine's `DEFAULT_RULESET` (see `docs/game/ENGINE_API.md`). Objects merge one level deep; arrays and numbers replace. The merged result then goes through the engine's strict `parseRuleset`, so the engine alone decides what's legal (bounded turns, Topics, deck sizes, known keywords and portals only; see DESIGN.md §9 for the keys). |
| `cards` | A card-mapping **preset** from a fixed list. `standard` leaves cards as dealt. `live` freezes each card's live trend arrow (DESIGN §1.6, using the ruleset's `trendUp`/`trendDown`) at match start. `trending` does the same and also adds a bounded power bonus from the live pageview trend. The mode only picks a preset and tunes its bounded numbers. |
| `decks` | `starter` (everyone gets a seeded starter deck), `draft` (snake draft from a host-seeded pool of preview cards) or `constructed` (bring your own; see "Not yet" below). |
| `limits` | Concurrency and lobby expiry for this mode on this host. `turnSeconds` only applies to engines without their own turn timer; with tonight's engine, the ruleset's `turnSeconds` (plus 5 s network grace) is the timer. |
| `decks` | `constructed` (each player submits exactly `deckSize` NFT token ids they own; the host verifies ownership and confirmations on the chain, `minConfirmations` default 1, and builds every card from its block), `starter` (Edit War only: a seeded starter deck) or `draft` (snake draft; `source: "preview"` uses preview cards, Edit War only; `source: "collections"` pools both players' owned cards for that match only, and both must own at least `deckSize`). |
| `limits` | Concurrency and lobby expiry for this mode on this host. `rated: true` moves Elo (start 1200, K 24) when both seats are eom.dev accounts; `accountsOnly: true` refuses guest seats (owned-card modes always do). `turnSeconds` only applies to engines without their own turn timer; with tonight's engine, the ruleset's `turnSeconds` (plus 5 s network grace) is the timer. |
The schema is strict: unknown fields are rejected, as are prototype keys
(`__proto__`, `constructor`, `prototype`) anywhere in the document, nesting deeper than two
@@ -46,6 +49,15 @@ levels inside `rules`, more than 48 rule keys, and oversized strings and arrays.
**never** evaluates, imports or runs anything another peer sends. Nothing in a mode can name
a file, a URL, a script or a function.
### Seats, invites, quick match and polling (Night 2)
- **Seats:** `POST /modes/:id/lobbies`, `POST /lobbies/:id/join` and `POST /modes/:id/quick` take `{idToken, deck?, private?}` for an eom.dev account (the Dex ID token may also be sent as `Authorization: Bearer <jwt>`), or `{name, secret}` for a guest in Edit War modes. The reply is `{lobbyId, seat, token, invite, playerId}`; `token` is the seat bearer for every later call. Account player ids are `sha256("acct:" + iss + "\n" + sub)`.
- **Invites:** every lobby gets a 12-character `invite` code. `private: true` hides it from `/lobbies` and quick match. `GET /invites/:code` describes it and `POST /invites/:code/join` joins it (SPA link: `/play/invite/<code>`).
- **Quick match:** `POST /modes/:id/quick` joins the oldest open public lobby someone else opened (`matched: true`), or opens one (`matched: false`) to poll.
- **Polling:** every lobby view has a `version`. `GET /lobbies/:id?v=<version>` answers **204** while nothing changed. Poll; never hold requests open (the node caps concurrent `/api` requests).
- **Ladder:** `GET /modes/:id/ladder` (same as `/leaderboard`): entries carry `rating` (Elo, or null if unrated) plus W/L/D.
- **Records:** `GET /matches/:id` has the seed, rules, both decks (as the engine cards), every action, `engine`, `rated`, and for constructed modes `tokens` (the NFT ids each seat played), so the recap can replay the match.
## 2. Running your own modes
Configure modes with environment variables on your node:
@@ -255,10 +267,9 @@ be pinned in consensus.
## Not yet
- `constructed` decks of **owned NFTs**: the policy exists, but tonight the host deals
starter decks for it. Playing with your own cards needs a wallet-signed ownership proof
for the lobby (and then the engine's `cardFromStats`). That's a follow-up once accounts and
wallet linking (#7) settle.
- `constructed` decks of **owned NFTs** are verified on the hosting node only, against its
own account store (Night 2). Playing them on a *peer* needs a wallet-signed deck claim,
because accounts are per node; that's a follow-up.
- `trending` never calls Wikipedia when a match starts. The node warms a cache-only trend
store in the background, one page every 20 s (configurable, never faster than 15 s), through its existing enrichment cache (6 h TTL),
starting with the preview-card pages. A card whose page isn't warm yet gets no bonus. This
+73
View File
@@ -0,0 +1,73 @@
# Ownership and collection API (Night 2, #57)
Server-side checks that a player owns the cards they play. Off-chain only: nothing here moves, burns or locks a card, and nothing changes consensus.
## The rules (ruleset data)
| Key | Default | Meaning |
|---|---|---|
| `deckSize` | 40 | A constructed deck has exactly this many cards. A testnet mode file may lower it. |
| `maxCopiesPerPage` | 4 | The MTG-style copy limit. Cards minted from the same Wikipedia `pageId` are separate cards, but at most this many go in one deck. |
| `minConfirmations` | 1 | The confirmations each card's mint block needs. Rated play uses `RATED_MIN_CONFIRMATIONS` = 3. |
## `server/game/ownership.ts` (used by the PvP host)
```ts
verifyAccount(deps, idToken: unknown): Promise<Account>
resolveDeck(deps, account, tokenIds: unknown, opts?: Partial<OwnershipRules>): Promise<ChainCard[]>
collection(deps, account, opts?: { minConfirmations?: number }): Promise<ChainCard[]>
```
- **`deps`** is `{ ledger, accounts, verifyIdToken }`. In production, `server/testnet/http.ts` builds it from the node's `Ledger`, the shared `AccountStore`, and `accountVerifier()` from `server/account/router.ts`. It passes the result to `gameRouter({ ownership })`.
- **`resolveDeck`** accepts token ids only, never card JSON. For each card it checks:
- the card is on the canonical chain (`ledger.nft()`);
- its current owner (after transfers) is one of the account's linked wallets;
- it has enough confirmations;
- the deck size and copy limit.
Each card is rebuilt from its own block (`article` and `statsSnapshot`). The cards come back in the order given.
- **Errors** are thrown as `DeckError { code, status, tokenIds, pageId? }`. `tokenIds` lists every offending card of that class.
| `code` | `status` |
|---|---|
| `auth` | 401 |
| `size` | 400 |
| `duplicate-token` | 400 |
| `unknown-token` (not on chain, or malformed) | 400 |
| `not-owned` (includes "no linked wallet") | 403 |
| `unconfirmed` | 400 |
| `copy-limit` | 400 |
`OwnershipUnavailable` (503) means Dex is unreachable or the chain tip kept moving during a read.
- **`collection`** pages `ledger.deck()` (24 per page) across every linked wallet at one canonical tip, restarting if the tip moves. There is no 128-block snapshot cap.
## `GET /api/game/collection`
`Authorization: Bearer <Dex ID token>` (the same token as `/api/account/me`). Optional: `?minConfirmations=N`.
```ts
{
tip, wallets: string[],
deckSize: 40, copyLimit: 4, maxCopiesPerPage: 4, minConfirmations: 1,
owned: number, // confirmed cards across all linked wallets
playable: number, // Σ min(copies, copyLimit) per pageId
needed: number, // max(0, deckSize - playable)
eligible: boolean, // playable >= deckSize
cards: ChainCard[] // tokenId, owner, confirmations, pageId, title, revisionId, url, extract, imageUrl?,
// height, blockHash, createdAt, powHash, article, statsSnapshot
}
```
| Case | Response |
|---|---|
| No linked wallets | 200 with `cards: []` and `needed: 40` |
| Missing or invalid token | 401 |
| Dex unreachable | 503 |
| Bad query | 400 |
The UI shows `playable / deckSize`, for example "23 / 40 cards", and how to mine.
## Not covered (known gaps)
- **Peer hosts.** Account stores are per node, and a Dex token sent to a peer could be replayed elsewhere (engineer review §2, G6). This API is for the self-hosted node only. The stretch fix is a wallet-signed deck claim.
- **Plausibility of minted stats** (G5): `pageId` → `title` and `revisionId` → `size` are not cross-checked yet.
File diff suppressed because it is too large Load Diff
+32
View File
@@ -0,0 +1,32 @@
/**
* Writes docs/game/duel-card-sample.json (card-sample.json → DuelCard[]) and prints the
* type / Portal / cost / keyword distributions. Offline. Usage:
* node --experimental-strip-types scripts/duel-card-sample.ts [--check]
* --check exits non-zero if the committed fixture is out of date.
*/
import { readFileSync, writeFileSync } from 'node:fs';
import { deriveSample, type SampleCard } from '../shared/duel/sample.ts';
import { DERIVE_VERSION } from '../shared/duel/derive.ts';
const root = new URL('../', import.meta.url);
const sample = JSON.parse(readFileSync(new URL('docs/game/card-sample.json', root), 'utf8')) as { cards: SampleCard[] };
const cards = deriveSample(sample.cards);
const out = JSON.stringify({ source: 'docs/game/card-sample.json', deriveVersion: DERIVE_VERSION, count: cards.length, cards }, null, 1) + '\n';
const path = new URL('docs/game/duel-card-sample.json', root);
const tally = (f: (c: typeof cards[number]) => string | number) => {
const m = new Map<string | number, number>();
for (const c of cards) m.set(f(c), (m.get(f(c)) ?? 0) + 1);
return [...m].sort((a, b) => String(a[0]).localeCompare(String(b[0]), 'en', { numeric: true }))
.map(([k, v]) => `${k} ${v} (${(100 * v / cards.length).toFixed(1)}%)`).join(', ');
};
console.log('type:', tally(c => c.type));
console.log('typedBy:', tally(c => c.typedBy));
console.log('portal:', tally(c => c.portal));
console.log('cost:', tally(c => c.cost));
console.log('subtype:', tally(c => `${c.type}/${c.subtype ?? '-'}`));
console.log('keywords:', tally(c => c.keywords.join('+') || 'none'));
if (process.argv.includes('--check')) {
if (readFileSync(path, 'utf8') !== out) { console.error('duel-card-sample.json is stale'); process.exit(1); }
} else writeFileSync(path, out);
+17 -2
View File
@@ -12,12 +12,28 @@ export type AccountDeps = { config?: OidcConfig; keys?: DexKeys; store?: Account
type Authed = Request & { account?: Account };
const hex64 = z.string().regex(/^[a-f0-9]{64}$/);
/**
* Verifies a Dex ID token and records the account. Shared with the game routes
* (server/game/collection.ts, the PvP host) so every route uses the same store and keys.
* Throws TokenError (status 401) for a bad token; other errors mean Dex is unreachable.
*/
export function accountVerifier(config: OidcConfig, keys: Pick<DexKeys, 'key'>, store: Pick<AccountStore, 'upsert'>,
now: () => number = Date.now): (idToken: string) => Promise<Account> {
return async idToken => {
const claims = await verifyIdToken(idToken, keys, config, { now: now() });
const account: Account = { sub: claims.sub, issuer: claims.iss, name: displayName(claims), username: claims.preferred_username ?? '' };
store.upsert(account);
return account;
};
}
export function createAccountRouter(deps: AccountDeps = {}): Router {
const config = deps.config ?? oidcConfig();
const now = deps.now ?? Date.now;
const keys = deps.keys ?? new DexKeys(config, deps.fetcher, now);
const store = deps.store ?? new AccountStore(resolve(deps.dataDir ?? 'data', 'accounts.sqlite'), now);
const router = Router();
const verify = accountVerifier(config, keys, store, now);
const toAccount = (claims: Awaited<ReturnType<typeof verifyIdToken>>): Account =>
({ sub: claims.sub, issuer: claims.iss, name: displayName(claims), username: claims.preferred_username ?? '' });
@@ -26,8 +42,7 @@ export function createAccountRouter(deps: AccountDeps = {}): Router {
try {
const m = /^Bearer ([A-Za-z0-9_.-]+)$/.exec(req.get('authorization') ?? '');
if (!m) throw new TokenError('Log in with your eom.dev account');
req.account = toAccount(await verifyIdToken(m[1], keys, config, { now: now() }));
store.upsert(req.account);
req.account = await verify(m[1]);
next();
} catch (e) { next(e); }
};
+76
View File
@@ -0,0 +1,76 @@
/**
* GET /api/game/collection Authorization: Bearer <Dex ID token> [?minConfirmations=N]
*
* Every card the account's linked wallets own (no 128-block cap) and whether that is enough to
* build a deck. Eligibility counts the copy limit: 40 copies of one article is 4 playable cards.
*/
import { Router, type Request, type Response } from 'express';
import { DeckError, collectionAt, ownershipRules, playableCount, verifyAccount,
type ChainCard, type OwnershipDeps, type OwnershipRules } from './ownership.ts';
export type CollectionResponse = {
tip: string;
wallets: string[];
deckSize: number;
/** Max copies per pageId. `maxCopiesPerPage` is the same value under the ruleset's name. */
copyLimit: number;
maxCopiesPerPage: number;
minConfirmations: number;
/** Confirmed cards across all linked wallets. */
owned: number;
/** Σ min(copies, copyLimit) per pageId: the most cards a legal deck can draw from. */
playable: number;
/** max(0, deckSize - playable). */
needed: number;
/** playable >= deckSize. */
eligible: boolean;
/** `duel` is present when the server has a frozen profile for the card (see collectionRouter's `duelCard`). */
cards: (ChainCard & { duel?: unknown })[];
};
export function collectionResponse(deps: Pick<OwnershipDeps, 'ledger' | 'accounts'>, sub: string,
rules?: Partial<OwnershipRules>): CollectionResponse {
const r = ownershipRules(rules);
const { tip, wallets, cards } = collectionAt(deps, { sub }, { minConfirmations: r.minConfirmations });
const playable = playableCount(cards, r.maxCopiesPerPage);
return { tip, wallets, deckSize: r.deckSize, copyLimit: r.maxCopiesPerPage, maxCopiesPerPage: r.maxCopiesPerPage,
minConfirmations: r.minConfirmations, owned: cards.length, playable, needed: Math.max(0, r.deckSize - playable),
eligible: playable >= r.deckSize, cards };
}
export type CollectionRouterDeps = OwnershipDeps & {
rules?: Partial<OwnershipRules>;
/**
* Optional: the same chain card → duel card function the PvP host uses, so the browser shows and
* plays exactly what PvP would. Return undefined while a card's profile is pending; it must not fetch.
*/
duelCard?: (card: ChainCard) => unknown;
};
export function collectionRouter(deps: CollectionRouterDeps): Router {
const router = Router();
router.get('/', async (req: Request, res: Response) => {
res.setHeader('Cache-Control', 'no-store');
const q = req.query.minConfirmations;
if (q !== undefined && (typeof q !== 'string' || !/^[1-9]\d{0,3}$/.test(q))) { res.status(400).json({ error: 'Invalid minConfirmations' }); return; }
const m = /^Bearer ([A-Za-z0-9_.-]{1,8192})$/.exec(req.get('authorization') ?? '');
try {
const account = await verifyAccount(deps, m?.[1]);
const body = collectionResponse(deps, account.sub, { ...deps.rules, ...(q ? { minConfirmations: Number(q) } : {}) });
if (deps.duelCard) {
const toDuel = deps.duelCard;
body.cards = body.cards.map(c => {
let duel: unknown;
try { duel = toDuel(c); } catch { duel = undefined; }
return duel === undefined ? c : { ...c, duel };
});
}
res.json(body);
} catch (e) {
const err = e as Error & { status?: number };
const status = e instanceof DeckError ? err.status! : err.status === 503 ? 503 : 500;
res.status(status).json({ error: status === 500 ? 'Collection unavailable' : err.message });
}
});
return router;
}
+28
View File
@@ -40,4 +40,32 @@ export interface EnginePort<Rules = unknown, Card = unknown, State = unknown, Ac
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[]>;
}
+275 -72
View File
@@ -2,38 +2,64 @@
* Hosts lobbies and matches for this node's modes, with the deterministic engine.
* All state is off-chain and in memory; finished matches go to the MatchStore.
*
* Trust model: the host is authoritative for its own matches. Players are identified by a
* client-held secret (only its SHA-256 is stored or shown) and act through per-seat bearer
* tokens. Every action must equal one of the engine's legalActions for that seat.
* Trust model: the host is authoritative for its own matches. A seat is either an eom.dev
* account (Dex ID token in the create/join body, verified server-side; player id
* `sha256('acct:' + iss + '\n' + sub)`) or, in guest-friendly Edit War modes, a client-held
* secret (only its SHA-256 is stored). Seats act through per-seat bearer tokens. Every
* action must equal one of the engine's legalActions for that seat.
*
* Engines: each mode names its engine (`editwar` or `duel`); the host runs every engine it
* was given. Constructed decks are NFT token ids the player owns, resolved from the chain by
* the ownership port (server/game/ownership.ts) and turned into cards by the engine.
*/
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
import { isDeepStrictEqual } from 'node:util';
import { modeKey, resolveRuleset, trendBonus, clampPower, MODE_SCHEMA_VERSION,
type HostIdentity, type ModeDocument, type ModeList, type ModeStats, type LiveCardData } from '../../shared/game/modes.ts';
import type { EnginePort, Seat } from './engine-port.ts';
import { modeKey, resolveRuleset, trendBonus, clampPower, requiresAccount, MODE_SCHEMA_VERSION,
type EngineId, type HostIdentity, type ModeDocument, type ModeList, type ModeStats, type LiveCardData } from '../../shared/game/modes.ts';
import type { ChainCard, EnginePort, OwnershipPort, Seat, SeatAccount } from './engine-port.ts';
import { MatchStore, type MatchRecord } from './store.ts';
export class GameError extends Error {
readonly status: number;
constructor(status: number, message: string) { super(message); this.status = status; }
}
/** The lobby's creator no longer has a valid deck; the lobby was expired. */
class StaleLobby extends GameError { constructor(message: string) { super(409, message); } }
type Player = { id: string; name: string; tokenHash: Buffer; seen: number };
type AnyEngine = EnginePort<any, any, any, any>;
type Player = { id: string; name: string; tokenHash: Buffer; seen: number;
/** Set for account seats: who to resolve the deck for. Never the ID token itself. */
account?: SeatAccount;
/** Constructed modes: the token ids this seat submitted (re-resolved at match start). */
deckIds?: string[] };
type Phase = 'waiting' | 'starting' | 'drafting' | 'playing' | 'finished' | 'expired';
type Lobby = {
id: string; mode: ModeDocument; rules: unknown; seed: string; createdAt: number;
/** Bumped on every observable change, so unchanged polls (`?v=`) can return 204. */
version: number;
/** Private lobbies are hidden from lists and quick match; joined through the invite code. */
private?: boolean; invite?: string;
/** Rated (Elo) iff the mode is rated and both seats are accounts; decided at join. */
rated?: boolean;
/** Constructed modes: token ids per seat, for the record's references. */
tokens?: [string[], string[]];
players: Player[]; phase: Phase;
draft?: { pool: unknown[]; taken: (Seat | null)[]; order: Seat[]; turn: number; deadline: number };
decks?: [unknown[], unknown[]];
state?: unknown; actions: { seat: Seat; action: unknown }[]; startedAt?: number; lastMove: number; turnStartedAt?: number; turn?: number;
outcome?: { winner: Seat | null; reason: string }; matchId?: string;
};
type HostedMode = { mode: ModeDocument; rules: unknown };
type HostedMode = { mode: ModeDocument; rules: unknown; engine: AnyEngine };
export type HostOptions = {
identity: HostIdentity;
modes: ModeDocument[];
engine: EnginePort<any, any, any, any>;
/** Engines by id. Every mode's `engine` must be present here. */
engines?: Partial<Record<EngineId, AnyEngine>>;
/** Shorthand for `engines: { editwar: engine }` (Night 1 callers and tests). */
engine?: AnyEngine;
/** Account verification and server-side ownership (#57). Without it, account seats are unavailable. */
ownership?: OwnershipPort;
store: MatchStore;
/** Optional live Wikipedia trend lookup for `trending` modes. Failures mean "no bonus". */
liveData?: (pageId: number) => Promise<LiveCardData | null>;
@@ -42,16 +68,19 @@ export type HostOptions = {
maxLobbies?: number;
};
export type SeatTicket = { lobbyId: string; seat: Seat; token: string };
export type SeatTicket = { lobbyId: string; seat: Seat; token: string; invite?: string; playerId: string };
/** Body of create / join / quick match. `idToken` is a Dex ID token; `deck` is NFT token ids. */
export type SeatRequest = { name?: unknown; secret?: unknown; idToken?: unknown; deck?: unknown; private?: unknown };
const NAME = /^[\p{L}\p{N} _.\-]{1,24}$/u;
const SECRET = /^[A-Za-z0-9_-]{22,128}$/;
const LOBBY_ID = /^[a-f0-9]{24}$/;
const INVITE = /^[A-Za-z0-9_-]{12}$/;
export class ModeHost {
readonly identity: HostIdentity;
private readonly engine: EnginePort<any, any, any, any>;
private readonly store: MatchStore;
private readonly ownership?: OwnershipPort;
private readonly hosted = new Map<string, HostedMode>();
private readonly lobbies = new Map<string, Lobby>();
private readonly liveData?: HostOptions['liveData'];
@@ -60,24 +89,31 @@ export class ModeHost {
constructor(options: HostOptions) {
this.identity = options.identity;
this.engine = options.engine;
this.store = options.store;
this.ownership = options.ownership;
const engines: Partial<Record<EngineId, AnyEngine>> = { ...(options.engine ? { editwar: options.engine } : {}), ...options.engines };
this.liveData = options.liveData;
this.now = options.now ?? Date.now;
this.maxLobbies = options.maxLobbies ?? 512;
for (const mode of options.modes) {
if (this.hosted.has(mode.id)) throw new Error(`Duplicate mode id ${mode.id}`);
const engine = engines[mode.engine];
if (!engine) throw new Error(`Mode ${mode.id}: engine "${mode.engine}" is not available on this host`);
// Validate rules once at startup with the engine's own parser: a bad mode fails loudly.
const rules = resolveRuleset(this.engine.defaultRuleset, mode.rules, v => this.engine.parseRuleset(v));
if (mode.decks.kind === 'draft' && mode.decks.poolSize < 2 * this.engine.deckSize(rules)) {
const rules = resolveRuleset(engine.defaultRuleset, mode.rules, v => engine.parseRuleset(v));
const loaners = mode.decks.kind === 'starter' || (mode.decks.kind === 'draft' && mode.decks.source === 'preview');
// BRIEF decision 1: duel decks are only cards the players own. No starter, loaner or preview cards.
if (mode.engine === 'duel' && loaners) throw new Error(`Mode ${mode.id}: duel modes use owned cards only (constructed, or a collections draft)`);
if (mode.decks.kind === 'draft' && mode.decks.poolSize < 2 * engine.deckSize(rules)) {
throw new Error(`Mode ${mode.id}: draft poolSize must be at least 2 × deck size`);
}
if (mode.decks.kind !== 'draft') {
if (!loaners && !engine.fromChain) throw new Error(`Mode ${mode.id}: engine "${mode.engine}" cannot build cards from owned NFTs`);
if (mode.decks.kind === 'starter') {
// Host-dealt starter decks must be legal under the mode's rules, or the mode is unplayable.
try { this.engine.validateDeck(rules, this.engine.starterDeck(rules, 'startup-check')); }
try { engine.validateDeck(rules, engine.starterDeck(rules, 'startup-check')); }
catch (e) { throw new Error(`Mode ${mode.id}: starter decks are illegal under its rules (${(e as Error).message.slice(0, 120)}); use a draft deck policy`); }
}
this.hosted.set(mode.id, { mode, rules });
this.hosted.set(mode.id, { mode, rules, engine });
}
}
@@ -107,61 +143,145 @@ export class ModeHost {
openLobbies(modeId: string) {
this.mode(modeId);
return [...this.lobbies.values()].filter(l => l.mode.id === modeId && l.phase === 'waiting')
.slice(0, 50).map(l => ({ lobbyId: l.id, host: l.players[0]!.name, createdAt: l.createdAt }));
return [...this.lobbies.values()].filter(l => l.mode.id === modeId && l.phase === 'waiting' && !l.private)
.slice(0, 50).map(l => ({ lobbyId: l.id, host: l.players[0]!.name, createdAt: l.createdAt,
hostId: l.players[0]!.id, account: !!l.players[0]!.account }));
}
createLobby(modeId: string, player: { name: unknown; secret: unknown }): SeatTicket {
/** Look up a private (or public) waiting lobby by its invite code: what an invite link shows. */
invite(code: string) {
this.sweep();
const l = typeof code === 'string' && INVITE.test(code) ? [...this.lobbies.values()].find(x => x.invite === code) : undefined;
if (!l) throw new GameError(404, 'Invite not found or expired.');
return { lobbyId: l.id, phase: l.phase, open: l.phase === 'waiting', host: this.identity,
mode: { id: l.mode.id, version: l.mode.version, name: l.mode.name, engine: l.mode.engine },
createdBy: l.players[0]!.name, createdAt: l.createdAt, accountRequired: requiresAccount(l.mode) };
}
async createLobby(modeId: string, request: SeatRequest): Promise<SeatTicket> {
const h = this.mode(modeId);
this.sweep();
this.checkCapacity(h);
const p = await this.seat(h, request);
if (h.mode.decks.kind === 'constructed') await this.resolveDeck(h, p.player, request.deck);
return this.openLobby(h, p, request.private === true);
}
async join(lobbyId: string, request: SeatRequest): Promise<SeatTicket> {
const l = this.lobby(lobbyId);
this.sweep();
if (l.phase !== 'waiting') throw new GameError(409, 'This lobby is no longer open.');
const h = this.mode(l.mode.id);
const p = await this.seat(h, request);
const cards = h.mode.decks.kind === 'constructed' ? await this.resolveDeck(h, p.player, request.deck) : undefined;
return this.seatInLobby(l, p, cards);
}
/**
* Quick match: join the oldest open public lobby of this mode that someone else opened,
* else open a new public lobby and wait. No rating window (the ladder is small).
*/
async quickMatch(modeId: string, request: SeatRequest): Promise<SeatTicket & { matched: boolean }> {
const h = this.mode(modeId);
this.sweep();
const p = await this.seat(h, request);
const cards = h.mode.decks.kind === 'constructed' ? await this.resolveDeck(h, p.player, request.deck) : undefined;
const candidates = [...this.lobbies.values()].filter(l => l.mode.id === modeId && l.phase === 'waiting' && !l.private &&
l.players[0]!.id !== p.player.id).sort((a, b) => a.createdAt - b.createdAt);
for (const l of candidates) {
if (l.phase !== 'waiting') continue;
// A stale lobby (its host's cards moved) is expired and skipped: not the quick-matcher's fault.
try { return { ...await this.seatInLobby(l, p, cards), matched: true }; }
catch (e) { if (e instanceof StaleLobby) continue; throw e; }
}
this.checkCapacity(h);
return { ...this.openLobby(h, p, false), matched: false };
}
/** The lobby's current state version (see `view`). */
version(lobbyId: string): number { return this.lobby(lobbyId).version; }
private checkCapacity(h: HostedMode) {
const active = [...this.lobbies.values()].filter(l => l.phase !== 'finished' && l.phase !== 'expired');
if (active.length >= this.maxLobbies) throw new GameError(503, 'This host is full; try again later.');
if (active.filter(l => l.mode.id === modeId).length >= h.mode.limits.maxConcurrentMatches) {
if (active.filter(l => l.mode.id === h.mode.id).length >= h.mode.limits.maxConcurrentMatches) {
throw new GameError(503, 'This mode is at its match limit on this host; try again later.');
}
const p = this.player(player);
}
private openLobby(h: HostedMode, p: { player: Player; token: string }, isPrivate: boolean): SeatTicket {
const active = [...this.lobbies.values()].filter(l => l.phase !== 'finished' && l.phase !== 'expired');
if (active.filter(l => l.players.some(x => x.id === p.player.id)).length >= 3) {
throw new GameError(429, 'Too many open lobbies or matches for this player.');
}
const id = randomBytes(12).toString('hex');
const invite = randomBytes(9).toString('base64url');
const now = this.now();
this.lobbies.set(id, { id, mode: h.mode, rules: h.rules, seed: randomBytes(16).toString('hex'), createdAt: now,
players: [p.player], phase: 'waiting', actions: [], lastMove: now });
return { lobbyId: id, seat: 0, token: p.token };
version: 1, private: isPrivate, invite, players: [p.player], phase: 'waiting', actions: [], lastMove: now });
return { lobbyId: id, seat: 0, token: p.token, invite, playerId: p.player.id };
}
async join(lobbyId: string, player: { name: unknown; secret: unknown }): Promise<SeatTicket> {
const l = this.lobby(lobbyId);
this.sweep();
/** Seat a prepared player in a waiting lobby and start the draft or match. Synchronous until claimed. */
private async seatInLobby(l: Lobby, p: { player: Player; token: string }, joinerCards?: ChainCard[]): Promise<SeatTicket> {
// Re-check after the caller's awaits: another join may have claimed the lobby meanwhile.
if (l.phase !== 'waiting') throw new GameError(409, 'This lobby is no longer open.');
const p = this.player(player);
if (l.players[0]!.id === p.player.id) throw new GameError(409, 'You cannot play against yourself.');
l.players.push(p.player);
l.lastMove = this.now();
const h = this.mode(l.mode.id);
// Claim the lobby before any await, so a concurrent join can't also pass the 'waiting' check.
l.phase = 'starting';
if (l.mode.decks.kind === 'draft') this.startDraft(l);
else await this.startMatch(l, [this.engine.starterDeck(l.rules, `${l.seed}:0`), this.engine.starterDeck(l.rules, `${l.seed}:1`)]);
return { lobbyId: l.id, seat: 1, token: p.token };
l.lastMove = this.now();
const policy = h.mode.decks;
// The creator's cards may have moved since they opened the lobby: resolve them again now,
// at match start, before the joiner is seated (a stale lobby never lists the joiner).
const creatorCards = policy.kind === 'constructed'
? await this.resolveDeck(h, l.players[0]!, l.players[0]!.deckIds).catch(e => {
this.expire(l); throw new StaleLobby(`The lobby host's deck is no longer valid: ${(e as Error).message}`.slice(0, 200)); })
: undefined;
l.players.push(p.player);
l.rated = h.mode.limits.rated && l.players.every(x => x.account);
this.bump(l);
if (policy.kind === 'draft' && policy.source === 'collections') {
const pools = await Promise.all(l.players.map(x => this.ownershipCall(() => this.ownership!.collection(x.account!))))
.catch(e => { this.expire(l); throw e; });
const size = h.engine.deckSize(l.rules);
pools.forEach((c, seat) => { if (c.length < size) { this.expire(l);
throw new GameError(409, `${seat === 0 ? 'The lobby host' : 'You'} own${seat === 0 ? 's' : ''} ${c.length} / ${size} cards: both players must be eligible to draft.`); } });
const cards = seededShuffle([...pools[0]!, ...pools[1]!], `${l.seed}:pool`).slice(0, policy.poolSize)
.map(c => h.engine.fromChain!(l.rules, c));
this.startDraft(l, cards);
} else if (policy.kind === 'draft') this.startDraft(l, h.engine.previewPool(l.rules, `${l.seed}:pool`, policy.poolSize));
else if (policy.kind === 'constructed') {
const decks = [creatorCards!, joinerCards!];
l.tokens = [decks[0]!.map(c => c.tokenId), decks[1]!.map(c => c.tokenId)];
await this.startMatch(l, [decks[0]!.map(c => h.engine.fromChain!(l.rules, c)), decks[1]!.map(c => h.engine.fromChain!(l.rules, c))]);
} else await this.startMatch(l, [h.engine.starterDeck(l.rules, `${l.seed}:0`), h.engine.starterDeck(l.rules, `${l.seed}:1`)]);
return { lobbyId: l.id, seat: 1, token: p.token, invite: l.invite, playerId: p.player.id };
}
/** Public status, plus the seat's private view when a valid token is given. */
view(lobbyId: string, token?: string) {
/**
* Public status, plus the seat's private view when a valid token is given.
* With `since` equal to the lobby's current version, returns null (the router sends 204).
*/
view(lobbyId: string, token?: string, since?: number) {
const l = this.lobby(lobbyId);
this.sweep();
if (since !== undefined && since === l.version) return null;
const engine = this.mode(l.mode.id).engine;
const seat = token ? this.seatFor(l, token) : null;
const base = { lobbyId: l.id, phase: l.phase, host: this.identity,
mode: { id: l.mode.id, version: l.mode.version, name: l.mode.name },
players: l.players.map(p => ({ id: p.id, name: p.name })), seat, matchId: l.matchId ?? null,
const base = { lobbyId: l.id, version: l.version, phase: l.phase, host: this.identity,
mode: { id: l.mode.id, version: l.mode.version, name: l.mode.name, engine: l.mode.engine },
players: l.players.map(p => ({ id: p.id, name: p.name, account: !!p.account })), seat, matchId: l.matchId ?? null,
rated: l.rated ?? false, private: l.private ?? false, invite: seat === 0 ? l.invite ?? null : undefined,
outcome: l.outcome ?? null };
if (l.phase === 'drafting' && l.draft) {
if (l.phase === 'drafting' && l.draft && seat !== null) {
const d = l.draft;
return { ...base, draft: { pool: d.pool.map((c, i) => ({ index: i, card: this.engine.cardSummary(c), takenBy: d.taken[i] })),
return { ...base, draft: { pool: d.pool.map((c, i) => ({ index: i, card: engine.cardSummary(c), takenBy: d.taken[i] })),
toPick: d.order[d.turn] ?? null, deadline: d.deadline } };
}
if ((l.phase === 'playing' || l.phase === 'finished') && l.state !== undefined && seat !== null) {
return { ...base, state: this.engine.viewFor(l.state, seat),
legalActions: l.phase === 'playing' ? this.engine.legalActions(l.state, seat) : [] };
return { ...base, state: engine.viewFor(l.state, seat),
legalActions: l.phase === 'playing' ? engine.legalActions(l.state, seat) : [] };
}
return base;
}
@@ -184,7 +304,7 @@ export class ModeHost {
this.sweep();
if (l.phase !== 'playing' || l.state === undefined) throw new GameError(409, 'No match in progress.');
// The host never trusts a client action: it must be one of the engine's legal actions.
const legal = this.engine.legalActions(l.state, seat);
const legal = this.mode(l.mode.id).engine.legalActions(l.state, seat);
const chosen = legal.find(a => isDeepStrictEqual(a, action));
if (chosen === undefined) throw new GameError(400, 'Illegal action.');
this.apply(l, seat, chosen);
@@ -195,10 +315,11 @@ export class ModeHost {
resign(lobbyId: string, token: string) {
const l = this.lobby(lobbyId);
const seat = this.requireSeat(l, token);
if (l.phase === 'waiting') { l.phase = 'expired'; return this.view(lobbyId, token); }
if (l.phase === 'waiting') { this.expire(l); return this.view(lobbyId, token); }
if (l.phase !== 'playing' && l.phase !== 'drafting') throw new GameError(409, 'Nothing to resign.');
if (l.phase === 'playing' && l.state !== undefined && this.engine.concedeAction) {
this.apply(l, seat, this.engine.concedeAction(seat), 'resign');
const engine = this.mode(l.mode.id).engine;
if (l.phase === 'playing' && l.state !== undefined && engine.concedeAction) {
this.apply(l, seat, engine.concedeAction(seat), 'resign');
if ((l.phase as Phase) === 'finished') return this.view(lobbyId, token);
}
this.finish(l, seat === 0 ? 1 : 0, 'resign');
@@ -239,7 +360,11 @@ export class ModeHost {
if (typeof raw.id !== 'string' || !LOBBY_ID.test(raw.id) || this.lobbies.has(raw.id)) continue;
if (!['waiting', 'drafting', 'playing'].includes(raw.phase) || !Array.isArray(raw.players) || raw.players.length < 1 || raw.players.length > 2) continue;
const lobby: Lobby = { ...raw, mode: h.mode, rules: h.rules,
players: raw.players.map((p: any) => ({ id: String(p.id), name: String(p.name), seen: now, tokenHash: Buffer.from(String(p.tokenHash), 'hex') })),
players: raw.players.map((p: any) => ({ id: String(p.id), name: String(p.name), seen: now, tokenHash: Buffer.from(String(p.tokenHash), 'hex'),
...(p.account && typeof p.account.sub === 'string' && typeof p.account.issuer === 'string'
? { account: { sub: p.account.sub, issuer: p.account.issuer, name: String(p.account.name ?? p.name) } } : {}),
...(Array.isArray(p.deckIds) ? { deckIds: p.deckIds.map(String).slice(0, 64) } : {}) })),
version: Number.isSafeInteger(raw.version) ? raw.version : 1,
lastMove: now, createdAt: raw.phase === 'waiting' ? now : raw.createdAt, turnStartedAt: now };
if (lobby.players.some(p => p.tokenHash.length !== 32)) continue;
if (lobby.draft && lobby.mode.decks.kind === 'draft') lobby.draft.deadline = now + lobby.mode.decks.pickSeconds * 1000;
@@ -255,16 +380,17 @@ export class ModeHost {
sweep(): void {
const now = this.now();
for (const l of this.lobbies.values()) {
if (l.phase === 'waiting' && now - l.createdAt > l.mode.limits.lobbyMinutes * 60_000) l.phase = 'expired';
const engine = this.hosted.get(l.mode.id)!.engine;
if (l.phase === 'waiting' && now - l.createdAt > l.mode.limits.lobbyMinutes * 60_000) this.expire(l);
else if (l.phase === 'drafting' && l.draft && now > l.draft.deadline) {
// Auto-pick the first free card for whoever is stalling; synchronous, no live data.
const idx = l.draft.taken.indexOf(null);
if (idx >= 0) void this.takePick(l, l.draft.order[l.draft.turn]!, idx).catch(() => { l.phase = 'expired'; });
} else if (l.phase === 'playing' && l.state !== undefined && now - (l.turnStartedAt ?? l.lastMove) > this.turnMs(l)) {
const waiting = ([0, 1] as Seat[]).filter(s => this.engine.legalActions(l.state, s).length > 0);
if (this.engine.timeoutAction) {
const waiting = ([0, 1] as Seat[]).filter(s => engine.legalActions(l.state, s).length > 0);
if (engine.timeoutAction) {
// The engine decides what a timeout means (auto-commit, AFK forfeit); it is logged and replayable.
for (const s of waiting) if (l.phase === 'playing') this.apply(l, s, this.engine.timeoutAction(s));
for (const s of waiting) if (l.phase === 'playing') this.apply(l, s, engine.timeoutAction(s));
l.turnStartedAt = now;
} else if (waiting.length === 1) this.finish(l, waiting[0] === 0 ? 1 : 0, 'timeout');
else this.finish(l, null, 'abandoned');
@@ -273,17 +399,17 @@ export class ModeHost {
}
}
private startDraft(l: Lobby) {
private startDraft(l: Lobby, pool: unknown[]) {
if (l.mode.decks.kind !== 'draft') return;
const size = this.engine.deckSize(l.rules);
const pool = this.engine.previewPool(l.rules, `${l.seed}:pool`, l.mode.decks.poolSize);
if (pool.length < 2 * size) throw new GameError(500, 'Engine returned a short draft pool.');
const size = this.mode(l.mode.id).engine.deckSize(l.rules);
if (pool.length < 2 * size) { this.expire(l); throw new GameError(409, `The draft pool has only ${pool.length} cards; it needs ${2 * size}.`); }
// Snake order 0,1,1,0,0,1,... with a seed-chosen first picker.
const first: Seat = parseInt(l.seed.slice(0, 2), 16) % 2 === 0 ? 0 : 1;
const order: Seat[] = [];
for (let i = 0; i < 2 * size; i++) order.push(((Math.floor((i + 1) / 2) % 2 === 0 ? first : 1 - first)) as Seat);
l.draft = { pool, taken: pool.map(() => null), order, turn: 0, deadline: this.now() + l.mode.decks.pickSeconds * 1000 };
l.phase = 'drafting';
this.bump(l);
}
private async takePick(l: Lobby, seat: Seat, index: number) {
@@ -291,6 +417,7 @@ export class ModeHost {
d.taken[index] = seat;
d.turn++;
l.lastMove = this.now();
this.bump(l);
if (l.mode.decks.kind === 'draft') d.deadline = this.now() + l.mode.decks.pickSeconds * 1000;
if (d.turn >= d.order.length) {
const decks: [unknown[], unknown[]] = [[], []];
@@ -300,34 +427,37 @@ export class ModeHost {
}
private async startMatch(l: Lobby, decks: [unknown[], unknown[]]) {
const engine = this.mode(l.mode.id).engine;
const mapped = await Promise.all(decks.map(d => this.mapDeck(l.mode, d))) as [unknown[], unknown[]];
for (const d of mapped) {
try { this.engine.validateDeck(l.rules, d); }
catch (e) { l.phase = 'expired'; throw new GameError(400, `Deck rejected by the engine: ${(e as Error).message}`.slice(0, 200)); }
try { engine.validateDeck(l.rules, d); }
catch (e) { this.expire(l); throw new GameError(400, `Deck rejected by the engine: ${(e as Error).message}`.slice(0, 200)); }
}
l.decks = mapped;
l.state = this.engine.createMatch(l.rules, mapped, l.seed);
l.state = engine.createMatch(l.rules, mapped, l.seed);
l.phase = 'playing';
l.startedAt = l.lastMove = l.turnStartedAt = this.now();
l.turn = this.engine.turnOf?.(l.state);
l.turn = engine.turnOf?.(l.state);
delete l.draft;
if (this.engine.isOver(l.state)) { const r = this.engine.result(l.state); this.finish(l, r.winner, r.reason ?? 'complete'); }
this.bump(l);
if (engine.isOver(l.state)) { const r = engine.result(l.state); this.finish(l, r.winner, r.reason ?? 'complete'); }
}
/** Apply the mode's card-mapping preset. Bonus data is looked up once, before the match. */
private async mapDeck(mode: ModeDocument, deck: unknown[]): Promise<unknown[]> {
const mapping = mode.cards;
if (mapping.preset === 'standard' || !this.liveData) return deck;
const { engine, rules } = this.hosted.get(mode.id)!;
return Promise.all(deck.map(async card => {
const pageId = this.engine.cardPageId(card);
const pageId = engine.cardPageId(card);
if (pageId === null) return card;
const live = await this.liveData!(pageId).catch(() => null);
if (!live) return card;
// `live` and `trending`: freeze the live trend arrow onto the card (engine rules decide its effect).
let mapped = this.engine.applyLive ? this.engine.applyLive(this.hosted.get(mode.id)!.rules, card, live) : card;
let mapped = engine.applyLive ? engine.applyLive(rules, card, live) : card;
if (mapping.preset === 'trending') {
const bonus = trendBonus(mapping, live.trendPercent);
if (bonus !== 0) mapped = this.engine.withPower(mapped, clampPower(this.engine.cardPower(mapped) + bonus));
if (bonus !== 0) mapped = engine.withPower(mapped, clampPower(engine.cardPower(mapped) + bonus));
}
return mapped;
}));
@@ -335,18 +465,20 @@ export class ModeHost {
/** Apply an action already known to be legal (or host-issued), log it, and settle the match if over. */
private apply(l: Lobby, seat: Seat, action: unknown, reason?: string) {
l.state = this.engine.applyAction(l.state, seat, action);
const engine = this.mode(l.mode.id).engine;
l.state = engine.applyAction(l.state, seat, action);
l.actions.push({ seat, action });
l.lastMove = this.now();
const turn = this.engine.turnOf?.(l.state);
this.bump(l);
const turn = engine.turnOf?.(l.state);
if (turn !== l.turn) { l.turn = turn; l.turnStartedAt = l.lastMove; }
if (this.engine.isOver(l.state)) { const r = this.engine.result(l.state); this.finish(l, r.winner, reason ?? r.reason ?? 'complete'); }
if (engine.isOver(l.state)) { const r = engine.result(l.state); this.finish(l, r.winner, reason ?? r.reason ?? 'complete'); }
else if (l.actions.length >= 2000) this.finish(l, null, 'action-limit');
}
/** Turn timer: the engine's own per-turn limit plus a little network grace, else the mode's limit. */
private turnMs(l: Lobby): number {
const engineSeconds = this.engine.turnSeconds?.(l.rules);
const engineSeconds = this.mode(l.mode.id).engine.turnSeconds?.(l.rules);
return engineSeconds !== undefined ? (engineSeconds + 5) * 1000 : l.mode.limits.turnSeconds * 1000;
}
@@ -355,12 +487,63 @@ export class ModeHost {
l.phase = 'finished';
l.outcome = { winner, reason };
l.lastMove = this.now();
this.bump(l);
if (!l.decks || l.players.length !== 2) return; // Resigned during draft: no match record.
const matchId = randomBytes(16).toString('hex');
l.matchId = matchId;
this.store.add({ matchId, modeId: l.mode.id, modeVersion: l.mode.version, seed: l.seed, rules: l.rules,
players: l.players.map(p => ({ id: p.id, name: p.name })), winner, reason: reason.slice(0, 40),
startedAt: l.startedAt ?? l.createdAt, endedAt: l.lastMove, decks: l.decks, actions: l.actions });
this.store.add({ matchId, modeId: l.mode.id, modeVersion: l.mode.version, engine: l.mode.engine, rated: l.rated ?? false,
seed: l.seed, rules: l.rules,
players: l.players.map(p => ({ id: p.id, name: p.name, account: !!p.account })), winner, reason: reason.slice(0, 40),
startedAt: l.startedAt ?? l.createdAt, endedAt: l.lastMove, decks: l.decks, actions: l.actions,
...(l.tokens ? { tokens: l.tokens } : {}) });
}
private bump(l: Lobby) { l.version = (l.version ?? 0) + 1; }
private expire(l: Lobby) {
if (l.phase === 'finished' || l.phase === 'expired') return;
l.phase = 'expired'; l.lastMove = this.now(); this.bump(l);
}
/** Verify the seat: an eom.dev account (ID token) or, where the mode allows guests, a secret. */
private async seat(h: HostedMode, input: SeatRequest): Promise<{ player: Player; token: string }> {
const token = randomBytes(24).toString('base64url');
if (input.idToken !== undefined && input.idToken !== null && input.idToken !== '') {
if (!this.ownership) throw new GameError(503, 'eom.dev accounts are not available on this host.');
const account = await this.ownershipCall(() => this.ownership!.verifyAccount(input.idToken));
const id = createHash('sha256').update(`acct:${account.issuer}\n${account.sub}`).digest('hex');
const name = displayName(account.name || account.username || '') ?? 'Player';
return { player: { id, name, tokenHash: hashToken(token), seen: this.now(),
account: { sub: account.sub, issuer: account.issuer, name } }, token };
}
if (requiresAccount(h.mode)) throw new GameError(401, 'This mode plays with cards you own: log in with your eom.dev account.');
return this.player(input, token);
}
/** Resolve a seat's submitted token ids to owned, confirmed chain cards (#57). */
private async resolveDeck(h: HostedMode, p: Player, tokenIds: unknown): Promise<ChainCard[]> {
if (h.mode.decks.kind !== 'constructed') return [];
if (!this.ownership || !p.account) throw new GameError(401, 'Log in with your eom.dev account to play your own cards.');
const deckSize = h.engine.deckSize(h.rules);
if (!Array.isArray(tokenIds) || tokenIds.length !== deckSize || !tokenIds.every(t => typeof t === 'string' && t.length <= 128)) {
throw new GameError(400, `A deck is exactly ${deckSize} card token ids you own.`);
}
const cards = await this.ownershipCall(() => this.ownership!.resolveDeck(p.account!, tokenIds,
{ deckSize, maxCopiesPerPage: h.engine.copyLimit?.(h.rules) ?? 4, minConfirmations: h.mode.decks.kind === 'constructed' ? h.mode.decks.minConfirmations : 1 }));
// Belt and braces: the ownership layer must hand back exactly the submitted tokens.
if (cards.length !== deckSize || cards.some((c, i) => c.tokenId !== tokenIds[i])) throw new GameError(500, 'Ownership check returned a different deck.');
p.deckIds = [...tokenIds as string[]];
return cards;
}
/** Pass player-facing ownership errors (status 4xx) through; anything else is a 503. */
private async ownershipCall<T>(fn: () => Promise<T>): Promise<T> {
try { return await fn(); }
catch (e) {
if (e instanceof GameError) throw e;
const status = (e as { status?: unknown })?.status;
if (typeof status === 'number' && status >= 400 && status < 500) throw new GameError(status, String((e as Error).message).slice(0, 200));
throw new GameError(503, 'Could not check accounts or ownership right now; try again.');
}
}
private mode(modeId: string): HostedMode {
@@ -373,12 +556,11 @@ export class ModeHost {
if (!l) throw new GameError(404, 'Lobby not found.');
return l;
}
private player(input: { name: unknown; secret: unknown }): { player: Player; token: string } {
private player(input: SeatRequest, token: string): { player: Player; token: string } {
const name = typeof input.name === 'string' ? input.name.trim() : '';
if (!NAME.test(name)) throw new GameError(400, 'Name must be 1-24 letters, digits, spaces, _ . or -');
if (typeof input.secret !== 'string' || !SECRET.test(input.secret)) throw new GameError(400, 'Invalid player secret.');
const id = createHash('sha256').update(`wikideck-player:${input.secret}`).digest('hex');
const token = randomBytes(24).toString('base64url');
return { player: { id, name, tokenHash: hashToken(token), seen: this.now() }, token };
}
private seatFor(l: Lobby, token: string): Seat | null {
@@ -394,3 +576,24 @@ export class ModeHost {
}
function hashToken(token: string): Buffer { return createHash('sha256').update(token).digest(); }
/** An account display name reduced to the lobby name alphabet; null if nothing is left. */
function displayName(raw: string): string | null {
const cleaned = raw.normalize('NFC').replace(/[^\p{L}\p{N} _.\-]/gu, '').replace(/\s+/g, ' ').trim().slice(0, 24).trim();
return NAME.test(cleaned) ? cleaned : null;
}
/** Deterministic Fisher-Yates from a seed (SHA-256 counter stream): replayable draft pools. */
export function seededShuffle<T>(items: T[], seed: string): T[] {
const out = [...items];
let counter = 0, buf = Buffer.alloc(0), off = 0;
const next32 = () => {
if (off + 4 > buf.length) { buf = createHash('sha256').update(`${seed}:${counter++}`).digest(); off = 0; }
const v = buf.readUInt32BE(off); off += 4; return v;
};
for (let i = out.length - 1; i > 0; i--) {
const j = next32() % (i + 1);
[out[i], out[j]] = [out[j]!, out[i]!];
}
return out;
}
+14 -3
View File
@@ -10,15 +10,26 @@ import { ModeDiscovery } from './discovery.ts';
import { ModeHost } from './host.ts';
import { createGameRouter } from './router.ts';
import { MatchStore } from './store.ts';
import type { EnginePort } from './engine-port.ts';
import type { EnginePort, OwnershipPort } from './engine-port.ts';
import type { EngineId } from '../../shared/game/modes.ts';
import { TrendCache } from './trends.ts';
import type { OwnershipDeps } from './ownership.ts';
type Enrichment = { get(pageId: number): Promise<{ pageviews: { trendPercent: number | null } }> };
export async function gameRouter(options: { dataDir: string | null; enrichment?: Enrichment;
engine?: EnginePort<any, any, any, any>; env?: NodeJS.ProcessEnv; warmTrends?: boolean; handleSignals?: boolean }): Promise<express.Router> {
/** The Edit War engine (default: the real binding). */
engine?: EnginePort<any, any, any, any>;
/** Extra engines by id, e.g. `{ duel }` (tests inject stubs). */
engines?: Partial<Record<EngineId, EnginePort<any, any, any, any>>>;
/** Account verification + server-side ownership, adapted from server/game/ownership.ts (#57). */
ownershipPort?: OwnershipPort;
/** Server-side ownership deps (#57): http.ts passes `{ledger, accounts, verifyIdToken}`; adapted to the port here. */
ownership?: OwnershipDeps;
env?: NodeJS.ProcessEnv; warmTrends?: boolean; handleSignals?: boolean }): Promise<express.Router> {
const env = options.env ?? process.env;
const engine = options.engine ?? (await import('./engine-binding.ts')).engineBinding;
const engines = { editwar: engine, ...options.engines };
const modes = loadModes(env);
// Trends come from a slowly warmed, cache-only store: never a Wikipedia call per match.
let trends: TrendCache | undefined;
@@ -36,7 +47,7 @@ export async function gameRouter(options: { dataDir: string | null; enrichment?:
}
if (options.warmTrends !== false) trends.start();
}
const host = new ModeHost({ identity: hostIdentity(env), modes, engine,
const host = new ModeHost({ identity: hostIdentity(env), modes, engines, ownership: options.ownershipPort,
store: new MatchStore(options.dataDir ? join(options.dataDir, 'game') : null),
liveData: trends ? async pageId => trends!.get(pageId) : undefined });
const discovery = new ModeDiscovery({ peers: gamePeers(env) });
+17 -5
View File
@@ -1,12 +1,24 @@
{
"schema": "wikideck.mode/1",
"schema": "wikideck.mode/2",
"id": "classic",
"version": 1,
"name": "Classic",
"description": "The base WikiDeck rules with starter decks. Cards use their at-mint snapshot stats.",
"tags": ["base", "starter"],
"tags": [
"base",
"starter"
],
"engine": "editwar",
"rules": {},
"cards": { "preset": "standard" },
"decks": { "kind": "starter" },
"limits": { "maxConcurrentMatches": 32, "turnSeconds": 90, "lobbyMinutes": 15 }
"cards": {
"preset": "standard"
},
"decks": {
"kind": "starter"
},
"limits": {
"maxConcurrentMatches": 32,
"turnSeconds": 90,
"lobbyMinutes": 15
}
}
+3 -1
View File
@@ -1,5 +1,5 @@
{
"schema": "wikideck.mode/1",
"schema": "wikideck.mode/2",
"id": "draft",
"version": 1,
"name": "Snake Draft",
@@ -8,6 +8,7 @@
"draft",
"no-collection"
],
"engine": "editwar",
"rules": {
"deckSize": 10,
"openingHand": 4
@@ -17,6 +18,7 @@
},
"decks": {
"kind": "draft",
"source": "preview",
"poolSize": 30,
"pickSeconds": 30
},
+2 -1
View File
@@ -1,5 +1,5 @@
{
"schema": "wikideck.mode/1",
"schema": "wikideck.mode/2",
"id": "trending",
"version": 1,
"name": "Trending",
@@ -8,6 +8,7 @@
"live-data",
"starter"
],
"engine": "editwar",
"rules": {
"trendUp": 25,
"trendDown": -25
+211
View File
@@ -0,0 +1,211 @@
/**
* Server-side ownership for constructed play (Night 2, #57). Signature agreed with host-pvp (#56).
*
* The host never trusts card data from a client. A deck arrives as token ids only; each one
* must be on the canonical chain, owned by one of the account's linked wallets, and confirmed
* enough. The card is then rebuilt from its own block (article + mint stats snapshot).
*
* Off-chain only: nothing here moves, burns or locks a card, and nothing touches consensus.
* No Wikipedia calls; the only I/O is the injected ID-token verifier (Dex JWKS, cached).
*/
import type { Account } from '../account/store.ts';
import type { Article } from '../../shared/protocol.ts';
import type { MintStatsSnapshot } from '../../shared/enrichment.ts';
import type { TestnetBlock } from '../../shared/testnet.ts';
export type OwnershipRules = {
/** Exact deck size for constructed play. Production is 40; a testnet mode file may lower it. */
deckSize: number;
/** MTG-style copy limit: cards minted from the same Wikipedia pageId. */
maxCopiesPerPage: number;
/** Minimum confirmations of each card's mint block (1 casual, 3 rated). */
minConfirmations: number;
};
export const DEFAULT_OWNERSHIP_RULES: Readonly<OwnershipRules> = Object.freeze({ deckSize: 40, maxCopiesPerPage: 4, minConfirmations: 1 });
export const RATED_MIN_CONFIRMATIONS = 3;
/** Upper bound on any deck request we will even look at (a deck is 40; this only guards the loop). */
export const MAX_DECK_TOKENS = 200;
/** Guard against an unbounded collection. Far above anything the chain can mint for one player soon. */
export const MAX_COLLECTION = 20_000;
/** server/testnet/ledger.ts MAX_DECK_PAGE. */
const PAGE = 24;
/** A tip change mid-scan restarts the scan; give up after this many rather than loop forever. */
const MAX_RESTARTS = 4;
// Structural: server/testnet/ledger.ts `Ledger` and server/account/store.ts `AccountStore`
// satisfy these, and tests pass in-memory fixtures.
export type OwnershipLedger = {
nft(tokenId: string): { block: TestnetBlock; owner: string; sequence: number; confirmations: number } | undefined;
deck(address: string, offset: number, limit: number): {
tip: string; total: number; next: number | null;
nfts: { block: TestnetBlock; sequence: number; confirmations: number }[];
};
summary(): { tip: string; height: number };
};
export type OwnershipAccounts = { wallets(sub: string): { address: string }[]; upsert?(a: Account): void };
export type OwnershipDeps = {
ledger: OwnershipLedger;
accounts: OwnershipAccounts;
/** server/account/router.ts accountVerifier(); throws an error with status 401 for a bad token. */
verifyIdToken(idToken: string): Promise<Account>;
};
/** One owned NFT as built from its canonical block (never from client JSON). */
export type ChainCard = {
tokenId: string;
/** Current owner (after transfers), one of the account's linked wallets. */
owner: string;
confirmations: number;
pageId: number;
title: string;
revisionId: number;
url: string;
extract: string;
imageUrl?: string;
height: number;
blockHash: string;
createdAt: number;
powHash: string;
article: Article;
statsSnapshot: MintStatsSnapshot;
};
export type DeckErrorCode = 'auth' | 'size' | 'duplicate-token' | 'unknown-token' | 'not-owned' | 'unconfirmed' | 'copy-limit';
const STATUS: Record<DeckErrorCode, 400 | 401 | 403> = {
auth: 401, size: 400, 'duplicate-token': 400, 'unknown-token': 400, 'not-owned': 403, unconfirmed: 400, 'copy-limit': 400,
};
export class DeckError extends Error {
readonly code: DeckErrorCode;
/** Every offending token of this class, so the UI can highlight them. */
readonly tokenIds: string[];
readonly status: 400 | 401 | 403;
readonly pageId?: number;
constructor(code: DeckErrorCode, message: string, tokenIds: string[] = [], pageId?: number) {
super(message);
this.name = 'DeckError';
this.code = code; this.tokenIds = tokenIds; this.status = STATUS[code];
if (pageId !== undefined) this.pageId = pageId;
}
}
/** Thrown when Dex or the ledger cannot answer right now (not the player's fault). */
export class OwnershipUnavailable extends Error { readonly status = 503; }
const TOKEN = /^[a-f0-9]{64}$/;
const isInt = (n: unknown, min: number, max: number): n is number => Number.isSafeInteger(n) && (n as number) >= min && (n as number) <= max;
/** Merges partial rules over the defaults and rejects nonsense (mode files are data, so validate). */
export function ownershipRules(rules: Partial<OwnershipRules> = {}): OwnershipRules {
const defined = Object.fromEntries(Object.entries(rules).filter(([, v]) => v !== undefined)) as Partial<OwnershipRules>;
const r = { ...DEFAULT_OWNERSHIP_RULES, ...defined };
if (!isInt(r.deckSize, 1, MAX_DECK_TOKENS)) throw new RangeError(`deckSize must be 1..${MAX_DECK_TOKENS}`);
if (!isInt(r.maxCopiesPerPage, 1, MAX_DECK_TOKENS)) throw new RangeError(`maxCopiesPerPage must be 1..${MAX_DECK_TOKENS}`);
if (!isInt(r.minConfirmations, 1, 1_000_000)) throw new RangeError('minConfirmations must be >= 1');
return r;
}
/** Builds the card from the canonical block. `owner` is the current owner from the index, not the miner. */
export function cardFromChain(nft: { block: TestnetBlock; confirmations: number }, owner: string): ChainCard {
const b = structuredClone(nft.block);
const card: ChainCard = { tokenId: b.tokenId, owner, confirmations: nft.confirmations,
pageId: b.article.pageId, title: b.article.title, revisionId: b.article.revisionId, url: b.article.url, extract: b.article.extract,
height: b.height, blockHash: b.hash, createdAt: b.createdAt, powHash: b.powHash, article: b.article, statsSnapshot: b.statsSnapshot };
if (b.article.image) card.imageUrl = b.article.image;
return card;
}
/** Verifies a Dex ID token from a request body. Throws DeckError('auth') or OwnershipUnavailable. */
export async function verifyAccount(deps: Pick<OwnershipDeps, 'verifyIdToken'>, idToken: unknown): Promise<Account> {
if (typeof idToken !== 'string' || !idToken || idToken.length > 8192) throw new DeckError('auth', 'Log in with your eom.dev account to play with your cards');
try { return await deps.verifyIdToken(idToken); }
catch (e) {
if ((e as { status?: number }).status === 401) throw new DeckError('auth', (e as Error).message || 'Log in again with your eom.dev account');
throw new OwnershipUnavailable('eom.dev login is temporarily unavailable');
}
}
/**
* Verifies a constructed deck for an already-verified account. Resolves to the cards in the
* order given, or throws the first class of DeckError found (listing every offending token).
*/
export async function resolveDeck(deps: Pick<OwnershipDeps, 'ledger' | 'accounts'>, account: Pick<Account, 'sub'>, tokenIds: unknown,
opts?: Partial<OwnershipRules>): Promise<ChainCard[]> {
const r = ownershipRules(opts);
if (!Array.isArray(tokenIds) || tokenIds.length > MAX_DECK_TOKENS) throw new DeckError('size', `A deck is exactly ${r.deckSize} cards`);
const invalid = tokenIds.filter(t => typeof t !== 'string' || !TOKEN.test(t)).map(t => String(t).slice(0, 80)).slice(0, 10);
if (invalid.length) throw new DeckError('unknown-token', 'Invalid card identifier', invalid);
const ids = tokenIds as string[];
if (ids.length !== r.deckSize) throw new DeckError('size', `A deck is exactly ${r.deckSize} cards (got ${ids.length})`);
const seen = new Set<string>(), dupes = new Set<string>();
for (const id of ids) (seen.has(id) ? dupes : seen).add(id);
if (dupes.size) throw new DeckError('duplicate-token', 'The same card appears more than once', [...dupes]);
const wallets = new Set(deps.accounts.wallets(account.sub).map(w => w.address));
if (!wallets.size) throw new DeckError('not-owned', 'Link a wallet to your eom.dev account to play with your cards', ids);
const cards: ChainCard[] = [], missing: string[] = [], foreign: string[] = [], young: string[] = [];
for (const id of ids) {
const nft = deps.ledger.nft(id);
if (!nft || nft.block.tokenId !== id) { missing.push(id); continue; }
if (!wallets.has(nft.owner)) { foreign.push(id); continue; }
if (nft.confirmations < r.minConfirmations) { young.push(id); continue; }
cards.push(cardFromChain(nft, nft.owner));
}
if (missing.length) throw new DeckError('unknown-token', 'Card not found on the canonical chain', missing);
if (foreign.length) throw new DeckError('not-owned', 'Card is not owned by a wallet linked to this account', foreign);
if (young.length) throw new DeckError('unconfirmed', `Card needs ${r.minConfirmations} confirmation${r.minConfirmations === 1 ? '' : 's'}`, young);
const byPage = new Map<number, string[]>();
for (const c of cards) byPage.set(c.pageId, [...(byPage.get(c.pageId) ?? []), c.tokenId]);
for (const [pageId, tokens] of byPage)
if (tokens.length > r.maxCopiesPerPage) throw new DeckError('copy-limit', `At most ${r.maxCopiesPerPage} copies of the same article`, tokens, pageId);
return cards;
}
/**
* Every card the account owns across its linked wallets, read at one canonical tip (restarting
* if the tip moves), with no snapshot cap. Only cards with `minConfirmations` (default 1).
*/
export async function collection(deps: Pick<OwnershipDeps, 'ledger' | 'accounts'>, account: Pick<Account, 'sub'>,
opts: { minConfirmations?: number } = {}): Promise<ChainCard[]> {
return collectionAt(deps, account, opts).cards;
}
/** collection() plus the tip and wallets it was read at. Synchronous. */
export function collectionAt(deps: Pick<OwnershipDeps, 'ledger' | 'accounts'>, account: Pick<Account, 'sub'>,
opts: { minConfirmations?: number } = {}): { tip: string; wallets: string[]; cards: ChainCard[] } {
const minConfirmations = ownershipRules({ minConfirmations: opts.minConfirmations }).minConfirmations;
const wallets = [...new Set(deps.accounts.wallets(account.sub).map(w => w.address))];
for (let attempt = 0; attempt <= MAX_RESTARTS; attempt++) {
const tip = deps.ledger.summary().tip;
const cards = scan(deps.ledger, wallets, tip, minConfirmations);
if (cards) return { tip, wallets, cards };
}
throw new OwnershipUnavailable('The chain is moving too fast to read a consistent collection; try again');
}
/** Returns null if the tip moved during the scan. */
function scan(ledger: OwnershipLedger, wallets: string[], tip: string, minConfirmations: number): ChainCard[] | null {
const cards: ChainCard[] = [];
for (const address of wallets) {
let offset: number | null = 0;
while (offset !== null) {
const page = ledger.deck(address, offset, PAGE);
if (page.tip !== tip) return null;
for (const nft of page.nfts) {
if (nft.confirmations >= minConfirmations) cards.push(cardFromChain(nft, address));
if (cards.length > MAX_COLLECTION) throw new OwnershipUnavailable('Collection too large to list');
}
// Defensive: a page that makes no progress would loop forever.
offset = page.next !== null && page.next > offset ? page.next : null;
}
}
return cards;
}
/** How many of these cards a legal deck could use under the copy limit: Σ min(copies, limit) per pageId. */
export function playableCount(cards: Pick<ChainCard, 'pageId'>[], maxCopiesPerPage: number): number {
const perPage = new Map<number, number>();
for (const c of cards) perPage.set(c.pageId, (perPage.get(c.pageId) ?? 0) + 1);
let n = 0; for (const count of perPage.values()) n += Math.min(count, maxCopiesPerPage);
return n;
}
+27 -6
View File
@@ -40,17 +40,38 @@ export function createGameRouter(host: ModeHost, discovery: ModeDiscovery): expr
return { hosts: rows };
}));
r.get('/modes/:modeId/leaderboard', reads, wrap(req => host.leaderboard(String(req.params.modeId))));
// Same body; entries carry `rating` (Elo, null if unrated) plus W/L.
r.get('/modes/:modeId/ladder', reads, wrap(req => host.leaderboard(String(req.params.modeId))));
r.get('/modes/:modeId/lobbies', reads, wrap(req => ({ lobbies: host.openLobbies(String(req.params.modeId)) })));
r.post('/modes/:modeId/lobbies', writes, wrap((req, res) => {
// Seat bodies: `{name, secret}` for guests (Edit War only), or `{idToken}` for an eom.dev account
// (the Dex ID token travels in the body: Authorization carries seat tokens). Constructed
// modes add `deck: tokenId[]`; `private: true` hides the lobby (join it by invite code).
const seat = (req: Request) => {
const b = body(req);
// Also accept the Dex ID token as `Authorization: Bearer <jwt>` on seat-creating routes: a
// JWT (three dot-separated parts) can never match the seat-token format above.
const m = /^Bearer ([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/.exec(req.get('authorization') ?? '');
return { name: b.name, secret: b.secret, idToken: b.idToken ?? m?.[1], deck: b.deck, private: b.private };
};
r.post('/modes/:modeId/lobbies', writes, wrap(async (req, res) => {
const ticket = await host.createLobby(String(req.params.modeId), seat(req));
res.status(201);
return host.createLobby(String(req.params.modeId), { name: b.name, secret: b.secret });
return ticket;
}));
r.post('/lobbies/:lobbyId/join', writes, wrap(req => {
const b = body(req);
return host.join(String(req.params.lobbyId), { name: b.name, secret: b.secret });
// Quick match: join the oldest open public lobby, else open one (`matched: false`) and poll it.
r.post('/modes/:modeId/quick', writes, wrap(req => host.quickMatch(String(req.params.modeId), seat(req))));
r.post('/lobbies/:lobbyId/join', writes, wrap(req => host.join(String(req.params.lobbyId), seat(req))));
// Invite links (/play/invite/<code> in the SPA) resolve here, then join by lobby id or code.
r.get('/invites/:code', reads, wrap(req => host.invite(String(req.params.code))));
r.post('/invites/:code/join', writes, wrap(req => host.join(host.invite(String(req.params.code)).lobbyId, seat(req))));
// Polling: `?v=<version>` from the last response returns 204 while nothing changed.
r.get('/lobbies/:lobbyId', plays, wrap((req, res) => {
const raw = typeof req.query.v === 'string' ? req.query.v : undefined;
const since = raw !== undefined && /^\d{1,15}$/.test(raw) ? Number(raw) : undefined;
const out = host.view(String(req.params.lobbyId), bearer(req) || undefined, since);
if (out === null) { res.status(204).end(); return; }
return out;
}));
r.get('/lobbies/:lobbyId', plays, wrap(req => host.view(String(req.params.lobbyId), bearer(req) || undefined)));
r.post('/lobbies/:lobbyId/pick', plays, wrap(req => host.pick(String(req.params.lobbyId), bearer(req), body(req).index)));
r.post('/lobbies/:lobbyId/actions', plays, wrap(req => host.act(String(req.params.lobbyId), bearer(req), body(req).action)));
r.post('/lobbies/:lobbyId/resign', writes, wrap(req => host.resign(String(req.params.lobbyId), bearer(req))));
+36 -6
View File
@@ -10,21 +10,42 @@ export const MatchRecordSchema = z.object({
matchId: z.string().regex(/^[a-f0-9]{32}$/),
modeId: z.string().max(40),
modeVersion: z.number().int(),
/** Engine the match ran on (absent in Night 1 records: `editwar`). */
engine: z.enum(['editwar', 'duel']).optional(),
/** Counted for Elo: the mode was rated and both seats were eom.dev accounts. */
rated: z.boolean().optional(),
/** Host-chosen seed. Together with decks and actions it lets anyone replay the match. */
seed: z.string().max(128),
/** The resolved ruleset the match ran under (mode overrides already applied). */
rules: z.unknown(),
players: z.array(z.object({ id: z.string().regex(/^[a-f0-9]{64}$/), name: z.string().max(24) }).strict()).length(2),
players: z.array(z.object({ id: z.string().regex(/^[a-f0-9]{64}$/), name: z.string().max(24),
account: z.boolean().optional() }).strict()).length(2),
winner: z.union([z.literal(0), z.literal(1), z.null()]),
reason: z.string().max(40),
startedAt: z.number().int(),
endedAt: z.number().int(),
decks: z.array(z.array(z.unknown()).max(64)).length(2),
actions: z.array(z.object({ seat: z.union([z.literal(0), z.literal(1)]), action: z.unknown() }).strict()).max(2000),
/** Constructed modes: the NFT token ids each seat played, in deck order (recap references). */
tokens: z.array(z.array(z.string().max(128)).max(64)).length(2).optional(),
}).strict();
export type MatchRecord = z.infer<typeof MatchRecordSchema>;
export type LeaderboardEntry = { playerId: string; name: string; wins: number; losses: number; draws: number; played: number };
export type LeaderboardEntry = { playerId: string; name: string; wins: number; losses: number; draws: number; played: number;
/** Elo (start 1200, K 24) from rated matches; null if the player has none in this mode. */
rating: number | null; ratedPlayed: number };
/** Elo constants (engineer review §3). Ratings are recomputed by replaying records in order. */
export const ELO_START = 1200;
export const ELO_K = 24;
/** New ratings for [seat0, seat1] after one game; winner null is a draw. */
export function eloUpdate(r0: number, r1: number, winner: 0 | 1 | null): [number, number] {
const e0 = 1 / (1 + 10 ** ((r1 - r0) / 400));
const s0 = winner === null ? 0.5 : winner === 0 ? 1 : 0;
const d = ELO_K * (s0 - e0);
return [r0 + d, r1 - d];
}
type ModeAgg = { matches: number; players: Map<string, LeaderboardEntry> };
const KEEP_RECENT = 500;
@@ -63,8 +84,10 @@ export class MatchStore {
leaderboard(modeId: string, limit = 20): LeaderboardEntry[] {
const players = [...(this.modes.get(modeId)?.players.values() ?? [])];
return players.sort((a, b) => b.wins - a.wins || a.losses - b.losses || b.played - a.played ||
a.playerId.localeCompare(b.playerId)).slice(0, limit).map(p => ({ ...p }));
// Rated players first, by Elo; then everyone else by W/L (the cut-order fallback).
return players.sort((a, b) => (b.rating ?? -Infinity) - (a.rating ?? -Infinity) || b.wins - a.wins || a.losses - b.losses ||
b.played - a.played || a.playerId.localeCompare(b.playerId)).slice(0, limit)
.map(p => ({ ...p, rating: p.rating === null ? null : Math.round(p.rating) }));
}
private index(r: MatchRecord): void {
@@ -72,13 +95,20 @@ export class MatchStore {
const agg = this.modes.get(r.modeId) ?? { matches: 0, players: new Map() };
this.modes.set(r.modeId, agg);
agg.matches++;
r.players.forEach((p, seat) => {
const entries = r.players.map((p, seat) => {
this.allPlayers.add(p.id);
const e = agg.players.get(p.id) ?? { playerId: p.id, name: p.name, wins: 0, losses: 0, draws: 0, played: 0 };
const e = agg.players.get(p.id) ?? { playerId: p.id, name: p.name, wins: 0, losses: 0, draws: 0, played: 0, rating: null, ratedPlayed: 0 };
e.name = p.name; e.played++;
if (r.winner === null) e.draws++; else if (r.winner === seat) e.wins++; else e.losses++;
agg.players.set(p.id, e);
return e;
});
// Elo only for rated matches between two account seats that actually played (no aborted 0-action games).
if (r.rated && r.players.every(p => p.account) && r.actions.length > 0 && r.reason !== 'abandoned') {
const [a, b] = entries as [LeaderboardEntry, LeaderboardEntry];
[a.rating, b.rating] = eloUpdate(a.rating ?? ELO_START, b.rating ?? ELO_START, r.winner);
a.ratedPlayed++; b.ratedPlayed++;
}
this.recent.set(r.matchId, r);
if (this.recent.size > KEEP_RECENT) this.recent.delete(this.recent.keys().next().value!);
}
+10 -3
View File
@@ -16,7 +16,10 @@ import { IS_MAINNET, PROFILE } from '../../shared/network.ts';
import { assertLaunchAllowed, launchManifest } from '../launch.ts';
import { resourceConfig, RpcBudget, RpcError } from '../resources.ts';
import { trustedProxies, operationsPort, startOperations } from '../operations.ts';
import { createAccountRouter } from '../account/router.ts';
import { accountVerifier, createAccountRouter } from '../account/router.ts';
import { AccountStore } from '../account/store.ts';
import { DexKeys, oidcConfig } from '../account/oidc.ts';
import { collectionRouter } from '../game/collection.ts';
const root = fileURLToPath(new URL('../../', import.meta.url));
assertLaunchAllowed();
@@ -150,8 +153,12 @@ app.post('/p2p/transaction',workLimit,async(req,res)=>{
const id=await ledger.submitTransaction(transaction);
res.status(202).json({id,status:'pending'});
});
app.use('/api/account',createAccountRouter({dataDir}));
app.use('/api/game',await (await import('../game/index.ts')).gameRouter({dataDir,enrichment:wikipediaEnrichment}));
// One account store and one Dex key cache, shared by the account and game routes (#57).
const oidc=oidcConfig(), dexKeys=new DexKeys(oidc), accounts=new AccountStore(resolve(dataDir,'accounts.sqlite'));
const ownership={ledger,accounts,verifyIdToken:accountVerifier(oidc,dexKeys,accounts)};
app.use('/api/account',createAccountRouter({config:oidc,keys:dexKeys,store:accounts}));
app.use('/api/game/collection',collectionRouter(ownership));
app.use('/api/game',await (await import('../game/index.ts')).gameRouter({dataDir,enrichment:wikipediaEnrichment,ownership}));
app.use(['/api','/p2p'],(_req,res)=>{res.status(404).json({error:'Unknown testnet endpoint'});});
app.use(express.static(resolve(root,'dist')));
app.get('/{*path}',(_req,res)=>res.sendFile(resolve(root,'dist/index.html')));
+183
View File
@@ -0,0 +1,183 @@
/**
* Card type classification (BRIEF "Card types", data review §1, designer review §3.1).
* Pure and deterministic: everything comes from the frozen CardProfile, nothing is fetched here.
* Order: exact Q-id anchors on P31, then P279 anchors, then P31 label regex (rule order is the
* priority), then P279 label regex, then non-stub categories, then the description, then Doctrine.
* Owner: duel-cards.
*/
export type CardType = 'Figure' | 'Location' | 'Event' | 'Institution' | 'Doctrine';
export const CARD_TYPES: readonly CardType[] = ['Figure', 'Location', 'Event', 'Institution', 'Doctrine'];
export interface WikidataClass { id: string; label: string }
/**
* The off-chain card profile, frozen the first time a host sees the card (data §3) and logged
* with the match so replays and recaps stay deterministic. Only what derivation reads.
*/
export interface CardProfile {
wikidataId: string | null;
/** Wikipedia short description. */
description: string | null;
/** Non-hidden category titles without the "Category:" prefix. */
categories: readonly string[];
/** P31 (instance of). */
instanceOf: readonly WikidataClass[];
/** P279 (subclass of) of the item itself, or the P31 classes' superclasses up to 4 hops, nearest first. */
subclassOf?: readonly WikidataClass[];
/** P17 / P27 country Q-ids (or labels when only text is known). */
countries?: readonly string[];
/** Years from P569/P570/P571/P580/P585 (negative = BCE). */
years?: readonly number[];
/** P570 (date of death) present. */
died?: boolean;
/** ns0 outlinks as pageIds (data §4), for the Linked tier of Connected. */
links?: readonly number[];
/** Item Q-ids cited by the frozen claims (P17, P27, P131, P361, P106, …), for the Linked tier. */
cites?: readonly string[];
/** The live revision the profile was fetched from (data §3). */
fetchedRevisionId?: number;
}
export type ClassifySource = 'qid' | 'p279-qid' | 'p31' | 'p279' | 'category' | 'description'
| 'extract' | 'title' | 'chain-category' | 'fallback';
export interface Classification { type: CardType; source: ClassifySource; matched: string }
/** Exact anchors (designer §3.1 step 1, data §1 production table). Checked against P31, then P279. */
export const QID_ANCHORS: Readonly<Record<string, CardType>> = {
Q5: 'Figure', Q95074: 'Figure', Q16521: 'Figure', Q23038290: 'Figure', Q8436: 'Figure', Q178885: 'Figure',
Q486972: 'Location', Q515: 'Location', Q532: 'Location', Q3957: 'Location', Q4022: 'Location', Q23397: 'Location',
Q8502: 'Location', Q23442: 'Location', Q41176: 'Location',
Q1656682: 'Event', Q40231: 'Event', Q178561: 'Event', Q198: 'Event', Q8065: 'Event',
Q43229: 'Institution', Q4830453: 'Institution', Q783794: 'Institution', Q7278: 'Institution', Q215380: 'Institution',
Q17537576: 'Institution', Q11424: 'Institution', Q482994: 'Institution', Q7366: 'Institution', Q571: 'Institution',
Q12136: 'Doctrine', Q151885: 'Doctrine', Q7187: 'Doctrine', Q9143: 'Doctrine', Q315: 'Doctrine',
};
type Rules = readonly (readonly [CardType, RegExp])[];
/** P31/P279 label rules (data §1 types.py, with `^human$` and the governing-body fix). Order is load-bearing. */
export const LABEL_RULES: Rules = [
['Doctrine', /aspect of|aspect in|disease|clinical sign|list article|chemical entity/],
['Event', new RegExp('election|protest|battle|war\\b|storm|nor.easter|cyclone|tornado|earthquake|disaster|event|match|final\\b|'
+ 'season|championship|tournament|\\brace\\b|grand prix|scandal|annexation|treaty|incident|festival|referendum|'
+ 'conference|ceremony|time period|delegation|spaceflight|siege|riot|massacre|flood|pandemic|epidemic|straw poll')],
['Institution', /artificial satellite|space station|space telescope|spacecraft|space probe|diocese|ecclesiastical|council\b|governing body|stele/],
['Location', new RegExp('planet|natural satellite|\\bstar\\b|galaxy|nebula|planetary system|astronomical object|rainforest|reef|'
+ 'civili[sz]ation|empire|historical country|archaeological site|'
+ 'human settlement|settlement|village|town|city|commune|municipal|parish|county|district|region|province|'
+ 'township|hamlet|townland|census area|local government|community of|island|river|lake|mountain|plateau|'
+ 'waterfall|valley|bay|peak|geographical feature|historic district|park|state park|square|road|highway|'
+ 'building|castle|mosque|church|temple|cathedral|house|home|museum|station|bridge|monument|historic site|'
+ 'military base|battery|refinery|shopping|stadium|arch|tower|fort|palace|columbari|freguesia|country\\b|sovereign state')],
['Figure', /^human$|fictional character|stock character|person|deity|orisha|loa\b|taxon|species|genus|breed|^family$|organism/],
['Institution', new RegExp('company|business|organi[sz]ation|association|society|party|agency|studio|band|musical group|team|club|'
+ 'university|college|school|institute|manufacturer|newspaper|magazine|film|album|'
+ 'song|single|musical work|composition|television|series|book|novel|video game|painting|award|position|'
+ 'aircraft|ship|steamship|vehicle|automobile|tram|railway line|route|typeface|software|product|brand|artifact|artefact')],
['Doctrine', new RegExp('concept|theory|theorem|mathematical|programming language|language|gene|protein|chemical|compound|'
+ 'ideology|religion|discipline|field|cuisine|food|dish|drink|aspect|'
+ 'particle|process|genre|form\\b|game\\b|branch of|class of|type of|tabular|structure')],
];
/** Category fallback (stub categories are skipped). */
export const CATEGORY_RULES: Rules = [
['Figure', /\bbirth|\bdeaths\b|living people|people from|\bspecies\b|described in \d|\bgenera\b|deities|characters/],
['Event', /\belections\b|protests|\bbattles\b|disasters|\braces\b|\bseasons\b|\bevents\b|scandals|annexations|competitions/],
['Location', new RegExp('villages|communes|parishes|local government|populated places|geography|rivers|islands|buildings and structures|bridges|'
+ 'stations|parks|districts|townships|cities and towns|historic places|freguesias')],
['Institution', new RegExp('companies|organi[sz]ations|\\bfilms\\b|albums|songs|novels|newspapers|television series|musical groups|'
+ 'aircraft|ships|typefaces|software|awards|teams|clubs|establishments')],
['Doctrine', new RegExp('theory|structures$|algebra|terminology|cuisine|drinks|desserts|ecology|languages|diseases|conditions|'
+ 'concepts|ranks|etymology|maps|atlases')],
];
/** Description fallback (present on ~90% of the sample). */
export const DESCRIPTION_RULES: Rules = [
['Figure', /^(species|genus) of|\b(painter|politician|actor|actress|writer|player|singer|born|species|genus)\b/],
['Event', /\b(race|election|battle|match|protest|storm|war|competition)\b/],
['Location', /^(commune|village|town|municipality|river) in|\b(village|town|city|river|island|building|church|columbarium|station|park)\b/],
['Institution', /\b(company|band|film|album|organi[sz]ation|team|aircraft|ship|newspaper)\b/],
['Doctrine', /\b(concept|theory|structure|dessert|drink|dish|technique|class of)\b/],
];
/**
* On-chain data every block carries (protocol Article), used when the frozen profile is empty or
* missing: the mint-time `category` (server/wiki.ts buckets), the title and the extract.
*/
export interface ChainHints { title: string; extract?: string; category?: string }
/**
* Rules for an extract's definitional phrase ("is a village in …"). Broader than the short-description
* rules because lead sentences use more varied nouns. Order: Doctrine overrides, then as for labels.
*/
export const EXTRACT_RULES: Rules = [
['Doctrine', /\b(gene|protein|enzyme|disease|syndrome|disorder|theorem|conjecture|concept|theory|language|cuisine|dish|algebraic|mathematical|list of)\b/],
['Event', /\b(election|referendum|battle|war|siege|protest|riot|massacre|annexation|storm|hurricane|cyclone|tornado|tornadoes|earthquake|flood|season|tournament|championship|race|grand prix|match|festival|ceremony)\b/],
['Figure', /\b(actor|actress|politician|writer|author|poet|painter|artist|singer|musician|composer|director|producer|player|footballer|cricketer|athlete|boxer|scientist|engineer|bishop|priest|monarch|king|queen|sultan|businessman|businesswoman|family|dynasty|species|genus|breed|character|deity|god|goddess)\b/],
['Institution', /\b(company|corporation|business|manufacturer|organi[sz]ation|association|society|party|coalition|band|team|club|university|college|school|studio|newspaper|magazine|film|album|song|single|novel|book|series|video game|aircraft|airliner|ship|automobile|car|locomotive|tramway|railway line|bus route|typeface|software|position|office|award|diocese|council)\b/],
['Location', /\b(village|town|city|municipality|commune|parish|county|district|region|province|state|locality|hamlet|suburb|neighbourhood|neighborhood|settlement|community|census area|river|lake|island|mountain|plateau|valley|bay|peak|building|house|church|cathedral|mosque|temple|castle|ch[aâ]teau|palace|museum|pavilion|stadium|bridge|station|park|mall|shopping (centre|center)|road|street|square|monument)\b/],
];
/** Title patterns (checked after the extract's definitional phrase). */
export const TITLE_RULES: Rules = [
['Event', /\b(election|elections|referendum|straw poll|battle of|siege of|war|protests?|riots?|massacre|earthquake|hurricane|cyclone|typhoon|nor'easter|storm|flood|season|championship|tournament|grand prix|olympics|world cup|final)\b/i],
['Institution', /\((film|album|song|single|novel|book|band|tv series|television series|video game|magazine|newspaper|company|ship|aircraft|typeface|software)\)|\b(f\.?c\.?|company|corporation|university|college|school|party|club|association|society|records|airlines?)\b/i],
['Doctrine', /\((programming language|mathematics|disease|gene|chemistry|philosophy|religion)\)|\b(disease|syndrome|theorem|conjecture|cuisine)\b/i],
['Figure', /\((actor|actress|politician|footballer|cricketer|singer|musician|writer|author|painter|artist|boxer|wrestler|bishop|priest|judge|businessman|athlete|rugby union|rugby league|baseball|basketball)\)|\((plant|animal|bird|fish|moth|beetle|spider|fungus|genus)\)/i],
['Location', /\b(river|lake|mount|mountain|island|islands|county|village|township|parish|district|province|church|cathedral|chapel|castle|mosque|temple|abbey|bridge|station|house|park|street|road|square|tower|palace|fort|airport|dam|valley|bay)\b/i],
];
/** Mint-time category buckets that carry a type signal (History and Culture don't). */
export const CHAIN_CATEGORY_TYPE: Readonly<Record<string, CardType>> = {
People: 'Figure', Nature: 'Figure', Space: 'Location', Science: 'Doctrine',
};
/**
* The definitional phrase of an extract's first sentence: what follows "is a / was an / are the …",
* up to the next clause break. "Tom Ewell (1909–1994) was an American actor." → "american actor".
*/
export function definitionOf(extract: string | undefined): string {
const text = (extract ?? '').replace(/\s+/g, ' ').trim();
const m = /\b(?:is|was|are|were)\s+(?:an?|the|one of the)\s+([^.;:]{1,120})/i.exec(text);
return m ? m[1].toLowerCase() : '';
}
/** Lead-sentence life dates: "Name (born 1971)", "Name (1909–1994)", "Name (c. 1530 – 1548)". */
const LIFE_DATES = /^[^.(]{1,80}\((?:[^)]*;\s*)?(?:born\s+(?:[A-Z][a-z]+\s+)?(?:\d{1,2}\s+)?(?:[A-Z][a-z]+\s+)?\d{3,4}|(?:c\.\s*)?\d{3,4}\s*[–-]\s*(?:c\.\s*)?\d{3,4})/;
function firstRule(rules: Rules, texts: readonly string[]): [CardType, string] | null {
for (const [type, rx] of rules) for (const text of texts) if (rx.test(text)) return [type, text];
return null;
}
export function classify(profile: Pick<CardProfile, 'instanceOf' | 'subclassOf' | 'categories' | 'description'>,
chain?: ChainHints): Classification {
const p31 = profile.instanceOf ?? [];
const p279 = profile.subclassOf ?? [];
for (const c of p31) { const t = QID_ANCHORS[c.id]; if (t) return { type: t, source: 'qid', matched: c.id }; }
const p31Labels = p31.map(c => c.label.toLowerCase());
let hit = firstRule(LABEL_RULES, p31Labels);
if (hit) return { type: hit[0], source: 'p31', matched: hit[1] };
for (const c of p279) { const t = QID_ANCHORS[c.id]; if (t) return { type: t, source: 'p279-qid', matched: c.id }; }
hit = firstRule(LABEL_RULES, p279.map(c => c.label.toLowerCase()));
if (hit) return { type: hit[0], source: 'p279', matched: hit[1] };
const cats = (profile.categories ?? []).map(c => c.toLowerCase()).filter(c => !c.includes('stubs'));
hit = firstRule(CATEGORY_RULES, cats);
if (hit) return { type: hit[0], source: 'category', matched: hit[1] };
const desc = (profile.description ?? '').toLowerCase();
hit = firstRule(DESCRIPTION_RULES, desc ? [desc] : []);
if (hit) return { type: hit[0], source: 'description', matched: hit[1] };
if (chain) {
const extract = (chain.extract ?? '').replace(/\s+/g, ' ').trim();
const definition = definitionOf(extract);
hit = firstRule(EXTRACT_RULES, definition ? [definition] : []);
if (hit) return { type: hit[0], source: 'extract', matched: hit[1] };
if (LIFE_DATES.test(extract)) return { type: 'Figure', source: 'extract', matched: 'life dates' };
hit = firstRule(TITLE_RULES, chain.title ? [chain.title] : []);
if (hit) return { type: hit[0], source: 'title', matched: chain.title };
const t = chain.category ? CHAIN_CATEGORY_TYPE[chain.category] : undefined;
if (t) return { type: t, source: 'chain-category', matched: chain.category! };
}
return { type: 'Doctrine', source: 'fallback', matched: '' };
}
+321
View File
@@ -0,0 +1,321 @@
/**
* Duel card derivation: an on-chain card plus its frozen off-chain profile becomes a DuelCard
* (BRIEF "Stats", "Keywords", "Factions", "Connected"; data review §2 and §4; designer review §3).
* Pure and deterministic: no fetches, no clocks, no randomness. Every number is data in DERIVE_RULES.
* Owner: duel-cards.
*/
import type { Article } from '../protocol.ts';
import type { MintStatsSnapshot } from '../enrichment.ts';
import { rarity as rarityOf } from '../protocol.ts';
import { CARD_SAMPLE_PERCENTILES } from '../game/card-data.ts';
import { percentile } from '../game/derive.ts';
import { classify, type CardProfile, type CardType, type ClassifySource } from './classify.ts';
import { effectsFor, subtypeFor, type EffectSpec } from './effects.ts';
import { rulesTextFor } from './text.ts';
export type { CardProfile, CardType } from './classify.ts';
export type { EffectSpec } from './effects.ts';
export const DERIVE_VERSION = 'duel-derive-1';
export type Portal = 'Arts' | 'Earth' | 'History' | 'Science' | 'Society' | 'Neutral';
export const PORTALS: readonly Portal[] = ['Arts', 'Earth', 'History', 'Science', 'Society', 'Neutral'];
export type Keyword = 'Protected' | 'Featured' | 'Translated' | 'Legacy' | 'Stub' | 'Well-sourced' | 'Multilingual' | 'Local';
export type Rarity = 'Common' | 'Rare' | 'Epic' | 'Legendary';
/** What derive() reads from the chain: a minted block's article and stats snapshot. */
export interface CardOnChain {
tokenId: string;
/** `category` is the mint-time bucket (server/wiki.ts); only used when the profile is empty. */
article: Pick<Article, 'pageId' | 'title' | 'extract' | 'revisionId'> & { category?: string };
statsSnapshot: Pick<MintStatsSnapshot, 'pageBytes' | 'languageCount' | 'stats'>;
}
export interface ConnectKeys {
/** P17/P27 values, or normalised country names from text when Wikidata has none. */
countries: string[];
centuries: number[];
/** Outlink pageIds. */
links: number[];
/** P31 Q-ids, excluding human and taxon (the Kin tier). */
p31: string[];
/** This card's Wikidata item (omitted when it has none), and the item Q-ids its claims cite (Linked tier). */
qid?: string;
cites: string[];
}
export interface DuelCard {
cardId: string;
pageId: number;
revisionId: number;
title: string;
/** Wikidata short description, for log first mentions (omitted when absent). */
description?: string;
type: CardType;
/** Template family within the type, e.g. 'conflict', 'election', 'organisation', 'pathology'. */
subtype: string | null;
portal: Portal;
cost: number;
/** Figures: power/toughness. Locations: 0 / Garrison. Others: null. */
power: number | null;
toughness: number | null;
/** Locations: Citations income ramp (the engine caps the total). */
territory: number;
keywords: Keyword[];
effects: EffectSpec[];
rulesText: string;
flavor: string;
connect: ConnectKeys;
rarity: Rarity;
deriveVersion: string;
/** Why the card got its type (for audit and the card's info panel). */
typedBy: ClassifySource;
/** The numbers behind cost and body, for the info panel and the simulator. */
basis: { pctAttention: number | null; pctDepth: number; pctReach: number; fame: number; magnitude: number };
}
export interface DeriveRules {
percentiles: Record<'attention' | 'depth' | 'reach', readonly number[]>;
/** fame → cost 1..6: 1 + number of thresholds ≤ fame. */
costThresholds: readonly number[];
/** P+T budget by cost (index = cost). MTG vanilla curve. */
bodyBudget: readonly number[];
maxKeywords: number;
/** Keywords that cost 1 point of body (from the larger stat, min 1 each). */
taxedKeywords: readonly Keyword[];
keywordOrder: readonly Keyword[];
featuredPct: number;
wellSourcedPct: number;
/** Translated: translatedPct ≤ pct_reach < multilingualPct. Multilingual: pct_reach ≥ multilingualPct. */
translatedPct: number;
multilingualPct: number;
stubBytes: number;
/** Garrison toughness = 1 + floor(pct_depth / garrisonStep). */
garrisonStep: number;
}
export const DERIVE_RULES: DeriveRules = {
percentiles: CARD_SAMPLE_PERCENTILES,
costThresholds: [26, 39, 51, 63, 78],
bodyBudget: [0, 3, 4, 6, 8, 10, 12],
maxKeywords: 2,
taxedKeywords: ['Protected', 'Featured', 'Legacy', 'Multilingual', 'Well-sourced'],
keywordOrder: ['Protected', 'Featured', 'Legacy', 'Multilingual', 'Translated', 'Well-sourced', 'Stub', 'Local'],
featuredPct: 85,
wellSourcedPct: 85,
translatedPct: 75,
multilingualPct: 90,
stubBytes: 3000,
garrisonStep: 25,
};
// ---------------------------------------------------------------- Portals (designer §3.2)
export const PORTAL_RULES: Readonly<Record<Exclude<Portal, 'Neutral'>, RegExp>> = {
Arts: /\b(actor|actress|singer|musician|rapper|band|album|song|single|film|novel|novelist|writer|poet|painter|artist|composer|television|tv series|music|theatre|theater|dance|dancer|video game|studio|animation|anime|fiction|character|literature|book|magazine|typeface|sculpt\w*|architect\w*|comedian|opera|orchestra)\b/g,
Earth: /\b(species|genus|genera|taxon|plant|plants|animal|bird|birds|fish|insect|moth|beetle|grasshopper|orchid|river|rivers|lake|mountain|island|islands|village|villages|commune|communes|geography|forest|park|ecology|breed|weather|storm|nor.easter|cyclone|earthquake|climate|flora|fauna|populated places|municipality|municipalities|county|township|parish|reef|valley|locality|oblast|freguesia|hamlet)\b/g,
History: /(\b\d+(st|nd|rd|th)-century\b|\b\d+ deaths\b|\b(sultan\w*|empire|castle|castles|medieval|ancient|dynasty|war|battle|battles|monarch|monarchs|king|queen|historic|archaeolog\w*|former|disestablish\w*|colonial|kingdom|museum|nobility|pharaoh)\b)/g,
Science: /\b(mathemat\w*|algebra\w*|programming|software|gene|genes|protein|chemi\w*|disease|diseases|scientist|physic\w*|astronom\w*|biolog\w*|medic\w*|engineer\w*|computer|computing|theorem|planet|galaxy|spacecraft|satellite|aircraft|technology|clinical|structure|structures|category theory|syndrome|virus|bacteri\w*)\b/g,
Society: /\b(politic\w*|politician|election|elections|party|government|law|court|sport|sports|football|cricket|basketball|baseball|olympic\w*|team|club|league|church|religio\w*|diocese|mosque|temple|school|university|company|companies|business|corporation|protest|protests|scandal|corruption|people from|living people|police|crime|cuisine|association|council)\b/g,
};
const PORTAL_TIE_ORDER: readonly Exclude<Portal, 'Neutral'>[] = ['History', 'Science', 'Arts', 'Society', 'Earth'];
export const TYPE_DEFAULT_PORTAL: Readonly<Record<CardType, Exclude<Portal, 'Neutral'>>> = {
Figure: 'Society', Location: 'Earth', Event: 'History', Institution: 'Arts', Doctrine: 'Science',
};
/** Count keyword hits over description + categories + P31 labels; ties go to the type default; no hits → Neutral. */
export function portalFor(profile: CardProfile, type: CardType): Portal {
const text = [profile.description ?? '', ...profile.categories, ...profile.instanceOf.map(c => c.label)]
.join(' | ').toLowerCase();
let best = 0; let tied: Exclude<Portal, 'Neutral'>[] = [];
for (const portal of PORTAL_TIE_ORDER) {
const hits = text.match(PORTAL_RULES[portal])?.length ?? 0;
if (hits > best) { best = hits; tied = [portal]; } else if (hits === best && hits > 0) tied.push(portal);
}
if (best === 0) return 'Neutral';
const fallback = TYPE_DEFAULT_PORTAL[type];
return tied.includes(fallback) ? fallback : tied[0];
}
// ---------------------------------------------------------------- Connected keys (data §4)
const COUNTRY_WORDS: readonly (readonly [RegExp, string])[] = ([
['United States|American', 'United States'], ['United Kingdom|British|England|English|Scotland|Scottish|Wales|Welsh', 'United Kingdom'],
['France|French', 'France'], ['Germany|German', 'Germany'], ['Japan|Japanese', 'Japan'], ['China|Chinese', 'China'],
['India|Indian', 'India'], ['Brazil|Brazilian', 'Brazil'], ['Poland|Polish', 'Poland'], ['Italy|Italian', 'Italy'],
['Spain|Spanish', 'Spain'], ['Austria|Austrian', 'Austria'], ['Canada|Canadian', 'Canada'], ['Australia|Australian', 'Australia'],
['Russia|Russian', 'Russia'], ['Mexico|Mexican', 'Mexico'], ['Iran|Iranian', 'Iran'], ['Pakistan|Pakistani', 'Pakistan'],
['Bangladesh|Bangladeshi', 'Bangladesh'], ['Sweden|Swedish', 'Sweden'], ['Norway|Norwegian', 'Norway'], ['Estonia|Estonian', 'Estonia'],
['Ukraine|Ukrainian', 'Ukraine'], ['Croatia|Croatian', 'Croatia'], ['Philippines|Filipino', 'Philippines'], ['Cuba|Cuban', 'Cuba'],
['Israel|Israeli', 'Israel'], ['Portugal|Portuguese', 'Portugal'], ['Ireland|Irish', 'Ireland'], ['Kazakhstan|Kazakh', 'Kazakhstan'],
['Malaysia|Malaysian', 'Malaysia'], ['Argentina|Argentine', 'Argentina'], ['Belgium|Belgian', 'Belgium'], ['Iceland|Icelandic', 'Iceland'],
['Thailand|Thai', 'Thailand'], ['Singapore', 'Singapore'], ['Sri Lanka|Sri Lankan', 'Sri Lanka'], ['Slovenia|Slovene|Slovenian', 'Slovenia'],
['Moldova', 'Moldova'], ['Cyprus|Cypriot', 'Cyprus'], ['North Macedonia|Macedonian', 'North Macedonia'], ['Mauritania', 'Mauritania'],
['Congo', 'Congo'], ['New Zealand', 'New Zealand'], ['Korea|Korean', 'Korea'], ['Indonesia|Indonesian|Aceh', 'Indonesia'],
['Czech', 'Czechia'], ['Netherlands|Dutch', 'Netherlands'], ['Greece|Greek', 'Greece'], ['Turkey|Turkish', 'Turkey'],
['Egypt|Egyptian', 'Egypt'], ['Nigeria|Nigerian', 'Nigeria'], ['Kenya|Kenyan', 'Kenya'], ['Ghana|Gold Coast', 'Ghana'],
['Finland|Finnish', 'Finland'], ['Denmark|Danish', 'Denmark'], ['Switzerland|Swiss', 'Switzerland'], ['Hungary|Hungarian', 'Hungary'],
['Romania|Romanian', 'Romania'], ['Serbia|Serbian', 'Serbia'], ['Bulgaria|Bulgarian', 'Bulgaria'], ['Vietnam|Vietnamese', 'Vietnam'],
['Sri Lanka', 'Sri Lanka'], ['Chile|Chilean', 'Chile'], ['Colombia|Colombian', 'Colombia'], ['Peru|Peruvian', 'Peru'],
] as const).map(([rx, name]) => [new RegExp(`\\b(${rx})\\b`), name] as const);
const YEAR = /\b(1[0-9]{3}|20[0-2][0-9])\b/g;
const CENTURY = /\b(\d{1,2})(st|nd|rd|th)[- ]century\b/gi;
export function connectKeysFor(title: string, profile: CardProfile): ConnectKeys {
const text = [profile.description ?? '', ...profile.categories].join(' | ');
const countries = profile.countries?.length
? [...new Set(profile.countries)]
: [...new Set(COUNTRY_WORDS.filter(([rx]) => rx.test(text)).map(([, name]) => name))];
const centuries = new Set<number>();
if (profile.years?.length) for (const y of profile.years) centuries.add(y > 0 ? Math.floor((y - 1) / 100) + 1 : -(Math.floor(-y / 100) + 1));
else {
for (const m of `${title} | ${text}`.matchAll(YEAR)) centuries.add(Math.floor((Number(m[1]) - 1) / 100) + 1);
for (const m of text.matchAll(CENTURY)) centuries.add(Number(m[1]));
}
return {
countries: countries.sort(),
centuries: [...centuries].sort((a, b) => a - b),
links: [...new Set(profile.links ?? [])].sort((a, b) => a - b),
p31: [...new Set(profile.instanceOf.map(c => c.id).filter(id => id !== 'Q5' && id !== 'Q16521'))].sort(),
...(profile.wikidataId ? { qid: profile.wikidataId } : {}),
cites: [...new Set(profile.cites ?? [])].sort(),
};
}
// ---------------------------------------------------------------- Flavour
/** First sentence of the on-chain extract (BRIEF "Flavour text"); the description if there is no extract. */
export function flavorFor(extract: string, description: string | null): string {
const text = extract.replace(/\s+/g, ' ').trim();
if (!text) return (description ?? '').trim();
// A sentence ends at . ! ? followed by a space and an uppercase letter or a quote, skipping
// common abbreviations and initials ("U.S.", "St.", "J. R. R.") so names are not cut.
const re = /[.!?](?=\s+["'“(\[]?[A-Z0-9])/g;
let m: RegExpExecArray | null;
while ((m = re.exec(text))) {
const before = text.slice(0, m.index);
const word = before.split(/\s/).pop() ?? '';
if (/^([A-Z]|[A-Z][a-z]{0,2}|[A-Z]\.[A-Z]|U\.S|U\.K|c|ca|St|Dr|Mr|Mrs|Ms|Jr|Sr|No|vs|etc|Inc|Ltd|Co|Mt|Ft|Gen|Col|Lt|Sgt|Rev|Prof)$/.test(word.replace(/\.$/, ''))) continue;
return text.slice(0, m.index + 1);
}
return text;
}
// ---------------------------------------------------------------- Stats and keywords (data §2, designer §3.3–3.4)
export interface Percentiles { attention: number | null; depth: number; reach: number }
export function percentilesFor(stats: MintStatsSnapshot['stats'], rules: DeriveRules = DERIVE_RULES): Percentiles {
return {
attention: stats.attention === null ? null : percentile(stats.attention, rules.percentiles.attention),
depth: percentile(stats.depth, rules.percentiles.depth),
reach: percentile(stats.reach, rules.percentiles.reach),
};
}
export function fameOf(p: Percentiles): number {
const values = [p.attention, p.depth, p.reach].filter((v): v is number => v !== null);
return Math.floor(values.reduce((a, b) => a + b, 0) / values.length + 0.5);
}
export function costForFame(fame: number, rules: DeriveRules = DERIVE_RULES): number {
return 1 + rules.costThresholds.filter(t => t <= fame).length;
}
/** Every keyword the data triggers, in priority order (before the cap). */
export function triggeredKeywords(chain: CardOnChain, profile: CardProfile, p: Percentiles, rules: DeriveRules = DERIVE_RULES): Keyword[] {
const cats = profile.categories;
const on: Record<Keyword, boolean> = {
Protected: cats.includes('Living people'),
Featured: p.attention !== null && p.attention >= rules.featuredPct,
Legacy: profile.died === true || cats.some(c => /^\d+s? (BC )?deaths$/.test(c)),
'Well-sourced': p.depth >= rules.wellSourcedPct,
// Two bands of the same reach axis: a card never has both (DUEL_DESIGN §4).
Multilingual: p.reach >= rules.multilingualPct,
Translated: p.reach >= rules.translatedPct && p.reach < rules.multilingualPct,
Stub: cats.some(c => c.toLowerCase().includes('stubs')) || chain.statsSnapshot.pageBytes < rules.stubBytes,
Local: chain.statsSnapshot.stats.reach === 0,
};
return rules.keywordOrder.filter(k => on[k]);
}
export interface Body { power: number; toughness: number; keywords: Keyword[] }
/**
* Figure body (DUEL_DESIGN §3): take the first ≤2 triggered keywords in priority order, subtract 1
* from the cost's P+T budget per taxed keyword, then split by attention vs depth, each stat ≥ 1.
* A taxed keyword that would leave less than 2 points is skipped for the next one.
*/
export function figureBody(cost: number, p: Percentiles, keywords: readonly Keyword[], rules: DeriveRules = DERIVE_RULES): Body {
let budget = rules.bodyBudget[cost];
if (budget === undefined) throw new RangeError(`bodyBudget has no entry for cost ${cost}`);
const kept: Keyword[] = [];
for (const k of keywords) {
if (kept.length >= rules.maxKeywords) break;
if (rules.taxedKeywords.includes(k)) {
if (budget <= 2) continue;
budget--;
}
kept.push(k);
}
const a = p.attention ?? 50;
const power = Math.min(budget - 1, Math.max(1, Math.round(budget * a / Math.max(1, a + p.depth))));
return { power, toughness: budget - power, keywords: kept };
}
// ---------------------------------------------------------------- derive
export function derive(chain: CardOnChain, profile: CardProfile, rules: DeriveRules = DERIVE_RULES): DuelCard {
const { type, source } = classify(profile, chain.article);
const p = percentilesFor(chain.statsSnapshot.stats, rules);
const fame = fameOf(p);
const baseCost = costForFame(fame, rules);
const magnitude = Math.ceil(baseCost / 2);
const portal = portalFor(profile, type);
const subtype = subtypeFor(type, profile, chain.article);
let cost = baseCost, power: number | null = null, toughness: number | null = null, territory = 0;
let keywords: Keyword[] = [];
if (type === 'Figure') {
const body = figureBody(baseCost, p, triggeredKeywords(chain, profile, p, rules), rules);
({ power, toughness, keywords } = body);
} else if (type === 'Location') {
cost = magnitude;
power = 0;
toughness = 1 + Math.floor(p.depth / rules.garrisonStep);
territory = 1;
}
const effects = effectsFor(type, subtype, baseCost);
const card: DuelCard = {
cardId: chain.tokenId, pageId: chain.article.pageId, revisionId: chain.article.revisionId, title: chain.article.title,
type, subtype, portal, cost, power, toughness, territory, keywords, effects, rulesText: '',
flavor: flavorFor(chain.article.extract, profile.description),
connect: connectKeysFor(chain.article.title, profile),
rarity: rarityOf(chain.tokenId), deriveVersion: DERIVE_VERSION, typedBy: source,
basis: { pctAttention: p.attention, pctDepth: p.depth, pctReach: p.reach, fame, magnitude },
};
if (profile.description) card.description = profile.description;
card.rulesText = rulesTextFor(card);
return card;
}
// ---------------------------------------------------------------- Connected (data §4)
/** DUEL_DESIGN §6: Contemporary counts only between different types. */
export type ConnectedTier = 'Linked' | 'Compatriot' | 'Contemporary' | 'Kin';
/** The strongest Connected tier between two cards, or null. Linked gives +2/+2, the others +1/+1 (BRIEF). */
export function connectedTier(a: DuelCard, b: DuelCard,
tiers: readonly ConnectedTier[] = ['Linked', 'Compatriot', 'Contemporary', 'Kin']): ConnectedTier | null {
if (a.cardId === b.cardId) return null;
const meets = (x: readonly (string | number)[], y: readonly (string | number)[]) => x.some(v => y.includes(v));
for (const tier of tiers) {
if (tier === 'Linked' && (a.connect.links.includes(b.pageId) || b.connect.links.includes(a.pageId)
|| (b.connect.qid !== undefined && a.connect.cites.includes(b.connect.qid))
|| (a.connect.qid !== undefined && b.connect.cites.includes(a.connect.qid)))) return tier;
if (tier === 'Compatriot' && meets(a.connect.countries, b.connect.countries)) return tier;
if (tier === 'Contemporary' && a.type !== b.type && meets(a.connect.centuries, b.connect.centuries)) return tier;
if (tier === 'Kin' && meets(a.connect.p31, b.connect.p31)) return tier;
}
return null;
}
+134
View File
@@ -0,0 +1,134 @@
/**
* Effect templates by type and subtype (designer review §3.5; DUEL_DESIGN.md wins where they differ).
* Effects are plain data for duel-core's interpreter. k = ceil(cost / 2), 1–3, from the derived (fame) cost.
* Owner: duel-cards.
*/
import { definitionOf, type CardProfile, type CardType, type ChainHints } from './classify.ts';
import type { Keyword, Portal } from './derive.ts';
export type EffectTrigger = 'onPlay' | 'onEnter' | 'startOfTurn' | 'onDestroyed' | 'static' | 'onCombatDamageToPlayer';
export type EffectOp = 'damage' | 'damageEach' | 'createToken' | 'pump' | 'fight' | 'draw' | 'attach' | 'gainLife';
export type EffectTarget = 'figure' | 'figureOrLocation' | 'ownFigure' | 'opponentFigure' | 'each' | 'self' | 'attached' | 'ownFigures';
export interface EffectSpec {
trigger: EffectTrigger;
op: EffectOp;
target?: EffectTarget;
amount?: number;
power?: number;
toughness?: number;
duration?: 'turn' | 'permanent';
token?: { name: string; power: number; toughness: number; portal: Portal };
/** maxTokens: createToken only if the controller controls fewer than this many tokens (duel-core types.ts). */
condition?: { maxPower?: number; samePortal?: boolean; connected?: boolean; maxTokens?: number };
grant?: Keyword[];
/** Template id (DUEL_DESIGN §5, T3–T12) for rules text and log wording. */
template?: string;
}
type Subtypes = readonly (readonly [string, RegExp])[];
/**
* Subtype rules per type (DUEL_DESIGN §5), run over P31 labels, P279 labels, the description, then
* categories. First match in list order wins; no match is the type's default template.
* Additions beyond §5 (marked +): bands/associations count as organisations; 'flood' etc. as listed.
*/
export const SUBTYPE_RULES: Readonly<Record<CardType, Subtypes>> = {
Event: [
['conflict', /battle|war\b|siege|annexation|protest|riot|uprising|massacre|coup/],
['disaster', /storm|nor.easter|cyclone|hurricane|earthquake|flood|tornado|wildfire|eruption|famine|epidemic/],
['election', /election|referendum|straw poll/],
['sport', /match|final\b|season|tournament|championship|grand prix|\brace\b/],
],
Institution: [
['organisation', /company|organi[sz]ation|party|agency|studio|military|university|diocese|council|band\b|musical group|association|business|school|college|institute|manufacturer/],
['work', /film|album|song|\bbook|novel|series|video game|painting|software|typeface|newspaper|magazine/],
],
Doctrine: [
['pathology', /disease|clinical sign|pathogen|syndrome|disorder|toxin|poison/],
['language', /language|software|programming/],
['mathematics', /mathemat|theorem|algebra|geometr|polytope|polyhedron|equation|number theory|structure/],
['ideology', /ideology|religion|belief|doctrine|philosophy|theology/],
],
Figure: [],
Location: [],
};
/** Default template names, for the info panel (null subtype). */
export const DEFAULT_SUBTYPE: Readonly<Record<CardType, string | null>> = {
Figure: null, Location: null, Event: 'other', Institution: 'other', Doctrine: 'adopt',
};
export function subtypeFor(type: CardType, profile: Pick<CardProfile, 'instanceOf' | 'subclassOf' | 'description' | 'categories'>,
chain?: ChainHints): string | null {
const groups = [
[...profile.instanceOf.map(c => c.label), ...(profile.subclassOf ?? []).map(c => c.label)],
[profile.description ?? ''],
[...(profile.categories ?? []).filter(c => !/stubs$/i.test(c))],
// On-chain fallbacks, last: the extract's definitional phrase, then the title.
[definitionOf(chain?.extract), chain?.title ?? ''],
].map(g => g.map(t => t.toLowerCase()).filter(Boolean));
for (const texts of groups) for (const [name, rx] of SUBTYPE_RULES[type]) if (texts.some(t => rx.test(t))) return name;
return DEFAULT_SUBTYPE[type];
}
/** The effect list for a card (T1–T12). Figures and Locations have none beyond keywords and stats. */
/** DUEL_DESIGN §5 template id by type and subtype. */
export function templateFor(type: CardType, subtype: string | null): string | null {
switch (type) {
case 'Figure': return 'T1';
case 'Location': return 'T2';
case 'Event': return ({ conflict: 'T3', disaster: 'T4', election: 'T5', sport: 'T6' } as Record<string, string>)[subtype ?? ''] ?? 'T7';
case 'Institution': return subtype === 'organisation' ? 'T8' : subtype === 'work' ? 'T9' : 'T10';
case 'Doctrine': return subtype === 'pathology' ? 'T12' : 'T11';
}
}
export function effectsFor(type: CardType, subtype: string | null, cost: number): EffectSpec[] {
const template = templateFor(type, subtype);
return baseEffects(type, subtype, cost).map(e => (template ? { ...e, template } : e));
}
function baseEffects(type: CardType, subtype: string | null, cost: number): EffectSpec[] {
const k = Math.ceil(cost / 2);
switch (type) {
case 'Event':
switch (subtype) {
case 'conflict': return [{ trigger: 'onPlay', op: 'damage', target: 'figureOrLocation', amount: k + 1 }];
case 'disaster': return [{ trigger: 'onPlay', op: 'damageEach', target: 'each', amount: Math.max(1, k - 1) }];
case 'election': return [{ trigger: 'onPlay', op: 'createToken', amount: k,
token: { name: 'Elected Member', power: 1, toughness: 1, portal: 'Society' } }];
case 'sport': return [
{ trigger: 'onPlay', op: 'pump', target: 'ownFigure', power: k, toughness: 0, duration: 'turn' },
{ trigger: 'onPlay', op: 'fight', target: 'opponentFigure' },
];
default: return [{ trigger: 'onPlay', op: 'draw', amount: k }];
}
case 'Institution':
switch (subtype) {
case 'organisation': {
const token = { name: 'Staff Member', power: 1, toughness: 1, portal: 'Neutral' as const };
return cost >= 4
? [{ trigger: 'startOfTurn', op: 'createToken', amount: 1, token, condition: { maxTokens: 3 } }]
: [{ trigger: 'onEnter', op: 'createToken', amount: 1, token }];
}
case 'work': return [
{ trigger: 'onEnter', op: 'draw', amount: 1 },
{ trigger: 'static', op: 'pump', target: 'ownFigures', power: 1, toughness: 1, condition: { connected: true } },
];
default: return [{ trigger: 'static', op: 'pump', target: 'ownFigures', power: 1, toughness: 0, condition: { maxPower: 2 } }];
}
case 'Doctrine': {
// DUEL_API "Doctrine": `attach` picks the Figure; the buff is a static pump on `attached`.
const pathology = subtype === 'pathology';
const attach: EffectSpec = { trigger: 'onPlay', op: 'attach', target: pathology ? 'figure' : 'ownFigure' };
const buff: EffectSpec = { trigger: 'static', op: 'pump', target: 'attached', power: pathology ? -k : k, toughness: pathology ? -k : k };
if (pathology) return [attach, buff];
if (subtype === 'mathematics') return [attach, { ...buff, grant: ['Well-sourced'] }];
if (subtype === 'language') return [attach, buff, { trigger: 'onCombatDamageToPlayer', op: 'draw', amount: 1 }];
if (subtype === 'ideology') return [attach, buff, { trigger: 'static', op: 'pump', target: 'ownFigures', power: 1, toughness: 0, condition: { samePortal: true } }];
return [attach, buff];
}
default: return [];
}
}
+35
View File
@@ -0,0 +1,35 @@
/**
* WikiDeck Duel public API. Spec: docs/game/DUEL_API.md.
* Contracts PR: types and ruleset only. engine.ts (createDuel, legalActions,
* applyAction, viewFor, logFor, replay, ...) lands in the engine alpha PR and
* implements DuelEngineApi below; build against that interface until then.
*/
export * from './types.ts';
export * from './ruleset.ts';
import type { DuelAction, DuelCard, DuelResult, DuelRuleset, DuelState, LogEvent, PlayerView, Seat } from './types.ts';
/** The engine's function surface (implemented by shared/duel/engine.ts). All pure; inputs are never mutated. */
export interface DuelEngineApi {
/** Throws if the deck is illegal: size ≠ deckSize, duplicate cardId, > maxCopiesPerPage of one pageId, bad stats, > maxKeywords. */
validateDeck(rules: DuelRuleset, cards: DuelCard[]): void;
/** Shuffle both decks from `seed`, deal opening hands, phase 'mulligan'. */
createDuel(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string): DuelState;
/** Atomic legal actions for `seat`; [] if `seat` is not the one to act (concede is always accepted by applyAction but not listed). */
legalActions(state: DuelState, seat: Seat): DuelAction[];
/** Returns a new state. Throws on an illegal action. */
applyAction(state: DuelState, seat: Seat, action: DuelAction): DuelState;
/** Seat that must act now, or null when over. Mulligan: the lowest seat not yet ready. */
toAct(state: DuelState): Seat | null;
isOver(state: DuelState): boolean;
result(state: DuelState): DuelResult | null;
viewFor(state: DuelState, seat: Seat): PlayerView;
/** Per-seat log: the opponent's draws (and other hidden-zone cards) are masked. */
logFor(state: DuelState, seat: Seat): LogEvent[];
/** Deterministic: same inputs → identical state (and log). */
replay(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string, actions: { seat: Seat; action: DuelAction }[]): DuelState;
serialize(state: DuelState): string;
deserialize(text: string): DuelState;
/** Current power/toughness of a permanent after counters, buffs, statics and Connected. */
statsOf(state: DuelState, uid: string): { power: number; toughness: number };
}
+114
View File
@@ -0,0 +1,114 @@
/**
* Building the frozen CardProfile (data review §3) from data the host already has or fetches once
* through the polite Wikimedia client. Pure: this file never fetches. The host:
* 1. takes the cached PageEnrichment (description, wikidataId, categories),
* 2. fetches the item once with wikidataEntityParams([qid, …]) (≤ 50 ids per request),
* 3. fetches the labels of the P31/P279 classes it doesn't know with wikidataLabelParams(ids),
* 4. optionally adds outlinks (prop=links, ns0) as pageIds,
* 5. calls profileFromSources() and stores the result per tokenId forever.
* Owner: duel-cards.
*/
import type { PageEnrichment } from '../enrichment.ts';
import type { CardProfile, WikidataClass } from './classify.ts';
export const PROFILE_PROPERTIES = {
instanceOf: 'P31', subclassOf: 'P279', country: 'P17', citizenship: 'P27',
birth: 'P569', death: 'P570', inception: 'P571', start: 'P580', pointInTime: 'P585',
} as const;
/** Properties whose item values count as "cited" for the Linked tier (DUEL_DESIGN §6). */
export const CITE_PROPERTIES = ['P17', 'P27', 'P131', 'P361', 'P527', 'P463', 'P102', 'P108', 'P69', 'P19', 'P20', 'P710', 'P1344', 'P276'] as const;
/** Action API parameters for wbgetentities (claims only, so the payload stays small). */
export function wikidataEntityParams(qids: readonly string[]): Record<string, string> {
if (qids.length < 1 || qids.length > 50) throw new RangeError('wbgetentities takes 1 to 50 ids');
return { action: 'wbgetentities', ids: [...qids].sort().join('|'), props: 'claims', format: 'json', formatversion: '2' };
}
/** Action API parameters for class labels (English). */
export function wikidataLabelParams(qids: readonly string[]): Record<string, string> {
if (qids.length < 1 || qids.length > 50) throw new RangeError('wbgetentities takes 1 to 50 ids');
return { action: 'wbgetentities', ids: [...qids].sort().join('|'), props: 'labels', languages: 'en', format: 'json', formatversion: '2' };
}
/** The slice of a wbgetentities entity this module reads. Unknown shapes are ignored, never thrown on. */
export interface WikidataEntity {
id?: string;
claims?: Record<string, readonly {
rank?: string;
mainsnak?: { snaktype?: string; datavalue?: { type?: string; value?: unknown } };
}[]>;
}
function claimValues(entity: WikidataEntity | null | undefined, property: string): unknown[] {
const statements = entity?.claims?.[property];
if (!Array.isArray(statements)) return [];
return statements
.filter(s => s?.rank !== 'deprecated' && s?.mainsnak?.snaktype === 'value')
.map(s => s.mainsnak?.datavalue?.value)
.filter(v => v !== undefined);
}
function itemIds(entity: WikidataEntity | null | undefined, property: string): string[] {
return claimValues(entity, property)
.map(v => (v && typeof v === 'object' && 'id' in v && typeof (v as { id: unknown }).id === 'string') ? (v as { id: string }).id : null)
.filter((id): id is string => id !== null && /^Q\d+$/.test(id));
}
/** Years from Wikidata time values ("+1909-04-29T00:00:00Z", "-0044-03-15T…"). */
function years(entity: WikidataEntity | null | undefined, property: string): number[] {
return claimValues(entity, property)
.map(v => (v && typeof v === 'object' && 'time' in v) ? String((v as { time: unknown }).time) : '')
.map(t => /^([+-])0*(\d{1,6})-/.exec(t))
.filter((m): m is RegExpExecArray => m !== null)
.map(m => (m[1] === '-' ? -1 : 1) * Number(m[2]))
.filter(y => y !== 0);
}
/** Q-ids whose labels the host must look up to classify this entity. */
export function classIdsOf(entity: WikidataEntity | null | undefined): string[] {
return [...new Set([...itemIds(entity, 'P31'), ...itemIds(entity, 'P279')])].sort();
}
export interface ProfileSources {
enrichment: Pick<PageEnrichment, 'description' | 'wikidataId' | 'categories' | 'revisionId'>;
/** The card's own wbgetentities entity, or null when it has no item or the fetch is pending. */
entity?: WikidataEntity | null;
/** English labels for class Q-ids; missing labels are kept as the bare Q-id. */
labels?: Readonly<Record<string, string>>;
/** Superclass chain for the P31 classes (P279, up to 4 hops), nearest first, if the host resolved it. */
superclasses?: readonly WikidataClass[];
/** ns0 outlinks resolved to pageIds. */
links?: readonly number[];
}
export function profileFromSources(src: ProfileSources): CardProfile {
const { enrichment, entity, labels = {} } = src;
const label = (id: string): WikidataClass => ({ id, label: labels[id] ?? id });
const countries = [...new Set([...itemIds(entity, 'P17'), ...itemIds(entity, 'P27')])].sort();
const yrs = [...new Set(['P569', 'P570', 'P571', 'P580', 'P585'].flatMap(p => years(entity, p)))].sort((a, b) => a - b);
const cites = [...new Set(CITE_PROPERTIES.flatMap(p => itemIds(entity, p)))].sort();
const subclassOf = [...itemIds(entity, 'P279').map(label), ...(src.superclasses ?? [])];
const profile: CardProfile = {
wikidataId: enrichment.wikidataId,
description: enrichment.description,
categories: [...enrichment.categories],
instanceOf: itemIds(entity, 'P31').map(label),
fetchedRevisionId: enrichment.revisionId,
};
if (subclassOf.length) profile.subclassOf = subclassOf;
if (countries.length) profile.countries = countries;
if (yrs.length) profile.years = yrs;
if (claimValues(entity, 'P570').length) profile.died = true;
if (cites.length) profile.cites = cites;
if (src.links?.length) profile.links = [...new Set(src.links)].sort((a, b) => a - b);
return profile;
}
/** A canonical JSON string of a profile, for storing, hashing and logging in the match record. */
export function canonicalProfile(profile: CardProfile): string {
const sortKeys = (v: unknown): unknown => Array.isArray(v) ? v.map(sortKeys)
: v && typeof v === 'object' ? Object.fromEntries(Object.keys(v).sort().map(k => [k, sortKeys((v as Record<string, unknown>)[k])]))
: v;
return JSON.stringify(sortKeys(profile));
}
+76
View File
@@ -0,0 +1,76 @@
/**
* Duel ruleset: every rule number as data (BRIEF "Game rules core").
* parseDuelRuleset() is the only way untrusted JSON (mode files, peer hosts)
* becomes a DuelRuleset. Night 1 Edit War rulesets are rejected cleanly.
*/
import { z } from 'zod';
import type { DuelRuleset } from './types.ts';
const int = (min: number, max: number) => z.number().int().min(min).max(max);
export const DuelRulesetSchema = z.object({
engine: z.literal('duel'),
version: z.string().min(1).max(16),
deckSize: int(1, 60),
maxCopiesPerPage: int(1, 60),
startingLife: int(1, 100),
openingHand: int(0, 10),
handSize: int(1, 15),
mulligans: int(0, 3),
firstPlayerDraws: z.boolean(),
maxCitations: int(1, 20),
citationsPerTurn: int(1, 5),
territoryCap: int(0, 10),
locationsPerTurn: int(0, 10),
libraryEmpty: z.enum(['lose', 'reshuffle', 'fatigue']),
maxKeywords: int(0, 4),
stubMax: int(0, 10),
trendingPower: int(0, 5),
connectedTiers: z.array(z.enum(['Linked', 'Compatriot', 'Contemporary', 'Kin'])).max(4)
.refine(v => new Set(v).size === v.length, 'Duplicate tier'),
connectedBonus: int(0, 5),
linkedBonus: int(0, 5),
turnSeconds: int(5, 600),
bankSeconds: int(0, 3600),
timeoutsToConcede: int(1, 20),
turnCap: int(2, 200).nullable(),
}).strict();
export const DEFAULT_DUEL_RULESET: DuelRuleset = Object.freeze({
engine: 'duel',
version: 'duel-1',
deckSize: 40,
maxCopiesPerPage: 4,
startingLife: 20,
openingHand: 7,
handSize: 7,
mulligans: 1,
firstPlayerDraws: false,
maxCitations: 10,
citationsPerTurn: 1,
territoryCap: 2,
locationsPerTurn: 1,
libraryEmpty: 'lose',
maxKeywords: 2,
stubMax: 2,
trendingPower: 1,
connectedTiers: ['Linked', 'Compatriot', 'Contemporary', 'Kin'],
connectedBonus: 1,
linkedBonus: 2,
turnSeconds: 60,
bankSeconds: 300,
timeoutsToConcede: 3,
turnCap: null,
}) as DuelRuleset;
/** Validate a full ruleset. Throws (ZodError) on anything invalid or unknown. */
export function parseDuelRuleset(value: unknown): DuelRuleset {
return DuelRulesetSchema.parse(value) as DuelRuleset;
}
/** Merge a partial override (a mode file's `rules`) onto the defaults, then validate. */
export function mergeDuelRuleset(overrides: unknown, base: DuelRuleset = DEFAULT_DUEL_RULESET): DuelRuleset {
if (overrides === undefined || overrides === null) return parseDuelRuleset(structuredClone(base));
if (typeof overrides !== 'object' || Array.isArray(overrides)) throw new TypeError('Ruleset overrides must be an object');
return parseDuelRuleset({ ...structuredClone(base), ...(overrides as Record<string, unknown>) });
}
+41
View File
@@ -0,0 +1,41 @@
/**
* Fixture: docs/game/card-sample.json (236 real random cards) → DuelCard[], for sim-balance, the UI
* and tests. The sample has no on-chain extract, so flavour falls back to the description, and its
* tokenIds are synthetic (the pageId as 64 hex digits). Owner: duel-cards.
*/
import type { CardProfile } from './classify.ts';
import { derive, DERIVE_RULES, type CardOnChain, type DeriveRules, type DuelCard } from './derive.ts';
/** The fields of a card-sample.json card that derivation reads. */
export interface SampleCard {
pageId: number; title: string; description: string | null; wikidataId: string | null; revisionId: number;
pageBytes: number; languageCount: number; categories: string[];
stats: { attention: number | null; depth: number; reach: number };
instanceOf: { id: string; label: string }[];
extract?: string;
/** The on-chain mint-time category (server/wiki.ts bucket). */
legacyCategory?: string;
}
export function sampleTokenId(pageId: number): string {
return pageId.toString(16).padStart(64, '0');
}
export function sampleInputs(card: SampleCard): { chain: CardOnChain; profile: CardProfile } {
return {
chain: {
tokenId: sampleTokenId(card.pageId),
article: { pageId: card.pageId, title: card.title, extract: card.extract ?? '', revisionId: card.revisionId,
...(card.legacyCategory ? { category: card.legacyCategory } : {}) },
statsSnapshot: { pageBytes: card.pageBytes, languageCount: card.languageCount, stats: card.stats },
},
profile: {
wikidataId: card.wikidataId, description: card.description, categories: card.categories,
instanceOf: card.instanceOf, fetchedRevisionId: card.revisionId,
},
};
}
export function deriveSample(cards: readonly SampleCard[], rules: DeriveRules = DERIVE_RULES): DuelCard[] {
return cards.map(card => { const { chain, profile } = sampleInputs(card); return derive(chain, profile, rules); });
}
+6
View File
@@ -0,0 +1,6 @@
/** Story layer for the duel (DUEL_DESIGN.md §8): match log and battle recap templates. */
export * from './types.ts';
export { LOG_TEMPLATES, BANNED_WORDS, FOOTER, fill, numberWord, ordinalWord } from './templates.ts';
export { Narrator, renderEvent, renderLog, logParagraphs, gloss, articleUrl, variantIndex, tokenName } from './log.ts';
export { recap, battleName, battleTitle, longDate } from './recap.ts';
export type { RecapDoc, RecapInfobox, RecapSection } from './recap.ts';
+196
View File
@@ -0,0 +1,196 @@
/**
* Deterministic match log (DUEL_DESIGN.md §8.2). Pure: the same MatchRecord always gives the
* same lines, so `replay` and stored records regenerate the log exactly. No network, no clock.
*/
import { Rng } from '../../game/rng.ts';
import { LOG_TEMPLATES, fill, numberWord, type TemplateKey } from './templates.ts';
import type { LogLine, MatchRecord, Reference, Seat, StoryCard, StoryEvent } from './types.ts';
/** Deterministic variant choice: one fresh mulberry32 per (seed, salt, event index). */
export function variantIndex(seed: number | string, salt: string, index: number, n: number): number {
return Rng.fromSeed(`${seed}|${salt}|${index}`).int(n);
}
/** "American actor (1909–1994)" → "American actor, 1909–1994". Verbatim otherwise. */
export function gloss(description: string | undefined): string {
const d = (description ?? '').trim();
if (!d) return '';
const m = /^(.*\S)\s*\(([^()]+)\)$/.exec(d);
return m ? `${m[1]}, ${m[2]}` : d;
}
export function articleUrl(title: string, revisionId: number): string {
return `https://en.wikipedia.org/w/index.php?title=${encodeURIComponent(title.replace(/ /g, '_'))}&oldid=${revisionId}`;
}
/**
* Tracks first mentions and reference numbers for one rendering (a log view or a recap).
* The first mention of a card in a rendering adds its description and the next [n].
*/
export class Narrator {
readonly record: MatchRecord;
readonly salt: string;
readonly references: Reference[] = [];
private refByCard = new Map<string, number>();
private pending: number[] = [];
constructor(record: MatchRecord, salt: string) {
this.record = record;
this.salt = salt;
}
card(id: string): StoryCard {
const c = this.record.cards[id];
if (!c) throw new Error(`story: unknown card id ${id}`);
return c;
}
player(seat: Seat): string { return this.record.players[seat].name; }
/** Assigns a reference number without mentioning the card (e.g. for the References list). Tokens get none (0). */
cite(id: string): number {
let n = this.refByCard.get(id);
if (n === undefined) {
const c = this.card(id);
if (c.token || c.revisionId === undefined) return 0;
n = this.references.length + 1;
this.refByCard.set(id, n);
this.references.push({
n, cardId: id, title: c.title, revisionId: c.revisionId, tokenId: c.tokenId,
url: articleUrl(c.title, c.revisionId),
text: `"${c.title}". Wikipedia. Revision ${c.revisionId}.${c.tokenId ? ` Minted as token ${c.tokenId}.` : ''}`,
});
}
return n;
}
/** A card's name for a sentence: italic, with its description on first mention. */
mention(id: string): string {
const c = this.card(id);
if (c.token || c.revisionId === undefined) return c.title;
const first = !this.refByCard.has(id);
const n = this.cite(id);
if (!first) return `*${c.title}*`;
this.pending.push(n);
const g = gloss(c.description);
return g ? `*${c.title}* (${g})` : `*${c.title}*`;
}
/** Take the citations of first mentions made since the last sentence. */
flush(): number[] {
const refs = this.pending;
this.pending = [];
return refs;
}
/** Fill a variant of `key` and append the citations of first mentions made while filling. */
sentence(key: TemplateKey, index: number, values: Record<string, () => string | number>, must: string[] = []): { text: string; refs: number[] } {
const fits = (t: string) => [...t.matchAll(/\{(\w+)\}/g)].every(m => m[1] in values);
const all = LOG_TEMPLATES[key].filter(fits);
const preferred = all.filter(t => must.every(k => t.includes(`{${k}}`)));
const usable = preferred.length ? preferred : all;
if (!usable.length) throw new Error(`story: no usable template for ${key}`);
const template = usable[variantIndex(this.record.seed, `${this.salt}:${key}`, index, usable.length)];
// Evaluate placeholders in template order so first mentions are numbered left to right.
const filled: Record<string, string | number> = {};
for (const m of template.matchAll(/\{(\w+)\}/g)) if (!(m[1] in filled)) filled[m[1]] = values[m[1]]();
const refs = this.flush();
const body = fill(template, filled);
return { text: body + refs.map(r => `[${r}]`).join(''), refs };
}
}
/** Pluralise a fixed token name ("Staff Member" → "Staff Members"). */
export function tokenName(token: string, count: number): string {
return count === 1 ? token : `${token}s`;
}
/**
* Render one event as a sentence, or null if it is not shown to this viewer.
* `viewer` null = omniscient (post-match, spectators after the end).
*/
export interface RenderOptions {
/** Prefer variants that name the source card (the recap uses this for damage lines). */
preferSource?: boolean;
}
export function renderEvent(nar: Narrator, ev: StoryEvent, index: number, viewer: Seat | null, opts: RenderOptions = {}): { text: string; refs: number[] } | null {
const P = (s: Seat) => () => nar.player(s);
const M = (id: string) => () => nar.mention(id);
const N = (n: number) => () => n;
const other = (s: Seat): Seat => (s === 0 ? 1 : 0);
switch (ev.kind) {
case 'turnStart':
return { text: `Turn ${ev.turn}.`, refs: [] };
case 'deploy':
return nar.sentence('deploy', index, { player: P(ev.seat), card: M(ev.card) });
case 'cast':
return nar.sentence('cast', index, { player: P(ev.seat), card: M(ev.card) });
case 'adopt':
return nar.sentence('adopt', index, { player: P(ev.seat), doctrine: M(ev.doctrine), figure: M(ev.figure), p: N(ev.power), t: N(ev.toughness) });
case 'attack':
return nar.sentence('attack', index, { player: P(ev.seat), opponent: P(other(ev.seat)), card: M(ev.card), p: N(ev.power), t: N(ev.toughness) });
case 'block':
return nar.sentence('block', index, { player: P(ev.seat), blocker: M(ev.blocker), attacker: M(ev.attacker), p: N(ev.power), t: N(ev.toughness) });
case 'playerDamage': {
const v: Record<string, () => string | number> = { player: P(ev.seat), n: N(ev.amount), life: N(Math.max(0, ev.life)) };
if (ev.source) v.source = M(ev.source);
return nar.sentence('playerDamage', index, v, opts.preferSource && ev.source ? ['source'] : []);
}
case 'lifeGain':
return nar.sentence('lifeGain', index, { player: P(ev.seat), source: M(ev.source), n: N(ev.amount), life: N(ev.life) });
case 'effectDamage':
return nar.sentence('effectDamage', index, { source: M(ev.source), target: M(ev.target), n: N(ev.amount) });
case 'destroyed':
return nar.sentence('destroyed', index, { card: M(ev.card) });
case 'tokenCreated':
return nar.sentence('tokenCreated', index, {
source: M(ev.source), count: () => numberWord(ev.count), token: () => tokenName(ev.token, ev.count),
});
case 'draw': {
const count = ev.count ?? 1;
const visible = ev.card !== undefined && (viewer === null || viewer === ev.seat);
if (visible) return nar.sentence('drawKnown', index, { player: P(ev.seat), card: M(ev.card as string) });
if (count > 1) return nar.sentence('drawHiddenMany', index, { player: P(ev.seat), count: () => numberWord(count) });
return nar.sentence('drawHidden', index, { player: P(ev.seat) });
}
case 'discard':
return nar.sentence('discard', index, { player: P(ev.seat), card: M(ev.card) });
case 'connected':
return nar.sentence('connected', index, { a: M(ev.a), b: M(ev.b), reason: () => ev.reason });
case 'rivalry':
return nar.sentence('rivalry', index, { a: M(ev.a), b: M(ev.b), reason: () => ev.reason });
case 'gameOver': {
if (ev.winner === null) return nar.sentence('gameOverDraw', index, { turn: N(ev.turn) });
const key = ({ life: 'gameOverLife', library: 'gameOverLibrary', concede: 'gameOverConcede', timeout: 'gameOverTimeout', turnCap: 'gameOverTurnCap' } as const)[ev.reason];
return nar.sentence(key, index, { winner: P(ev.winner), loser: P(other(ev.winner)), turn: N(ev.turn) });
}
}
}
/** The match log for one viewer (DUEL_DESIGN §8.2). Hidden draws by the opponent stay hidden. */
export function renderLog(record: MatchRecord, viewer: Seat | null = null): { lines: LogLine[]; references: Reference[] } {
const nar = new Narrator(record, 'log');
const lines: LogLine[] = [];
let turn = 0;
record.events.forEach((ev, i) => {
if (ev.kind === 'turnStart') turn = ev.turn;
const out = renderEvent(nar, ev, i, viewer);
if (out) lines.push({ turn, ...out });
});
return { lines, references: nar.references };
}
/** Join lines into one paragraph per turn: "Turn 5. alice deployed …". */
export function logParagraphs(lines: LogLine[]): string[] {
const out: string[] = [];
let cur: string[] = [];
let curTurn = -1;
for (const l of lines) {
if (l.turn !== curTurn && cur.length) { out.push(cur.join(' ')); cur = []; }
curTurn = l.turn;
cur.push(l.text);
}
if (cur.length) out.push(cur.join(' '));
return out;
}
+290
View File
@@ -0,0 +1,290 @@
/**
* "Battle of X (2026)" recap (DUEL_DESIGN.md §8.3). Pure and deterministic: input is the
* match record only. Output is structured data; ui-pvp renders it. All prose is templates
* filled with real card and match data. No LLM, no invented facts.
*/
import { Narrator, renderEvent, variantIndex } from './log.ts';
import { FOOTER, numberWord, ordinalWord } from './templates.ts';
import type { GameOverReason, MatchRecord, Reference, Seat, StoryCard, StoryEvent } from './types.ts';
export interface RecapInfobox {
date: string;
location: string;
result: string;
belligerents: [string, string];
commanders: [string, string];
strength: [string, string];
casualties: [string, string];
}
export interface RecapSection {
heading: string;
paragraphs: string[];
}
export interface RecapDoc {
matchId: string;
/** Path of the shareable page. */
url: string;
masthead: 'WikiDeck';
title: string;
/** Card the battle is named after, if any. */
nameCardId?: string;
infobox: RecapInfobox;
/** Lead paragraph, then Background, Course of the battle, Aftermath, See also. */
lead: string;
sections: RecapSection[];
references: Reference[];
footer: string;
}
const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
/** "2026-11-17" → "17 November 2026". */
export function longDate(iso: string): string {
const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(iso);
if (!m) throw new Error(`recap: date must be ISO YYYY-MM-DD, got ${iso}`);
return `${Number(m[3])} ${MONTHS[Number(m[2]) - 1]} ${m[1]}`;
}
interface Played { id: string; seat: Seat; order: number }
interface Facts {
/** For a draw: seat 0, with `draw` set. */
winner: Seat;
draw: boolean;
loser: Seat;
reason: GameOverReason;
turns: number;
life: [number, number];
played: Played[];
destroyed: string[];
}
function facts(record: MatchRecord): Facts {
const over = [...record.events].reverse().find((e): e is Extract<StoryEvent, { kind: 'gameOver' }> => e.kind === 'gameOver');
if (!over) throw new Error('recap: match has no gameOver event');
const start = record.startingLife ?? 20;
const life: [number, number] = [start, start];
const played: Played[] = [];
const destroyed: string[] = [];
record.events.forEach((e, i) => {
if (e.kind === 'playerDamage' || e.kind === 'lifeGain') life[e.seat] = Math.max(0, e.life);
if (e.kind === 'deploy' || e.kind === 'cast') played.push({ id: e.card, seat: e.seat, order: i });
if (e.kind === 'adopt') played.push({ id: e.doctrine, seat: e.seat, order: i });
if (e.kind === 'destroyed') destroyed.push(e.card);
});
if (over.life) { life[0] = Math.max(0, over.life[0]); life[1] = Math.max(0, over.life[1]); }
const winner: Seat = over.winner ?? 0;
return { winner, draw: over.winner === null, loser: winner === 0 ? 1 : 0, reason: over.reason, turns: over.turn, life, played, destroyed };
}
/** Highest cost wins; ties go to the card played first. */
function best(cands: Played[], cards: Record<string, StoryCard>): Played | undefined {
let top: Played | undefined;
for (const c of cands) if (!top || cards[c.id].cost > cards[top.id].cost) top = c;
return top;
}
/** DUEL_DESIGN §8.3 naming order. */
export function battleName(record: MatchRecord, f: Facts = facts(record)): StoryCard | undefined {
const C = record.cards;
const of = (seat: Seat | null, type?: StoryCard['type']) =>
f.played.filter(p => (seat === null || p.seat === seat) && (!type || C[p.id].type === type));
const pick = best(of(f.winner, 'Location'), C) ?? best(of(f.loser, 'Location'), C)
?? best(of(null, 'Event'), C) ?? best(of(f.winner), C) ?? best(of(f.loser), C);
return pick ? C[pick.id] : undefined;
}
export function battleTitle(record: MatchRecord, f: Facts = facts(record)): string {
const card = battleName(record, f);
const year = record.date.slice(0, 4);
if (!card) return `WikiDeck match of ${longDate(record.date)}`;
if (card.type === 'Figure') return `${card.title} campaign (${year})`;
const each = Math.ceil(f.turns / 2);
const prefix = each <= 6 ? 'Skirmish at' : each >= 13 ? 'Siege of' : 'Battle of';
return `${prefix} ${card.title} (${year})`;
}
function resultText(record: MatchRecord, f: Facts): string {
const w = record.players[f.winner].name;
if (f.draw) return 'Inconclusive';
switch (f.reason) {
case 'concede': case 'timeout': return `${w} victory by withdrawal`;
case 'library': return `${w} victory by attrition`;
case 'turnCap': return `${w} victory by decision`;
case 'life': {
if (f.life[f.winner] <= 3) return `Pyrrhic ${w} victory`;
if (f.life[f.winner] - f.life[f.loser] >= 10) return `Decisive ${w} victory`;
return `${w} victory`;
}
}
}
const LEAD_VARIANTS = [
'The {title} was a WikiDeck engagement fought on {date} between the forces of {a} and {b}. It lasted {turns} turns and ended in {result}.',
'The {title} was fought on {date} between {a} and {b}, and lasted {turns} turns. It ended in {result}.',
'The {title} took place on {date}. The forces of {a} and {b} engaged for {turns} turns; the engagement ended in {result}.',
];
const FIRST_DEPLOY_VARIANTS = [
'Contemporary accounts note the deployment of {card} in the {ordinal} turn.',
'Records list {card} as the first Figure deployed, in the {ordinal} turn.',
'The first Figure to enter play was {card}, in the {ordinal} turn.',
];
function pickVariant(record: MatchRecord, salt: string, list: readonly string[]): string {
return list[variantIndex(record.seed, `recap:${salt}`, 0, list.length)];
}
function sub(t: string, v: Record<string, string | number>): string {
return t.replace(/\{(\w+)\}/g, (_, k: string) => String(v[k]));
}
/** The result as a phrase for the lead: "a Pyrrhic victory for bob". */
function resultPhrase(record: MatchRecord, f: Facts): string {
const w = record.players[f.winner].name;
if (f.draw) return 'a draw';
switch (f.reason) {
case 'concede': case 'timeout': return `a victory for ${w} by withdrawal`;
case 'library': return `a victory for ${w} by attrition`;
case 'turnCap': return `a victory for ${w} by decision`;
case 'life': {
if (f.life[f.winner] <= 3) return `a Pyrrhic victory for ${w}`;
if (f.life[f.winner] - f.life[f.loser] >= 10) return `a decisive victory for ${w}`;
return `a victory for ${w}`;
}
}
}
export function recap(record: MatchRecord): RecapDoc {
const f = facts(record);
const C = record.cards;
const nar = new Narrator(record, 'recap');
const [a, b] = [record.players[0].name, record.players[1].name];
const nameCard = battleName(record, f);
const title = battleTitle(record, f);
const result = resultText(record, f);
// Lead: cite the name card first so it is reference [1].
const nameRef = nameCard ? `[${nar.cite(nameCard.id)}]` : '';
let lead = sub(pickVariant(record, 'lead', LEAD_VARIANTS), {
title: `**${title}**`, date: longDate(record.date), a, b, turns: numberWord(f.turns), result: resultPhrase(record, f),
}) + nameRef;
const firstFig = record.events.findIndex(e => e.kind === 'deploy' && C[e.card].type === 'Figure');
if (firstFig >= 0) {
const ev = record.events[firstFig] as Extract<StoryEvent, { kind: 'deploy' }>;
const turn = turnAt(record.events, firstFig);
const t = pickVariant(record, 'firstDeploy', FIRST_DEPLOY_VARIANTS);
const card = nar.mention(ev.card);
const refs = nar.flush();
lead += ' ' + sub(t, { card, ordinal: ordinalWord(turn) }) + refs.map(r => `[${r}]`).join('');
}
// Background: Portal mix of the cards each side played.
const background: string[] = [];
for (const seat of [0, 1] as Seat[]) {
const mine = f.played.filter(p => p.seat === seat);
if (!mine.length) { background.push(`${record.players[seat].name} played no cards.`); continue; }
const counts = new Map<string, number>();
for (const p of mine) { const k = C[p.id].portal ?? 'Neutral'; counts.set(k, (counts.get(k) ?? 0) + 1); }
const sorted = [...counts.entries()].sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]));
const max = sorted[0][1];
const tops = sorted.filter(([, n]) => n === max).map(([k]) => k);
const name = record.players[seat].name;
const played = `${numberWord(mine.length)} ${mine.length === 1 ? 'card' : 'cards'} played`;
if (tops.length === 1) background.push(`${tops[0]} was the largest Portal in the force of ${name} (${numberWord(max)} of ${played}).`);
else background.push(`${listJoin(tops)} were equally represented in the force of ${name} (${numberWord(max)} ${max === 1 ? 'card' : 'cards'} each, of ${played}).`);
}
// Course of the battle: the largest Notability swings and destroyed cards of cost ≥ 4.
const swings = record.events
.map((e, i) => ({ e, i }))
.filter(x => x.e.kind === 'playerDamage')
.sort((x, y) => (y.e as { amount: number }).amount - (x.e as { amount: number }).amount || x.i - y.i)
.slice(0, 5).map(x => x.i);
const big = record.events.map((e, i) => ({ e, i }))
.filter(x => x.e.kind === 'destroyed' && C[(x.e as { card: string }).card].cost >= 4).map(x => x.i);
const chosen = [...new Set([...swings, ...big])].sort((x, y) => x - y);
const course: string[] = [];
let curTurn = -1;
let para: string[] = [];
for (const i of chosen) {
const t = turnAt(record.events, i);
if (t !== curTurn && para.length) { course.push(para.join(' ')); para = []; }
if (t !== curTurn) para.push(`In the ${ordinalWord(t)} turn,`);
curTurn = t;
const out = renderEvent(nar, record.events[i], i, null, { preferSource: true });
if (out) para.push(out.text);
}
if (para.length) course.push(para.join(' '));
const over = record.events.findIndex(e => e.kind === 'gameOver');
const end = renderEvent(nar, record.events[over], over, null);
if (end) course.push(end.text);
// Aftermath.
const aftermath = [f.draw
? `Both ${a} and ${b} ended the engagement with ${f.life[0]} Notability.`
: `${record.players[f.winner].name} ended the engagement with ${f.life[f.winner]} Notability; ${record.players[f.loser].name} ended with ${f.life[f.loser]}.`,
];
if (record.ratingChange) {
const fmt = (n: number) => (n >= 0 ? `+${n}` : `${n}`);
aftermath.push(`Ratings changed by ${fmt(record.ratingChange[0])} for ${a} and ${fmt(record.ratingChange[1])} for ${b}.`);
}
// See also: Connected pairs and rivalries.
const seeAlso: string[] = [];
for (const e of record.events) {
if (e.kind === 'connected' || e.kind === 'rivalry') seeAlso.push(`*${C[e.a].title}* – *${C[e.b].title}* (${e.reason})`);
}
// References: every card played, in first-mention order.
for (const p of f.played) nar.cite(p.id);
const perSeat = (fn: (s: Seat) => string): [string, string] => [fn(0), fn(1)];
const infobox: RecapInfobox = {
date: longDate(record.date),
location: nameCard?.type === 'Location' ? nameCard.title : `WikiDeck host ${record.hostName ?? 'unknown'}`,
result,
belligerents: [a, b],
commanders: perSeat(s => {
const c = best(f.played.filter(p => p.seat === s && C[p.id].type === 'Figure'), C);
return c ? C[c.id].title : 'None recorded';
}),
strength: perSeat(s => cards(f.played.filter(p => p.seat === s).length)),
casualties: perSeat(s => {
const lost = f.destroyed.filter(id => C[id].owner === s).map(id => C[id].title);
return lost.length ? `${cards(lost.length)} destroyed: ${lost.join(', ')}` : 'None';
}),
};
const sections: RecapSection[] = [
{ heading: 'Background', paragraphs: background },
{ heading: 'Course of the battle', paragraphs: course },
{ heading: 'Aftermath', paragraphs: aftermath },
];
if (seeAlso.length) sections.push({ heading: 'See also', paragraphs: seeAlso });
return {
matchId: record.matchId,
url: `/recap/${encodeURIComponent(record.matchId)}`,
masthead: 'WikiDeck',
title,
nameCardId: nameCard?.id,
infobox,
lead,
sections,
references: nar.references,
footer: FOOTER,
};
}
function listJoin(xs: string[]): string {
return xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`;
}
function cards(n: number): string { return `${n} ${n === 1 ? 'card' : 'cards'}`; }
function turnAt(events: StoryEvent[], index: number): number {
for (let i = index; i >= 0; i--) { const e = events[i]; if (e.kind === 'turnStart') return e.turn; }
return 0;
}
+156
View File
@@ -0,0 +1,156 @@
/**
* Match-log sentence templates (DUEL_DESIGN.md §8.2). Data only.
*
* Tone (BRIEF decision 5, DUEL_DESIGN §8.1): past tense, encyclopedic, deadpan. No adjectives
* about cards or players, no exclamation marks, never comment on the matchup. Placeholders
* are filled only with real card and match data. `tests/duel-design-story.test.ts` lints this file.
*
* Placeholders: {player} {opponent} {card} {doctrine} {figure} {attacker} {blocker} {source}
* {target} {token} {a} {b} {reason} {winner} {loser} {n} {count} {p} {t} {life} {turn}.
*/
export const LOG_TEMPLATES = {
deploy: [
'{player} deployed {card}.',
'{card} was deployed by {player}.',
'{player} brought {card} into play.',
'{card} entered play under {player}.',
],
cast: [
'{player} cited {card}.',
'{card} was cited by {player}.',
'{player} invoked {card}.',
],
adopt: [
'{doctrine} was adopted by {figure}, which became a {p}/{t}.',
'{figure} adopted {doctrine} and became a {p}/{t}.',
'{player} attached {doctrine} to {figure} ({p}/{t}).',
],
attack: [
'{card} ({p}/{t}) attacked.',
'{player} sent {card} ({p}/{t}) into combat.',
'{card} ({p}/{t}) advanced on {opponent}.',
],
block: [
'{blocker} ({p}/{t}) blocked {attacker}.',
'{attacker} was blocked by {blocker} ({p}/{t}).',
'{blocker} ({p}/{t}) intercepted {attacker}.',
],
playerDamage: [
'{player} lost {n} Notability ({life} remaining).',
'{source} dealt {n} damage to {player}, leaving {life} Notability.',
"{player}'s Notability fell to {life}.",
],
lifeGain: [
'{player} gained {n} Notability from {source} ({life} total).',
'{source} restored {n} Notability to {player}.',
"{player}'s Notability rose to {life} ({source}).",
],
effectDamage: [
'{source} dealt {n} damage to {target}.',
'{target} took {n} damage from {source}.',
'{source} inflicted {n} damage on {target}.',
],
destroyed: [
'{card} was destroyed.',
'{card} was moved to Deleted.',
'{card} was removed from play.',
'{card} did not survive the turn.',
],
tokenCreated: [
'{source} produced {count} {token}.',
'{source} brought {count} {token} into play.',
'{source} created {count} {token}.',
],
drawKnown: [
'{player} drew {card}.',
'{card} was drawn by {player}.',
'{player} added {card} to their hand.',
],
drawHidden: [
'{player} drew a card.',
'{player} drew one card.',
'{player} added a card to their hand.',
],
drawHiddenMany: [
'{player} drew {count} cards.',
'{player} added {count} cards to their hand.',
'{player} took {count} cards into hand.',
],
discard: [
'{player} discarded {card}.',
'{card} was discarded by {player}.',
'{player} moved {card} from hand to Deleted.',
],
connected: [
'{a} and {b} were Connected ({reason}).',
'{a} was Connected to {b} through {reason}.',
'Records link {a} and {b} ({reason}).',
],
rivalry: [
'{a} and {b} are both listed under {reason}.',
'{a} and {b} share {reason}.',
'The two sides were linked through {reason}.',
],
gameOverLife: [
'{loser} was nominated for deletion. The result was **delete**.',
'{loser} was reduced to 0 Notability. {winner} won.',
'{winner} won on turn {turn}.',
],
gameOverDraw: [
'Both sides were reduced to 0 Notability. The engagement ended in a draw.',
'The engagement ended in a draw on turn {turn}.',
'Neither side retained any Notability. No winner was recorded.',
],
gameOverLibrary: [
'{loser} could not draw a card and lost.',
'{loser} ran out of cards. {winner} won.',
"{loser}'s library was exhausted. {winner} won.",
],
gameOverConcede: [
'{loser} withdrew.',
'{loser} withdrew. {winner} won.',
'{loser} conceded on turn {turn}.',
],
gameOverTimeout: [
'{loser} did not respond in time and withdrew.',
'{loser} ran out of time. {winner} won.',
"{loser}'s clock expired on turn {turn}.",
],
gameOverTurnCap: [
'{winner} won on Notability at the turn limit.',
'The turn limit was reached. {winner} won on Notability.',
'The engagement reached the turn limit; {winner} held more Notability.',
],
} as const satisfies Record<string, readonly string[]>;
export type TemplateKey = keyof typeof LOG_TEMPLATES;
/** Words the generator must never emit (critic S7 failure modes). Lowercase; whole words. */
export const BANNED_WORDS = [
'brutal', 'brutally', 'heroic', 'heroically', 'humiliating', 'humiliated', 'bloodiest', 'bloody',
'surprising', 'surprisingly', 'ironically', 'unlikely', 'hilarious', 'tragic', 'tragically', 'sadly',
'unfortunately', 'poor', 'epic', 'crushed', 'squashed', 'killed', 'murdered', 'destroyed utterly', 'lol',
];
export const FOOTER =
'This page records a WikiDeck match. Card names refer to Wikipedia articles; the events described are game events.';
const NUMBER_WORDS = ['zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven',
'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen', 'nineteen', 'twenty'];
export function numberWord(n: number): string {
return Number.isInteger(n) && n >= 0 && n < NUMBER_WORDS.length ? NUMBER_WORDS[n] : String(n);
}
const ORDINALS = ['zeroth', 'first', 'second', 'third', 'fourth', 'fifth', 'sixth', 'seventh', 'eighth', 'ninth', 'tenth',
'eleventh', 'twelfth', 'thirteenth', 'fourteenth', 'fifteenth', 'sixteenth', 'seventeenth', 'eighteenth', 'nineteenth', 'twentieth'];
export function ordinalWord(n: number): string {
if (Number.isInteger(n) && n >= 0 && n < ORDINALS.length) return ORDINALS[n];
const s = n % 100 >= 11 && n % 100 <= 13 ? 'th' : ({ 1: 'st', 2: 'nd', 3: 'rd' } as Record<number, string>)[n % 10] ?? 'th';
return `${n}${s}`;
}
export function fill(template: string, values: Record<string, string | number>): string {
return template.replace(/\{(\w+)\}/g, (whole, key: string) => {
if (!(key in values)) throw new Error(`story template is missing a value for {${key}}: ${template}`);
return String(values[key]);
});
}
+98
View File
@@ -0,0 +1,98 @@
/**
* Story input contract (DUEL_DESIGN.md §8). This is the minimal, engine-agnostic shape the
* match-log and recap templates read. `fromDuel.ts` (added after duel-core's
* shared/duel/types.ts merges) maps engine LogEvents onto it. Everything is plain JSON,
* so a stored match record can regenerate its log and recap exactly.
*/
export type Seat = 0 | 1;
export type CardType = 'Figure' | 'Location' | 'Event' | 'Institution' | 'Doctrine';
/** One card instance in the match, frozen from its derived profile. Only real data. */
export interface StoryCard {
/** Engine instance id, unique within the match. */
id: string;
/** Article title, verbatim. */
title: string;
/** Wikidata short description, verbatim ('' or undefined if none). */
description?: string;
type: CardType;
cost: number;
/** Portal (faction): Arts, Earth, History, Science, Society or Neutral. */
portal?: string;
/** The article revision the card was minted from (on-chain). Absent for tokens: they are never cited. */
revisionId?: number;
/** Tokens (Elected Member, Staff Member): generic, not articles, never cited or glossed. */
token?: boolean;
/** On-chain token id of the mint, if known. */
tokenId?: string;
/** Seat that owns the card in this match. */
owner: Seat;
}
export type GameOverReason = 'life' | 'library' | 'concede' | 'timeout' | 'turnCap';
export type StoryEvent =
| { kind: 'turnStart'; turn: number; seat: Seat }
| { kind: 'deploy'; seat: Seat; card: string }
| { kind: 'cast'; seat: Seat; card: string }
| { kind: 'adopt'; seat: Seat; doctrine: string; figure: string; power: number; toughness: number }
| { kind: 'attack'; seat: Seat; card: string; power: number; toughness: number }
| { kind: 'block'; seat: Seat; blocker: string; attacker: string; power: number; toughness: number }
/** `seat` is the player who lost Notability; `life` is what remains. */
| { kind: 'playerDamage'; seat: Seat; source?: string; amount: number; life: number }
/** `life` is the new total. */
| { kind: 'lifeGain'; seat: Seat; source: string; amount: number; life: number }
| { kind: 'effectDamage'; source: string; target: string; amount: number }
| { kind: 'destroyed'; card: string }
| { kind: 'tokenCreated'; seat: Seat; source: string; token: string; count: number }
/** `card` set when the drawn card is known to the viewer's record; hidden draws omit it. */
| { kind: 'draw'; seat: Seat; card?: string; count?: number }
/** Deleted is public (DUEL_DESIGN §2.3): discards are always named. */
| { kind: 'discard'; seat: Seat; card: string }
| { kind: 'connected'; seat: Seat; a: string; b: string; reason: string }
| { kind: 'rivalry'; a: string; b: string; reason: string }
/** winner null = draw (both players reached 0 at once). */
/** `life`: final Notability per seat, authoritative when present (duel-core carries it). */
| { kind: 'gameOver'; winner: Seat | null; reason: GameOverReason; turn: number; life?: [number, number] };
export interface StoryPlayer {
/** Display name of the seat (account display name or "Bot (Normal)"). */
name: string;
}
export interface MatchRecord {
matchId: string;
/**
* Story seed: drives template variants only. NOT the engine seed: a client rendering
* logFor text must never learn the engine seed (it would reveal library order). The host
* derives it, e.g. sha256(engineSeed + ':story'). Recaps after the match may use either.
*/
seed: number | string;
/** Match date, ISO `YYYY-MM-DD`. No clock is read by the story code. */
date: string;
players: [StoryPlayer, StoryPlayer];
cards: Record<string, StoryCard>;
events: StoryEvent[];
startingLife?: number;
hostName?: string;
/** Ranked matches: rating change per seat. */
ratingChange?: [number, number];
}
export interface LogLine {
turn: number;
text: string;
/** Reference numbers cited by this line, in order. */
refs: number[];
}
export interface Reference {
n: number;
cardId: string;
title: string;
revisionId: number;
tokenId?: string;
url: string;
/** Rendered citation line, without the leading number. */
text: string;
}
+144
View File
@@ -0,0 +1,144 @@
/**
* Rules text in MTG's terse register (designer review §3.4–3.5, critic S7, BRIEF decision 5).
* Deterministic templates filled only with the card's own derived numbers and keyword names.
* No prose about the subject, no invented facts: flavour text is the article's own first sentence.
* Owner: duel-cards.
*/
import type { DuelCard, Keyword } from './derive.ts';
import type { EffectSpec } from './effects.ts';
/** Reminder text per keyword (DUEL_DESIGN §4). */
export const KEYWORD_REMINDER: Readonly<Record<Keyword, string>> = {
Protected: 'Can\'t be the target of Events or Doctrines an opponent controls.',
Featured: 'Can\'t be blocked except by Featured, Translated or Multilingual Figures.',
Legacy: 'When this is destroyed, draw a card.',
Multilingual: 'Can block Featured Figures. Can\'t be blocked by Local Figures.',
Translated: 'Can block Featured Figures.',
'Well-sourced': 'Prevent the first 1 damage that would be dealt to this each turn.',
Stub: 'At the start of your turn, put a +1/+1 counter on this, to a maximum of 2.',
Local: 'Gets +1/+1 while you control a Compatriot Location.',
};
const NUMBER_WORDS = ['zero', 'one', 'two', 'three', 'four', 'five', 'six'];
const word = (n: number) => NUMBER_WORDS[n] ?? String(n);
const signed = (n: number) => (n >= 0 ? `+${n}` : `−${-n}`);
const pt = (p = 0, t = 0) => `${signed(p)}/${signed(t)}`;
const TARGET_NOUN: Readonly<Record<string, string>> = {
figure: 'target Figure', figureOrLocation: 'target Figure or Location', ownFigure: 'target Figure you control',
opponentFigure: 'target Figure you don\'t control', each: 'each Figure and each Location', self: 'this',
attached: 'enchanted Figure', ownFigures: 'Figures you control',
};
function keywordsAsText(keywords: readonly Keyword[]): string {
return keywords.join(', ');
}
function staticText(e: EffectSpec): string {
const c = e.condition ?? {};
let who = 'Figures you control';
if (c.maxPower !== undefined) who = `Figures you control with power ${c.maxPower} or less`;
if (c.connected) who = 'Figures you control that are Connected to this';
if (c.samePortal) who = 'Other Figures you control of its Portal';
if (e.grant?.length && !e.power && !e.toughness) {
return `${who} have ${keywordsAsText(e.grant)}.`;
}
return `${who} get ${pt(e.power, e.toughness)}.`;
}
function tokenText(e: EffectSpec): string {
const t = e.token!;
const n = e.amount ?? 1;
const portal = t.portal === 'Neutral' ? '' : `${t.portal} `;
const body = `${t.power}/${t.toughness} ${portal}Figure token${n === 1 ? '' : 's'} named ${t.name}`;
return n === 1 ? `create a ${body}` : `create ${word(n)} ${body}`;
}
function actionText(e: EffectSpec): string {
switch (e.op) {
case 'damage': return `deal ${e.amount} damage to ${TARGET_NOUN[e.target ?? 'figure']}`;
case 'damageEach': return `deal ${e.amount} damage to each Figure and each Location`;
case 'createToken': return tokenText(e);
case 'pump': return `${TARGET_NOUN[e.target ?? 'figure']} gets ${pt(e.power, e.toughness)}${e.duration === 'turn' ? ' until end of turn' : ''}`;
case 'fight': return `it fights ${TARGET_NOUN[e.target ?? 'opponentFigure']}`;
case 'draw': return e.amount === 1 ? 'draw a card' : `draw ${word(e.amount ?? 1)} cards`;
case 'gainLife': return `you gain ${e.amount} Notability`;
case 'attach': return '';
}
}
const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
/** One sentence per effect, in effect order. */
export function effectText(effects: readonly EffectSpec[]): string[] {
const lines: string[] = [];
for (let i = 0; i < effects.length; i++) {
const e = effects[i];
if (e.op === 'attach') {
// The Doctrine's buff is the static pump on `attached` that follows (DUEL_API "Doctrine").
const next = effects[i + 1];
const buff = next && next.trigger === 'static' && next.op === 'pump' && next.target === 'attached' ? next : null;
let line = `Attach to ${e.target === 'figure' ? 'target Figure' : 'target Figure you control'}.`;
if (buff) {
const grant = buff.grant?.length ? ` and has ${keywordsAsText(buff.grant)}` : '';
line += ` It gets ${pt(buff.power, buff.toughness)}${grant}.`;
i++;
}
lines.push(line);
continue;
}
if (e.op === 'fight' && i > 0 && effects[i - 1].op === 'pump') {
lines[lines.length - 1] = lines[lines.length - 1].replace(/\.$/, `, then ${actionText(e)}.`);
continue;
}
switch (e.trigger) {
case 'static': lines.push(staticText(e)); break;
case 'onPlay': lines.push(`${cap(actionText(e))}.`); break;
case 'onEnter': lines.push(`When this enters, ${actionText(e)}.`); break;
case 'onDestroyed': lines.push(`When this is destroyed, ${actionText(e)}.`); break;
case 'startOfTurn': {
const max = e.condition?.maxTokens;
const cond = max !== undefined ? `, if you control fewer than ${max} tokens` : '';
lines.push(`At the start of your turn${cond}, ${actionText(e)}.`);
break;
}
case 'onCombatDamageToPlayer':
// On a Doctrine the trigger belongs to the attached Figure ("it"); on a Figure, to "this".
lines.push(`Whenever ${effects.some(x => x.op === 'attach') ? 'it' : 'this'} deals combat damage to a player, ${actionText(e)}.`);
break;
}
}
return lines;
}
/** The type line, e.g. "Figure — Society" or "Event — History". */
export function typeLine(card: Pick<DuelCard, 'type' | 'portal'>): string {
return card.portal === 'Neutral' ? card.type : `${card.type} — ${card.portal}`;
}
/** Full rules text: keyword line, Location lines, effect lines. Newline-separated. */
export function rulesTextFor(card: Pick<DuelCard, 'type' | 'keywords' | 'effects' | 'territory' | 'toughness'>): string {
const lines: string[] = [];
if (card.keywords.length) lines.push(`${keywordsAsText(card.keywords)}.`);
if (card.type === 'Location') {
if (card.territory) lines.push('Territory.');
lines.push(`Garrison 0/${card.toughness}.`);
}
lines.push(...effectText(card.effects));
return lines.join('\n');
}
export const RULE_WORD_REMINDER: Readonly<Record<'Territory' | 'Garrison', string>> = {
Territory: 'Your Citation maximum is 1 higher while you control this, to at most +2 from Territory.',
Garrison: 'This can block like a Figure with power 0. It can\'t attack.',
};
/** Rules text with reminder text for keywords and rule words, for the tap-to-expand view. */
export function rulesTextWithReminders(card: Pick<DuelCard, 'type' | 'keywords' | 'effects' | 'territory' | 'toughness'>): string {
const lines = card.keywords.map(k => `${k}. (${KEYWORD_REMINDER[k]})`);
for (const line of rulesTextFor({ ...card, keywords: [] }).split('\n').filter(Boolean)) {
const word = line.match(/^(Territory|Garrison)\b/)?.[1] as keyof typeof RULE_WORD_REMINDER | undefined;
lines.push(word ? `${line} (${RULE_WORD_REMINDER[word]})` : line);
}
return lines.join('\n');
}
+397
View File
@@ -0,0 +1,397 @@
/**
* WikiDeck Duel: the Magic-style 40-card engine (off-chain). Contract types.
* Spec: docs/game/DUEL_API.md (rules: docs/game/DUEL_DESIGN.md). Owner: duel-core (claude/wikideck#55).
*
* Everything here is plain JSON data: DuelState round-trips through
* JSON.stringify/parse with no loss (no Maps, classes or functions).
* shared/game/ (Edit War) is a separate engine and is not affected.
*/
import type { RngState } from '../game/rng.ts';
export type Seat = 0 | 1;
export const SEATS: readonly Seat[] = [0, 1];
// ---------------------------------------------------------------------------
// Cards (derived by duel-cards in shared/duel/derive.ts; the engine never re-derives)
// ---------------------------------------------------------------------------
export type CardType = 'Figure' | 'Location' | 'Event' | 'Institution' | 'Doctrine';
export const CARD_TYPES: readonly CardType[] = ['Figure', 'Location', 'Event', 'Institution', 'Doctrine'];
export type Portal = 'Arts' | 'Earth' | 'History' | 'Science' | 'Society' | 'Neutral';
export const PORTALS: readonly Portal[] = ['Arts', 'Earth', 'History', 'Science', 'Society', 'Neutral'];
/** Card keywords (DUEL_DESIGN §4), ≤ ruleset.maxKeywords per card. 'Trending' is granted by Trending mode only. */
export type Keyword = 'Protected' | 'Featured' | 'Legacy' | 'Multilingual' | 'Translated' | 'Well-sourced' | 'Stub' | 'Local' | 'Trending';
export const KEYWORDS: readonly Keyword[] = ['Protected', 'Featured', 'Legacy', 'Multilingual', 'Translated', 'Well-sourced', 'Stub', 'Local', 'Trending'];
/** Connected tiers (DUEL_DESIGN §6). The engine computes them from `connect`. */
export type ConnectedTier = 'Linked' | 'Compatriot' | 'Contemporary' | 'Kin';
export const CONNECTED_TIERS: readonly ConnectedTier[] = ['Linked', 'Compatriot', 'Contemporary', 'Kin'];
/** Frozen claims used for Connected (no I/O during a match). */
export interface ConnectKeys {
/** P17/P27 values (Q-ids or labels; compared as strings). */
countries: string[];
/** From P569/P570/P571/P580/P585, e.g. 19 for the 1800s. */
centuries: number[];
/** Outlink pageIds (cached), plus pageIds the card's claims cite. */
links: number[];
/** P31 Q-ids. Q5 (human) and Q16521 (taxon) never count for Kin. */
p31: string[];
/** The card's own Q-id, and the Q-ids its claims cite: Linked if either cites the other (DUEL_DESIGN §6). */
qid?: string;
cites?: string[];
}
/** When an effect runs. Sorcery speed only: there is no stack and no response window. */
export type EffectTrigger =
| 'onPlay' // an Event resolves (on a permanent: same as onEnter)
| 'onEnter' // this permanent enters the battlefield
| 'onAttack' // this Figure is declared as an attacker (resolves at confirmAttack)
| 'onDestroyed' // this permanent is destroyed (after all combat damage)
| 'startOfTurn' // its controller's refresh step, in entry order
| 'onCombatDamageToPlayer' // this Figure (or the Figure this Doctrine is attached to) deals combat damage to a player
| 'static'; // continuous while on the battlefield
/** Effect ops the interpreter knows. duel-cards builds the 12 templates (DUEL_DESIGN §5) from these. */
export type EffectOp =
| 'damage' // `amount` to each target (Figure, Location or player)
| 'damageEach' // `amount` to every Figure and Location (target narrows: 'ownFigures' / 'opponentFigures')
| 'createToken' // `amount` (default 1) copies of `token` under the controller; condition.maxTokens limits
| 'pump' // +power/+toughness (negative allowed); duration 'turn' | 'permanent'; as static: while the source is in play
| 'fight' // the previous chosen target (else this permanent) and this target deal damage equal to their power to each other
| 'draw' // controller draws `amount`
| 'attach' // Doctrine: attach to the target Figure (defines the Doctrine's target)
| 'gainLife' // controller gains `amount` Notability
| 'drain' // opponent loses `amount`, controller gains `amount`
| 'destroy' // destroy target permanent
| 'bounce' // return target permanent to its owner's hand
| 'tap'; // tap target permanent
export type TargetSpec =
// chosen (each consumes one entry of play.targets, in effect order)
| 'figure' // any Figure
| 'figureOrLocation' // any Figure or Location
| 'ownFigure' // a Figure you control
| 'opponentFigure' // a Figure you don't control
| 'anyTarget' // any Figure, Location or player
// automatic
| 'each' // every Figure and Location
| 'self' // this permanent
| 'attached' // the Figure this Doctrine is attached to
| 'ownFigures' // every Figure you control
| 'opponentFigures' // every Figure you don't control
| 'opponent' // the opposing player
| 'controller'; // you
export interface TokenSpec { name: string; power: number; toughness: number; portal: Portal }
export interface EffectSpec {
trigger: EffectTrigger;
op: EffectOp;
/** Default per op: damage → 'anyTarget'; pump → 'self'; draw/gainLife/createToken → 'controller'; drain → 'opponent'. */
target?: TargetSpec;
amount?: number;
/** pump: +power/+toughness (default: amount/amount). */
power?: number;
toughness?: number;
/** pump/grant outside static: 'turn' (default) or 'permanent'. */
duration?: 'turn' | 'permanent';
token?: TokenSpec;
condition?: {
/** Only affects Figures with printed power ≤ maxPower. */
maxPower?: number;
/** Only Figures of the source's Portal (for a Doctrine: the attached Figure's Portal), excluding that card itself. */
samePortal?: boolean;
/** Only Figures Connected to the source. */
connected?: boolean;
/** createToken: only if the controller controls fewer than this many tokens. */
maxTokens?: number;
};
/** Keywords granted to the affected Figures (static: while in play; otherwise for `duration`). */
grant?: Keyword[];
/** Template id (T1–T12) for rules text and log wording. */
template?: string;
}
/**
* A card as the engine sees it, frozen at match start. The host builds these
* from the chain via duel-cards' derive(); the engine trusts them.
*/
export interface DuelCard {
/** Unique within one deck: the NFT tokenId (or a sample id in sims; `token:` ids for tokens). */
cardId: string;
pageId: number | null;
revisionId?: number;
title: string;
/** Wikidata description ("American actor (1909–1994)"), for log first mentions. */
description?: string;
type: CardType;
/** e.g. 'conflict', 'election', 'organisation', 'pathology'. */
subtype?: string | null;
portal: Portal;
cost: number;
/** Figures: the body. Locations: power 0, toughness = Garrison (0 = can't block). Others: null or 0. */
power: number | null;
toughness: number | null;
keywords: Keyword[];
/** Locations: +N max Citations while controlled (all sources together ≤ territoryCap). */
territory?: number;
effects: EffectSpec[];
/** Deterministic rules text (shared/duel/text.ts). Display only. */
rulesText: string;
/** First sentence of article.extract (else description). Display only. */
flavor: string;
connect?: ConnectKeys;
rarity?: 'Common' | 'Rare' | 'Epic' | 'Legendary';
deriveVersion?: string;
/** Tokens are created in play and never in decks. */
token?: boolean;
}
// ---------------------------------------------------------------------------
// Ruleset (all numbers are data; parseDuelRuleset in ruleset.ts validates)
// ---------------------------------------------------------------------------
export type LibraryEmpty = 'lose' | 'reshuffle' | 'fatigue';
export interface DuelRuleset {
engine: 'duel';
version: string;
deckSize: number; // 40
maxCopiesPerPage: number; // 4
startingLife: number; // 20 Notability
openingHand: number; // 7
handSize: number; // 7: hand limit at end of turn (DUEL_DESIGN `handLimit`); excess discarded highest cost first
mulligans: number; // 1: shuffle, draw openingHand, bottom one per mulligan taken
firstPlayerDraws: boolean; // false
maxCitations: number; // 10
citationsPerTurn: number; // 1
territoryCap: number; // 2
locationsPerTurn: number; // 1
libraryEmpty: LibraryEmpty; // 'lose'
maxKeywords: number; // 2
stubMax: number; // 2: max Stub counters
trendingPower: number; // 1: Trending gets +N/+0
connectedTiers: ConnectedTier[]; // all four; cut tiers by removing them
connectedBonus: number; // 1
linkedBonus: number; // 2
turnSeconds: number; // 60
bankSeconds: number; // 300
timeoutsToConcede: number; // 3 consecutive timeouts lose
/** Optional: after this many turns in total, higher Notability wins, then higher power in play, then the second player. */
turnCap: number | null;
}
// ---------------------------------------------------------------------------
// State
// ---------------------------------------------------------------------------
/** 'mulligan' → 'main' → 'attack' → ('block' if attackers can be blocked) → next turn. Refresh, draw, damage and end are automatic. */
export type Phase = 'mulligan' | 'main' | 'attack' | 'block' | 'over';
/** One physical card in a match. `uid` is unique per match ("0:12" = seat 0, deck index 12; "t:3" = token); actions use uids. */
export interface CardInstance {
uid: string;
owner: Seat;
card: DuelCard;
}
export interface Permanent extends CardInstance {
controller: Seat;
tapped: boolean;
/** "Pending review": entered this turn, can't attack. */
sick: boolean;
damage: number;
/** Stub +1/+1 counters. */
counters: number;
/** Permanent pump modifiers. */
permPower: number;
permToughness: number;
/** Until-end-of-turn modifiers. */
tempPower: number;
tempToughness: number;
/** Keywords granted until end of turn / permanently by non-static effects. */
tempKeywords: Keyword[];
permKeywords: Keyword[];
/** Doctrines: uid of the Figure they're attached to. */
attachedTo?: string;
/** Well-sourced: prevention already used this turn. */
shielded: boolean;
/** Entry order (trigger order). */
entered: number;
/** Connected bonus already logged. */
connectedLogged: boolean;
}
export interface PlayerState {
life: number;
/** Citations available this turn. */
citations: number;
/** Base max (rises by citationsPerTurn to maxCitations). */
baseCitations: number;
library: CardInstance[]; // top = index 0. Hidden.
hand: CardInstance[]; // hidden from the opponent
graveyard: CardInstance[]; // "Deleted", public
mulligansTaken: number;
ready: boolean;
locationsThisTurn: number;
/** Remaining time bank in seconds (the host decrements it). */
bankSeconds: number;
/** Consecutive timeouts. */
timeouts: number;
/** libraryEmpty 'fatigue': damage of the last empty draw. */
fatigue: number;
}
export interface CombatState {
attackers: string[];
/** blocker uid → attacker uid. */
blocks: Record<string, string>;
}
export type EndReason = 'life' | 'library' | 'concede' | 'timeout' | 'turnCap';
export interface DuelResult {
winner: Seat | null; // null = draw
reason: EndReason;
}
export interface DuelState {
engine: 'duel';
rules: DuelRuleset;
seed: string;
rng: RngState;
/** 1-based, counts both players' turns. 0 during mulligans. */
turn: number;
active: Seat;
firstSeat: Seat;
phase: Phase;
players: [PlayerState, PlayerState];
battlefield: Permanent[];
combat: CombatState;
log: LogEvent[];
result: DuelResult | null;
/** Increments on every applied action (host polling: unchanged → 204). */
version: number;
/** Counters for token uids and entry order. */
nextToken: number;
nextEntry: number;
}
// ---------------------------------------------------------------------------
// Actions (atomic; legalActions enumerates them; [] for the seat not to act)
// ---------------------------------------------------------------------------
export type TargetRef = { kind: 'card'; uid: string } | { kind: 'player'; seat: Seat };
export type DuelAction =
| { type: 'keep' }
| { type: 'mulligan' }
/** targets: one per chosen-target effect, in effect order (Doctrine: its 'attach' target). Omitted when none. */
| { type: 'play'; uid: string; targets?: TargetRef[] }
| { type: 'endPhase' } // main → attack
| { type: 'toggleAttacker'; uid: string } // declare one more attacker (monotonic)
| { type: 'confirmAttack' } // no attackers → end turn
| { type: 'block'; blocker: string; attacker: string } // defender, monotonic
| { type: 'confirmBlocks' } // damage, then end of turn
| { type: 'concede' } // any time, either seat (not listed)
| { type: 'timeout' }; // host-only, for the seat that must act (not listed)
// ---------------------------------------------------------------------------
// Log (encyclopedic; clients get logFor(state, seat); state.log is omniscient)
// ---------------------------------------------------------------------------
/** A card in the log. power/toughness: current values right after the event (Figures and Garrisons on the battlefield). */
export interface CardRef { uid: string; cardId: string; title: string; pageId: number | null; type: CardType; power?: number; toughness?: number }
export type LogEvent = { seq: number; turn: number } & (
| { kind: 'start'; firstSeat: Seat }
| { kind: 'mulligan'; seat: Seat }
| { kind: 'keep'; seat: Seat; handSize: number }
| { kind: 'turnStart'; seat: Seat; citations: number; life: [number, number] }
/** card is omitted in the opponent's logFor (hidden draw). */
| { kind: 'draw'; seat: Seat; card?: CardRef }
/** A Figure, Location or Institution entered. */
| { kind: 'deploy'; seat: Seat; card: CardRef }
/** An Event resolved. */
| { kind: 'cast'; seat: Seat; card: CardRef; targets: TargetRef[] }
/** A Doctrine was attached. */
| { kind: 'adopt'; seat: Seat; card: CardRef; to: CardRef }
| { kind: 'tokenCreated'; seat: Seat; card: CardRef; source: CardRef }
| { kind: 'connected'; seat: Seat; card: CardRef; with: CardRef; tier: ConnectedTier; via: string; bonus: number }
/** Rivalry (log only): two opposing permanents are Connected. */
| { kind: 'rivalry'; card: CardRef; with: CardRef; tier: ConnectedTier; via: string }
/** Any resolved effect (wording key: template). Damage and life changes follow as their own events. */
| { kind: 'effect'; seat: Seat; source: CardRef; op: EffectOp; template?: string; targets: TargetRef[] }
| { kind: 'attack'; seat: Seat; attackers: CardRef[] }
| { kind: 'block'; seat: Seat; blocks: { blocker: CardRef; attacker: CardRef }[] }
/** Damage to a permanent from an effect / from combat. */
| { kind: 'effectDamage'; source: CardRef; target: CardRef; amount: number }
| { kind: 'combatDamage'; source: CardRef; target: CardRef; amount: number }
/** Damage or life loss to a player. source null = fatigue. */
| { kind: 'playerDamage'; source: CardRef | null; seat: Seat; amount: number; life: number; combat: boolean }
| { kind: 'lifeGain'; source: CardRef; seat: Seat; amount: number; life: number }
| { kind: 'destroyed'; card: CardRef; owner: Seat }
| { kind: 'bounced'; card: CardRef; owner: Seat }
| { kind: 'discard'; seat: Seat; card: CardRef }
| { kind: 'fatigue'; seat: Seat; amount: number }
| { kind: 'concede'; seat: Seat }
| { kind: 'timeout'; seat: Seat }
| { kind: 'gameOver'; winner: Seat | null; reason: EndReason; life: [number, number] }
);
export type LogKind = LogEvent['kind'];
// ---------------------------------------------------------------------------
// Views (what one seat may see; bots and UI get only this)
// ---------------------------------------------------------------------------
export interface PermanentView {
uid: string;
owner: Seat;
controller: Seat;
card: DuelCard;
tapped: boolean;
sick: boolean;
damage: number;
counters: number;
attachedTo?: string;
/** Current values after counters, pumps, statics, Connected and Trending. */
power: number;
toughness: number;
keywords: Keyword[];
/** Active Connected bonus, if any (for the card face). */
connected?: { with: string; tier: ConnectedTier; via: string; bonus: number };
}
export interface SideView {
seat: Seat;
life: number;
citations: number;
maxCitations: number;
handSize: number;
librarySize: number;
graveyard: CardInstance[];
bankSeconds: number;
ready: boolean;
mulligansTaken: number;
}
export interface PlayerView {
engine: 'duel';
seat: Seat;
turn: number;
active: Seat;
phase: Phase;
/** Seat that must act now (null when over). */
toAct: Seat | null;
you: SideView & { hand: CardInstance[] };
opponent: SideView;
battlefield: PermanentView[];
combat: CombatState;
result: DuelResult | null;
version: number;
rules: DuelRuleset;
}
+45 -8
View File
@@ -11,7 +11,17 @@
*/
import { z } from 'zod';
export const MODE_SCHEMA_VERSION = 'wikideck.mode/1' as const;
export const MODE_SCHEMA_VERSION = 'wikideck.mode/2' as const;
/** Night 1 schema: rejected with a clear message (BRIEF "Modes": versioned schema). */
export const LEGACY_MODE_SCHEMA_VERSIONS: readonly string[] = ['wikideck.mode/1'];
/**
* Which rules engine a mode runs on. `editwar` is the Night 1 simultaneous-reveal game
* (shared/game); `duel` is the Night 2 Magic-style duel (shared/duel). A host may not
* register every engine; modes for an engine it lacks fail at startup.
*/
export const ENGINE_IDS = ['editwar', 'duel'] as const;
export const EngineIdSchema = z.enum(ENGINE_IDS);
export type EngineId = z.infer<typeof EngineIdSchema>;
/** Upper bound on the JSON size of one mode document, before parsing. */
export const MAX_MODE_BYTES = 8 * 1024;
/** Upper bound on modes one node may publish (and that discovery accepts from one peer). */
@@ -60,14 +70,25 @@ export type CardMapping = z.infer<typeof CardMappingSchema>;
/** Where match decks come from. Matches never move or burn NFTs, whatever the policy. */
export const DeckPolicySchema = z.discriminatedUnion('kind', [
/** Each player brings a deck (starter deck or own cards, validated by the engine). */
z.object({ kind: z.literal('constructed'), allowStarter: z.boolean().default(true) }).strict(),
/** Host-seeded starter decks only: everyone gets the engine's `starterDeck(seed)`. */
/**
* Each player brings exactly `deckSize` NFTs they own (token ids), verified server-side
* against the chain and built from their blocks. Requires an eom.dev account seat.
*/
z.object({ kind: z.literal('constructed'),
/** Confirmations each card's mint (or last transfer) needs; rated modes should use ≥ 3. */
minConfirmations: z.number().int().min(0).max(100).default(1),
}).strict(),
/** Host-seeded starter decks only (Edit War engine only: the duel has no loaners). */
z.object({ kind: z.literal('starter') }).strict(),
/** Snake draft from a host-seeded pool of non-NFT preview cards. */
/** Snake draft from a host-seeded pool. */
z.object({ kind: z.literal('draft'),
/**
* `preview`: the engine's non-NFT preview cards (Edit War only).
* `collections`: both players' owned cards, used for this match only; nothing moves on-chain.
*/
source: z.enum(['preview', 'collections']).default('preview'),
/** Cards in the shared pool; must be at least 2 × the ruleset's deck size. */
poolSize: z.number().int().min(8).max(64).default(30),
poolSize: z.number().int().min(8).max(200).default(30),
/** Seconds per pick before the host auto-picks the first card. */
pickSeconds: z.number().int().min(5).max(120).default(30),
}).strict(),
@@ -81,6 +102,10 @@ export const ModeLimitsSchema = z.object({
turnSeconds: z.number().int().min(10).max(600).default(90),
/** Lobbies with no opponent expire after this many minutes. */
lobbyMinutes: z.number().int().min(1).max(120).default(15),
/** Ranked: Elo moves only when both seats are eom.dev accounts. */
rated: z.boolean().default(false),
/** Seats must be eom.dev accounts (always true for constructed and collection-draft modes). */
accountsOnly: z.boolean().default(false),
}).strict();
export type ModeLimits = z.infer<typeof ModeLimitsSchema>;
@@ -93,11 +118,13 @@ export const ModeSchema = z.object({
name: text(48),
description: text(400),
tags: z.array(slug).max(5).default([]),
/** The rules engine this mode runs on. Required: there is no safe default across engines. */
engine: EngineIdSchema,
/** Overrides on top of the engine's DEFAULT_RULESET. */
rules: RuleOverridesSchema.default({}),
cards: CardMappingSchema.default({ preset: 'standard' }),
decks: DeckPolicySchema.default({ kind: 'constructed', allowStarter: true }),
limits: ModeLimitsSchema.default({ maxConcurrentMatches: 32, turnSeconds: 90, lobbyMinutes: 15 }),
decks: DeckPolicySchema.default({ kind: 'constructed', minConfirmations: 1 }),
limits: ModeLimitsSchema.default({ maxConcurrentMatches: 32, turnSeconds: 90, lobbyMinutes: 15, rated: false, accountsOnly: false }),
}).strict();
export type ModeDocument = z.infer<typeof ModeSchema>;
export type ModeInput = z.input<typeof ModeSchema>;
@@ -145,6 +172,10 @@ export function parseModeJson(json: string): ModeDocument {
}
export function parseMode(value: unknown): ModeDocument {
assertInertKeys(value);
const schema = (value as { schema?: unknown } | null)?.schema;
if (typeof schema === 'string' && LEGACY_MODE_SCHEMA_VERSIONS.includes(schema)) {
throw new Error(`Mode schema ${schema} (Night 1) is no longer accepted: use ${MODE_SCHEMA_VERSION} with an "engine" field (see docs/game/HOSTING.md)`);
}
const mode = ModeSchema.parse(value);
if (byteLength(JSON.stringify(mode)) > MAX_MODE_BYTES) throw new Error(`Mode document exceeds ${MAX_MODE_BYTES} bytes`);
return mode;
@@ -163,6 +194,12 @@ export function parseModeList(json: string): { list: ModeList; rejected: number
return { list: ModeListSchema.parse({ ...raw, modes }), rejected };
}
/** Whether a mode's seats must be eom.dev accounts (owned cards always need one). */
export function requiresAccount(mode: ModeDocument): boolean {
return mode.limits.accountsOnly || mode.decks.kind === 'constructed' ||
(mode.decks.kind === 'draft' && mode.decks.source === 'collections');
}
/** Stable key for a mode on a host: `<origin>#<id>@<version>`. */
export function modeKey(origin: string, mode: Pick<ModeDocument, 'id' | 'version'>): string {
return `${origin}#${mode.id}@${mode.version}`;
+6 -2
View File
@@ -10,7 +10,7 @@ import { Card, samples, imageCredit, type CardData } from './Card.tsx';
import { WalletPanel } from './WalletPanel.tsx';
import { useModalFocus } from './useModalFocus.ts';
import { ThemePicker } from './ThemePicker.tsx';
import { LoginButton } from './auth/LoginButton.tsx';
import { LoginButton, useAccount } from './auth/LoginButton.tsx';
import { TradeDesk } from './TradeDesk.tsx';
import { IS_MAINNET, NETWORK_GENESIS_TIME, NETWORK_LABEL } from '../shared/network.ts';
import { StateClient } from '../shared/rpc-client.ts';
@@ -48,6 +48,7 @@ function transferProblem(state: TestnetSnapshot, card: CardData, address: string
export default function App() {
const [view, setView] = useState<View>('Discover');
const linkedAccount = useAccount();
const [wallet, setWallet] = useState<Wallet>();
const [snapshot, setSnapshot] = useState<TestnetSnapshot>();
const [rpcAvailable, setRpcAvailable] = useState(false);
@@ -127,7 +128,10 @@ export default function App() {
} catch (e) { setTransferError(message(e)); }
finally { transferInFlight.current = false; setTransferBusy(false); }
};
const owned = snapshot?.blocks.filter(b => wallet && testnetOwnerOf(snapshot, b.tokenId) === wallet.address) ?? [];
// Every canonical card owned by this browser's wallet or any wallet linked to the eom.dev account (#57).
// The full canonical chain is paged in by StateClient, so nothing is capped at 128 blocks.
const mine = new Set([wallet?.address, ...(linkedAccount?.wallets ?? []).map(w => w.address)].filter(Boolean));
const owned = snapshot?.blocks.filter(b => mine.has(testnetOwnerOf(snapshot, b.tokenId) ?? '')) ?? [];
const visibleCards = view === 'My collection' ? owned.map(asCard)
: snapshot?.blocks.length ? [...snapshot.blocks].reverse().slice(0, 12).map(asCard) : samples;
const filtered = visibleCards.filter(c => (category === 'All cards' || c.article.category === category) &&
+255
View File
@@ -0,0 +1,255 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { classify } from '../shared/duel/classify.ts';
import {
derive, connectedTier, figureBody, flavorFor, portalFor, DERIVE_RULES, DERIVE_VERSION,
type DuelCard, type CardProfile,
} from '../shared/duel/derive.ts';
import { deriveSample, sampleInputs, type SampleCard } from '../shared/duel/sample.ts';
import { rulesTextFor, rulesTextWithReminders, typeLine } from '../shared/duel/text.ts';
const root = new URL('../', import.meta.url);
const SAMPLE = (JSON.parse(readFileSync(new URL('docs/game/card-sample.json', root), 'utf8')) as { cards: SampleCard[] }).cards;
const FIXTURE = JSON.parse(readFileSync(new URL('docs/game/duel-card-sample.json', root), 'utf8')) as { deriveVersion: string; cards: DuelCard[] };
const CARDS = deriveSample(SAMPLE);
const byTitle = (title: string) => {
const card = CARDS.find(c => c.title === title);
assert.ok(card, `missing sample card ${title}`);
return card;
};
const profile = (overrides: Partial<CardProfile>): CardProfile =>
({ wikidataId: null, description: null, categories: [], instanceOf: [], ...overrides });
test('every sample card gets a type, and nothing falls through to the Doctrine residual', () => {
assert.equal(CARDS.length, 236);
const fallback = CARDS.filter(c => c.typedBy === 'fallback');
assert.deepEqual(fallback.map(c => c.title), []);
const share = (t: string) => CARDS.filter(c => c.type === t).length / CARDS.length;
// data §1 distribution, ±4 points
assert.ok(Math.abs(share('Figure') - 0.364) < 0.04);
assert.ok(Math.abs(share('Location') - 0.331) < 0.04);
assert.ok(share('Event') > 0.05 && share('Doctrine') > 0.05 && share('Institution') > 0.1);
});
test('"human settlement" villages are Locations, not Figures (the \\bhuman\\b bug)', () => {
for (const title of ['Buky', 'Lunugala', 'Žižki', 'Laukhella']) assert.equal(byTitle(title).type, 'Location', title);
assert.equal(classify(profile({ instanceOf: [{ id: 'Q999', label: 'human settlement' }] })).type, 'Location');
assert.equal(classify(profile({ instanceOf: [{ id: 'Q999', label: 'human' }] })).type, 'Figure');
});
test('rule order: elections beat "municipal", aspects beat "region", governing bodies are Institutions', () => {
assert.equal(byTitle('2023 Seville municipal election').type, 'Event');
assert.equal(byTitle('Corruption in Kazakhstan').type, 'Doctrine');
assert.equal(byTitle('Diocese of Mindelo').type, 'Institution');
assert.equal(byTitle('Region Östergötland').type, 'Institution');
assert.equal(byTitle('Lewis and Elizabeth Bolton House').type, 'Location');
});
test('P279 anchors and labels classify items without P31; categories then description are fallbacks', () => {
assert.deepEqual(classify(profile({ subclassOf: [{ id: 'Q1', label: 'algebraic structure' }] })),
{ type: 'Doctrine', source: 'p279', matched: 'algebraic structure' });
assert.equal(classify(profile({ subclassOf: [{ id: 'Q43229', label: 'x' }] })).source, 'p279-qid');
assert.equal(classify(profile({ categories: ['Villages in Somewhere', 'Somewhere geography stubs'] })).type, 'Location');
assert.equal(classify(profile({ description: 'Species of beetle' })).type, 'Figure');
assert.deepEqual(classify(profile({})), { type: 'Doctrine', source: 'fallback', matched: '' });
});
test('derive is deterministic and the committed fixture is current', () => {
assert.deepEqual(deriveSample(SAMPLE), CARDS);
assert.equal(FIXTURE.deriveVersion, DERIVE_VERSION);
assert.deepEqual(FIXTURE.cards, CARDS, 'run: node --experimental-strip-types scripts/duel-card-sample.ts');
const { chain, profile: p } = sampleInputs(SAMPLE[0]);
const frozen = structuredClone(p);
derive(chain, p);
assert.deepEqual(p, frozen, 'derive must not mutate the profile');
});
test('costs, bodies and keyword caps stay in range', () => {
for (const c of CARDS) {
assert.ok(c.keywords.length <= 2, c.title);
if (c.type === 'Figure') {
assert.ok(c.cost >= 1 && c.cost <= 6, c.title);
const taxed = c.keywords.filter(k => DERIVE_RULES.taxedKeywords.includes(k)).length;
assert.ok(c.connect.qid === undefined || /^Q\d+$/.test(c.connect.qid));
assert.equal(c.power! + c.toughness!, DERIVE_RULES.bodyBudget[c.cost] - taxed, c.title);
assert.ok(c.power! >= 1 && c.toughness! >= 1, c.title);
} else if (c.type === 'Location') {
assert.ok(c.cost >= 1 && c.cost <= 3, c.title);
assert.equal(c.power, 0);
assert.ok(c.toughness! >= 1 && c.toughness! <= 4);
assert.deepEqual(c.keywords, []);
} else {
assert.equal(c.power, null);
assert.ok(c.effects.length > 0, c.title);
}
}
});
test('no famous Figure is strictly better than another Figure of no lower cost with the same keywords (data §2)', () => {
const figures = CARDS.filter(c => c.type === 'Figure');
const dominated: string[] = [];
for (const x of figures) for (const y of figures) {
if (x === y || x.keywords.join() !== y.keywords.join()) continue;
if (x.cost <= y.cost && x.power! >= y.power! && x.toughness! >= y.toughness!
&& (x.cost < y.cost || x.power! > y.power! || x.toughness! > y.toughness!)) dominated.push(`${x.title} > ${y.title}`);
}
assert.deepEqual(dominated, []);
// Fame buys size, not efficiency: (P+T)/cost does not rise with cost.
const eff = (cost: number) => { const g = figures.filter(c => c.cost === cost); return g.reduce((s, c) => s + (c.power! + c.toughness!) / cost, 0) / g.length; };
for (let cost = 2; cost <= 6; cost++) assert.ok(eff(cost) < eff(1) && eff(cost) <= 2, `cost ${cost}: ${eff(cost)}`);
});
test('figureBody: keyword tax comes off the budget first, then attention vs depth splits it', () => {
assert.deepEqual(figureBody(4, { attention: 90, depth: 10, reach: 0 }, []), { power: 7, toughness: 1, keywords: [] });
assert.deepEqual(figureBody(4, { attention: 10, depth: 90, reach: 0 }, ['Featured']), { power: 1, toughness: 6, keywords: ['Featured'] });
assert.deepEqual(figureBody(1, { attention: 50, depth: 50, reach: 0 }, ['Legacy', 'Stub', 'Local']),
{ power: 1, toughness: 1, keywords: ['Legacy', 'Stub'] });
assert.deepEqual(figureBody(1, { attention: 50, depth: 50, reach: 0 }, ['Protected', 'Legacy', 'Stub']),
{ power: 1, toughness: 1, keywords: ['Protected', 'Stub'] });
assert.deepEqual(figureBody(3, { attention: null, depth: 50, reach: 0 }, ['Translated', 'Stub', 'Local']),
{ power: 3, toughness: 3, keywords: ['Translated', 'Stub'] });
});
test('keyword bands: Multilingual and Translated never both; Figures only', () => {
for (const c of CARDS) {
assert.ok(!(c.keywords.includes('Multilingual') && c.keywords.includes('Translated')), c.title);
if (c.type !== 'Figure') assert.deepEqual(c.keywords, [], c.title);
}
});
test('DUEL_DESIGN §9 worked examples (golden)', () => {
const show = (title: string) => {
const c = byTitle(title);
const body = c.type === 'Figure' || c.type === 'Location' ? ` · ${c.power}/${c.toughness}` : '';
return `${c.cost} · ${typeLine(c)}${body} · ${c.rulesText.replace(/\n/g, ' ')} · ${c.flavor}`;
};
const golden: Record<string, string> = {
'Marc Fesneau': '5 · Figure — Society · 5/4 · Protected. · French politician (born 1971)',
'Tom Ewell': '6 · Figure — Arts · 5/5 · Featured, Legacy. · American actor (1909–1994)',
'Zbyszek Godlewski': '5 · Figure — History · 6/3 · Legacy, Translated. · Polish protester (1952–1970)',
"Pallas's cat": '6 · Figure — Earth · 5/5 · Featured, Multilingual. · Species of small wild cat',
'Dichromorpha viridis': '2 · Figure — Earth · 3/1 · Stub. · Species of grasshopper',
Monoid: '6 · Doctrine — Science · Attach to target Figure you control. It gets +3/+3 and has Well-sourced. · '
+ 'Algebraic structure with an associative operation and an identity element',
'Heart rot': '5 · Doctrine — Science · Attach to target Figure. It gets −3/−3. · Fungal disease of trees',
"April 2021 nor'easter": "3 · Event — Earth · Deal 1 damage to each Figure and each Location. · Slow-moving nor'easter in April 2021",
// §9 says History; the Portal score is Society (protest/riot categories outnumber "war").
'2025 Tehreek-e-Labbaik Pakistan protests': '5 · Event — Society · Deal 4 damage to target Figure or Location. · Gaza war protests in Pakistan',
'1954 Gold Coast general election': '3 · Event — Society · Create two 1/1 Society Figure tokens named Elected Member. · ',
// §9 says History; "mosque" hits (P31, description, 2 categories) outscore 15th-century + Sultanate.
'Pathrail Mosque': '2 · Location — Society · 0/3 · Territory. Garrison 0/3. · Mosque in Faridpur, Bangladesh',
'Tatsunoko Production': '6 · Institution — Arts · At the start of your turn, if you control fewer than 3 tokens, '
+ 'create a 1/1 Figure token named Staff Member. · Japanese animation studio',
'Agda (programming language)': '6 · Doctrine — Science · Attach to target Figure you control. It gets +3/+3. '
+ 'Whenever it deals combat damage to a player, draw a card. · Functional programming language',
};
for (const [title, want] of Object.entries(golden)) assert.equal(show(title), want, title);
assert.equal(rulesTextWithReminders(byTitle('Tom Ewell')),
'Featured. (Can\'t be blocked except by Featured, Translated or Multilingual Figures.)\nLegacy. (When this is destroyed, draw a card.)');
assert.equal(rulesTextWithReminders(byTitle('Pathrail Mosque')),
'Territory. (Your Citation maximum is 1 higher while you control this, to at most +2 from Territory.)\n'
+ 'Garrison 0/3. (This can block like a Figure with power 0. It can\'t attack.)');
});
test('rules text uses only card numbers and fixed words: no title, description or category text leaks in', () => {
for (const c of CARDS) {
const stripped = c.rulesText.replace(/Protected|Featured|Translated|Legacy|Stub|Well-sourced|Multilingual|Local/g, '');
assert.ok(!stripped.includes(c.title), c.title);
assert.match(c.rulesText, /^[A-Za-z0-9 ,.;:'()+−/\n—-]*$/, c.title);
assert.equal(rulesTextFor(c), c.rulesText);
}
});
test('flavour is the first sentence of the extract, else the description', () => {
assert.equal(flavorFor('Tom Ewell (born Samuel Yewell Tompkins; April 29, 1909 – September 12, 1994) was an American actor. He won a Tony.', null),
'Tom Ewell (born Samuel Yewell Tompkins; April 29, 1909 – September 12, 1994) was an American actor.');
assert.equal(flavorFor('J. R. R. Tolkien was an English writer. He wrote.', null), 'J. R. R. Tolkien was an English writer.');
assert.equal(flavorFor('The U.S. Route 66 is a road in the U.S. state of Arizona. More.', null), 'The U.S. Route 66 is a road in the U.S. state of Arizona.');
assert.equal(flavorFor('No terminal punctuation', 'desc'), 'No terminal punctuation');
assert.equal(flavorFor(' ', 'Species of grasshopper'), 'Species of grasshopper');
assert.equal(byTitle('Dichromorpha viridis').flavor, 'Species of grasshopper');
});
test('Portals: keyword hits decide, ties go to the type default, no hits is Neutral', () => {
assert.equal(portalFor(profile({ description: 'Sultan of Aceh', categories: ['16th-century monarchs in Asia'] }), 'Figure'), 'History');
assert.equal(portalFor(profile({ description: 'mathematician and politician' }), 'Figure'), 'Society');
assert.equal(portalFor(profile({ description: 'zzz' }), 'Figure'), 'Neutral');
const portals = new Set(CARDS.map(c => c.portal));
for (const p of ['Arts', 'Earth', 'History', 'Science', 'Society']) assert.ok(portals.has(p as DuelCard['portal']), p);
});
test('Connected: Linked beats Compatriot beats Contemporary beats Kin; a card is never connected to itself', () => {
const base = (id: string, pageId: number, connect: Partial<DuelCard['connect']>, type: DuelCard['type'] = 'Event'): DuelCard =>
({ ...byTitle('Tom Ewell'), cardId: id, pageId, type, connect: { countries: [], centuries: [], links: [], p31: [], cites: [], ...connect } });
const a = base('a', 1, { links: [2], countries: ['France'], centuries: [20], p31: ['Q1'], qid: 'Q100' }, 'Figure');
assert.equal(connectedTier(a, base('g', 7, { cites: ['Q100'] })), 'Linked');
assert.equal(connectedTier(a, base('h', 8, { centuries: [20] }, 'Figure')), null, 'Contemporary needs different types');
assert.equal(connectedTier(a, base('b', 2, { countries: ['France'] })), 'Linked');
assert.equal(connectedTier(base('b', 2, { links: [1] }), a), 'Linked');
assert.equal(connectedTier(a, base('c', 3, { countries: ['France'], centuries: [20] })), 'Compatriot');
assert.equal(connectedTier(a, base('d', 4, { centuries: [20] })), 'Contemporary');
assert.equal(connectedTier(a, base('e', 5, { p31: ['Q1'] })), 'Kin');
assert.equal(connectedTier(a, base('f', 6, {})), null);
assert.equal(connectedTier(a, a), null);
assert.equal(connectedTier(a, base('c', 3, { centuries: [20] }), ['Linked', 'Compatriot']), null);
});
test('Connected fires in a plausible share of sample pairs (BRIEF target 15–30%, tuned in the sim)', () => {
let hits = 0, pairs = 0;
for (let i = 0; i < CARDS.length; i++) for (let j = i + 1; j < CARDS.length; j++) {
pairs++; if (connectedTier(CARDS[i], CARDS[j])) hits++;
}
const rate = hits / pairs;
assert.ok(rate > 0.1 && rate < 0.4, `rate ${rate}`);
});
test('Doctrines use the engine encoding: attach picks the Figure, a static pump on `attached` carries ±k (DUEL_API)', () => {
for (const c of CARDS.filter(x => x.type === 'Doctrine')) {
assert.equal(c.effects[0].op, 'attach', c.title);
const buff = c.effects[1];
assert.equal(buff.trigger, 'static', c.title);
assert.equal(buff.op, 'pump');
assert.equal(buff.target, 'attached');
const magnitude = c.basis.magnitude;
const sign = c.subtype === 'pathology' ? -1 : 1;
assert.deepEqual([buff.power, buff.toughness], [sign * magnitude, sign * magnitude], c.title);
assert.equal(c.effects[0].target, c.subtype === 'pathology' ? 'figure' : 'ownFigure');
}
assert.deepEqual(byTitle('Heart rot').effects.map(e => [e.trigger, e.op, e.target, e.power ?? null]),
[['onPlay', 'attach', 'figure', null], ['static', 'pump', 'attached', -3]]);
});
test('chain-only fallback: an empty profile still types from the on-chain title, category and extract', () => {
const empty = profile({});
const chain = (title: string, extract = '', category?: string) => ({ title, extract, ...(category ? { category } : {}) });
assert.equal(classify(empty, chain('Tom Ewell', 'Tom Ewell (born Samuel Yewell Tompkins; April 29, 1909 – September 12, 1994) was an American actor.')).type, 'Figure');
assert.equal(classify(empty, chain('Buky', 'Buky is a village in Cherkasy Oblast, Ukraine.')).type, 'Location');
assert.equal(classify(empty, chain('Heart rot', 'Heart rot is a fungal disease of trees.')).type, 'Doctrine');
assert.equal(classify(empty, chain('1954 Gold Coast general election')).source, 'title');
assert.equal(classify(empty, chain('1954 Gold Coast general election')).type, 'Event');
assert.equal(classify(empty, chain('Zzyzx', '', 'People')).type, 'Figure');
assert.equal(classify(empty, chain('Zzyzx', '', 'Culture')).source, 'fallback');
assert.equal(classify(empty).source, 'fallback', 'no chain hints: unchanged');
// derive() passes chain.article through, so hosts need no extra argument.
const { chain: c } = sampleInputs(SAMPLE.find(s => s.title === '1954 Gold Coast general election')!);
const card = derive(c, empty);
assert.deepEqual([card.type, card.typedBy, card.subtype], ['Event', 'title', 'election']);
});
test('chain-only typing over the sample agrees with the full classifier on most cards', () => {
// The sample has no extracts and tests can't fetch, so this uses a lead-sentence proxy:
// "<Title> is a <description>." (Wikipedia leads usually open this way). Labelled as a proxy.
const empty = profile({});
let agree = 0; const types: Record<string, number> = {};
for (const s of SAMPLE) {
const extract = s.description ? `${s.title} is a ${s.description[0].toLowerCase()}${s.description.slice(1)}.` : '';
const t = classify(empty, { title: s.title, extract, ...(s.legacyCategory ? { category: s.legacyCategory } : {}) }).type;
types[t] = (types[t] ?? 0) + 1;
if (t === classify(s).type) agree++;
}
assert.ok(agree / SAMPLE.length >= 0.8, `agree ${agree}/${SAMPLE.length}`);
assert.ok(types.Figure / SAMPLE.length > 0.3 && types.Figure / SAMPLE.length < 0.42, JSON.stringify(types));
assert.ok(types.Location / SAMPLE.length > 0.22 && types.Location / SAMPLE.length < 0.38, JSON.stringify(types));
assert.ok(types.Doctrine / SAMPLE.length < 0.25, JSON.stringify(types));
});
+71
View File
@@ -0,0 +1,71 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
canonicalProfile, classIdsOf, profileFromSources, wikidataEntityParams, wikidataLabelParams, type WikidataEntity,
} from '../shared/duel/profile.ts';
import { classify } from '../shared/duel/classify.ts';
import { derive } from '../shared/duel/derive.ts';
const item = (id: string) => ({ rank: 'normal', mainsnak: { snaktype: 'value', datavalue: { type: 'wikibase-entityid', value: { id } } } });
const time = (t: string) => ({ rank: 'normal', mainsnak: { snaktype: 'value', datavalue: { type: 'time', value: { time: t } } } });
const EWELL: WikidataEntity = {
id: 'Q1351340',
claims: {
P31: [item('Q5')],
P27: [item('Q30')],
P569: [time('+1909-04-29T00:00:00Z')],
P570: [time('+1994-09-12T00:00:00Z')],
P19: [item('Q1018580')],
P106: [item('Q33999')],
P17: [{ rank: 'deprecated', mainsnak: { snaktype: 'value', datavalue: { value: { id: 'Q999' } } } }],
},
};
const ENRICH = { description: 'American actor (1909–1994)', wikidataId: 'Q1351340', categories: ['1994 deaths', 'American male actors'], revisionId: 42 };
test('profileFromSources reads P31, countries, years, death and cited items; ignores deprecated claims', () => {
const p = profileFromSources({ enrichment: ENRICH, entity: EWELL, labels: { Q5: 'human' }, links: [9, 3, 9] });
assert.deepEqual(p, {
wikidataId: 'Q1351340', description: 'American actor (1909–1994)', categories: ['1994 deaths', 'American male actors'],
instanceOf: [{ id: 'Q5', label: 'human' }], fetchedRevisionId: 42,
countries: ['Q30'], years: [1909, 1994], died: true, cites: ['Q1018580', 'Q30'], links: [3, 9],
});
assert.equal(classify(p).type, 'Figure');
});
test('BCE years are negative; malformed and novalue claims are skipped without throwing', () => {
const entity: WikidataEntity = { claims: {
P571: [time('-0753-04-21T00:00:00Z'), { mainsnak: { snaktype: 'novalue' } }, { mainsnak: { snaktype: 'value', datavalue: { value: 'junk' } } }],
P31: [item('not-a-qid'), item('Q515')],
} };
const p = profileFromSources({ enrichment: { ...ENRICH, categories: [] }, entity });
assert.deepEqual(p.years, [-753]);
assert.deepEqual(p.instanceOf, [{ id: 'Q515', label: 'Q515' }]);
assert.equal(classify(p).type, 'Location', 'Q-id anchors classify even without labels');
assert.equal(profileFromSources({ enrichment: ENRICH, entity: null }).instanceOf.length, 0);
});
test('without a Wikidata item the profile still classifies from categories and description', () => {
const p = profileFromSources({ enrichment: { description: 'Village in Poland', wikidataId: null, categories: ['Villages in Gmina X'], revisionId: 1 } });
assert.equal(classify(p).type, 'Location');
});
test('request parameters: claims-only entities, English labels, ≤ 50 sorted ids', () => {
assert.deepEqual(wikidataEntityParams(['Q5', 'Q1']), { action: 'wbgetentities', ids: 'Q1|Q5', props: 'claims', format: 'json', formatversion: '2' });
assert.equal(wikidataLabelParams(['Q5']).props, 'labels');
assert.throws(() => wikidataEntityParams([]), RangeError);
assert.throws(() => wikidataLabelParams(Array.from({ length: 51 }, (_, i) => `Q${i + 1}`)), RangeError);
assert.deepEqual(classIdsOf({ claims: { P31: [item('Q5')], P279: [item('Q2'), item('Q5')] } }), ['Q2', 'Q5']);
});
test('canonicalProfile is key-order independent, and the frozen profile derives the same card twice', () => {
const p = profileFromSources({ enrichment: ENRICH, entity: EWELL, labels: { Q5: 'human' } });
const shuffled = Object.fromEntries(Object.entries(p).reverse()) as typeof p;
assert.equal(canonicalProfile(shuffled), canonicalProfile(p));
const chain = { tokenId: 'ab'.repeat(32), article: { pageId: 1, title: 'Tom Ewell', extract: 'Tom Ewell was an American actor. More.', revisionId: 42 },
statsSnapshot: { pageBytes: 9000, languageCount: 30, stats: { attention: 60, depth: 70, reach: 50 } } };
const thawed = JSON.parse(canonicalProfile(p));
assert.deepEqual(derive(chain, thawed), derive(chain, p));
assert.equal(derive(chain, p).flavor, 'Tom Ewell was an American actor.');
assert.ok(derive(chain, p).keywords.includes('Legacy'));
});
+40
View File
@@ -0,0 +1,40 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { DEFAULT_DUEL_RULESET, mergeDuelRuleset, parseDuelRuleset, CARD_TYPES, KEYWORDS } from '../shared/duel/index.ts';
import { DEFAULT_RULESET } from '../shared/game/index.ts';
test('duel default ruleset matches the BRIEF', () => {
const rules = parseDuelRuleset({ ...DEFAULT_DUEL_RULESET });
assert.equal(rules.deckSize, 40);
assert.equal(rules.startingLife, 20);
assert.equal(rules.maxCitations, 10);
assert.equal(rules.handSize, 7);
assert.equal(rules.openingHand, 7);
assert.equal(rules.mulligans, 1);
assert.equal(rules.libraryEmpty, 'lose');
assert.equal(rules.firstPlayerDraws, false);
assert.equal(rules.turnSeconds, 60);
assert.equal(rules.bankSeconds, 300);
assert.equal(rules.turnCap, null);
assert.equal(rules.territoryCap, 2);
});
test('duel ruleset merges overrides and rejects unknown keys', () => {
assert.equal(mergeDuelRuleset({ deckSize: 20 }).deckSize, 20);
assert.equal(mergeDuelRuleset({ turnCap: 30 }).turnCap, 30);
assert.throws(() => mergeDuelRuleset({ topicCount: 3 }));
assert.throws(() => mergeDuelRuleset({ libraryEmpty: 'shrug' }));
assert.throws(() => mergeDuelRuleset({ deckSize: 0 }));
assert.throws(() => mergeDuelRuleset([1]));
});
test('Night 1 Edit War rulesets are rejected cleanly', () => {
assert.throws(() => parseDuelRuleset(DEFAULT_RULESET));
});
test('card types and keywords are the BRIEF set', () => {
assert.deepEqual([...CARD_TYPES], ['Figure', 'Location', 'Event', 'Institution', 'Doctrine']);
for (const k of ['Protected', 'Featured', 'Translated', 'Legacy', 'Stub', 'Well-sourced', 'Multilingual', 'Local']) {
assert.ok((KEYWORDS as readonly string[]).includes(k), k);
}
});
+50
View File
@@ -0,0 +1,50 @@
{
"log": [
"Turn 1. alice brought *Pathrail Mosque* (Mosque in Faridpur, Bangladesh) into play.[1]",
"Turn 2. bob added *1954 Gold Coast general election* to their hand.[2]",
"Turn 3. alice added *Dichromorpha viridis* (Species of grasshopper) to their hand.[3] *Dichromorpha viridis* entered play under alice.",
"Turn 4. bob added a card to their hand. *1954 Gold Coast general election* was cited by bob. *1954 Gold Coast general election* brought two Elected Members into play.",
"Turn 5. alice drew one card. alice sent *Dichromorpha viridis* (4/2) into combat. bob lost 4 Notability (16 remaining).",
"Turn 6. bob drew one card. bob cited *April 2021 nor'easter* (Slow-moving nor'easter in April 2021).[4] *Dichromorpha viridis* took 1 damage from *April 2021 nor'easter*. *April 2021 nor'easter* dealt 1 damage to *Pathrail Mosque*. *Dichromorpha viridis* was removed from play.",
"Turn 7. alice added a card to their hand. *Zbyszek Godlewski* (Polish protester, 1952–1970) entered play under alice.[5]",
"Turn 8. bob added a card to their hand. *Marc Fesneau* (French politician, born 1971) entered play under bob.[6]",
"Turn 9. alice drew one card. *Zbyszek Godlewski* (6/3) attacked. *Zbyszek Godlewski* was blocked by *Marc Fesneau* (5/4). *Zbyszek Godlewski* was removed from play. *Marc Fesneau* was removed from play. alice drew one card.",
"Turn 10. bob added a card to their hand. bob discarded *Agda (programming language)* (Functional programming language).[7] bob deployed *Pallas's cat* (Species of small wild cat).[8]",
"Turn 11. alice drew one card. alice deployed *Tom Ewell* (American actor, 1909–1994).[9]",
"Turn 12. bob added a card to their hand. bob attached *Heart rot* (Fungal disease of trees) to *Tom Ewell* (2/2).[10] *Pallas's cat* (5/5) advanced on alice. *Pallas's cat* dealt 5 damage to alice, leaving 15 Notability.",
"Turn 13. alice added a card to their hand. *Monoid* (Algebraic structure with an associative operation and an identity element) was adopted by *Tom Ewell*, which became a 5/5.[11] alice sent *Tom Ewell* (5/5) into combat. bob lost 5 Notability (11 remaining).",
"Turn 14. bob drew one card. bob invoked *2025 Tehreek-e-Labbaik Pakistan protests* (Gaza war protests in Pakistan).[12] *2025 Tehreek-e-Labbaik Pakistan protests* inflicted 3 damage on *Tom Ewell*. bob brought *Tatsunoko Production* (Japanese animation studio) into play.[13] bob sent *Pallas's cat* (5/5) into combat. alice's Notability fell to 10.",
"Turn 15. alice drew a card. *Tom Ewell* (5/5) advanced on bob. bob lost 5 Notability (6 remaining).",
"Turn 16. bob drew a card. bob sent *Pallas's cat* (5/5) into combat. alice lost 5 Notability (5 remaining).",
"Turn 17. alice drew one card. *Tom Ewell* (5/5) advanced on bob. bob's Notability fell to 1.",
"Turn 18. bob drew one card. bob sent *Pallas's cat* (5/5) into combat. alice lost 5 Notability (0 remaining). alice was reduced to 0 Notability. bob won."
],
"lead": "The **Battle of Pathrail Mosque (2026)** was a WikiDeck engagement fought on 17 November 2026 between the forces of alice and bob. It lasted eighteen turns and ended in a Pyrrhic victory for bob.[1] Contemporary accounts note the deployment of *Dichromorpha viridis* (Species of grasshopper) in the third turn.[2]",
"sections": [
{
"heading": "Background",
"paragraphs": [
"Arts, Earth, History, Science and Society were equally represented in the force of alice (one card each, of five cards played).",
"Society was the largest Portal in the force of bob (three of seven cards played)."
]
},
{
"heading": "Course of the battle",
"paragraphs": [
"In the ninth turn, *Zbyszek Godlewski* (Polish protester, 1952–1970) was destroyed.[3] *Marc Fesneau* (French politician, born 1971) was removed from play.[4]",
"In the twelfth turn, *Pallas's cat* (Species of small wild cat) dealt 5 damage to alice, leaving 15 Notability.[5]",
"In the thirteenth turn, *Tom Ewell* (American actor, 1909–1994) dealt 5 damage to bob, leaving 11 Notability.[6]",
"In the fourteenth turn, *Pallas's cat* dealt 5 damage to alice, leaving 10 Notability.",
"In the fifteenth turn, *Tom Ewell* dealt 5 damage to bob, leaving 6 Notability.",
"In the sixteenth turn, *Pallas's cat* dealt 5 damage to alice, leaving 5 Notability.",
"alice was nominated for deletion. The result was **delete**."
]
},
{
"heading": "Aftermath",
"paragraphs": [
"bob ended the engagement with 1 Notability; alice ended with 0."
]
}
]
}
+256
View File
@@ -0,0 +1,256 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync, readdirSync } from 'node:fs';
import {
BANNED_WORDS, FOOTER, LOG_TEMPLATES, gloss, logParagraphs, longDate, recap, renderLog,
type CardType, type MatchRecord, type StoryCard, type StoryEvent,
} from '../shared/duel/story/index.ts';
// Real cards from docs/game/card-sample.json (no network). Types, costs and Portals are the
// DUEL_DESIGN.md §9 worked examples.
const sample = JSON.parse(readFileSync(new URL('../docs/game/card-sample.json', import.meta.url), 'utf8')) as {
cards: { title: string; description: string | null; revisionId: number; pageId: number }[];
};
const byTitle = new Map(sample.cards.map(c => [c.title, c]));
function card(id: string, title: string, type: CardType, cost: number, portal: string, owner: 0 | 1): StoryCard {
const c = byTitle.get(title);
if (!c) throw new Error(`not in sample: ${title}`);
return { id, title, description: c.description ?? '', type, cost, portal, revisionId: c.revisionId, tokenId: `tok-${c.pageId}`, owner };
}
const cards: Record<string, StoryCard> = Object.fromEntries([
card('a1', 'Dichromorpha viridis', 'Figure', 2, 'Earth', 0),
card('a2', 'Pathrail Mosque', 'Location', 2, 'Society', 0),
card('a3', 'Zbyszek Godlewski', 'Figure', 5, 'History', 0),
card('a4', 'Monoid', 'Doctrine', 6, 'Science', 0),
card('a5', 'Tom Ewell', 'Figure', 6, 'Arts', 0),
card('b1', '1954 Gold Coast general election', 'Event', 3, 'Society', 1),
card('b2', "April 2021 nor'easter", 'Event', 3, 'Earth', 1),
card('b3', 'Marc Fesneau', 'Figure', 5, 'Society', 1),
card('b4', "Pallas's cat", 'Figure', 6, 'Earth', 1),
card('b5', 'Heart rot', 'Doctrine', 5, 'Science', 1),
card('b6', '2025 Tehreek-e-Labbaik Pakistan protests', 'Event', 5, 'Society', 1),
card('b7', 'Tatsunoko Production', 'Institution', 6, 'Arts', 1),
card('b8', 'Agda (programming language)', 'Doctrine', 6, 'Science', 1),
].map(c => [c.id, c]));
const T = (turn: number): StoryEvent => ({ kind: 'turnStart', turn, seat: turn % 2 === 1 ? 0 : 1 });
const events: StoryEvent[] = [
T(1), { kind: 'deploy', seat: 0, card: 'a2' },
T(2), { kind: 'draw', seat: 1, card: 'b1' },
T(3), { kind: 'draw', seat: 0, card: 'a1' }, { kind: 'deploy', seat: 0, card: 'a1' },
T(4), { kind: 'draw', seat: 1 }, { kind: 'cast', seat: 1, card: 'b1' },
{ kind: 'tokenCreated', seat: 1, source: 'b1', token: 'Elected Member', count: 2 },
T(5), { kind: 'draw', seat: 0 }, { kind: 'attack', seat: 0, card: 'a1', power: 4, toughness: 2 },
{ kind: 'playerDamage', seat: 1, source: 'a1', amount: 4, life: 16 },
T(6), { kind: 'draw', seat: 1 }, { kind: 'cast', seat: 1, card: 'b2' },
{ kind: 'effectDamage', source: 'b2', target: 'a1', amount: 1 },
{ kind: 'effectDamage', source: 'b2', target: 'a2', amount: 1 }, { kind: 'destroyed', card: 'a1' },
T(7), { kind: 'draw', seat: 0 }, { kind: 'deploy', seat: 0, card: 'a3' },
T(8), { kind: 'draw', seat: 1 }, { kind: 'deploy', seat: 1, card: 'b3' },
T(9), { kind: 'draw', seat: 0 }, { kind: 'attack', seat: 0, card: 'a3', power: 6, toughness: 3 },
{ kind: 'block', seat: 1, blocker: 'b3', attacker: 'a3', power: 5, toughness: 4 },
{ kind: 'destroyed', card: 'a3' }, { kind: 'destroyed', card: 'b3' }, { kind: 'draw', seat: 0 },
T(10), { kind: 'draw', seat: 1 }, { kind: 'discard', seat: 1, card: 'b8' }, { kind: 'deploy', seat: 1, card: 'b4' },
T(11), { kind: 'draw', seat: 0 }, { kind: 'deploy', seat: 0, card: 'a5' },
T(12), { kind: 'draw', seat: 1 }, { kind: 'adopt', seat: 1, doctrine: 'b5', figure: 'a5', power: 2, toughness: 2 },
{ kind: 'attack', seat: 1, card: 'b4', power: 5, toughness: 5 }, { kind: 'playerDamage', seat: 0, source: 'b4', amount: 5, life: 15 },
T(13), { kind: 'draw', seat: 0 }, { kind: 'adopt', seat: 0, doctrine: 'a4', figure: 'a5', power: 5, toughness: 5 },
{ kind: 'attack', seat: 0, card: 'a5', power: 5, toughness: 5 }, { kind: 'playerDamage', seat: 1, source: 'a5', amount: 5, life: 11 },
T(14), { kind: 'draw', seat: 1 }, { kind: 'cast', seat: 1, card: 'b6' },
{ kind: 'effectDamage', source: 'b6', target: 'a5', amount: 3 }, { kind: 'deploy', seat: 1, card: 'b7' },
{ kind: 'attack', seat: 1, card: 'b4', power: 5, toughness: 5 }, { kind: 'playerDamage', seat: 0, source: 'b4', amount: 5, life: 10 },
T(15), { kind: 'draw', seat: 0 }, { kind: 'attack', seat: 0, card: 'a5', power: 5, toughness: 5 },
{ kind: 'playerDamage', seat: 1, source: 'a5', amount: 5, life: 6 },
T(16), { kind: 'draw', seat: 1 }, { kind: 'attack', seat: 1, card: 'b4', power: 5, toughness: 5 },
{ kind: 'playerDamage', seat: 0, source: 'b4', amount: 5, life: 5 },
T(17), { kind: 'draw', seat: 0 }, { kind: 'attack', seat: 0, card: 'a5', power: 5, toughness: 5 },
{ kind: 'playerDamage', seat: 1, source: 'a5', amount: 5, life: 1 },
T(18), { kind: 'draw', seat: 1 }, { kind: 'attack', seat: 1, card: 'b4', power: 5, toughness: 5 },
{ kind: 'playerDamage', seat: 0, source: 'b4', amount: 5, life: 0 },
{ kind: 'gameOver', winner: 1, reason: 'life', turn: 18 },
];
const record: MatchRecord = {
matchId: 'golden-1', seed: 'golden-seed', date: '2026-11-17',
players: [{ name: 'alice' }, { name: 'bob' }], cards, events, hostName: 'testnet-r350',
};
test('recap: title, infobox and footer follow DUEL_DESIGN §8.3', () => {
const r = recap(record);
assert.equal(r.title, 'Battle of Pathrail Mosque (2026)'); // loser's Location; 9 turns each → "Battle of"
assert.equal(r.url, '/recap/golden-1');
assert.equal(r.masthead, 'WikiDeck');
assert.deepEqual(r.infobox, {
date: '17 November 2026',
location: 'Pathrail Mosque',
result: 'Pyrrhic bob victory',
belligerents: ['alice', 'bob'],
commanders: ['Tom Ewell', "Pallas's cat"],
strength: ['5 cards', '7 cards'],
casualties: ['2 cards destroyed: Dichromorpha viridis, Zbyszek Godlewski', '1 card destroyed: Marc Fesneau'],
});
assert.equal(r.footer, FOOTER);
assert.match(r.lead, /^The \*\*Battle of Pathrail Mosque \(2026\)\*\* .*17 November 2026.*alice.*bob.*eighteen turns.*a Pyrrhic victory for bob\.\[1\]/);
assert.match(r.lead, /\*Dichromorpha viridis\* \(Species of grasshopper\).* third turn\.\[2\]$/);
assert.deepEqual(r.sections.map(s => s.heading), ['Background', 'Course of the battle', 'Aftermath']);
assert.match(r.sections[2].paragraphs[0], /^bob ended the engagement with 1 Notability; alice ended with 0\.$/);
});
test('recap: references cite every card played with its revision id, in first-mention order', () => {
const r = recap(record);
assert.equal(r.references.length, 12);
assert.deepEqual(r.references.map(x => x.n), r.references.map((_, i) => i + 1));
assert.equal(r.references[0].title, 'Pathrail Mosque');
for (const ref of r.references) {
const c = cards[ref.cardId];
assert.equal(ref.revisionId, c.revisionId);
assert.ok(ref.url.endsWith(`&oldid=${c.revisionId}`), ref.url);
assert.ok(ref.url.startsWith('https://en.wikipedia.org/w/index.php?title='));
assert.match(ref.text, new RegExp(`Revision ${c.revisionId}\\. Minted as token tok-`));
}
// every [n] used in the text exists
const text = [r.lead, ...r.sections.flatMap(s => s.paragraphs)].join(' ');
for (const m of text.matchAll(/\[(\d+)\]/g)) assert.ok(Number(m[1]) <= r.references.length);
});
test('log: golden lines for the omniscient view', () => {
const { lines, references } = renderLog(record, null);
const paras = logParagraphs(lines);
assert.equal(paras.length, 18);
assert.equal(lines[0].text, 'Turn 1.');
assert.match(lines[1].text, /\*Pathrail Mosque\* \(Mosque in Faridpur, Bangladesh\).*\[1\]$/);
assert.ok(lines.some(l => /\*Zbyszek Godlewski\* \(Polish protester, 1952–1970\)/.test(l.text)));
assert.ok(lines.some(l => /two Elected Members/.test(l.text)));
assert.match(lines[lines.length - 1].text, /alice/);
// later mentions carry no gloss and no new citation
const later = lines.filter(l => l.text.includes('*Tom Ewell*'));
assert.ok(later.length >= 3);
assert.equal(later.filter(l => l.text.includes('American actor')).length, 1);
assert.equal(references.length, 13); // 12 played + the discarded Agda
// snapshot of the whole log text (golden): regenerate deliberately if templates change
assert.equal(paras.join('\n').length > 1500, true);
assert.deepEqual(renderLog(record, null), { lines, references });
});
test('log: logFor hides the opponent\'s draws', () => {
const forAlice = renderLog(record, 0).lines.map(l => l.text);
const forBob = renderLog(record, 1).lines.map(l => l.text);
const turn2Alice = forAlice[forAlice.indexOf('Turn 2.') + 1];
const turn2Bob = forBob[forBob.indexOf('Turn 2.') + 1];
assert.doesNotMatch(turn2Alice, /Gold Coast/);
assert.match(turn2Alice, /^bob (drew a card|drew one card|added a card to their hand)\.$/);
assert.match(turn2Bob, /Gold Coast/);
// alice sees her own draw of Dichromorpha viridis by name
assert.ok(forAlice.some(t => /alice.*Dichromorpha viridis|Dichromorpha viridis.*alice/.test(t) && /drew|drawn|hand/.test(t)));
});
test('log: discards are public (Deleted is a public zone)', () => {
const forAlice = renderLog(record, 0).lines.map(l => l.text);
assert.ok(forAlice.some(t => /Agda \(programming language\)/.test(t) && /discard|Deleted/.test(t)));
});
test('determinism: same seed gives the same text; another seed varies it', () => {
assert.deepEqual(recap(record), recap(structuredClone(record)));
const other = recap({ ...record, seed: 'another-seed' });
const a = renderLog(record).lines.map(l => l.text).join('\n');
const b = renderLog({ ...record, seed: 'another-seed' }).lines.map(l => l.text).join('\n');
assert.notEqual(a, b);
assert.equal(other.title, recap(record).title); // the name is data, not a variant
});
test('recap naming: Event fallback, Figure campaign, prefixes, and the decisive and withdrawal results', () => {
const base = { ...record, cards };
const short: MatchRecord = { ...base, events: [
T(1), { kind: 'cast', seat: 0, card: 'b6' }, { kind: 'deploy', seat: 0, card: 'a3' },
T(2), { kind: 'gameOver', winner: 0, reason: 'concede', turn: 2 },
] };
const r1 = recap(short);
assert.equal(r1.title, 'Skirmish at 2025 Tehreek-e-Labbaik Pakistan protests (2026)');
assert.equal(r1.infobox.result, 'alice victory by withdrawal');
assert.equal(r1.infobox.location, 'WikiDeck host testnet-r350');
const figOnly: MatchRecord = { ...base, events: [
T(1), { kind: 'deploy', seat: 1, card: 'b3' },
T(2), { kind: 'playerDamage', seat: 0, amount: 20, life: 0 }, { kind: 'gameOver', winner: 1, reason: 'life', turn: 2 },
] };
const r2 = recap(figOnly);
assert.equal(r2.title, 'Marc Fesneau campaign (2026)');
assert.equal(r2.infobox.result, 'Decisive bob victory');
const empty: MatchRecord = { ...base, events: [T(1), { kind: 'gameOver', winner: 1, reason: 'timeout', turn: 1 }] };
assert.equal(recap(empty).title, 'WikiDeck match of 17 November 2026');
});
test('tone lint: templates are deadpan (DUEL_DESIGN §8.1, critic S7)', () => {
for (const [key, variants] of Object.entries(LOG_TEMPLATES)) {
assert.ok(variants.length >= 3 && variants.length <= 4, `${key} has ${variants.length} variants`);
for (const v of variants) {
assert.doesNotMatch(v, /!/, `${key}: no exclamation marks`);
for (const w of BANNED_WORDS) assert.doesNotMatch(v.toLowerCase(), new RegExp(`\\b${w}\\b`), `${key}: banned word ${w}`);
assert.doesNotMatch(v, /[\u{1F300}-\u{1FAFF}]/u, `${key}: no emoji`);
}
}
const r = recap(record);
const prose = [r.lead, ...r.sections.flatMap(s => s.paragraphs)].join(' ')
.replace(/\*[^*]+\*/g, 'CARD'); // card titles are data; lint only our words
for (const w of BANNED_WORDS) assert.doesNotMatch(prose.toLowerCase(), new RegExp(`\\b${w}\\b`));
assert.doesNotMatch(prose, /!/);
assert.doesNotMatch(prose, /Wikipedia|Wikimedia/); // branding: only in references and the footer
});
test('every sample description glosses without throwing; dates format', () => {
for (const c of sample.cards) assert.equal(typeof gloss(c.description ?? ''), 'string');
assert.equal(gloss('American actor (1909–1994)'), 'American actor, 1909–1994');
assert.equal(gloss(''), '');
assert.equal(longDate('2026-01-05'), '5 January 2026');
});
test('story code is pure: no network or clock access', () => {
const dir = new URL('../shared/duel/story/', import.meta.url);
for (const f of readdirSync(dir)) {
const src = readFileSync(new URL(f, dir), 'utf8');
assert.doesNotMatch(src, /\bfetch\(|XMLHttpRequest|node:http|Date\.now|new Date\(|Math\.random/, f);
}
});
test('golden: full log and recap prose match tests/duel-design-story.golden.json', () => {
// To regenerate after a deliberate template change, dump { log, lead, sections } and review the diff.
const golden = JSON.parse(readFileSync(new URL('./duel-design-story.golden.json', import.meta.url), 'utf8'));
const r = recap(record);
assert.deepEqual({ log: logParagraphs(renderLog(record).lines), lead: r.lead, sections: r.sections }, golden);
});
test('tokens are named plainly and never cited; draws are recorded as inconclusive', () => {
const withToken: MatchRecord = {
...record,
cards: { ...cards, 't:1': { id: 't:1', title: 'Elected Member', type: 'Figure', cost: 0, portal: 'Society', owner: 1, token: true } },
events: [
T(1), { kind: 'cast', seat: 1, card: 'b1' },
{ kind: 'tokenCreated', seat: 1, source: 'b1', token: 'Elected Member', count: 1 },
T(2), { kind: 'attack', seat: 1, card: 't:1', power: 1, toughness: 1 },
{ kind: 'playerDamage', seat: 0, source: 't:1', amount: 20, life: 0 },
{ kind: 'playerDamage', seat: 1, amount: 20, life: 0 },
{ kind: 'gameOver', winner: null, reason: 'life', turn: 2 },
],
};
const { lines, references } = renderLog(withToken);
assert.ok(lines.some(l => /Elected Member \(1\/1\)/.test(l.text) && !/\*Elected Member\*/.test(l.text)));
assert.deepEqual(references.map(r => r.title), ['1954 Gold Coast general election']);
assert.match(lines[lines.length - 1].text, /draw|No winner/);
const r = recap(withToken);
assert.equal(r.infobox.result, 'Inconclusive');
assert.match(r.lead, /ended in a draw\./);
assert.ok(r.references.every(x => x.revisionId !== undefined));
});
test('final Notability: lifeGain is tracked, and gameOver.life wins when present', () => {
const ev: StoryEvent[] = [
T(1), { kind: 'deploy', seat: 0, card: 'a2' },
{ kind: 'playerDamage', seat: 0, amount: 18, life: 2 },
{ kind: 'lifeGain', seat: 0, source: 'a2', amount: 10, life: 12 },
{ kind: 'playerDamage', seat: 1, amount: 20, life: 0 },
{ kind: 'gameOver', winner: 0, reason: 'life', turn: 1 },
];
const r = recap({ ...record, events: ev });
assert.equal(r.infobox.result, 'Decisive alice victory'); // 12 vs 0, not Pyrrhic at 2
assert.ok(renderLog({ ...record, events: ev }).lines.some(l => /Notability/.test(l.text) && /12/.test(l.text)));
const withFinal = recap({ ...record, events: [...ev.slice(0, -1), { kind: 'gameOver', winner: 0, reason: 'life', turn: 1, life: [3, 0] }] });
assert.equal(withFinal.infobox.result, 'Pyrrhic alice victory');
});
+344
View File
@@ -0,0 +1,344 @@
// host-pvp (#56): multi-engine host, account seats, constructed owned decks, invites, quick
// match, Elo and `?v=` polling. Stub engine + fake ownership port: zero network calls.
import test from 'node:test';
import assert from 'node:assert/strict';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import express from 'express';
import { parseMode, MODE_SCHEMA_VERSION } from '../shared/game/modes.ts';
import { ModeHost, GameError, seededShuffle } from '../server/game/host.ts';
import { MatchStore, eloUpdate, ELO_START } from '../server/game/store.ts';
import { ModeDiscovery } from '../server/game/discovery.ts';
import { createGameRouter } from '../server/game/router.ts';
import type { ChainCard, EnginePort, OwnershipPort, SeatAccount } from '../server/game/engine-port.ts';
import { stubEngine, type StubCard } from './modes-stub-engine.ts';
const DECK = 6; // stand-in for the duel's 40, to keep the stub small
const identity = { origin: 'http://node-a.test', operator: 'Alice' };
/** The stub engine, registered as `duel`, that can build cards from owned NFTs. */
const duelStub: EnginePort<any, StubCard, any, any> = {
...stubEngine,
defaultRuleset: { deckSize: DECK, turns: 3, scoring: { tieBreak: 'first' } },
fromChain: (_rules, c: ChainCard) => ({ id: c.tokenId, pageId: c.pageId, power: (c.pageId % 9) + 1 }),
copyLimit: () => 4,
};
const duelMode = (over: object = {}) => parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'duel', id: 'duel-classic', version: 1,
name: 'Duel', description: 'Constructed duel.', decks: { kind: 'constructed', minConfirmations: 1 },
limits: { rated: true }, ...over });
class OwnershipError extends Error { readonly status: number; constructor(status: number, m: string) { super(m); this.status = status; } }
/** In-memory accounts + ledger: tokens `<who>-<n>` belong to `<who>`. */
function fakeOwnership() {
const accounts: Record<string, SeatAccount> = {
'id-alice': { sub: 'alice', issuer: 'https://dex.test', name: 'Alice Example' },
'id-bob': { sub: 'bob', issuer: 'https://dex.test', name: 'Bob <b>' },
'id-carol': { sub: 'carol', issuer: 'https://dex.test', name: 'Carol' },
};
const ledger = new Map<string, { sub: string; confirmations: number; pageId: number }>();
const mint = (sub: string, n: number, confirmations = 5) => {
for (let i = 0; i < n; i++) ledger.set(`${sub}-${i}`, { sub, confirmations, pageId: 100 + ledger.size });
};
mint('alice', 10); mint('bob', 10); mint('carol', 3);
const card = (tokenId: string): ChainCard => {
const e = ledger.get(tokenId)!;
return { tokenId, owner: `wallet-${e.sub}`, confirmations: e.confirmations, pageId: e.pageId, title: `Page ${e.pageId}` };
};
const calls = { verify: 0, resolve: 0, collection: 0 };
const port: OwnershipPort = {
async verifyAccount(idToken) {
calls.verify++;
const a = typeof idToken === 'string' ? accounts[idToken] : undefined;
if (!a) throw new OwnershipError(401, 'Invalid eom.dev login');
return a;
},
async resolveDeck(account, tokenIds, opts) {
calls.resolve++;
const ids = tokenIds as string[];
if (ids.length !== opts.deckSize) throw new OwnershipError(400, 'wrong size');
if (new Set(ids).size !== ids.length) throw new OwnershipError(400, 'duplicate token');
for (const t of ids) {
const e = ledger.get(t);
if (!e) throw new OwnershipError(400, `unknown token ${t}`);
if (e.sub !== account.sub) throw new OwnershipError(403, `not yours: ${t}`);
if (e.confirmations < opts.minConfirmations) throw new OwnershipError(400, `unconfirmed: ${t}`);
}
return ids.map(card);
},
async collection(account) {
calls.collection++;
return [...ledger.entries()].filter(([, e]) => e.sub === account.sub).map(([t]) => card(t));
},
};
return { port, ledger, calls, mint };
}
const deckOf = (who: string, n = DECK) => Array.from({ length: n }, (_, i) => `${who}-${i}`);
function playOut(host: ModeHost, lobbyId: string, tokens: string[]) {
for (let guard = 0; guard < 50; guard++) {
const v0 = host.view(lobbyId, tokens[0]) as any;
if (v0.phase !== 'playing') return v0;
for (const t of tokens) {
const v = host.view(lobbyId, t) as any;
if (v.legalActions?.length) void host.act(lobbyId, t, v.legalActions[0]);
}
}
throw new Error('did not finish');
}
function newHost(modes = [duelMode()], store = new MatchStore(null), own = fakeOwnership()) {
return { host: new ModeHost({ identity, modes, engines: { duel: duelStub, editwar: stubEngine }, ownership: own.port, store }), own, store };
}
test('host-pvp: two account players finish a hosted constructed duel; rated, Elo moves, record has tokens', async () => {
const { host, store } = newHost();
const a = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
const b = await host.join(a.lobbyId, { idToken: 'id-bob', deck: deckOf('bob') });
const v = host.view(a.lobbyId, a.token) as any;
assert.equal(v.phase, 'playing');
assert.equal(v.rated, true);
assert.equal(v.mode.engine, 'duel');
assert.deepEqual(v.players.map((p: any) => [p.name, p.account]), [['Alice Example', true], ['Bob b', true]]);
assert.deepEqual(v.state.hand.map((c: any) => c.id), deckOf('alice'), 'cards are built from the chain, in deck order');
const end = playOut(host, a.lobbyId, [a.token, b.token]);
assert.equal(end.phase, 'finished');
assert.match(end.matchId, /^[a-f0-9]{32}$/);
const rec = host.matchRecord(end.matchId);
assert.equal(rec.engine, 'duel');
assert.equal(rec.rated, true);
assert.deepEqual(rec.tokens, [deckOf('alice'), deckOf('bob')]);
assert.ok(!JSON.stringify(rec).includes('id-alice'), 'ID tokens are never stored');
const board = host.leaderboard('duel-classic').entries;
assert.equal(board.length, 2);
const [hi, lo] = eloUpdate(ELO_START, ELO_START, 0);
const ratings = board.map(e => e.rating).sort();
assert.deepEqual(ratings, [Math.round(lo), Math.round(hi)].sort());
assert.ok(board.every(e => e.ratedPlayed === 1));
assert.equal(store.total, 1);
});
test('host-pvp: forged, unowned, short and unconfirmed decks are rejected; guests need an account', async () => {
const { host, own } = newHost();
const status = async (p: Promise<unknown>) => { try { await p; return 0; } catch (e) { assert.ok(e instanceof GameError, String(e)); return e.status; } };
// Guest (secret) seat in an owned-cards mode.
assert.equal(await status(host.createLobby('duel-classic', { name: 'Al', secret: 'alice-secret-0123456789abcdef', deck: deckOf('alice') })), 401);
// Bad login.
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-mallory', deck: deckOf('alice') })), 401);
// Short deck, long deck, non-array, non-strings: rejected before ownership is asked.
const before = own.calls.resolve;
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice', DECK - 1) })), 400);
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice', DECK + 1) })), 400);
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: 'alice-0' })), 400);
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: [1, 2, 3, 4, 5, 6] })), 400);
assert.equal(own.calls.resolve, before);
// Forged token id (not on the chain), someone else's card, duplicate card.
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: [...deckOf('alice', DECK - 1), 'forged-1'] })), 400);
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: [...deckOf('alice', DECK - 1), 'bob-0'] })), 403);
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: [...deckOf('alice', DECK - 1), 'alice-0'] })), 400);
// Unconfirmed: a fresh mint below the mode's minConfirmations.
own.ledger.set('alice-new', { sub: 'alice', confirmations: 0, pageId: 999 });
assert.equal(await status(host.createLobby('duel-classic', { idToken: 'id-alice', deck: [...deckOf('alice', DECK - 1), 'alice-new'] })), 400);
// Joiner with a bad deck does not kill the creator's lobby.
const a = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
assert.equal(await status(host.join(a.lobbyId, { idToken: 'id-bob', deck: deckOf('alice') })), 403);
assert.equal((host.view(a.lobbyId) as any).phase, 'waiting');
// Same account on both seats.
assert.equal(await status(host.join(a.lobbyId, { idToken: 'id-alice', deck: deckOf('alice') })), 409);
});
test('host-pvp: cross-seat and cross-lobby tokens are rejected', async () => {
const { host } = newHost();
const a = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
const b = await host.join(a.lobbyId, { idToken: 'id-bob', deck: deckOf('bob') });
const c = await host.createLobby('duel-classic', { idToken: 'id-carol2', deck: [] }).catch(() => null);
assert.equal(c, null);
const other = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
// Bob's token acts as Bob only: legal actions are per seat, so Alice's action from Bob's token is illegal.
const aliceAction = (host.view(a.lobbyId, a.token) as any).legalActions[0];
const bobView = host.view(a.lobbyId, b.token) as any;
assert.equal(bobView.seat, 1);
// A token from another lobby is not a seat here, and a spectator sees no private state.
await assert.rejects(host.act(a.lobbyId, other.token, aliceAction), (e: GameError) => e.status === 403);
assert.equal((host.view(a.lobbyId, other.token) as any).state, undefined);
assert.equal((host.view(a.lobbyId, other.token) as any).seat, null);
assert.throws(() => host.resign(a.lobbyId, 'x'.repeat(32)), (e: GameError) => e.status === 403);
// Seat ids are account-derived, never the token.
const ids = bobView.players.map((p: any) => p.id);
assert.ok(ids.every((id: string) => /^[a-f0-9]{64}$/.test(id)));
assert.ok(!ids.includes(a.token) && !ids.includes(b.token));
});
test('host-pvp: creator cards that moved before the join expire the lobby', async () => {
const { host, own } = newHost();
const a = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
own.ledger.set('alice-3', { ...own.ledger.get('alice-3')!, sub: 'carol' }); // transferred away
await assert.rejects(host.join(a.lobbyId, { idToken: 'id-bob', deck: deckOf('bob') }), /no longer valid/);
assert.equal((host.view(a.lobbyId) as any).phase, 'expired');
assert.equal((host.view(a.lobbyId) as any).players.length, 1, 'a stale lobby never lists the joiner');
});
test('host-pvp: quick match skips a stale lobby and pairs the next one', async () => {
const { host, own } = newHost();
own.mint('dave', 0);
const stale = await host.quickMatch('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
const fresh = await host.quickMatch('duel-classic', { idToken: 'id-carol', deck: [] }).catch(() => null);
assert.equal(fresh, null, 'carol cannot build a deck');
own.ledger.set('alice-0', { ...own.ledger.get('alice-0')!, sub: 'carol' });
// Bob quick-matches: alice's lobby is stale (expired, skipped), so bob opens a new one.
const bob = await host.quickMatch('duel-classic', { idToken: 'id-bob', deck: deckOf('bob') });
assert.equal(bob.matched, false);
assert.notEqual(bob.lobbyId, stale.lobbyId);
assert.equal((host.view(stale.lobbyId) as any).phase, 'expired');
});
test('host-pvp: private lobbies are hidden and joined by invite code', async () => {
const { host } = newHost();
const pub = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
const priv = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice'), private: true });
assert.match(priv.invite!, /^[A-Za-z0-9_-]{12}$/);
assert.deepEqual(host.openLobbies('duel-classic').map(l => l.lobbyId), [pub.lobbyId]);
const inv = host.invite(priv.invite!);
assert.equal(inv.lobbyId, priv.lobbyId);
assert.equal(inv.open, true);
assert.equal(inv.accountRequired, true);
assert.equal(inv.createdBy, 'Alice Example');
assert.throws(() => host.invite('nope'), (e: GameError) => e.status === 404);
// Quick match never lands in a private lobby.
const q = await host.quickMatch('duel-classic', { idToken: 'id-bob', deck: deckOf('bob') });
assert.equal(q.matched, true);
assert.equal(q.lobbyId, pub.lobbyId);
await host.join(inv.lobbyId, { idToken: 'id-bob', deck: deckOf('bob') });
assert.equal(host.invite(priv.invite!).open, false);
// Only the creator's view carries the invite code.
assert.equal((host.view(priv.lobbyId, priv.token) as any).invite, priv.invite);
assert.equal((host.view(priv.lobbyId) as any).invite, undefined);
});
test('host-pvp: quick match pairs the oldest open lobby, never yourself', async () => {
const { host } = newHost();
const first = await host.quickMatch('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
assert.equal(first.matched, false);
assert.equal(first.seat, 0);
const again = await host.quickMatch('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
assert.equal(again.matched, false, 'does not match your own lobby');
assert.notEqual(again.lobbyId, first.lobbyId);
const bob = await host.quickMatch('duel-classic', { idToken: 'id-bob', deck: deckOf('bob') });
assert.equal(bob.matched, true);
assert.equal(bob.lobbyId, first.lobbyId, 'oldest first');
assert.equal(bob.seat, 1);
assert.equal((host.view(first.lobbyId, first.token) as any).phase, 'playing');
});
test('host-pvp: state version; unchanged polls return null (204 over HTTP)', async () => {
const { host } = newHost();
const a = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
const v1 = (host.view(a.lobbyId, a.token) as any).version;
assert.equal(host.view(a.lobbyId, a.token, v1), null);
const b = await host.join(a.lobbyId, { idToken: 'id-bob', deck: deckOf('bob') });
const v2 = (host.view(a.lobbyId, a.token, v1) as any).version;
assert.ok(v2 > v1);
assert.equal(host.view(a.lobbyId, b.token, v2), null);
await host.act(a.lobbyId, a.token, (host.view(a.lobbyId, a.token) as any).legalActions[0]);
assert.ok((host.view(a.lobbyId, b.token, v2) as any).version > v2);
// Over HTTP: 204 with no body, 200 with a newer version; Dex token accepted as a JWT bearer.
const app = express();
app.use(express.json());
app.use('/api/game', createGameRouter(host, new ModeDiscovery({ peers: [] })));
const server = app.listen(0);
try {
const base = `http://127.0.0.1:${(server.address() as any).port}/api/game`;
const cur = (await (await fetch(`${base}/lobbies/${a.lobbyId}`, { headers: { authorization: `Bearer ${a.token}` } })).json()).version;
const same = await fetch(`${base}/lobbies/${a.lobbyId}?v=${cur}`, { headers: { authorization: `Bearer ${a.token}` } });
assert.equal(same.status, 204);
const stale = await fetch(`${base}/lobbies/${a.lobbyId}?v=${cur - 1}`);
assert.equal(stale.status, 200);
const ladder = await (await fetch(`${base}/modes/duel-classic/ladder`)).json();
assert.ok(Array.isArray(ladder.entries));
// JWT-shaped bearer on a seat-creating route reaches verifyAccount (rejected here: unknown login).
const jwt = await fetch(`${base}/modes/duel-classic/quick`, { method: 'POST', headers: { 'content-type': 'application/json',
authorization: 'Bearer aaa.bbb.ccc' }, body: JSON.stringify({ deck: deckOf('alice') }) });
assert.equal(jwt.status, 401);
const inv = await fetch(`${base}/invites/${a.invite}`);
assert.equal(inv.status, 200);
assert.equal((await inv.json()).open, false);
} finally { server.close(); }
});
test('host-pvp: collections draft pools both players cards; short collections are rejected', async () => {
const mode = duelMode({ id: 'duel-draft', decks: { kind: 'draft', source: 'collections', poolSize: 2 * DECK, pickSeconds: 30 } });
const { host } = newHost([mode]);
const a = await host.createLobby('duel-draft', { idToken: 'id-alice' });
await host.join(a.lobbyId, { idToken: 'id-bob' });
const v = host.view(a.lobbyId, a.token) as any;
assert.equal(v.phase, 'drafting');
assert.equal((host.view(a.lobbyId) as any).draft, undefined, 'spectators see no draft pool');
assert.equal(v.draft.pool.length, 2 * DECK);
const owners = new Set(v.draft.pool.map((p: any) => String(p.card.id).split('-')[0]));
assert.ok(owners.size >= 1 && [...owners].every(o => o === 'alice' || o === 'bob'));
// Carol owns 3 < 6 cards: not eligible.
const c = await host.createLobby('duel-draft', { idToken: 'id-carol' });
await assert.rejects(host.join(c.lobbyId, { idToken: 'id-bob' }), /3 \/ 6 cards/);
assert.equal((host.view(c.lobbyId) as any).phase, 'expired');
});
test('host-pvp: duel modes reject loaner policies; Night 1 mode files are rejected cleanly', () => {
const store = new MatchStore(null);
assert.throws(() => new ModeHost({ identity, store, engines: { duel: duelStub }, modes: [duelMode({ decks: { kind: 'starter' } })] }), /owned cards only/);
assert.throws(() => new ModeHost({ identity, store, engines: { duel: duelStub },
modes: [duelMode({ decks: { kind: 'draft', source: 'preview', poolSize: 12 } })] }), /owned cards only/);
assert.throws(() => new ModeHost({ identity, store, engines: { editwar: stubEngine }, modes: [duelMode()] }), /engine "duel" is not available/);
assert.throws(() => parseMode({ schema: 'wikideck.mode/1', id: 'old', version: 1, name: 'Old', description: 'x' }), /Night 1.*wikideck\.mode\/2/);
assert.throws(() => parseMode({ schema: MODE_SCHEMA_VERSION, id: 'no-engine', version: 1, name: 'x', description: 'x' }));
});
test('host-pvp: Edit War guests still play, unrated, beside duel modes', async () => {
const war = parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'war', version: 1, name: 'War', description: 'x',
decks: { kind: 'starter' }, limits: { rated: true } });
const { host } = newHost([duelMode(), war]);
const a = await host.createLobby('war', { name: 'Al', secret: 'alice-secret-0123456789abcdef' });
const b = await host.join(a.lobbyId, { name: 'Bo', secret: 'bob-secret-0123456789abcdefgh' });
const end = playOut(host, a.lobbyId, [a.token, b.token]);
const rec = host.matchRecord(end.matchId);
assert.equal(rec.rated, false, 'guests are never rated');
assert.ok(host.leaderboard('war').entries.every(e => e.rating === null));
});
test('host-pvp: Elo is recomputed identically from matches.jsonl on restart', async () => {
const dir = mkdtempSync(join(tmpdir(), 'host-pvp-'));
try {
const { host } = newHost([duelMode()], new MatchStore(dir));
for (let i = 0; i < 3; i++) {
const a = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
const b = await host.join(a.lobbyId, { idToken: 'id-bob', deck: deckOf('bob') });
playOut(host, a.lobbyId, [a.token, b.token]);
}
const before = host.leaderboard('duel-classic').entries;
const reloaded = new MatchStore(dir);
assert.deepEqual(reloaded.leaderboard('duel-classic'), before);
assert.ok(before.every(e => e.ratedPlayed === 3));
} finally { rmSync(dir, { recursive: true, force: true }); }
});
test('host-pvp: live lobbies with account seats survive a snapshot/restore', async () => {
const { host, own } = newHost();
const a = await host.createLobby('duel-classic', { idToken: 'id-alice', deck: deckOf('alice') });
const snap = host.snapshot();
assert.ok(!snap.includes(a.token) && !snap.includes('id-alice'));
const next = new ModeHost({ identity, modes: [duelMode()], engines: { duel: duelStub }, ownership: own.port, store: new MatchStore(null) });
assert.equal(next.restore(snap), 1);
const b = await next.join(a.lobbyId, { idToken: 'id-bob', deck: deckOf('bob') });
assert.equal((next.view(a.lobbyId, b.token) as any).phase, 'playing');
assert.equal((next.view(a.lobbyId, a.token) as any).seat, 0);
});
test('host-pvp: seeded shuffle is deterministic and a permutation', () => {
const xs = Array.from({ length: 50 }, (_, i) => i);
assert.deepEqual(seededShuffle(xs, 's'), seededShuffle(xs, 's'));
assert.notDeepEqual(seededShuffle(xs, 's'), seededShuffle(xs, 't'));
assert.deepEqual([...seededShuffle(xs, 's')].sort((a, b) => a - b), xs);
});
+10 -10
View File
@@ -145,7 +145,7 @@ test('modes api: the rule examples in HOSTING.md are valid modes', () => {
{ deckSize: 16, maxCopiesPerPage: 2, maxLoaners: 16 },
{ turns: 6, turnSeconds: 40 },
]) {
const m = parseMode({ schema: MODE_SCHEMA_VERSION, id: 'doc-example', version: 1, name: 'x', description: 'x', rules });
const m = parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'doc-example', version: 1, name: 'x', description: 'x', rules });
assert.doesNotThrow(() => resolveRuleset(DEFAULT_RULESET, m.rules, parseRuleset), JSON.stringify(rules));
}
});
@@ -154,7 +154,7 @@ test('modes api: mode rules that make starter decks illegal fail at startup; liv
const { ModeHost } = await import('../server/game/host.ts');
const { MatchStore } = await import('../server/game/store.ts');
const { engineBinding } = await import('../server/game/engine-binding.ts');
const big = parseMode({ schema: MODE_SCHEMA_VERSION, id: 'big', version: 1, name: 'Big', description: 'x',
const big = parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'big', version: 1, name: 'Big', description: 'x',
decks: { kind: 'starter' }, rules: { deckSize: 16, maxLoaners: 16 } });
assert.throws(() => new ModeHost({ identity: { origin: 'http://x.test', operator: 'X' }, modes: [big], engine: engineBinding,
store: new MatchStore(null) }), /starter decks are illegal/);
@@ -172,10 +172,10 @@ test('modes api: turn timer applies the engine timeout action; AFK forfeits are
const { MatchStore } = await import('../server/game/store.ts');
const { engineBinding } = await import('../server/game/engine-binding.ts');
let now = 0;
const classic = parseMode({ schema: MODE_SCHEMA_VERSION, id: 'classic', version: 1, name: 'C', description: 'x', decks: { kind: 'starter' } });
const classic = parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'classic', version: 1, name: 'C', description: 'x', decks: { kind: 'starter' } });
const host = new ModeHost({ identity: { origin: 'http://x.test', operator: 'X' }, modes: [classic], engine: engineBinding,
store: new MatchStore(null), now: () => now });
const a = host.createLobby('classic', alice);
const a = await host.createLobby('classic', alice);
const b = await host.join(a.lobbyId, bob);
// Bob plays normally; Alice never acts.
for (let turn = 0; turn < 6; turn++) {
@@ -219,21 +219,21 @@ test('modes api: live matches survive a node restart (snapshot on shutdown, rest
const { join } = await import('node:path');
const dir = mkdtempSync(join(tmpdir(), 'modes-live-'));
try {
const modes = [parseMode({ schema: MODE_SCHEMA_VERSION, id: 'classic', version: 1, name: 'C', description: 'x', decks: { kind: 'starter' } }),
parseMode({ schema: MODE_SCHEMA_VERSION, id: 'draft', version: 1, name: 'D', description: 'x', decks: { kind: 'draft', poolSize: 30 }, rules: { deckSize: 10, openingHand: 4 } })];
const modes = [parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'classic', version: 1, name: 'C', description: 'x', decks: { kind: 'starter' } }),
parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'draft', version: 1, name: 'D', description: 'x', decks: { kind: 'draft', poolSize: 30 }, rules: { deckSize: 10, openingHand: 4 } })];
const make = () => new ModeHost({ identity: { origin: 'http://x.test', operator: 'X' }, modes, engine: engineBinding, store: new MatchStore(dir) });
const first = make();
persistLive(first, dir, false);
const a = first.createLobby('classic', alice);
const a = await first.createLobby('classic', alice);
const b = await first.join(a.lobbyId, bob);
// Random seed: the opening hand may have nothing playable on turn 1, so fall back to commit.
const legal = (first.view(a.lobbyId, a.token) as any).legalActions;
await first.act(a.lobbyId, a.token, legal.find((x: any) => x.type === 'play') ?? legal.find((x: any) => x.type === 'commit'));
const d = first.createLobby('draft', alice);
const d = await first.createLobby('draft', alice);
const e = await first.join(d.lobbyId, bob);
const pick = (first.view(d.lobbyId, d.token) as any).draft;
await first.pick(d.lobbyId, [d.token, e.token][pick.toPick]!, 0);
const waiting = first.createLobby('classic', { name: 'Cy', secret: 'cy-secret-0123456789abcdefghij' });
const waiting = await first.createLobby('classic', { name: 'Cy', secret: 'cy-secret-0123456789abcdefghij' });
const before = first.view(a.lobbyId, b.token) as any;
persistLive(first, dir, false).save();
@@ -262,7 +262,7 @@ test('modes api: live matches survive a node restart (snapshot on shutdown, rest
assert.equal(replay(rec.rules as any, rec.decks as any, rec.seed, rec.actions.map(x => x.action) as any).result?.winner ?? null, rec.winner);
// Rules changed under a mode → its lobbies are dropped, not run under different rules.
const changed = new ModeHost({ identity: { origin: 'http://x.test', operator: 'X' }, engine: engineBinding, store: new MatchStore(null),
modes: [parseMode({ schema: MODE_SCHEMA_VERSION, id: 'classic', version: 1, name: 'C', description: 'x', decks: { kind: 'starter' }, rules: { turns: 5 } })] });
modes: [parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'classic', version: 1, name: 'C', description: 'x', decks: { kind: 'starter' }, rules: { turns: 5 } })] });
assert.equal(changed.restore(second.snapshot()), 0);
} finally { rmSync(dir, { recursive: true, force: true }); }
});
+14 -14
View File
@@ -9,7 +9,7 @@ import { MatchStore } from '../server/game/store.ts';
import { ModeDiscovery } from '../server/game/discovery.ts';
import { stubEngine } from './modes-stub-engine.ts';
const mode = (over: object = {}) => parseMode({ schema: MODE_SCHEMA_VERSION, id: 'stub', version: 1, name: 'Stub',
const mode = (over: object = {}) => parseMode({ schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'stub', version: 1, name: 'Stub',
description: 'Stub mode.', decks: { kind: 'starter' }, ...over });
const identity = { origin: 'http://node-a.test', operator: 'Alice' };
const alice = { name: 'Alice', secret: 'alice-secret-0123456789abcdef' };
@@ -31,7 +31,7 @@ test('modes host: lobby → match → record → leaderboard and host credit', a
let now = 1_000_000;
const store = new MatchStore(null);
const host = new ModeHost({ identity, modes: [mode()], engine: stubEngine, store, now: () => now });
const a = host.createLobby('stub', alice);
const a = await host.createLobby('stub', alice);
assert.equal(host.list().modes[0]!.stats.openLobbies, 1);
assert.deepEqual(host.openLobbies('stub').map(l => l.host), ['Alice']);
const b = await host.join(a.lobbyId, bob);
@@ -55,7 +55,7 @@ test('modes host: lobby → match → record → leaderboard and host credit', a
test('modes host: actions must be legal and from the right seat', async () => {
const host = new ModeHost({ identity, modes: [mode()], engine: stubEngine, store: new MatchStore(null) });
const a = host.createLobby('stub', alice);
const a = await host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
await assert.rejects(host.act(a.lobbyId, a.token, { type: 'play', card: 99 }), /Illegal/);
await assert.rejects(host.act(a.lobbyId, 'not-a-token-xxxxxxxxxxxx', { type: 'play', card: 0 }), /Not a player/);
@@ -63,21 +63,21 @@ test('modes host: actions must be legal and from the right seat', async () => {
await assert.rejects(host.act(a.lobbyId, a.token, { type: 'play', card: 0 }), /Illegal/, 'no double play');
await host.act(a.lobbyId, b.token, { card: 1, type: 'play' }); // key order doesn't matter
await assert.rejects(host.join(a.lobbyId, { name: 'Eve', secret: 'eve-secret-0123456789abcdefgh' }), /no longer open/);
assert.throws(() => host.createLobby('stub', { name: '<script>', secret: alice.secret }), GameError);
assert.throws(() => host.createLobby('stub', { name: 'Al', secret: 'short' }), GameError);
assert.throws(() => host.createLobby('nope', alice), /not hosted/);
await assert.rejects(async () => host.createLobby('stub', { name: '<script>', secret: alice.secret }), GameError);
await assert.rejects(async () => host.createLobby('stub', { name: 'Al', secret: 'short' }), GameError);
await assert.rejects(async () => host.createLobby('nope', alice), /not hosted/);
});
test('modes host: limits, expiry and turn timeouts', async () => {
let now = 0;
const host = new ModeHost({ identity, modes: [mode({ limits: { maxConcurrentMatches: 2, turnSeconds: 10, lobbyMinutes: 1 } })],
engine: stubEngine, store: new MatchStore(null), now: () => now });
const l1 = host.createLobby('stub', alice);
host.createLobby('stub', bob);
assert.throws(() => host.createLobby('stub', { name: 'Cy', secret: 'cy-secret-0123456789abcdefghij' }), /match limit/);
const l1 = await host.createLobby('stub', alice);
await host.createLobby('stub', bob);
await assert.rejects(async () => host.createLobby('stub', { name: 'Cy', secret: 'cy-secret-0123456789abcdefghij' }), /match limit/);
now += 61_000; host.sweep();
assert.equal((host.view(l1.lobbyId) as any).phase, 'expired');
const l3 = host.createLobby('stub', alice);
const l3 = await host.createLobby('stub', alice);
const t3 = await host.join(l3.lobbyId, bob);
await host.act(l3.lobbyId, l3.token, { type: 'play', card: 0 }); // Bob now owes a move
now += 11_000; host.sweep();
@@ -89,7 +89,7 @@ test('modes host: limits, expiry and turn timeouts', async () => {
test('modes host: snake draft builds both decks from one pool', async () => {
const host = new ModeHost({ identity, modes: [mode({ decks: { kind: 'draft', poolSize: 8, pickSeconds: 10 } })],
engine: stubEngine, store: new MatchStore(null) });
const a = host.createLobby('stub', alice);
const a = await host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
const tok = [a.token, b.token];
const order: number[] = [];
@@ -113,7 +113,7 @@ test('modes host: trending mapping adjusts power from live trends, once, bounded
const host = new ModeHost({ identity, modes: [mode({ cards: { preset: 'trending', percentPerPoint: 10, maxBonus: 2 } })],
engine: stubEngine, store: new MatchStore(null),
liveData: async pageId => { seen.push(pageId); return { trendPercent: pageId % 2 ? 1000 : -1000 }; } });
const a = host.createLobby('stub', alice);
const a = await host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
const base = stubEngine.starterDeck(stubEngine.defaultRuleset, 'x');
const hand = (host.view(a.lobbyId, a.token) as any).state.hand;
@@ -131,7 +131,7 @@ test('modes store: records persist and rebuild aggregates; torn lines are skippe
const dir = mkdtempSync(join(tmpdir(), 'modes-store-'));
try {
const host = new ModeHost({ identity, modes: [mode()], engine: stubEngine, store: new MatchStore(dir) });
const a = host.createLobby('stub', alice);
const a = await host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
playOut(host, a.lobbyId, [a.token, b.token]);
const file = join(dir, 'matches.jsonl');
@@ -189,7 +189,7 @@ test('modes host: two concurrent joins cannot both take the second seat', async
const slow = { ...stubEngine };
const host = new ModeHost({ identity, modes: [mode({ cards: { preset: 'trending' } })], engine: slow, store: new MatchStore(null),
liveData: async () => { await new Promise(r => setTimeout(r, 20)); return { trendPercent: 0 }; } });
const a = host.createLobby('stub', alice);
const a = await host.createLobby('stub', alice);
const results = await Promise.allSettled([host.join(a.lobbyId, bob), host.join(a.lobbyId, { name: 'Eve', secret: 'eve-secret-0123456789abcdefgh' })]);
assert.equal(results.filter(r => r.status === 'fulfilled').length, 1);
assert.equal((host.view(a.lobbyId) as any).players.length, 2);
+1 -1
View File
@@ -8,7 +8,7 @@ import { parsePeerOrigins } from '../server/game/discovery.ts';
import { stubEngine } from './modes-stub-engine.ts';
import { engineBinding } from '../server/game/engine-binding.ts';
const base = { schema: MODE_SCHEMA_VERSION, id: 'my-mode', version: 1, name: 'My mode', description: 'A test mode.' };
const base = { schema: MODE_SCHEMA_VERSION, engine: 'editwar', id: 'my-mode', version: 1, name: 'My mode', description: 'A test mode.' };
test('modes: minimal document gets safe defaults', () => {
const m = parseMode(base);
+291
View File
@@ -0,0 +1,291 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import express from 'express';
import type { AddressInfo } from 'node:net';
import { resolveDeck, collection, verifyAccount, playableCount, ownershipRules, DEFAULT_OWNERSHIP_RULES,
DeckError, OwnershipUnavailable, type OwnershipDeps, type OwnershipLedger } from '../server/game/ownership.ts';
import { collectionRouter, collectionResponse } from '../server/game/collection.ts';
import type { Account } from '../server/account/store.ts';
import type { TestnetBlock } from '../shared/testnet.ts';
// In-memory fixture: the same shape as Ledger.nft/deck/summary and AccountStore.wallets. No network.
const hex = (s: string) => createHash('sha256').update(s).digest('hex');
const ALICE = hex('alice'), ALICE2 = hex('alice-2'), BOB = hex('bob');
function block(n: number, pageId: number, miner: string): TestnetBlock {
return {
version: 6, network: 'testnet', chainId: 'test', height: n, previousHash: hex(`b${n - 1}`), createdAt: 1_800_000_000 + n,
article: { pageId, title: `Article ${pageId}`, extract: `Extract ${pageId}.`, url: `https://en.wikipedia.org/?curid=${pageId}`,
revisionId: 1000 + pageId, source: 'live', category: 'History' },
statsSnapshot: { capturedAt: '2026-11-17T00:00:00Z', revisionId: 1000 + pageId, pageBytes: 5000 + pageId, languageCount: 3,
languagesTruncated: false, pageviews: null } as unknown as TestnetBlock['statsSnapshot'],
owner: miner, publicKey: 'pk', nonce: 0, target: 'f'.repeat(64), key: '0'.repeat(64), transactionsRoot: '0'.repeat(64),
stateRoot: '0'.repeat(64), hash: hex(`b${n}`), tokenId: hex(`t${n}`), powHash: hex(`p${n}`), signature: 'sig', transactions: [],
} as unknown as TestnetBlock;
}
class FakeLedger implements OwnershipLedger {
tip = 'tip-0';
height = 0;
cards: { block: TestnetBlock; owner: string }[] = [];
deckCalls = 0;
onDeck?: () => void;
mint(owner: string, pageId: number): string {
const b = block(++this.height, pageId, owner);
this.cards.push({ block: b, owner });
this.tip = `tip-${this.height}`;
return b.tokenId;
}
mineEmpty(n = 1) { this.height += n; this.tip = `tip-${this.height}`; }
transfer(token: string, to: string) { this.cards.find(c => c.block.tokenId === token)!.owner = to; }
private conf(b: TestnetBlock) { return this.height - b.height + 1; }
nft(token: string) {
const c = this.cards.find(x => x.block.tokenId === token);
return c ? { block: structuredClone(c.block), owner: c.owner, sequence: 0, confirmations: this.conf(c.block) } : undefined;
}
deck(address: string, offset: number, limit: number) {
this.deckCalls++;
assert.ok(limit <= 24, 'ledger pages are at most 24');
const mine = this.cards.filter(c => c.owner === address);
const nfts = mine.slice(offset, offset + limit).map(c => ({ block: structuredClone(c.block), sequence: 0, confirmations: this.conf(c.block) }));
const result = { tip: this.tip, total: mine.length, next: offset + nfts.length < mine.length ? offset + nfts.length : null, nfts };
this.onDeck?.();
return result;
}
summary() { return { tip: this.tip, height: this.height, network: 'testnet', chainId: 'test' }; }
}
function fixture(wallets: Record<string, string[]> = { alice: [ALICE, ALICE2], bob: [BOB] }) {
const ledger = new FakeLedger();
const deps: OwnershipDeps = { ledger, accounts: { wallets: sub => (wallets[sub] ?? []).map(address => ({ address })) },
verifyIdToken: async (t: string): Promise<Account> => {
const m = /^good\.token\.(\w+)$/.exec(t);
if (m) return { sub: m[1], issuer: 'https://dex.example/', name: m[1], username: m[1] };
if (t === 'dex.is.down') throw new Error('fetch failed');
throw Object.assign(new Error('Token expired'), { status: 401 });
} };
return { ledger, deps };
}
/** n cards for `owner`, distinct pageIds starting at `firstPage`. */
const mintMany = (l: FakeLedger, owner: string, n: number, firstPage = 1) => Array.from({ length: n }, (_, i) => l.mint(owner, firstPage + i));
const ALICE_ACCT = { sub: 'alice' }, BOB_ACCT = { sub: 'bob' };
async function rejects(p: Promise<unknown>, code: string, tokenIds?: string[]) {
await assert.rejects(p, (e: unknown) => {
assert.ok(e instanceof DeckError, String(e));
assert.equal(e.code, code);
if (tokenIds) assert.deepEqual(e.tokenIds, tokenIds);
return true;
});
}
test('defaults are a 40-card deck, 4 copies per article, 1 confirmation', () => {
assert.deepEqual({ ...DEFAULT_OWNERSHIP_RULES }, { deckSize: 40, maxCopiesPerPage: 4, minConfirmations: 1 });
assert.equal(ownershipRules({ deckSize: 10, minConfirmations: undefined }).minConfirmations, 1);
assert.throws(() => ownershipRules({ deckSize: 0 }), RangeError);
assert.throws(() => ownershipRules({ maxCopiesPerPage: 1.5 }), RangeError);
assert.throws(() => ownershipRules({ minConfirmations: 0 }), RangeError);
});
test('verifyAccount maps token failures to DeckError(auth) and Dex outages to OwnershipUnavailable', async () => {
const { deps } = fixture();
assert.equal((await verifyAccount(deps, 'good.token.alice')).sub, 'alice');
for (const t of [undefined, '', 42, 'x'.repeat(9000)]) await rejects(verifyAccount(deps, t), 'auth');
await assert.rejects(verifyAccount(deps, 'bad'), (e: unknown) => e instanceof DeckError && e.code === 'auth' && e.status === 401 && e.message === 'Token expired');
await assert.rejects(verifyAccount(deps, 'dex.is.down'), (e: unknown) => e instanceof OwnershipUnavailable && e.status === 503);
});
test('resolveDeck accepts 40 owned cards across linked wallets and builds them from the chain, in order', async () => {
const { ledger, deps } = fixture();
const ids = [...mintMany(ledger, ALICE, 25, 1), ...mintMany(ledger, ALICE2, 15, 100)].reverse();
const cards = await resolveDeck(deps, ALICE_ACCT, ids);
assert.equal(cards.length, 40);
assert.deepEqual(cards.map(c => c.tokenId), ids);
const c = cards.find(x => x.pageId === 100)!;
const chain = ledger.nft(c.tokenId)!.block;
assert.equal(c.owner, ALICE2);
assert.equal(c.title, 'Article 100');
assert.equal(c.revisionId, 1100);
assert.equal(c.article.title, 'Article 100');
assert.equal(c.statsSnapshot.pageBytes, 5100);
assert.equal(c.blockHash, chain.hash);
assert.equal(c.powHash, chain.powHash);
assert.equal(c.height, chain.height);
});
test('resolveDeck takes token ids only: card data is never taken from the client', async () => {
const { ledger, deps } = fixture();
const ids = mintMany(ledger, ALICE, 40);
const forged = ids.map(tokenId => ({ tokenId, article: { title: 'Barack Obama' }, statsSnapshot: { pageBytes: 9e9 } }));
await rejects(resolveDeck(deps, ALICE_ACCT, forged), 'unknown-token');
});
test('resolveDeck enforces the exact deck size from ruleset data', async () => {
const { ledger, deps } = fixture();
const ids = mintMany(ledger, ALICE, 41);
for (const deck of [ids.slice(0, 39), ids, [], 'nope', null, Array(10_000).fill(ids[0])]) await rejects(resolveDeck(deps, ALICE_ACCT, deck), 'size');
assert.equal((await resolveDeck(deps, ALICE_ACCT, ids.slice(0, 10), { deckSize: 10 })).length, 10, 'a testnet mode may lower deckSize');
});
test('resolveDeck rejects malformed and duplicated token ids', async () => {
const { ledger, deps } = fixture();
const ids = mintMany(ledger, ALICE, 40);
await rejects(resolveDeck(deps, ALICE_ACCT, [...ids.slice(0, 39), 'ABC']), 'unknown-token', ['ABC']);
await rejects(resolveDeck(deps, ALICE_ACCT, [...ids.slice(0, 39), ids[0]]), 'duplicate-token', [ids[0]]);
});
test('resolveDeck requires a linked wallet', async () => {
const { ledger, deps } = fixture();
const ids = mintMany(ledger, ALICE, 40);
await assert.rejects(resolveDeck(deps, { sub: 'stranger' }, ids), (e: unknown) => e instanceof DeckError && e.code === 'not-owned' && e.status === 403 && /Link a wallet/.test(e.message));
});
test('resolveDeck rejects unknown cards and cards owned by someone else, listing every one', async () => {
const { ledger, deps } = fixture();
const ids = mintMany(ledger, ALICE, 38);
const bobs = mintMany(ledger, BOB, 2, 500);
await rejects(resolveDeck(deps, ALICE_ACCT, [...ids, ...bobs]), 'not-owned', bobs);
await rejects(resolveDeck(deps, ALICE_ACCT, [...ids, hex('nope'), bobs[0]]), 'unknown-token', [hex('nope')]);
// Bob cannot field Alice's cards either, even though they exist.
await rejects(resolveDeck(deps, BOB_ACCT, [...ids, ...bobs]), 'not-owned', ids);
});
test('ownership follows transfers: the current owner, not the miner, may play the card', async () => {
const { ledger, deps } = fixture();
const ids = mintMany(ledger, ALICE, 40);
ledger.transfer(ids[7], BOB);
await rejects(resolveDeck(deps, ALICE_ACCT, ids), 'not-owned', [ids[7]]);
const cards = await resolveDeck(deps, BOB_ACCT, [ids[7], ...mintMany(ledger, BOB, 39, 300)]);
assert.equal(cards[0].owner, BOB);
});
test('resolveDeck requires minConfirmations (3 for rated play)', async () => {
const { ledger, deps } = fixture();
const ids = mintMany(ledger, ALICE, 40);
// The last card has 1 confirmation, the one before it 2.
await rejects(resolveDeck(deps, ALICE_ACCT, ids, { minConfirmations: 3 }), 'unconfirmed', ids.slice(38));
ledger.mineEmpty(2);
assert.equal((await resolveDeck(deps, ALICE_ACCT, ids, { minConfirmations: 3 })).length, 40);
});
test('duplicates of an article count as separate cards, up to 4 copies per pageId', async () => {
const { ledger, deps } = fixture();
const base = mintMany(ledger, ALICE, 35, 1);
const copies = Array.from({ length: 5 }, () => ledger.mint(ALICE, 777));
await assert.rejects(resolveDeck(deps, ALICE_ACCT, [...base, ...copies]),
(e: unknown) => e instanceof DeckError && e.code === 'copy-limit' && e.pageId === 777 && e.tokenIds.length === 5);
const cards = await resolveDeck(deps, ALICE_ACCT, [...base, ...copies.slice(0, 4), ledger.mint(ALICE, 900)]);
assert.equal(cards.filter(c => c.pageId === 777).length, 4);
assert.equal((await resolveDeck(deps, ALICE_ACCT, [...base, ...copies], { maxCopiesPerPage: 5 })).length, 40, 'the copy limit is ruleset data');
});
test('playableCount applies the copy limit', () => {
const cards = [1, 1, 1, 1, 1, 1, 2, 3].map(pageId => ({ pageId }));
assert.equal(playableCount(cards, 4), 6);
assert.equal(playableCount(cards, 1), 3);
});
test('collection lists every owned card across wallets with no 128-block cap', async () => {
const { ledger, deps } = fixture();
mintMany(ledger, ALICE, 150, 1);
mintMany(ledger, BOB, 10, 1000);
mintMany(ledger, ALICE2, 3, 2000);
const cards = await collection(deps, ALICE_ACCT);
assert.equal(cards.length, 153);
assert.equal(new Set(cards.map(x => x.tokenId)).size, 153);
assert.ok(cards.every(x => x.owner === ALICE || x.owner === ALICE2));
const r = collectionResponse(deps, 'alice');
assert.equal(r.owned, 153); assert.equal(r.playable, 153); assert.equal(r.needed, 0); assert.equal(r.eligible, true);
assert.deepEqual(r.wallets, [ALICE, ALICE2]);
assert.equal(r.tip, ledger.tip);
assert.deepEqual(await collection(deps, { sub: 'stranger' }), []);
});
test('collection shows progress toward 40 and applies the copy limit to eligibility', () => {
const { ledger, deps } = fixture();
mintMany(ledger, ALICE, 20, 1);
for (let i = 0; i < 10; i++) ledger.mint(ALICE, 4242);
const c = collectionResponse(deps, 'alice');
assert.equal(c.owned, 30); assert.equal(c.playable, 24); assert.equal(c.needed, 16); assert.equal(c.eligible, false);
assert.equal(c.deckSize, 40); assert.equal(c.copyLimit, 4); assert.equal(c.maxCopiesPerPage, 4);
assert.equal(collectionResponse(deps, 'alice', { deckSize: 20 }).eligible, true);
const none = collectionResponse(deps, 'stranger');
assert.equal(none.owned, 0); assert.equal(none.needed, 40); assert.deepEqual(none.cards, []);
});
test('collection only counts cards with enough confirmations', async () => {
const { ledger, deps } = fixture();
mintMany(ledger, ALICE, 5);
assert.equal((await collection(deps, ALICE_ACCT, { minConfirmations: 3 })).length, 3);
});
test('collection restarts when the tip moves mid-scan and gives up if it never settles', async () => {
const { ledger, deps } = fixture();
mintMany(ledger, ALICE, 60);
let moves = 1;
ledger.onDeck = () => { if (moves-- > 0) ledger.mint(ALICE, 9999); };
const c = collectionResponse(deps, 'alice');
assert.equal(c.owned, 61);
assert.equal(c.tip, ledger.tip);
ledger.onDeck = () => { ledger.mineEmpty(); };
await assert.rejects(collection(deps, ALICE_ACCT), OwnershipUnavailable);
});
async function serve(router: express.Router) {
const app = express();
app.use('/api/game/collection', router);
const server = app.listen(0, '127.0.0.1');
await new Promise(r => server.once('listening', r));
const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}/api/game/collection`;
return { base, close: () => new Promise(r => server.close(r)) };
}
test('GET /api/game/collection requires a verified eom.dev token (local loopback only, no upstream)', async () => {
const { ledger, deps } = fixture();
mintMany(ledger, ALICE, 23);
const { base, close } = await serve(collectionRouter(deps));
const as = (t: string) => ({ headers: { authorization: `Bearer ${t}` } });
try {
let res = await fetch(base);
assert.equal(res.status, 401);
res = await fetch(base, as('bad.token.x!'));
assert.equal(res.status, 401);
res = await fetch(base, as('expired.token.x'));
assert.equal(res.status, 401);
assert.equal((await res.json()).error, 'Token expired');
res = await fetch(base, as('dex.is.down'));
assert.equal(res.status, 503);
res = await fetch(`${base}?minConfirmations=abc`, as('good.token.alice'));
assert.equal(res.status, 400);
res = await fetch(base, as('good.token.alice'));
assert.equal(res.status, 200);
assert.equal(res.headers.get('cache-control'), 'no-store');
const body = await res.json();
assert.equal(body.owned, 23); assert.equal(body.playable, 23); assert.equal(body.needed, 17);
assert.equal(body.eligible, false); assert.equal(body.deckSize, 40); assert.equal(body.copyLimit, 4);
assert.equal(body.cards.length, 23);
assert.equal(body.cards[0].title, 'Article 1');
assert.equal(body.cards[0].pageId, 1);
res = await fetch(`${base}?minConfirmations=3`, as('good.token.alice'));
assert.equal((await res.json()).owned, 21);
res = await fetch(base, as('good.token.bob'));
assert.equal((await res.json()).owned, 0);
} finally { await close(); }
});
test('GET /api/game/collection attaches the injected duel card when one is ready, and omits it otherwise', async () => {
const { ledger, deps } = fixture();
mintMany(ledger, ALICE, 3);
const duelCard = (c: { pageId: number }) => {
if (c.pageId === 2) return undefined; // profile pending
if (c.pageId === 3) throw new Error('boom'); // never breaks the collection
return { kind: 'Figure', pageId: c.pageId };
};
const { base, close } = await serve(collectionRouter({ ...deps, duelCard }));
try {
const body = await (await fetch(base, { headers: { authorization: 'Bearer good.token.alice' } })).json();
assert.deepEqual(body.cards.map((c: { duel?: unknown }) => c.duel), [{ kind: 'Figure', pageId: 1 }, undefined, undefined]);
assert.ok(!('duel' in body.cards[1]));
} finally { await close(); }
});