nerdamer 1.1.13 → 2.0.0-rc.1

package/output/algebra/algorithms/factorUnivariate.js

@@ -0,0 +1,1072 @@
+"use strict";
+/**
+ * @module factor_univariate
+ *
+ * Exact univariate polynomial factorization over Z[x].
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.factorPolynomialBig = factorPolynomialBig;
+exports.factorPolynomial = factorPolynomial;
+const arith_1 = require("./arith");
+const poly_1 = require("./poly");
+const MAX_DISTINCT_DEGREE_ITERATIONS = 64n;
+const BASE_PRIME_BUDGET = 32;
+const PRIME_BUDGET_DEGREE_DIVISOR = 4;
+const PRIME_BUDGET_BIT_DIVISOR = 64;
+const MAX_PRIME_BUDGET = 256;
+const DEFAULT_MIN_FACTOR_PRIME = 3;
+function sqrtExactBigint(n) {
+    if (n < 0n) {
+        return null;
+    }
+    const r = (0, arith_1.bigIntSqrt)(n);
+    return r * r === n ? r : null;
+}
+function degZPoly(f) {
+    const t = (0, poly_1.zTrim)(f);
+    if (t.length === 1 && t[0] === 0n) {
+        return -1;
+    }
+    return t.length - 1;
+}
+// ============================================================================
+// MOD p ARITHMETIC (BigInt GF(p))
+// ============================================================================
+// We represent F_p[x] polynomials with the same coefficient array type as ZPoly.
+// The only difference is that coefficients are interpreted modulo p.
+const modP = (a, p) => (0, arith_1.modNorm)(a, p);
+const invP = (a, p) => (0, arith_1.modInv)(a, p);
+const asFp = (coeffs, p) => ({ p, coeffs });
+const addFp = (a, b, p) => (0, poly_1.fpAdd)(asFp(a, p), asFp(b, p)).coeffs;
+const subFp = (a, b, p) => (0, poly_1.fpSub)(asFp(a, p), asFp(b, p)).coeffs;
+const mulFp = (a, b, p) => (0, poly_1.fpMul)(asFp(a, p), asFp(b, p)).coeffs;
+const scalarMulFp = (a, c, p) => (0, poly_1.fpScale)(asFp(a, p), c).coeffs;
+const divFp = (f, g, p) => {
+    const { q, r } = (0, poly_1.fpDivRem)(asFp(f, p), asFp(g, p));
+    return [q.coeffs, r.coeffs];
+};
+const gcdFp = (f, g, p) => (0, poly_1.fpGCD)(asFp(f, p), asFp(g, p)).coeffs;
+// x^e mod f over Fp
+function powXModFp(e, f, p) {
+    if (e === 0n) {
+        return [1n];
+    }
+    let result = [1n];
+    let base = [0n, 1n]; // x
+    // reduce base mod f
+    base = divFp(base, f, p)[1];
+    let k = e;
+    while (k > 0n) {
+        if (k & 1n) {
+            result = divFp(mulFp(result, base, p), f, p)[1];
+        }
+        base = divFp(mulFp(base, base, p), f, p)[1];
+        k >>= 1n;
+    }
+    return (0, poly_1.zTrim)(result);
+}
+// pow(h, e) mod f over Fp
+function powPolyModFp(h, e, f, p) {
+    if (e === 0n) {
+        return [1n];
+    }
+    let result = [1n];
+    let base = divFp(h, f, p)[1];
+    let k = e;
+    while (k > 0n) {
+        if (k & 1n) {
+            result = divFp(mulFp(result, base, p), f, p)[1];
+        }
+        base = divFp(mulFp(base, base, p), f, p)[1];
+        k >>= 1n;
+    }
+    return (0, poly_1.zTrim)(result);
+}
+// ============================================================================
+// BERLEKAMP (correct Frobenius powers)
+// ============================================================================
+function berlekampMatrixFp(f, p) {
+    const n = degZPoly(f);
+    if (n <= 0) {
+        return [];
+    }
+    const QminusI = [];
+    for (let i = 0; i < n; i++) {
+        // FIX: x^(p^i) mod f (NOT x^(i*p))
+        const exp = (0, arith_1.pow)(p, BigInt(i));
+        const xpi = powXModFp(exp, f, p);
+        const row = new Array(n).fill(0n);
+        for (let j = 0; j < n; j++) {
+            row[j] = modP(xpi[j] ?? 0n, p);
+        }
+        row[i] = modP(row[i] - 1n, p); // subtract I
+        QminusI.push(row);
+    }
+    return QminusI;
+}
+function nullSpaceFp(A, p) {
+    const m = A.length;
+    if (m === 0) {
+        return [];
+    }
+    const n = A[0].length;
+    // row-reduced echelon form
+    const M = A.map(r => r.map(x => modP(x, p)));
+    const pivotCols = [];
+    let pivotRow = 0;
+    for (let col = 0; col < n && pivotRow < m; col++) {
+        let sel = -1;
+        for (let r = pivotRow; r < m; r++) {
+            if (M[r][col] !== 0n) {
+                sel = r;
+                break;
+            }
+        }
+        if (sel === -1) {
+            continue;
+        }
+        [M[pivotRow], M[sel]] = [M[sel], M[pivotRow]];
+        const inv = invP(M[pivotRow][col], p);
+        for (let j = col; j < n; j++) {
+            M[pivotRow][j] = modP(M[pivotRow][j] * inv, p);
+        }
+        for (let r = 0; r < m; r++) {
+            if (r === pivotRow) {
+                continue;
+            }
+            const factor = M[r][col];
+            if (factor === 0n) {
+                continue;
+            }
+            for (let j = col; j < n; j++) {
+                M[r][j] = modP(M[r][j] - factor * M[pivotRow][j], p);
+            }
+        }
+        pivotCols.push(col);
+        pivotRow++;
+    }
+    const isPivot = new Array(n).fill(false);
+    for (const c of pivotCols) {
+        isPivot[c] = true;
+    }
+    const freeCols = [];
+    for (let c = 0; c < n; c++) {
+        if (!isPivot[c]) {
+            freeCols.push(c);
+        }
+    }
+    // If no free cols, nullspace is {0}. But Berlekamp always has at least constant 1 in kernel of Q-I,
+    // so with our construction we should have at least 1 free column in typical cases.
+    const basis = [];
+    for (const free of freeCols) {
+        const v = new Array(n).fill(0n);
+        v[free] = 1n;
+        for (let i = pivotCols.length - 1; i >= 0; i--) {
+            const pc = pivotCols[i];
+            let sum = 0n;
+            for (let j = pc + 1; j < n; j++) {
+                sum = modP(sum + M[i][j] * v[j], p);
+            }
+            v[pc] = modP(-sum, p);
+        }
+        basis.push(v);
+    }
+    // Ensure we always include the constant vector (1,0,0,...)
+    // In some edge cases, elimination choices might miss it; add if absent.
+    const hasConst = basis.some(v => v[0] === 1n && v.slice(1).every(x => x === 0n));
+    if (!hasConst) {
+        const v = new Array(n).fill(0n);
+        v[0] = 1n;
+        basis.unshift(v);
+    }
+    return basis;
+}
+function vecToPoly(v, p) {
+    return (0, poly_1.zTrim)(v.map(x => modP(x, p)));
+}
+/**
+ * Deterministic Berlekamp splitting (good for small/moderate p), with CZ fallback for stubborn cases.
+ */
+function berlekampFactorFp(fIn, p) {
+    let f = (0, poly_1.zTrim)(fIn.slice());
+    const n = degZPoly(f);
+    if (n <= 0) {
+        return [f];
+    }
+    if (n === 1) {
+        return [f];
+    }
+    // Make monic
+    const inv = invP((0, poly_1.zLC)(f), p);
+    f = scalarMulFp(f, inv, p);
+    const QmI = berlekampMatrixFp(f, p);
+    const ns = nullSpaceFp(QmI, p);
+    // If kernel dimension is 1 -> irreducible
+    if (ns.length <= 1) {
+        return [f];
+    }
+    const basisPolys = ns.map(v => vecToPoly(v, p));
+    let factors = [f];
+    // Try each basis polynomial (skip the constant one)
+    for (let bIdx = 0; bIdx < basisPolys.length; bIdx++) {
+        const b = basisPolys[bIdx];
+        if (degZPoly(b) <= 0) {
+            continue;
+        }
+        const newFactors = [];
+        let changed = false;
+        for (const fac of factors) {
+            if (degZPoly(fac) <= 1) {
+                newFactors.push(fac);
+                continue;
+            }
+            let splitDone = false;
+            for (let a = 0n; a < p; a++) {
+                const bMinusA = b.slice();
+                bMinusA[0] = modP((bMinusA[0] ?? 0n) - a, p);
+                const g = gcdFp(fac, (0, poly_1.zTrim)(bMinusA), p);
+                if (degZPoly(g) > 0 && degZPoly(g) < degZPoly(fac)) {
+                    const [q] = divFp(fac, g, p);
+                    newFactors.push(g, q);
+                    changed = true;
+                    splitDone = true;
+                    break;
+                }
+            }
+            if (!splitDone) {
+                newFactors.push(fac);
+            }
+        }
+        factors = newFactors;
+        if (!changed) {
+            continue;
+        }
+    }
+    // CZ fallback (probabilistic) if still composite factors remain
+    // Uses: gcd(f, h^((p^d - 1)/2) +/- 1) for target d
+    const trySplitCZ = (fac, seed) => {
+        const d = degZPoly(fac);
+        if (d <= 1) {
+            return null;
+        }
+        // cheap deterministic "random" poly from seed
+        const h = new Array(d)
+            .fill(0n)
+            .map((_, i) => modP(seed * 17n + BigInt(i) * 31n + seed * BigInt(i), p));
+        for (let targetDeg = 1; targetDeg < d; targetDeg++) {
+            const exp = ((0, arith_1.pow)(p, BigInt(targetDeg)) - 1n) / 2n;
+            const hPow = powPolyModFp(h, exp, fac, p);
+            const g1 = gcdFp(fac, subFp(hPow, [1n], p), p);
+            if (degZPoly(g1) > 0 && degZPoly(g1) < d) {
+                const [q] = divFp(fac, g1, p);
+                return [g1, q];
+            }
+            const g2 = gcdFp(fac, addFp(hPow, [1n], p), p);
+            if (degZPoly(g2) > 0 && degZPoly(g2) < d) {
+                const [q] = divFp(fac, g2, p);
+                return [g2, q];
+            }
+        }
+        return null;
+    };
+    for (let iter = 1n; iter <= MAX_DISTINCT_DEGREE_ITERATIONS; iter++) {
+        let changed = false;
+        const newFactors = [];
+        for (const fac of factors) {
+            if (degZPoly(fac) <= 1) {
+                newFactors.push(fac);
+                continue;
+            }
+            const split = trySplitCZ(fac, iter);
+            if (split) {
+                newFactors.push(split[0], split[1]);
+                changed = true;
+            }
+            else {
+                newFactors.push(fac);
+            }
+        }
+        factors = newFactors;
+        if (!changed) {
+            break;
+        }
+    }
+    return factors;
+}
+// ============================================================================
+// HENSEL LIFTING (BigInt, two-factor step + multi-factor tree)
+// ============================================================================
+// NOTE: All generic univariate (Z/mZ)[x] operations are centralized in poly.ts
+// (zTrimMod/zAddMod/zSubMod/zMulMod/zScaleMod/zDivRemMod).
+function extendedGcdMod(a, b, m) {
+    let old_r = (0, poly_1.zTrimMod)(a, m);
+    let r = (0, poly_1.zTrimMod)(b, m);
+    let old_s = [1n];
+    let s = [0n];
+    let old_t = [0n];
+    let t = [1n];
+    while (!(0, poly_1.zIsZero)(r)) {
+        const { q, r: rem } = (0, poly_1.zDivRemMod)(old_r, r, m);
+        old_r = r;
+        r = rem;
+        old_s = (0, poly_1.zSubMod)(old_s, (0, poly_1.zMulMod)(q, s, m), m);
+        old_t = (0, poly_1.zSubMod)(old_t, (0, poly_1.zMulMod)(q, t, m), m);
+        // shift
+        [old_s, s] = [s, old_s];
+        [old_t, t] = [t, old_t];
+    }
+    // make gcd monic
+    if (!(0, poly_1.zIsZero)(old_r)) {
+        const inv = invP((0, poly_1.zLC)(old_r), m);
+        old_r = (0, poly_1.zScaleMod)(old_r, inv, m);
+        old_s = (0, poly_1.zScaleMod)(old_s, inv, m);
+        old_t = (0, poly_1.zScaleMod)(old_t, inv, m);
+    }
+    return [old_r, old_s, old_t];
+}
+/**
+ * Two-factor Hensel lift step:
+ * given f ≡ g*h (mod pk), and s*g + t*h ≡ 1 (mod pk),
+ * lift to modulus pkNext = pk*p.
+ */
+function henselStep(f, g, h, s, t, p, pk) {
+    const pkNext = pk * p;
+    // e = f - g*h mod pkNext
+    const gh = (0, poly_1.zMulMod)(g, h, pkNext);
+    const e = (0, poly_1.zSubMod)((0, poly_1.zTrimMod)(f, pkNext), gh, pkNext);
+    // Compute correction:
+    // q,r = (s*e) / h  (mod pkNext)  so that deg(r) < deg(h)
+    const se = (0, poly_1.zMulMod)(s, e, pkNext);
+    const { q, r } = (0, poly_1.zDivRemMod)(se, h, pkNext);
+    // g' = g + t*e + q*g  (mod pkNext)
+    let gNew = (0, poly_1.zAddMod)(g, (0, poly_1.zMulMod)(t, e, pkNext), pkNext);
+    gNew = (0, poly_1.zAddMod)(gNew, (0, poly_1.zMulMod)(q, g, pkNext), pkNext);
+    // h' = h + r (mod pkNext)
+    const hNew = (0, poly_1.zAddMod)(h, r, pkNext);
+    // Update Bezout:
+    // b = s*g' + t*h'  (mod pkNext)
+    const b = (0, poly_1.zAddMod)((0, poly_1.zMulMod)(s, gNew, pkNext), (0, poly_1.zMulMod)(t, hNew, pkNext), pkNext);
+    // c = b - 1
+    const c = (0, poly_1.zSubMod)(b, [1n], pkNext);
+    // q2,r2 = (s*c)/h'  (mod pkNext)
+    const sc = (0, poly_1.zMulMod)(s, c, pkNext);
+    const { q: q2, r: r2 } = (0, poly_1.zDivRemMod)(sc, hNew, pkNext);
+    const sNew = (0, poly_1.zSubMod)(s, r2, pkNext);
+    let tNew = (0, poly_1.zSubMod)(t, (0, poly_1.zMulMod)(t, c, pkNext), pkNext);
+    tNew = (0, poly_1.zSubMod)(tNew, (0, poly_1.zMulMod)(q2, gNew, pkNext), pkNext);
+    return {
+        g: (0, poly_1.zTrimMod)(gNew, pkNext),
+        h: (0, poly_1.zTrimMod)(hNew, pkNext),
+        s: (0, poly_1.zTrimMod)(sNew, pkNext),
+        t: (0, poly_1.zTrimMod)(tNew, pkNext),
+    };
+}
+function henselLiftMulti(f, factorsModP, pNum, power) {
+    if (factorsModP.length === 0) {
+        return [];
+    }
+    if (factorsModP.length === 1) {
+        return [(0, poly_1.zPrimitivePart)(f)];
+    }
+    const p = BigInt(pNum);
+    function toZPolyFromFp(fp) {
+        // coefficients already in [0,p-1], embed into bigint
+        return (0, poly_1.zTrim)(fp.map(c => BigInt(c)));
+    }
+    function buildTree(polys, mod) {
+        if (polys.length === 1) {
+            return { poly: (0, poly_1.zTrimMod)(polys[0], mod) };
+        }
+        const mid = Math.floor(polys.length / 2);
+        const left = buildTree(polys.slice(0, mid), mod);
+        const right = buildTree(polys.slice(mid), mod);
+        const poly = (0, poly_1.zMulMod)(left.poly, right.poly, mod);
+        const [, s, t] = extendedGcdMod(left.poly, right.poly, mod);
+        return { poly, s, t, left, right };
+    }
+    function liftTree(node, target, pk) {
+        if (!node.left || !node.right) {
+            return;
+        }
+        const lifted = henselStep(target, node.left.poly, node.right.poly, node.s, node.t, p, pk);
+        node.left.poly = lifted.g;
+        node.right.poly = lifted.h;
+        node.s = lifted.s;
+        node.t = lifted.t;
+        liftTree(node.left, lifted.g, pk);
+        liftTree(node.right, lifted.h, pk);
+    }
+    function collectLeaves(node) {
+        if (!node.left && !node.right) {
+            return [node.poly];
+        }
+        return [
+            ...(node.left ? collectLeaves(node.left) : []),
+            ...(node.right ? collectLeaves(node.right) : []),
+        ];
+    }
+    // Start modulus pk = p (k=1)
+    let pk = p;
+    const factorsZ = factorsModP.map(toZPolyFromFp);
+    const tree = buildTree(factorsZ, pk);
+    // Lift k=1..power-1 to pk = p^power
+    for (let k = 1; k < power; k++) {
+        const pkNext = pk * p;
+        const target = (0, poly_1.zTrimMod)(f, pkNext);
+        // One global step to pkNext is achieved by calling henselStep with pk (current modulus)
+        liftTree(tree, target, pk);
+        pk = pkNext;
+    }
+    return collectLeaves(tree).map(poly => (0, poly_1.zTrimMod)(poly, pk));
+}
+// ============================================================================
+// RECOMBINATION (BigInt exact division) — FIXED seed (start at 1)
+// ============================================================================
+function combinations(n, k) {
+    const res = [];
+    const combo = [];
+    function rec(start) {
+        if (combo.length === k) {
+            res.push(combo.slice());
+            return;
+        }
+        for (let i = start; i < n; i++) {
+            combo.push(i);
+            rec(i + 1);
+            combo.pop();
+        }
+    }
+    rec(0);
+    return res;
+}
+function recombineFactorsBig(f, lifted, modulus) {
+    const result = [];
+    let remaining = (0, poly_1.zTrim)(f.slice());
+    const n = lifted.length;
+    const used = new Set();
+    // Try increasing subset sizes
+    for (let size = 1; size < n; size++) {
+        const combos = combinations(n, size);
+        for (const combo of combos) {
+            if (combo.some(i => used.has(i))) {
+                continue;
+            }
+            // FIX: start at 1n, not lc
+            let prod = [1n];
+            for (const idx of combo) {
+                prod = (0, poly_1.zMulMod)(prod, lifted[idx], modulus);
+            }
+            const candidateSym = (0, poly_1.zToSymmetricMod)(prod, modulus);
+            const { primitive: cand } = (0, poly_1.zNormalizePrimitiveSign)(candidateSym);
+            if (degZPoly(cand) <= 0) {
+                continue;
+            }
+            const q = (0, poly_1.zTryDivExact)(remaining, cand);
+            if (q) {
+                result.push(cand);
+                remaining = q;
+                for (const idx of combo) {
+                    used.add(idx);
+                }
+                if (degZPoly(remaining) <= 0) {
+                    // consumed everything
+                    return result;
+                }
+            }
+        }
+    }
+    if (degZPoly(remaining) > 0) {
+        result.push((0, poly_1.zPrimitivePart)(remaining));
+    }
+    return result;
+}
+// ============================================================================
+// PRIME SELECTION + BOUNDS (BigInt exact)
+// ============================================================================
+function toFpPolyFromZ(f, p) {
+    return (0, poly_1.zTrim)(f.map(c => modP(c, p)));
+}
+function countFactorsModP_Berlekamp(f, pNum) {
+    const p = BigInt(pNum);
+    const fMod = toFpPolyFromZ(f, p);
+    const lc = (0, poly_1.zLC)(fMod);
+    const fMonic = lc === 1n ? fMod : scalarMulFp(fMod, invP(lc, p), p);
+    const QmI = berlekampMatrixFp(fMonic, p);
+    const ns = nullSpaceFp(QmI, p);
+    return ns.length; // kernel dimension
+}
+function coefficientBoundMignotte(f) {
+    // bound = 2^n * ||f||_2, where ||f||_2 = sqrt(sum c^2)
+    const n = degZPoly(f);
+    let sum = 0n;
+    for (const c of f) {
+        sum += c * c;
+    }
+    const norm = (0, arith_1.bigIntSqrt)(sum) + ((0, arith_1.bigIntSqrt)(sum) * (0, arith_1.bigIntSqrt)(sum) === sum ? 0n : 1n); // ceil sqrt
+    const twoPow = 1n << BigInt(Math.max(0, n));
+    return twoPow * norm;
+}
+function primeBudgetForUniZ(f) {
+    // Adaptive budget: grows (slowly) with degree and coefficient bit-size.
+    // Goal: terminate deterministically, but avoid giving up too early on hard inputs.
+    const n = Math.max(0, degZPoly(f));
+    let maxAbs = 0n;
+    for (const c of f) {
+        const a = c < 0n ? -c : c;
+        if (a > maxAbs) {
+            maxAbs = a;
+        }
+    }
+    const bits = (0, arith_1.bigintBitLength)(maxAbs);
+    // Scale the baseline prime budget with polynomial degree and coefficient size.
+    let budget = BASE_PRIME_BUDGET +
+        Math.ceil(n / PRIME_BUDGET_DEGREE_DIVISOR) +
+        Math.ceil(bits / PRIME_BUDGET_BIT_DIVISOR);
+    // Clamp to a reasonable range.
+    if (budget < BASE_PRIME_BUDGET) {
+        budget = BASE_PRIME_BUDGET;
+    }
+    if (budget > MAX_PRIME_BUDGET) {
+        budget = MAX_PRIME_BUDGET;
+    }
+    return budget;
+}
+function findGoodPrimeBig(f, minPrime = DEFAULT_MIN_FACTOR_PRIME, maxPrimes = undefined) {
+    const lc = (0, arith_1.abs)((0, poly_1.zLC)(f));
+    const df = (0, poly_1.zDerivative)(f);
+    const budget = (maxPrimes ?? primeBudgetForUniZ(f)) | 0;
+    if (!Number.isFinite(budget) || budget <= 0) {
+        throw new arith_1.PrimeSelectionError('findGoodPrimeBig: invalid maxPrimes', { budget });
+    }
+    let bestP = 0;
+    let bestCount = Number.POSITIVE_INFINITY;
+    let tried = 0;
+    let pNum = (0, arith_1.nextPrime32)(Math.max(2, minPrime));
+    while (tried < budget) {
+        tried++;
+        const pBig = BigInt(pNum);
+        // Reject primes dividing the leading coefficient (degree drop)
+        if (lc % pBig === 0n) {
+            pNum = (0, arith_1.nextPrime32)(pNum + 1);
+            continue;
+        }
+        // square-free test: gcd(f mod p, f' mod p) == 1
+        const p = pBig;
+        const fMod = toFpPolyFromZ(f, p);
+        const dfMod = toFpPolyFromZ(df, p);
+        const g = gcdFp(fMod, dfMod, p);
+        if (degZPoly(g) !== 0) {
+            pNum = (0, arith_1.nextPrime32)(pNum + 1);
+            continue;
+        }
+        const cnt = countFactorsModP_Berlekamp(f, pNum);
+        if (cnt < bestCount) {
+            bestCount = cnt;
+            bestP = pNum;
+            if (cnt <= 2) {
+                break;
+            }
+        }
+        pNum = (0, arith_1.nextPrime32)(pNum + 1);
+    }
+    if (bestP === 0) {
+        throw new arith_1.PrimeSelectionError(`Could not find suitable prime after trying ${tried} primes (budget=${budget})`, {
+            tried,
+            budget,
+            minPrime,
+        });
+    }
+    return { p: bestP, numFactors: bestCount };
+}
+// ============================================================================
+// SQUARE-FREE FACTORIZATION (BigInt)
+// ============================================================================
+/**
+ * Square-free factorization over **ℤ** (BigInt).
+ *
+ * Returns a list of pairs `[g_i, m_i]` such that:
+ *   f = ∏ g_i^{m_i}
+ * and each g_i is square-free and pairwise coprime.
+ *
+ * Implementation follows the standard gcd-with-derivative approach:
+ * - Let d = f' and g = gcd(f, d)
+ * - Repeatedly split out square-free parts by dividing by g and updating g with gcd steps.
+ *
+ * @param f Primitive, trimmed polynomial.
+ * @returns Array of `[factor, multiplicity]` pairs.
+ */
+function squareFreeFactorizationBig(f) {
+    f = (0, poly_1.zTrim)(f);
+    if (degZPoly(f) <= 0) {
+        return [];
+    }
+    // make primitive
+    f = (0, poly_1.zPrimitivePart)(f);
+    const df = (0, poly_1.zDerivative)(f);
+    if ((0, poly_1.zIsZero)(df)) {
+        return [[f, 1]];
+    }
+    let g = (0, poly_1.zGcdPrimitivePRS)(f, df);
+    if (degZPoly(g) === 0) {
+        return [[f, 1]];
+    }
+    const sq = (0, poly_1.zTryDivExact)(f, g);
+    if (!sq) {
+        return [[f, 1]];
+    }
+    let w = sq;
+    let i = 1;
+    const out = [];
+    while (degZPoly(w) > 0) {
+        const nextG = (0, poly_1.zGcdPrimitivePRS)(g, w);
+        const factor = (0, poly_1.zTryDivExact)(w, nextG);
+        if (factor && degZPoly(factor) > 0) {
+            out.push([(0, poly_1.zPrimitivePart)(factor), i]);
+        }
+        w = nextG;
+        const gDiv = (0, poly_1.zTryDivExact)(g, nextG);
+        if (!gDiv) {
+            break;
+        }
+        g = gDiv;
+        i++;
+    }
+    return out;
+}
+// ============================================================================
+// MAIN SQUARE-FREE FACTORING OVER bigint (Zassenhaus outline)
+// ============================================================================
+function tryFactorQuarticEvenZ(f) {
+    f = (0, poly_1.zTrim)(f);
+    if (degZPoly(f) !== 4) {
+        return null;
+    }
+    const a0 = f[0] ?? 0n;
+    const a1 = f[1] ?? 0n;
+    const a2 = f[2] ?? 0n;
+    const a3 = f[3] ?? 0n;
+    const a4 = f[4] ?? 0n;
+    if (a4 === 0n) {
+        return null;
+    }
+    // Only handle monic quartics for now (covers current failures).
+    if (a4 !== 1n) {
+        return null;
+    }
+    // If odd terms present, not an even quartic.
+    if (a1 !== 0n || a3 !== 0n) {
+        return null;
+    }
+    // 1) Even-quartic split: x^4 + a2*x^2 + a0 = (x^2 + u*x + v)(x^2 - u*x + v)
+    // Requires v^2 = a0 and u^2 = 2*v - a2.
+    const v = sqrtExactBigint(a0);
+    if (v !== null) {
+        const u2 = 2n * v - a2;
+        const u = sqrtExactBigint(u2);
+        if (u !== null) {
+            const f1 = [v, u, 1n]; // x^2 + u*x + v
+            const f2 = [v, -u, 1n]; // x^2 - u*x + v
+            return [(0, poly_1.zPrimitivePart)(f1), (0, poly_1.zPrimitivePart)(f2)];
+        }
+    }
+    // 2) Biquadratic: treat as quadratic in t=x^2: t^2 + a2*t + a0.
+    // Roots are r1,r2 = (-a2 ± sqrt(a2^2 - 4*a0)) / 2; need integer roots.
+    const disc = a2 * a2 - 4n * a0;
+    const s = sqrtExactBigint(disc);
+    if (s !== null) {
+        const n1 = -a2 + s;
+        const n2 = -a2 - s;
+        if (n1 % 2n === 0n && n2 % 2n === 0n) {
+            const r1 = n1 / 2n;
+            const r2 = n2 / 2n;
+            // t^2 + a2*t + a0 = (t - r1)(t - r2) => (x^2 - r1)(x^2 - r2)
+            const g1 = [-r1, 0n, 1n];
+            const g2 = [-r2, 0n, 1n];
+            return [(0, poly_1.zPrimitivePart)(g1), (0, poly_1.zPrimitivePart)(g2)];
+        }
+    }
+    return null;
+}
+/**
+ * Stride substitution: if all nonzero exponents in f share a common divisor s >= 2,
+ * write f(x) = g(x^s) where g has degree n/s. Factor g over Z, then for each factor
+ * h(t) of g, expand h(x^s) and recursively factor it (it may split further).
+ *
+ * Examples:
+ *   x^6+4x^4+16x^2+64, s=2 → g(t)=t^3+4t^2+16t+64=(t+4)(t^2+16) → (x^2+4)(x^4+16)
+ *   x^8+x^4+1, s=4 → g(t)=t^2+t+1 (irreducible) → returns null, but then
+ *     tryFactorQuarticEvenZ or Berlekamp handles x^8+x^4+1 directly.
+ */
+function tryFactorStrideSubstitutionZ(f) {
+    f = (0, poly_1.zTrim)(f);
+    const n = degZPoly(f);
+    if (n < 4) {
+        return null;
+    }
+    // Find stride = gcd of all nonzero exponent indices
+    let stride = 0;
+    for (let i = 1; i < f.length; i++) {
+        if ((f[i] ?? 0n) !== 0n) {
+            stride = stride === 0 ? i : Number((0, arith_1.gcd)(BigInt(stride), BigInt(i)));
+        }
+    }
+    if (stride < 2) {
+        return null;
+    }
+    // Build g(t) where f(x) = g(x^stride)
+    const gLen = Math.floor(n / stride) + 1;
+    const g = new Array(gLen).fill(0n);
+    for (let i = 0; i < f.length; i++) {
+        const c = f[i] ?? 0n;
+        if (c !== 0n) {
+            if (i % stride !== 0) {
+                return null; // Safety check
+            }
+            g[i / stride] = c;
+        }
+    }
+    // Factor g(t). Try factorPolynomialBig first; if it fails to split,
+    // fall back to rational root search (catches cases where Hensel lifting
+    // fails due to bad prime/factor grouping on small polynomials).
+    let gResult = factorPolynomialBig((0, poly_1.zTrim)(g));
+    if (!gResult.factors || gResult.factors.length <= 1) {
+        // Rational root fallback: try divisors of the constant term / leading coeff
+        const gTrimmed = (0, poly_1.zTrim)(g);
+        const gDeg = degZPoly(gTrimmed);
+        if (gDeg >= 2 && gDeg <= 6) {
+            const constTerm = gTrimmed[0] ?? 0n;
+            const leadCoeff = gTrimmed[gDeg] ?? 1n;
+            if (constTerm !== 0n) {
+                const constDivs = (0, arith_1.getDivisors)(constTerm < 0n ? -constTerm : constTerm);
+                const leadDivs = (0, arith_1.getDivisors)(leadCoeff < 0n ? -leadCoeff : leadCoeff);
+                for (const p_val of constDivs) {
+                    for (const q_val of leadDivs) {
+                        for (const sign of [1n, -1n]) {
+                            const numer = sign * p_val;
+                            // Evaluate q^deg * g(numer/q) to avoid fractions
+                            let evalResult = 0n;
+                            for (let i = 0; i <= gDeg; i++) {
+                                const coeff = gTrimmed[i] ?? 0n;
+                                let numerPow = 1n;
+                                for (let j = 0; j < i; j++) {
+                                    numerPow *= numer;
+                                }
+                                let qPow = 1n;
+                                for (let j = 0; j < gDeg - i; j++) {
+                                    qPow *= q_val;
+                                }
+                                evalResult += coeff * numerPow * qPow;
+                            }
+                            if (evalResult === 0n) {
+                                // Found root numer/q_val. Factor is (q_val*t - numer).
+                                const linFactor = [-numer, q_val];
+                                const quotient = (0, poly_1.zTryDivExact)(gTrimmed, linFactor);
+                                if (quotient) {
+                                    // Rebuild factorization result
+                                    const quotResult = factorPolynomialBig(quotient);
+                                    const newFactors = [
+                                        { coefficients: (0, poly_1.zTrim)(linFactor), multiplicity: 1 },
+                                    ];
+                                    for (const f of quotResult.factors) {
+                                        newFactors.push(f);
+                                    }
+                                    gResult = {
+                                        content: quotResult.content,
+                                        factors: newFactors,
+                                    };
+                                    break;
+                                }
+                            }
+                        }
+                        if (gResult.factors.length > 1) {
+                            break;
+                        }
+                    }
+                    if (gResult.factors.length > 1) {
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if (!gResult.factors || gResult.factors.length <= 1) {
+        return null; // g is irreducible, substitution didn't help
+    }
+    // Expand each factor h(t) → h(x^stride) and recursively factor
+    const out = [];
+    for (const factor of gResult.factors) {
+        const hCoeffs = factor.coefficients;
+        const mult = factor.multiplicity ?? 1;
+        // Build h(x^stride)
+        const expanded = new Array((hCoeffs.length - 1) * stride + 1).fill(0n);
+        for (let i = 0; i < hCoeffs.length; i++) {
+            expanded[i * stride] = hCoeffs[i];
+        }
+        // Recursively factor (h(x^stride) may split further, e.g. x^4+16 might factor)
+        const subFactors = factorSquareFreeBig((0, poly_1.zTrim)(expanded));
+        for (let k = 0; k < mult; k++) {
+            out.push(...subFactors);
+        }
+    }
+    // Handle content
+    if (gResult.content !== 1n && gResult.content !== -1n) {
+        out.unshift([gResult.content]);
+    }
+    else if (gResult.content === -1n && out.length > 0) {
+        out[0] = out[0].map(c => -c);
+    }
+    return out.length > 1 ? out : null;
+}
+function factorSquareFreeBig(f) {
+    f = (0, poly_1.zTrim)(f);
+    if (degZPoly(f) <= 1) {
+        return [(0, poly_1.zPrimitivePart)(f)];
+    }
+    // Cheap special cases that Berlekamp/Hensel sometimes misses due to recombination heuristics.
+    const quartic = tryFactorQuarticEvenZ(f);
+    if (quartic) {
+        return quartic;
+    }
+    // Stride substitution: if all nonzero terms have exponents divisible by some
+    // stride s >= 2 (e.g. only even-degree terms when s=2), substitute t = x^s,
+    // factor the lower-degree polynomial g(t), then expand each factor h(t) back
+    // to h(x^s) and recursively factor (since h(x^s) may split further over Z[x]).
+    // Example: x^6+4x^4+16x^2+64 with s=2 gives t^3+4t^2+16t+64 = (t+4)(t^2+16),
+    //   yielding (x^2+4)(x^4+16).
+    const strideSub = tryFactorStrideSubstitutionZ(f);
+    if (strideSub) {
+        return strideSub;
+    }
+    // bound (BigInt exact)
+    const bound = coefficientBoundMignotte(f);
+    const lcAbs = (0, arith_1.abs)((0, poly_1.zLC)(f));
+    // pick prime: do NOT conclude irreducible from a single prime.
+    // A reducible polynomial over ℤ can be irreducible modulo some primes, so
+    // keep trying until Berlekamp actually splits (within a deterministic budget).
+    let pNum;
+    let p;
+    const df = (0, poly_1.zDerivative)(f);
+    const budget = primeBudgetForUniZ(f);
+    // Start from a "good" prime if possible, but keep searching until we get a split.
+    let startPrime = 3;
+    try {
+        startPrime = findGoodPrimeBig(f).p;
+    }
+    catch {
+        startPrime = 3;
+    }
+    let tried = 0;
+    let cand = (0, arith_1.nextPrime32)(Math.max(2, startPrime));
+    let factorsModP_monic;
+    while (tried < budget) {
+        tried++;
+        const pBig = BigInt(cand);
+        // Reject primes dividing the leading coefficient (degree drop)
+        if (modP((0, poly_1.zLC)(f), pBig) === 0n) {
+            cand = (0, arith_1.nextPrime32)(cand + 1);
+            continue;
+        }
+        // square-free test: gcd(f mod p, f' mod p) == 1
+        const fModTry = toFpPolyFromZ(f, pBig);
+        const dfModTry = toFpPolyFromZ(df, pBig);
+        const g = gcdFp(fModTry, dfModTry, pBig);
+        if (degZPoly(g) !== 0) {
+            cand = (0, arith_1.nextPrime32)(cand + 1);
+            continue;
+        }
+        // Factor mod p (Berlekamp)
+        const facs = berlekampFactorFp(fModTry, pBig);
+        if (facs.length > 1) {
+            pNum = cand;
+            p = pBig;
+            factorsModP_monic = facs;
+            break;
+        }
+        cand = (0, arith_1.nextPrime32)(cand + 1);
+    }
+    if (!pNum || !p || !factorsModP_monic) {
+        return [(0, poly_1.zPrimitivePart)(f)];
+    }
+    // lifting height: find k with p^k > 2*lc*bound
+    const target = 2n * lcAbs * bound;
+    let k = 1;
+    let modulus = p;
+    while (modulus <= target) {
+        modulus *= p;
+        k++;
+    }
+    // Berlekamp factors a monic polynomial; we need product == f (mod p).
+    // Restore leading coefficient by scaling one factor by lc(f) mod p.
+    const lcModP = modP((0, poly_1.zLC)(f), p);
+    const factorsModP = factorsModP_monic.map(g => g.slice());
+    if (lcModP !== 1n) {
+        factorsModP[0] = scalarMulFp(factorsModP[0], lcModP, p);
+    }
+    // Hensel lift to p^k
+    const lifted = henselLiftMulti((0, poly_1.zTrim)(f), factorsModP, pNum, k);
+    // Recombine (BigInt exact)
+    const recombined = recombineFactorsBig(f, lifted, modulus);
+    // If recombination returns same polynomial, treat as irreducible
+    if (recombined.length === 1) {
+        const a = (0, poly_1.zPrimitivePart)(f);
+        const b = (0, poly_1.zPrimitivePart)(recombined[0]);
+        if (polyEqualsZ(a, b)) {
+            return [a];
+        }
+    }
+    // Recursively factor any composite returned factors
+    const out = [];
+    for (const cand of recombined) {
+        if (degZPoly(cand) <= 1) {
+            out.push((0, poly_1.zPrimitivePart)(cand));
+        }
+        else {
+            const candNorm = (0, poly_1.zPrimitivePart)(cand);
+            if (polyEqualsZ(candNorm, (0, poly_1.zPrimitivePart)(f))) {
+                out.push(candNorm);
+            }
+            else {
+                out.push(...factorSquareFreeBig(candNorm));
+            }
+        }
+    }
+    return out;
+}
+function polyEqualsZ(a, b) {
+    a = (0, poly_1.zTrim)(a);
+    b = (0, poly_1.zTrim)(b);
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+// ============================================================================
+// PUBLIC API (BigInt)
+// ============================================================================
+/**
+ * Factor a univariate integer polynomial over Z.
+ *
+ * @param input Polynomial given as either:
+ *  - a string (parsed using the library parser), or
+ *  - a coefficient array `ZPoly` (lowest degree first).
+ * @param variable Variable name to treat as the univariate indeterminate.
+ *
+ * @returns A normalized factorization:
+ *  - `content`: the integer content extracted from the polynomial
+ *  - `factors`: primitive, normalized factors with multiplicities
+ *
+ * @remarks
+ * This is the preferred API if you need exact arithmetic (no `number` rounding).
+ */
+/**
+ * Factor a univariate polynomial over **ℤ** using exact BigInt arithmetic.
+ *
+ * Pipeline (high level):
+ * 1) Parse + trim
+ * 2) Split into `content` and `primitive` part
+ * 3) Square-free factorization
+ * 4) Factor each square-free component (modular splitting + lifting)
+ * 5) Recombine multiplicities and return a normalized factor list
+ *
+ * Notes:
+ * - Factors are returned **primitive** and **normalized** (unit/sign absorbed into `content`).
+ * - For multivariate inputs, use the multivariate entry points in this module.
+ *
+ * @param input Polynomial string (parser format) or coefficient array.
+ * @param variable The variable name to use when parsing from string.
+ * @returns `{ content, factors }` where `content` is the integer unit/content and `factors` are primitive factors.
+ *
+ * @throws {Error} If parsing fails or the polynomial is malformed.
+ */
+function factorPolynomialBig(input) {
+    let f = (0, poly_1.zTrim)(input);
+    if ((0, poly_1.zIsZero)(f)) {
+        return { content: 0n, factors: [] };
+    }
+    if (degZPoly(f) === 0) {
+        return { content: f[0] ?? 0n, factors: [] };
+    }
+    const { content, primitive } = (0, poly_1.zNormalizePrimitiveSign)(f);
+    f = primitive;
+    const sqf = squareFreeFactorizationBig(f);
+    const sqfParts = sqf.length === 0 ? [[f, 1]] : sqf;
+    const result = { content, factors: [] };
+    for (const [part, mult] of sqfParts) {
+        const irr = factorSquareFreeBig(part);
+        for (const fac of irr) {
+            result.factors.push({
+                coefficients: (0, poly_1.zPrimitivePart)(fac),
+                multiplicity: mult,
+            });
+        }
+    }
+    return result;
+}
+// ============================================================================
+// COMPATIBILITY WRAPPERS (number[] / number output)
+// ============================================================================
+function assertSafeIntArray(arr, who) {
+    if (arr.length === 0) {
+        throw new Error(`${who}: empty coefficient array`);
+    }
+    for (let i = 0; i < arr.length; i++) {
+        const c = arr[i];
+        if (!Number.isFinite(c) || !Number.isInteger(c) || !Number.isSafeInteger(c)) {
+            throw new Error(`${who}: coefficient at index ${i} is not a safe integer: ${c}`);
+        }
+    }
+}
+function toBigFromNumberPoly(f) {
+    return (0, poly_1.zTrim)(f.map(x => BigInt(x)));
+}
+function toNumberFromBigPoly(f) {
+    // only safe if all coefficients fit safe integer
+    const out = [];
+    for (const c of f) {
+        if (c > BigInt(Number.MAX_SAFE_INTEGER) || c < BigInt(Number.MIN_SAFE_INTEGER)) {
+            throw new Error(`toNumberFromBigPoly: coefficient out of safe range: ${c.toString()}`);
+        }
+        out.push(Number(c));
+    }
+    // trim zeros
+    while (out.length > 1 && out[out.length - 1] === 0) {
+        out.pop();
+    }
+    return out;
+}
+/**
+ * Factor a univariate integer polynomial over Z with safe JS-number coefficients.
+ *
+ * @param input Polynomial given as either:
+ *  - a string, or
+ *  - a `number[]` coefficient array (lowest degree first).
+ * @param variable Variable name to treat as the univariate indeterminate.
+ *
+ * @returns A normalized factorization (same shape as `factorPolynomialBig`, but using `number[]` input).
+ *
+ * @throws If coefficients are not safe integers.
+ */
+function factorPolynomial(input) {
+    if (Array.isArray(input)) {
+        assertSafeIntArray(input, 'factorPolynomial');
+    }
+    const big = toBigFromNumberPoly(input);
+    const r = factorPolynomialBig(big);
+    const content = (() => {
+        if (r.content > BigInt(Number.MAX_SAFE_INTEGER) ||
+            r.content < BigInt(Number.MIN_SAFE_INTEGER)) {
+            throw new Error(`factorPolynomial: content out of safe range: ${r.content.toString()}`);
+        }
+        return Number(r.content);
+    })();
+    const factors = r.factors.map(f => ({
+        coefficients: toNumberFromBigPoly(f.coefficients),
+        multiplicity: f.multiplicity,
+    }));
+    return { content, factors };
+}