return-scenario-engine 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Gale Finance Open Source Software
+Copyright 2026 Sid Kalla
+
+This product includes software originally developed by Sid Kalla for
+Gale Finance (https://gale.finance/).

package/README.md

@@ -0,0 +1,68 @@
+# return-scenario-engine
+
+Dependency-free historical investment scenarios for caller-owned normalized index series. TypeScript and Python share a public contract and synthetic golden corpus.
+
+![Synthetic scenario result](https://raw.githubusercontent.com/sidko/return-scenario-engine/main/docs/assets/synthetic-scenario.svg)
+
+```bash
+npm install return-scenario-engine
+# or: python -m pip install return-scenario-engine
+```
+
+```ts
+import { calculateScenario } from 'return-scenario-engine';
+
+const dates = ['2024-01-01', '2024-01-02', '2024-01-03'];
+const result = calculateScenario({
+  amountCents: 100_000,
+  requestedStart: '2024-01-01',
+  requestedEnd: '2024-01-03',
+  assetA: { assetKey: 'sample-a', schemaVersion: 1, methodologyVersion: 'return-scenario-v1.0.0', seriesBasis: 'close_index', annualizationFactor: 365, dates, growthIndex: [100, 110, 121] },
+  assetB: { assetKey: 'sample-b', schemaVersion: 1, methodologyVersion: 'return-scenario-v1.0.0', seriesBasis: 'close_index', annualizationFactor: 365, dates, growthIndex: [100, 95, 100] },
+});
+
+console.log(result.status); // "ok"
+```
+
+Each artifact provides its key, schema/methodology versions, series basis, annualization factor, ordered civil dates, and positive normalized index values. Results contain snapped dates, integer-cent ending values, display-rounded metrics, drawdown/recovery data, correlation, and a shared wealth path; invalid inputs return named errors.
+
+`roundHalfAwayFromZero` / `round_half_away_from_zero` accept any positive safe
+integer scale and reject nonfinite values, invalid scales, and unsafe results.
+
+The visual is actual output from the synthetic `crypto_crypto_long_window` golden case: a $1,000 scenario ends at $2,309.81 for asset A and $845.66 for asset B. This is a headless library, not a chart UI.
+
+## Contract and limits
+
+Node.js 20+ and Python 3.11+ are supported. Both `0.1.0` artifacts share the methodology JSON, public SHA-256 hash, and synthetic fixtures. Read [`return-scenario-v1.json`](https://github.com/sidko/return-scenario-engine/blob/main/methodology/return-scenario-v1.json) before comparing outputs. The package does not fetch prices, select assets, retain provider data, or implement routes and UI. A partial paired registry upload must be completed or corrected before announcing the version.
+
+## Development
+
+```bash
+npm ci
+python -m pip install -e './python[test]'
+PYTHON_BIN=python3 npm test
+python -m build python
+```
+
+`npm test` builds a temporary Python wheel and checks every golden scenario against both implementations. Fixtures are synthetic and contain no provider history.
+
+## First release
+
+For the first npm release, publish the reviewed tarball interactively with 2FA
+and configure npm trusted publishing for `.github/workflows/release.yml` and
+its `npm` environment. Configure PyPI's pending trusted publisher, then run the
+manual release workflow against the existing tag with target `pypi` to upload
+the matching Python artifact. Verify both registries before creating the GitHub
+Release. Later releases use the same manual workflow with target `both`; retry a
+single failed side with `npm` or `pypi`. Never republish an immutable existing
+version or treat a mismatched pair as successful.
+
+## Origin
+
+This package was extracted from [Gale Finance](https://gale.finance/) calculation work. Gale’s launch-bundle formats, UI, routes, analytics, market data, and asset policy stay private. Until migration, it is “extracted from Gale,” not evidence that Gale uses the published artifact.
+
+Early commits reconstruct private-monorepo milestones. Author dates reflect original work; public content and hashes were rewritten to exclude private details. Some early development used Claude as a coding assistant; Sid Kalla selected, reviewed, and maintains this code.
+
+Apache-2.0 covers this code and does not grant rights to Gale Finance branding. See [CONTRIBUTING](https://github.com/sidko/return-scenario-engine/blob/main/CONTRIBUTING.md), [SECURITY](https://github.com/sidko/return-scenario-engine/blob/main/SECURITY.md), and [AGENT_INTEGRATION](https://github.com/sidko/return-scenario-engine/blob/main/AGENT_INTEGRATION.md).
+
+Maintenance is best effort; the latest release is supported unless its notes say otherwise.

package/lib/index.d.ts

@@ -0,0 +1,24 @@
+import type { AmountParseResult, HundredthsMetricValue, ScenarioInput, ScenarioResult } from './types.js';
+export { ARTIFACT_SCHEMA_VERSION, METHODOLOGY_HASH, METHODOLOGY_VERSION } from './methodology.js';
+export declare const SUPPORTED_SCHEMA_VERSION: 1;
+export declare const SUPPORTED_METHODOLOGY_VERSION: "return-scenario-v1.0.0";
+export declare const SUPPORTED_SERIES_BASES: readonly ["close_index", "adjusted_close_index"];
+export declare const DEFAULT_FIXTURE_SERIES_BASIS = "close_index";
+export declare const MIN_AMOUNT_CENTS = 100;
+export declare const MAX_AMOUNT_CENTS = 1000000000;
+export declare const CAGR_DAY_COUNT = 365.25;
+export declare const CALMAR_MIN_ABS_DRAWDOWN = 0.0001;
+export declare const ZERO_VARIANCE_SUMSQ_EPSILON = 1e-24;
+export declare const CORRELATION_CLAMP_TOLERANCE = 1e-12;
+export declare function roundHalfAwayFromZero(value: number, scale?: number): number;
+export declare function displayCents(usdValue: number): number;
+export declare function displayBasisPoints(decimalValue: number): number;
+export declare function displayHundredths(ratioValue: number): number;
+export declare function isValidCivilDate(value: unknown): value is string;
+export declare function civilDay(value: string): number;
+export declare function firstAnniversary(value: string): string;
+export declare function shiftYearsBack(value: string, years: number): string;
+export declare function parseUsdAmountToCents(value: unknown): AmountParseResult;
+export declare const parseAmountToCents: typeof parseUsdAmountToCents;
+export declare function pearsonCorrelation(valuesA: number[], valuesB: number[]): HundredthsMetricValue;
+export declare function calculateScenario(input: ScenarioInput): ScenarioResult;

package/lib/index.js

@@ -0,0 +1,452 @@
+import { METHODOLOGY_HASH, ARTIFACT_SCHEMA_VERSION, METHODOLOGY_VERSION, } from './methodology.js';
+export { ARTIFACT_SCHEMA_VERSION, METHODOLOGY_HASH, METHODOLOGY_VERSION } from './methodology.js';
+export const SUPPORTED_SCHEMA_VERSION = ARTIFACT_SCHEMA_VERSION;
+export const SUPPORTED_METHODOLOGY_VERSION = METHODOLOGY_VERSION;
+export const SUPPORTED_SERIES_BASES = ['close_index', 'adjusted_close_index'];
+export const DEFAULT_FIXTURE_SERIES_BASIS = 'close_index';
+export const MIN_AMOUNT_CENTS = 100;
+export const MAX_AMOUNT_CENTS = 1_000_000_000;
+export const CAGR_DAY_COUNT = 365.25;
+export const CALMAR_MIN_ABS_DRAWDOWN = 0.0001;
+export const ZERO_VARIANCE_SUMSQ_EPSILON = 1e-24;
+export const CORRELATION_CLAMP_TOLERANCE = 1e-12;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+function normalizeZero(value) {
+    return value === 0 ? 0 : value;
+}
+function basisPointMetricUnavailable(reason) {
+    return { available: false, reason };
+}
+function hundredthsMetricUnavailable(reason) {
+    return { available: false, reason };
+}
+function basisPointMetricAvailable(value) {
+    if (!Number.isFinite(value))
+        return basisPointMetricUnavailable('nonfinite_result');
+    return { available: true, value: normalizeZero(value), displayBasisPoints: displayBasisPoints(value) };
+}
+function hundredthsMetricAvailable(value) {
+    if (!Number.isFinite(value))
+        return hundredthsMetricUnavailable('nonfinite_result');
+    return { available: true, value: normalizeZero(value), displayHundredths: displayHundredths(value) };
+}
+function decimalString(value) {
+    const raw = Math.abs(value).toString();
+    if (!raw.includes('e'))
+        return raw;
+    const [coefficient, exponentText] = raw.split('e');
+    const exponent = Number(exponentText);
+    const [integerPart, fractionPart = ''] = coefficient.split('.');
+    const digits = `${integerPart}${fractionPart}`;
+    const decimalIndex = integerPart.length + exponent;
+    if (decimalIndex <= 0)
+        return `0.${'0'.repeat(Math.abs(decimalIndex))}${digits}`;
+    if (decimalIndex >= digits.length)
+        return `${digits}${'0'.repeat(decimalIndex - digits.length)}`;
+    return `${digits.slice(0, decimalIndex)}.${digits.slice(decimalIndex)}`;
+}
+export function roundHalfAwayFromZero(value, scale = 1) {
+    if (!Number.isFinite(value))
+        throw new Error('cannot round nonfinite value');
+    if (!Number.isSafeInteger(scale) || scale <= 0)
+        throw new Error('scale must be a positive safe integer');
+    const sign = value < 0 ? -1 : 1;
+    const [integerPart, fractionPart = ''] = decimalString(value).split('.');
+    const numerator = BigInt(`${integerPart}${fractionPart}`.replace(/^0+(?=\d)/, '') || '0') * BigInt(scale);
+    const denominator = 10n ** BigInt(fractionPart.length);
+    let scaled = numerator / denominator;
+    if ((numerator % denominator) * 2n >= denominator)
+        scaled += 1n;
+    if (scaled > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new Error('rounded result exceeds safe integer range');
+    const rounded = Number(scaled);
+    return rounded === 0 ? 0 : sign * rounded;
+}
+export function displayCents(usdValue) {
+    return roundHalfAwayFromZero(usdValue, 100);
+}
+export function displayBasisPoints(decimalValue) {
+    return roundHalfAwayFromZero(decimalValue, 10_000);
+}
+export function displayHundredths(ratioValue) {
+    return roundHalfAwayFromZero(ratioValue, 100);
+}
+export function isValidCivilDate(value) {
+    if (typeof value !== 'string' || !DATE_RE.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map(Number);
+    const parsed = new Date(Date.UTC(year, month - 1, day));
+    return (parsed.getUTCFullYear() === year &&
+        parsed.getUTCMonth() === month - 1 &&
+        parsed.getUTCDate() === day);
+}
+export function civilDay(value) {
+    if (!isValidCivilDate(value))
+        throw new Error(`invalid civil date: ${value}`);
+    const [year, month, day] = value.split('-').map(Number);
+    return Math.floor(Date.UTC(year, month - 1, day) / DAY_MS);
+}
+export function firstAnniversary(value) {
+    if (!isValidCivilDate(value))
+        throw new Error(`invalid civil date: ${value}`);
+    const [year, month, day] = value.split('-').map(Number);
+    const shifted = new Date(Date.UTC(year + 1, month - 1, day));
+    if (shifted.getUTCMonth() !== month - 1) {
+        shifted.setUTCDate(0);
+    }
+    return shifted.toISOString().slice(0, 10);
+}
+export function shiftYearsBack(value, years) {
+    if (!isValidCivilDate(value))
+        return value;
+    const [year, month, day] = value.split('-').map(Number);
+    const shifted = new Date(Date.UTC(year - years, month - 1, day));
+    if (shifted.getUTCMonth() !== month - 1) {
+        shifted.setUTCDate(0);
+    }
+    return shifted.toISOString().slice(0, 10);
+}
+export function parseUsdAmountToCents(value) {
+    if (typeof value !== 'string')
+        return { ok: false, reason: 'invalid_amount' };
+    const raw = value.trim().replace(/^\$\s*/, '');
+    const plainAmount = /^(0|[1-9][0-9]*)(\.[0-9]{1,2})?$/;
+    const groupedAmount = /^(0|[1-9][0-9]{0,2}(,[0-9]{3})+)(\.[0-9]{1,2})?$/;
+    if (!plainAmount.test(raw) && !groupedAmount.test(raw)) {
+        return { ok: false, reason: 'invalid_amount' };
+    }
+    const [dollars, cents = ''] = raw.replaceAll(',', '').split('.');
+    const parsed = Number(dollars) * 100 + Number(cents.padEnd(2, '0') || '0');
+    if (!Number.isSafeInteger(parsed) || parsed < MIN_AMOUNT_CENTS || parsed > MAX_AMOUNT_CENTS) {
+        return { ok: false, reason: 'invalid_amount' };
+    }
+    return { ok: true, cents: parsed };
+}
+export const parseAmountToCents = parseUsdAmountToCents;
+function orderedMean(values) {
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function sampleVariance(values) {
+    if (values.length < 2)
+        return null;
+    const mean = orderedMean(values);
+    return values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / (values.length - 1);
+}
+function sampleStddev(values) {
+    const variance = sampleVariance(values);
+    return variance === null ? null : Math.sqrt(variance);
+}
+function simpleReturns(values) {
+    const returns = [];
+    for (let index = 1; index < values.length; index += 1) {
+        const previous = values[index - 1];
+        const current = values[index];
+        if (previous <= 0 || current <= 0)
+            throw new Error('normalized indexes must be positive');
+        returns.push(current / previous - 1);
+    }
+    return returns;
+}
+export function pearsonCorrelation(valuesA, valuesB) {
+    if (valuesA.length !== valuesB.length || valuesA.length < 2) {
+        return hundredthsMetricUnavailable('insufficient_data');
+    }
+    const meanA = orderedMean(valuesA);
+    const meanB = orderedMean(valuesB);
+    let covariance = 0;
+    let sumSqA = 0;
+    let sumSqB = 0;
+    for (let index = 0; index < valuesA.length; index += 1) {
+        const deltaA = valuesA[index] - meanA;
+        const deltaB = valuesB[index] - meanB;
+        covariance += deltaA * deltaB;
+        sumSqA += deltaA * deltaA;
+        sumSqB += deltaB * deltaB;
+    }
+    if (sumSqA <= ZERO_VARIANCE_SUMSQ_EPSILON || sumSqB <= ZERO_VARIANCE_SUMSQ_EPSILON) {
+        return hundredthsMetricUnavailable('zero_variance');
+    }
+    let correlation = covariance / Math.sqrt(sumSqA * sumSqB);
+    if (Math.abs(Math.abs(correlation) - 1) <= CORRELATION_CLAMP_TOLERANCE) {
+        correlation = correlation > 0 ? 1 : -1;
+    }
+    else if (correlation < -1 || correlation > 1) {
+        return hundredthsMetricUnavailable('nonfinite_result');
+    }
+    return hundredthsMetricAvailable(correlation);
+}
+function drawdownStats(values, dates) {
+    if (values.length < 2) {
+        return {
+            maxDrawdown: basisPointMetricUnavailable('insufficient_data'),
+            peakDate: null,
+            troughDate: null,
+            recoveryDate: null,
+            recoveryDays: null,
+            recoveryStatus: 'not_applicable',
+        };
+    }
+    let runningPeak = values[0];
+    let runningPeakAtTrough = values[0];
+    let troughIndex = 0;
+    let maxDrawdown = 0;
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value >= runningPeak)
+            runningPeak = value;
+        const drawdown = value / runningPeak - 1;
+        if (drawdown < maxDrawdown) {
+            maxDrawdown = drawdown;
+            troughIndex = index;
+            runningPeakAtTrough = runningPeak;
+        }
+    }
+    if (maxDrawdown === 0) {
+        return {
+            maxDrawdown: { available: true, value: 0, displayBasisPoints: 0 },
+            peakDate: null,
+            troughDate: null,
+            recoveryDate: null,
+            recoveryDays: null,
+            recoveryStatus: 'not_applicable',
+        };
+    }
+    let peakIndex = 0;
+    for (let index = 0; index <= troughIndex; index += 1) {
+        if (values[index] === runningPeakAtTrough)
+            peakIndex = index;
+    }
+    let recoveryIndex = null;
+    for (let index = troughIndex; index < values.length; index += 1) {
+        if (values[index] >= runningPeakAtTrough) {
+            recoveryIndex = index;
+            break;
+        }
+    }
+    return {
+        maxDrawdown: basisPointMetricAvailable(maxDrawdown),
+        peakDate: dates[peakIndex],
+        troughDate: dates[troughIndex],
+        recoveryDate: recoveryIndex === null ? null : dates[recoveryIndex],
+        recoveryDays: recoveryIndex === null ? null : civilDay(dates[recoveryIndex]) - civilDay(dates[troughIndex]),
+        recoveryStatus: recoveryIndex === null ? 'not_recovered' : 'recovered',
+    };
+}
+function validateAsset(asset) {
+    if (typeof asset.assetKey !== 'string' || !asset.assetKey)
+        return false;
+    if (!SUPPORTED_SERIES_BASES.includes(asset.seriesBasis))
+        return false;
+    if (!Array.isArray(asset.dates) || !Array.isArray(asset.growthIndex) || asset.dates.length !== asset.growthIndex.length) {
+        return false;
+    }
+    if (asset.dates.length === 0)
+        return false;
+    if (typeof asset.annualizationFactor !== 'number' || !Number.isFinite(asset.annualizationFactor) || asset.annualizationFactor <= 0) {
+        return false;
+    }
+    let previous = null;
+    for (let index = 0; index < asset.dates.length; index += 1) {
+        const currentDate = asset.dates[index];
+        const value = asset.growthIndex[index];
+        if (!isValidCivilDate(currentDate))
+            return false;
+        if (previous !== null && currentDate <= previous)
+            return false;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+            return false;
+        previous = currentDate;
+    }
+    return true;
+}
+function checkMethodology(assetA, assetB) {
+    return (assetA.schemaVersion === SUPPORTED_SCHEMA_VERSION &&
+        assetB.schemaVersion === SUPPORTED_SCHEMA_VERSION &&
+        assetA.methodologyVersion === SUPPORTED_METHODOLOGY_VERSION &&
+        assetB.methodologyVersion === SUPPORTED_METHODOLOGY_VERSION &&
+        SUPPORTED_SERIES_BASES.includes(assetA.seriesBasis) &&
+        SUPPORTED_SERIES_BASES.includes(assetB.seriesBasis));
+}
+function dateToIndex(asset) {
+    return new Map(asset.dates.map((currentDate, index) => [currentDate, index]));
+}
+function nativeWindow(asset, effectiveStart, effectiveEnd) {
+    const dates = [];
+    const values = [];
+    for (let index = 0; index < asset.dates.length; index += 1) {
+        const currentDate = asset.dates[index];
+        if (effectiveStart <= currentDate && currentDate <= effectiveEnd) {
+            dates.push(currentDate);
+            values.push(asset.growthIndex[index]);
+        }
+    }
+    return { dates, values };
+}
+function assetMetrics(asset, dates, values, amountCents, elapsedDays) {
+    const amountUsd = amountCents / 100;
+    const growth = values[values.length - 1] / values[0];
+    const endingValueUsd = amountUsd * growth;
+    const endingValueCents = displayCents(endingValueUsd);
+    const profitLossUsd = endingValueUsd - amountUsd;
+    const profitLossCents = endingValueCents - amountCents;
+    const totalReturnValue = growth - 1;
+    const returns = simpleReturns(values);
+    const drawdown = drawdownStats(values, dates);
+    let cagr = basisPointMetricUnavailable('period_too_short');
+    if (elapsedDays >= 30) {
+        const cagrValue = growth ** (CAGR_DAY_COUNT / elapsedDays) - 1;
+        cagr = basisPointMetricAvailable(cagrValue);
+    }
+    let volatility = basisPointMetricUnavailable('insufficient_data');
+    if (returns.length >= 30) {
+        const stddev = sampleStddev(returns);
+        if (stddev !== null) {
+            const volatilityValue = stddev * Math.sqrt(asset.annualizationFactor);
+            volatility = basisPointMetricAvailable(volatilityValue);
+        }
+    }
+    let calmar = hundredthsMetricUnavailable('period_too_short');
+    const firstAnniversaryReached = dates[dates.length - 1] >= firstAnniversary(dates[0]);
+    const drawdownMetric = drawdown.maxDrawdown;
+    if (firstAnniversaryReached && cagr.available && drawdownMetric.available) {
+        const maxDrawdown = drawdownMetric.value;
+        if (Math.abs(maxDrawdown) >= CALMAR_MIN_ABS_DRAWDOWN) {
+            const calmarValue = cagr.value / Math.abs(maxDrawdown);
+            calmar = hundredthsMetricAvailable(calmarValue);
+        }
+        else {
+            calmar = hundredthsMetricUnavailable('zero_drawdown');
+        }
+    }
+    return {
+        endingValueUsd: normalizeZero(endingValueUsd),
+        endingValueCents,
+        profitLossUsd: normalizeZero(profitLossUsd),
+        profitLossCents,
+        totalReturn: basisPointMetricAvailable(totalReturnValue),
+        cagr,
+        volatility,
+        drawdown,
+        calmar,
+        nativeObservationCount: values.length,
+        nativeReturnCount: returns.length,
+        periodOutcome: profitLossCents > 0 ? 'gain' : profitLossCents < 0 ? 'loss' : 'unchanged',
+    };
+}
+function compareDisplayValues(metricA, metricB) {
+    if (!metricA.available || !metricB.available)
+        return 'unavailable';
+    const valueA = metricA.displayBasisPoints;
+    const valueB = metricB.displayBasisPoints;
+    if (valueA === valueB)
+        return 'tie';
+    return valueA > valueB ? 'asset_a' : 'asset_b';
+}
+function compareEndingValue(metricsA, metricsB) {
+    if (metricsA.endingValueCents === metricsB.endingValueCents)
+        return 'tie';
+    return metricsA.endingValueCents > metricsB.endingValueCents ? 'asset_a' : 'asset_b';
+}
+function compareDeeperDrawdown(metricsA, metricsB) {
+    const drawdownA = metricsA.drawdown.maxDrawdown;
+    const drawdownB = metricsB.drawdown.maxDrawdown;
+    if (!drawdownA.available || !drawdownB.available)
+        return 'unavailable';
+    const valueA = drawdownA.displayBasisPoints;
+    const valueB = drawdownB.displayBasisPoints;
+    if (typeof valueA !== 'number' || typeof valueB !== 'number')
+        return 'unavailable';
+    if (valueA === valueB)
+        return 'tie';
+    return valueA < valueB ? 'asset_a' : 'asset_b';
+}
+export function calculateScenario(input) {
+    if (!input || typeof input !== 'object')
+        throw new Error('invalid scenario input');
+    const { assetA, assetB, amountCents, requestedStart, requestedEnd } = input;
+    if (!assetA || typeof assetA !== 'object' || !assetB || typeof assetB !== 'object') {
+        throw new Error('invalid asset artifact');
+    }
+    if (typeof assetA.assetKey !== 'string' ||
+        !assetA.assetKey ||
+        typeof assetB.assetKey !== 'string' ||
+        !assetB.assetKey) {
+        throw new Error('invalid asset artifact');
+    }
+    if (assetA.assetKey === assetB.assetKey)
+        return { status: 'error', reason: 'same_asset' };
+    if (!Number.isSafeInteger(amountCents) || amountCents < MIN_AMOUNT_CENTS || amountCents > MAX_AMOUNT_CENTS) {
+        return { status: 'error', reason: 'invalid_amount' };
+    }
+    if (!isValidCivilDate(requestedStart) || !isValidCivilDate(requestedEnd)) {
+        return { status: 'error', reason: 'invalid_date' };
+    }
+    if (requestedStart > requestedEnd)
+        return { status: 'error', reason: 'start_after_end' };
+    if (!checkMethodology(assetA, assetB))
+        return { status: 'error', reason: 'methodology_mismatch' };
+    if (!validateAsset(assetA) || !validateAsset(assetB))
+        throw new Error('invalid asset artifact');
+    const indexA = dateToIndex(assetA);
+    const indexB = dateToIndex(assetB);
+    const sharedDates = assetA.dates.filter((currentDate) => indexB.has(currentDate));
+    if (!sharedDates.length)
+        return { status: 'error', reason: 'no_overlap' };
+    const requestedSharedDates = sharedDates.filter((currentDate) => requestedStart <= currentDate && currentDate <= requestedEnd);
+    if (!requestedSharedDates.length)
+        return { status: 'error', reason: 'no_overlap' };
+    const effectiveStart = sharedDates.find((currentDate) => currentDate >= requestedStart) || null;
+    const effectiveEnd = [...sharedDates].reverse().find((currentDate) => currentDate <= requestedEnd) || null;
+    if (effectiveStart === null || effectiveEnd === null || effectiveStart >= effectiveEnd) {
+        return { status: 'error', reason: 'insufficient_shared_observations' };
+    }
+    const selectedSharedDates = sharedDates.filter((currentDate) => effectiveStart <= currentDate && currentDate <= effectiveEnd);
+    if (selectedSharedDates.length < 2)
+        return { status: 'error', reason: 'insufficient_shared_observations' };
+    const elapsedDays = civilDay(effectiveEnd) - civilDay(effectiveStart);
+    if (elapsedDays <= 0)
+        return { status: 'error', reason: 'insufficient_shared_observations' };
+    const nativeA = nativeWindow(assetA, effectiveStart, effectiveEnd);
+    const nativeB = nativeWindow(assetB, effectiveStart, effectiveEnd);
+    const sharedValuesA = selectedSharedDates.map((currentDate) => assetA.growthIndex[indexA.get(currentDate)]);
+    const sharedValuesB = selectedSharedDates.map((currentDate) => assetB.growthIndex[indexB.get(currentDate)]);
+    const metricsA = assetMetrics(assetA, nativeA.dates, nativeA.values, amountCents, elapsedDays);
+    const metricsB = assetMetrics(assetB, nativeB.dates, nativeB.values, amountCents, elapsedDays);
+    const sharedReturnsA = simpleReturns(sharedValuesA);
+    const sharedReturnsB = simpleReturns(sharedValuesB);
+    const correlation = sharedReturnsA.length >= 30 && sharedReturnsB.length >= 30
+        ? pearsonCorrelation(sharedReturnsA, sharedReturnsB)
+        : hundredthsMetricUnavailable('insufficient_data');
+    const amountUsd = amountCents / 100;
+    return {
+        status: 'ok',
+        scenario: {
+            methodologyVersion: SUPPORTED_METHODOLOGY_VERSION,
+            methodologyContractHash: METHODOLOGY_HASH,
+            amountCents,
+            requestedStart,
+            requestedEnd,
+            effectiveStart,
+            effectiveEnd,
+            startSnap: effectiveStart === requestedStart ? 'exact' : 'forward',
+            endSnap: effectiveEnd === requestedEnd ? 'exact' : 'backward',
+            elapsedDays,
+            sharedObservationCount: selectedSharedDates.length,
+            assetA: metricsA,
+            assetB: metricsB,
+            pair: {
+                correlation,
+                sharedReturnCount: sharedReturnsA.length,
+            },
+            wealthPath: selectedSharedDates.map((currentDate) => ({
+                date: currentDate,
+                assetAUsd: normalizeZero(amountUsd * assetA.growthIndex[indexA.get(currentDate)] / sharedValuesA[0]),
+                assetBUsd: normalizeZero(amountUsd * assetB.growthIndex[indexB.get(currentDate)] / sharedValuesB[0]),
+            })),
+            endingValueWinner: compareEndingValue(metricsA, metricsB),
+            totalReturnWinner: compareDisplayValues(metricsA.totalReturn, metricsB.totalReturn),
+            deeperDrawdownAsset: compareDeeperDrawdown(metricsA, metricsB),
+        },
+    };
+}

package/lib/methodology.d.ts

@@ -0,0 +1,4 @@
+/** Identifiers for the public, provider-free return-scenario contract. */
+export declare const ARTIFACT_SCHEMA_VERSION: 1;
+export declare const METHODOLOGY_VERSION: "return-scenario-v1.0.0";
+export declare const METHODOLOGY_HASH: "55ef9001eb8795071cfff1e135430d41952aedd8708ba1d767c3453804fd49b0";

package/lib/methodology.js

@@ -0,0 +1,4 @@
+/** Identifiers for the public, provider-free return-scenario contract. */
+export const ARTIFACT_SCHEMA_VERSION = 1;
+export const METHODOLOGY_VERSION = 'return-scenario-v1.0.0';
+export const METHODOLOGY_HASH = '55ef9001eb8795071cfff1e135430d41952aedd8708ba1d767c3453804fd49b0';

package/lib/types.d.ts

@@ -0,0 +1,111 @@
+export type MetricReason = 'insufficient_data' | 'period_too_short' | 'zero_drawdown' | 'zero_variance' | 'nonfinite_result';
+export type ScenarioErrorReason = 'same_asset' | 'invalid_amount' | 'invalid_date' | 'start_after_end' | 'methodology_mismatch' | 'no_overlap' | 'insufficient_shared_observations';
+export type SnapStatus = 'exact' | 'forward' | 'backward';
+export type ComparisonWinner = 'asset_a' | 'asset_b' | 'tie' | 'unavailable';
+export type PeriodOutcome = 'gain' | 'loss' | 'unchanged';
+export type RecoveryStatus = 'recovered' | 'not_recovered' | 'not_applicable';
+export type MetricValue = {
+    available: true;
+    value: number;
+} | {
+    available: false;
+    reason: MetricReason;
+};
+export type BasisPointMetricValue = {
+    available: true;
+    value: number;
+    displayBasisPoints: number;
+} | {
+    available: false;
+    reason: MetricReason;
+};
+export type HundredthsMetricValue = {
+    available: true;
+    value: number;
+    displayHundredths: number;
+} | {
+    available: false;
+    reason: MetricReason;
+};
+/** Caller-owned normalized index data; it intentionally has no provider or product metadata. */
+export type AssetSeriesArtifact = Readonly<{
+    assetKey: string;
+    schemaVersion: 1;
+    methodologyVersion: 'return-scenario-v1.0.0';
+    seriesBasis: 'close_index' | 'adjusted_close_index';
+    annualizationFactor: number;
+    dates: readonly string[];
+    growthIndex: readonly number[];
+}>;
+export type ScenarioInput = Readonly<{
+    assetA: AssetSeriesArtifact;
+    assetB: AssetSeriesArtifact;
+    amountCents: number;
+    requestedStart: string;
+    requestedEnd: string;
+}>;
+export type DrawdownResult = Readonly<{
+    maxDrawdown: BasisPointMetricValue;
+    peakDate: string | null;
+    troughDate: string | null;
+    recoveryDate: string | null;
+    recoveryDays: number | null;
+    recoveryStatus: RecoveryStatus;
+}>;
+export type AssetScenarioMetrics = Readonly<{
+    endingValueUsd: number;
+    endingValueCents: number;
+    profitLossUsd: number;
+    profitLossCents: number;
+    totalReturn: BasisPointMetricValue;
+    cagr: BasisPointMetricValue;
+    volatility: BasisPointMetricValue;
+    drawdown: DrawdownResult;
+    calmar: HundredthsMetricValue;
+    nativeObservationCount: number;
+    nativeReturnCount: number;
+    periodOutcome: PeriodOutcome;
+}>;
+export type WealthPathPoint = Readonly<{
+    date: string;
+    assetAUsd: number;
+    assetBUsd: number;
+}>;
+export type PairMetrics = Readonly<{
+    correlation: HundredthsMetricValue;
+    sharedReturnCount: number;
+}>;
+export type ScenarioSuccess = Readonly<{
+    methodologyVersion: 'return-scenario-v1.0.0';
+    methodologyContractHash: string;
+    amountCents: number;
+    requestedStart: string;
+    requestedEnd: string;
+    effectiveStart: string;
+    effectiveEnd: string;
+    startSnap: 'exact' | 'forward';
+    endSnap: 'exact' | 'backward';
+    elapsedDays: number;
+    sharedObservationCount: number;
+    assetA: AssetScenarioMetrics;
+    assetB: AssetScenarioMetrics;
+    pair: PairMetrics;
+    wealthPath: readonly WealthPathPoint[];
+    endingValueWinner: ComparisonWinner;
+    totalReturnWinner: ComparisonWinner;
+    deeperDrawdownAsset: ComparisonWinner;
+}>;
+export type ScenarioResult = {
+    status: 'error';
+    reason: ScenarioErrorReason;
+} | {
+    status: 'ok';
+    scenario: ScenarioSuccess;
+};
+export type AmountParseResult = {
+    ok: true;
+    cents: number;
+} | {
+    ok: false;
+    reason: 'invalid_amount';
+};

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/methodology/return-scenario-v1.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": 1,
+  "methodologyVersion": "return-scenario-v1.0.0",
+  "constants": {
+    "amountCentsMin": 100,
+    "amountCentsMax": 1000000000,
+    "cagrDayCount": 365.25,
+    "calmarMinAbsDrawdown": 0.0001,
+    "defaultAnnualizationFactor": 252
+  },
+  "dateAlignment": {
+    "civilDatePattern": "YYYY-MM-DD",
+    "timezone": "utc_civil_day_ordinals",
+    "startSnap": "first_shared_on_or_after_request",
+    "endSnap": "last_shared_on_or_before_request",
+    "sharedMetrics": "shared_observation_dates_only",
+    "nativeMetrics": "per_asset_native_observations_between_shared_effective_boundaries"
+  },
+  "formulas": {
+    "totalReturn": "index_end/index_start-1",
+    "endingValueUsd": "amount_usd*index_end/index_start",
+    "cagr": "pow(index_end/index_start,365.25/elapsed_calendar_days)-1",
+    "realizedVolatility": "sample_stddev_native_simple_returns_ddof_1*sqrt(annualization_factor)",
+    "drawdown": "index_t/running_max(index_0_to_t)-1",
+    "calmar": "cagr/abs(max_drawdown)",
+    "correlation": "pearson_aligned_shared_simple_returns_ordered_centered_sums"
+  },
+  "minimumEvidence": {
+    "totalReturnSharedPrices": 2,
+    "cagrElapsedCalendarDays": 30,
+    "volatilityNativeReturns": 30,
+    "drawdownNativePrices": 2,
+    "correlationSharedReturns": 30,
+    "calmarFirstAnniversaryRequired": true
+  },
+  "rounding": {
+    "money": "integer_cents_half_away_from_zero",
+    "percent": "integer_basis_points_half_away_from_zero",
+    "ratio": "integer_hundredths_half_away_from_zero",
+    "negativeZero": "normalize_to_positive_zero"
+  }
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "return-scenario-engine",
+  "version": "0.1.0",
+  "description": "Portable historical return scenario calculations for normalized indexes.",
+  "type": "module",
+  "exports": { ".": { "types": "./lib/index.d.ts", "import": "./lib/index.js" } },
+  "types": "./lib/index.d.ts",
+  "files": ["lib", "methodology", "LICENSE", "NOTICE", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": { "build": "tsc --project tsconfig.json", "test": "npm run build && bash test/run-conformance.sh", "prepack": "npm run build" },
+  "repository": { "type": "git", "url": "git+https://github.com/sidko/return-scenario-engine.git" },
+  "bugs": { "url": "https://github.com/sidko/return-scenario-engine/issues" },
+  "homepage": "https://github.com/sidko/return-scenario-engine#readme",
+  "license": "Apache-2.0",
+  "devDependencies": { "@types/node": "24.3.1", "typescript": "5.9.3" }
+}