# Historical question bank

The initial bank contains **184 questions and 5,636 eligible answer records**
covering the **22 senior men's World Cup finals from 1930 through 2022**. The
application should make this cutoff visible. No 2026 tournament facts are used.

Every published question retains the complete eligible set from the source
snapshot. The eight-answer minimum decides whether to include a question; it
does not limit the number of answers in an included question.

| Category | Questions | Eligibility |
|---|---:|---|
| World Cup teams | 22 | All teams that played in one finals tournament |
| Tournament scorers | 22 | All players with a credited goal in that tournament |
| Winning squads | 22 | Every player in the champion's registered squad |
| National squads | 45 | Other 2022 squads and other 2014/2018 quarter-finalists |
| Final appearances | 14 | Starters and used substitutes in finals from 1970 onward |
| Country scorers | 48 | All players with a credited finals goal for a given team |
| Penalty shootouts | 11 | All players who converted a shootout kick in a tournament |

## Source and license

The bank is derived directly from **The Fjelstul World Cup Database**, authored
by **Joshua C. Fjelstul, Ph.D.**, at the immutable Git commit
`f942c6b9844d8a2bc0621e45ee5c187a56670100` dated 20 July 2023:

https://github.com/jfjelstul/worldcup/tree/f942c6b9844d8a2bc0621e45ee5c187a56670100

That snapshot's [license statement](https://github.com/jfjelstul/worldcup/blob/f942c6b9844d8a2bc0621e45ee5c187a56670100/README.md#the-license)
allows commercial use under **CC BY-SA 4.0**. It requests the copyright notice
**© 2022 Joshua C. Fjelstul, Ph.D.** Preserve that version-specific notice.
The source README, package DESCRIPTION, codebook, CSVs and full license are
retained with SHA-256 hashes in `data/source/manifest.json`.

The author's newer WorldCups.ai download has different advertised licensing.
This project does **not** use that download or its API. Do not silently replace
the pinned inputs with new commercial-service data.

The derived `questions.json`, `catalog.json`, aliases and scoring adaptations
are also distributed under CC BY-SA 4.0. Give attribution, link the license,
describe modifications and preserve users' rights to reuse the data under
that license. This data notice does not change the license or visibility of
the independently written application code. No competitor answer bank was used.

## Public delivery paths

Keep the complete dataset available independently of the game APIs. Returning
only prompts during play is compatible with publishing a separate download.
The app's Sources page should link to these files:

| Public URL | Repository input | Response type |
|---|---|---|
| `/data/questions.json` | `data/questions.json` | `application/json` |
| `/data/catalog.json` | `data/catalog.json` | `application/json` |
| `/data/LICENSE.txt` | `data/LICENSE.txt` | `text/plain; charset=utf-8` |
| `/data/ATTRIBUTION.md` | `data/ATTRIBUTION.md` | `text/markdown; charset=utf-8` |

The application owner implements these URLs, either as static assets or public
routes. Do not put authentication or a purchase requirement on these four
downloads. The 8.4 MB of retained raw source data need not be in the Worker
bundle; the immutable upstream links provide access to those originals.

Suggested visible attribution:

> Historical data adapted from The Fjelstul World Cup Database by Joshua C.
> Fjelstul, Ph.D. (© 2022), licensed CC BY-SA 4.0. We added scoped questions,
> spelling aliases and fixed record-based scores. Men's tournaments through
> 2022; final-appearance records start in 1970. Download the data and license.

Link the database title, license name and downloads in the live page. The game
is independent and must not imply an official FIFA or data-author affiliation.

## Score semantics

For players, calculate a fixed World Cup footprint:

`4 × distinct tournament squad selections + credited World Cup goals`

The counts cover men's finals from 1930–2022. A squad selection counts even if
the player never entered a match. Own goals and shootout kicks are excluded
from credited goals. Career appearances are deliberately not used: that
table begins in 1970 and would undercount earlier players.

| Player footprint | Points |
|---:|---:|
| 24 or greater | 10 |
| 17–23 | 25 |
| 10–16 | 50 |
| 6–9 | 75 |
| 0–5 | 100 |

Team answers use distinct finals-tournament entries: 15+ entries = 10 points,
10–14 = 25, 6–9 = 50, 3–5 = 75, and 1–2 = 100. Germany and West Germany's
entries are combined for this score; East Germany is excluded.

This is an auditable historical-record proxy. It is **not observed answer
rarity, a popularity survey, current player fame, or an answer-selection
percentage**. A globally famous player with a short World Cup record can earn
a high score. Display the actual reason supplied with the accepted answer.

For any seven-question game, the maximum is
`sum(max(question.answers.map(answer => answer.score)))`. Some questions top
out below 100. For example, `teams-1930` has a maximum of 75. Do not hard-code
700 as every round's maximum.

## Names, aliases and scope

Answer IDs are the stable upstream player/team identifiers. Aliases are
lowercase normalized strings. Case, accents, whitespace and punctuation are
ignored. Additional mappings cover letters such as `ß`, `ø`, `ł`, `đ`, `æ`,
`œ`, `ð`, `þ` and `ı`; German `oe/ue/ae` spellings are explicit aliases.
Both given-family and family-given orders are retained. Hyphenless names
such as `Son Heungmin` are accepted. Common nicknames include Chicharito,
CR7, Neymar Jr and Vini Jr.

Use the same normalization as `normalize()` in `scripts/build-questions.py`.
Do not perform substring matching or unrestricted fuzzy acceptance: that can
accept the wrong person. Every normalized alias belongs to only one answer
within a question. Ambiguous surnames such as `Hernandez` in the 2022 France
squad, or `Martinez` in the 2022 Argentina squad, are removed. `Ronaldo` is
ambiguous among the 2006 scorers; `Cristiano Ronaldo` and `Ronaldo Nazario`
are unambiguous. Historical namesakes may include a birth year in their
display name to permit a precise answer.

Registered squad membership differs from taking the field. Karim Benzema is
eligible for France's registered 2022 squad question, but not the 2022 final
appearance question. This distinction is supported by the official squad
list. A scorer question excludes someone whose only contribution was an own
goal or a shootout kick. Each question's `detail` explains its boundary.

Historical teams remain distinct. The Germany country-scorer question is the
one explicit merger: Germany plus West Germany, excluding East Germany.
The Soviet Union is not silently merged with Russia, nor Czechoslovakia with
the Czech Republic.

## Verification and reproduction

Run from the repository root:

```sh
python3 scripts/build-questions.py
python3 scripts/build-questions.py --check
node --test tests/data.test.mjs
```

`--check` verifies all input hashes and byte-for-byte output reproduction.
To re-download the exact pinned inputs, run `--download`; this respects the
standard `HTTPS_PROXY` environment variable. A changed source hash causes an
error rather than replacing the input silently. Normal builds require no
network, paid API, API key, model, Python package or browser.

Tests independently reconstruct all eligible sets from the original CSVs,
reconcile goal events with every recorded match score, recompute every player
score, reject known ineligible answers and ambiguous surnames, and verify
cutoffs, licensing, hashes and reproducibility. Independent official-source
spot checks and nickname evidence are recorded in `data/source/verification.json`.

The source is a third-party database compiled from Wikipedia and partly
cross-checked against FIFA match reports. Verification confirms faithful
construction and stated sample facts; it does not claim a fresh manual
review of every historical event. No live 2026 record or crowd-frequency
claim should be inferred from this bank.
