Shay c32b0db6a9 docs: consolidate governance anchors and clean up test registries

2026-07-03 12:05:10 -07:00

19 KiB

Raw Blame History

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 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 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:

String Normalization & Regex Scans: Do not write custom regexes for number words, percentages, or units in local files. Use the unified parser interface.
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.
Calendar Metrics: Day-counts and calendar logic must be resolved strictly through the calendar pack.

No-new-legacy rule (enforced after operationalization PR)

New derivation capabilities must consume KernelFacts / ProblemFrame facts where the substrate can represent the needed meaning. Construction entry point: generate/problem_frame_builder.py::build_problem_frame.

New raw-prose/local-regex parsing inside a derivation organ requires an explicit LEGACY_EXCEPTION comment and migration rationale. CI guard: tests/test_kernel_no_new_legacy_derivation_surfaces.py. Legacy inventory: docs/analysis/kernel-substrate-deprecation-audit-2026-06-18.md.

8. Kernel Pack Model

Every Kernel Pack is structured as a declarative, immutable resource directory under language_packs/data/<pack_name>_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

Doctrine Alignment: Commit this architecture and doctrine document (PR-0).
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.
Organ Refactoring: Update one target-state organ (e.g., percent_partition.py or temporal_tariff.py) to consume the new facade.
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.

19 KiB Raw Blame History