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>
205 lines
10 KiB
TypeScript
205 lines
10 KiB
TypeScript
// Card identity (engineer WS E, data review §3): the off-chain, mutable facts about a card's article
|
|
// (P31/P279 classes, a few Wikidata claims, categories, outlinks) frozen ONCE per tokenId, the first time
|
|
// the card is seen, so that a later Wikipedia/Wikidata edit can never retype a card someone owns.
|
|
//
|
|
// - On-chain data (article, statsSnapshot) stays the source of truth for everything it covers.
|
|
// - Identities are never fetched at match time. They are pre-baked in the background
|
|
// (scripts/night2/prebake-identity.ts), from cached data or through an injected IdentitySource that
|
|
// must use the process-wide Wikimedia client on its `background` lane. This file performs no I/O
|
|
// besides the sqlite store and never calls fetch itself.
|
|
// - First write wins: `freeze` never overwrites an existing record (data §3 "freeze at first sight").
|
|
import { DatabaseSync } from 'node:sqlite';
|
|
import { createHash } from 'node:crypto';
|
|
import { join, resolve } from 'node:path';
|
|
|
|
export const IDENTITY_VERSION = 1;
|
|
/** Where hosts keep the store: next to the ledger, `$WIKIDECK_DATA_DIR/card-identity.sqlite` (default ./data). */
|
|
export function identityStoreFile(env: NodeJS.ProcessEnv = process.env): string {
|
|
return join(env.WIKIDECK_DATA_DIR ?? resolve('data'), 'card-identity.sqlite');
|
|
}
|
|
|
|
/** Same shape as shared/duel/classify.ts `WikidataClass` (duel-cards, #70). */
|
|
export type WikidataClass = { id: string; label: string };
|
|
/**
|
|
* A frozen card identity. Its profile fields are structurally the `CardProfile` that duel-cards'
|
|
* `derive()` reads (shared/duel/classify.ts), so `toProfile(identity)` can be passed straight in.
|
|
*/
|
|
export type CardIdentity = {
|
|
version: typeof IDENTITY_VERSION;
|
|
tokenId: string;
|
|
pageId: number;
|
|
title: string;
|
|
/** article.revisionId from the mint block. */
|
|
mintRevisionId: number | null;
|
|
/** The live revision the off-chain facts were read from (data §3; may differ from the mint revision). */
|
|
fetchedRevisionId: number | null;
|
|
wikidataId: string | null;
|
|
wikidataRev: number | null;
|
|
/** Wikipedia short description. */
|
|
description: string | null;
|
|
/** Non-hidden category titles without the "Category:" prefix, sorted. */
|
|
categories: string[];
|
|
/** P31 (instance of). */
|
|
instanceOf: WikidataClass[];
|
|
/** P279 of the item, or its P31 classes' superclasses, nearest first. */
|
|
subclassOf: WikidataClass[];
|
|
/** P17 / P27 country Q-ids, sorted. */
|
|
countries: string[];
|
|
/** Years from P569/P570/P571/P580/P585 (negative = BCE), sorted. */
|
|
years: number[];
|
|
/** P570 (date of death) present. */
|
|
died: boolean;
|
|
/** P625 or prop=coordinates, [lat, lon]. */
|
|
coords: [number, number] | null;
|
|
/** ns0 outlinks as pageIds, sorted, deduplicated (Connected, Linked tier). Empty when unknown. */
|
|
links: number[];
|
|
/** Item Q-ids cited by the frozen claims (P17, P27, P131, P361, P106, ...). */
|
|
cites: string[];
|
|
/** sha256 of `links`, so match records can log a short fingerprint. */
|
|
linksHash: string;
|
|
/** Where the facts came from: an offline cache (e.g. card-sample.json) or a live background fetch. */
|
|
source: 'cache' | 'wikimedia';
|
|
frozenAt: string;
|
|
};
|
|
|
|
/** What a source knows about an article; any field may be missing. */
|
|
export type IdentityFacts = Partial<Pick<CardIdentity, 'fetchedRevisionId' | 'wikidataId' | 'wikidataRev' | 'description'
|
|
| 'categories' | 'instanceOf' | 'subclassOf' | 'countries' | 'years' | 'died' | 'coords' | 'links' | 'cites'>>;
|
|
/** The minimum the chain tells us about a card (built from its mint block, never from client JSON). */
|
|
export type ChainArticle = { tokenId: string; pageId: number; title: string; revisionId?: number | null };
|
|
|
|
/**
|
|
* A source of identity facts. A live implementation must route every request through the shared
|
|
* Wikimedia client on the background lane (never the mint or interactive lanes) and batch where it
|
|
* can. Returning `undefined` for a page means "unknown for now": nothing is frozen and it is retried
|
|
* on a later run.
|
|
*/
|
|
export interface IdentitySource {
|
|
readonly kind: CardIdentity['source'];
|
|
lookup(articles: ChainArticle[]): Promise<Map<number, IdentityFacts | undefined>>;
|
|
}
|
|
|
|
export function linksHash(links: readonly number[]): string {
|
|
return createHash('sha256').update(JSON.stringify(links)).digest('hex');
|
|
}
|
|
|
|
const QID = /^Q\d+$/;
|
|
const uniqStrings = (xs: readonly unknown[] | undefined) => [...new Set((xs ?? []).filter((x): x is string => typeof x === 'string'))].sort();
|
|
const uniqInts = (xs: readonly unknown[] | undefined) =>
|
|
[...new Set((xs ?? []).filter((x): x is number => Number.isSafeInteger(x)))].sort((a, b) => a - b);
|
|
const classes = (xs: readonly WikidataClass[] | undefined) =>
|
|
(xs ?? []).filter(c => c && QID.test(c.id)).map(c => ({ id: c.id, label: typeof c.label === 'string' ? c.label : '' }));
|
|
|
|
/** Pure: build a frozen identity from chain data plus whatever facts a source returned. */
|
|
export function buildIdentity(article: ChainArticle, facts: IdentityFacts, source: CardIdentity['source'], now: Date): CardIdentity {
|
|
const links = uniqInts(facts.links);
|
|
const coords = facts.coords && facts.coords.length === 2 && facts.coords.every(Number.isFinite) ? [facts.coords[0], facts.coords[1]] as [number, number] : null;
|
|
return {
|
|
version: IDENTITY_VERSION,
|
|
tokenId: article.tokenId,
|
|
pageId: article.pageId,
|
|
title: article.title,
|
|
mintRevisionId: article.revisionId ?? null,
|
|
fetchedRevisionId: facts.fetchedRevisionId ?? null,
|
|
wikidataId: facts.wikidataId && QID.test(facts.wikidataId) ? facts.wikidataId : null,
|
|
wikidataRev: facts.wikidataRev ?? null,
|
|
description: typeof facts.description === 'string' ? facts.description : null,
|
|
categories: uniqStrings(facts.categories),
|
|
instanceOf: classes(facts.instanceOf),
|
|
subclassOf: classes(facts.subclassOf),
|
|
countries: uniqStrings(facts.countries),
|
|
years: uniqInts(facts.years),
|
|
died: facts.died === true,
|
|
coords,
|
|
links,
|
|
cites: uniqStrings(facts.cites).filter(q => QID.test(q)),
|
|
linksHash: linksHash(links),
|
|
source,
|
|
frozenAt: now.toISOString(),
|
|
};
|
|
}
|
|
|
|
/** The duel-cards `CardProfile` view of an identity (structural; no import, so no stacked PR). */
|
|
export function toProfile(i: CardIdentity) {
|
|
return { wikidataId: i.wikidataId, description: i.description, categories: i.categories, instanceOf: i.instanceOf,
|
|
subclassOf: i.subclassOf, countries: i.countries, years: i.years, died: i.died, links: i.links, cites: i.cites,
|
|
...(i.fetchedRevisionId != null ? { fetchedRevisionId: i.fetchedRevisionId } : {}) };
|
|
}
|
|
|
|
/** Persistent per-token identity store. Records are immutable once written. */
|
|
export class IdentityStore {
|
|
readonly #db: DatabaseSync;
|
|
constructor(file: string) {
|
|
this.#db = new DatabaseSync(file);
|
|
this.#db.exec(`CREATE TABLE IF NOT EXISTS card_identity (
|
|
token_id TEXT PRIMARY KEY, page_id INTEGER NOT NULL, version INTEGER NOT NULL, body TEXT NOT NULL)`);
|
|
}
|
|
get(tokenId: string): CardIdentity | undefined {
|
|
const row = this.#db.prepare('SELECT body FROM card_identity WHERE token_id = ?').get(tokenId) as { body: string } | undefined;
|
|
return row ? JSON.parse(row.body) as CardIdentity : undefined;
|
|
}
|
|
has(tokenId: string): boolean { return this.get(tokenId) !== undefined; }
|
|
/** Freeze at first sight: returns the stored record, which is the earlier one if it already existed. */
|
|
freeze(identity: CardIdentity): CardIdentity {
|
|
this.#db.prepare('INSERT OR IGNORE INTO card_identity (token_id, page_id, version, body) VALUES (?, ?, ?, ?)')
|
|
.run(identity.tokenId, identity.pageId, identity.version, JSON.stringify(identity));
|
|
return this.get(identity.tokenId)!;
|
|
}
|
|
/** Freeze several in one transaction (one fsync per batch, not per card). */
|
|
freezeMany(identities: CardIdentity[]): void {
|
|
this.#db.exec('BEGIN');
|
|
try { for (const i of identities) this.freeze(i); this.#db.exec('COMMIT'); }
|
|
catch (e) { this.#db.exec('ROLLBACK'); throw e; }
|
|
}
|
|
count(): number { return (this.#db.prepare('SELECT COUNT(*) AS n FROM card_identity').get() as { n: number }).n; }
|
|
all(): CardIdentity[] {
|
|
return (this.#db.prepare('SELECT body FROM card_identity ORDER BY token_id').all() as { body: string }[]).map(r => JSON.parse(r.body));
|
|
}
|
|
close() { this.#db.close(); }
|
|
}
|
|
|
|
export type PrebakeReport = { seen: number; alreadyFrozen: number; frozen: number; unknown: number };
|
|
|
|
/**
|
|
* Freeze identities for every card not yet in the store, asking the source in batches. The caller
|
|
* controls pacing (batch size, and the source's client controls request rate).
|
|
*/
|
|
export async function prebake(store: IdentityStore, source: IdentitySource, articles: ChainArticle[],
|
|
opts: { batchSize?: number; now?: () => Date } = {}): Promise<PrebakeReport> {
|
|
const batchSize = Math.max(1, Math.min(50, opts.batchSize ?? 50)), now = opts.now ?? (() => new Date());
|
|
const seenTokens = new Set<string>(), todo: ChainArticle[] = [];
|
|
let alreadyFrozen = 0;
|
|
for (const a of articles) {
|
|
if (seenTokens.has(a.tokenId)) continue;
|
|
seenTokens.add(a.tokenId);
|
|
if (store.has(a.tokenId)) alreadyFrozen++; else todo.push(a);
|
|
}
|
|
let frozen = 0, unknown = 0;
|
|
for (let i = 0; i < todo.length; i += batchSize) {
|
|
const batch = todo.slice(i, i + batchSize), facts = await source.lookup(batch), ready = [];
|
|
for (const a of batch) {
|
|
const f = facts.get(a.pageId);
|
|
if (!f) { unknown++; continue; }
|
|
ready.push(buildIdentity(a, f, source.kind, now()));
|
|
}
|
|
store.freezeMany(ready); frozen += ready.length;
|
|
}
|
|
return { seen: seenTokens.size, alreadyFrozen, frozen, unknown };
|
|
}
|
|
|
|
/** Offline source: facts from an already-cached card file such as docs/game/card-sample.json. */
|
|
export function cachedSource(cards: readonly { pageId: number; wikidataId?: string | null; revisionId?: number | null;
|
|
description?: string | null; instanceOf?: WikidataClass[]; categories?: string[] }[]): IdentitySource {
|
|
const byPage = new Map(cards.map(c => [c.pageId, c]));
|
|
return {
|
|
kind: 'cache',
|
|
async lookup(articles) {
|
|
return new Map(articles.map(a => {
|
|
const c = byPage.get(a.pageId);
|
|
return [a.pageId, c ? { fetchedRevisionId: c.revisionId ?? null, wikidataId: c.wikidataId ?? null,
|
|
description: c.description ?? null, instanceOf: c.instanceOf ?? [], categories: c.categories ?? [] } : undefined];
|
|
}));
|
|
},
|
|
};
|
|
}
|