arch: separate LatexSyntax from Compute Engine Core

Author: arnog

CHANGELOG.md

@@ -7,6 +7,39 @@
   treatment. Non-numeric arguments (e.g., tuples, triples) still trigger
   function-call behavior.
 
+- **LatexSyntax is now an injectable dependency**. The `ComputeEngine`
+  constructor accepts an optional `latexSyntax` option to inject a `LatexSyntax`
+  instance. When importing the full package (`@cortex-js/compute-engine`), a
+  `LatexSyntax` is created automatically — existing code works unchanged. When
+  importing only `@cortex-js/compute-engine/core`, no `LatexSyntax` is bundled;
+  `ce.parse()`, `.latex`, and `.toLatex()` will throw unless a `LatexSyntax` is
+  explicitly provided. MathJSON serialization (`.json`, `.toMathJson()`)
+  gracefully omits the optional `latex` metadata field when no `LatexSyntax` is
+  available.
+
+  ```ts
+  // Full package — works as before, LatexSyntax auto-created:
+  import { ComputeEngine } from '@cortex-js/compute-engine';
+  const ce = new ComputeEngine();
+  ce.parse('x^2');  // works
+
+  // Core-only — explicit injection for LaTeX support:
+  import { ComputeEngine } from '@cortex-js/compute-engine/core';
+  import { LatexSyntax } from '@cortex-js/compute-engine/latex-syntax';
+  const ce = new ComputeEngine({ latexSyntax: new LatexSyntax() });
+  ce.parse('x^2');  // works
+
+  // Core-only — no LaTeX needed:
+  import { ComputeEngine } from '@cortex-js/compute-engine/core';
+  const ce = new ComputeEngine();
+  ce.expr(['Add', 'x', 1]).simplify();  // works
+  ce.parse('x + 1');                     // throws: LatexSyntax not available
+  ```
+
+- **New `ILatexSyntax` interface**: A structural interface for LaTeX
+  parser/serializers, exposed on `IComputeEngine.latexSyntax`. Allows custom
+  implementations without depending on the `LatexSyntax` class.
+
 **Package modularization**: The monolithic `@cortex-js/compute-engine` package
 can now be imported as seven independently usable sub-paths, enabling smaller
 bundles for consumers who only need a subset of functionality.

MIGRATION_GUIDE_0.55.0.md

@@ -12,8 +12,8 @@ work** — with a few breaking API changes listed below.
 | 0.54.x | 0.55.0 |
 | --- | --- |
 | `ce.box(input)` | `ce.expr(input)` |
-| `ce.latexDictionary` | `new LatexSyntax({ dictionary })` |
-| `ce.latexDictionary = [...]` | `new LatexSyntax({ dictionary: [...] })` |
+| `ce.latexDictionary` | `new LatexSyntax({ dictionary })` passed to constructor |
+| `ce.latexDictionary = [...]` | `new ComputeEngine({ latexSyntax: new LatexSyntax({ dictionary: [...] }) })` |
 | `ComputeEngine.getLatexDictionary()` | `import { LATEX_DICTIONARY }` |
 | `isBoxedExpression(x)` | `isExpression(x)` |
 | `isBoxedNumber(x)` | `isNumber(x)` |
@@ -49,10 +49,11 @@ import { expr } from '@cortex-js/compute-engine';
 const e = expr(['Add', 'x', 1]);
 ```
 
-### 2. `ce.latexDictionary` removed
+### 2. `ce.latexDictionary` removed — use `LatexSyntax` constructor injection
 
 The `latexDictionary` getter and setter on `ComputeEngine` are removed. LaTeX
-dictionaries are now managed by the standalone `LatexSyntax` class.
+dictionaries are now managed by the `LatexSyntax` class, which is injected into
+`ComputeEngine` via the `latexSyntax` constructor option.
 
 ```ts
 // Before
@@ -68,8 +69,7 @@ ce.latexDictionary = [
 ];
 
 // After
