@descix/egpt-math-sdk 0.1.0

package/dist/notebooks/arithmetic-basics.html

@@ -0,0 +1,166 @@
+<frqtl-notebook version="1" title="EGPT Arithmetic Basics — Exact Rational Operations on EGPTReal">
+
+<cell type="markdown">
+# EGPT Arithmetic Basics
+
+The EGPT math library operates on **exact rational numbers** — no floating-point rounding, no approximation. Every value is a `EGPTReal`, which internally stores a numerator and denominator as BigInts and keeps the fraction in fully reduced form at all times.
+
+This notebook walks through the four fundamental arithmetic operations (`add`, `subtract`, `multiply`, `normalDivide`) on two rational constants:
+
+- `a = 3/2`
+- `b = 5/4`
+
+Every computation below goes through the `math` builtin — the live FRQTL math SDK the IDE resolved. The active math backend is reported by the SDK itself, never asserted.
+</cell>
+
+<cell type="js" lane="math" id="backend">
+// Confirm the active backend before any arithmetic.
+// activeMathBackend is a DERIVED field from MathBackendRegistry.active().id.
+// It reads 'js-reference' by default and 'wasm-math' when the shim selects it.
+const { math, display } = caps;
+display(`Active math backend (derived from SDK): ${math.activeMathBackend}`);
+</cell>
+
+<cell type="markdown">
+## 1. Constructing exact rationals
+
+`EGPTReal.fromRational(numerator, denominator)` accepts BigInt arguments and returns an `EGPTReal` whose internal representation is the fully reduced fraction `numerator / denominator`.
+
+Calling `.toMathString()` on an `EGPTReal` returns a human-readable string like `"3/2"` for a rational value, or a log-space representation for values constructed in information space.
+</cell>
+
+<cell type="js" lane="math" id="construct" out="a, b">
+// Construct two exact rational values.
+// fromRational(numerator: BigInt, denominator: BigInt) → EGPTReal
+const { math } = caps;
+const { EGPTReal } = math;
+
+const a = EGPTReal.fromRational(3n, 2n);   // 3/2 = 1.5 exactly
+const b = EGPTReal.fromRational(5n, 4n);   // 5/4 = 1.25 exactly
+
+console.log('a =', a.toMathString());
+console.log('b =', b.toMathString());
+
+return { a, b };
+</cell>
+
+<cell type="markdown">
+## 2. Addition
+
+`EGPTMath.add(a, b)` returns a new `EGPTReal` equal to `a + b`, computed by finding the common denominator and summing numerators — all in exact integer arithmetic.
+
+Expected: `3/2 + 5/4 = 6/4 + 5/4 = 11/4`
+</cell>
+
+<cell type="js" lane="math" id="addition" in="a, b" out="sum">
+const { math } = caps;
+const { EGPTMath } = math;
+const { a, b } = inputs;   // consumed cross-cell bindings arrive on `inputs`, never as bare globals
+
+const sum = EGPTMath.add(a, b);
+
+console.log(`${a.toMathString()} + ${b.toMathString()} = ${sum.toMathString()}`);
+
+return { sum };
+</cell>
+
+<cell type="markdown">
+## 3. Subtraction
+
+`EGPTMath.subtract(a, b)` returns `a - b` with the same exact integer discipline.
+
+Expected: `3/2 - 5/4 = 6/4 - 5/4 = 1/4`
+</cell>
+
+<cell type="js" lane="math" id="subtraction" in="a, b" out="diff">
+const { math } = caps;
+const { EGPTMath } = math;
+const { a, b } = inputs;   // consumed cross-cell bindings arrive on `inputs`, never as bare globals
+
+const diff = EGPTMath.subtract(a, b);
+
+console.log(`${a.toMathString()} - ${b.toMathString()} = ${diff.toMathString()}`);
+
+return { diff };
+</cell>
+
+<cell type="markdown">
+## 4. Multiplication
+
+`EGPTMath.multiply(a, b)` returns `a × b`. For rational numbers this is simply `(num_a × num_b) / (den_a × den_b)`, then fully reduced.
+
+Expected: `3/2 × 5/4 = 15/8`
+</cell>
+
+<cell type="js" lane="math" id="multiplication" in="a, b" out="product">
+const { math } = caps;
+const { EGPTMath } = math;
+const { a, b } = inputs;   // consumed cross-cell bindings arrive on `inputs`, never as bare globals
+
+const product = EGPTMath.multiply(a, b);
+
+console.log(`${a.toMathString()} × ${b.toMathString()} = ${product.toMathString()}`);
+
+return { product };
+</cell>
+
+<cell type="markdown">
+## 5. Division
+
+`EGPTMath.normalDivide(a, b)` returns `a / b` as an exact rational — it inverts `b` and multiplies, staying entirely in integer arithmetic.
+
+Expected: `(3/2) ÷ (5/4) = (3/2) × (4/5) = 12/10 = 6/5`
+</cell>
+
+<cell type="js" lane="math" id="division" in="a, b" out="quotient">
+const { math } = caps;
+const { EGPTMath } = math;
+const { a, b } = inputs;   // consumed cross-cell bindings arrive on `inputs`, never as bare globals
+
+const quotient = EGPTMath.normalDivide(a, b);
+
+console.log(`${a.toMathString()} ÷ ${b.toMathString()} = ${quotient.toMathString()}`);
+
+return { quotient };
+</cell>
+
+<cell type="markdown">
+## 6. Summary — all four operations together
+
+The final cell mirrors the original demo's combined `checks` array, verifying that all four results are what exact rational arithmetic requires. No floating-point approximation is involved at any step.
+</cell>
+
+<cell type="js" lane="math" id="summary" in="a, b, sum, diff, product, quotient">
+// Reproduce the original demo's combined output.
+// All four results must match exact rational expectations.
+const { math } = caps;
+const { EGPTMath } = math;
+const { sum, diff, product, quotient } = inputs;   // consumed cross-cell bindings arrive on `inputs`, never as bare globals
+
+const checks = [
+  sum.toMathString(),
+  diff.toMathString(),
+  product.toMathString(),
+  quotient.toMathString()
+];
+
+const expected = ['11/4', '1/4', '15/8', '6/5'];
+
+let allPass = true;
+checks.forEach((result, i) => {
+  const pass = result === expected[i];
+  if (!pass) allPass = false;
+  console.log(`${pass ? 'PASS' : 'FAIL'}  checks[${i}]: got "${result}", expected "${expected[i]}"`);
+});
+
+console.log('');
+console.log(allPass
+  ? `All 4 arithmetic checks PASSED — exact rational semantics confirmed on '${math.activeMathBackend}' math backend.`
+  : `One or more arithmetic checks FAILED — inspect the results above.`);
+
+if (!allPass) {
+  throw new Error('Arithmetic checks failed — see console output above.');
+}
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/complex-twiddle.html

