36 lines
3 KiB
Markdown
36 lines
3 KiB
Markdown
# 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:
|
|
1. Specific regex-based triggers (e.g. `_DECREASE_DELTA_QUESTION_RE` for proportional decrease delta).
|
|
2. General question clause extraction via `_QUESTION_ENTITY_RE` (or fallback to unresolved if `?` is present).
|
|
3. 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`.
|