-import { LatexSyntax, LATEX_DICTIONARY } from '@cortex-js/compute-engine';
-// Or: import { LatexSyntax, LATEX_DICTIONARY } from '@cortex-js/compute-engine/latex-syntax';
+import { ComputeEngine, LatexSyntax, LATEX_DICTIONARY } from '@cortex-js/compute-engine';
 
 const syntax = new LatexSyntax({
   dictionary: [
@@ -84,6 +84,11 @@ const syntax = new LatexSyntax({
   ],
 });
 
+// Inject into the engine so ce.parse(), .latex, .toLatex() use it:
+const ce = new ComputeEngine({ latexSyntax: syntax });
+ce.parse('\\placeholder{x}');
+
+// Or use the LatexSyntax instance directly (no engine needed):
 const mathJson = syntax.parse('\\placeholder{x}');
 ```
 
@@ -127,7 +132,7 @@ import { isExpression, isNumber } from '@cortex-js/compute-engine';
 
 If you were passing custom library definitions with `latexDictionary` entries
 to the `ComputeEngine` constructor, that field is no longer recognized. Define
-your LaTeX entries via a `LatexSyntax` instance instead.
+your LaTeX entries via a `LatexSyntax` instance and inject it.
 
 ```ts
 // Before
@@ -140,21 +145,22 @@ const ce = new ComputeEngine({
 });
 
 // After
-import { LatexSyntax, LATEX_DICTIONARY } from '@cortex-js/compute-engine';
-
-const ce = new ComputeEngine({
-  libraries: [{
-    name: 'mylib',
-    operators: { MyOp: { ... } },
-  }],
-});
+import { ComputeEngine, LatexSyntax, LATEX_DICTIONARY } from '@cortex-js/compute-engine';
 
 const syntax = new LatexSyntax({
   dictionary: [
     ...LATEX_DICTIONARY,
     { latexTrigger: '\\myop', parse: 'MyOp' },
   ],
 });
+
+const ce = new ComputeEngine({
+  latexSyntax: syntax,
+  libraries: [{
+    name: 'mylib',
+    operators: { MyOp: { ... } },
+  }],
+});
 ```
 
 ### 6. Compilation registry methods now `@internal`
@@ -220,6 +226,19 @@ const e = ce.expr(['Add', ['Power', 'x', 2], 1]);
 e.simplify();
 ```
 
+To add LaTeX support to a core-only engine, inject a `LatexSyntax`:
+
+```ts
+import { ComputeEngine } from '@cortex-js/compute-engine/core';
+import { LatexSyntax } from '@cortex-js/compute-engine/latex-syntax';
+
+const ce = new ComputeEngine({ latexSyntax: new LatexSyntax() });
+ce.parse('x^2 + 1'); // works
+```
+
+Without injection, `ce.parse()`, `.latex`, and `.toLatex()` throw an error.
+MathJSON operations (`ce.expr()`, `.json`, `.evaluate()`, etc.) work without it.
+
 ### Compilation targets only
 
 ```ts
@@ -243,10 +262,19 @@ The following convenience methods were **kept** on `ComputeEngine` and
 
 | Method | Still works? | Standalone alternative |
 | --- | --- | --- |
-| `ce.parse(latex)` | Yes | `parse(latex)` from `latex-syntax` + `ce.expr()` |
-| `expr.latex` | Yes | `serialize(expr.json)` from `latex-syntax` |
-| `expr.toLatex()` | Yes | `serialize(expr.json)` from `latex-syntax` |
+| `ce.parse(latex)` | Yes (requires `LatexSyntax`) | `parse(latex)` from `latex-syntax` + `ce.expr()` |
+| `expr.latex` | Yes (requires `LatexSyntax`) | `serialize(expr.json)` from `latex-syntax` |
+| `expr.toLatex()` | Yes (requires `LatexSyntax`) | `serialize(expr.json)` from `latex-syntax` |
 | `ce.box(input)` | Yes (deprecated) | `ce.expr(input)` |
 
-These convenience methods use the standalone `LatexSyntax` internally and
-will continue to work for the foreseeable future.
+These convenience methods delegate to the engine's injected `LatexSyntax`
+instance. When using the full package (`@cortex-js/compute-engine`), a
+`LatexSyntax` is automatically created — existing code works unchanged. When
+using only the core sub-path, pass a `LatexSyntax` via the constructor:
+
+```ts
+const ce = new ComputeEngine({ latexSyntax: new LatexSyntax() });
+```
+
+The `LatexSyntax` instance is accessible via `ce.latexSyntax` (returns
+`undefined` if none is available).

docs/architecture/CURRENT-ARCHITECTURE.md

@@ -79,7 +79,6 @@ This document captures the implemented architecture after the recent modularizat
 | `engine-runtime-state.ts` | Execution limits (time, iteration, recursion) and verification state |
 | `engine-configuration-lifecycle.ts` | Configuration change propagation and reset fan-out |
 | `engine-cache.ts` | Expression and rule-set caching with generation-based invalidation |
-| `engine-latex-dictionary-state.ts` | LaTeX dictionary indexing and rebuild |
 
 ### Scoping & Declarations
 | File | Responsibility |
@@ -101,6 +100,38 @@ This document captures the implemented architecture after the recent modularizat
 | `engine-compilation-targets.ts` | Registry for named compilation targets (JavaScript, GLSL, etc.) |
 | `engine-type-resolver.ts` | Type resolution callback for parser integration |
 
+## LatexSyntax as Injectable Dependency
+
+`LatexSyntax` is an optional dependency of `ComputeEngine`. The engine does not
+statically import the `LatexSyntax` class — it only uses the structural
+`ILatexSyntax` interface from `types-engine.ts`.
+
+**Injection mechanism:**
+
+1. **Explicit constructor option**: `new ComputeEngine({ latexSyntax: new LatexSyntax() })`.
+2. **Static factory** (`ComputeEngine._latexSyntaxFactory`): Registered by the
+   full entry point (`compute-engine.ts`). Enables lazy creation so `new ComputeEngine()` still works with LaTeX when imported from the full package.
+3. **No LatexSyntax**: When imported from the core sub-path without injection,
+   `ce.parse()`, `.latex`, and `.toLatex()` throw a clear error. MathJSON
+   serialization gracefully omits the optional `latex` metadata field.
+
+**Key types:**
+
+- `ILatexSyntax` (in `types-engine.ts`) — structural interface with `parse()` and `serialize()` methods.
+- `IComputeEngine.latexSyntax` — getter returning the instance (lazily created via factory if available) or `undefined`.
+- `IComputeEngine._requireLatexSyntax()` — returns the instance or throws.
+
+**Files involved:**
+
+| File | Role |
+|------|------|
+| `types-engine.ts` | Defines `ILatexSyntax` interface, declares `latexSyntax` / `_requireLatexSyntax()` on `IComputeEngine` |
+| `index.ts` | Stores instance, exposes getter/helper, accepts constructor option, holds static factory |
+| `compute-engine.ts` | Registers the factory: `ComputeEngine._latexSyntaxFactory = () => new LatexSyntax()` |
+| `abstract-boxed-expression.ts` | `.latex` / `.toLatex()` route through `engine._requireLatexSyntax()` |
+| `serialize.ts` | Latex metadata conditional on `ce.latexSyntax` availability |
+| `rules.ts` | Rule parsing constructs LatexSyntax via `ce._requireLatexSyntax().constructor` |
+
 ## Free Functions & Lazy Global Engine
 
 Top-level free functions (`parse`, `simplify`, `evaluate`, `N`, `assign`) are exported from `index.ts` via `free-functions.ts`. They are backed by a lazily-instantiated global `ComputeEngine` accessible via `getDefaultEngine()`.
@@ -112,7 +143,10 @@ Top-level free functions (`parse`, `simplify`, `evaluate`, `N`, `assign`) are ex
 - `assign(id, value)` / `assign({...})` — assign values in the global engine
 - `getDefaultEngine()` — access the shared engine instance for configuration
 
-The global engine is created on first call to any free function, using a dynamic `require('./index')` inside `getDefaultEngine()` to avoid circular dependency (since `index.ts` re-exports `free-functions.ts`).
+The global engine is created on first call to any free function via a factory
+registered by the entry point. The full entry point (`compute-engine.ts`)
+registers a factory that includes `LatexSyntax`; the core entry point
+(`index.ts`) registers a factory without it.
 
 ## Extension Contracts (Runtime Guards)
 
@@ -130,7 +164,7 @@ Custom libraries (`new ComputeEngine({ libraries: [...] })`):
 - `requires` must be an array of library names
 - duplicate dependencies in `requires` are rejected
 - `definitions` must be object or array of objects
-- `latexDictionary` must be an array
+- `latexDictionary` must be an array (if present; removed from standard libraries)
 
 Compile option payloads (`compile(expr, options)`):
 - validates `to`, `target`, `operators`, `functions`, `vars`, `imports`, `preamble`, `fallback`

docs/plans/2026-02-27-big-decimal-design.md

@@ -41,6 +41,9 @@ BigDecimal.precision = 50; // set by engine's setPrecision()
 - **Guard digits**: transcendental implementations use `precision + 10`
   internally, round result to `precision`.
 
+See `docs/NUMERIC-SERIALIZATION.md` for how precision affects the three output
+paths (`.json`, `.latex`, `.toString()`).
+
 ## API Surface
 
 ### Construction

docs/plans/2026-02-27-modularization-design.md

@@ -146,19 +146,28 @@ e.json;         // → MathJsonExpression
 e.toString();   // → ASCII math
 ```
 
+**`LatexSyntax` is an injectable dependency** (implemented):
+
+`ComputeEngine` accepts an optional `latexSyntax` constructor option. When
+importing the full package, a `LatexSyntax` is auto-created via a static
+factory. When importing only from `/core`, no `LatexSyntax` is bundled.
+
+- `ce.parse()` — available when `LatexSyntax` is injected, throws otherwise
+- `ce.latexSyntax` — getter returning the `ILatexSyntax` instance or `undefined`
+- `ce._requireLatexSyntax()` — returns instance or throws with clear message
+
 **Removed from `ComputeEngine`**:
 
-- `ce.parse()` — use `parse()` from latex-syntax + `ce.expr()`
 - `ce.latexDictionary` (get/set) — owned by `LatexSyntax`
 - `ce.decimalSeparator` — moves to `LatexSyntax` options
 - `static getLatexDictionary()` — moves to latex-syntax exports
 - `registerCompilationTarget()`, `getCompilationTarget()`,
   `listCompilationTargets()`, `unregisterCompilationTarget()` — registry removed
 - `_compile()` — replaced by free `compile()` in compile module
 
-**Removed from `BoxedExpression`**:
+**Still on `BoxedExpression`** (require injected LatexSyntax):
 
-- `.toLatex()` / `.latex` — use `serialize(expr.json)` from latex-syntax
+- `.toLatex()` / `.latex` — available when `LatexSyntax` is injected; alternatively use `serialize(expr.json)` from latex-syntax directly
 - `.compile()` — use `compile(expr)` from compile module
 
 **Renamed**:
@@ -243,10 +252,10 @@ simplify(expr(parse('x^2 + 2x + 1')));
 
 ## Breaking Changes Summary
 
-| Removed | Replacement |
+| Changed | Replacement |
 | --- | --- |
-| `ce.parse(latex)` | `ce.expr(parse(latex))` |
-| `expr.toLatex()` / `expr.latex` | `serialize(expr.json)` |
+| `ce.parse(latex)` | Still available when `LatexSyntax` is injected; or `ce.expr(parse(latex))` |
+| `expr.toLatex()` / `expr.latex` | Still available when `LatexSyntax` is injected; or `serialize(expr.json)` |
 | `expr.compile(options)` | `compile(expr, options)` |
 | `ce.box(input)` | `ce.expr(input)` |
 | `ce.latexDictionary` | `new LatexSyntax({ dictionary })` |

docs/plans/2026-02-28-biggamma-precision-design.md

@@ -0,0 +1,99 @@
+# Precision-Scaling bigGamma / bigGammaln
+
+**Date:** 2026-02-28
+**Status:** Approved
+
+## Problem
+
+`bigGamma` and `bigGammaln` in `src/compute-engine/numerics/special-functions.ts`
+use fixed Lanczos/Spouge coefficient tables with ~16 digits of precision. At
+BigDecimal.precision > 16, the results are dominated by coefficient error:
+
+- Gamma(1) at prec=100: `1.00000000000000000000298...` (should be exactly 1)
+- Gamma(5) at prec=100: `24.0000000000000000000564...` (should be exactly 24)
+- Gamma(1/2) at prec=100: 16 matching digits vs sqrt(pi)
+
+Meanwhile, all BigDecimal elementary functions (exp, ln, sin, cos, sqrt, atan)
+match decimal.js at 499-500 of 500 digits. Gamma is the outlier.
+
+## Approach: Stirling Series + Runtime Bernoulli Numbers
+
+Replace the fixed-coefficient Lanczos approximation with the Stirling asymptotic
+series for ln(Γ(z)), using Bernoulli numbers computed at runtime to the needed
+precision. This is the same pattern already used by `bigDigamma`.
+
+### Algorithm for bigGammaln(ce, z)
+
+1. **Exact fast paths** (no approximation error):
+   - Positive integer z: return `ln((z-1)!)` from exact bigint factorial
+   - Half-integer z = n + 1/2: return `ln((2n)! √π / (4^n n!))` — exact up to √π
+
+2. **Reflection** (existing, unchanged):
+   For z < 0.5, use `Γ(z) = π / (sin(πz) · Γ(1-z))`
+
+3. **Stirling series** for general z ≥ 0.5:
+   - Shift z upward by m steps using recurrence:
+     `lnΓ(z) = lnΓ(z+m) - ln(z·(z+1)·...·(z+m-1))`
+   - Shift target: `z+m > p·ln(10)/(2π) ≈ 0.37·p` where p = BigDecimal.precision
+   - Compute via Stirling:
+     `lnΓ(w) = (w-½)ln(w) - w + ½ln(2π) + Σ_{k=1}^{N} B_{2k} / (2k(2k-1)·w^{2k-1})`
+   - N ≈ π·w terms (stop when term < 10^{-(p+guard)})
+
+### Algorithm for bigGamma(ce, z)
+
+Thin wrapper:
+- Positive integer z ≥ 1: return exact `(z-1)!` as BigDecimal
+- Otherwise: `exp(bigGammaln(ce, z))`
+
+### Bernoulli Number Computation
+
+Compute B₂, B₄, ..., B_{2N} as exact rationals `[bigint, bigint]` using the
+even-only recurrence:
+
+```
+B_{2m} = (2m-1)/(2(2m+1)) - 1/(2m+1) · Σ_{j=1}^{m-1} C(2m+1, 2j) · B_{2j}
+```
+
+This is O(N²) bigint operations with no precision loss. The rational table is
+converted to BigDecimal at working precision + guard digits when evaluating the
+Stirling series.
+
+**Scaling:** For p=100, N ≈ 115 Bernoulli numbers. For p=500, N ≈ 575. The
+bigint recurrence runs in under 100ms even for p=500.
+
+### Caching
+
+- `'bernoulli-even-rationals'` in `ce._cache`: the `[bigint, bigint][]` table.
+  Grows monotonically (exact rationals never need recomputation). Extended if a
+  higher-precision call needs more terms.
+- Remove `'lanczos-7-c'`, `'gamma-p-ln'`, `'gamma-g-ln'` cache entries (dead).
+
+## Files Changed
+
+1. **`src/compute-engine/numerics/special-functions.ts`**
+   - Replace `bigGamma` and `bigGammaln` implementations
+   - Add `computeBernoulliEven(n)` → `[bigint, bigint][]` utility
+   - Remove `LANCZOS_7_C` and `GAMMA_P_LN` coefficient arrays
+
+2. **No other files change.** Function signatures are identical, so all callers
+   (`bigBeta`, `bigZeta`, Gamma library entry in `arithmetic.ts`) work unchanged.
+
+## Testing
+
+The existing `test/big-decimal/precision-comparison.test.ts` Gamma section is
+the regression test. After the fix, expected results:
+
+| Input        | Before (digits) | After (digits, prec=50) | After (digits, prec=100) |
+|--------------|-----------------|------------------------|-------------------------|
+| Gamma(1)     | 0               | 50 (exact)             | 100 (exact)             |
+| Gamma(2)     | 0               | 50 (exact)             | 100 (exact)             |
+| Gamma(5)     | 1               | 50 (exact)             | 100 (exact)             |
+| Gamma(10)    | 4               | 50 (exact)             | 100 (exact)             |
+| Gamma(1/2)   | 16              | ~45                    | ~95                     |
+| Gamma(3/2)   | 16              | ~45                    | ~95                     |
+
+## Future Work
+
+- Upgrade `bigDigamma`/`bigTrigamma`/`bigPolygamma` to use the same runtime
+  Bernoulli table (they currently use the 15-entry `BERNOULLI_2K_STRINGS` array,
+  limiting them to ~50 digits). Natural follow-up, not part of this change.