@@ -0,0 +1,148 @@
+<frqtl-notebook version="1" title="Complex Numbers in EGPT — Exact Rational Arithmetic with ComplexEGPTReal">
+
+<cell type="markdown">
+# Complex Numbers in EGPT — Exact Rational Arithmetic
+
+Classical floating-point represents complex numbers as pairs of IEEE doubles. EGPT represents them as pairs of **`EGPTReal` values** — rational numbers stored symbolically as prime-factorisation vectors. Every operation is exact: no rounding, no cancellation error, no NaN. The result of `3 + 4i` squared is `25` as a BigInt ratio, not `24.999999...`.
+
+This notebook walks through the fundamentals:
+
+1. **Constructing** complex numbers from exact integer components.
+2. **Inspecting** the symbolic representation via `toMathString()`.
+3. **Computing magnitude squared** — `|z|² = a² + b²` — using `EGPTMath.multiply` and `EGPTMath.add`, both exact.
+4. **Verifying** that the result matches the known integer value.
+
+Everything below runs through the single injected `math` capability — no URL imports, no floating-point.
+</cell>
+
+<cell type="js" lane="math" id="backend">
+// Report the active backend — derived from the SDK, never hardcoded.
+const { math, display } = caps;
+const backend = math.activeMathBackend;
+display(`Active math backend (derived): ${backend}`);
+</cell>
+
+<cell type="markdown">
+## 1. Constructing complex numbers
+
+A `ComplexEGPTReal` is a pair `(real: EGPTReal, imag: EGPTReal)`. We build each component from an exact integer via `EGPTReal.fromBigInt(n)` — the canonical integer entry point. There is no approximate coercion from JS `Number`.
+
+Here we construct:
+- `z1 = 3 + 4i` — a classic Pythagorean complex number whose magnitude is exactly 5.
+- `z2 = 5 + (-2)i` — a second number to illustrate that negative imaginary parts work identically.
+</cell>
+
+<cell type="js" lane="math" id="construct" out="z1str, z2str">
+const { math, display } = caps;
+const { EGPTReal, ComplexEGPTReal } = math;
+
+// Build z1 = 3 + 4i
+const z1 = new ComplexEGPTReal(EGPTReal.fromBigInt(3n), EGPTReal.fromBigInt(4n));
+
+// Build z2 = 5 + (-2)i
+const z2 = new ComplexEGPTReal(EGPTReal.fromBigInt(5n), EGPTReal.fromBigInt(-2n));
+
+// toMathString() renders the EGPTReal symbolic representation
+const z1str = `z1: real=${z1.real.toMathString()}, imag=${z1.imag.toMathString()}`;
+const z2str = `z2: real=${z2.real.toMathString()}, imag=${z2.imag.toMathString()}`;
+
+display(z1str);
+display(z2str);
+
+return { z1str, z2str };
+</cell>
+
+<cell type="markdown">
+## 2. The symbolic representation
+
+`toMathString()` exposes how the EGPT system stores a number internally. Small integers like `3`, `4`, `5`, `-2` appear in a compact form — but the underlying type is always an exact rational (a numerator/denominator pair of BigInts). There is no lossy float encoding happening here.
+
+Both `z1` and `z2` are confirmed to be `ComplexEGPTReal` instances, not raw JS objects.
+</cell>
+
+<cell type="js" lane="math" id="instanceof-check" out="isComplex">
+const { math, display } = caps;
+const { EGPTReal, ComplexEGPTReal } = math;
+
+// Reconstruct locally (cells are independent — no cross-cell variable sharing)
+const z1 = new ComplexEGPTReal(EGPTReal.fromBigInt(3n), EGPTReal.fromBigInt(4n));
+const z2 = new ComplexEGPTReal(EGPTReal.fromBigInt(5n), EGPTReal.fromBigInt(-2n));
+
+const isComplex = z1 instanceof ComplexEGPTReal && z2 instanceof ComplexEGPTReal;
+display(`Both are ComplexEGPTReal instances: ${isComplex}`);
+
+return { isComplex };
+</cell>
+
+<cell type="markdown">
+## 3. Magnitude squared: |z|² = a² + b²
+
+For a complex number `z = a + bi`, the magnitude squared is:
+
+```
+|z|² = a·a + b·b
+```
+
+We compute this using `EGPTMath.multiply` (exact rational multiplication) and `EGPTMath.add` (exact rational addition). For `z1 = 3 + 4i`:
+
+```
+|z1|² = 3·3 + 4·4 = 9 + 16 = 25
+```
+
+This is the Pythagorean triple `(3, 4, 5)` — the magnitude `|z1|` is exactly 5.
+</cell>
+
+<cell type="js" lane="math" id="magnitude-squared" out="magSqStr">
+const { math, display } = caps;
+const { EGPTReal, EGPTMath, ComplexEGPTReal } = math;
+
+const z1 = new ComplexEGPTReal(EGPTReal.fromBigInt(3n), EGPTReal.fromBigInt(4n));
+
+// Exact rational arithmetic — no floating-point at any step
+const realSquared = EGPTMath.multiply(z1.real, z1.real);   // 3 * 3 = 9
+const imagSquared = EGPTMath.multiply(z1.imag, z1.imag);   // 4 * 4 = 16
+const magnitudeSquared = EGPTMath.add(realSquared, imagSquared); // 9 + 16 = 25
+
+const magSqStr = magnitudeSquared.toMathString();
+display(`|z1|² = ${magSqStr}`);
+
+// Verify against expected value
+const expected = EGPTReal.fromBigInt(25n);
+const correct = magnitudeSquared.equals(expected);
+display(`Equals 25 (exact comparison via .equals()): ${correct}`);
+
+return { magSqStr };
+</cell>
+
+<cell type="markdown">
+## 4. Why `.equals()`, not `===` or `==`
+
+EGPT stores rationals as prime-factorisation vectors. Two `EGPTReal` values may have different internal representations that are mathematically equal. The only correct comparison is **`.equals()`** — a symbolic equality check on the reduced rational. Never use `==`, `===`, or string comparison (`.toMathString() ===`) to compare EGPTReal values.
+
+This is the same discipline as comparing fractions: `1/2` and `2/4` are equal but not string-identical.
+</cell>
+
+<cell type="js" lane="math" id="summary" in="z1str, z2str, isComplex, magSqStr">
+const { math, display } = caps;
+const { EGPTReal, EGPTMath, ComplexEGPTReal } = math;
+
+// Reproduce the original run(sdk) return value exactly
+const z1 = new ComplexEGPTReal(EGPTReal.fromBigInt(3n), EGPTReal.fromBigInt(4n));
+const z2 = new ComplexEGPTReal(EGPTReal.fromBigInt(5n), EGPTReal.fromBigInt(-2n));
+const magnitudeSquaredZ1 = EGPTMath.add(
+  EGPTMath.multiply(z1.real, z1.real),
+  EGPTMath.multiply(z1.imag, z1.imag)
+);
+
+const result = {
+  category: "complex-twiddle",
+  z1: { real: z1.real.toMathString(), imag: z1.imag.toMathString() },
+  z2: { real: z2.real.toMathString(), imag: z2.imag.toMathString() },
+  magnitudeSquaredZ1: magnitudeSquaredZ1.toMathString(),
+  isComplex: z1 instanceof ComplexEGPTReal && z2 instanceof ComplexEGPTReal
+};
+
+display(result);
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/double-slit-rosetta-qft.html

