@descix/egpt-math-sdk 0.1.0

package/dist/notebooks/iso-entropy-log.html

@@ -0,0 +1,127 @@
+<frqtl-notebook version="1" title="E — Entropy-Log Bijection (log₂ N ≡ H(Uniform(N)))">
+
+<cell type="markdown">
+# E — Entropy-Log Bijection
+
+The hub of the canonical EGPTMath chain:
+
+> **log₂ N  ≡  H(Uniform(N))**
+
+The binary logarithm of a natural number IS the Shannon entropy of a uniform distribution on N outcomes. This is not a metaphor — it is formally proven in EGPT's Lean chain (`RotaUniformTheorem` + `entropy_of_fair_coin_is_one_bit`, `RET.lean`).
+
+Three statements, with honest provenance:
+
+- **E1** `log₂ N ≡ H(Uniform(N))` — pedagogical (both sides transcendental). Lean-backed.
+- **E2** `H(N) ≡ Σ_{p|N} v_p(N)·H(p)` — entropy is additive over prime atoms (LFTA in entropy form). Lean-backed.
+- **E3** `N ≡ ∏_p p^{v_p(N)}` — the exponentiated form of E2, **bit-exact** over BigInt. This is the runnable witness.
+
+Every downstream theorem (T/W/N/M four-views, OrderFinder) is a *projection* of E2. Run the cells below to witness E3 bit-exactly.
+
+*(Ported from `lib/egpt/js/model/theorems/E_EntropyLogBijection.js`. Cells reach `PrimeAtomPolynomial` through the injected `math` builtin — no imports.)*
+</cell>
+
+<cell type="markdown">
+## E1 — log₂ N ≡ H(Uniform(N))  (cited, not asserted)
+
+E1 and E2 are **print-only citations of Lean theorems** — both sides are transcendental reals and cannot be asserted inside exact EGPTReal arithmetic. The operational meaning: the information content of specifying one of N equally-likely outcomes is log₂(N) bits, and that is the shortest binary description (ParticlePath) length that resolves a 1-of-N selection.
+
+Lean theorems cited: `RotaUniformTheorem`, `entropy_of_fair_coin_is_one_bit` (EGPT/Entropy/RET.lean), `H_canonical_ln` (EGPT/Entropy/H.lean), `equivParticleFuturePDFToReal` (EntropyNumber/Basic.lean).
+</cell>
+
+<cell type="js" lane="math" id="e1-cite">
+const { display } = caps;
+display('E1 stated and cited — no runtime assertion (transcendental on both sides).');
+display('  log₂ N ≡ H(Uniform(N))    [Lean: RotaUniformTheorem + entropy_of_fair_coin_is_one_bit]');
+</cell>
+
+<cell type="markdown">
+## E2 — H(N) ≡ Σ v_p(N)·H(p)  (entropy additive over atoms)
+
+Shannon entropy is **additive** over the prime-atom decomposition of N — the LFTA written in entropy form. The primes are the irreducible information atoms; the decomposition is unique. This is why `PrimeAtomPolynomial` can read N's multiplicative structure by reading its additive exponent vector.
+
+Lean: `EGPT_Fundamental_Theorem_of_Arithmetic_via_Entropy_Bits` (EGPT/NumberTheory/Analysis.lean).
+</cell>
+
+<cell type="js" lane="math" id="e2-cite">
+const { display } = caps;
+display('E2 stated and cited — no runtime assertion (transcendental on both sides).');
+display('  H(N) ≡ Σ_{p|N} v_p(N)·H(p)    [Lean: EGPT_Fundamental_Theorem_of_Arithmetic_via_Entropy_Bits]');
+</cell>
+
+<cell type="markdown">
+## E3 — N ≡ ∏_p p^{v_p(N)}  (bit-exact witness)
+
+Both sides of E3 are integers, so we assert it **bit-exactly** on BigInt. Factorise N into its LFTA exponent vector via `PrimeAtomPolynomial.factorize`, reconstruct N by multiplying atoms raised to their exponents, and check the product equals N. We also check the sparsity bound Ω(N) ≤ bitLength(N) (every atom contributes ≥ log₂(2) = 1 bit).
+
+The cell produces `e3ok` (all cases passed) for the closing cell to confirm.
+</cell>
+
+<cell type="js" lane="math" id="e3-witness" out="e3ok">
+const { math, display } = caps;
+const { PrimeAtomPolynomial } = math;
+
+// Local check helper: in a notebook cell, a failed claim THROWS (no process.exit).
+let anyFailed = false;
+function check(label, cond) {
+  display((cond ? '  ✓ ' : '  ✗ ') + label);
+  if (!cond) { anyFailed = true; throw new Error('E3 FAILED: ' + label); }
+}
+
+// Reconstruct N from its LFTA exponent vector via ∏ p^{v_p}.
+function reconstruct(factors) {
+  let N = 1n;
+  for (const { prime, exponent } of factors) {
+    for (let i = 0n; i < exponent; i++) N *= prime;
+  }
+  return N;
+}
+
+const TEST_CASES = [
+  { N: 12n,   note: 'small semiprime-with-power (v_2=2, v_3=1)' },
+  { N: 21n,   note: 'small semiprime (v_3=1, v_7=1)' },
+  { N: 35n,   note: 'small semiprime (v_5=1, v_7=1)' },
+  { N: 391n,  note: 'medium semiprime 17·23' },
+  { N: 1024n, note: 'pure power of 2 (tight sparsity)' },
+  { N: 2310n, note: 'primorial 2·3·5·7·11 (five atoms)' },
+  { N: 997n,  note: 'large prime (Ω=1)' }
+];
+
+for (const { N, note } of TEST_CASES) {
+  const factors = PrimeAtomPolynomial.factorize(N);
+  const omega   = PrimeAtomPolynomial.bigOmega(N);
+  const bits    = BigInt(PrimeAtomPolynomial.bitLength(N));
+  const recon   = reconstruct(factors);
+  const vstr    = factors.map(f => `(${f.prime}^${f.exponent})`).join(' · ') || '1';
+  display(`N=${N}  ${note}`);
+  display(`  v⃗(N) = ${vstr}   log₂ form = ${PrimeAtomPolynomial.logspaceSum(N)}`);
+  display(`  reconstruct ∏ p^{v_p} = ${recon}    Ω=${omega}  bitLen=${bits}`);
+  check(`E3 bit-exact: ${N} ≡ ∏ p^{v_p}`, recon === N);
+  check(`sparsity: Ω(${N})=${omega} ≤ bitLen=${bits}`, omega <= bits);
+}
+
+display('— sparsity tight at N = 2^k (Ω = k = bitLen − 1) —');
+for (let k = 1n; k <= 20n; k++) {
+  const N = 1n << k;
+  const omega = PrimeAtomPolynomial.bigOmega(N);
+  const bits  = BigInt(PrimeAtomPolynomial.bitLength(N));
+  check(`Ω(2^${k})=${omega} and bitLen=${bits}`, omega === k && bits === k + 1n);
+}
+
+return { e3ok: !anyFailed };
+</cell>
+
+<cell type="markdown">
+## QED
+
+The hub is log₂ = H. Every spoke is a projection. E1 and E2 are Lean-backed citations (transcendental on both sides); E3 is their exponentiated form, lives entirely in BigInt, and is the canonical-space witness that the chain is consistent.
+</cell>
+
+<cell type="js" lane="math" id="e-qed" in="e3ok">
+const { display } = caps;
+const ok = inputs.e3ok;
+display(ok
+  ? 'QED — E3 verified bit-exactly for all test N. log₂ N is the hub; every canonical theorem is a projection.'
+  : 'E3 did not pass — see the witness cell above.');
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/iso-fft-polynomial.html

