spec/GAP_DECISIONS.md

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.