[duel-cards] profile.ts: build the frozen CardProfile from enrichment + wbgetentities (pure, no fetch)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 21:47:00 -05:00
co-authored by Claude Opus 5.5
parent 3c70f643f2
commit a8468dd96c
2 changed files with 185 additions and 0 deletions
+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));
}
+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'));
});