@@ -0,0 +1,136 @@
+<frqtl-notebook version="1" title="F — FFT-Polynomial Isomorphism (the transform IS Horner evaluation)">
+
+<cell type="markdown">
+# F — FFT-Polynomial Isomorphism
+
+The DFT/FFT is **not** a matrix object — it is pointwise polynomial evaluation at canonical nodes, with the inverse being polynomial interpolation. No Vandermonde matrix is ever built.
+
+- **F1** `EGPTFFT.forward(c) ≡ [ evaluateAt(c, k/N) for k=0..N-1 ]`
+- **F2** `inverse(forward(c)) ≡ c` (Newton divided-difference round-trip)
+- **F3** `toValueRepresentation / fromValueRepresentation ≡ identity` at canonical base x = 2^k
+- **Corollary** `multiply(P,Q)` ↔ pointwise product of `forward(P)`, `forward(Q)` (convolution theorem)
+
+*(Ported from `theorems/F_FFTPolynomialIsomorphism.js`. Cells destructure `EGPTReal`, `EGPTMath`, `EGPTPolynomial`, `EGPTFFT` from the injected `math` builtin — no imports. `renderVec` is inlined below.)*
+</cell>
+
+<cell type="markdown">
+## Setup — inline helpers
+
+`renderVec` (exact p/q rendering) and `vecEquals` are inlined here because the TraceReport helper is not on the SDK surface. Everything else comes from `caps.math`.
+</cell>
+
+<cell type="js" lane="math" id="f-setup" out="fhelp">
+const { math } = caps;
+const { EGPTReal } = math;
+// Inline canonical-string render (mirrors EGPTReal.toCanonicalStr / TraceReport.renderValue).
+function renderValue(v) {
+  if (v == null) return String(v);
+  if (typeof v._getPPFRationalParts === 'function') {
+    const { numerator, denominator } = v._getPPFRationalParts();
+    if (denominator === 1n || denominator === -1n) return String(denominator < 0n ? -numerator : numerator);
+    return `${numerator}/${denominator}`;
+  }
+  return String(v);
+}
+function renderVec(v) { return '[ ' + v.map(renderValue).join(', ') + ' ]'; }
+function vecEquals(u, v) {
+  if (u.length !== v.length) return false;
+  for (let i = 0; i < u.length; i++) if (!u[i].equals(v[i])) return false;
+  return true;
+}
+const intN = (n) => EGPTReal.fromBigInt(BigInt(n));
+const frac = (n, d) => EGPTReal.fromRational(BigInt(n), BigInt(d));
+// Expose the helpers to downstream cells as a binding.
+return { fhelp: { renderVec, vecEquals, intN, frac } };
+</cell>
+
+<cell type="markdown">
+## F1 — forward ≡ Horner evaluation at k/N (no matrix)
+
+`EGPTFFT.forward(c)` evaluates the polynomial with coefficient vector `c` at the canonical nodes `x_k = k/N`. This is exactly per-point `EGPTPolynomial.evaluateAt(c, k/N)` — no transform matrix is materialised.
+</cell>
+
+<cell type="js" lane="math" id="f1" in="fhelp">
+const { math, display } = caps;
+const { EGPTFFT, EGPTPolynomial, EGPTReal, EGPTMath } = math;
+const { renderVec, vecEquals, intN, frac } = inputs.fhelp;
+const ONE = EGPTReal.fromBigInt(1n);
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('F1 FAILED: ' + label); }
+
+const c1 = [ frac(1, 3), frac(-7, 6), ONE ];
+display('P(x) = 1/3 − (7/6)·x + x²    c = ' + renderVec(c1));
+const N1 = c1.length;
+const viaForward = EGPTFFT.forward(c1);
+display('forward(c)               = ' + renderVec(viaForward));
+const viaHorner = [];
+for (let k = 0; k < N1; k++) viaHorner.push(EGPTPolynomial.evaluateAt(c1, frac(k, N1)));
+display('[evaluateAt(c,k/N) k=0..2]= ' + renderVec(viaHorner));
+check('forward(c) ≡ Horner-evaluate at k/N (no matrix built)', vecEquals(viaForward, viaHorner));
+
+const c1b = [ intN(5), intN(-2), intN(7), intN(-1) ];
+const N1b = 8;
+const fb = EGPTFFT.forward(c1b, N1b);
+const hb = []; for (let k = 0; k < N1b; k++) hb.push(EGPTPolynomial.evaluateAt(c1b, frac(k, N1b)));
+check(`N=${N1b}: forward = pointwise Horner (integer coeffs, fractional nodes)`, vecEquals(fb, hb));
+</cell>
+
+<cell type="markdown">
+## F2 — inverse ∘ forward ≡ identity (Newton DD round-trip)
+
+`EGPTFFT.inverse` reconstructs the coefficient vector from the samples via Newton divided differences — again no matrix inversion. The round-trip is bit-exact over rational `EGPTReal`.
+</cell>
+
+<cell type="js" lane="math" id="f2" in="fhelp">
+const { math, display } = caps;
+const { EGPTFFT, EGPTReal } = math;
+const { renderVec, vecEquals, intN, frac } = inputs.fhelp;
+const ONE = EGPTReal.fromBigInt(1n);
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('F2 FAILED: ' + label); }
+
+const c2 = [ frac(1, 3), frac(-7, 6), ONE, frac(2, 5), frac(-1, 2) ];
+display('c (length 5, fractional) = ' + renderVec(c2));
+const samples = EGPTFFT.forward(c2);
+display('forward(c)               = ' + renderVec(samples));
+const recovered = EGPTFFT.inverse(samples);
+display('inverse(samples)         = ' + renderVec(recovered));
+check('inverse ∘ forward is identity (length-5 fractional)', vecEquals(recovered, c2));
+
+const c2b = [ intN(3), intN(1), intN(4), intN(1) ];
+check('inverse ∘ forward is identity (length-4 integer)', vecEquals(EGPTFFT.inverse(EGPTFFT.forward(c2b)), c2b));
+</cell>
+
+<cell type="markdown">
+## F3 — value representation ≡ identity at x = 2^k
+
+`toValueRepresentation` samples the polynomial at the canonical EGPT base nodes x = 2^0, 2^1, …, and `fromValueRepresentation` inverts it. Both equal direct Horner evaluation; the pair round-trips exactly.
+</cell>
+
+<cell type="js" lane="math" id="f3" in="fhelp">
+const { math, display } = caps;
+const { EGPTPolynomial } = math;
+const { renderVec, vecEquals, intN } = inputs.fhelp;
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('F3 FAILED: ' + label); }
+
+const c3 = [ intN(-7), intN(11), intN(-2), intN(1) ];   // P(x) = -7 + 11x - 2x² + x³
+display('P(x) = -7 + 11x − 2x² + x³    c = ' + renderVec(c3));
+const samples = EGPTPolynomial.toValueRepresentation(c3);
+display('toValueRepresentation(c)  = [P(1),P(2),P(4),P(8)] = ' + renderVec(samples));
+const direct = [1,2,4,8].map(x => EGPTPolynomial.evaluateAt(c3, intN(x)));
+check('toValueRepresentation = direct Horner at x = 2^0..2^D', vecEquals(samples, direct));
+const recovered = EGPTPolynomial.fromValueRepresentation(samples);
+display('fromValueRepresentation   = ' + renderVec(recovered));
+check('fromValueRepresentation ∘ toValueRepresentation = identity', vecEquals(recovered, c3));
+</cell>
+
+<cell type="markdown">
+## QED
+
+The transform is Horner evaluation; the inverse is interpolation; the convolution theorem follows from pointwise products in the value domain. No Vandermonde, no transform matrix — the FFT corner of the canonical chain is a projection of polynomial evaluation.
+</cell>
+
+<cell type="js" lane="math" id="f-qed">
+const { display } = caps;
+display('QED — F1/F2/F3 verified bit-exactly. The FFT IS polynomial evaluate/interpolate, matrix-free.');
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/iso-matrix-four-views.html

