forked from WikiDeck/wikideck
Night 2 (2026-11-17), from the `claude/wikideck` fork's `night/2026-11-17` branch. It follows Night 1 (#22).
## What's in it
- **Duel engine** (fork #72, #80): 40-card decks of cards you own, Notability/Citations, keywords, effects T1–T12, Connected, a hidden-information-safe `viewFor`/`logFor`, and replay. Balance v1 tuning (#84) gives the first player about 51%.
- **Card profiles** (#70, #82): Figure, Location, Event, Institution or Doctrine, plus stats, keywords and rules text, all derived from real article data. Templates only.
- **Design and story** (#66, #69, #83): DUEL_DESIGN.md, plus the match log and the encyclopedic "Battle of X (2026)" recap.
- **PvP** (#74, #77, #81, #76, #85):
- The server checks ownership, and 40-card eligibility is enforced.
- Modes: Classic (ranked), Draft and Trending.
- Invites, quick match, Elo, a ladder and recap pages. Online matches render on the duel board.
- **Duel board UI** (#79): MTG-style card faces and combat declaration, built for 360 px first.
- **Polite Wikimedia client** (#73, #75): throttled, cached and identified requests, the mint-path fix, and a prefetch pool.
- **Android mining** (#78): native RandomX, as a sideload build. The emulator mined a testnet block.
- **Testnet ops** (#67, #68).
PR numbers refer to `claude/wikideck`.
## Status
- **Tests:** 423, of which 422 pass, 0 fail and 1 is skipped. The build is OK (`node:24-alpine`, `--network none`).
- **Testnet:** running this commit (036489c) on r350.
- **Untouched:** no changes to `server/testnet/consensus.ts`, `randomx.ts`, `native/` or the mainnet compose.
- **Review:** night-review reviewed fork #66–#79. #80–#85 came from the agents' unfinished branches and were not reviewed.
- **Known gaps:**
- The PvP end-to-end test hasn't been run (it needs two eom.dev accounts).
- Bot matches aren't reachable from Play.
- Card identity pre-bake hasn't been done.
- The RandomX verifier latch (`server/testnet/randomx.ts:140`) is still open.
This PR is for Eric to merge.
🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: WikiDeck/wikideck#23
Co-authored-by: Claude <claude@eom.dev>
145 lines
8.4 KiB
Markdown
145 lines
8.4 KiB
Markdown
# WikiDeck Night 2: design brief (locked decisions)
|
||
|
||
**Night 2:** 2026-11-17, 21:30 to **02:00 EST, hard stop**.
|
||
|
||
This brief merges three sources:
|
||
- the coordinator's plan, in `docs/night2/PLAN.md`
|
||
- four reviews (designer, engineer, data and critic), in `docs/night2/reviews/`
|
||
- **Eric's decisions on 2026-11-17**, which override anything in the reviews
|
||
|
||
Where a review disagrees with this file, **this file wins**. Where this file is silent, follow the reviews, in this order:
|
||
1. engineer, for architecture
|
||
2. designer, for rules
|
||
3. data, for derivation
|
||
4. critic, for process
|
||
|
||
## Eric's decisions (non-negotiable)
|
||
1. **A full 40-card, Magic-style game.**
|
||
- A deck is exactly 40 cards, and every card in it is an NFT the player owns.
|
||
- There are no loaners, Basics, filler or proxies.
|
||
2. **Players can't play until they own enough cards.**
|
||
- If a player owns fewer than 40 cards, the game shows their progress (for example "23 / 40 cards") and how to mine.
|
||
- There is no "practice with borrowed cards".
|
||
- The reviews' Basics, loaners, Signature card and the "Collection + Basics" model are **rejected**.
|
||
3. **PvP is first-class.** Bot matches exist, but only for eligible players.
|
||
4. **The mobile app must be able to mine.**
|
||
- Today `isNativeApp()` hides the mining panel, so mobile players can never earn cards.
|
||
- Fix it in the Android app.
|
||
- Write in `docs/night2/MOBILE_MINING.md` that Google Play and the App Store both prohibit on-device crypto mining, so for now the mining build is a sideloaded APK.
|
||
5. **Tone: lean in, Cards Against Humanity style.**
|
||
- Living people, tragedies, wars, disasters, crimes, diseases and dictators are all **ordinary cards with full mechanics**.
|
||
- There are no `solemn` flags, no special-casing and no softened verbs.
|
||
- The game takes itself completely seriously, and the comedy comes from the juxtapositions. Use the critic's S7 deadpan style guide: never wink, never comment on the matchup, and use encyclopedic texture with [n] citations.
|
||
- "Casualties" is fine.
|
||
- **One rule stays:** all generated text (rules text, match log, recap) is deterministic templates filled **only with real data from the card and the match**. Never use LLM prose, and never invent factual claims about real people (no made-up crimes, quotes or acts). Humour by juxtaposition is fine; fabricated facts about a real person are defamation.
|
||
6. **iOS is paused.** Don't touch `ios/` or the macOS VM.
|
||
7. **Wikimedia politeness by default** (the engineer's §4 and the data analyst's §5), including the mint-path bug (§9 below).
|
||
|
||
## Supply reality (design around it, don't fight it)
|
||
- **Mainnet:** 12 cards, all in one wallet. Consensus mints at most about 96 cards a day, network-wide. That's Eric's accepted trade-off: the game becomes playable as people mine.
|
||
- **Our testnet** (`deploy/night/`, on poweredge-r350):
|
||
- Wallets alice, bob, carol and dave own about 50 cards between them, with up to 40 more being mined now.
|
||
- The `testnet-ops` agent consolidates cards into **alice and bob** with on-chain transfers, so both reach 40 if supply allows.
|
||
- Deck size is **ruleset data** (`deckSize`, default 40). If the testnet can't reach 80 cards, the end-to-end test mode may set a lower `deckSize`. That's a testnet mode file only; production stays at 40.
|
||
- **Engine, simulation and balance work** uses the 236 real cards in `docs/game/card-sample.json` as the card pool. Build 40-card random decks from it. This needs no chain.
|
||
|
||
## Game rules core (designer §2, adapted to 40 cards)
|
||
- **Life:** each player starts with 20 Notability; at 0 you lose. Drawing from an empty library loses (the MTG rule). These are ruleset keys.
|
||
- **Opening:** hands of 7, with one mulligan (shuffle, draw 7, bottom 1). The first player skips their first draw.
|
||
- **Turn:** refresh, draw, main, combat, end.
|
||
- **Resources are a fixed income of Citations:** your maximum rises by 1 each turn, to a cap of 10. There are no land cards, so no land screw.
|
||
- Locations ramp at most +2 in total.
|
||
- Hand limit is 7.
|
||
- **Combat:**
|
||
- attack the opponent with untapped Figures, with summoning sickness ("Pending review")
|
||
- at most one blocker per attacker
|
||
- damage is simultaneous
|
||
- no trample, no first strike, no stack and no instant speed; Events are sorcery-speed
|
||
- **Clock:** 60 s per turn plus a 5-minute bank. No turn cap is required. If the sims show stalls, add `turnCap` as a ruleset key.
|
||
- **Card types** (designer §3 and data §1):
|
||
- **Figure:** a creature
|
||
- **Location:** a permanent with Territory or Garrison
|
||
- **Event:** sorcery-speed
|
||
- **Institution:** an artifact
|
||
- **Doctrine:** an Aura that attaches to a Figure, so *Tetrated dodecahedron* can buff *Cho Yang-ho*
|
||
- Classify with data §1's P31 → P279 anchor classes, falling back to categories, then the description, then Doctrine.
|
||
- Fix the `\bhuman\b` → People bug.
|
||
- Freeze each card's derived profile the first time the card is seen.
|
||
- **Factions ("Portals"):** designer §3.2. There are no colour restrictions in deckbuilding.
|
||
- **Stats:** data §2. Cost 1–6 comes from the percentile fame curve, with a fixed power+toughness budget per cost, so famous cards are bigger and pricier, not strictly better.
|
||
- **Keywords:** designer §3.4 and data §2, at most 2 per card, each triggered by real data:
|
||
- Protected
|
||
- Featured
|
||
- Translated
|
||
- Legacy
|
||
- Stub
|
||
- Well-sourced
|
||
- Multilingual
|
||
- Local
|
||
- **Connected:** the data team's tiers (data §4): Linked, Compatriot, Contemporary and Kin, from cached Wikidata claims and links.
|
||
- It gives +1/+1, or +2/+2 for a direct link.
|
||
- Aim for it to fire in 15–30% of pairs, tuned in the simulator.
|
||
- **Flavour text:** the first sentence of the on-chain `article.extract`.
|
||
|
||
## Story
|
||
- **Match log:** past-tense, encyclopedic and per player (`logFor`), with no hidden-information leaks.
|
||
- **Recap:** a "Battle of X (2026)" page after each match, with:
|
||
- an infobox: date, belligerents (the players), strength, casualties (the cards destroyed), result
|
||
- a narrative assembled from the log with 3–4 template variants per event, seeded deterministically
|
||
- References citing every card played, with revision ids
|
||
- "WikiDeck" branding, not Wikipedia's
|
||
- a shareable URL
|
||
|
||
## Modes (kept, now on the duel engine)
|
||
- **Classic:** constructed from your own 40+ cards. It's ranked.
|
||
- **Draft:** both players must be eligible. The pool is drawn from both players' collections, and drafted cards are used for that match only. Nothing moves on-chain.
|
||
- **Trending:** live pageview momentum changes stats (designer §5), from a daily refreshed cache.
|
||
- **Peer-hosted house rules:** stay data-only, with a versioned schema. Night 1 mode files are rejected cleanly.
|
||
|
||
## PvP (engineer §3)
|
||
- **Seats and ownership:**
|
||
- Seats are tied to eom.dev accounts (Dex) and their linked wallets.
|
||
- The host verifies **ownership on the server** (`ownership.ts`, using `ledger.nft()`) and builds each card from the chain.
|
||
- **Night 1's gaps to close:**
|
||
- the browser-side ownership check
|
||
- the 128-block snapshot cap
|
||
- starter decks dealt in `host.ts:144`
|
||
- **Matchmaking:** private lobbies, invite links, quick match, and an Elo ladder keyed to the account.
|
||
- **Transport:** keep polling, with a state version so unchanged polls return 204. Don't use long-polling.
|
||
|
||
## Wikimedia (engineer §4 and data §5)
|
||
**One process-wide client:**
|
||
- 1 request per second, burst 3, 1 request in flight per host
|
||
- priority lanes: mint, then interactive, then background
|
||
- `maxlag=5`
|
||
- honour `Retry-After`
|
||
- a circuit breaker after 3 consecutive 429s
|
||
- a daily cap
|
||
- a sqlite cache on disk with ETags
|
||
- a User-Agent with an operator contact (a config key that operators must set; the testnet uses the project URL)
|
||
|
||
**The mint path changes transport only:** request parameters stay byte-identical, and the cache is never used for mint data.
|
||
|
||
**Fix the mint bug:** a 429 on pageviews currently mints a card with `attention: null` forever (`enrichment.ts:145-164`). Fail and retry instead.
|
||
|
||
**Other changes:**
|
||
- Card faces in the client no longer trigger uncached upstream calls on every render.
|
||
- An article prefetch pool for mining templates (data §8).
|
||
|
||
**Tests make zero network calls.**
|
||
|
||
## Cut order if late
|
||
1. the Elo ladder (keep W/L)
|
||
2. quick match (keep invites)
|
||
3. Trending's live stats
|
||
4. the Kin and Contemporary tiers of Connected
|
||
5. recap polish (keep the plain log)
|
||
|
||
**Never cut:**
|
||
- the duel core
|
||
- 40-card owned-deck validation on the server
|
||
- PvP over invite links
|
||
- the Wikimedia client and mint fix
|
||
- mobile mining
|
||
- the recap (the story is the point)
|