@descix/egpt-math-sdk

EGPT Math SDK — browser-first exact arithmetic over the rational field

Provides the EGPT Math engine as a pluggable browser package: a bit-exact rational arithmetic core (backed by the egpt_math_sdk_wasm Rust/WASM crate) behind a stable MathBackendProvider interface that lets you swap implementations without touching calling code.

What is this

EGPT Math replaces the standard floating-point math kernel with bit-exact rational arithmetic over prime-indexed information atoms. Operations like matrix multiplication, polynomial evaluation, and order-finding in quantum simulation run on exact ℚ values instead of approximations — producing provably correct intermediate results that track the EGPT compression chain.

This SDK package publishes the browser-runnable surface. The full EGPT math theory, Lean proof chains (P=NP capstone, bijection chain), and canonical dev core live in the FRAQTL monorepo (lib/egpt/).

Installation

npm install @descix/egpt-math-sdk

Browser Usage

import { createEgptMathSdk } from "@descix/egpt-math-sdk";

const sdk = await createEgptMathSdk({
  wasmUrl: new URL("./wasm/egpt_math_sdk_wasm_bg.wasm", import.meta.url).toString(),
  wasmModuleUrl: new URL("./wasm/egpt_math_sdk_wasm.js", import.meta.url).toString()
});

// Derived badge — never hardcoded (truth-in-labeling). Always "wasm-math" in
// this package: createEgptMathSdk() throws rather than returning an SDK for
// any other outcome (see §Publish surface below).
console.log("Backend:", sdk.activeMathBackend);  // "wasm-math"

// Rational arithmetic — real Rust/WASM compute, no JS math core in this bundle.
const a = sdk.EGPTReal.fromRational(3n, 4n);
const b = sdk.EGPTReal.fromRational(1n, 2n);
const sum = sdk.EGPTMath.add(a, b);
console.log(sum.toMathString());  // "5/4"

// Matrix multiply, routed through the polynomial bijective chain.
const A = sdk.EGPTMatrix.from([[1n, 2n], [3n, 4n]]);
const B = sdk.EGPTMatrix.from([[5n, 6n], [7n, 8n]]);
console.log(sdk.EGPTMatrix.format(sdk.EGPTMatrix.matMul(A, B), "A x B"));

Verify it yourself — egpt-math-bench

Run the canonical assertion bench COLD from the published package — no clone, no build:

npx -y -p @descix/egpt-math-sdk egpt-math-bench

It loads this package's own WASM surface (dist/wasm/) and drives the 157 canonical EGPT-Math assertions against it — real Rust/WASM arithmetic, never a JS math core. It prints a deterministic, machine-checkable summary line and exits 0 iff every runnable assertion passes:

EGPT-MATH BENCH: 157 canonical assertions | <M> runnable | <M>/<M> pass | <G> structurally-gapped (pinned) → RESULT: PASS

The <G> structurally-gapped assertions are PINNED with their missing-op reason (each GAP <id> <name> — <reason> line): they exercise dev-core-only surfaces (in-place scalar mutation, PPF-internal {N, offset} introspection, scaled-vector irrationals, exact N-gon cos/sin, and the not-yet-faced EGPTStat/EGPTComplex/TwiddleTable classes) that the WASM-only facade cannot bit-exactly reproduce without shipping the JS core (forbidden) or growing the Rust provider contract. Pass --quiet to suppress the per-gap listing.

Publish surface — WASM-only (CEO standing rule, 2026-07-10)