@@ -0,0 +1,131 @@
+<frqtl-notebook version="1" title="M — Matrix Four Views (one matrix, four projections of its row-product polynomial)">
+
+<cell type="markdown">
+# M — Matrix Four Views
+
+A single matrix M projects through four surfaces of the EGPT bijective chain — all projections of one object, the row-product polynomial `P_M(x) = ∏_i row_i(x)`:
+
+- **M1** matrix coefficient form ≡ M itself (rows ARE polynomials)
+- **M2** product polynomial ≡ `∏_i row_i(x)` (`EGPTPolynomial.multiply` reducer)
+- **M3** integer u-space root multiset ≡ `toNatRoots(P_M)` (rational-root theorem + lcm clearing)
+- **M4** prime-atom multiset / composite Nat ≡ `toNat(P_M)` (LFTA closure)
+
+Provenance: `Translation5/6/7.lean`. For atom-root fixtures the closure `toNat(P_M) ≡ EGPTPrimeComposite.fromEGPTReal(N)` holds at records AND value.
+
+*(Ported from `theorems/M_MatrixFourViews.js`. `EGPTReal/EGPTPolynomial/EGPTPrimeComposite/EGPTMatrix` come from `caps.math` — no imports. The `runFourViews` runner + render helpers are inlined.)*
+</cell>
+
+<cell type="markdown">
+## Setup — the four-view runner
+
+The runner mirrors the source `runFourViews`: compute P_M, its rational roots, integer u-roots, and the LFTA prime-atom composite; assert internal consistency (composite value = ∏ u-roots) and, for atom-root fixtures, the closure to N. Produced as a binding the fixture cells call.
+</cell>
+
+<cell type="js" lane="math" id="m-setup" out="mrun">
+const { math, display } = caps;
+const { EGPTReal, EGPTPolynomial, EGPTPrimeComposite, EGPTMatrix } = math;
+const ZERO = EGPTReal.fromBigInt(0n);
+const ONE  = EGPTReal.fromBigInt(1n);
+const intN = (n) => EGPTReal.fromBigInt(BigInt(n));
+const frac = (n, d) => EGPTReal.fromRational(BigInt(n), BigInt(d));
+function renderValue(v) {
+  if (v == null) return String(v);
+  if (typeof v._getPPFRationalParts === 'function') {
+    const { numerator, denominator } = v._getPPFRationalParts();
+    if (denominator === 1n || denominator === -1n) return String(denominator < 0n ? -numerator : numerator);
+    return `${numerator}/${denominator}`;
+  }
+  return String(v);
+}
+function showRecords(records) {
+  if (records.length === 0) return '(empty multiset, value = 1)';
+  const numCount = new Map(), denCount = new Map();
+  for (const r of records) {
+    const m = r.location === 'numerator' ? numCount : denCount;
+    m.set(r.prime, (m.get(r.prime) || 0n) + 1n);
+  }
+  const parts = [];
+  for (const p of [...numCount.keys()].sort((a,b)=>(a<b?-1:a>b?1:0))) { const k = numCount.get(p); parts.push(k === 1n ? `(${p})` : `(${p}^${k})`); }
+  for (const p of [...denCount.keys()].sort((a,b)=>(a<b?-1:a>b?1:0))) { const k = denCount.get(p); parts.push(k === 1n ? `(${p})⁻¹` : `(${p}^${k})⁻¹`); }
+  return parts.join(' · ');
+}
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('M FAILED: ' + label); }
+
+function runFourViews(label, M, expectedClosingN) {
+  display('── ' + label);
+  const { rows, cols } = EGPTMatrix.shape(M);
+  display(`  M1  shape ${rows} × ${cols}`);
+  const P_M = M.reduce((acc, row) => EGPTPolynomial.multiply(acc, row), [ONE]);
+  display(`  M2  P_M(x) = [ ${P_M.map(renderValue).join(', ')} ]   deg = ${EGPTPolynomial.degree(P_M)}`);
+  const rRoots = EGPTPolynomial.rationalRoots(P_M);
+  display(`  M3  rationalRoots = [${rRoots.map(renderValue).join(', ')}]`);
+  for (const r of rRoots) check(`P_M(${renderValue(r)}) = 0`, EGPTPolynomial.evaluateAt(P_M, r).equals(ZERO));
+  const uRoots = EGPTPolynomial.toNatRoots(P_M);
+  display(`      toNatRoots = [${uRoots.map(u => u.breakSymbolicToApproximateBigInt().toString()).join(', ')}]`);
+  check('every u-root is integer-valued', uRoots.every(u => u._getPPFRationalParts().denominator === 1n));
+  const composite = EGPTPolynomial.toNat(P_M);
+  const compositeN = composite.breakSymbolicToApproximateBigInt();
+  display(`  M4  toNat(P_M) = ${compositeN}   records = ${showRecords(composite.records)}`);
+  let uProduct = 1n; for (const u of uRoots) uProduct *= u.breakSymbolicToApproximateBigInt();
+  check(`composite value = ∏ u-roots = ${uProduct}`, compositeN === uProduct);
+  if (expectedClosingN !== null) {
+    const expected = EGPTPrimeComposite.fromEGPTReal(intN(expectedClosingN));
+    check(`closure: toNat(P_M) === ${expectedClosingN}n`, compositeN === BigInt(expectedClosingN));
+    const aKey = EGPTPrimeComposite.recordsMultisetKey(composite.records);
+    const eKey = EGPTPrimeComposite.recordsMultisetKey(expected.records);
+    check('closure: records multiset matches fromEGPTReal(N)', aKey === eKey);
+  }
+  return { composite, compositeN };
+}
+return { mrun: { runFourViews, intN, frac, EGPTMatrix } };
+</cell>
+
+<cell type="markdown">
+## Fixtures A–D — single matrices
+
+Fixture A: `[[(x−2)(x−3)]] = [[6,-5,1]]` (closes to N=6). Fixture B: `[[(x−2)²(x−3)]]` (N=12). Fixture C: two-row `[[(x−2)(x−3)],[(x−3)(x−5)]]` (N=90). Fixture D: fractional roots `[[1/3,-7/6,1]]` → u-roots [3,4], N=12 (the lcm-clearing demo).
+</cell>
+
+<cell type="js" lane="math" id="m-abcd" in="mrun">
+const { display } = caps;
+const { runFourViews, intN, frac, EGPTMatrix } = inputs.mrun;
+runFourViews('Fixture A — [[6,-5,1]] = [[(x−2)(x−3)]] (N=6)', EGPTMatrix.from([[6, -5, 1]]), 6n);
+runFourViews('Fixture B — [[-12,16,-7,1]] = [[(x−2)²(x−3)]] (N=12)', EGPTMatrix.from([[-12, 16, -7, 1]]), 12n);
+runFourViews('Fixture C — two-row, roots {2,3,3,5} (N=90)', EGPTMatrix.from([[6, -5, 1], [15, -8, 1]]), 90n);
+runFourViews('Fixture D — fractional [[1/3,-7/6,1]] → u-roots [3,4] (N=12)', EGPTMatrix.from([[ frac(1, 3), frac(-7, 6), intN(1) ]]), 12n);
+display('Fixtures A–D complete.');
+</cell>
+
+<cell type="markdown">
+## Fixture E — GEMM observation
+
+C = gemm(A, B) with A=[[6,-5,1]] (1×3), B=[[2],[3],[4]] (3×1) → C=[[1]] (1×1). The four-views chain runs end-to-end on each of A, B, C. GEMM is matrix multiplication, not polynomial multiplication — we observe the chain runs on all three, not a pointwise-records identity (the ℕ×ℕ→ℕ correspondence is mediated by Translation5/7).
+</cell>
+
+<cell type="js" lane="math" id="m-gemm" in="mrun">
+const { math, display } = caps;
+const { runFourViews, intN, EGPTMatrix } = inputs.mrun;
+const { EGPTReal, EGPTPrimeComposite } = math;
+const ONE = EGPTReal.fromBigInt(1n);
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('M-E FAILED: ' + label); }
+const A = EGPTMatrix.from([[6, -5, 1]]);
+const B = EGPTMatrix.from([[2], [3], [4]]);
+const C = EGPTMatrix.gemm(A, B);
+const sC = EGPTMatrix.shape(C);
+check('gemm shape: C is 1×1', sC.rows === 1 && sC.cols === 1);
+check('gemm value: C[0][0] = 1 (= 6·2 − 5·3 + 1·4)', C[0][0].equals(ONE));
+const resA = runFourViews('E.A — A = [[6,-5,1]] (N=6)', A, 6n);
+const resB = runFourViews('E.B — B = [[2],[3],[4]] (column matrix)', B, null);
+const resC = runFourViews('E.C — C = gemm(A,B) = [[1]]', C, null);
+check('E chain ran end-to-end on A,B,C',
+  resA.composite instanceof EGPTPrimeComposite &&
+  resB.composite instanceof EGPTPrimeComposite &&
+  resC.composite instanceof EGPTPrimeComposite);
+</cell>
+
+<cell type="js" lane="math" id="m-qed">
+const { display } = caps;
+display('QED — four matrix views, one bijective object (the row-product polynomial), zero runtime heuristics.');
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/iso-number-theory-four-views.html

