Grammar of reading (#412)

The contrastive grammar-of-reading layer: receptive-focused phenomenon notes modeled on EuRom5’s Gramática da leitura, cross-referenced from the Documents reader. Method background: docs/features/bridge_method.md; source inventory and product implications: the grammar-of-reading chapter summary in the raw content of the EuRom5 source in the research knowledge base (admin: Knowledge Base > Sources, SLA research domain; #540); coexistence with the production-side grammar notes: docs/features/grammar_bridge_audit.md.

Status: the structure slice is built (data model, EuRom5 topic inventory as seed rows, reader hook, admin CRUD). Content authoring and the reader UI for surfacing notes are follow-up work on #412.

Data model

reading_phenomenon_sections - the 26 EuRom5 sections (number, slug, title), the linear-browsing grouping. Fixed reference data.

reading_phenomena - one row per reading obstacle, addressable at subsection granularity (the book cross-references §24.4, never §24):

key - stable identifier (eurom5-10.3; eurom5-17 for the two single-entry sections). The target of reader cross-refs and note-to-note links. Immersive-authored phenomena beyond the book get non-eurom5 keys.
number - subsection number within the section; null for single-entry sections.
entry_kind - note (prose phenomenon note) or paradigm (pure cross-language forms table: EuRom5 §5.1, §6.1-6.2, §21.1, §26.x, which map to the Verbs surface rather than prose).
status - draft / reviewable / published; structure rows ship as drafts, publishing is the content-authoring gate.
divergent_languages - which languages deviate on this phenomenon (“French almost always requires an explicit subject”). Drives relative-opacity filtering: relevant_for?(target_language:, known_languages:) surfaces a note only when the target diverges from every known language - if any known patterns with the target, the learner already has the bridge.
bridge_key - optional one-way link into the grammar-note corpus, matching COALESCE(grammar_notes.bridge_key, slug) (the #413 grouping key). linked_grammar_notes resolves it to published notes (“learn this properly”). Grammar notes never link back.
statements (jsonb) - per-language parallel prose, the EuRom5 “same observation in every language” shape; the render path picks the reader’s best language.
examples (jsonb) - aligned example rows displayed in canonical continuum order (PT-ES-CA-IT-FR-EN) with the divergent cells marked.

reading_phenomenon_links - directed note-to-note cross references, the book’s own [§n.n] pattern (§13.3 <-> §10.3, §20.7 <-> §24.1); mutual references are two rows.

Seeding

db/seeds/eurom5_grammar_of_reading.yml holds the full topic inventory: 26 sections, 124 phenomenon rows (122 numbered subsections plus §17 and §19), 8 paradigm entries, 7 in-book cross references. Structure only - titles, no prose. Grammar::ReadingPhenomenonSeeder upserts it (idempotent, never touches authored content); it runs in the CreateReadingPhenomena migration and any time via:

bin/rails grammar:seed_reading_phenomena

Reader hook

document_aids rows with aid_type: grammar_ref carry payload["phenomenon_key"] resolving to a phenomenon note (DocumentAid#reading_phenomenon); validation requires the key to resolve. This is the EuRom5 [§n] pattern: an annotation in the text jumps into the grammar of reading. Aid generation does not emit grammar_ref aids until phenomenon content is authored.

Admin

/admin/reading_phenomena is the authoring surface (structure fields, bridge metadata, statements/examples as JSON); /admin/reading_phenomenon_sections is read-only reference data. Grammar notes gained a bridge_key input for the #413 Phase 2 drift repair.

Content authoring (not yet built)

~110 prose notes (the non-paradigm rows), LLM-drafted and human-reviewed per the #412 plan: receptive register only, minimal terminology, an English column extending each contrast (English usually patterns with French), and divergent_languages filled per note so relative-opacity filtering activates. Priority follows the book’s own order: lexicon, sound/spelling, syntax, verb system, determiners, function words, morphology.