core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
core/docs/analysis/kernel-knowledge-inventory-2026-06-18.md

9 KiB
Raw Blame History

Kernel Knowledge Inventory — Repo Evidence (2026-06-18)

This document maps the locations in the CORE codebase where fundamental knowledge, conversions, scalar equivalents, and domain boundaries are handled locally or duplicated.

1. Empirical Starting Point (PR-0 Baseline)

As of PR-0, the baseline scoring metrics after #827 are:

  • train_sample: 30 correct, 20 refused, 0 wrong (30/20/0)
  • holdout_dev: 5 correct, 495 refused, 0 wrong (5/495/0)

Important

This PR is documentation-only and does not change these baseline numbers.

2. Files Inspected

The following key parts of the repository were analyzed:

  • language_packs/numerics_loader.py
  • language_packs/loader.py
  • scripts/generate_en_numerics_v1.py
  • language_packs/data/en_numerics_v1/manifest.json, lexicon.jsonl
  • language_packs/data/en_units_v1/manifest.json, lexicon.jsonl, conversions.jsonl
  • generate/derivation/calendar_grounding.py
  • generate/derivation/piecewise_daily_hours_total.py
  • generate/derivation/nested_fraction_remainder_total.py
  • generate/derivation/percent_partition.py
  • generate/derivation/temporal_tariff.py
  • generate/derivation/comparatives.py
  • generate/derivation/extract.py
  • generate/math_parser.py
  • generate/math_roundtrip.py
  • tests/test_math_candidate_graph_xhigh_sprint13_lift.py
  • docs/analysis/gsm8k-xhigh-capability-sprint13-lookback-2026-06-18.md

3. Existing Numeric/Fraction/Percent Handling

  • ADR-0128 (en_numerics_v1): Establishes the static lookup mappings for numbers (cardinals/ordinals), fractions, multipliers, and format regexes (e.g., matching decimals or slash-fractions).
  • generate/derivation/extract.py: Locally implements regexes for extracting fractions like _HALF_OF_RE and _FRACTION_OF_RE. It interprets these values using custom functions to map "half" to 0.5 rather than reading from en_numerics_v1.
  • generate/math_parser.py: Contains custom comparative parser slots such as "half as many apples" or "half as much", separating them from other numbers.

4. Existing Unit/Dimension Handling

  • ADR-0127 (en_units_v1): Standardizes dimension classes and unit conversions.
  • generate/binding_graph/units.py: Employs static unit structures for dimensional checks.
  • generate/math_candidate_parser.py: Widens parsing parameters dynamically to support trailing prepositions in unit extraction, rather than using structured lookups.

5. Existing Provenance/Source-Token Handling

  • generate/derivation/calendar_grounding.py: Implements MonthGrounding, producing a provenance identifier of calendar_table:month_name.
  • generate/derivation/state/provenance.py: Contains provenance validity verifiers that validate whether operands are bound to character positions in problem text.

6. Existing Hazard/Refusal Handling

  • generate/derivation/calendar_grounding.py: Explicitly blocks February lookups due to leap year ambiguities.
  • generate/derivation/piecewise_daily_hours_total.py: Checks if month lengths are even to license a "halfway" split.
  • generate/derivation/percent_partition.py: Blocks and refuses ungrounded percentages or indefinite quantifiers (like "some").

7. Repeated Local Logic in Derivation Organs

Multiple derivation organs independently handle scalar scalars (like "half" and "1/2"), months of the year, rates, or comparatives. They use ad hoc matching regexes and mapping dictionaries, leading to severe code duplication and validation gaps.

8. Places Where Scalar Equivalence is Duplicated

  • generate/derivation/closed_reference_affine_aggregate.py maps "half" to 0.5 for basic scaling, but treats the composite comparative contexts separately.
  • generate/derivation/nested_fraction_remainder_total.py uses local regexes matching half of the... and inverse scalar scaling.
  • generate/derivation/percent_partition.py uses local regex checks for "half".
  • generate/derivation/temporal_tariff.py parses "half" and "1/2" locally for overtime rate multipliers.

9. Places Where Unit Logic is Duplicated

  • generate/derivation/survey_rate_earnings.py and bounded_rate_projection.py parse unit scales and dimensions ad hoc.
  • generate/math_candidate_parser.py repeats checking of plurals/singulars for nouns and measurements.

