@insiderfinance/totalfinance 0.1.0

package/modules/risk/dist/frontier.js

@@ -0,0 +1,1183 @@
+/**
+ * The constrained mean-variance efficient frontier (FC7 slice 4, Stage 4.4), traced by composing
+ * the existing optimizers plus a covariance-independent linear maximum-return endpoint:
+ *
+ *   • the left endpoint is `minVariance` under the same constraints;
+ *   • every interior point is `meanVariance` at some risk aversion λ — sweeping λ under a fixed
+ *     constraint set traces the frontier, and a target expected return is met by monotone
+ *     bisection on λ (the solved return is non-increasing in λ);
+ *   • the tangency point, when a per-period risk-free rate is supplied, is `maxSharpe`.
+ *
+ * The grid is explicit (`'risk-aversion'` values, `'target-return'` values, or an evenly spaced
+ * `'points'` count between the minimum-variance return and the maximum achievable return) — a
+ * missing goal is a typed refusal, not a secret default. Every point is kept in grid order,
+ * including the ones that could not be solved: an unreachable target is a `feasible: false`
+ * point whose `reason` names the achievable range; a non-finite solve is a failed point. The
+ * sweep itself never throws past input validation and never carries a non-finite number.
+ */
+import { CONVENTIONS_VERSION, ErrorCode, InputError, ensureKnownKeys, requireArgumentArray, requireArgumentObject, requireRepresentableResult, warning, WarningCode, } from '../../core/dist/index.js';
+import { describeInputValue } from './input-description.js';
+import { assertSquare, dot, quadForm } from './linalg.js';
+import { snapshotFiniteVector } from './numeric-vector.js';
+import { OPTIMIZE_CONSTRAINTS_KEYS, validateOptimizeConstraints } from './optimizer-validation.js';
+import { maxSharpe, meanVariance, minVariance, } from './optimize.js';
+const FUNCTION_NAME = 'efficientFrontier';
+const INPUT_KEYS = ['mean', 'covariance', 'grid', 'constraints', 'riskFreeRatePerPeriod'];
+const GRID_KINDS = [
+    'risk-aversion',
+    'target-return',
+    'points',
+];
+/**
+ * First-stage cap on the number of requested points. The aggregate solve budget below is the
+ * decisive cap because a target point contains a bisection of full constrained solves.
+ */
+const MAX_FRONTIER_POINTS = 10_000;
+/** Maximum aggregate outer solver iterations licensed by one synchronous frontier call. */
+const MAX_FRONTIER_WORK_UNITS = 10_000_000;
+/**
+ * Conservative primitive-operation budget: covariance mat-vecs scale with n²; a general
+ * constraint projection may run 500 Dykstra cycles across every convex set, each O(n).
+ */
+const MAX_FRONTIER_OPERATION_UNITS = 12_000_000_000;
+/** Actual hard caps in the optimizer projectors and endpoint simplex. */
+const MAX_AFFINE_BOX_PROJECTION_SWEEPS = 600;
+const MAX_DYKSTRA_CYCLES = 500;
+const MAX_LINEAR_PROGRAM_OPERATIONS = 50_000_000;
+/** The mean-variance/minimum-variance default when the caller does not state a cap. */
+const DEFAULT_SOLVER_ITERATIONS = 5_000;
+/** Constrained maxSharpe performs at most 65 grid + 2 seed + 40 refinement solves. */
+const MAX_TANGENCY_SOLVES = 107;
+/** Scale-relative bisection bracket on log₁₀ λ for target-return points. */
+const LOG_LAMBDA_RELATIVE_LOW = -16;
+const LOG_LAMBDA_RELATIVE_HIGH = 16;
+const MAX_BISECTION_STEPS = 64;
+/** λ grid used for `'points'` when the maximum return is unbounded/unknown: [10⁻², 10²]. */
+const FALLBACK_LOG_LAMBDA_RANGE = [-2, 2];
+/** Tolerance below which a point counts as satisfying the constraint set. */
+const FEASIBILITY_TOL = 1e-6;
+/** Relative tolerance for "the solved return equals the target" and endpoint identification. */
+const TARGET_RELATIVE_TOL = 1e-10;
+const fail = (message, code, context) => {
+    throw new InputError(`${FUNCTION_NAME}: ${message}`, { code, context });
+};
+const hasOwnProperty = Object.prototype.hasOwnProperty;
+/** Plain stored-data object guard for this facade's nested request grammar. */
+function requireDataObject(field, value, consumed) {
+    requireArgumentObject(FUNCTION_NAME, field, value);
+    const record = value;
+    const prototype = Object.getPrototypeOf(record);
+    if (prototype !== Object.prototype && prototype !== null) {
+        fail(`${field} must be a plain object of stored data.`, ErrorCode.InputWrongType, { field });
+    }
+    for (const key of Reflect.ownKeys(record)) {
+        const descriptor = Object.getOwnPropertyDescriptor(record, key);
+        if (typeof key !== 'string' ||
+            descriptor === undefined ||
+            !descriptor.enumerable ||
+            !('value' in descriptor)) {
+            fail(`${field} must contain only enumerable string-keyed stored data; accessors, hidden fields, and symbols are not frontier inputs.`, ErrorCode.InputWrongShape, { field });
+        }
+    }
+    for (const key of consumed) {
+        if (hasOwnProperty.call(record, key) || !(key in record))
+            continue;
+        fail(`${field}.${key} is inherited rather than an own field — state every frontier input explicitly.`, ErrorCode.InputWrongShape, { field: `${field}.${key}` });
+    }
+}
+/** Dense stored-data arrays for the grid grammar (no sparse/accessor/decorated arrays). */
+function requireDataArray(field, value) {
+    if (!Array.isArray(value)) {
+        fail(`${field} must be a plain array.`, ErrorCode.InputWrongType, { field });
+    }
+    const array = value;
+    if (Object.getPrototypeOf(array) !== Array.prototype) {
+        fail(`${field} must be a plain array.`, ErrorCode.InputWrongType, { field });
+    }
+    for (let index = 0; index < array.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(array, String(index));
+        if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {
+            fail(`${field} must be a dense array of stored values; index ${index} is missing or accessor-backed.`, ErrorCode.InputWrongShape, { field: `${field}[${index}]` });
+        }
+    }
+    for (const key of Reflect.ownKeys(array)) {
+        if (key === 'length')
+            continue;
+        const index = typeof key === 'string' && /^(0|[1-9][0-9]*)$/.test(key) ? Number(key) : -1;
+        if (!Number.isSafeInteger(index) || index < 0 || index >= array.length) {
+            fail(`${field} must contain only its dense indexed values; ${String(key)} is not grid data.`, ErrorCode.InputWrongShape, { field });
+        }
+    }
+}
+// ───────────────────────── validation ─────────────────────────
+function validateGrid(grid) {
+    if (grid === undefined) {
+        fail(`grid is required — { kind: 'risk-aversion', values } | { kind: 'target-return', values } | { kind: 'points', count }. There is no default sampling of the frontier.`, ErrorCode.InputMissingField, { field: 'grid' });
+    }
+    requireDataObject('grid', grid, ['kind', 'count', 'values']);
+    const record = grid;
+    const kind = record['kind'];
+    if (kind === undefined) {
+        fail(`grid.kind is required — one of ${GRID_KINDS.map((k) => `'${k}'`).join(' | ')}.`, ErrorCode.InputMissingField, { field: 'grid.kind' });
+    }
+    if (typeof kind !== 'string' || !GRID_KINDS.includes(kind)) {
+        const received = describeInputValue(kind);
+        fail(`grid.kind must be one of ${GRID_KINDS.map((k) => `'${k}'`).join(' | ')}. Received ${received}.`, ErrorCode.InputInvalidEnum, { field: 'grid.kind', received });
+    }
+    if (kind === 'points') {
+        ensureKnownKeys(FUNCTION_NAME, 'grid', grid, ['kind', 'count']);
+        const count = record['count'];
+        if (count === undefined) {
+            fail(`grid.count is required for grid.kind 'points'.`, ErrorCode.InputMissingField, {
+                field: 'grid.count',
+            });
+        }
+        // A count is a work budget (2026-08-23 review, P0): safe integer, ≥ 2, and capped.
+        if (typeof count !== 'number' ||
+            !Number.isSafeInteger(count) ||
+            count < 2 ||
+            count > MAX_FRONTIER_POINTS) {
+            fail(`grid.count must be a safe integer in [2, ${MAX_FRONTIER_POINTS.toLocaleString('en-US')}] (each point is a full constrained mean-variance solve, so the count is a work budget; two points are the frontier's endpoints), got ${describeInputValue(count)}.`, ErrorCode.InputOutOfRange, { received: describeInputValue(count), min: 2, max: MAX_FRONTIER_POINTS });
+        }
+        return { kind: 'points', count: count };
+    }
+    ensureKnownKeys(FUNCTION_NAME, 'grid', grid, ['kind', 'values']);
+    const values = record['values'];
+    if (values === undefined) {
+        fail(`grid.values is required for grid.kind '${kind}'.`, ErrorCode.InputMissingField, {
+            field: 'grid.values',
+        });
+    }
+    requireDataArray('grid.values', values);
+    const list = values;
+    if (list.length === 0) {
+        fail(`grid.values must list at least one ${kind} value.`, ErrorCode.InputWrongShape, {
+            field: 'grid.values',
+            length: 0,
+        });
+    }
+    if (list.length > MAX_FRONTIER_POINTS) {
+        fail(`grid.values lists ${list.length.toLocaleString('en-US')} points; the sweep is capped at ${MAX_FRONTIER_POINTS.toLocaleString('en-US')} (each point is a full constrained solve).`, ErrorCode.InputOutOfRange, { points: list.length, max: MAX_FRONTIER_POINTS });
+    }
+    for (let i = 0; i < list.length; i++) {
+        const v = list[i];
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            fail(`grid.values[${i}] must be a finite number, got ${describeInputValue(v)}.`, ErrorCode.InputNotFinite, { field: 'grid.values', index: i, received: describeInputValue(v) });
+        }
+        if (kind === 'risk-aversion' && !(v > 0)) {
+            fail(`grid.values[${i}] must be > 0 for grid.kind 'risk-aversion' (λ scales the variance penalty), got ${v}.`, ErrorCode.InputOutOfRange, { field: 'grid.values', index: i, received: v });
+        }
+    }
+    return kind === 'risk-aversion'
+        ? { kind: 'risk-aversion', values: list.slice() }
+        : { kind: 'target-return', values: list.slice() };
+}
+/** The mean vector: correct length and all finite (the optimizers' own teaching, replicated). */
+function requireMeanVector(mean, n) {
+    return snapshotFiniteVector(FUNCTION_NAME, 'mean', mean, n);
+}
+function pointCountOf(grid) {
+    return grid.kind === 'points' ? grid.count : grid.values.length;
+}
+/**
+ * Refuse the PRODUCT of point count, target bisection depth, endpoint work, tangency work, and the
+ * caller's per-solve iteration cap. Independent coordinate caps do not bound their product.
+ */
+function requireFrontierWorkBudget(grid, constraints, includesTangency, assetCount, maximumReturnBounded) {
+    const maximumIterations = constraints.maximumIterations ?? DEFAULT_SOLVER_ITERATIONS;
+    const points = pointCountOf(grid);
+    const pointSolves = grid.kind === 'risk-aversion'
+        ? points
+        : grid.kind === 'target-return'
+            ? points * MAX_BISECTION_STEPS
+            : maximumReturnBounded === true
+                ? // Two finite endpoints are reused without a mean-variance solve. If either endpoint
+                    // cannot be produced, the implementation falls back to one risk-aversion solve per
+                    // requested point, so retain that branch in the upper bound too.
+                    Math.max(points, Math.max(0, points - 2) * MAX_BISECTION_STEPS)
+                : points;
+    const hasInequality = Boolean(constraints.longOnly ||
+        constraints.bounds ||
+        constraints.groups?.length ||
+        constraints.turnover);
+    const tangencySolves = includesTangency ? (hasInequality ? MAX_TANGENCY_SOLVES : 1) : 0;
+    // One minimum-variance solve, the branch-accurate grid work, and optional tangency work. The
+    // linear endpoint has its own independent primitive-operation cap below rather than pretending
+    // it performs projected-gradient iterations.
+    const solverCalls = 1 + pointSolves + tangencySolves;
+    const workUnits = solverCalls * maximumIterations;
+    const hasGeneralProjection = Boolean(constraints.groups?.length || constraints.turnover);
+    const constraintSetCount = 2 +
+        (constraints.groups ?? []).reduce((count, group) => count + (group.min !== undefined ? 1 : 0) + (group.max !== undefined ? 1 : 0), 0) +
+        (constraints.turnover !== undefined ? 1 : 0);
+    // The affine-box projector performs TWO 200-step bracketing loops plus 200 bisections (600), not
+    // 64. General constraints perform 500 Dykstra cycles; a turnover set sorts n magnitudes in every
+    // cycle. Add one n² covariance mat-vec per outer iteration, a conservative 4n³ factorization /
+    // conditioning setup per solver call, and the endpoint simplex's independent 50m cap.
+    const projectionOperations = hasGeneralProjection
+        ? MAX_DYKSTRA_CYCLES *
+            (constraintSetCount * assetCount +
+                (constraints.turnover !== undefined
+                    ? assetCount * Math.max(1, Math.ceil(Math.log2(Math.max(2, assetCount))))
+                    : 0))
+        : MAX_AFFINE_BOX_PROJECTION_SWEEPS * assetCount;
+    const operationsPerIteration = assetCount * assetCount + projectionOperations;
+    const setupOperations = solverCalls * 4 * assetCount ** 3;
+    const endpointOperations = maximumReturnBounded === true ? MAX_LINEAR_PROGRAM_OPERATIONS : 0;
+    const operationUnits = workUnits * operationsPerIteration +
+        solverCalls * projectionOperations +
+        setupOperations +
+        endpointOperations;
+    if (workUnits > MAX_FRONTIER_WORK_UNITS ||
+        operationUnits > MAX_FRONTIER_OPERATION_UNITS ||
+        !Number.isSafeInteger(operationUnits)) {
+        fail(`grid, asset dimension, and constraints combine to at most ${workUnits.toLocaleString('en-US')} constrained-solver iterations (${solverCalls.toLocaleString('en-US')} possible solves × ${maximumIterations.toLocaleString('en-US')} iterations) and ${Number.isFinite(operationUnits) ? operationUnits.toLocaleString('en-US') : 'more than Number.MAX_SAFE_INTEGER'} primitive operation units (n² covariance work plus ${hasGeneralProjection ? `up to ${MAX_DYKSTRA_CYCLES} Dykstra cycles across ${constraintSetCount} constraint sets${constraints.turnover !== undefined ? ' including the turnover sort' : ''}` : `${MAX_AFFINE_BOX_PROJECTION_SWEEPS} affine-box bracket/bisection sweeps`}, factorization setup, and the bounded endpoint LP). This synchronous call's aggregate budgets are ${MAX_FRONTIER_WORK_UNITS.toLocaleString('en-US')} solver iterations and ${MAX_FRONTIER_OPERATION_UNITS.toLocaleString('en-US')} operation units. Reduce the grid count/values, lower constraints.maximumIterations, simplify the constraint set, or split independent frontier requests explicitly.`, ErrorCode.InputOutOfRange, {
+            field: 'grid',
+            points,
+            assetCount,
+            solverCalls,
+            maximumIterations,
+            tangencySolves,
+            maximumReturnBounded,
+            workUnits,
+            maximumWorkUnits: MAX_FRONTIER_WORK_UNITS,
+            constraintSetCount,
+            projectionOperations,
+            operationsPerIteration,
+            setupOperations,
+            endpointOperations,
+            operationUnits,
+            maximumOperationUnits: MAX_FRONTIER_OPERATION_UNITS,
+        });
+    }
+}
+/**
+ * Re-throw an optimizer's input refusal under this function's name so the teaching names the
+ * boundary the caller actually touched; the code and context are preserved.
+ */
+function refuseAsFrontier(error) {
+    if (error instanceof InputError) {
+        throw new InputError(`${FUNCTION_NAME}: ${error.message}`, {
+            code: error.code,
+            context: { ...(error.context ?? {}), function: FUNCTION_NAME },
+        });
+    }
+    throw error;
+}
+// ───────────────────────── feasibility & boundedness under the constraint grammar ─────────────────────────
+function resolveBoxBounds(n, c) {
+    if (c.bounds)
+        return { lo: c.bounds.map((b) => b[0]), hi: c.bounds.map((b) => b[1]) };
+    const lo = c.longOnly ? 0 : Number.NEGATIVE_INFINITY;
+    return {
+        lo: new Array(n).fill(lo),
+        hi: new Array(n).fill(Number.POSITIVE_INFINITY),
+    };
+}
+/**
+ * Maximum absolute violation of the constraint set by `w` (0 ⇒ feasible): budget equality, box,
+ * group caps, turnover budget — the same measure the optimizers use to refuse a fabricated success.
+ */
+function constraintViolation(w, budget, c) {
+    const n = w.length;
+    const { lo, hi } = resolveBoxBounds(n, c);
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+        if (!Number.isFinite(w[i]))
+            return Infinity;
+        sum += w[i];
+    }
+    let v = Math.abs(sum - budget);
+    for (let i = 0; i < n; i++)
+        v = Math.max(v, lo[i] - w[i], w[i] - hi[i]);
+    for (const g of c.groups ?? []) {
+        let s = 0;
+        for (const m of g.members)
+            s += w[m];
+        if (g.max !== undefined)
+            v = Math.max(v, s - g.max);
+        if (g.min !== undefined)
+            v = Math.max(v, g.min - s);
+    }
+    if (c.turnover) {
+        let t = 0;
+        for (let i = 0; i < n; i++)
+            t += Math.abs(w[i] - c.turnover.previousWeights[i]);
+        v = Math.max(v, t - c.turnover.max);
+    }
+    return v;
+}
+function resolveEndpointBounds(n, c) {
+    const { lo, hi } = resolveBoxBounds(n, c);
+    let hasAggregateGroups = false;
+    for (const group of c.groups ?? []) {
+        if (group.members.length !== 1) {
+            hasAggregateGroups = true;
+            continue;
+        }
+        const member = group.members[0];
+        if (group.min !== undefined)
+            lo[member] = Math.max(lo[member], group.min);
+        if (group.max !== undefined)
+            hi[member] = Math.min(hi[member], group.max);
+    }
+    return { lo, hi, hasAggregateGroups };
+}
+/**
+ * Prove whether EXPECTED RETURN is bounded without consulting covariance or an iterative solver.
+ * Under a budget equality and a box, return is unbounded exactly when weight can flow without
+ * limit from a lower-mean, unbounded-below asset to a higher-mean, unbounded-above asset. A finite
+ * turnover ball is compact. Aggregate groups may remove such a direction; until a general LP
+ * certificate exists, that case is honestly `null` (unknown), never falsely called unbounded.
+ */
+function maximumReturnBounded(problem) {
+    const { mu, constraints } = problem;
+    if (constraints.turnover)
+        return { bounded: true, iterations: 0 };
+    const { lo, hi, hasAggregateGroups } = resolveEndpointBounds(mu.length, constraints);
+    let boxAllowsPositiveRecession = false;
+    for (let receiver = 0; receiver < mu.length && !boxAllowsPositiveRecession; receiver++) {
+        if (hi[receiver] !== Number.POSITIVE_INFINITY)
+            continue;
+        for (let donor = 0; donor < mu.length; donor++) {
+            if (receiver !== donor &&
+                lo[donor] === Number.NEGATIVE_INFINITY &&
+                mu[receiver] > mu[donor]) {
+                boxAllowsPositiveRecession = true;
+                break;
+            }
+        }
+    }
+    if (!boxAllowsPositiveRecession)
+        return { bounded: true, iterations: 0 };
+    if (hasAggregateGroups)
+        return { bounded: null, iterations: 0 };
+    return { bounded: false, iterations: 0 };
+}
+function constraintSummary(n, c, budget) {
+    const parts = [`budget ${budget}`];
+    if (c.bounds)
+        parts.push(`${n} per-asset [lower, upper] bounds`);
+    else if (c.longOnly)
+        parts.push('long-only (weights ≥ 0)');
+    else
+        parts.push('no box (weights unbounded above and below)');
+    if (c.groups?.length)
+        parts.push(`${c.groups.length} group exposure cap(s)`);
+    if (c.turnover)
+        parts.push(`turnover ≤ ${c.turnover.max} against previous weights`);
+    if (c.maximumIterations !== undefined)
+        parts.push(`maximumIterations ${c.maximumIterations}`);
+    if (c.tolerance !== undefined)
+        parts.push(`tolerance ${c.tolerance}`);
+    return parts.join('; ');
+}
+const failedPortfolio = (reason, warnings, iterations = 0) => ({
+    weights: null,
+    expectedReturn: null,
+    variance: null,
+    volatility: null,
+    sharpeRatio: null,
+    converged: false,
+    iterations,
+    feasible: false,
+    reason,
+    warnings,
+});
+/** Measure a solver result into a frontier portfolio; a non-finite anywhere makes it a failed one. */
+function measure(problem, result, solverName) {
+    const weights = result.value.weights;
+    const iterations = result.diagnostics.iterations ?? 0;
+    const warnings = result.diagnostics.warnings;
+    if (weights.length !== problem.mu.length || weights.some((w) => !Number.isFinite(w))) {
+        return failedPortfolio(`${solverName} produced non-finite weights — the point is reported as failed rather than carrying NaN into the frontier.`, warnings, iterations);
+    }
+    const expectedReturn = dot(problem.mu, weights);
+    const variance = quadForm(problem.covariance, weights);
+    const volatility = Math.sqrt(Math.max(0, variance));
+    if (!Number.isFinite(expectedReturn) || !Number.isFinite(variance)) {
+        return failedPortfolio(`${solverName} weights give a non-finite expected return or variance (the input magnitudes overflow the arithmetic) — reported as a failed point.`, warnings, iterations);
+    }
+    let sharpeRatio = null;
+    if (problem.riskFreeRatePerPeriod !== undefined) {
+        sharpeRatio =
+            volatility > 0 ? (expectedReturn - problem.riskFreeRatePerPeriod) / volatility : null;
+        if (sharpeRatio !== null && !Number.isFinite(sharpeRatio)) {
+            return failedPortfolio(`${solverName} weights give a non-finite Sharpe ratio — reported as a failed point.`, warnings, iterations);
+        }
+    }
+    const violation = constraintViolation(weights, problem.budget, problem.constraints);
+    const feasible = violation <= FEASIBILITY_TOL;
+    const converged = (result.diagnostics.converged ?? false) && feasible;
+    const solverReason = warnings.find((w) => w.code === 'optimize.not_converged')?.context?.['reason'];
+    const reason = !feasible
+        ? `${solverName} could not satisfy the constraint set (maximum violation ${violation.toExponential(2)}) — the feasible region is empty or the solver stopped outside it.`
+        : !converged
+            ? `${solverName} stopped without converging${typeof solverReason === 'string' ? ` (${solverReason})` : ''}.`
+            : undefined;
+    return {
+        weights,
+        expectedReturn,
+        variance,
+        volatility,
+        sharpeRatio,
+        converged,
+        iterations,
+        feasible,
+        ...(reason !== undefined ? { reason } : {}),
+        warnings: [
+            ...warnings,
+            ...(problem.riskFreeRatePerPeriod !== undefined && volatility === 0
+                ? [
+                    warning(WarningCode.RiskZeroVolatilitySharpe, `${FUNCTION_NAME}: the portfolio has zero volatility, so its Sharpe ratio is undefined (reported as null).`, 'info', { expectedReturn }),
+                ]
+                : []),
+        ],
+    };
+}
+/** Solve `meanVariance` at risk aversion λ under the problem's constraint set. */
+function solveAtRiskAversion(problem, riskAversion) {
+    const options = { ...problem.constraints, riskAversion };
+    const result = meanVariance({ mean: problem.mu, covariance: problem.covariance, options });
+    return measure(problem, result, `meanVariance (λ = ${riskAversion.toExponential(3)})`);
+}
+const withRequested = (portfolio, index, requested) => ({ index, requested, ...portfolio });
+const nearlyEqual = (a, b) => Math.abs(a - b) <= TARGET_RELATIVE_TOL * Math.max(1, Math.abs(a), Math.abs(b));
+/**
+ * Derive finite coordinate bounds from the hard constraint grammar. A turnover ball bounds each
+ * coordinate directly. Otherwise, finite lower (upper) bounds plus the budget equality imply an
+ * upper (lower) bound for every coordinate. This proves compactness for the common long-only +
+ * sector-cap problem without pretending arbitrary overlapping groups imply individual bounds.
+ */
+function finiteEndpointBounds(problem) {
+    const { lo, hi } = resolveEndpointBounds(problem.mu.length, problem.constraints);
+    const turnover = problem.constraints.turnover;
+    if (turnover) {
+        for (let index = 0; index < lo.length; index++) {
+            lo[index] = Math.max(lo[index], turnover.previousWeights[index] - turnover.max);
+            hi[index] = Math.min(hi[index], turnover.previousWeights[index] + turnover.max);
+        }
+    }
+    if (lo.every(Number.isFinite)) {
+        const totalLower = lo.reduce((sum, value) => sum + value, 0);
+        if (!Number.isFinite(totalLower))
+            return null;
+        for (let index = 0; index < hi.length; index++) {
+            hi[index] = Math.min(hi[index], problem.budget - (totalLower - lo[index]));
+        }
+    }
+    if (hi.every(Number.isFinite)) {
+        const totalUpper = hi.reduce((sum, value) => sum + value, 0);
+        if (!Number.isFinite(totalUpper))
+            return null;
+        for (let index = 0; index < lo.length; index++) {
+            lo[index] = Math.max(lo[index], problem.budget - (totalUpper - hi[index]));
+        }
+    }
+    if (!lo.every(Number.isFinite) || !hi.every(Number.isFinite))
+        return null;
+    const bounds = [];
+    for (let index = 0; index < lo.length; index++) {
+        if (lo[index] > hi[index])
+            return null;
+        bounds.push([lo[index], hi[index]]);
+    }
+    return { bounds };
+}
+/** Affine-normalize expected returns to [0, 1] without overflowing on large finite means. */
+function normalizedExpectedReturnObjective(mean) {
+    let magnitude = 0;
+    for (const value of mean)
+        magnitude = Math.max(magnitude, Math.abs(value));
+    if (magnitude === 0)
+        return null;
+    const scaled = mean.map((value) => value / magnitude);
+    let minimum = scaled[0];
+    let maximum = scaled[0];
+    for (const value of scaled) {
+        minimum = Math.min(minimum, value);
+        maximum = Math.max(maximum, value);
+    }
+    const spread = maximum - minimum;
+    return spread === 0 ? null : scaled.map((value) => (value - minimum) / spread);
+}
+const LINEAR_PROGRAM_EPSILON = 1e-10;
+const MAX_LINEAR_PROGRAM_TABLEAU_CELLS = 2_000_000;
+/** Two-phase simplex for `max objective·x` subject to `A·x ≤ b`, `x ≥ 0`. */
+function solveLinearProgram(input) {
+    const { coefficients: A, bounds: b, objective, maximumPivots } = input;
+    const rowCount = b.length;
+    const variableCount = objective.length;
+    const cells = (rowCount + 2) * (variableCount + 2);
+    if (cells > MAX_LINEAR_PROGRAM_TABLEAU_CELLS ||
+        A.some((row, index) => row.length !== variableCount ||
+            !Number.isFinite(b[index]) ||
+            row.some((value) => !Number.isFinite(value))) ||
+        objective.some((value) => !Number.isFinite(value))) {
+        return { status: 'numerical', pivots: 0 };
+    }
+    const operationBound = Math.max(1, Math.floor(MAX_LINEAR_PROGRAM_OPERATIONS / Math.max(1, cells)));
+    const pivotLimit = Math.min(maximumPivots, operationBound);
+    if (pivotLimit < 1)
+        return { status: 'work-limit', pivots: 0 };
+    const basic = new Array(rowCount);
+    const nonBasic = new Array(variableCount + 1);
+    const tableau = Array.from({ length: rowCount + 2 }, () => new Array(variableCount + 2).fill(0));
+    for (let row = 0; row < rowCount; row++) {
+        for (let column = 0; column < variableCount; column++) {
+            tableau[row][column] = A[row][column];
+        }
+        basic[row] = variableCount + row;
+        tableau[row][variableCount] = -1;
+        tableau[row][variableCount + 1] = b[row];
+    }
+    for (let column = 0; column < variableCount; column++) {
+        nonBasic[column] = column;
+        tableau[rowCount][column] = -objective[column];
+    }
+    nonBasic[variableCount] = -1;
+    tableau[rowCount + 1][variableCount] = 1;
+    let pivots = 0;
+    let numericalFailure = false;
+    const pivot = (pivotRow, pivotColumn) => {
+        if (pivots >= pivotLimit)
+            return false;
+        const value = tableau[pivotRow][pivotColumn];
+        if (!Number.isFinite(value) || Math.abs(value) <= LINEAR_PROGRAM_EPSILON) {
+            numericalFailure = true;
+            return false;
+        }
+        const inverse = 1 / value;
+        for (let row = 0; row < rowCount + 2; row++) {
+            if (row === pivotRow)
+                continue;
+            for (let column = 0; column < variableCount + 2; column++) {
+                if (column === pivotColumn)
+                    continue;
+                tableau[row][column] =
+                    tableau[row][column] -
+                        tableau[pivotRow][column] * tableau[row][pivotColumn] * inverse;
+            }
+        }
+        for (let column = 0; column < variableCount + 2; column++) {
+            if (column !== pivotColumn) {
+                tableau[pivotRow][column] = tableau[pivotRow][column] * inverse;
+            }
+        }
+        for (let row = 0; row < rowCount + 2; row++) {
+            if (row !== pivotRow) {
+                tableau[row][pivotColumn] = tableau[row][pivotColumn] * -inverse;
+            }
+        }
+        tableau[pivotRow][pivotColumn] = inverse;
+        const previousBasic = basic[pivotRow];
+        basic[pivotRow] = nonBasic[pivotColumn];
+        nonBasic[pivotColumn] = previousBasic;
+        pivots++;
+        if (tableau.some((row) => row.some((value) => !Number.isFinite(value)))) {
+            numericalFailure = true;
+            return false;
+        }
+        return true;
+    };
+    const runPhase = (phase) => {
+        const objectiveRow = phase === 1 ? rowCount + 1 : rowCount;
+        while (true) {
+            let entering = -1;
+            for (let column = 0; column <= variableCount; column++) {
+                if (phase === 2 && nonBasic[column] === -1)
+                    continue;
+                if (entering < 0 ||
+                    tableau[objectiveRow][column] <
+                        tableau[objectiveRow][entering] - LINEAR_PROGRAM_EPSILON ||
+                    (Math.abs(tableau[objectiveRow][column] - tableau[objectiveRow][entering]) <=
+                        LINEAR_PROGRAM_EPSILON &&
+                        nonBasic[column] < nonBasic[entering])) {
+                    entering = column;
+                }
+            }
+            if (entering < 0 || tableau[objectiveRow][entering] >= -LINEAR_PROGRAM_EPSILON) {
+                return 'optimal';
+            }
+            let leaving = -1;
+            for (let row = 0; row < rowCount; row++) {
+                const coefficient = tableau[row][entering];
+                if (coefficient <= LINEAR_PROGRAM_EPSILON)
+                    continue;
+                if (leaving < 0) {
+                    leaving = row;
+                    continue;
+                }
+                const ratio = tableau[row][variableCount + 1] / coefficient;
+                const currentRatio = tableau[leaving][variableCount + 1] / tableau[leaving][entering];
+                if (ratio < currentRatio - LINEAR_PROGRAM_EPSILON ||
+                    (Math.abs(ratio - currentRatio) <= LINEAR_PROGRAM_EPSILON &&
+                        basic[row] < basic[leaving])) {
+                    leaving = row;
+                }
+            }
+            if (leaving < 0)
+                return 'unbounded';
+            if (!pivot(leaving, entering))
+                return 'stopped';
+        }
+    };
+    let mostNegativeRow = 0;
+    for (let row = 1; row < rowCount; row++) {
+        if (tableau[row][variableCount + 1] < tableau[mostNegativeRow][variableCount + 1]) {
+            mostNegativeRow = row;
+        }
+    }
+    if (rowCount > 0 && tableau[mostNegativeRow][variableCount + 1] < -LINEAR_PROGRAM_EPSILON) {
+        if (!pivot(mostNegativeRow, variableCount)) {
+            return { status: numericalFailure ? 'numerical' : 'work-limit', pivots };
+        }
+        const phaseOne = runPhase(1);
+        if (phaseOne === 'stopped') {
+            return { status: numericalFailure ? 'numerical' : 'work-limit', pivots };
+        }
+        if (phaseOne === 'unbounded' ||
+            tableau[rowCount + 1][variableCount + 1] < -LINEAR_PROGRAM_EPSILON) {
+            return { status: 'infeasible', pivots };
+        }
+        for (let row = 0; row < rowCount; row++) {
+            if (basic[row] !== -1)
+                continue;
+            let entering = 0;
+            for (let column = 1; column <= variableCount; column++) {
+                if (Math.abs(tableau[row][column]) >
+                    Math.abs(tableau[row][entering]) + LINEAR_PROGRAM_EPSILON ||
+                    (Math.abs(Math.abs(tableau[row][column]) - Math.abs(tableau[row][entering])) <=
+                        LINEAR_PROGRAM_EPSILON &&
+                        nonBasic[column] < nonBasic[entering])) {
+                    entering = column;
+                }
+            }
+            if (Math.abs(tableau[row][entering]) > LINEAR_PROGRAM_EPSILON && !pivot(row, entering)) {
+                return { status: numericalFailure ? 'numerical' : 'work-limit', pivots };
+            }
+        }
+    }
+    const phaseTwo = runPhase(2);
+    if (phaseTwo === 'stopped') {
+        return { status: numericalFailure ? 'numerical' : 'work-limit', pivots };
+    }
+    if (phaseTwo === 'unbounded')
+        return { status: 'unbounded', pivots };
+    const solution = new Array(variableCount).fill(0);
+    for (let row = 0; row < rowCount; row++) {
+        if (basic[row] >= 0 && basic[row] < variableCount) {
+            solution[basic[row]] = tableau[row][variableCount + 1];
+        }
+    }
+    return { status: 'optimal', solution, pivots };
+}
+/** General covariance-independent LP endpoint for aggregate groups and turnover constraints. */
+function solveCertifiedMaximumReturn(problem) {
+    const compact = finiteEndpointBounds(problem);
+    if (compact === null) {
+        return {
+            portfolio: null,
+            iterations: 0,
+            reason: 'the hard constraints do not yield finite coordinate bounds for a scale-independent endpoint certificate',
+        };
+    }
+    const objective = normalizedExpectedReturnObjective(problem.mu);
+    if (objective === null) {
+        return {
+            portfolio: null,
+            iterations: 0,
+            reason: 'the expected-return objective has no representable cross-asset spread',
+        };
+    }
+    const assetCount = problem.mu.length;
+    const hasTurnover = problem.constraints.turnover !== undefined;
+    const variableCount = assetCount + (hasTurnover ? assetCount : 0);
+    const coefficients = [];
+    const bounds = [];
+    const addConstraint = (entries, bound) => {
+        if (!Number.isFinite(bound))
+            return false;
+        const row = new Array(variableCount).fill(0);
+        for (const [index, coefficient] of entries)
+            row[index] = coefficient;
+        coefficients.push(row);
+        bounds.push(bound);
+        return true;
+    };
+    const lower = compact.bounds.map(([value]) => value);
+    const upper = compact.bounds.map(([, value]) => value);
+    for (let index = 0; index < assetCount; index++) {
+        if (!addConstraint([[index, 1]], upper[index] - lower[index])) {
+            return { portfolio: null, iterations: 0, reason: 'a shifted weight bound overflowed' };
+        }
+    }
+    const lowerSum = lower.reduce((sum, value) => sum + value, 0);
+    const shiftedBudget = problem.budget - lowerSum;
+    const budgetEntries = lower.map((_, index) => [index, 1]);
+    if (!addConstraint(budgetEntries, shiftedBudget) ||
+        !addConstraint(budgetEntries.map(([index]) => [index, -1]), -shiftedBudget)) {
+        return { portfolio: null, iterations: 0, reason: 'the shifted budget overflowed' };
+    }
+    for (const group of problem.constraints.groups ?? []) {
+        const entries = group.members.map((member) => [member, 1]);
+        const lowerInGroup = group.members.reduce((sum, member) => sum + lower[member], 0);
+        if ((group.max !== undefined && !addConstraint(entries, group.max - lowerInGroup)) ||
+            (group.min !== undefined &&
+                !addConstraint(entries.map(([index]) => [index, -1]), lowerInGroup - group.min))) {
+            return { portfolio: null, iterations: 0, reason: 'a shifted group bound overflowed' };
+        }
+    }
+    if (problem.constraints.turnover) {
+        const turnover = problem.constraints.turnover;
+        for (let index = 0; index < assetCount; index++) {
+            const auxiliary = assetCount + index;
+            const shiftedPrevious = turnover.previousWeights[index] - lower[index];
+            if (!addConstraint([
+                [index, 1],
+                [auxiliary, -1],
+            ], shiftedPrevious) ||
+                !addConstraint([
+                    [index, -1],
+                    [auxiliary, -1],
+                ], -shiftedPrevious)) {
+                return { portfolio: null, iterations: 0, reason: 'a shifted turnover bound overflowed' };
+            }
+        }
+        if (!addConstraint(lower.map((_, index) => [assetCount + index, 1]), turnover.max)) {
+            return { portfolio: null, iterations: 0, reason: 'the turnover budget overflowed' };
+        }
+    }
+    const lp = solveLinearProgram({
+        coefficients,
+        bounds,
+        objective: [...objective, ...(hasTurnover ? new Array(assetCount).fill(0) : [])],
+        maximumPivots: problem.constraints.maximumIterations ?? DEFAULT_SOLVER_ITERATIONS,
+    });
+    if (lp.status !== 'optimal') {
+        return {
+            portfolio: null,
+            iterations: lp.pivots,
+            reason: `the linear maximum-return endpoint stopped with status '${lp.status}'`,
+        };
+    }
+    const weights = lower.map((value, index) => value + lp.solution[index]);
+    const portfolio = { ...exactEndpointPortfolio(problem, weights), iterations: lp.pivots };
+    if (!portfolio.converged) {
+        return {
+            portfolio: null,
+            iterations: lp.pivots,
+            reason: portfolio.reason ?? 'the linear endpoint failed its post-solve feasibility audit',
+        };
+    }
+    return { portfolio, iterations: lp.pivots };
+}
+/**
+ * Maximize a linear objective over a budget equality and per-asset box by transferring weight from
+ * the lowest-return donors to the highest-return receivers. Starting from any feasible point, this
+ * is the continuous-knapsack optimum. A finite `transferLimit` adds an L1 turnover ball around the
+ * starting portfolio: each unit moved consumes two units of L1 turnover.
+ */
+function maximizeExpectedReturnByTransfers(mean, start, lo, hi, transferLimit, budget) {
+    const weights = start.slice();
+    // Iterative solvers may return a feasible point a few ulps off the budget plane. Repair that
+    // residue before the exact transfer solve so an endpoint at a literal bound remains literal.
+    let budgetResidue = budget - weights.reduce((sum, weight) => sum + weight, 0);
+    for (let index = 0; index < weights.length && budgetResidue !== 0; index++) {
+        const capacity = budgetResidue > 0 ? hi[index] - weights[index] : weights[index] - lo[index];
+        if (!(capacity > 0))
+            continue;
+        const adjustment = Math.sign(budgetResidue) * Math.min(Math.abs(budgetResidue), capacity);
+        weights[index] = weights[index] + adjustment;
+        budgetResidue -= adjustment;
+    }
+    if (Math.abs(budgetResidue) > FEASIBILITY_TOL)
+        return null;
+    const donors = mean.map((_, index) => index).sort((a, b) => mean[a] - mean[b] || a - b);
+    const receivers = donors.slice().reverse();
+    let donorCursor = 0;
+    let receiverCursor = 0;
+    let remaining = transferLimit;
+    while (donorCursor < donors.length && receiverCursor < receivers.length && remaining > 0) {
+        const donor = donors[donorCursor];
+        const receiver = receivers[receiverCursor];
+        if (donor === receiver || !(mean[receiver] > mean[donor]))
+            break;
+        const donorCapacity = Math.max(0, weights[donor] - lo[donor]);
+        const receiverCapacity = Math.max(0, hi[receiver] - weights[receiver]);
+        if (donorCapacity === 0) {
+            donorCursor++;
+            continue;
+        }
+        if (receiverCapacity === 0) {
+            receiverCursor++;
+            continue;
+        }
+        const amount = Math.min(donorCapacity, receiverCapacity, remaining);
+        // An infinite transfer is precisely an unbounded direction. It should have been classified
+        // before this solve; returning null keeps a numerical edge case from fabricating an endpoint.
+        if (!(amount > 0) || !Number.isFinite(amount))
+            return null;
+        weights[donor] = weights[donor] - amount;
+        weights[receiver] = weights[receiver] + amount;
+        if (!Number.isFinite(weights[donor]) || !Number.isFinite(weights[receiver]))
+            return null;
+        if (Number.isFinite(remaining))
+            remaining = Math.max(0, remaining - amount);
+        if (amount >= donorCapacity)
+            donorCursor++;
+        if (amount >= receiverCapacity)
+            receiverCursor++;
+    }
+    return weights;
+}
+function exactEndpointPortfolio(problem, weights) {
+    const result = {
+        value: { weights, objective: dot(problem.mu, weights) },
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            objective: 'maximum-expected-return',
+            budget: problem.budget,
+        },
+        diagnostics: { converged: true, iterations: 0, warnings: [] },
+    };
+    return measure(problem, result, 'linear maximum-return endpoint');
+}
+/**
+ * Compute the covariance-independent maximum-return endpoint exactly for box/budget constraints,
+ * singleton groups, and the common turnover case whose base portfolio is itself feasible. More
+ * general aggregate groups or an off-budget turnover base are returned as undetermined rather than
+ * approximated with an arbitrary risk-aversion ladder.
+ */
+function solveMaximumReturn(problem, minimum) {
+    const { lo, hi, hasAggregateGroups } = resolveEndpointBounds(problem.mu.length, problem.constraints);
+    let start = minimum.weights;
+    let transferLimit = Number.POSITIVE_INFINITY;
+    if (problem.constraints.turnover) {
+        start = problem.constraints.turnover.previousWeights;
+        transferLimit = problem.constraints.turnover.max / 2;
+        const baseBudgetGap = Math.abs(start.reduce((sum, weight) => sum + weight, 0) - problem.budget);
+        if (baseBudgetGap > 1e-12 ||
+            constraintViolation(start, problem.budget, problem.constraints) > FEASIBILITY_TOL) {
+            return solveCertifiedMaximumReturn(problem);
+        }
+    }
+    if (hasAggregateGroups)
+        return solveCertifiedMaximumReturn(problem);
+    if (start === null) {
+        return {
+            portfolio: null,
+            iterations: 0,
+            reason: 'no feasible starting portfolio was available',
+        };
+    }
+    const weights = maximizeExpectedReturnByTransfers(problem.mu, start, lo, hi, transferLimit, problem.budget);
+    if (weights === null) {
+        return {
+            portfolio: null,
+            iterations: 0,
+            reason: 'the exact linear endpoint exceeded finite-number representation',
+        };
+    }
+    return { portfolio: exactEndpointPortfolio(problem, weights), iterations: 0 };
+}
+const describeRange = (range) => {
+    const low = range.minimum?.expectedReturn;
+    const high = range.maximum?.expectedReturn;
+    const upper = range.bounded === false
+        ? 'unbounded'
+        : high === null || high === undefined
+            ? 'unknown'
+            : String(high);
+    return `[${low === null || low === undefined ? 'unknown' : String(low)}, ${upper}${range.bounded === false ? ')' : ']'}`;
+};
+/**
+ * Center target-return bisection on the scale ratio `mean spread / covariance magnitude`. This
+ * makes an internal target request invariant to quoting covariance in e.g. unit, percent, or basis
+ * point squared terms. Explicit risk-aversion grids retain the caller's literal λ semantics.
+ */
+function targetRiskAversionLogCenter(problem) {
+    let meanMagnitude = 0;
+    for (const value of problem.mu)
+        meanMagnitude = Math.max(meanMagnitude, Math.abs(value));
+    let normalizedSpread = 0;
+    if (meanMagnitude > 0) {
+        const anchor = problem.mu[0] / meanMagnitude;
+        for (const value of problem.mu) {
+            normalizedSpread = Math.max(normalizedSpread, Math.abs(value / meanMagnitude - anchor));
+        }
+    }
+    let covarianceMagnitude = 0;
+    for (const row of problem.covariance) {
+        for (const value of row)
+            covarianceMagnitude = Math.max(covarianceMagnitude, Math.abs(value));
+    }
+    if (meanMagnitude === 0 || normalizedSpread === 0 || covarianceMagnitude === 0)
+        return 0;
+    const center = Math.log10(meanMagnitude) + Math.log10(normalizedSpread) - Math.log10(covarianceMagnitude);
+    // Keep the full relative bracket representable as a positive finite JavaScript number.
+    return Math.max(-280, Math.min(280, center));
+}
+/** Solve one target expected return by monotone bisection on log₁₀ λ. */
+function solveTargetReturn(problem, target, range) {
+    const minimum = range.minimum;
+    if (minimum === null || minimum.expectedReturn === null) {
+        return failedPortfolio(`target ${target} cannot be placed: the minimum-variance endpoint failed (${minimum?.reason ?? 'no solution'}), so the achievable range is unknown.`, []);
+    }
+    const low = minimum.expectedReturn;
+    if (nearlyEqual(target, low))
+        return { ...minimum, iterations: 0 };
+    if (target < low) {
+        return failedPortfolio(`target expected return ${target} is below the minimum-variance portfolio's ${low} — the efficient frontier starts there; achievable range ${describeRange(range)}.`, []);
+    }
+    if (range.bounded === true && range.maximum !== null && range.maximum.expectedReturn !== null) {
+        const high = range.maximum.expectedReturn;
+        if (nearlyEqual(target, high))
+            return { ...range.maximum, iterations: 0 };
+        if (target > high) {
+            return failedPortfolio(`target expected return ${target} exceeds the maximum achievable ${high} under the constraints — achievable range ${describeRange(range)}.`, []);
+        }
+    }
+    // return(λ) is non-increasing in λ under a fixed constraint set: bisect log₁₀ λ around
+    // the problem's mean/covariance scale, not an absolute ladder tied to one unit convention.
+    const logCenter = targetRiskAversionLogCenter(problem);
+    let logLow = logCenter + LOG_LAMBDA_RELATIVE_LOW; // return here ≥ target
+    let logHigh = logCenter + LOG_LAMBDA_RELATIVE_HIGH; // return here ≤ target
+    let iterations = 0;
+    let closest = null;
+    let closestGap = Infinity;
+    const tolerance = TARGET_RELATIVE_TOL * Math.max(1, Math.abs(target));
+    for (let step = 0; step < MAX_BISECTION_STEPS; step++) {
+        const logMid = 0.5 * (logLow + logHigh);
+        const candidate = solveAtRiskAversion(problem, 10 ** logMid);
+        iterations += candidate.iterations;
+        if (candidate.expectedReturn === null) {
+            return { ...candidate, iterations };
+        }
+        const gap = Math.abs(candidate.expectedReturn - target);
+        if (gap < closestGap) {
+            closest = candidate;
+            closestGap = gap;
+        }
+        if (gap <= tolerance)
+            break;
+        if (candidate.expectedReturn > target)
+            logLow = logMid;
+        else
+            logHigh = logMid;
+    }
+    const point = closest;
+    const met = closestGap <= tolerance;
+    const converged = point.converged && met;
+    const reason = !met
+        ? `scale-relative bisection on λ ∈ [1e${logCenter + LOG_LAMBDA_RELATIVE_LOW}, 1e${logCenter + LOG_LAMBDA_RELATIVE_HIGH}] closed to within ${closestGap.toExponential(2)} of target ${target} (closest solved return ${point.expectedReturn}) without meeting it.`
+        : point.reason;
+    return {
+        ...point,
+        iterations,
+        converged,
+        ...(reason !== undefined ? { reason } : {}),
+    };
+}
+// ───────────────────────── the facade ─────────────────────────
+/**
+ * Trace the constrained mean-variance efficient frontier by composing `minVariance`,
+ * `meanVariance`, and (with a risk-free rate) `maxSharpe` under ONE constraint set.
+ *
+ * ```ts
+ * efficientFrontier({
+ *   mean,
+ *   covariance,
+ *   grid: { kind: 'points', count: 20 },
+ *   constraints: { longOnly: true },
+ *   riskFreeRatePerPeriod: 0.04 / 252,
+ * });
+ * ```
+ *
+ * `value.points` keeps every grid point in order; a target outside the achievable range is a
+ * `feasible: false` point whose `reason` names the range, never a throw. `diagnostics.monotone`
+ * reports whether volatility rises with expected return across the solved points (the shape a
+ * correct frontier has) and names the first violation in a warning when it does not.
+ */
+export function efficientFrontier(input) {
+    requireDataObject('input', input, INPUT_KEYS);
+    ensureKnownKeys(FUNCTION_NAME, 'input', input, INPUT_KEYS);
+    const { mean, covariance, constraints: rawConstraints, riskFreeRatePerPeriod } = input;
+    requireArgumentArray(FUNCTION_NAME, 'covariance', covariance);
+    const n = covariance.length;
+    if (n === 0 || !Array.isArray(covariance[0])) {
+        fail('covariance must be a non-empty square matrix (at least one asset).', ErrorCode.InputWrongShape, { rows: n });
+    }
+    assertSquare(covariance, n, FUNCTION_NAME);
+    const mu = requireMeanVector(mean, n);
+    if (rawConstraints !== undefined) {
+        requireDataObject('constraints', rawConstraints, OPTIMIZE_CONSTRAINTS_KEYS);
+        ensureKnownKeys(FUNCTION_NAME, 'constraints', rawConstraints, OPTIMIZE_CONSTRAINTS_KEYS);
+        if (rawConstraints.transactionCosts !== undefined) {
+            fail(`constraints.transactionCosts is not part of an efficient frontier: it changes the objective relative to one previous portfolio, so mixing cost-penalized interior solves with a gross maximum-return endpoint would not describe one coherent frontier. Use meanVariance directly for a cost-aware rebalance, or omit transactionCosts to trace the gross mean-variance frontier.`, ErrorCode.InputOutOfRange, { field: 'constraints.transactionCosts' });
+        }
+    }
+    const constraints = rawConstraints ?? {};
+    // Validate the complete shared grammar without solving. The work estimator below may inspect
+    // nested groups/turnover, and malformed input must receive the optimizer's canonical teaching
+    // before any work or nested property access occurs.
+    validateOptimizeConstraints(constraints, FUNCTION_NAME, n);
+    if (riskFreeRatePerPeriod !== undefined &&
+        (typeof riskFreeRatePerPeriod !== 'number' || !Number.isFinite(riskFreeRatePerPeriod))) {
+        fail(`riskFreeRatePerPeriod must be a finite number in the per-period units of mean, got ${describeInputValue(riskFreeRatePerPeriod)}.`, ErrorCode.InputNotFinite, { received: describeInputValue(riskFreeRatePerPeriod) });
+    }
+    const grid = validateGrid(input.grid);
+    const budget = constraints.budget ?? 1;
+    const problem = { mu, covariance, constraints, budget, riskFreeRatePerPeriod };
+    const boundedness = maximumReturnBounded(problem);
+    const bounded = boundedness.bounded;
+    requireFrontierWorkBudget(grid, constraints, riskFreeRatePerPeriod !== undefined, n, bounded);
+    // The left endpoint. Constraint validation and aggregate-work refusal have already completed, so
+    // no hostile request can buy a solver run merely to discover malformed grammar or excessive work.
+    let minimumResult;
+    try {
+        minimumResult = minVariance(covariance, constraints);
+    }
+    catch (error) {
+        refuseAsFrontier(error);
+    }
+    const minimum = measure(problem, minimumResult, 'minVariance');
+    const warnings = [];
+    let totalIterations = minimum.iterations + boundedness.iterations;
+    let maximum = null;
+    let maximumFailureReason;
+    if (bounded === true && minimum.feasible) {
+        const endpoint = solveMaximumReturn(problem, minimum);
+        maximum = endpoint.portfolio;
+        maximumFailureReason = endpoint.reason;
+        totalIterations += endpoint.iterations;
+    }
+    const range = { minimum: minimum.feasible ? minimum : null, maximum, bounded };
+    // ---- the sweep ----
+    const points = [];
+    let gridKind = grid.kind;
+    if (grid.kind === 'risk-aversion') {
+        grid.values.forEach((riskAversion, index) => {
+            const portfolio = solveAtRiskAversion(problem, riskAversion);
+            points.push(withRequested(portfolio, index, { riskAversion }));
+        });
+    }
+    else if (grid.kind === 'target-return') {
+        grid.values.forEach((targetReturn, index) => {
+            const portfolio = solveTargetReturn(problem, targetReturn, range);
+            points.push(withRequested(portfolio, index, { targetReturn }));
+        });
+    }
+    else {
+        const count = grid.count;
+        const low = range.minimum?.expectedReturn ?? null;
+        const high = range.maximum?.expectedReturn ?? null;
+        if (bounded === true && low !== null && high !== null) {
+            for (let index = 0; index < count; index++) {
+                const targetReturn = index === count - 1 ? high : low + ((high - low) * index) / (count - 1);
+                const portfolio = solveTargetReturn(problem, targetReturn, range);
+                points.push(withRequested(portfolio, index, { targetReturn }));
+            }
+        }
+        else {
+            // No finite maximum to span to: fall back to a logarithmic λ grid, descending so expected
+            // return rises left to right, and say so — never throw, never guess a range.
+            gridKind = 'risk-aversion';
+            const [logLow, logHigh] = FALLBACK_LOG_LAMBDA_RANGE;
+            const rangeUnknown = bounded !== false;
+            warnings.push(warning(rangeUnknown ? 'risk.frontier_return_range_unknown' : 'risk.frontier_unbounded_return', rangeUnknown
+                ? `${FUNCTION_NAME}: the maximum achievable return could not be certified (${maximumFailureReason ?? minimum.reason ?? 'aggregate group constraints need a general linear-program certificate'}), so the ${count} points are a logarithmic risk-aversion grid over [1e${logLow}, 1e${logHigh}] (descending) instead of evenly spaced target returns.`
+                : `${FUNCTION_NAME}: the maximum achievable return is unbounded under these box, group, budget, and turnover constraints, so the ${count} points are a logarithmic risk-aversion grid over [1e${logLow}, 1e${logHigh}] (descending) instead of evenly spaced target returns. Add bounds, group limits, longOnly, or a turnover budget that caps the positive-return leverage direction.`, 'warn', { count, bounded, riskAversionRange: [10 ** logLow, 10 ** logHigh] }));
+            for (let index = 0; index < count; index++) {
+                const logLambda = logHigh - ((logHigh - logLow) * index) / (count - 1);
+                const riskAversion = 10 ** logLambda;
+                const portfolio = solveAtRiskAversion(problem, riskAversion);
+                points.push(withRequested(portfolio, index, { riskAversion }));
+            }
+        }
+    }
+    for (const point of points)
+        totalIterations += point.iterations;
+    // ---- tangency ----
+    let tangency;
+    if (riskFreeRatePerPeriod !== undefined) {
+        let tangencyResult;
+        try {
+            tangencyResult = maxSharpe({
+                mean: mu,
+                covariance,
+                options: { ...constraints, riskFreeRatePerPeriod },
+            });
+        }
+        catch (error) {
+            refuseAsFrontier(error);
+        }
+        tangency = measure(problem, tangencyResult, 'maxSharpe');
+        totalIterations += tangency.iterations;
+    }
+    // ---- diagnostics ----
+    const solved = points.filter((p) => p.weights !== null);
+    const solvedCount = solved.length;
+    const failedCount = points.length - solvedCount;
+    const converged = points.length > 0 && failedCount === 0 && points.every((point) => point.converged);
+    let monotone = true;
+    const ordered = solved
+        .slice()
+        .sort((a, b) => a.expectedReturn - b.expectedReturn || a.index - b.index);
+    for (let i = 1; i < ordered.length; i++) {
+        const previous = ordered[i - 1];
+        const current = ordered[i];
+        const slack = 1e-9 * Math.max(1, previous.volatility);
+        if (current.volatility < previous.volatility - slack) {
+            monotone = false;
+            warnings.push(warning(WarningCode.RiskFrontierNotMonotone, `${FUNCTION_NAME}: volatility is not non-decreasing with expected return — point ${current.index} (return ${current.expectedReturn}, volatility ${current.volatility}) sits below point ${previous.index} (return ${previous.expectedReturn}, volatility ${previous.volatility}). A point that did not converge, or an ill-conditioned covariance, usually explains it.`, 'warn', {
+                pointIndex: current.index,
+                previousPointIndex: previous.index,
+                expectedReturn: current.expectedReturn,
+                volatility: current.volatility,
+                previousVolatility: previous.volatility,
+            }));
+            break;
+        }
+    }
+    if (failedCount > 0) {
+        warnings.push(warning(WarningCode.RiskFrontierPointsFailed, `${FUNCTION_NAME}: ${failedCount} of ${points.length} points failed (see each point's reason) — unreachable targets and non-finite solves are reported, not thrown.`, 'warn', {
+            failedCount,
+            failedIndices: points.filter((p) => p.weights === null).map((p) => p.index),
+        }));
+    }
+    const result = {
+        value: {
+            points,
+            minimumVariance: minimum,
+            ...(tangency !== undefined ? { tangency } : {}),
+            expectedReturnRange: {
+                minimum: range.minimum?.expectedReturn ?? null,
+                maximum: bounded === true ? (maximum?.expectedReturn ?? null) : null,
+            },
+            solvedCount,
+            failedCount,
+        },
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            objective: 'mean-variance',
+            budget,
+            grid: { kind: gridKind, count: points.length },
+            ...(riskFreeRatePerPeriod !== undefined ? { riskFreeRatePerPeriod } : {}),
+            constraintSummary: constraintSummary(n, constraints, budget),
+        },
+        diagnostics: {
+            warnings,
+            converged,
+            iterations: totalIterations,
+            solvedCount,
+            failedCount,
+            monotone,
+            maximumReturnBounded: bounded,
+        },
+    };
+    // Law 7 finalizer: every number in the envelope is finite by construction (failed points are
+    // null-with-reason); the finalizer makes that a checked postcondition, not a promise.
+    return requireRepresentableResult(FUNCTION_NAME, result);
+}
+//# sourceMappingURL=frontier.js.map