# Gap Decisions — DRAFT for Core handoff **Status:** DRAFT. Spec rulings for Core against gaps listed in `spec/PROPERTIES.md` § Gaps. **Target commit:** `194e588`. **Policy:** Prefer **Match C++ as coded** when README prose and implementation disagree, unless README is the only statement of a math identity (then say so). **No invented numeric constants.** Alapeno remains out of scope. Sources for gap list: `spec/PROPERTIES.md` lines 269–276 (Gaps section). --- ## 1. EPSILON naming (README name vs `0xFFFFFFFFULL` literal) **Sources** - PROPERTIES Gaps: “Named C++ identifier `EPSILON`: named only in README Key Constants; code uses literal `0xFFFFFFFFULL` in mulmod, not a `types.h` symbol.” - Prop 6 cites: README.md § “Key Constants” (line 320); `src/goldilocks.cpp:27,31`. - `J_API.md` already exposes fold constant as noun `EPSILON_FOLD` (= `0xFFFFFFFF` = \(2^{32}-1\)), noting README name `EPSILON`. **Ruling:** **Match C++ as coded** (literal fold mask in mulmod path). **Rationale:** README supplies the name; the implementation never defines an `EPSILON` symbol in `types.h` — Core must implement the fold arithmetic with the same literal value, not invent a C++ identifier. **Done for Core** - Provide a named J noun for the fold constant (e.g. `EPSILON_FOLD` per `J_API.md`) equal to `0xFFFFFFFF` (= \(2^{32}-1\)). - Use that value in `fp_mulmod` / fold exactly as `src/goldilocks.cpp` uses `eps` / `hi_lo` mask. - Do not require a `types.h`-style C++ symbol named `EPSILON`; README naming is documentation alias only. --- ## 2. BARRITT_MU unused **Sources** - PROPERTIES Gaps: “`BARRITT_MU`: defined equal to `P` and unused (`src/goldilocks.cpp:9–10`); no Barrett algorithm steps beyond the comment.” - No numbered property asserts Barrett reduction; Goldilocks reduction is props 5–12 (fold / mulmod as coded). **Ruling:** **Match C++ as coded** (define-equal-to-`P`, unused; no Barrett path). **Rationale:** Sources define the constant and leave it unused; there is no Barrett algorithm identity to implement beyond the comment. Inventing Barrett steps would invent math not present in the cited cpp. **Done for Core** - May omit `BARRITT_MU` entirely, or expose a synonym equal to `GOLDILOCKS_PRIME` / `P` with no call sites. - Do **not** implement Barrett reduction; keep reduction as fold/mulmod per props 5–12 and `src/goldilocks.cpp`. --- ## 3. PMat grading unchecked in `insert` / `validate_grading` **Sources** - PROPERTIES Gaps: “PMat per-entry grading vs indices: stated in `pmat.h:3` but not checked in `insert` / `validate_grading`.” - Prop 28: header/README narrative says grading `tgt_sig - src_sig = monomial` is enforced; **Gap note** — `insert` does not compare signatures to row/col grades; `validate_grading` always returns `true` (`src/pmat.cpp:19–22`). Cite: `include/pmat.h:3,21–25`. **Ruling:** **Match C++ as coded** (stub / always-true validate; insert domain checks only). **Rationale:** The stated grading condition is narrative in the header; the coded surface that tests and callers see is domain checks on `insert` (prop 27) plus a no-op `validate_grading`. Enforcing full grading now would change observable C++ behavior Core is recreating. README/header is not a separate coded math identity here — the stub is the behavior. **Done for Core** - `pmat_insert`: fail only on `row ≥ rows`, `col ≥ cols`, or `sign ∉ {1,-1}` (prop 27); do not compare signatures to row/col grades. - `validate_grading` (or J equivalent): return success / true unconditionally, matching `src/pmat.cpp:19–22`. - Document that prop 28 “stated” grading remains a future Spec upgrade, not Core F1 obligation. --- ## 4. Compose deltas (`a.delta_source + b.delta_target` only vs README/full both signatures) **Sources** - PROPERTIES Gaps: “Compose monomial rule vs ‘sum of both signatures’: coded as `a.delta_source` + `b.delta_target` only (`src/pmat.cpp:54–55`), not full addition of both signatures from both factors.” - Prop 31 (as coded): on matching `a.col == b.row`: `sign_acc *= a.sign * b.sign`; `monom_acc.delta_source += a.monomial.delta_source`; `monom_acc.delta_target += b.monomial.delta_target`. Cite: `src/pmat.cpp:51–55`. - Prop 30 states composition preserves grading (narrative); prop 29 conservation is separately tested on entry monomials. **Ruling:** **Match C++ as coded** (accumulate `a.delta_source` into result source and `b.delta_target` into result target only). **Rationale:** Prop 31 already records the coded rule with a precise cite. A “sum of both signatures from both factors” reading is the prose disagreement; Core must reproduce the cpp accumulation, not invent a fuller bilinear sum. **Done for Core** - On compose match `a.col == b.row`: multiply signs; add **only** `a.monomial.delta_source` to accumulated `delta_source`; add **only** `b.monomial.delta_target` to accumulated `delta_target`. - Do not add `a.delta_target` or `b.delta_source` into the composed monomial unless/until Spec revises prop 31 against a code change. --- ## 5. PHI unused in math cpp **Sources** - PROPERTIES Gaps: “PHI usage in UAC/recurrence math: constant present; no consuming identity in the cited math cpp files.” - Prop 22: `PHI = 1.618033988749895`. Cite: `include/types.h:21`. “(Sources do not state further mathematical use in the UAC/recurrence core.)” **Ruling:** **Match C++ as coded** (constant present; unused in field / PMat / spectral / recurrence math paths). **Rationale:** Value is sourced from `types.h`; no cited math cpp consumes it. README is not supplying a PHI identity to implement — absence of use is the coded fact. **Done for Core** - Expose noun `PHI` with the value from `include/types.h:21` / prop 22 (do not invent a different constant). - Do not wire PHI into Goldilocks, PMat, spectral governor, or Banach recurrence steps unless a later Spec cites a consuming identity. --- ## Summary table | # | Gap | Spec ruling | Done for Core (one line) | |---|-----|-------------|---------------------------| | 1 | EPSILON naming | Match C++ as coded | Named fold noun = `0xFFFFFFFF`; use in mulmod; no required C++ `EPSILON` symbol | | 2 | BARRITT_MU unused | Match C++ as coded | Omit or synonym-of-P; no Barrett algorithm | | 3 | PMat grading unchecked | Match C++ as coded | Insert domain checks only; validate always true | | 4 | Compose deltas | Match C++ as coded | `a.delta_source` + `b.delta_target` only (prop 31) | | 5 | PHI unused | Match C++ as coded | Expose constant; no math consumer in Core F1 | --- ## Handoff note This document is **DRAFT for Core**. It does not modify `PROPERTIES.md`, `j/`, `verify/`, `include/`, `src/`, or Alapeno. Core should treat the five “Done for Core” bullets as the F1 obligation for these gaps; reopen Spec only if a later commit changes the cited cpp behavior.