@fitchmultz/pi-calculator 4.1.6 → 4.1.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 4.1.7 - 2026-11-01
+
+<!-- npm-release:unreleased:start -->
+<!-- npm-release:unreleased:end -->
+
+- Adopt the strict quality policy baseline and current Pi practice (#48) ([50e0e33](https://github.com/fitchmultz/pi-calculator/commit/50e0e33a0443a2d0ec1c12a5cf4080342ba61850))
+
+### What's Changed
+
+- Adopt the strict quality policy baseline and current Pi practice by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/48
+
+**Full Changelog**: https://github.com/fitchmultz/pi-calculator/compare/v4.1.6...v4.1.7
+
 ## 4.1.6 - 2026-11-01
 
 <!-- npm-release:unreleased:start -->
@@ -8,8 +21,8 @@
 - Use direct Flash for automatic release remediation (#49) ([544c540](https://github.com/fitchmultz/pi-calculator/commit/544c540e8d12cbe0ec8c6cde7050628f41700a4e))
 
 ### What's Changed
-* Use direct Flash for necessary release remediation by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/49
 
+- Use direct Flash for necessary release remediation by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/49
 
 **Full Changelog**: https://github.com/fitchmultz/pi-calculator/compare/v4.1.5...v4.1.6
 
@@ -22,8 +35,8 @@
 - Pin reviewed release source binding (#46) ([2a75d8b](https://github.com/fitchmultz/pi-calculator/commit/2a75d8beebdf247c7703d35b8a5944ab7b9cf7cb))
 
 ### What's Changed
-* Bind automatic releases to the reviewed version by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/46
 
+- Bind automatic releases to the reviewed version by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/46
 
 **Full Changelog**: https://github.com/fitchmultz/pi-calculator/compare/v4.1.4...v4.1.5
 
@@ -35,8 +48,8 @@
 - Enable reviewed npm version remediation (#44) ([20c90cf](https://github.com/fitchmultz/pi-calculator/commit/20c90cfb5e28452cfa3f7bf2d7923659b6b18a86))
 
 ### What's Changed
-* Enable reviewed npm version remediation by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/44
 
+- Enable reviewed npm version remediation by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/44
 
 **Full Changelog**: https://github.com/fitchmultz/pi-calculator/compare/v4.1.3...v4.1.4
 
@@ -48,8 +61,8 @@
 - Enable reviewed automatic npm releases (#42) ([f7ce653](https://github.com/fitchmultz/pi-calculator/commit/f7ce6539ac13a509750e4960c4ef5182c5530b40))
 
 ### What's Changed
-* Enable reviewed automatic npm releases by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/42
 
+- Enable reviewed automatic npm releases by @fitchmultz in https://github.com/fitchmultz/pi-calculator/pull/42
 
 **Full Changelog**: https://github.com/fitchmultz/pi-calculator/compare/v4.1.2...v4.1.3
 

package/README.md

@@ -2,7 +2,7 @@
 
 pi-calculator adds a calculator tool to [Pi](https://github.com/earendil-works/pi), with 40 significant digits of decimal precision. Use it to check totals or evaluate scientific expressions.
 
-![Pi sends an expression to the calculator, which returns a decimal result or rejects an invalid expression.](.github/readme/calculator-flow.png)
+![Pi sends an expression to the calculator, which returns a decimal result or rejects an invalid expression.](https://raw.githubusercontent.com/fitchmultz/pi-calculator/main/.github/readme/calculator-flow.png)
 
 ## Install and try it
 
@@ -56,7 +56,7 @@ Keep expressions within 4,096 characters. See [limits](docs/reference.md#limits)
 
 See [result format](docs/reference.md#result-format) to use the calculator tool from another extension.
 
-Read the [migration notes](https://github.com/fitchmultz/pi-calculator/blob/main/docs/reference.md#migration) before upgrading.
+Read the [migration notes](https://github.com/fitchmultz/pi-calculator/blob/main/docs/reference.md#upgrading-from-v2) before upgrading.
 
 ## Verification
 

package/decimal.ts

@@ -14,61 +14,127 @@ export function resetDecimal(): void {
 	Decimal.set(DECIMAL_CONFIG);
 }
 
+const GUARD_DECIMAL_CONFIG = {
+	defaults: true,
+	precision: DECIMAL_PRECISION + 10,
+	rounding: DecimalBase.ROUND_HALF_UP,
+} as const;
+
+/** Wider working clone; its extra digits keep intermediate results exact. */
+export const GuardDecimal = DecimalBase.clone(GUARD_DECIMAL_CONFIG);
+
+/** Restore the guard clone's configuration once an expression run finishes. */
+export function resetGuardDecimal(): void {
+	GuardDecimal.set(GUARD_DECIMAL_CONFIG);
+}
+
 const DECIMAL_LITERAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
 
 function decimalFromString(value: string): DecimalValue {
-	if (!DECIMAL_LITERAL.test(value)) throw new Error("invalid decimal literal");
+	if (!DECIMAL_LITERAL.test(value)) {
+		throw new Error("invalid decimal literal");
+	}
 	const decimal = new Decimal(value);
-	if (!decimal.isFinite()) throw new Error("decimal literal overflow");
+	if (!decimal.isFinite()) {
+		throw new Error("decimal literal overflow");
+	}
 	if (decimal.isZero() && /[1-9]/.test(value.replace(/[eE].*$/, ""))) {
 		throw new Error("decimal literal underflow");
 	}
 	const rounded = decimal.toSignificantDigits(DECIMAL_PRECISION);
-	if (!rounded.isFinite()) throw new Error("decimal literal overflow");
-	if (rounded.isZero() && !decimal.isZero()) throw new Error("decimal literal underflow");
+	if (!rounded.isFinite()) {
+		throw new Error("decimal literal overflow");
+	}
+	if (rounded.isZero() && !decimal.isZero()) {
+		throw new Error("decimal literal underflow");
+	}
 	return rounded;
 }
 
 export function toDec(value: unknown): DecimalValue {
-	if (value instanceof Decimal) return value;
-	if (typeof value === "string") return decimalFromString(value);
+	if (value instanceof Decimal) {
+		return value;
+	}
+	if (typeof value === "string") {
+		return decimalFromString(value);
+	}
 	if (typeof value === "number") {
-		if (!Number.isFinite(value)) throw new Error("non-finite number");
+		if (!Number.isFinite(value)) {
+			throw new Error("non-finite number");
+		}
 		return new Decimal(String(value));
 	}
 	throw new Error(`expected number, got ${typeof value}`);
 }
 
+/** Span of the quoted literal starting at `start`, or 0 when there is none. */
+function quotedSpan(expression: string, start: number, quote: string): number {
+	const end = expression.indexOf(quote, start + 1);
+	if (end < 0) {
+		throw new Error("unclosed string in expression");
+	}
+	return end + 1 - start;
+}
+
+/** Decimal literal text at `start`, or undefined when those digits belong to a name. */
+function decimalLiteral(expression: string, start: number): string | undefined {
+	const previous = expression[start - 1];
+	if (previous !== undefined && /[\w.]/.test(previous)) {
+		return undefined;
+	}
+	return expression.slice(start).match(/^(?:\d+\.\d+|\d+\.|\.\d+|\d+)(?:[eE][+-]?\d+)?/)?.[0];
+}
+
+/** Reject syntax the calculator refuses rather than normalizes. */
+function rejectUnsupported(expression: string, start: number, ch: string): void {
+	if (ch === ";") {
+		throw new Error("multiple expressions are not supported");
+	}
+	if (ch === "/" && expression[start + 1] === "*") {
+		throw new Error("comments are not supported");
+	}
+}
+
+/** Nesting depth after one bracket, rejecting the limit as it is crossed. */
+function trackDepth(depth: number, ch: string): number {
+	if (ch === "(" || ch === "[") {
+		if (depth + 1 > MAX_EXPRESSION_DEPTH) {
+			throw new Error(`expression is too deeply nested (max ${MAX_EXPRESSION_DEPTH})`);
+		}
+		return depth + 1;
+	}
+	if ((ch === ")" || ch === "]") && depth > 0) {
+		return depth - 1;
+	}
+	return depth;
+}
+
 /** Preserve numeric literal precision and normalize ** outside quoted strings. */
 export function decimalizeExpression(expression: string): string {
-	if (expression.includes("\\")) throw new Error("escape sequences are not supported");
+	if (expression.includes("\\")) {
+		throw new Error("escape sequences are not supported");
+	}
 
 	let result = "";
 	let i = 0;
 	let nestingDepth = 0;
 
 	while (i < expression.length) {
-		const ch = expression[i]!;
+		const ch = expression[i];
+		if (ch === undefined) {
+			break; // the loop bound keeps the index inside the string
+		}
 
 		if (ch === '"' || ch === "'") {
-			const end = expression.indexOf(ch, i + 1);
-			if (end < 0) throw new Error("unclosed string in expression");
-			result += expression.slice(i, end + 1);
-			i = end + 1;
+			const span = quotedSpan(expression, i, ch);
+			result += expression.slice(i, i + span);
+			i += span;
 			continue;
 		}
 
-		if (ch === "/" && expression[i + 1] === "*") throw new Error("comments are not supported");
-		if (ch === ";") throw new Error("multiple expressions are not supported");
+		rejectUnsupported(expression, i, ch);
 
-		if (ch === "(" || ch === "[") {
-			nestingDepth++;
-			if (nestingDepth > MAX_EXPRESSION_DEPTH) {
-				throw new Error(`expression is too deeply nested (max ${MAX_EXPRESSION_DEPTH})`);
-			}
-		} else if ((ch === ")" || ch === "]") && nestingDepth > 0) {
-			nestingDepth--;
-		}
+		nestingDepth = trackDepth(nestingDepth, ch);
 
 		if (ch === "*" && expression[i + 1] === "*") {
 			result += "^";
@@ -76,10 +142,10 @@ export function decimalizeExpression(expression: string): string {
 			continue;
 		}
 
-		const match = expression.slice(i).match(/^(?:\d+\.\d+|\d+\.|\.\d+|\d+)(?:[eE][+-]?\d+)?/);
-		if (match && (i === 0 || !/[\w.]/.test(expression[i - 1]!))) {
-			result += `d("${match[0]}")`;
-			i += match[0].length;
+		const literal = decimalLiteral(expression, i);
+		if (literal !== undefined) {
+			result += `d("${literal}")`;
+			i += literal.length;
 			continue;
 		}
 

package/docs/development.md

@@ -0,0 +1,32 @@
+# Development
+
+[Back to the README](../README.md)
+
+## Local verification
+
+Requires Node.js 24 or later. From a checkout:
+
+```sh
+npm ci --ignore-scripts
+npm run verify
+```
+
+`verify` runs the quality gates first — both lint passes, the format check, both compiler projects, the baseline drift check and the policy verifier — then the committed harness, the numerical and work-limit checks, and an actual Pi extension-load check. It covers schema and structured result contracts, native nested validation/policy/evaluation errors and native tool-card rendering.
+
+The individual gates run on their own: `npm run lint` (the semantic pass, then compiler diagnostics over the files a compiler project owns), `npm run lint:agent`, `npm run lint:fix`, `npm run format`, `npm run format:check`, `npm test`, `npm run lint:baseline`, and `npm run policy`. The configuration, the baseline it is checked against, and the harness probes are described in [AGENTS.md](../AGENTS.md).
+
+The type-aware lint pass and `tsc` need a host with native builds for `oxlint-tsgolint` and TypeScript. On a host without them (Android on ARM64, for example) the compiler-dependent probes report an explicit skip, so the acceptance gate has to be run on a qualified host or in CI.
+
+The locked development cohort uses Pi 1.4.0 and TypeBox 1.3.27. Pi supplies the schema and terminal UI libraries; `decimal.js` and `expr-eval-fork` are runtime dependencies. No evaluator or grammar compatibility layer is needed.
+
+Update the development TypeBox pin alongside the qualified Pi host, using the version that host ships. Independent TypeBox updates are disabled in Renovate because they install duplicate host schema libraries and slow development startup. Each compatibility lane selects its host's TypeBox version.
+
+## Compatibility qualification
+
+The locked development cohort is reproducible local tooling. Release qualification selects the latest stable official Pi and the [fitchmultz/pi fork](https://github.com/fitchmultz/pi) main once per run, freezing the official version and fork commit throughout the checks.
+
+Each host is qualified separately; a matching version string alone does not establish compatibility. CI runs the full verification against both frozen hosts, including fresh Git and packed npm consumers. See the [compatibility workflow](../.github/workflows/pi-compatibility.yml).
+
+## Release process
+
+When `NPM_RELEASE_ENABLED` is `true`, each main merge enters the automatic version queue. Its version PR must pass current-head compatibility and reviews before the main-only pipeline publishes matching npm and GitHub releases. The release caller reuses the same frozen host inputs for qualification and publishing. See the [version workflow](../.github/workflows/npm-version.yml), [release workflow](../.github/workflows/npm-release.yml), and [changelog](../CHANGELOG.md).

package/docs/reference.md

@@ -0,0 +1,83 @@
+# Calculator reference
+
+[Back to the README](../README.md)
+
+## Installation options
+
+Requires Node.js 24 or later and Pi 1.0.0 or later. The published npm package is `@fitchmultz/pi-calculator`.
+
+```sh
+pi install npm:@fitchmultz/pi-calculator
+```
+
+Git installation is also supported:
+
+```sh
+pi install git:github.com/fitchmultz/pi-calculator
+```
+
+When switching from Git to npm, run `pi list`, remove the exact Git source it shows with `pi remove <source>`, then install the scoped npm package. This avoids loading the calculator twice. Existing Git installs can stay on Git.
+
+Start a new Pi session with `pi` after installation. The package adds one `calculator` tool with one required `expression` string. Pi supplies the schema and terminal UI libraries; evaluation uses `decimal.js` and `expr-eval-fork`.
+
+Pi extensions execute with full system access. Review the source before installing.
+
+## Expressions
+
+Operators are `+`, `-`, `*`, `/`, `%`, `^` and `**`; constants are `PI` and `E`. Arrays support zero-based indexing: `[1,2,3][2]` returns `3`. Combine independent results in one flat array:
+
+```text
+[0.1 + 0.2, 2^64]
+[stdev([2,4,4,4,5,5,7,9]), stdevs([2,4,4,4,5,5,7,9])]
+```
+
+### Functions
+
+- **Trigonometry:** `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `sinh`, `cosh`, `tanh`, `asinh`, `acosh` and `atanh`. Trig uses radians. `radians(degrees)` and `degrees(radians)` convert angles.
+- **Roots, powers and logarithms:** `sqrt`, `cbrt`, `abs`, `pow`, `exp`, `expm1`, `ln`/`log`, `log1p`, `log2`, `log10`/`lg`. Both `ln` and `log` are natural logarithms. For small inputs, use `expm1(x)` for `exp(x)-1` and `log1p(x)` for `ln(1+x)` to preserve precision.
+- **Rounding:** `ceil`, `floor`, `round`, `roundTo`, `trunc` and `sign`. `roundTo(value, places)` rounds halves away from zero; negative places round to tens, hundreds and so on.
+- **Percentages:** `percent(rate, amount)` gives `rate%` of `amount`: `percent(15, 200)` returns `30`.
+- **Statistics:** `sum`, `mean`, `median`, `stdev` and `stdevs` take numeric arrays. `stdev` is population standard deviation; `stdevs` is sample standard deviation and requires at least two elements.
+- **Extremes and distance:** `min`, `max`, `hypot`/`pyt` take either an array or individual arguments.
+- **Factorials:** `n!` and `fac(n)` compute factorials for integers from 0 through 1000.
+
+Aggregates require finite numeric elements. Sums preserve cancellation remainders before rounding; means and even medians round after division.
+
+Input literals and arithmetic are rounded to 40 significant digits using half-up rounding. Results are rounded decimal strings. For example, `exp(ln(1000))` can differ slightly from `1000` because intermediate calculations round.
+
+## Result format
+
+The tool returns a finite scalar or a flat array of finite scalars, represented as decimal strings. A nested array, nonnumeric result or nonfinite member fails the whole expression. Large finite values use scientific notation.
+
+Model-facing content contains only the value, such as `0.3`, or a JSON array of strings, such as `["0.3","18446744073709551616"]`.
+
+Both `details` and native `structuredContent` contain the same object:
+
+```json
+{
+  "expression": "[0.1 + 0.2, 2^64]",
+  "value": ["0.3", "18446744073709551616"]
+}
+```
+
+`expression` is trimmed. `value` is a string or string array. The tool declares an `outputSchema`, so nested and codemode callers can receive these values without reparsing display text.
+
+Evaluation failures throw and become native error results. Schema and policy checks remain Pi-owned. The tool requests native strict JSON-schema sampling where the provider supports it and uses Pi's normal fallback elsewhere. Pi's tool card displays the safely escaped expression above the result.
+
+## Limits
+
+- Expressions: at most 4,096 characters and 128 nesting levels.
+- Output: serialized expression/value details must fit within 50 KiB. Oversized results are rejected rather than truncated.
+- Factorials: operands from 0 through 1000, with a shared 1,000-step factorial budget per expression. Each factorial costs at least one step.
+- Circular trig: `sin`, `cos` and `tan` reject absolute inputs above `1e100`.
+- Hyperbolic functions: reject absolute inputs above 10,000.
+- Modulo: `%` rejects operand exponent gaps above 10,000.
+- Expensive operations: share a 10,000-unit work budget. Circular trig and `atan2` calls cost 100 units each, allowing at most 100 per expression when no other operation uses that budget.
+
+<a id="migration"></a>
+
+## Upgrading from v2
+
+Version 3 removed the old angle-conversion names: replace `deg(x)` with `radians(x)` and `rad(x)` with `degrees(x)`. There are no compatibility aliases.
+
+Tool content no longer includes `expression =`. Consumers should read the expression from details and handle both string and string-array values.

package/eval.ts

@@ -1,5 +1,15 @@
 import { Parser } from "expr-eval-fork";
-import { DECIMAL_PRECISION, Decimal, decimalizeExpression, resetDecimal, toDec, type DecimalValue } from "./decimal.ts";
+import {
+	DECIMAL_PRECISION,
+	Decimal,
+	decimalizeExpression,
+	GuardDecimal,
+	resetDecimal,
+	resetGuardDecimal,
+	toDec,
+	type DecimalValue,
+} from "./decimal.ts";
+import { exactSum, mean, standardDeviation } from "./statistics.ts";
 
 export const MAX_EXPRESSION_LENGTH = 4096;
 const MAX_FACTORIAL_OPERAND = 1000;
@@ -14,16 +24,10 @@ const E = new Decimal("2.718281828459045235360287471352662497757");
 const MAX_TRIG_ABS = new Decimal("1e100");
 const SMALL_ATAN_ABS = new Decimal("1e-100");
 const LARGE_ATAN_ABS = new Decimal("1e100");
-const GUARD_DECIMAL_CONFIG = {
-	defaults: true,
-	precision: DECIMAL_PRECISION + 10,
-	rounding: Decimal.ROUND_HALF_UP,
-} as const;
-const GuardDecimal = Decimal.clone(GUARD_DECIMAL_CONFIG);
 
 let factorialWorkLeft = 0;
 let expensiveWorkLeft = 0;
-const EMPTY_VARIABLES: Record<string, never> = Object.create(null);
+const EMPTY_VARIABLES: Record<string, never> = nullMap({});
 
 const parser = new Parser({
 	allowMemberAccess: false,
@@ -38,11 +42,22 @@ const parser = new Parser({
 	},
 });
 
-function nullMap<T extends object>(values: T): T {
-	return Object.assign(Object.create(null), values);
+function nullMap<T extends object>(values: Readonly<T>): T {
+	const target = { ...values };
+	Object.setPrototypeOf(target, null);
+	return target;
 }
 
-function requireArity(name: string, args: unknown[], count: number): void {
+/** Read an argument position the arity check has already guaranteed. */
+function argumentAt<T>(values: readonly T[], index: number): T {
+	const value = values[index];
+	if (value === undefined) {
+		throw new Error(`missing argument at index ${index}`);
+	}
+	return value;
+}
+
+function requireArity(name: string, args: readonly unknown[], count: number): void {
 	if (args.length !== count) {
 		throw new Error(`${name}() needs exactly ${count} argument${count === 1 ? "" : "s"}`);
 	}
@@ -50,16 +65,24 @@ function requireArity(name: string, args: unknown[], count: number): void {
 
 function factorial(value: unknown) {
 	const n = toDec(value);
-	if (!n.isInteger() || n.lt(0)) throw new Error("factorial needs a non-negative integer");
-	if (n.gt(MAX_FACTORIAL_OPERAND)) throw new Error(`factorial operand too large (max ${MAX_FACTORIAL_OPERAND})`);
+	if (!n.isInteger() || n.lt(0)) {
+		throw new Error("factorial needs a non-negative integer");
+	}
+	if (n.gt(MAX_FACTORIAL_OPERAND)) {
+		throw new Error(`factorial operand too large (max ${MAX_FACTORIAL_OPERAND})`);
+	}
 
 	const count = n.toNumber();
 	const cost = Math.max(count, 1);
-	if (cost > factorialWorkLeft) throw new Error("factorial work budget exceeded");
+	if (cost > factorialWorkLeft) {
+		throw new Error("factorial work budget exceeded");
+	}
 	factorialWorkLeft -= cost;
 
 	let result = 1n;
-	for (let i = 2; i <= count; i++) result *= BigInt(i);
+	for (let i = 2; i <= count; i++) {
+		result *= BigInt(i);
+	}
 	return new Decimal(result.toString()).toSignificantDigits(DECIMAL_PRECISION);
 }
 
@@ -71,7 +94,9 @@ function decimals(values: unknown, name: string, minLength = 1): DecimalValue[]
 	return values.map((value, index) => {
 		try {
 			const number = toDec(value);
-			if (!number.isFinite()) throw new Error("expected a finite number");
+			if (!number.isFinite()) {
+				throw new Error("expected a finite number");
+			}
 			return number;
 		} catch {
 			throw new Error(`${name}(): invalid number at index ${index}`);
@@ -79,78 +104,12 @@ function decimals(values: unknown, name: string, minLength = 1): DecimalValue[]
 	});
 }
 
-function decimalArguments(args: unknown[], name: string): DecimalValue[] {
+function decimalArguments(args: readonly unknown[], name: string): DecimalValue[] {
 	const values = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
-	if (values.length === 0) throw new Error(`${name}() needs at least one number`);
-	return decimals(values, name);
-}
-
-function sum(xs: DecimalValue[], Ctor = Decimal, divisor = 1): DecimalValue {
-	if (xs.some((x) => !x.isFinite())) return Ctor.sum(...xs).div(divisor);
-
-	// Decimal.sum also truncates across large exponent gaps. Signed BigInt chunks
-	// keep the exact sum sparse, including intermediate values outside Decimal's range.
-	const width = BigInt(Ctor.precision);
-	const base = 10n ** width;
-	const bins = new Map<bigint, bigint>();
-	const add = (key: bigint, value: bigint) => bins.set(key, (bins.get(key) ?? 0n) + value);
-	for (const x of xs) {
-		if (x.isZero()) continue;
-		const digits = x.toExponential().split("e")[0]!.replace(".", "");
-		const exponent = BigInt(x.e) - BigInt(x.sd() - 1);
-		const key = exponent >= 0n ? exponent / width : (exponent - width + 1n) / width;
-		add(key, BigInt(digits) * 10n ** (exponent - key * width));
-	}
-	for (let key of [...bins.keys()].sort((a, b) => Number(a - b))) {
-		for (;;) {
-			const value = bins.get(key)!;
-			const carry = value / base;
-			bins.set(key, value % base);
-			if (!carry) break;
-			add(++key, carry);
-		}
+	if (values.length === 0) {
+		throw new Error(`${name}() needs at least one number`);
 	}
-
-	const keys = [...bins.keys()].filter((key) => bins.get(key) !== 0n).sort((a, b) => Number(b - a));
-	if (keys.length === 0) return new Ctor(0);
-	let key = keys[0]!;
-	let coefficient = bins.get(key)!;
-	let i = 1;
-	const digitCount = (n: bigint) => n.toString().replace("-", "").length;
-	const retained = Ctor.precision + Math.ceil(Math.log10(divisor)) + 2;
-	for (; i < keys.length; i++) {
-		const next = keys[i]!;
-		if (digitCount(coefficient) >= retained || key - next > 2n) break;
-		coefficient = coefficient * base ** (key - next) + bins.get(next)!;
-		key = next;
-	}
-
-	// Normalized chunks have magnitude < base, so the leading remaining chunk
-	// determines the tail's sign. A sticky digit preserves which side of a tie it lies on.
-	let shift = 0n;
-	if (i < keys.length) {
-		shift = BigInt(Math.max(2, retained - digitCount(coefficient)));
-		coefficient = coefficient * 10n ** shift + (bins.get(keys[i]!)! > 0n ? 1n : -1n);
-	}
-	// Divide and round before restoring the exponent to avoid intermediate overflow/underflow.
-	const [mantissa, exponent] = new Ctor(coefficient.toString()).div(divisor).toExponential().split("e");
-	return new Ctor(`${mantissa}e${BigInt(exponent!) + key * width - shift}`);
-}
-
-function mean(xs: DecimalValue[]): DecimalValue {
-	return sum(xs, Decimal, xs.length);
-}
-
-function standardDeviation(xs: DecimalValue[], sample: boolean): DecimalValue {
-	// Scale before subtraction; a power of ten preserves small spreads around a large offset.
-	const scale = new GuardDecimal(`1e${GuardDecimal.max(...xs.map((x) => x.abs())).e}`);
-	const scaled = xs.map((x) => new GuardDecimal(x).div(scale));
-	// Center on an input first so a large common offset cannot round away the spread.
-	const shifted = scaled.map((x) => x.minus(scaled[0]!));
-	const center = sum(shifted, GuardDecimal, xs.length);
-	const squared = shifted.map((x) => x.minus(center).pow(2));
-	return new Decimal(sum(squared, GuardDecimal, sample ? xs.length - 1 : xs.length)
-		.sqrt().times(scale).toSignificantDigits(DECIMAL_PRECISION));
+	return decimals(values, name);
 }
 
 function tangent(value: DecimalValue): DecimalValue {
@@ -162,30 +121,47 @@ function tangent(value: DecimalValue): DecimalValue {
 function arctangent(value: DecimalValue): DecimalValue {
 	// Decimal.atan can loop when argument reduction overflows or underflows.
 	const abs = value.abs();
-	if (abs.lt(SMALL_ATAN_ABS)) return value;
-	if (abs.gt(LARGE_ATAN_ABS)) return PI.div(value.isNegative() ? -2 : 2);
+	if (abs.lt(SMALL_ATAN_ABS)) {
+		return value;
+	}
+	if (abs.gt(LARGE_ATAN_ABS)) {
+		return PI.div(value.isNegative() ? -2 : 2);
+	}
 	return Decimal.atan(value);
 }
 
 function arctangent2(y: DecimalValue, x: DecimalValue): DecimalValue {
-	if (x.isZero() || y.isZero() || !x.isFinite() || !y.isFinite()) return Decimal.atan2(y, x);
+	if (x.isZero() || y.isZero() || !x.isFinite() || !y.isFinite()) {
+		return Decimal.atan2(y, x);
+	}
 	const ratio = y.div(x);
-	if (ratio.abs().lt(SMALL_ATAN_ABS)) return x.isNegative() ? (y.isNegative() ? PI.negated() : PI) : ratio;
-	if (ratio.abs().gt(LARGE_ATAN_ABS)) return PI.div(y.isNegative() ? -2 : 2);
+	if (ratio.abs().lt(SMALL_ATAN_ABS)) {
+		if (x.isNegative()) {
+			return y.isNegative() ? PI.negated() : PI;
+		}
+		return ratio;
+	}
+	if (ratio.abs().gt(LARGE_ATAN_ABS)) {
+		return PI.div(y.isNegative() ? -2 : 2);
+	}
 	return Decimal.atan2(y, x);
 }
 
 function expm1(value: DecimalValue): DecimalValue {
 	const x = new GuardDecimal(value.toString());
 	if (x.abs().gte(0.1)) {
-		return new Decimal(GuardDecimal.exp(x).minus(1).toSignificantDigits(DECIMAL_PRECISION).toString());
+		return new Decimal(
+			GuardDecimal.exp(x).minus(1).toSignificantDigits(DECIMAL_PRECISION).toString(),
+		);
 	}
 	let term = x;
 	let total = x;
 	for (let n = 2; n <= DECIMAL_PRECISION + 10; n++) {
 		term = term.times(x).div(n);
 		const next = total.plus(term);
-		if (next.eq(total)) break;
+		if (next.eq(total)) {
+			break;
+		}
 		total = next;
 	}
 	return new Decimal(total.toSignificantDigits(DECIMAL_PRECISION).toString());
@@ -194,21 +170,27 @@ function expm1(value: DecimalValue): DecimalValue {
 function log1p(value: DecimalValue): DecimalValue {
 	const x = new GuardDecimal(value.toString());
 	if (x.abs().gte(0.1)) {
-		return new Decimal(GuardDecimal.ln(x.plus(1)).toSignificantDigits(DECIMAL_PRECISION).toString());
+		return new Decimal(
+			GuardDecimal.ln(x.plus(1)).toSignificantDigits(DECIMAL_PRECISION).toString(),
+		);
 	}
 	let power = x;
 	let total = x;
 	for (let n = 2; n <= DECIMAL_PRECISION + 10; n++) {
 		power = power.times(x);
 		const next = n % 2 === 0 ? total.minus(power.div(n)) : total.plus(power.div(n));
-		if (next.eq(total)) break;
+		if (next.eq(total)) {
+			break;
+		}
 		total = next;
 	}
 	return new Decimal(total.toSignificantDigits(DECIMAL_PRECISION).toString());
 }
 
 function spendExpensiveWork(cost: number): void {
-	if (cost > expensiveWorkLeft) throw new Error("expression work budget exceeded");
+	if (cost > expensiveWorkLeft) {
+		throw new Error("expression work budget exceeded");
+	}
 	expensiveWorkLeft -= cost;
 }
 
@@ -218,18 +200,25 @@ function trigonometric(
 	maxAbs?: DecimalValue,
 ): (x: DecimalValue) => DecimalValue {
 	return (x) => {
-		if (maxAbs && x.abs().gt(maxAbs)) {
-			throw new Error(`${name}() argument too large (max absolute value ${maxAbs.toString()})`);
+		if (maxAbs !== undefined && x.abs().gt(maxAbs)) {
+			throw new Error(
+				`${name}() argument too large (max absolute value ${maxAbs.toString()})`,
+			);
 		}
 		spendExpensiveWork(TRIG_WORK);
 		return fn(x);
 	};
 }
 
-function hyperbolic(name: string, fn: (x: DecimalValue) => DecimalValue): (x: DecimalValue) => DecimalValue {
+function hyperbolic(
+	name: string,
+	fn: (x: DecimalValue) => DecimalValue,
+): (x: DecimalValue) => DecimalValue {
 	return (x) => {
 		if (x.abs().gt(MAX_HYPERBOLIC_ABS)) {
-			throw new Error(`${name}() argument too large (max absolute value ${MAX_HYPERBOLIC_ABS})`);
+			throw new Error(
+				`${name}() argument too large (max absolute value ${MAX_HYPERBOLIC_ABS})`,
+			);
 		}
 		spendExpensiveWork(x.isFinite() ? Math.max(1, Math.ceil(x.abs().toNumber())) : 1);
 		return fn(x);
@@ -239,7 +228,9 @@ function hyperbolic(name: string, fn: (x: DecimalValue) => DecimalValue): (x: De
 function modulo(a: unknown, b: unknown) {
 	const left = toDec(a);
 	const right = toDec(b);
-	if (right.isZero()) throw new Error("modulo by zero");
+	if (right.isZero()) {
+		throw new Error("modulo by zero");
+	}
 	const exponentGap = left.isFinite() && right.isFinite() ? Math.abs(left.e - right.e) : 0;
 	if (exponentGap > MAX_MODULO_EXPONENT_GAP) {
 		throw new Error(`modulo exponent gap too large (max ${MAX_MODULO_EXPONENT_GAP})`);
@@ -248,29 +239,39 @@ function modulo(a: unknown, b: unknown) {
 	return left.mod(right);
 }
 
-function roundTo(...args: unknown[]) {
+function roundTo(...args: readonly unknown[]) {
 	requireArity("roundTo", args, 2);
 	const digits = toDec(args[1]);
 	if (!digits.isInteger() || digits.abs().gt(MAX_ROUND_DIGITS)) {
-		throw new Error(`roundTo() digits must be an integer from -${MAX_ROUND_DIGITS} to ${MAX_ROUND_DIGITS}`);
+		throw new Error(
+			`roundTo() digits must be an integer from -${MAX_ROUND_DIGITS} to ${MAX_ROUND_DIGITS}`,
+		);
 	}
 	const places = digits.toNumber();
 	const value = toDec(args[0]);
-	if (places >= 0) return value.toDecimalPlaces(places);
+	if (places >= 0) {
+		return value.toDecimalPlaces(places);
+	}
 	const scale = new Decimal(10).pow(-places);
 	return value.div(scale).toDecimalPlaces(0).times(scale);
 }
 
 function arrayIndex(values: unknown, index: unknown): unknown {
-	if (!Array.isArray(values)) throw new Error("indexing needs an array");
+	if (!Array.isArray(values)) {
+		throw new Error("indexing needs an array");
+	}
 	let n: DecimalValue;
 	try {
 		n = toDec(index);
 	} catch {
 		throw new Error("array index needs an integer");
 	}
-	if (!n.isInteger()) throw new Error("array index needs an integer");
-	if (n.lt(0) || n.gte(values.length)) throw new Error("array index out of range");
+	if (!n.isInteger()) {
+		throw new Error("array index needs an integer");
+	}
+	if (n.lt(0) || n.gte(values.length)) {
+		throw new Error("array index out of range");
+	}
 	return values[n.toNumber()];
 }
 
@@ -306,7 +307,12 @@ const decimalUnary: Record<string, (x: DecimalValue) => DecimalValue> = {
 };
 
 parser.unaryOps = nullMap({
-	...Object.fromEntries(Object.entries(decimalUnary).map(([name, fn]) => [name, (value: unknown) => fn(toDec(value))])),
+	...Object.fromEntries(
+		Object.entries(decimalUnary).map(([name, fn]) => [
+			name,
+			(value: unknown) => fn(toDec(value)),
+		]),
+	),
 	"+": toDec,
 	"-": (value: unknown) => toDec(value).negated(),
 	"!": factorial,
@@ -319,7 +325,9 @@ parser.binaryOps = nullMap({
 	"/": (a, b) => {
 		const numerator = toDec(a);
 		const denominator = toDec(b);
-		if (denominator.isZero()) throw new Error("division by zero");
+		if (denominator.isZero()) {
+			throw new Error("division by zero");
+		}
 		return numerator.div(denominator);
 	},
 	"%": modulo,
@@ -328,38 +336,40 @@ parser.binaryOps = nullMap({
 });
 parser.ternaryOps = nullMap({});
 
-const hypot = (...args: unknown[]) => Decimal.hypot(...decimalArguments(args, "hypot"));
+const hypot = (...args: readonly unknown[]) => Decimal.hypot(...decimalArguments(args, "hypot"));
 
 parser.functions = nullMap({
-	d: (...args: unknown[]) => {
+	d: (...args: readonly unknown[]) => {
 		requireArity("d", args, 1);
-		if (typeof args[0] !== "string") throw new Error("invalid decimal literal");
+		if (typeof args[0] !== "string") {
+			throw new Error("invalid decimal literal");
+		}
 		return toDec(args[0]);
 	},
-	fac: (...args: unknown[]) => {
+	fac: (...args: readonly unknown[]) => {
 		requireArity("fac", args, 1);
 		return factorial(args[0]);
 	},
-	pow: (...args: unknown[]) => {
+	pow: (...args: readonly unknown[]) => {
 		requireArity("pow", args, 2);
 		return toDec(args[0]).pow(toDec(args[1]));
 	},
-	atan2: (...args: unknown[]) => {
+	atan2: (...args: readonly unknown[]) => {
 		requireArity("atan2", args, 2);
 		const values = args.map(toDec);
 		spendExpensiveWork(TRIG_WORK);
-		return arctangent2(values[0]!, values[1]!);
+		return arctangent2(argumentAt(values, 0), argumentAt(values, 1));
 	},
-	min: (...args: unknown[]) => Decimal.min(...decimalArguments(args, "min")),
-	max: (...args: unknown[]) => Decimal.max(...decimalArguments(args, "max")),
-	sum: (...args: unknown[]) => {
+	min: (...args: readonly unknown[]) => Decimal.min(...decimalArguments(args, "min")),
+	max: (...args: readonly unknown[]) => Decimal.max(...decimalArguments(args, "max")),
+	sum: (...args: readonly unknown[]) => {
 		requireArity("sum", args, 1);
-		return sum(decimals(args[0], "sum"));
+		return exactSum(decimals(args[0], "sum"));
 	},
 	hypot,
 	pyt: hypot,
 	roundTo,
-	percent: (...args: unknown[]) => {
+	percent: (...args: readonly unknown[]) => {
 		requireArity("percent", args, 2);
 		const rate = toDec(args[0]);
 		const amount = toDec(args[1]);
@@ -368,29 +378,32 @@ parser.functions = nullMap({
 			? amount.div(100).times(rate)
 			: rate.div(100).times(amount);
 	},
-	radians: (...args: unknown[]) => {
+	radians: (...args: readonly unknown[]) => {
 		requireArity("radians", args, 1);
 		return toDec(args[0]).times(PI).div(180);
 	},
-	degrees: (...args: unknown[]) => {
+	degrees: (...args: readonly unknown[]) => {
 		requireArity("degrees", args, 1);
 		return toDec(args[0]).times(180).div(PI);
 	},
-	mean: (...args: unknown[]) => {
+	mean: (...args: readonly unknown[]) => {
 		requireArity("mean", args, 1);
 		return mean(decimals(args[0], "mean"));
 	},
-	median: (...args: unknown[]) => {
+	median: (...args: readonly unknown[]) => {
 		requireArity("median", args, 1);
 		const xs = decimals(args[0], "median").sort((a, b) => a.comparedTo(b));
 		const mid = Math.floor(xs.length / 2);
-		return xs.length % 2 === 0 ? mean([xs[mid - 1]!, xs[mid]!]) : xs[mid]!;
+		if (xs.length % 2 !== 0) {
+			return argumentAt(xs, mid);
+		}
+		return mean([argumentAt(xs, mid - 1), argumentAt(xs, mid)]);
 	},
-	stdev: (...args: unknown[]) => {
+	stdev: (...args: readonly unknown[]) => {
 		requireArity("stdev", args, 1);
 		return standardDeviation(decimals(args[0], "stdev"), false);
 	},
-	stdevs: (...args: unknown[]) => {
+	stdevs: (...args: readonly unknown[]) => {
 		requireArity("stdevs", args, 1);
 		return standardDeviation(decimals(args[0], "stdevs", 2), true);
 	},
@@ -400,27 +413,34 @@ parser.consts = nullMap({ PI, E });
 
 function normalizeExpression(expression: string): string {
 	const trimmed = expression.trim();
-	if (!trimmed) throw new Error("Expression is empty");
+	if (trimmed === "") {
+		throw new Error("Expression is empty");
+	}
 	if (trimmed.length > MAX_EXPRESSION_LENGTH) {
 		throw new Error(`Expression too long (max ${MAX_EXPRESSION_LENGTH} chars)`);
 	}
 	return trimmed;
 }
 
-function resultString(result: unknown): string {
-	if (typeof result === "number") result = new Decimal(String(result));
+function resultString(value: unknown): string {
+	const result = typeof value === "number" ? new Decimal(String(value)) : value;
 	if (!(result instanceof Decimal)) {
 		const type = Array.isArray(result) ? "array" : typeof result;
 		throw new Error(`Expression did not evaluate to a number (got ${type})`);
 	}
 	if (!result.isFinite()) {
-		if (result.isNaN()) throw new Error("Result is NaN");
+		if (result.isNaN()) {
+			throw new Error("Result is NaN");
+		}
 		throw new Error(result.isPositive() ? "Result is Infinity" : "Result is -Infinity");
 	}
 	return result.toString();
 }
 
-export function evaluateExpression(expression: string): { expression: string; value: string | string[] } {
+export function evaluateExpression(expression: string): {
+	expression: string;
+	value: string | string[];
+} {
 	const normalized = normalizeExpression(expression);
 	let result: unknown;
 	factorialWorkLeft = MAX_FACTORIAL_WORK;
@@ -433,14 +453,18 @@ export function evaluateExpression(expression: string): { expression: string; va
 			.replace(/^\[DecimalError\]\s*/, "")
 			.replace(/^parse error \[\d+:\d+\]:\s*/, "")
 			.replace(/\bT[A-Z]+:\s*/g, "");
-		if (/precision limit exceeded/i.test(message)) message = "numeric argument exceeds precision limit";
-		if (error instanceof RangeError && /call stack/i.test(message)) message = "expression is too deeply nested";
-		throw new Error(`Invalid expression: ${message}`);
+		if (/precision limit exceeded/i.test(message)) {
+			message = "numeric argument exceeds precision limit";
+		}
+		if (error instanceof RangeError && /call stack/i.test(message)) {
+			message = "expression is too deeply nested";
+		}
+		throw new Error(`Invalid expression: ${message}`, { cause: error });
 	} finally {
 		factorialWorkLeft = 0;
 		expensiveWorkLeft = 0;
 		resetDecimal();
-		GuardDecimal.set(GUARD_DECIMAL_CONFIG);
+		resetGuardDecimal();
 	}
 
 	const value = Array.isArray(result) ? result.map(resultString) : resultString(result);

package/expr-eval-fork.d.ts

@@ -1,8 +1,14 @@
-import "expr-eval-fork";
+// Re-exporting keeps this file a module, so the declaration augments the package's typings.
+import type { Parser } from "expr-eval-fork";
+
+export type { Parser };
 
 declare module "expr-eval-fork" {
 	interface Parser {
 		binaryOps: Record<string, (left: unknown, right: unknown) => unknown>;
-		ternaryOps: Record<string, (condition: unknown, consequent: unknown, alternate: unknown) => unknown>;
+		ternaryOps: Record<
+			string,
+			(condition: unknown, consequent: unknown, alternate: unknown) => unknown
+		>;
 	}
 }

package/index.ts

@@ -13,26 +13,38 @@ const calculatorTool = defineTool({
 		"Use calculator for non-trivial calculations; simple arithmetic does not need a tool call. Results are rounded decimal strings. In calculator expressions, use sum([...]) for totals and roundTo(value, places) for requested rounding. Put independent results in a flat array.",
 	],
 	constrainedSampling: { type: "json_schema", strict: "prefer" },
+	annotations: { readOnlyHint: true, idempotentHint: true },
 	parameters: Type.Object(
 		{
 			expression: Type.String({
 				minLength: 1,
 				maxLength: MAX_EXPRESSION_LENGTH,
-				description: "Numeric expression: + - * / % ^ **, PI, E, roots, trig, n! (0–1000), sum/mean/median. log/ln are natural; log2/log10 choose a base. Use expm1(x) for exp(x)-1 and log1p(x) for ln(1+x) when x is small. Trig uses radians; radians(degrees) and degrees(radians) convert angles. percent(rate, amount) gives rate% of amount. stdev(array) is population; stdevs(array) is sample. roundTo(value, places) rounds halves away from zero.",
+				description:
+					"Numeric expression: + - * / % ^ **, PI, E, roots, trig, n! (0–1000), sum/mean/median. log/ln are natural; log2/log10 choose a base. Use expm1(x) for exp(x)-1 and log1p(x) for ln(1+x) when x is small. Trig uses radians; radians(degrees) and degrees(radians) convert angles. percent(rate, amount) gives rate% of amount. stdev(array) is population; stdevs(array) is sample. roundTo(value, places) rounds halves away from zero.",
 			}),
 		},
 		{ additionalProperties: false },
 	),
-	outputSchema: Type.Object({
-		expression: Type.String(),
-		value: Type.Union([Type.String(), Type.Array(Type.String())]),
-	}, { additionalProperties: false }),
-	renderCall(args, theme) {
-		return new Text(theme.fg("toolTitle", theme.bold("calculator ")) + theme.fg("dim", JSON.stringify(args.expression ?? "")), 0, 0);
+	outputSchema: Type.Object(
+		{
+			expression: Type.String(),
+			value: Type.Union([Type.String(), Type.Array(Type.String())]),
+		},
+		{ additionalProperties: false },
+	),
+	renderCall(args: { readonly expression?: string }, theme) {
+		return new Text(
+			theme.fg("toolTitle", theme.bold("calculator ")) +
+				theme.fg("dim", JSON.stringify(args.expression ?? "")),
+			0,
+			0,
+		);
 	},
 	async execute(_toolCallId, params) {
 		const evaluated = evaluateExpression(params.expression);
-		const text = Array.isArray(evaluated.value) ? JSON.stringify(evaluated.value) : evaluated.value;
+		const text = Array.isArray(evaluated.value)
+			? JSON.stringify(evaluated.value)
+			: evaluated.value;
 		return {
 			content: [{ type: "text", text }],
 			details: evaluated,
@@ -41,6 +53,6 @@ const calculatorTool = defineTool({
 	},
 });
 
-export default function (pi: ExtensionAPI) {
+export default function (pi: ExtensionAPI): void {
 	pi.registerTool(calculatorTool);
 }

package/package.json

@@ -1,71 +1,90 @@
 {
-  "name": "@fitchmultz/pi-calculator",
-  "version": "4.1.6",
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "description": "Deterministic high-precision calculator tool for Pi",
-  "type": "module",
-  "files": [
-    "index.ts",
-    "eval.ts",
-    "decimal.ts",
-    "expr-eval-fork.d.ts",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "keywords": [
-    "pi-package",
-    "pi",
-    "calculator",
-    "decimal"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/fitchmultz/pi-calculator.git"
-  },
-  "engines": {
-    "node": ">=24.0.0"
-  },
-  "scripts": {
-    "check": "node check.ts",
-    "check:load": "node check-extension.ts",
-    "typecheck": "tsc",
-    "verify": "npm run typecheck && npm run check && npm run check:load",
-    "check:compat": "npm run verify"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "dependencies": {
-    "decimal.js": "10.6.0",
-    "expr-eval-fork": "3.0.3"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
-    "@earendil-works/pi-tui": {
-      "optional": true
-    },
-    "typebox": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.4.0",
-    "@earendil-works/pi-tui": "1.4.0",
-    "@types/node": "24.19.1",
-    "typebox": "1.3.27",
-    "typescript": "7.0.2"
-  }
+	"name": "@fitchmultz/pi-calculator",
+	"version": "4.1.7",
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "MIT",
+	"description": "Deterministic high-precision calculator tool for Pi",
+	"type": "module",
+	"files": [
+		"index.ts",
+		"eval.ts",
+		"decimal.ts",
+		"expr-eval-fork.d.ts",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE",
+		"statistics.ts",
+		"docs"
+	],
+	"keywords": [
+		"pi-package",
+		"pi",
+		"calculator",
+		"decimal"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fitchmultz/pi-calculator.git"
+	},
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"scripts": {
+		"check": "node check.ts",
+		"check:load": "node check-extension.ts",
+		"typecheck": "tsc",
+		"typecheck:declarations": "tsc -p tsconfig.declarations.json",
+		"lint": "node scripts/lint.mjs all",
+		"lint:agent": "node scripts/lint.mjs agent",
+		"lint:fix": "node scripts/lint.mjs fix",
+		"format": "oxfmt --write .",
+		"format:check": "oxfmt --check .",
+		"policy": "node scripts/policy.ts",
+		"test": "node --test \"test/**/*.test.ts\"",
+		"verify": "node scripts/checks.mjs lint format:check typecheck typecheck:declarations lint:baseline policy test check check:load",
+		"check:compat": "npm run verify",
+		"lint:baseline": "node scripts/lint-baseline.ts",
+		"lint:scope": "node scripts/lint.mjs scope",
+		"format:write": "oxfmt --write .",
+		"check:quality": "node scripts/checks.mjs lint format:check typecheck typecheck:declarations lint:baseline policy"
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"image": "https://raw.githubusercontent.com/fitchmultz/pi-calculator/main/.github/readme/calculator-flow.png"
+	},
+	"dependencies": {
+		"decimal.js": "10.6.0",
+		"expr-eval-fork": "3.0.3"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
+		},
+		"typebox": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "^1.4.0",
+		"@earendil-works/pi-coding-agent": "1.4.0",
+		"@earendil-works/pi-tui": "1.4.0",
+		"@types/node": "24.19.1",
+		"oxfmt": "0.75.0",
+		"oxlint": "1.90.0",
+		"oxlint-tsgolint": "7.0.2005",
+		"typebox": "1.3.27",
+		"typescript": "7.0.2"
+	}
 }

package/statistics.ts

@@ -0,0 +1,151 @@
+import { DECIMAL_PRECISION, Decimal, GuardDecimal, type DecimalValue } from "./decimal.ts";
+
+/** Absent bins hold zero, which is what the sparse sum below assumes. */
+function bin(bins: Map<bigint, bigint>, key: bigint): bigint {
+	return bins.get(key) ?? 0n;
+}
+
+function addBin(bins: Map<bigint, bigint>, key: bigint, value: bigint): void {
+	bins.set(key, (bins.get(key) ?? 0n) + value);
+}
+
+/** Exact significand digits as a signed integer, keeping every input digit. */
+function significandDigits(value: DecimalValue): string {
+	const [digits] = value.toExponential().split("e");
+	if (digits === undefined) {
+		throw new Error("expected an exact decimal significand");
+	}
+	return digits.replace(".", "");
+}
+
+/** Spread each value across the bins its exponent falls in, keeping the exact sum sparse. */
+function fillBins(xs: readonly DecimalValue[], bins: Map<bigint, bigint>, width: bigint): void {
+	for (const x of xs) {
+		if (x.isZero()) {
+			continue;
+		}
+		const exponent = BigInt(x.e) - BigInt(x.sd() - 1);
+		const key = exponent >= 0n ? exponent / width : (exponent - width + 1n) / width;
+		addBin(bins, key, BigInt(significandDigits(x)) * 10n ** (exponent - key * width));
+	}
+}
+
+/** Carry each bin into the next so every stored bin stays below the base. */
+function carryBins(bins: Map<bigint, bigint>, base: bigint): void {
+	for (const start of [...bins.keys()].sort((a, b) => Number(a - b))) {
+		let key = start;
+		for (;;) {
+			const value = bin(bins, key);
+			const carry = value / base;
+			bins.set(key, value % base);
+			if (carry === 0n) {
+				break;
+			}
+			key += 1n;
+			addBin(bins, key, carry);
+		}
+	}
+}
+
+type DecimalConstructor = typeof Decimal;
+
+const digitCount = (n: bigint) => n.toString().replace("-", "").length;
+
+/** Fold the leading bins into one coefficient; a sticky digit keeps the tail's side of a tie. */
+function leadingCoefficient(
+	bins: Map<bigint, bigint>,
+	keys: readonly bigint[],
+	base: bigint,
+	retained: number,
+): [coefficient: bigint, key: bigint, shift: bigint] {
+	const leading = keys[0];
+	if (leading === undefined) {
+		return [0n, 0n, 0n];
+	}
+	let key = leading;
+	let coefficient = bin(bins, key);
+	let index = 1;
+	while (index < keys.length) {
+		const next = keys[index];
+		if (next === undefined) {
+			break;
+		}
+		if (digitCount(coefficient) >= retained || key - next > 2n) {
+			break;
+		}
+		coefficient = coefficient * base ** (key - next) + bin(bins, next);
+		key = next;
+		index += 1;
+	}
+	// Normalized chunks have magnitude < base, so the leading remaining chunk
+	// determines the tail's sign.
+	let shift = 0n;
+	const tail = index < keys.length ? keys[index] : undefined;
+	if (tail !== undefined) {
+		shift = BigInt(Math.max(2, retained - digitCount(coefficient)));
+		coefficient = coefficient * 10n ** shift + (bin(bins, tail) > 0n ? 1n : -1n);
+	}
+	return [coefficient, key, shift];
+}
+
+/** Sum `xs` exactly, then divide, so large exponent gaps keep every input digit. */
+export function exactSum(
+	xs: readonly DecimalValue[],
+	Ctor: DecimalConstructor = Decimal,
+	divisor = 1,
+): DecimalValue {
+	if (xs.some((x) => !x.isFinite())) {
+		return Ctor.sum(...xs).div(divisor);
+	}
+
+	// Decimal.sum also truncates across large exponent gaps. Signed BigInt chunks
+	// keep the exact sum sparse, including intermediate values outside Decimal's range.
+	const width = BigInt(Ctor.precision);
+	const base = 10n ** width;
+	const bins = new Map<bigint, bigint>();
+	fillBins(xs, bins, width);
+	carryBins(bins, base);
+
+	const keys = [...bins.keys()]
+		.filter((key) => bins.get(key) !== 0n)
+		.sort((a, b) => Number(b - a));
+	if (keys.length === 0) {
+		return new Ctor(0);
+	}
+	const retained = Ctor.precision + Math.ceil(Math.log10(divisor)) + 2;
+	const [coefficient, key, shift] = leadingCoefficient(bins, keys, base, retained);
+	// Divide and round before restoring the exponent to avoid intermediate overflow/underflow.
+	const [mantissa, exponent] = new Ctor(coefficient.toString())
+		.div(divisor)
+		.toExponential()
+		.split("e");
+	if (mantissa === undefined || exponent === undefined) {
+		throw new Error("expected an exact decimal exponent form");
+	}
+	return new Ctor(`${mantissa}e${BigInt(exponent) + key * width - shift}`);
+}
+
+export function mean(xs: readonly DecimalValue[]): DecimalValue {
+	return exactSum(xs, Decimal, xs.length);
+}
+
+export function standardDeviation(xs: readonly DecimalValue[], sample: boolean): DecimalValue {
+	// Scale before subtraction; a power of ten preserves small spreads around a large offset.
+	const widest = GuardDecimal.max(...xs.map((x) => x.abs()));
+	const scale = new GuardDecimal(`1e${widest.e}`);
+	const scaled = xs.map((x) => new GuardDecimal(x).div(scale));
+	const anchor = scaled[0];
+	if (anchor === undefined) {
+		throw new Error("statistics need at least one number");
+	}
+	// Center on an input first so a large common offset cannot round away the spread.
+	const shifted = scaled.map((x) => x.minus(anchor));
+	const center = exactSum(shifted, GuardDecimal, xs.length);
+	const squared = shifted.map((x) => x.minus(center).pow(2));
+	return new Decimal(
+		exactSum(squared, GuardDecimal, sample ? xs.length - 1 : xs.length)
+			.sqrt()
+			.times(scale)
+			.toSignificantDigits(DECIMAL_PRECISION),
+	);
+}