From ce29327b4f55d95a0af27109d36b64f2e546fc4e Mon Sep 17 00:00:00 2001 From: Shay Date: Thu, 18 Jun 2026 16:40:18 -0700 Subject: [PATCH] docs(architecture): tighten kernel knowledge doctrine --- .../kernel-knowledge-inventory-2026-06-18.md | 166 +++++++++ ...kernel-knowledge-implementation-roadmap.md | 121 +++++++ .../architecture/kernel-knowledge-layer-v1.md | 320 ++++++++++++++++++ 3 files changed, 607 insertions(+) create mode 100644 docs/analysis/kernel-knowledge-inventory-2026-06-18.md create mode 100644 docs/architecture/kernel-knowledge-implementation-roadmap.md create mode 100644 docs/architecture/kernel-knowledge-layer-v1.md diff --git a/docs/analysis/kernel-knowledge-inventory-2026-06-18.md b/docs/analysis/kernel-knowledge-inventory-2026-06-18.md new file mode 100644 index 00000000..899e5c88 --- /dev/null +++ b/docs/analysis/kernel-knowledge-inventory-2026-06-18.md @@ -0,0 +1,166 @@ +# 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` | diff --git a/docs/architecture/kernel-knowledge-implementation-roadmap.md b/docs/architecture/kernel-knowledge-implementation-roadmap.md new file mode 100644 index 00000000..ce74f458 --- /dev/null +++ b/docs/architecture/kernel-knowledge-implementation-roadmap.md @@ -0,0 +1,121 @@ +# Kernel Knowledge — Implementation Roadmap + +This document outlines the step-by-step roadmap for implementing and integrating the target-state **Kernel Knowledge Layer** in CORE. + +--- + +## Current Baseline Context (PR-0 Status) + +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) + +> [!NOTE] +> This roadmap is documentation-only (PR-0). It introduces no code, changes no serving paths, and has **zero impact** on these baseline benchmark scores. + +--- + +## PR 1: Kernel Knowledge Doctrine +- **Purpose:** Establish the architectural design, taxonomy, and rules for the Kernel Knowledge Layer. +- **Files Likely Touched:** + - `docs/architecture/kernel-knowledge-layer-v1.md` + - `docs/analysis/kernel-knowledge-inventory-2026-06-18.md` + - `docs/architecture/kernel-knowledge-implementation-roadmap.md` +- **Tests Required:** None (documentation-only). +- **Explicit Non-Goals:** Modifying python source files or changing benchmarks. +- **Acceptance Criteria:** Code review approval from domain experts. +- **Risks:** Scope-creep in review. +- **Rollback Strategy:** Revert docs commits. + +--- + +## PR 2: ScalarEquivalence Facade +- **Purpose:** Introduce the `ScalarEquivalence` facade layer querying over the existing [ADR-0128](docs/decisions/ADR-0128-numerics-pack.md) `en_numerics_v1` pack to map and canonicalize number words, fractions, and percentages, unless a later ADR proves a separate pack is necessary. +- **Files Likely Touched:** + - `language_packs/scalar_equivalence.py` [NEW] +- **Tests Required:** + - Unit tests validating mapping of `half`, `0.5`, `50%`, and unicode fraction symbols to their canonical scalar values. +- **Explicit Non-Goals:** Integrating this facade into any parser or serving code path. +- **Acceptance Criteria:** All unit tests pass; package build is successful. +- **Risks:** Unforeseen package import issues or dependency cycles. +- **Rollback Strategy:** Remove the new facade file. + +--- + +## PR 3: Refactor Percent Partition Organ +- **Purpose:** Update the percent partition organ to resolve scalar equivalences through the new `ScalarEquivalence` facade. +- **Files Likely Touched:** + - `generate/derivation/percent_partition.py` + - `generate/derivation/extract.py` +- **Tests Required:** + - Run the `smoke` and `cognition` suites to verify that `percent_partition` cases still pass. +- **Explicit Non-Goals:** Modifying other organs. +- **Acceptance Criteria:** Percent partition cases pass, and local regex matches for scalars are removed. +- **Risks:** Breaking edge cases in fraction parsing. +- **Rollback Strategy:** Revert `percent_partition.py` to its original state. + +--- + +## PR 4: Units/Dimensions Kernel v1 +- **Purpose:** Unify the units and numerics loaders to standardize dimension checks. +- **Files Likely Touched:** + - `language_packs/loader.py` + - `language_packs/numerics_loader.py` +- **Tests Required:** + - Standard unit conversion tests. +- **Explicit Non-Goals:** Implementing new physical dimensions. +- **Acceptance Criteria:** Units and numerics packs load under a single unified API. +- **Risks:** Merge conflicts with concurrent PRs. +- **Rollback Strategy:** Revert loader refactoring. + +--- + +## PR 5: ProcessFrame Kernel v1 +- **Purpose:** Introduce declarative process frames (e.g., repeating work cycles, wages) exposing candidate relation schemas and role requirements. +- **Files Likely Touched:** + - `generate/derivation/process_frame.py` [NEW] +- **Tests Required:** + - Rate multiplier and labor hours computation schemas. +- **Explicit Non-Goals:** Modifying the solver engine or executing arithmetic solving. +- **Acceptance Criteria:** Process frames expose correct schemas and role mappings. +- **Risks:** Under-specifying the labor rate relations. +- **Rollback Strategy:** Remove `process_frame.py`. + +--- + +## PR 6: ProblemFrame IR v0 +- **Purpose:** Define the intermediate representation (IR) structure for parsed problems. +- **Files Likely Touched:** + - `generate/problem_frame.py` [NEW] +- **Tests Required:** + - Parsing unit and comparative structures into the IR. +- **Explicit Non-Goals:** Replacing the candidate graph parser or solving arithmetic. +- **Acceptance Criteria:** ProblemFrame holds structured quantities and dimensions. +- **Risks:** Performance overhead during parse phases. +- **Rollback Strategy:** Remove `problem_frame.py`. + +--- + +## PR 7: Morphology Atlas v2 with Missing-Kernel Labels +- **Purpose:** Extend the experience flywheel to report missing kernel nodes. +- **Files Likely Touched:** + - `scripts/gsm8k_experience_flywheel.py` +- **Tests Required:** + - Running the flywheel on failed cases and verifying the presence of `missing-kernel` tags. +- **Explicit Non-Goals:** Automatic pack mutation. +- **Acceptance Criteria:** Flywheel reports correctly tag missing elements. +- **Risks:** Misclassifying parsing failures as missing nodes. +- **Rollback Strategy:** Revert flywheel changes. + +--- + +## PR 8: First Contract-Backed ProblemFrame Organ +- **Purpose:** Implement a solver organ that consumes the ProblemFrame IR rather than raw text. +- **Files Likely Touched:** + - `generate/derivation/first_ir_organ.py` [NEW] +- **Tests Required:** + - Integration tests on GSM8K problems mapped to the new organ. +- **Explicit Non-Goals:** Overwriting all existing organs. +- **Acceptance Criteria:** The target organ passes all evaluation cases with zero errors. +- **Risks:** Performance degradation under multi-step parsing. +- **Rollback Strategy:** Disable or remove `first_ir_organ.py`. diff --git a/docs/architecture/kernel-knowledge-layer-v1.md b/docs/architecture/kernel-knowledge-layer-v1.md new file mode 100644 index 00000000..df19000f --- /dev/null +++ b/docs/architecture/kernel-knowledge-layer-v1.md @@ -0,0 +1,320 @@ +# Kernel Knowledge Layer — Architecture & Doctrine (v1) + +This document defines the architecture, boundary rules, and operational doctrine for the target-state **Kernel Knowledge Layer** in CORE. + +--- + +## 1. Purpose + +The Kernel Knowledge Layer acts as a seeded, reviewed, and deterministic substrate of fundamental facts, equivalences, dimensions, physical containers, calendar systems, and hazard invariants. It provides a shared "world model" that language-processing and mathematical derivation components will consult, ensuring that common-sense relationships (such as $1 \text{ hour} = 60 \text{ minutes}$ or $\text{"half"} = 0.5$) are canonicalized consistently rather than re-engineered ad hoc inside individual derivation organs. + +--- + +## 2. Baseline Context & Empirical Standing + +As of PR-0, the current empirical results of CORE (after integration of #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 (PR-0). It introduces no code, changes no serving paths, and has **zero impact** on these baseline benchmark scores. + +--- + +## 3. Why CORE Needs This Now + +As CORE has expanded its capabilities on GSM8K and similar arithmetic reasoning benchmarks, we have transitioned from simple single-step operations to complex multi-step transitive reasoning chains. However, this progress has come at the cost of duplicate local logic. + +Without a central Kernel Knowledge Layer: +- Multi-step derivation organs must each write custom regexes or lookup maps for numbers like "half", "quarter", "1/2", and "50%". +- Calendar parsing (e.g., month names, day counts, and temporal splits) is repeatedly hard-coded within specific scheduling organs. +- Dimensional conversions (e.g., currency conversions, hours to days) are hand-crafted within isolated problem-solving paths. + +By introducing a standardized Kernel Knowledge Layer, we decouple **lexical/factual grounding** from **derivation/problem-solving logic**. + +--- + +## 4. What Recent GSM8K Sprints Revealed + +Recent development sprints (Sprints 10 through 13) targeted high-difficulty math reasoning paths: +- **Sprint 11 (Piecewise Daily Hours):** Introduced month-length lookups and "halfway through the month" logic, which was implemented as local calendar grounding tables inside the organ. +- **Sprint 12 (Nested Partitions):** Revealed that handling phrases like "half of the kids" or "1/4 of the remaining" required specialized parsing patterns repeated across multiple files. +- **Sprint 13 (Robust Lift):** Highlighted the risk of boundary violations when resolving comparative scales ("twice as many", "half as many"). Without standardized hazard verification, organs easily make unsound inferences due to unbound base quantities or category mismatches. + +These sprints proved that while CORE's geometric runtime can enforce invariants once representations are built, the *construction* of those representations relies on brittle, repetitive local logic. + +--- + +## 5. What Already Exists in ADR-0128 (`en_numerics_v1`) + +The sibling specification [ADR-0128](docs/decisions/ADR-0128-numerics-pack.md) defines `en_numerics_v1`. It contains: +- **Cardinal number words:** Zero to twenty, tens, and magnitudes. +- **Ordinal number words:** First through thirty-first, plus major anchors. +- **Fraction words & symbols:** "half", "third", "quarter", "three-quarters", and Unicode symbols (`½`, `¾`, `⅔`). +- **Multiplier words:** "double", "triple", "twice", "thrice". +- **Quantifiers:** "all", "none", "some", "each", "every", "many", "few". +- **Comparison anchors:** "more", "fewer", "less", "additional", "times". +- **Numeric format rules:** Declarative regexes matching thousand-separated, decimals, slash-fractions, mixed numbers, and percentages. + +--- + +## 6. What Already Exists in ADR-0127 (`en_units_v1`) + +[ADR-0127](docs/decisions/ADR-0127-units-pack-and-units-aware-parser.md) defines `en_units_v1`. It contains: +- **Dimensions:** Closed physical and financial dimensions (`count`, `length`, `time`, `mass`, `money`, `volume`, `wage`, `unit_price`). +- **Unit definitions:** Standard mappings for `foot`/`feet`, `hour`/`hours`, `dollar`/`dollars`, `cent`/`cents`, and entity units like `person`/`people`, `child`/`children`. +- **Conversion graphs:** Formal conversion edges between units within the same dimension (e.g., $1 \text{ dollar} = 100 \text{ cents}$). +- **Containers:** Default sizes for physical containers (`box`, `pack`, `bag`, `crate`). + +--- + +## 7. What Must Not Be Duplicated + +To prevent architectural drift and maintain a clean separation of concerns, the following functions **must not** be duplicated in derivation organs: +1. **String Normalization & Regex Scans:** Do not write custom regexes for number words, percentages, or units in local files. Use the unified parser interface. +2. **Dimension Tables:** Standard conversion coefficients (e.g., $60 \text{ minutes} = 1 \text{ hour}$) must reside in the units pack conversions, not in organ-level multiplication constants. +3. **Calendar Metrics:** Day-counts and calendar logic must be resolved strictly through the calendar pack. + +--- + +## 8. Kernel Pack Model + +Every Kernel Pack is structured as a declarative, immutable resource directory under `language_packs/data/_v1/` containing: +- `manifest.json`: Defines pack metadata, determinism class (`D0`), and cryptographic file checksums. +- `lexicon.jsonl`: Contains individual lexeme or concept definitions. +- `glosses.jsonl`: Human-readable descriptions explaining the exact semantic scope. +- `.mastery_report.json`: Cryptographic seals verifying disk contents. + +--- + +## 9. Pack Boundaries + +A Kernel Pack is a **passive database**. It acts as a static vocabulary and relational index: +- It **does** expose lookup functions (`lookup_*()`) and regex matching helpers (`match_*()`). +- It **does not** execute algorithms, traverse state graphs, or perform arithmetic reduction. +- It **does not** retain session state. All operations are stateless, side-effect-free, and thread-safe. + +--- + +## 10. Provenance Model + +Provenance is the system's guarantee of semantic origin. The taxonomy consists of the following explicit classes: + +* `problem_text`: Literal string offsets and spans from the input narrative text. +* `derived`: Values computed during derivation steps. +* `kernel_unit`: Physical and economic unit anchors defined in `en_units_v1`. +* `kernel_calendar`: Calendar parameters derived from structured rules. Specifically, the notation `calendar_table:{month}` represents a `kernel_calendar` provenance, not a generic world fact. +* `kernel_math`: Fundamental mathematical identities and properties. +* `kernel_world_fact`: General static world facts (e.g., currency relationships or gravity constants). +* `reviewed_pack`: Checked, human-curated facts and mappings. +* `speculative`: Deductive conclusions from speculative premises (retaining speculative standing). + +When a derivation organ constructs a quantity or relation, it will carry over the provenance. In-problem operands derived from narrative text must preserve their character offsets or string spans as `source_token`. + +--- + +## 11. Hazard Model + +A **Hazard** represents a semantic ambiguity, dimensional collision, or boundary violation that could lead to an incorrect inference if left unvalidated. +- When a kernel lookup retrieves an ambiguous node, it must attach a list of potential hazard IDs. +- For example, retrieving the lexeme "quarter" carries hazards: `[quarter_coin, quarter_calendar_period, quarter_school_term]`. +- The consumer (ProblemFrame or derivation organ) will check if the context disambiguates the hazard. If not, it must refuse the transaction (`refuse`). + +--- + +## 12. Review/Proposal Model + +To prevent unreviewed drift, kernel packs follow a strict proposal flow: +- Packs are compiled deterministically via offline scripts (e.g., `scripts/generate_en_numerics_v1.py`). +- Automatic runtime mutation of packs is forbidden. +- Any change to a pack must be proposed via a schema and checklist change, generating new SHA-256 hashes, and must be reviewed by codeowners prior to merging. + +--- + +## 13. What Packs May Do + +- Canonicalize varying surface forms (e.g., `half`, `0.5`, `50%`, `½`) to a single canonical ID (`scalar:1/2`) and numeric value. +- Map words to standard grammatical tags (e.g., `NOUN`, `NUM`, `ADJ`) and semantic tags. +- Declare dimensional conversion multipliers (e.g., $\text{multiplier}=100.0$ for dollars to cents). + +--- + +## 14. What Packs May Not Do + +- Decide which arithmetic operation to perform on problem operands. +- Solve equations or build target derivation networks directly. +- Infer missing problem values unless explicitly defined in a conversions graph. + +--- + +## 15. Target-State Relationships + +### Relationship to ProblemFrame +In the target state, the **ProblemFrame** represents the structured intermediate representation (IR) of the mathematical problem: +- The ProblemFrame will consume raw text, parse it using the candidate graph parser, and query the Kernel Knowledge Layer to ground actors, objects, quantities, and units. +- It will validate that dimensions match across comparison and addition operations. +- The ProblemFrame will not perform math; it will assert that the problem's relational structure is well-formed. + +### Relationship to Derivation Organs +In the target state, derivation organs are specialized mathematical solvers: +- Organs **will not** parse raw surfaces directly. Instead, they will consume the structured entities and relations in the ProblemFrame. +- Organs will rely on the kernel packs to perform unit conversions or to scale values by fractional/multiplicative operators. + +### Relationship to Experience Flywheel / Morphology Atlas +In the target state, the **Experience Flywheel** reviews failed or refused problems to categorize errors: +- If a problem is refused due to a missing lexical term or relation, the Flywheel will mark it with a `missing-kernel` label. +- This feeds back into the proposal queue for future kernel pack updates. +- The Flywheel **never** automatically writes to the packs; it only reports gaps. + +--- + +## 16. Non-Goals + +- Impersonating a large-scale language model by embedding encyclopedic world knowledge. +- Handling arbitrary sentence logic. +- Supporting real-time learning of user-defined facts in the core loop without human-in-the-loop review. + +--- + +## 17. First Implementation Sequence + +1. **Doctrine Alignment:** Commit this architecture and doctrine document (PR-0). +2. **ScalarEquivalence Facade over ADR-0128/en_numerics_v1:** Implement the facade layer to query numerics and fraction equivalences, unless a later ADR proves a separate pack is necessary. +3. **Organ Refactoring:** Update one target-state organ (e.g., `percent_partition.py` or `temporal_tariff.py`) to consume the new facade. +4. **Units/Dimensions Kernel:** Refactor and unify the units loader and conversions framework. + +--- + +## 18. Kernel Pack Categories + +### Category 1: scalar_equivalence +- **Scope:** Canonical fractions, multipliers, and percentages. +- **Example Nodes:** `scalar:1/2`, `scalar:3/4`, `scalar:2/1` +- **Example Surfaces:** "half", "one half", "1/2", "0.5", "50%", "double", "twice" +- **Example Relations:** `equivalence(surface, scalar_value)` +- **Allowed Inferences:** Grouping multiple spelling and symbolic representations of the same scalar scaling factor (e.g., "half" = 0.5). +- **Hazards:** `unbound_base_quantity`, `percent_change_vs_percent_of` +- **Provenance Requirements:** `reviewed_pack` (backed by `adr-0128:operator_seed`) +- **Must Not Solve:** Problem-level fraction partitions. +- **Special Case Inconsistencies:** 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, preventing conflicts during substitution. +- **First Candidate Tests:** Unification tests showing that "50%" and "half" map to the identical float/Fraction representation. + +### Category 2: units_dimensions +- **Scope:** Standard units of measure and conversions. +- **Example Nodes:** `unit:dollar`, `unit:cent`, `unit:hour`, `unit:minute`, `dimension:length` +- **Example Surfaces:** "dollars", "$", "cents", "hours", "hrs", "minutes", "mins" +- **Example Relations:** `conversion_factor(unit:dollar, unit:cent, 100.0)` +- **Allowed Inferences:** Converting quantities between compatible units (e.g., $2 \text{ hours} \rightarrow 120 \text{ minutes}$). +- **Hazards:** `dimension_mismatch`, `incompatible_conversions` +- **Provenance Requirements:** `kernel_unit` +- **Must Not Solve:** Rate calculations involving non-compatible dimensions (e.g., speed = distance / time). +- **First Candidate Tests:** Round-trip unit conversion tests. + +### Category 3: arithmetic_laws +- **Scope:** Common mathematical identities and algebraic patterns. +- **Example Nodes:** `identity:additive_neutral`, `law:distributive` +- **Example Surfaces:** "total", "combined", "each" +- **Example Relations:** `distributive_law(A * (B + C) = A*B + A*C)` +- **Allowed Inferences:** Exposing algebraic patterns for solvers to structure their mathematical target graph. +- **Hazards:** `operation_overflow` +- **Provenance Requirements:** `kernel_math` +- **Must Not Solve:** Solving multi-step equation systems directly. + +### Category 4: comparatives +- **Scope:** Relational comparatives that describe inequalities or relative ratios. +- **Example Nodes:** `comparative:more_than`, `comparative:less_than` +- **Example Surfaces:** "fewer", "more", "additional", "older than", "younger than" +- **Example Relations:** `relation:greater_than(A, B, delta)` +- **Allowed Inferences:** Establishing logical constraints and ordering models. +- **Hazards:** `reverse_comparative_inversion_error` +- **Provenance Requirements:** `reviewed_pack` (backed by `adr-0138`) +- **Must Not Solve:** Executing comparative additions/subtractions directly without context verification. + +### Category 5: part_whole +- **Scope:** Partitioning of groups and fractions of aggregates. +- **Example Nodes:** `partition:subgroup`, `partition:remainder` +- **Example Surfaces:** "rest", "remaining", "others", "girls", "boys" +- **Example Relations:** `complement(subgroup, remainder)` +- **Allowed Inferences:** Declaring candidate relation schemas (e.g., `sum(partitions) = 1.0`) and role requirements. +- **Hazards:** `unbound_whole_reference` +- **Provenance Requirements:** `reviewed_pack` +- **Must Not Solve:** Multi-step fraction remainder cascades. + +### Category 6: transfer_ledger +- **Scope:** Transits, gives, receives, sells, buys, and balance changes. +- **Example Nodes:** `transfer:give`, `transfer:receive`, `transfer:spend` +- **Example Surfaces:** "gave", "bought", "spent", "sold", "lost", "found" +- **Example Relations:** `balance_delta(actor, item, change_amount)` +- **Allowed Inferences:** Exposing structured transfer relations and debit/credit role templates. +- **Hazards:** `double_count_transfer` +- **Provenance Requirements:** `reviewed_pack` +- **Must Not Solve:** Arithmetic inventory changes. + +### Category 7: containers +- **Scope:** Storage, capacity bounds, and containment. +- **Example Nodes:** `container:box`, `container:crate`, `container:bag` +- **Example Surfaces:** "boxes", "crates", "packs", "bags" +- **Example Relations:** `contains(container, item, capacity)` +- **Allowed Inferences:** Exposing candidate relation schemas and capacity roles (e.g., `total_items = container_count * container_capacity`). +- **Hazards:** `unbound_container_size` +- **Provenance Requirements:** `kernel_unit` +- **Must Not Solve:** Box layout packing optimizations or solving totals. + +### Category 8: temporal_calendar +- **Scope:** Months, weeks, calendar splits, and offsets. +- **Example Nodes:** `calendar:month:june`, `calendar:week` +- **Example Surfaces:** "June", "week", "halfway through the month" +- **Example Relations:** `day_count(calendar:month:june, 30)` +- **Allowed Inferences:** Resolving explicit calendar names and periods to day counts using `calendar_table:{month}` under the `kernel_calendar` class. +- **Hazards:** `leap_year_ambiguity`, `vague_temporal_spans` +- **Provenance Requirements:** `kernel_calendar` +- **Must Not Solve:** Multi-month schedule parsing or solving days. + +### Category 9: spatial_route +- **Scope:** Linear distances, stops, and directional paths. +- **Example Nodes:** `route:distance`, `route:stop` +- **Example Surfaces:** "miles", "kilometers", "stops", "lights" +- **Example Relations:** `stops_per_distance(stops, distance)` +- **Allowed Inferences:** Exposing rate schemas along spatial routes. +- **Hazards:** `unbound_route_segments` +- **Provenance Requirements:** `reviewed_pack` +- **Must Not Solve:** Arithmetic solving of rates. + +### Category 10: process_frames +- **Scope:** Repeating workflows, rates, and earnings over time. +- **Example Nodes:** `process:labor`, `process:production` +- **Example Surfaces:** "earns", "makes", "works", "per day", "hourly" +- **Example Relations:** `wage_earned(hours, rate)` +- **Allowed Inferences:** Exposing production and labor relation schemas and rate roles. +- **Hazards:** `overtime_tariff_boundary_error` +- **Provenance Requirements:** `reviewed_pack` +- **Must Not Solve:** Solving earnings or applying overtime equations. + +### Category 11: ontology_minimal +- **Scope:** Minimal semantic hierarchy for entities to check dimensional compatibility. +- **Example Nodes:** `class:people`, `class:item`, `class:place` +- **Example Surfaces:** "students", "girls", "crayons", "classroom" +- **Example Relations:** `subclass_of(girls, students)` +- **Allowed Inferences:** Validating subclass hierarchy compatibility for addition/subtraction. +- **Hazards:** `incompatible_class_addition` +- **Provenance Requirements:** `reviewed_pack` +- **Must Not Solve:** Large-scale taxonomies. + +### Category 12: ambiguity_hazards +- **Scope:** Explicit registry of words carrying multiple meanings that require context constraints. +- **Example Nodes:** `hazard:quarter`, `hazard:third` +- **Example Surfaces:** "quarter", "third", "percent change" +- **Example Relations:** `has_hazard(quarter, quarter_coin)` +- **Allowed Inferences:** Flagging dangerous contexts for defensive refusal. +- **Hazards:** `unresolved_ambiguity_refusal` +- **Provenance Requirements:** `reviewed_pack` +- **Must Not Solve:** Disambiguation algorithms. + +### Category 13: provenance +- **Scope:** Source tracking anchors. +- **Example Nodes:** `provenance:text`, `provenance:table` +- **Example Relations:** `source_binding(operand, token_span)` +- **Allowed Inferences:** Tracking whether values are derived from narrative or are world constants. +- **Hazards:** `untracked_operand_provenance` +- **Provenance Requirements:** `reviewed_pack` +- **Must Not Solve:** Semantic parsers.