core/generate/comprehension
Shay a0e9ca8535
feat(comprehension): reader lifecycle for question-frame Phase 1 (ADR-0164.3) (#326)
Adds the three lifecycle functions for the incremental compositional
reader per ADR-0164.3 §Lifecycle API:

- begin_sentence(problem_state, source_text_offset) -> SentenceReadingState
- apply_word(sentence_state, problem_state, word) -> SentenceReadingState | ReaderRefusal
- end_sentence(sentence_state, problem_state) -> ProblemReadingState | ReaderRefusal

Phase 1 scope is question sentences only. The update rules for the
question_frame live in a single readable table (_QUESTION_FRAME_RULES);
statement-side frames (initial_state_frame, operation_frame,
descriptive_frame) refuse with a Phase-2 diagnostic.

The five Brief-8 GSM8K target question sentences (0007, 0017, 0027,
0036, 0043) produce valid QuestionTargetSlot outputs end-to-end.

_interface_stubs.py provides a thin, functional surface for the
lexeme-primitive scanner (Brief 6) and lexicon loader (Brief 7) so
this PR does not block on them. The stub honours the en_core_math_v1
pack entries and adds a closed Phase-1 supplemental vocabulary marked
for fold-in to the pack once Briefs 6/7 land.

Tests cover determinism (byte-equal canonical bytes), the five GSM8K
target sentences with expected (entity, unit_class, kind) triples,
all token-level and sentence-level refusal modes, and lifecycle
invariants (registry preservation, sentence_index advance).

Stacked on feat/state-two-level-split (PR #323) per ADR-0164.3
§Naming — state types live in state.py.
2026-05-26 20:13:12 -07:00
..
__init__.py
_interface_stubs.py feat(comprehension): reader lifecycle for question-frame Phase 1 (ADR-0164.3) (#326) 2026-05-26 20:13:12 -07:00
lexeme_primitives.py feat(comprehension): lexeme primitive registry (ADR-0164.1) (#324) 2026-05-26 20:03:39 -07:00
lexicon.py feat(comprehension): operational lexicon loader for en_core_math_v1 (ADR-0164 §Decision §1) (#325) 2026-05-26 20:08:27 -07:00
lifecycle.py feat(comprehension): reader lifecycle for question-frame Phase 1 (ADR-0164.3) (#326) 2026-05-26 20:13:12 -07:00
state.py feat(comprehension): split ComprehensionState into ProblemReadingState + SentenceReadingState (ADR-0164.3) (#323) 2026-05-26 19:54:17 -07:00