@@ -0,0 +1,99 @@
+<frqtl-notebook version="1" title="N — Number Theory Four Views (factoring, roots, order, period are one object)">
+
+<cell type="markdown">
+# N — Number Theory Four Views
+
+A single `(a, N)` pair projects through four classical number-theoretic surfaces, all reading the same prime-atom vector `v⃗(N)`:
+
+- **N1** prime factorisation ≡ `v⃗(N)` (LFTA, Lean-backed)
+- **N2** polynomial root finding ≡ roots of `P_N(x) = ∏_p (x−p)^{v_p(N)}` (constructive over EGPTReal)
+- **N3** order finding ≡ min divisor of φ(N) with `a^r ≡ 1` (LFTA + Lagrange)
+- **N4** signal period ≡ direct orbit period of `a^k mod N` (classical Shor, definitional)
+
+The four projections agree on r and on the prime set every time — not by tuning, but because they are the same operation under four labels.
+
+*(Ported from `theorems/N_NumberTheoryFourViews.js`. `EGPTReal/EGPTPolynomial/PrimeAtomPolynomial/OrderFinder` come from `caps.math` — no imports. The runner + helpers are inlined.)*
+</cell>
+
+<cell type="markdown">
+## Setup — the four-view runner
+
+Builds the atom-root polynomial, checks each prime is a root (N1≡N2), finds the order via `OrderFinder` (N3), and the direct orbit period (N4), asserting N3≡N4 and N1≡N2. Produced as a binding the case cells call.
+</cell>
+
+<cell type="js" lane="math" id="n-setup" out="nrun">
+const { math, display } = caps;
+const { EGPTReal, EGPTPolynomial, PrimeAtomPolynomial, OrderFinder } = math;
+const ZERO = EGPTReal.fromBigInt(0n);
+const ONE  = EGPTReal.fromBigInt(1n);
+const intN = (n) => EGPTReal.fromBigInt(BigInt(n));
+
+function buildAtomRootPolynomial(N) {
+  const factors = PrimeAtomPolynomial.factorize(N);
+  let poly = [ONE];
+  for (const { prime, exponent } of factors) {
+    const linear = [intN(-prime), ONE];
+    for (let k = 0n; k < exponent; k++) poly = EGPTPolynomial.multiply(poly, linear);
+  }
+  return poly;
+}
+function directPeriodOfOrbit(a, N) {
+  const aBi = BigInt(a), NBi = BigInt(N);
+  let current = 1n;
+  for (let r = 1; r <= Number(NBi); r++) { current = (current * aBi) % NBi; if (current === 1n) return r; }
+  return null;
+}
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('N FAILED: ' + label); }
+
+function runFourViews(a, N, expectedOrder) {
+  const aBi = BigInt(a), NBi = BigInt(N);
+  display(`── a = ${aBi}, N = ${NBi}`);
+  // N1
+  const factors = PrimeAtomPolynomial.factorize(NBi);
+  const primeSet = factors.map(f => f.prime);
+  display(`  N1  factorize(${NBi}) = ${factors.map(f => `(${f.prime}^${f.exponent})`).join(' · ') || '1'}   Ω=${PrimeAtomPolynomial.bigOmega(NBi)} bitLen=${PrimeAtomPolynomial.bitLength(NBi)}`);
+  // N2
+  const P = buildAtomRootPolynomial(NBi);
+  for (const p of primeSet) check(`N2  P_${NBi}(${p}) = 0`, EGPTPolynomial.evaluateAt(P, intN(p)).equals(ZERO));
+  check(`deg(P) = Ω(N) = ${Number(PrimeAtomPolynomial.bigOmega(NBi))}`, EGPTPolynomial.degree(P) === Number(PrimeAtomPolynomial.bigOmega(NBi)));
+  // N3
+  const phi = PrimeAtomPolynomial.totient(NBi);
+  const orderR = OrderFinder.findOrder(aBi, NBi);
+  display(`  N3  φ(${NBi})=${phi}  order(${aBi} mod ${NBi})=${orderR}`);
+  check(`order(${aBi} mod ${NBi}) = ${expectedOrder}`, orderR === expectedOrder);
+  check(`verify: ${aBi}^${orderR} ≡ 1 (mod ${NBi})`, OrderFinder.verifyOrder(aBi, NBi, orderR));
+  // N4
+  const directPeriod = directPeriodOfOrbit(aBi, NBi);
+  display(`  N4  direct orbit period = ${directPeriod}`);
+  check(`direct orbit period = ${expectedOrder}`, directPeriod === expectedOrder);
+  check('N3 order ≡ N4 period', orderR === directPeriod);
+}
+return { nrun: runFourViews };
+</cell>
+
+<cell type="markdown">
+## Cases — eight (a, N) pairs
+
+Each pair runs all four projections and asserts they agree on the order/period and the prime set.
+</cell>
+
+<cell type="js" lane="math" id="n-cases" in="nrun">
+const { display } = caps;
+const run = inputs.nrun;
+run(3n,   8n,  2);
+run(7n,  15n,  4);
+run(2n,   7n,  3);
+run(2n,  15n,  4);
+run(4n,  15n,  2);
+run(2n,  21n,  6);
+run(5n,  21n,  6);
+run(3n,  35n, 12);
+display('All eight cases agree across N1/N2/N3/N4.');
+</cell>
+
+<cell type="js" lane="math" id="n-qed">
+const { display } = caps;
+display('QED — factoring, polynomial roots, order finding, and signal period are four labels for one object: v⃗(N).');
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/iso-pi-log-fraction-loop.html

