PR #836 Lookback — feat(kernel): introduce construction-affordance catalog skeleton

This lookback documents the design rationale, implementation details, and verification results for the initial slice of the construction-affordance catalog skeleton.

Rationale & Design Choices

1. Catalog Registry is Diagnostic-Only

Every entry in generate/construction_affordances.py is configured with diagnostic_only=True and serving_allowed=False. This enforces a clean trust boundary:

Candidate structures and affordances can be registered, introspected, and traced diagnostically.
The runtime serving path remains completely untouched and isolated, preventing any serving-time regressions.

2. Separation of Registry and Dispatch Logic

The contract assessment functions (assess_fraction_decrease and assess_percent_partition in generate/problem_frame_contracts.py) contain construction-specific structural logic, role bindings, and hazard checks.

We introduced _CONTRACT_REGISTRY to map candidate organs to catalog entries.
To prevent a leaky abstraction and forced interfaces, the actual dispatch in assess_contracts() remains explicit and structural, but references the catalog metadata where applicable.
This ensures the registry remains a metadata/introspection layer describing what a construction means, while the assessment functions describe how its obligations are proven.

3. Question-Target Priority Cascade

We documented the priority cascade inside _bound_question_target (in generate/problem_frame_builder.py). This prevents order-fragility in future additions:

Specific regex-based triggers (e.g. _DECREASE_DELTA_QUESTION_RE for proportional decrease delta).
General question clause extraction via _QUESTION_ENTITY_RE (or fallback to unresolved if ? is present).
Clause-level target classification (e.g. more -> difference, originally -> initial, left -> final, etc.).

Closed Test Gaps

We successfully added targeted test coverage to tests/test_problem_frame_contracts.py to close all outstanding edge cases from the proportional-change proof of concept:

Scale boundary rejection: Rejects scale values of 0 (0/4), 1 (4/4), or greater than 1 (5/4) with a scale_out_of_range blocker.
Multi-base rejection: Ensures multiple candidate relations trigger decrease_relation_ambiguous.
State entity continuity: Rejects cases where the state entity in the relation differs from the target entity of the question, triggering state_entity_continuity_unproven.
Unit continuity: Rejects cases where the base quantity unit does not match the relation unit, triggering unit_continuity_unproven.
Percent-partition blocker specificity: Asserts that unequal-partition confusers correctly surface partition_subgroups_not_distinct and percent_subgroup_links_incomplete.

Verification Results

All 46 tests across the targeted test suite pass successfully in < 0.5s.
Catalog behavior verified by new dedicated tests in tests/test_construction_affordances.py.

3 KiB Raw Blame History