10. Places Where Actor/Target Binding is Duplicated

  • generate/derivation/nested_fraction_remainder_total.py parses actor-camp target bindings locally.
  • generate/derivation/piecewise_daily_hours_total.py binds hours to specific actors in schedule lines.

11. Places Where Process-Frame Logic is Duplicated

  • generate/derivation/survey_rate_earnings.py, temporal_tariff.py, and piecewise_daily_hours_total.py each independently define the rate-multiplication process (rate \times hours \times days) and overtime rules.

12. Existing Pack Machinery That Should Be Reused

  • language_packs/numerics_loader.py: The lookup_cardinal, lookup_fraction, and match_number_format methods are already fully functional and will be imported.
  • language_packs/loader.py: The units registry (_UNITS_MAP and _DIMENSIONS_MAP) and dimensional conversions graph will be utilized.

13. Gaps

  • ProblemFrame Integration: There is currently no standardized ProblemFrame representation; organs consume raw text or candidate graph outputs directly.
  • Transitive Hazards: Relational transitivity (greater_than, before_event) is implemented on the solver side rather than being checked at the boundary.

14. Risks

  • Silent Overruns: Without unified dimension matching, organs might combine incompatible measurements (e.g., adding dollars and items) when solving.
  • Adversarial Overfitting: Local parsers in organs are tuned to train samples; small text variations cause them to fail or misalign.

15. Recommended PR Sequence

  1. PR-0: Documentation & Architecture Inventory (This PR).
  2. PR-1: Refactor language_packs to combine numerics and units loaders.
  3. PR-2: ScalarEquivalence facade over en_numerics_v1.
  4. PR-3: Refactor percent_partition.py and nested_fraction_remainder_total.py to use the facade.

Tables

Table A — Repeated Scalar Logic

File Surface Handled Canonical Meaning Local Hazards Should Move to Facade?
generate/derivation/closed_reference_affine_aggregate.py "half" 0.5 unbound_base Yes
generate/derivation/nested_fraction_remainder_total.py "half" 0.5 unbound_whole Yes
generate/derivation/percent_partition.py "half" 0.5 percent_vs_fraction Yes
generate/derivation/temporal_tariff.py "half", "1/2" 0.5 double_overtime Yes

Note: The surface "half" corresponds to a scalar value of 0.5. Relational comparatives such as "one-and-a-half" or "half-again" are treated as distinct $1.5$-style scalar relations.

Table B — Repeated Unit/Dimension Logic

File Unit Family Conversion/Check Local Hazards Should Move to Unit Pack?
generate/derivation/calendar_grounding.py time.month Month day-count mapping leap_year Yes
generate/derivation/survey_rate_earnings.py money Currency formatting unsupported_currency Yes
generate/derivation/bounded_rate_projection.py speed Distance per time conversions ratio_inversion Yes

Table C — Repeated Process/Relation Logic

File Process Frame Verbs/Surfaces Relation Emitted Hazards Candidate Pack
generate/derivation/temporal_tariff.py labor "works", "paid" wage_earned overtime_tariff process_frames
generate/derivation/nested_fraction_remainder_total.py partition "going to", "rest" subset unbound_complement part_whole
generate/derivation/survey_rate_earnings.py labor "makes", "earns" earnings compound_rates process_frames

Table D — Provenance Risks

File Pattern Risk Recommended Provenance
generate/derivation/calendar_grounding.py calendar_table:{month} Fabricating world facts without source kernel_calendar (explicit calendar table entry)
generate/derivation/nested_fraction_remainder_total.py "half" Lost token-span link problem_text (exact span in narrative)
generate/derivation/temporal_tariff.py "1/2" Fabricated multiplier problem_text (exact span in narrative)

Table E — Ambiguity Hazards

Surface Possible Meanings Safe Contexts Refusal Contexts Candidate Pack
"quarter" 0.25 / coin / school term Explicit numeric math Currency mix-ups / temporal splits ambiguity_hazards
"third" 1/3 / position Explicit fraction Calendar positioning / rank orders ambiguity_hazards
"half" 0.5 / time split Simple scaling Half an hour temporal conversions ambiguity_hazards
"some" quantity > 0 None (indefinite) All math operations ambiguity_hazards