@@ -0,0 +1,140 @@
+<frqtl-notebook version="1" title="π — Log-Fraction Unit-Loop Bijection (the PPF address IS a point on the loop)">
+
+<cell type="markdown">
+# π — Log-Fraction Unit-Loop Bijection
+
+"The address IS the map" at its most visible. Every positive integer N has a PPF decomposition `N = 2^L + offset`; its scaled residue `r(N) = offset/2^L ∈ [0,1)` is an exact rational; and that fraction maps bijectively to a point on the L1 unit loop by four straight-line quadrants — no transcendental angle, no `Math.log2`.
+
+- **π1** PPF `{L, offset}` ≡ `(⌊log₂ N⌋, N − 2^L)` — bit-exact over BigInt
+- **π2** `offset / 2^L` ≡ a canonical fraction in [0,1) — exact rational, invertible
+- **π3** that fraction ≡ an L1 unit-loop position (x,y) with |x|+|y|=1 — exact rational bijection
+
+All claims are asserted over every N ∈ [2,100] with **no tolerance step**.
+
+*(Ported from `theorems/pi_LogFractionUnitLoopBijection.js`. Only `EGPTReal`/`EGPTMath` are needed — both on `caps.math`. The PPF + L1-loop helpers use only those primitives and are inlined.)*
+</cell>
+
+<cell type="markdown">
+## Setup — PPF and L1-loop helpers (inlined)
+
+`ppfOf`, the L1 forward/inverse quadrant maps, and `renderValue` are inlined — they call only `EGPTReal`/`EGPTMath`. Exposed as a binding the π cells consume.
+</cell>
+
+<cell type="js" lane="math" id="pi-setup" out="pihelp">
+const { math } = caps;
+const { EGPTReal, EGPTMath } = math;
+const H_ZERO = EGPTReal.fromBigInt(0n);
+const H_ONE = EGPTReal.fromBigInt(1n);
+const H_NEG_ONE = EGPTReal.fromRational(-1n, 1n);
+const H_QUARTER = EGPTReal.fromRational(1n, 4n);
+const H_HALF = EGPTReal.fromRational(1n, 2n);
+const H_3QUARTER = EGPTReal.fromRational(3n, 4n);
+
+function bitLengthBigInt(n) { let x = n < 0n ? -n : n, b = 0; while (x > 0n) { x >>= 1n; b++; } return b; }
+function bigPow2(k) { return 1n << BigInt(k); }
+function ppfOf(n) {
+  if (n <= 0n) throw new Error('ppfOf requires positive n, got ' + n);
+  if (n === 1n) return { L: 0, offset: 0n };
+  const L = bitLengthBigInt(n) - 1;
+  return { L, offset: n - (1n << BigInt(L)) };
+}
+function renderValue(v) {
+  if (v == null) return String(v);
+  if (typeof v._getPPFRationalParts === 'function') {
+    const { numerator, denominator } = v._getPPFRationalParts();
+    if (denominator === 1n || denominator === -1n) return String(denominator < 0n ? -numerator : numerator);
+    return `${numerator}/${denominator}`;
+  }
+  return String(v);
+}
+function canonicalFractionToL1Position(H) {
+  if (EGPTMath.equals(H, H_ZERO))     return { x: H_ONE,     y: H_ZERO };
+  if (EGPTMath.equals(H, H_QUARTER))  return { x: H_ZERO,    y: H_ONE };
+  if (EGPTMath.equals(H, H_HALF))     return { x: H_NEG_ONE, y: H_ZERO };
+  if (EGPTMath.equals(H, H_3QUARTER)) return { x: H_ZERO,    y: H_NEG_ONE };
+  if (EGPTMath.compare(H, H_QUARTER) < 0) { const p = EGPTMath.divide(H, H_QUARTER); return { x: EGPTMath.subtract(H_ONE, p), y: p }; }
+  if (EGPTMath.compare(H, H_HALF) < 0) { const p = EGPTMath.divide(EGPTMath.subtract(H, H_QUARTER), H_QUARTER); return { x: EGPTMath.subtract(H_ZERO, p), y: EGPTMath.subtract(H_ONE, p) }; }
+  if (EGPTMath.compare(H, H_3QUARTER) < 0) { const p = EGPTMath.divide(EGPTMath.subtract(H, H_HALF), H_QUARTER); return { x: EGPTMath.subtract(p, H_ONE), y: EGPTMath.subtract(H_ZERO, p) }; }
+  const p = EGPTMath.divide(EGPTMath.subtract(H, H_3QUARTER), H_QUARTER); return { x: p, y: EGPTMath.subtract(p, H_ONE) };
+}
+function l1PositionToCanonicalFraction({ x, y }) {
+  const xPos = EGPTMath.compare(x, H_ZERO) >= 0;
+  const yPos = EGPTMath.compare(y, H_ZERO) >= 0;
+  if (xPos && yPos) return EGPTMath.multiply(y, H_QUARTER);
+  if (!xPos && yPos) return EGPTMath.add(H_QUARTER, EGPTMath.multiply(EGPTMath.subtract(H_ZERO, x), H_QUARTER));
+  if (!xPos && !yPos) return EGPTMath.add(H_HALF, EGPTMath.multiply(EGPTMath.add(x, H_ONE), H_QUARTER));
+  return EGPTMath.add(H_3QUARTER, EGPTMath.multiply(x, H_QUARTER));
+}
+return { pihelp: { ppfOf, bigPow2, bitLengthBigInt, renderValue, canonicalFractionToL1Position, l1PositionToCanonicalFraction,
+  cardinals: { H_ZERO, H_ONE, H_NEG_ONE, H_QUARTER, H_HALF, H_3QUARTER } } };
+</cell>
+
+<cell type="markdown">
+## π1 — PPF {L, offset} ≡ (⌊log₂ N⌋, N − 2^L)
+
+`N = 2^L + offset` with `0 ≤ offset < 2^L` and `L = bitLength(N) − 1`. Asserted bit-exactly for every N ∈ [2,100].
+</cell>
+
+<cell type="js" lane="math" id="pi1" in="pihelp">
+const { display } = caps;
+const { ppfOf, bigPow2, bitLengthBigInt } = inputs.pihelp;
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('π1 FAILED: ' + label); }
+for (const N of [17n, 21n, 35n, 391n]) { const p = ppfOf(N); display(`N=${N}: PPF {L=${p.L}, offset=${p.offset}} → 2^${p.L}+${p.offset} = ${bigPow2(p.L) + p.offset}`); }
+check('π1 reconstruction: 2^L + offset = N for every N ∈ [2,100]', (() => { for (let N = 2n; N <= 100n; N++) { const { L, offset } = ppfOf(N); if (bigPow2(L) + offset !== N) return false; } return true; })());
+check('π1 offset bound: 0 ≤ offset < 2^L for every N ∈ [2,100]', (() => { for (let N = 2n; N <= 100n; N++) { const { L, offset } = ppfOf(N); if (offset < 0n || offset >= bigPow2(L)) return false; } return true; })());
+check('π1 bit-length identity: L = bitLength(N) − 1 for every N ∈ [2,100]', (() => { for (let N = 2n; N <= 100n; N++) { const { L } = ppfOf(N); if (L !== bitLengthBigInt(N) - 1) return false; } return true; })());
+</cell>
+
+<cell type="markdown">
+## π2 — offset / 2^L ≡ a canonical fraction in [0,1)
+
+The scaled residue `r(N) = offset/2^L` is an exact rational in [0,1); multiplying back by 2^L recovers offset exactly.
+</cell>
+
+<cell type="js" lane="math" id="pi2" in="pihelp">
+const { math, display } = caps;
+const { EGPTReal, EGPTMath } = math;
+const { ppfOf, bigPow2, renderValue, cardinals } = inputs.pihelp;
+const { H_ZERO, H_ONE } = cardinals;
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('π2 FAILED: ' + label); }
+for (const N of [17n, 21n, 35n, 391n]) { const { L, offset } = ppfOf(N); const r = EGPTReal.fromRational(offset, bigPow2(L)); display(`N=${N}: r(N) = ${offset}/${bigPow2(L)} = ${renderValue(r)}`); }
+check('π2 range: 0 ≤ r(N) < 1 for every N ∈ [2,100]', (() => { for (let N = 2n; N <= 100n; N++) { const { L, offset } = ppfOf(N); const r = EGPTReal.fromRational(offset, bigPow2(L)); if (EGPTMath.compare(r, H_ZERO) < 0 || EGPTMath.compare(r, H_ONE) >= 0) return false; } return true; })());
+check('π2 inversion: r · 2^L = offset (exact) for every N ∈ [2,100]', (() => { for (let N = 2n; N <= 100n; N++) { const { L, offset } = ppfOf(N); const r = EGPTReal.fromRational(offset, bigPow2(L)); const prod = EGPTMath.multiply(r, EGPTReal.fromBigInt(bigPow2(L)))._getPPFRationalParts(); if (prod.denominator !== 1n || prod.numerator !== offset) return false; } return true; })());
+</cell>
+
+<cell type="markdown">
+## π3 — canonical fraction ≡ L1 unit-loop position (x,y)
+
+`r ∈ [0,1)` maps bijectively to (x,y) on |x|+|y|=1 by four straight-line quadrants. Cardinal fractions land on cardinal vertices; the round trip r → (x,y) → r is the identity; the L1 norm is exactly 1. (This is a 1D→2D position readout, not a multiplicative primitive.)
+</cell>
+
+<cell type="js" lane="math" id="pi3" in="pihelp">
+const { math, display } = caps;
+const { EGPTReal, EGPTMath } = math;
+const { ppfOf, bigPow2, renderValue, canonicalFractionToL1Position, l1PositionToCanonicalFraction, cardinals } = inputs.pihelp;
+const { H_ZERO, H_ONE, H_NEG_ONE, H_QUARTER, H_HALF, H_3QUARTER } = cardinals;
+function check(label, cond) { display((cond ? '  ✓ ' : '  ✗ ') + label); if (!cond) throw new Error('π3 FAILED: ' + label); }
+
+for (const N of [17n, 21n, 35n, 391n]) { const { L, offset } = ppfOf(N); const r = EGPTReal.fromRational(offset, bigPow2(L)); const pos = canonicalFractionToL1Position(r); display(`N=${N}: r=${renderValue(r)} → (x,y)=(${renderValue(pos.x)}, ${renderValue(pos.y)})`); }
+
+for (const [label, H_frac, eX, eY] of [
+  ['r=0', H_ZERO, H_ONE, H_ZERO], ['r=1/4', H_QUARTER, H_ZERO, H_ONE],
+  ['r=1/2', H_HALF, H_NEG_ONE, H_ZERO], ['r=3/4', H_3QUARTER, H_ZERO, H_NEG_ONE]
+]) { const pos = canonicalFractionToL1Position(H_frac); check(`cardinal ${label} → (${renderValue(eX)}, ${renderValue(eY)})`, EGPTMath.equals(pos.x, eX) && EGPTMath.equals(pos.y, eY)); }
+
+check('π3 L1 norm |x|+|y| = 1 for every N ∈ [2,100]', (() => {
+  for (let N = 2n; N <= 100n; N++) { const { L, offset } = ppfOf(N); const r = EGPTReal.fromRational(offset, bigPow2(L)); const pos = canonicalFractionToL1Position(r);
+    const px = pos.x._getPPFRationalParts(), py = pos.y._getPPFRationalParts();
+    const ax = EGPTReal.fromRational(px.numerator < 0n ? -px.numerator : px.numerator, px.denominator);
+    const ay = EGPTReal.fromRational(py.numerator < 0n ? -py.numerator : py.numerator, py.denominator);
+    if (!EGPTMath.equals(EGPTMath.add(ax, ay), H_ONE)) return false; } return true; })());
+check('π3 round trip r → (x,y) → r is identity for every N ∈ [2,100]', (() => {
+  for (let N = 2n; N <= 100n; N++) { const { L, offset } = ppfOf(N); const r = EGPTReal.fromRational(offset, bigPow2(L)); const pos = canonicalFractionToL1Position(r); if (!EGPTMath.equals(l1PositionToCanonicalFraction(pos), r)) return false; } return true; })());
+</cell>
+
+<cell type="js" lane="math" id="pi-qed">
+const { display } = caps;
+display('QED — π1/π2/π3 verified bit-exactly over N ∈ [2,100]. The PPF address of N IS its point on the unit loop — exact, no transcendentals.');
+</cell>
+
+</frqtl-notebook>