@descix/egpt-math-sdk 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# @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
+
+```js
+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"));
+```
+
+## 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:
+
+```js
+// 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:
+```bash
+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
+
+```bash
+# 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
+```

package/dist/egpt-math-sdk.browser.js

@@ -0,0 +1,5 @@
+import { createEgptMathSdk } from "./index.js";
+
+if (typeof window !== "undefined") {
+  window.EgptMathSdk = { createEgptMathSdk };
+}

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+export type EgptMathSdkInitOptions = {
+  wasmUrl?: string;
+  wasmModuleUrl?: string;
+};
+
+export declare class EGPTReal {
+  static fromBigInt(n: bigint | number | string): EGPTReal;
+  static fromRational(num: bigint | number, den: bigint | number): EGPTReal;
+  static fromRationalStr(str: string): EGPTReal;
+  static readonly ZERO: EGPTReal;
+  static readonly ONE: EGPTReal;
+  static fromAtomVec(atomVec: { sign: -1 | 0 | 1; factors: { prime: bigint; exponent: bigint }[] }): EGPTReal;
+  static fromAtomRoot(term: { leadingCoeff: EGPTReal; roots: { value: EGPTReal; multiplicity: bigint }[] }): EGPTReal;
+  static gcd(a: bigint | number, b: bigint | number): bigint;
+  static lcm(a: bigint | number, b: bigint | number): bigint;
+  static modPow(base: bigint | number, exp: bigint | number, mod: bigint | number): bigint;
+
+  toCanonicalStr(): string;
+  toMathString(): string;
+  toString(): string;
+  add(other: EGPTReal): EGPTReal;
+  subtract(other: EGPTReal): EGPTReal;
+  multiply(other: EGPTReal): EGPTReal;
+  divide(other: EGPTReal): EGPTReal;
+  normalDivide(other: EGPTReal): EGPTReal;
+  mod(other: EGPTReal): EGPTReal;
+  equals(other: EGPTReal): boolean;
+  compare(other: EGPTReal): -1 | 0 | 1;
+  pow(expNum: bigint | number, expDen?: bigint | number): EGPTReal;
+  sqrt(): EGPTReal;
+  exp2(): EGPTReal;
+  log2(): EGPTReal;
+  getIntegerBitLength(): bigint;
+  breakSymbolicToApproximateBigInt(): bigint;
+  breakSymbolicToApproximateJSNumber(): number;
+  breakSymbolicToString(): string;
+  toPrimeAtoms(): { sign: -1 | 0 | 1; factors: { prime: bigint; exponent: bigint }[] };
+  toAtomRoot(): { leadingCoeff: EGPTReal; roots: { value: EGPTReal; multiplicity: bigint }[] };
+}
+
+export declare const EGPTMath: {
+  add(a: EGPTReal, b: EGPTReal): EGPTReal;
+  subtract(a: EGPTReal, b: EGPTReal): EGPTReal;
+  multiply(a: EGPTReal, b: EGPTReal): EGPTReal;
+  divide(a: EGPTReal, b: EGPTReal): EGPTReal;
+  normalDivide(a: EGPTReal, b: EGPTReal): EGPTReal;
+  mod(a: EGPTReal, b: EGPTReal): EGPTReal;
+  equals(a: EGPTReal, b: EGPTReal): boolean;
+  compare(a: EGPTReal, b: EGPTReal): -1 | 0 | 1;
+  pow(base: EGPTReal, expNum: bigint | number, expDen?: bigint | number): EGPTReal;
+  sqrt(a: EGPTReal): EGPTReal;
+  getIntegerBitLength(a: EGPTReal): bigint;
+};
+
+export declare const EGPTPolynomial: {
+  add(a: EGPTReal[], b: EGPTReal[]): EGPTReal[];
+  multiply(a: EGPTReal[], b: EGPTReal[]): EGPTReal[];
+  divide(dividend: EGPTReal[], divisor: EGPTReal[]): { quotient: EGPTReal[]; remainder: EGPTReal[] };
+  forwardTransform(coeffs: EGPTReal[], n: number): EGPTReal[];
+  inverseTransform(samples: EGPTReal[], n: number): EGPTReal[];
+  evaluateAt(poly: EGPTReal[], x: EGPTReal): EGPTReal;
+  gcd(a: EGPTReal[], b: EGPTReal[]): EGPTReal[];
+};
+
+export declare const EGPTMatrix: {
+  zeros(rows: number, cols: number): EGPTReal[][];
+  identity(n: number): EGPTReal[][];
+  from(rows: Array<Array<unknown>>): EGPTReal[][];
+  shape(M: EGPTReal[][]): { rows: number; cols: number };
+  transpose(M: EGPTReal[][]): EGPTReal[][];
+  equals(A: EGPTReal[][], B: EGPTReal[][]): boolean;
+  dotViaPolynomial(a: EGPTReal[], b: EGPTReal[]): EGPTReal;
+  matVec(M: EGPTReal[][], v: EGPTReal[]): EGPTReal[];
+  gemm(A: EGPTReal[][], B: EGPTReal[][], alpha?: EGPTReal, beta?: EGPTReal, C?: EGPTReal[][] | null): EGPTReal[][];
+  matMul(A: EGPTReal[][], B: EGPTReal[][]): EGPTReal[][];
+  evaluateRowsAt(M: EGPTReal[][], x: EGPTReal): EGPTReal[];
+  format(M: EGPTReal[][], label?: string): string;
+  print(M: EGPTReal[][], label?: string): void;
+  // toValueReps/fromValueReps are NOT part of this facade — see wasm-facade.js
+  // module doc (the correct op isn't in the 37-op provider contract).
+};
+
+export declare const EGPTFFT: {
+  forward(coeffs: EGPTReal[], n?: number): EGPTReal[];
+  inverse(values: EGPTReal[], n?: number): EGPTReal[];
+};
+
+export type EgptMathSdk = {
+  EGPTReal: typeof EGPTReal;
+  EGPTMath: typeof EGPTMath;
+  EGPTPolynomial: typeof EGPTPolynomial;
+  EGPTMatrix: typeof EGPTMatrix;
+  EGPTFFT: typeof EGPTFFT;
+  wasm: Record<string, (...args: unknown[]) => unknown>;
+  activeMathBackend: string;
+  benchmarks: { qftBaseline: Record<string, unknown> };
+  metadata: Record<string, unknown>;
+};
+
+export declare function createEgptMathSdk(options?: EgptMathSdkInitOptions): Promise<EgptMathSdk>;