testnet-ops: identity fields match duel-cards CardProfile (links as pageIds, years, cites, subclassOf, description); toProfile()

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 21:46:09 -05:00
co-authored by Claude Opus 5.5
parent 36cbaccd42
commit 47cab9f619
3 changed files with 72 additions and 35 deletions
+1 -1
View File
@@ -50,7 +50,7 @@ Use a separate browser profile, or a private window, per player, because a brows
- **Difficulty (for mobile mining, #59):** at block ~90, an accepted block took between about 2 K and 130 K hashes. That is up to ~8 min at the 4-worker r350 rate of ~250 H/s. One light-mode thread on the emulator is far slower, so expect a long wait per block, with high variance. - **Difficulty (for mobile mining, #59):** at block ~90, an accepted block took between about 2 K and 130 K hashes. That is up to ~8 min at the 4-worker r350 rate of ~250 H/s. One light-mode thread on the emulator is far slower, so expect a long wait per block, with high variance.
## Card identity pre-bake (engineer WS E) ## Card identity pre-bake (engineer WS E)
- `server/game/identity.ts` is a persistent per-token store (`node:sqlite`). It freezes each card's off-chain identity at first sight and never rewrites it. The identity covers P31 classes, categories, country, dates, coordinates and an outlinks hash. - `server/game/identity.ts` is a persistent per-token store (`node:sqlite`). It freezes each card's off-chain identity at first sight and never rewrites it. The identity covers P31/P279 classes, description, categories, countries, years, coordinates and outlink pageIds. Its fields match duel-cards' `CardProfile` (#70), and `toProfile()` returns that view.
- `scripts/night2/prebake-identity.ts --node <url> --store <file> [--cards <cached.json> ...]` reads the canonical chain from one node and freezes what the cached card files know. - `scripts/night2/prebake-identity.ts --node <url> --store <file> [--cards <cached.json> ...]` reads the canonical chain from one node and freezes what the cached card files know.
- It **never calls Wikimedia itself**. - It **never calls Wikimedia itself**.
- Live facts arrive only through the wikimedia team's client on its `background` lane (#62), once that client has merged. - Live facts arrive only through the wikimedia team's client on its `background` lane (#62), once that client has merged.
+58 -27
View File
@@ -1,5 +1,5 @@
// Card identity (engineer WS E, data review §3): the off-chain, mutable facts about a card's article // Card identity (engineer WS E, data review §3): the off-chain, mutable facts about a card's article
// (P31 classes, a few Wikidata claims, categories, outlinks) frozen ONCE per tokenId, the first time // (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. // 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. // - On-chain data (article, statsSnapshot) stays the source of truth for everything it covers.
@@ -13,8 +13,12 @@ import { createHash } from 'node:crypto';
export const IDENTITY_VERSION = 1; export const IDENTITY_VERSION = 1;
export type WikidataClass = { id: string; label?: string }; /** Same shape as shared/duel/classify.ts `WikidataClass` (duel-cards, #70). */
export type IdentityDates = { birth?: string; death?: string; inception?: string; pointInTime?: string; start?: string }; 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 = { export type CardIdentity = {
version: typeof IDENTITY_VERSION; version: typeof IDENTITY_VERSION;
tokenId: string; tokenId: string;
@@ -22,29 +26,40 @@ export type CardIdentity = {
title: string; title: string;
/** article.revisionId from the mint block. */ /** article.revisionId from the mint block. */
mintRevisionId: number | null; mintRevisionId: number | null;
/** The revision the off-chain facts were read from (may differ from the mint revision). */ /** The live revision the off-chain facts were read from (data §3; may differ from the mint revision). */
fetchedRevisionId: number | null; fetchedRevisionId: number | null;
wikidataId: string | null; wikidataId: string | null;
wikidataRev: number | null; wikidataRev: number | null;
instanceOf: WikidataClass[]; /** Wikipedia short description. */
description: string | null;
/** Non-hidden category titles without the "Category:" prefix, sorted. */
categories: string[]; categories: string[];
/** P17 (country) or P27 (citizenship) Q-ids. */ /** P31 (instance of). */
country: string[]; instanceOf: WikidataClass[];
dates: IdentityDates; /** 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]. */ /** P625 or prop=coordinates, [lat, lon]. */
coords: [number, number] | null; coords: [number, number] | null;
/** Main-namespace outlink titles, sorted, deduplicated. Empty when unknown. */ /** ns0 outlinks as pageIds, sorted, deduplicated (Connected, Linked tier). Empty when unknown. */
outlinks: string[]; links: number[];
/** sha256 of the sorted outlinks, so match records can log a short fingerprint. */ /** Item Q-ids cited by the frozen claims (P17, P27, P131, P361, P106, ...). */
outlinksHash: string; 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. */ /** Where the facts came from: an offline cache (e.g. card-sample.json) or a live background fetch. */
source: 'cache' | 'wikimedia'; source: 'cache' | 'wikimedia';
frozenAt: string; frozenAt: string;
}; };
/** What a source knows about an article; any field may be missing. */ /** What a source knows about an article; any field may be missing. */
export type IdentityFacts = Partial<Pick<CardIdentity, 'fetchedRevisionId' | 'wikidataId' | 'wikidataRev' | 'instanceOf' export type IdentityFacts = Partial<Pick<CardIdentity, 'fetchedRevisionId' | 'wikidataId' | 'wikidataRev' | 'description'
| 'categories' | 'country' | 'dates' | 'coords' | 'outlinks'>>; | '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). */ /** 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 }; export type ChainArticle = { tokenId: string; pageId: number; title: string; revisionId?: number | null };
@@ -59,15 +74,20 @@ export interface IdentitySource {
lookup(articles: ChainArticle[]): Promise<Map<number, IdentityFacts | undefined>>; lookup(articles: ChainArticle[]): Promise<Map<number, IdentityFacts | undefined>>;
} }
export function outlinksHash(outlinks: readonly string[]): string { export function linksHash(links: readonly number[]): string {
return createHash('sha256').update(JSON.stringify(outlinks)).digest('hex'); return createHash('sha256').update(JSON.stringify(links)).digest('hex');
} }
const uniqSorted = (xs: readonly string[] | undefined) => [...new Set((xs ?? []).filter(x => typeof x === 'string'))].sort(); 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. */ /** 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 { export function buildIdentity(article: ChainArticle, facts: IdentityFacts, source: CardIdentity['source'], now: Date): CardIdentity {
const outlinks = uniqSorted(facts.outlinks); 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; const coords = facts.coords && facts.coords.length === 2 && facts.coords.every(Number.isFinite) ? [facts.coords[0], facts.coords[1]] as [number, number] : null;
return { return {
version: IDENTITY_VERSION, version: IDENTITY_VERSION,
@@ -76,20 +96,31 @@ export function buildIdentity(article: ChainArticle, facts: IdentityFacts, sourc
title: article.title, title: article.title,
mintRevisionId: article.revisionId ?? null, mintRevisionId: article.revisionId ?? null,
fetchedRevisionId: facts.fetchedRevisionId ?? null, fetchedRevisionId: facts.fetchedRevisionId ?? null,
wikidataId: facts.wikidataId && /^Q\d+$/.test(facts.wikidataId) ? facts.wikidataId : null, wikidataId: facts.wikidataId && QID.test(facts.wikidataId) ? facts.wikidataId : null,
wikidataRev: facts.wikidataRev ?? null, wikidataRev: facts.wikidataRev ?? null,
instanceOf: (facts.instanceOf ?? []).filter(c => /^Q\d+$/.test(c.id)).map(c => c.label ? { id: c.id, label: c.label } : { id: c.id }), description: typeof facts.description === 'string' ? facts.description : null,
categories: uniqSorted(facts.categories), categories: uniqStrings(facts.categories),
country: uniqSorted(facts.country).filter(q => /^Q\d+$/.test(q)), instanceOf: classes(facts.instanceOf),
dates: { ...(facts.dates ?? {}) }, subclassOf: classes(facts.subclassOf),
countries: uniqStrings(facts.countries),
years: uniqInts(facts.years),
died: facts.died === true,
coords, coords,
outlinks, links,
outlinksHash: outlinksHash(outlinks), cites: uniqStrings(facts.cites).filter(q => QID.test(q)),
linksHash: linksHash(links),
source, source,
frozenAt: now.toISOString(), 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. */ /** Persistent per-token identity store. Records are immutable once written. */
export class IdentityStore { export class IdentityStore {
readonly #db: DatabaseSync; readonly #db: DatabaseSync;
@@ -153,7 +184,7 @@ export async function prebake(store: IdentityStore, source: IdentitySource, arti
/** Offline source: facts from an already-cached card file such as docs/game/card-sample.json. */ /** 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; export function cachedSource(cards: readonly { pageId: number; wikidataId?: string | null; revisionId?: number | null;
instanceOf?: WikidataClass[]; categories?: string[] }[]): IdentitySource { description?: string | null; instanceOf?: WikidataClass[]; categories?: string[] }[]): IdentitySource {
const byPage = new Map(cards.map(c => [c.pageId, c])); const byPage = new Map(cards.map(c => [c.pageId, c]));
return { return {
kind: 'cache', kind: 'cache',
@@ -161,7 +192,7 @@ export function cachedSource(cards: readonly { pageId: number; wikidataId?: stri
return new Map(articles.map(a => { return new Map(articles.map(a => {
const c = byPage.get(a.pageId); const c = byPage.get(a.pageId);
return [a.pageId, c ? { fetchedRevisionId: c.revisionId ?? null, wikidataId: c.wikidataId ?? null, return [a.pageId, c ? { fetchedRevisionId: c.revisionId ?? null, wikidataId: c.wikidataId ?? null,
instanceOf: c.instanceOf ?? [], categories: c.categories ?? [] } : undefined]; description: c.description ?? null, instanceOf: c.instanceOf ?? [], categories: c.categories ?? [] } : undefined];
})); }));
}, },
}; };
+13 -7
View File
@@ -4,7 +4,7 @@ import assert from 'node:assert/strict';
import { mkdtempSync, readFileSync, rmSync } from 'node:fs'; import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os'; import { tmpdir } from 'node:os';
import { join } from 'node:path'; import { join } from 'node:path';
import { IdentityStore, buildIdentity, cachedSource, outlinksHash, prebake, import { IdentityStore, buildIdentity, cachedSource, linksHash, prebake, toProfile,
type ChainArticle, type IdentitySource } from '../server/game/identity.ts'; type ChainArticle, type IdentitySource } from '../server/game/identity.ts';
const sample = JSON.parse(readFileSync(new URL('../docs/game/card-sample.json', import.meta.url), 'utf8')).cards as any[]; const sample = JSON.parse(readFileSync(new URL('../docs/game/card-sample.json', import.meta.url), 'utf8')).cards as any[];
@@ -28,6 +28,10 @@ test('no fetch: pre-bake from the cached sample freezes every sample card', asyn
assert.deepEqual(salah.instanceOf, [{ id: 'Q5', label: 'human' }]); assert.deepEqual(salah.instanceOf, [{ id: 'Q5', label: 'human' }]);
assert.equal(salah.source, 'cache'); assert.equal(salah.source, 'cache');
assert.ok(salah.categories.includes('Sultans of Aceh')); assert.ok(salah.categories.includes('Sultans of Aceh'));
assert.equal(salah.description, 'Sultan of Aceh (1530–1537/9)');
const profile = toProfile(salah);
assert.deepEqual(profile.instanceOf, [{ id: 'Q5', label: 'human' }]);
assert.equal(profile.fetchedRevisionId, 1358732737);
} finally { globalThis.fetch = realFetch; store.close(); done(); } } finally { globalThis.fetch = realFetch; store.close(); done(); }
}); });
@@ -35,8 +39,8 @@ test('freeze at first sight: a later, different profile never overwrites the sto
const { store, done } = tmpStore(); const { store, done } = tmpStore();
try { try {
const a = art(sample[0], 1); const a = art(sample[0], 1);
const first = store.freeze(buildIdentity(a, { instanceOf: [{ id: 'Q5' }] }, 'cache', now())); const first = store.freeze(buildIdentity(a, { instanceOf: [{ id: 'Q5', label: 'human' }] }, 'cache', now()));
const second = store.freeze(buildIdentity(a, { instanceOf: [{ id: 'Q515' }] }, 'wikimedia', new Date())); const second = store.freeze(buildIdentity(a, { instanceOf: [{ id: 'Q515', label: 'city' }] }, 'wikimedia', new Date()));
assert.deepEqual(second, first); assert.deepEqual(second, first);
assert.equal(store.get(a.tokenId)!.instanceOf[0].id, 'Q5'); assert.equal(store.get(a.tokenId)!.instanceOf[0].id, 'Q5');
const again = await prebake(store, cachedSource(sample), [a, a], { now }); const again = await prebake(store, cachedSource(sample), [a, a], { now });
@@ -60,7 +64,7 @@ test('sources are asked in bounded batches and identities persist across reopen'
const calls: number[] = []; const calls: number[] = [];
const source: IdentitySource = { kind: 'wikimedia', async lookup(batch) { const source: IdentitySource = { kind: 'wikimedia', async lookup(batch) {
calls.push(batch.length); calls.push(batch.length);
return new Map(batch.map(a => [a.pageId, { outlinks: ['B', 'A', 'A'], coords: [1, 2] as [number, number], country: ['Q30', 'bad'] }])); return new Map(batch.map(a => [a.pageId, { links: [7, 3, 3, 1.5], coords: [1, 2] as [number, number], cites: ['Q30', 'bad'], years: [1948, -44], died: true }]));
} }; } };
let store = new IdentityStore(join(dir, 'id.sqlite')); let store = new IdentityStore(join(dir, 'id.sqlite'));
await prebake(store, source, sample.slice(0, 12).map(art), { batchSize: 5, now }); await prebake(store, source, sample.slice(0, 12).map(art), { batchSize: 5, now });
@@ -68,9 +72,11 @@ test('sources are asked in bounded batches and identities persist across reopen'
store.close(); store.close();
store = new IdentityStore(join(dir, 'id.sqlite')); store = new IdentityStore(join(dir, 'id.sqlite'));
const one = store.get(art(sample[3], 3).tokenId)!; const one = store.get(art(sample[3], 3).tokenId)!;
assert.deepEqual(one.outlinks, ['A', 'B']); assert.deepEqual(one.links, [3, 7]);
assert.equal(one.outlinksHash, outlinksHash(['A', 'B'])); assert.equal(one.linksHash, linksHash([3, 7]));
assert.deepEqual(one.country, ['Q30']); assert.deepEqual(one.cites, ['Q30']);
assert.deepEqual(one.years, [-44, 1948]);
assert.equal(one.died, true);
assert.deepEqual(one.coords, [1, 2]); assert.deepEqual(one.coords, [1, 2]);
assert.equal(one.mintRevisionId, sample[3].revisionId); assert.equal(one.mintRevisionId, sample[3].revisionId);
assert.equal(store.count(), 12); assert.equal(store.count(), 12);