@@ -0,0 +1,154 @@
+<frqtl-notebook version="1" title="Double Slit → Rosetta → QFT — one notebook, three engines">
+
+<cell type="markdown">
+# Double Slit → Rosetta → QFT
+
+One environment, three engines, **individually runnable**. This dogfood proves the unified-notebook capability end-to-end:
+
+- **imperative cells** — nothing runs on load; you click Run per cell.
+- **typed object-bag handoff** — a cell declares what it consumes (`in`) and produces (`out`); the kernel wires named outputs to named inputs and marks consumers *stale* (never auto-runs them).
+- **a live physics canvas alongside math** — the double-slit simulation mounts only when you Run its canvas cell, and at most one canvas runs at a time.
+
+The loose through-line: an interference pattern *is* information; we encode it (Rosetta), and we factor a number whose period extraction is the "quantum" step of Shor's algorithm (QFT) — all classical, all here.
+</cell>
+
+<cell type="markdown">
+## 1. The double slit
+
+The canvas below DECLARES the canonical double-slit experiment (`setup="./setups/double-slit.js#setupDoubleSlit"` + `stage="480x480"` + `seed="42"`); the shim synthesizes the builder boilerplate (import → ensureEngine → ExperimentRunner → setup → mount) and runs it in the realm. It does **not** start on notebook load — click **Run** to mount and start it. The canvas also declares `produceAfter="600"`: before committing the `hist` binding (§2) the shim warms the realm 600 deterministic ticks so particles cross the stage and accumulate at the detector — so the histogram (and the §3 chart) shows **real** fringe data rather than an empty tick-0 snapshot. The runner stays **realm-internal** (it is never a kernel binding); realm-produced data reaches downstream cells via the realm→kernel binding seam (§2). Switch to another notebook and back, Run again — the pane disposes the prior runner first, so there is never a duplicate RAF loop.
+
+The canvas also declares `liveChart="detectorHistogram"`: a **same-cell** live accumulation chart renders **inside this canvas's own realm**, beneath the sim, and **fills as the sim runs** (the original-gallery model). It subscribes to the realm's **local** tick stream (`handle.on('tick')`), polls the same `detectorHistogram` projector, and redraws ~10×/s — so you watch the fringes build live. This is **orthogonal** to `produces=`: the live chart draws continuously and commits **nothing**, while `produces="hist"` derives the histogram **once** and commits the `hist` kernel binding the §3 chart consumes. Because the live chart lives in the realm, its data **never** crosses the renderer↔realm boundary.
+</cell>
+
+<cell type="module" name="./setups/double-slit.js">
+/* setupDoubleSlit — THIN ADAPTER over the canonical setup factory
+ * (WS gym-controls-as-sugar Bite 0: this cell used to hand-copy the physics —
+ * a divergent fork of lib/frqtl/objects/setup/setupDoubleSlit.js that had
+ * already drifted onto a stale `universe.init(...)` positional-argument call the
+ * engine now FAIL-LOUDs on. The canonical factory is imported by BARE SPECIFIER
+ * (a relative path here would 404 — see lib/shim/notebook/frqtl-setups-importmap.js);
+ * this cell only bridges the notebook builder's `(frqtl, universe, options)` call
+ * shape to the factory's `(universe, options)` shape — ZERO physics here. This
+ * is the SAME canonical factory the gallery-double-slit notebook and the
+ * lib/frqtl/experiments/double-slit/ page all drive — one experiment identity.)
+ */
+import { setupDoubleSlit as _setupDoubleSlit } from '@frqtl/setups/double-slit';
+
+export function setupDoubleSlit(frqtl, universe, options) {
+    return _setupDoubleSlit(universe, options);
+}
+</cell>
+
+<cell type="canvas" id="c-ds-canvas" setup="./setups/double-slit.js#setupDoubleSlit" stage="480x480" seed="42" produces="hist" produceAfter="600" liveChart="detectorHistogram"></cell>
+
+<cell type="markdown">
+## 2. Pull the interference histogram (the realm→kernel binding seam)
+
+The canvas above DECLARES its setup (`setup="./setups/double-slit.js#setupDoubleSlit"`) **and** what it produces (`produces="hist"`); the shim synthesizes the builder and runs it **realm-internal** — the runner is **never** a kernel binding (WS-NOTEBOOK-SHIM-MANAGED-BUILDER C9).
+
+After the runner mounts, the realm DERIVES a **serializable** detector histogram from the live runner via the one frozen-handle projector (`detectorHistogram(runner)`, default `produceVia`) and commits it as the `hist` binding through the single binding-commit authority `kernel.commitViewOutputs` (WS-NOTEBOOK-REALM-KERNEL-BINDING). The committed value is a plain `{ binKey: count }` object — a live runner can never cross the seam (it FAILS LOUD at the serializability gate). The `hist`-consuming cells below now resolve once you Run the canvas; before it has produced, they still FAIL LOUD ("`hist` not yet produced") — by design, never a silent empty result.
+</cell>
+
+<cell type="markdown">
+## 3. Chart the fringes
+
+The chart cell consumes `hist` and renders the interference fringes as a bar chart (Chart.js). It FAILs LOUD naming the producing cell if `hist` is not yet produced — it never silently draws an empty chart, and never auto-runs the upstream cell. (`hist` arrives via the realm→kernel binding seam — see §2.)
+</cell>
+
+<cell type="chart" id="c-ds-chart" in="hist" spec="bar:hist"></cell>
+
+<cell type="markdown">
+## 4. Encoding the pattern (Rosetta)
+
+Now we cross lanes — `frqtl` → `math`. This cell consumes `hist` (produced in the frqtl lane) and builds a Rosetta `Codec` over the histogram counts: a typed pipeline `HostFloats → EGPTReal → HostFloats` with an explicit `claim`. Running it captures per-stage `snapshots` (the object-bag-per-stage trace) — the same provenance discipline the notebook kernel generalizes. This is the `hist → chain` cross-lane handoff.
+</cell>
+
+<cell type="js" lane="math" id="c-rosetta" in="hist" out="chain">
+// Cross-lane handoff: hist (frqtl) → a Rosetta Codec (math).
+const { math, display } = caps;
+// `hist` arrives via the realm→kernel binding seam as a SERIALIZABLE plain
+// { binKey: count } object (a live runner / Map can never cross the seam). Read its
+// counts from the plain object's values (NOT Map.values()).
+const hist = inputs.hist;
+const counts = (hist && typeof hist === 'object')
+  ? Object.keys(hist).map((k) => Number(hist[k]))
+  : [];
+// Pad to a non-empty array so the chain always has something to encode.
+const payload = counts.length ? counts : [0];
+
+const codecRuntime = math.codec;   // { registry, Codec, buildCodecDsl, EncodingClasses }
+const dsl = codecRuntime.buildCodecDsl(
+  codecRuntime.registry, codecRuntime.Codec, codecRuntime.EncodingClasses
+).dsl;
+
+// A minimal typed round-trip chain over the histogram values.
+dsl.input('HostFloats', { payload, format: 'fp64' });
+dsl.push('HostFloatsToEGPTReal');
+dsl.push('EGPTRealToHostFloats');
+// Codec.run THROWS MissingClaimError unless a claim was declared first
+// (architect ground-truth correction #4).
+dsl.claim('round-trip-exact', { reference: 'round-trip-exact', tolerance: 'exact' });
+
+const built = dsl.build();
+const codec = built.codec;
+const chain = codec.run(built.headEncoding);   // RunResult { snapshots, output, trace }
+
+display(`Rosetta chain ran: ${chain.snapshots.length} snapshots ` +
+  `(input → EGPTReal → host floats); claim="${chain.claimMeta && chain.claimMeta.name}".`);
+return { chain };
+</cell>
+
+<cell type="js" lane="math" id="c-rosetta-trace" in="chain">
+// Display the per-stage snapshots (the object-bag-per-stage trace) + the
+// round-trip verdict. Ties the Rosetta paradigm to the notebook paradigm:
+// named typed handoff, captured at every stage.
+const { display } = caps;
+const chain = inputs.chain;
+const kinds = chain.snapshots.map(s => (s && s.constructor && s.constructor.kind) || '?');
+display(`stages: ${kinds.join('  →  ')}`);
+const head = chain.snapshots[0];
+const tail = chain.output;
+const roundTrips = (head && typeof head.equals === 'function')
+  ? head.equals(tail) : false;
+display(`round-trip (head.equals(output)): ${roundTrips ? 'OK (exact)' : 'differs'}`);
+</cell>
+
+<cell type="markdown">
+## 5. The QFT benchmark
+
+This `math`-lane cell drives the **same** `FraqtlSession` the QFT showcase notebook drives (`math.FraqtlSession.auto()` → `session.run(N)`) — reuse, not fork. It factors the 39-bit semiprime `549755813701 = 712321 × 771781` (the period-extraction "quantum" step of Shor's algorithm, run classically here). N and the 594-core-year comparison come from the single baseline authority `math.benchmarks.qftBaseline` — no inlined figures. This cell is deliberately **not** wired to the others: not every cell must chain.
+</cell>
+
+<cell type="js" lane="math" id="c-qft" out="qft">
+const { math, display } = caps;
+const b = math.benchmarks && math.benchmarks.qftBaseline;
+if (!b) {
+  throw new Error('math.benchmarks.qftBaseline absent — figures live in ONE authority (FAIL-LOUD).');
+}
+const N = b.benchmarkRun.N;                 // the SAME semiprime, from the authority
+const session = math.FraqtlSession.auto();
+const t0 = performance.now();
+const result = session.run(N);
+const elapsedMs = (typeof result.elapsed_ms === 'number') ? result.elapsed_ms : (performance.now() - t0);
+
+const expected = b.benchmarkRun.factors;
+const got = (result.factors || []).slice().sort((x, y) => x - y);
+const want = expected.slice().sort((x, y) => x - y);
+const ok = got.length === want.length && got.every((v, i) => v === want[i]);
+
+display(ok
+  ? `FACTORS VERIFIED on ${math.activeMathBackend}: ${N} = ${result.factors.join(' x ')} ` +
+    `in ${elapsedMs.toFixed(0)} ms — vs the published ${b.studyCompute.coreYears} core-years of supercomputer compute.`
+  : `MISMATCH: got [${result.factors}], expected [${expected}].`);
+
+const qft = { N, factors: result.factors, ok, elapsedMs, backend: math.activeMathBackend };
+return { qft };
+</cell>
+
+<cell type="markdown">
+## What this validates
+
+Interference → encoding → factoring, in one notebook, on one execution surface, every cell individually runnable, the physics canvas never auto-triggered. This is the capability bar for the CODE + GALLERY merge: the same native `<frqtl-notebook>` format and the same on-demand kernel carry markdown, math, live physics, and charts side by side.
+</cell>
+
+</frqtl-notebook>

package/dist/notebooks/egpt-fft-test.html

@@ -0,0 +1,202 @@
+<frqtl-notebook version="1" title="EGPTFFT — SDK Parity Tests (forward / inverse round-trip)">
+
+<cell type="markdown">
+# EGPTFFT — SDK Parity Tests
+
+`EGPTFFT` is a thin pedagogical wrapper over `EGPTPolynomial`'s canonical transform
+primitives. It makes the polynomial-transform interpretation of an FFT explicit: there
+is no floating-point, no Cooley-Tukey butterfly, and no complex exponential. Instead:
+
+| Method | What it computes |
+|--------|-----------------|
+| `EGPTFFT.forward(coeffs, N)` | Evaluates `P(x) = c₀ + c₁x + …` at the N uniform rational nodes `k/N` via Horner's method. Each result is an exact `EGPTReal` rational. |
+| `EGPTFFT.inverse(values, N)` | Recovers the original coefficient vector from those N samples via Newton divided-differences — bit-exact. |
+
+The round-trip identity `inverse(forward(c, N), N) === c` holds to the last bit because
+both operations live entirely in Shannon/PPF (rational) space.
+
+This notebook runs the three canonical parity tests from `sdk/egpt-math-sdk/src/editor/tests/EGPTFFTTest.js`:
+
+1. **Agreement test** — `EGPTFFT.forward` matches `EGPTPolynomial.forwardTransform` for a mixed-rational input.
+2. **Integer round-trip** — `inverse(forward(c, 4), 4) === c` for integer coefficients.
+3. **Rational round-trip** — `inverse(forward(c, 5), 5) === c` for fractional coefficients.
+
+All three tests use explicit `N` values (matching the source) to exercise the N-override
+path in `EGPTFFT.forward` / `.inverse`.
+</cell>
+
+<cell type="markdown">
+## Setup — test harness and value constructors
+
+A minimal harness (`test` / `assert` / `assertPolyEquals`) mirrors the original source.
+`passed` / `failed` counts accumulate across all phase cells via the shared `suite` binding.
+</cell>
+
+<cell type="js" lane="math" id="fft-setup" out="suite">
+const { math } = caps;
+const { EGPTReal, EGPTPolynomial } = math;
+
+// Convenient EGPTReal constructors used across all phase cells.
+const intN = (n) => EGPTReal.fromBigInt(BigInt(n));
+const frac = (n, d) => EGPTReal.fromRational(BigInt(n), BigInt(d));
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function test(name, fn) {
+    try {
+        fn();
+        console.log('  ok  — ' + name);
+        passed++;
+    } catch (err) {
+        console.log('  FAIL — ' + name + ' (' + err.message + ')');
+        failed++;
+        failures.push(name);
+    }
+}
+
+function assert(condition, message) {
+    if (!condition) throw new Error(message || 'assertion failed');
+}
+
+function assertPolyEquals(actual, expected, message) {
+    if (!EGPTPolynomial.equals(actual, expected)) throw new Error(message || 'polynomial mismatch');
+}
+
+return {
+    suite: {
+        test,
+        assert,
+        assertPolyEquals,
+        intN,
+        frac,
+        getResults: () => ({ passed, failed, failures })
+    }
+};
+</cell>
+
+<cell type="markdown">
+## Phase 1 — forward agrees with EGPTPolynomial.forwardTransform
+
+`EGPTFFT.forward(coeffs, N)` is defined as `EGPTPolynomial.forwardTransform(coeffs, N)`.
+This test verifies that identity directly for a three-element mixed-rational input with N = 3.
+
+Input: `[ 1/3, -7/6, 1 ]`  — one integer, two fractions.
+</cell>
+
+<cell type="js" lane="math" id="fft-phase1" in="suite" out="ph1">
+const { math } = caps;
+const { EGPTFFT, EGPTPolynomial } = math;
+const { test, assertPolyEquals, frac, intN, getResults } = inputs.suite;
+
+console.log('[Phase 1] EGPTFFT.forward matches EGPTPolynomial.forwardTransform');
+
+test('EGPTFFT.forward matches EGPTPolynomial.forwardTransform', () => {
+    const coeffs = [
+        frac(1, 3),
+        frac(-7, 6),
+        intN(1)
+    ];
+    assertPolyEquals(
+        EGPTFFT.forward(coeffs, 3),
+        EGPTPolynomial.forwardTransform(coeffs, 3),
+        'forward(c, 3) should equal forwardTransform(c, 3)'
+    );
+});
+
+return { ph1: getResults() };
+</cell>
+
+<cell type="markdown">
+## Phase 2 — inverse(forward(c)) round-trips integer coefficients
+
+For integer input `[ 2, -3, 0, 5 ]` with N = 4, applying `forward` then `inverse`
+must recover the original vector exactly.
+
+The N = 4 override exercises the case where the number of transform sample-points is
+equal to the number of coefficients — this is the "square Vandermonde" case where the
+forward matrix is invertible by construction.
+</cell>
+
+<cell type="js" lane="math" id="fft-phase2" in="suite" out="ph2">
+const { math } = caps;
+const { EGPTFFT } = math;
+const { test, assertPolyEquals, intN, getResults } = inputs.suite;
+
+console.log('[Phase 2] inverse(forward(c)) round trips integer coefficients');
+
+test('EGPTFFT inverse(forward(c)) round trips integer coefficients', () => {
+    const coeffs = [
+        intN(2),
+        intN(-3),
+        intN(0),
+        intN(5)
+    ];
+    assertPolyEquals(
+        EGPTFFT.inverse(EGPTFFT.forward(coeffs, 4), 4),
+        coeffs,
+        'round trip should recover [ 2, -3, 0, 5 ] exactly'
+    );
+});
+
+return { ph2: getResults() };
+</cell>
+
+<cell type="markdown">
+## Phase 3 — inverse(forward(c)) round-trips rational coefficients
+
+For fractional input `[ 1/2, -3/4, 5/7 ]` with N = 5, the forward transform produces
+five rational-valued samples at nodes `0/5, 1/5, 2/5, 3/5, 4/5`. The inverse must
+recover the original three coefficients exactly from those five over-determined samples.
+
+N = 5 > len(coeffs) = 3 exercises the "over-sampled" path: Newton divided-differences
+reconstruct the unique degree-2 polynomial fitting all five points.
+</cell>
+
+<cell type="js" lane="math" id="fft-phase3" in="suite" out="ph3">
+const { math } = caps;
+const { EGPTFFT } = math;
+const { test, assertPolyEquals, frac, getResults } = inputs.suite;
+
+console.log('[Phase 3] inverse(forward(c)) round trips rational coefficients');
+
+test('EGPTFFT inverse(forward(c)) round trips rational coefficients', () => {
+    const coeffs = [
+        frac(1, 2),
+        frac(-3, 4),
+        frac(5, 7)
+    ];
+    assertPolyEquals(
+        EGPTFFT.inverse(EGPTFFT.forward(coeffs, 5), 5),
+        coeffs,
+        'round trip should recover [ 1/2, -3/4, 5/7 ] exactly'
+    );
+});
+
+return { ph3: getResults() };
+</cell>
+
+<cell type="markdown">
+## Summary
+
+Final tally across all three parity tests.
+</cell>
+
+<cell type="js" lane="math" id="fft-summary" in="ph3">
+const { passed, failed, failures } = inputs.ph3;
+const total = passed + failed;
+
+console.log('');
+console.log('='.repeat(60));
+console.log('EGPTFFTTest TOTAL: ' + passed + '/' + total + ' passed');
+if (failures.length > 0) {
+    console.log('Failed tests:');
+    failures.forEach((f) => console.log('  - ' + f));
+}
+console.log('='.repeat(60));
+
+if (failed > 0) throw new Error('EGPTFFTTest failed: ' + failed);
+</cell>
+
+</frqtl-notebook>