From Word Lists to Proof: What the Question Engine Actually Tests
For yczz/oc-english, a question is the point where stored curriculum becomes a decision a learner can make and the application can score. This chapter follows that transformation from book and unit data to practice cards and exams, then asks what a passing result really means. Readers will leave with two separate judgments: the engine is structured and reproducible enough to support a coherent progression loop, but its evidence remains bounded by the kinds of recognition tasks it presents.
The distinction matters because the application’s larger promise depends on a small technical choice. If a unit is marked complete, the product is making a claim about what the learner has done. If an exam is passed, it is making a stronger claim about performance. Those claims can be useful, but only if the reader understands how the underlying questions were assembled.
The content layer is compact by design
The Rust content layer treats a book as a collection of units, and a unit as a collection of word records. A record can contain an English term, a Chinese gloss, and optional phonetic information. The application embeds the book files into the binary rather than fetching them from a service at question time. The retained registry names 13 PEP-labeled books, spanning primary grades three through six and junior grades seven through nine.
That organization gives the question engine a stable boundary. When it is asked to create questions for a unit, it knows the unit’s words and the larger book that can supply related material. It does not need a network connection or a remote content API to decide what a word means in the application. The same choice makes the result inspectable: the source data, the question rules, and the resulting card shape are all present in the project.
The content layer also contains a separate grammar knowledge base. It has 13 explanatory points, including the use of a and an, noun plurals, am/is/are, pronouns, there is/there are, modal verbs, common verb forms, comparison, and some/any. A hand-written mapping associates the relevant points with each book. This mapping is not an adaptive diagnosis of a learner’s weaknesses. It is a product rule that says which compact explanations and question templates are appropriate to a given level of the embedded material.
That difference between content and question rules is useful. The word files provide the raw learning material. The grammar cards provide explanations a learner can consult. The question engine determines how those materials become a task. A stored entry such as pencil can become a meaning question. The same unit’s word can also become a listening question, where the application reads the English term and asks the learner to choose it. A verb or adjective can be selected as the basis for a grammar template when the unit and book mapping make that template available.
The engine uses four options for each card. For a meaning question, the correct gloss is combined with distractors gathered from other words in the same book. For a listening question, the alternatives are other English terms selected from a pool of words with roughly similar length. The point is not to make distractors linguistically perfect; it is to create a bounded choice in which the learner has to discriminate the target from plausible-looking alternatives.
Grammar questions work differently. They are generated from a small family of templates and the grammatical material available in the unit. If a unit contains nouns, it can support templates such as plural formation or article choice. If it contains verbs, it can support forms such as the third-person singular, present continuous, past tense, or can plus the base verb. Adjectives can feed comparative or superlative questions. The template supplies a sentence frame, the morphology helper supplies a candidate form, and the grammar card supplies an explanation when the learner needs one.
This is a useful division of labor for an offline prototype. The data layer does not need to contain a prewritten question for every possible attempt. The rules can reuse a modest vocabulary in several forms, while the grammar point remains attached to an explanation. But the same compactness creates a boundary. A template can check whether a learner recognizes goes as a third-person form or chooses bigger in a comparative sentence; it cannot, by itself, show that the learner can construct a new sentence with the rule.
Consider what happens to one retained record such as pencil. Its English form can become the target of a meaning card, where the learner maps the form to a stored gloss. It can become the spoken text for a listening card, where the learner maps sound back to one written option. Because the record is available inside a unit, it can also be available to a grammar template when the unit’s words and the book’s grammar mapping make that template appropriate. The same word has not become three different facts; it has become three different prompts that require different decisions.
The distractor rules reveal the design’s priorities. Meaning alternatives are gathered from elsewhere in the same book, which gives the generator a large enough pool without an external semantic model. Listening alternatives are chosen partly by word length, a cheap way to keep the options visually comparable. Neither rule guarantees that every wrong answer is equally plausible in meaning or sound. The generator is optimizing for a stable four-option interaction, not for a professionally authored assessment item with independently calibrated difficulty.
Grammar adds another layer of selection. The book-to-grammar mapping proposes which rule families belong with a book, but the unit still needs suitable material. Noun-based templates need nouns; verb-based templates need verbs; comparison templates need adjectives. The generator skips a family when the unit cannot support it and tries another mapped point. This prevents a grammar question from referring to a kind of word that is absent, while also showing that the grammar portion is shaped by both curriculum mapping and the local vocabulary available in a unit.
The result is a compact content pipeline with three separate contracts: the record contract says what material exists, the question contract says how that material becomes a four-option task, and the progress contract says which successful task can count toward a unit. Confusing those contracts creates predictable mistakes. A word being present in a book does not mean it has been practiced. A question being generated does not mean it is part of the exam. A correct option on a grammar template does not mean the learner has demonstrated unrestricted use of the rule.
The relationship among the layers is easier to see as a pipeline:
The diagram distinguishes two outputs that can otherwise look identical on screen. Practice is expansive: it creates two cards for every word and adds three grammar cards when possible. The exam is selective: it takes eight word questions, four listening questions, and three grammar questions. Practice is the route to coverage; the exam is a fixed sample of that content.
Randomness that can be replayed
The engine uses shuffled question order and shuffled options, but it does not use untraceable randomness for an exam attempt. It derives a deterministic seed from the book, unit, and a salt. Practice has its own fixed seed. An exam includes the attempt number in the seed, so a later attempt can present a different arrangement while the same attempt can be regenerated consistently.
This matters because grading happens after the learner submits answers. The system does not need to store a complete exam paper in the profile to know what the learner saw. It can reproduce the paper from the same inputs, compare each submitted option with the regenerated answer index, and then update the result. Determinism here is not a claim about educational quality; it is a reliability mechanism. It prevents the questions used for scoring from drifting away from the questions used for display.
The fixed exam mix gives the score a defined shape. Eight questions ask about word meanings, four ask the learner to identify a word heard through the application’s text-to-speech path, and three ask about grammar. A score of 12 out of 15 passes. This makes the threshold easy to explain and gives the progression system a stable transition condition. It also means that a score is partly a report about the composition of this particular paper. A learner who passes has met the application’s standard on that mixture of constrained tasks.
The generator has a fallback for small units. If the unit cannot supply enough material for the listening portion or the full paper, the engine can draw additional words from the wider book. The exam still has its intended total and mix when the source permits it, but “unit exam” should not be read as “every question comes only from this unit.” The fallback is a sensible way to preserve a 15-question contract for uneven source data. It is also a reason to interpret the paper’s scope carefully.
There is a second distinction between variety and replayability. The question order and option order are shuffled, so the learner does not always see the same layout. Yet the seed ties a particular attempt to its book, unit, and attempt number. The first attempt can be regenerated as the first attempt; a later attempt can be different while remaining reproducible. This is a deliberate compromise: enough variation to make retakes meaningful, enough stability for the scorer to know which answer index belongs to the displayed paper.
The same caution applies to grammar. The morphology helpers cover common patterns and a selected set of irregular forms: plural endings, third-person endings, -ing, past tense, comparison, and articles. Those rules make generated questions predictable, but they are intentionally simplified. English spelling and pronunciation contain exceptions and distinctions that a small rule table will not capture. The grammar explanations are useful cards within this application; they are not a complete grammar reference.
The source data itself deserves the same level of care. The book records include glosses and, when available, phonetics, and their files identify an upstream spreadsheet source. The repository does not include an independent audit of that curriculum or a study comparing these materials with learner outcomes. That does not invalidate the embedded content. It defines the level of claim the project can support: the application contains a concrete, inspectable curriculum layer, not an independently validated educational corpus.
The assessment boundary becomes clearest when the three question types are separated.
A meaning card asks the learner to map an English form to one of four displayed meanings. This is a recognition task. It can reveal that the learner distinguishes the target from the provided alternatives at that moment. It does not show whether the learner could retrieve the word from a blank page, spell it, pronounce it, or use it in a sentence.
A listening card asks the learner to hear the application’s spoken text and select the matching written word. This adds a sound-to-form decision. It is more than seeing the answer printed beside the prompt, but it still uses a small set of displayed choices and a synthetic voice path. It does not establish that the learner can understand different speakers, follow connected speech, or produce the word aloud.
A grammar card places a blank or choice inside a template sentence. It can check a selected form such as a plural, a verb ending, or a comparative. If the learner answers incorrectly, the application can show a linked explanation. That is a useful feedback path, but a fixed sentence frame reduces the number of decisions the learner must make. The task tests selection inside a known structure, not flexible command of the rule in unfamiliar communication.
These limits are not defects that cancel the product. They are the conditions under which its progress signals should be read. The application is strongest when it says: this word has been successfully recognized in the available card format; this unit has met its practice condition; this exam attempt reached 12 or more correct answers; this best score improved or held. It becomes too strong if those statements are silently translated into: the learner has mastered the word, can communicate fluently, or will remember the rule later.
The gate itself illustrates both sides. Requiring every unit word to appear in the practiced-word record prevents a learner from opening the exam simply by browsing the unit. The 12/15 threshold gives passing a clear operational meaning. But the gate is based on the same question formats that generated the record. It guarantees a sequence of application events—correct selections, stored progress, and a passing paper—not a broader measure of language transfer.
That is why reproducibility and validity should not be confused. Deterministic seeding makes the software’s scoring dependable. It does not make the question a better measure than its prompt and alternatives allow. The embedded content makes the app available offline. It does not independently verify every gloss or grammar explanation. The fixed mix makes progress legible. It does not turn a game milestone into a longitudinal learning study.
The question engine therefore provides a sound foundation for oc-english’s local progression loop: its inputs are bounded, its outputs are structured, and its exam attempts can be replayed for consistent grading. Its proof is narrower than the word “learning” can suggest. The next judgment is about what happens when this limited but durable proof is converted into points and then into a character’s appearance and room. That is where a stored answer becomes a visible consequence—and where the difference between activity and mastery must remain in view.