No JS math-core source ships in dist/. dist/index.js is built from src/browser/dist-entry.js (NOT src/browser/sdk-entry.js, which remains the DEV source entry used by the local IDE at /egpt-src/index.js and is unaffected by this rule). Every arithmetic op in the published package is a dispatch through the WasmMathBackendProvider (real Rust/WASM), never JS BigInt PPF math — scripts/verify-publish-surface.mjs asserts this on every build (probes the built bundle for symbols unique to the concrete lib/egpt/js/model/core/* implementation, plus a size ceiling; wired into make verify-publish-surface at the repo root, which also gates @descix/frqtl-sdk's equivalent rule for the physics engine).

Shipped: EGPTReal, EGPTMath, EGPTPolynomial (the 37-op provider contract), EGPTMatrix (GEMM via the row-is-a-polynomial identity), EGPTFFT (forward/inverse polynomial transform), the raw wasm arena-op facade, metadata, activeMathBackend, benchmarks.qftBaseline.

NOT shipped in this dist (all still fully available in DEV via sdk-entry.js / /egpt-src/) — because each is structurally coupled to the concrete js-reference classes (duck-typed on EGPTReal instances, _getPPFRationalParts(), etc.), and reimplementing them against the WASM facade is future work, not this Bite's scope:

• EGPTStat / EGPTStatData, Multilinear, OrderFinder, EGPTPrimeComposite, PrimeAtomPolynomial, EGPTComplex / ComplexEGPTReal / TwiddleTable, EGPTranscendental (the class — the 37-op exp2/log2 ops ARE shipped on EGPTReal/EGPTMath).
• The codec system (Encoding, Codec, TransformRegistry, buildCodecDsl, the encoding classes) and math.codec.
• EGPTdsp / factorizeWithLogRoot / presetOptions / FraqtlSession — these are already fully WASM-routable (their source, log-root-order-finding.js, dispatches every hot-loop op through the active backend), but that source file statically imports lib/egpt's multi-backend MathBackendRegistry (shared with the DEV entry) — decoupling it needs a small DI-style refactor, flagged as a follow-up rather than done here.
• EGPTMatrix.toValueReps / .fromValueReps — point-excluded: the correct op (EGPTPolynomial.toValueRepresentation/fromValueRepresentation, evaluation at canonical base nodes 2^0..2^D + Newton-DD inversion) isn't in the 37-op provider contract, and substituting the wrong operation would silently compute the wrong number — omission-with-a-loud-error was judged safer than a silent wrong answer.

Editor harness excluded. The interactive playground previously shipped at dist/editor/ (a live exerciser of the FULL class surface, including the excluded classes above) is excluded from this dist entirely — it remains available in DEV via /egpt-src/editor/.

Notebooks (dist/notebooks/) ship as data, not code, so their presence doesn't itself violate the no-core-source rule — but a subset of them reference the excluded classes above and will throw a legible error at cell-run time (FAIL LOUD, never a silently wrong answer). Known-runnable against this dist: arithmetic-basics, factorization-basics, polynomials, rational-core, matrix (all of EGPTMatrix except toValueReps/ fromValueReps), fft. Known-broken (reference an excluded class): egpt-matrix-test (uses toValueReps), stats, complex-twiddle, transcendentals, prime-composite, double-slit-rosetta-qft (uses math.codec), the iso-*/egpt-*-test theorem notebooks (OrderFinder, PrimeAtomPolynomial, EGPTPrimeComposite, EGPTStat).

The MathBackendProvider contract (BYO #4 — internal, M5)

MathBackendRegistry is NOT exported by @descix/egpt-math-sdk — not from this package's published dist/ (§Publish surface above: the dist-only entry, dist-entry.js, has exactly one backend and never registers a second one) and not from the DEV source entry either (sdk-entry.js imports MathBackendRegistry for its own internal use but does not re-export it). Do not import { MathBackendRegistry } from "@descix/egpt-math-sdk" — that import throws (no such export). The registry is monorepo-internal:

// FRAQTL monorepo development ONLY — not a published package import.
import { MathBackendRegistry } from "lib/egpt/js/model/backend/MathBackendProvider.js";

// Register a custom backend
MathBackendRegistry.register({
  id: "my-backend",
  fromBigInt: (n) => /* ... */,
  add: (a, b) => /* ... */,
  // ... full 37-op surface (see lib/egpt/js/model/backend/README.md)
});

MathBackendRegistry.select("my-backend");
// All SDK codec chains and the order-finding QFT loop now execute on your backend.

The contract is defined at lib/egpt/js/model/backend/README.md in the FRAQTL repository. Status: INTERNAL — published only after M5 (V2 transport) proves the dispatch path with honest performance numbers, and the registry itself is exposed on a public entry (it is not, as of this Bite).

Packaging policy

Published payload is dist/ and this README.md only (package.json#files). Source trees (src/, scripts/, Rust crates) are not published.

Verification:

npm run build
npm run verify:publish-surface
npm run pack:dry-run

CHANGES (M5)

M5.2 — V2 binary transport (2026-06-11)

The integer hot-loop ops (modPow, gcd, lcm) now use Uint8Array binary limb transport ([sign_byte, ...le_magnitude_bytes]) instead of string marshaling. No SharedArrayBuffer — plain ArrayBuffer copies (no COOP/COEP headers required). Builds on the egpt_math_sdk_wasm crate V2 exports: mod_pow_v2, gcd_v2, lcm_v2.

Honest performance (M2 Pro, 100 × modPow(2..101, N-1, N), N=39-bit semiprime):

• js-reference: 0.47 ms
• wasm-math V1 (string): 1.76 ms (3.77x)
• wasm-math V2 (binary): 2.06 ms (4.42x)
• V2 vs V1 ratio: 1.17x (V2 is slightly slower due to WASM call boundary overhead — string parsing was not the dominant cost; boundary crossing is)

This confirms: the remaining overhead vs js-reference is WASM call boundary cost, not serialization format. A future bulk-operation batching approach would be the next meaningful step.

M5.1 — Handle-model upgrade (2026-06-11)

Codec transforms that call EGPTReal instance-method ops (.toPrimeAtoms(), .toAtomRoot(), .fromAtomVec(), .fromAtomRoot(), breakSymbolic*) now route through MathBackendRegistry.active() via a single dispatch shim (lib/egpt/js/model/backend/handleDispatch.js). Codec chains running under the wasm-math backend now genuinely execute those ops through WASM. 50/50 parity fixtures pass (46 original + 4 new instance-op fixtures).

Architect publication recommendation (M5)

Hold — do not publish as BYO #4 yet.

Grounds: V2 binary transport shows the WASM overhead is dominated by call boundary crossing (4.4x vs js-reference), not serialization. The advertised benefit of the BYO contract is that third-party backends execute faster or differently than js-reference; at 4.4x overhead, an integrator's first experience would be a slowdown. The contract design is clean and correct (50/50 parity, FAIL-LOUD throughout); the value proposition needs bulk-operation batching or a demonstration workload where WASM compute savings dominate boundary cost. Recommendation: ship internally as M5, revisit publish after a batching benchmark demonstrates net positive throughput.

CEO/EVP decision required before publication.

In-browser code editor scaffold — REMOVED from this dist (2026-07-10)

The interactive editor scaffold (dist/editor/index.html + examples + theorem demos + tests) previously published here has been excluded from the publish surface — see §Publish surface above. It remains available for local development at /egpt-src/editor/ (served by lib/server/mounts.js off sdk/egpt-math-sdk/src/editor/).

Local Development

# Build WASM bridge (requires wasm-pack + Rust toolchain)
npm run build:wasm-bridge

# Build SDK dist
npm run build

# Run parity suite (requires built WASM)
node --test lib/egpt/js/model/backend/test/parity.test.mjs

# V1 vs V2 transport timing
node sdk/egpt-math-sdk/src/browser/n39-timing.mjs