open-index/open-npm huggingface dataset:
npm package: @samsmith2121/synthetic-leverage-engine
Description: Engine and tests for a synthetic leverage simulator
Latest version: 0.1.2

# synthetic-leverage-engine
Engine and tests for a synthetic leverage simulator

## Handoff note for UI builders
- The engine is the single source of truth for financial logic.
- UI integrations should import from `src/public-api.ts` (or package root exports that re-export it) and call engine functions only.
- UI integrations should avoid importing low-level internal engine files directly unless the public engine surface is intentionally extended first.
- Do not duplicate backtest, Monte Carlo, benchmark, validation, metrics, diagnostics, or cost logic in UI code.
- Cash yield behavior is explicit and configurable (`cashYieldDaily`); zero-yield is a supported/default mode, not the only mode.
- If UI needs new output shapes, extend the engine first and keep locked accounting order unchanged.

The repository now includes a deterministic research workflow on top of the trusted fixed-path engine:

- Strategy diagnostics explaining exposure, transitions, cost mix, drawdown profile, and benchmark-relative behavior (`buildStrategyDiagnostics` via run summaries)
- Sensitivity analysis utilities:
  - one-way sensitivity (`runOneWaySensitivity`)
  - two-way sensitivity with grid-friendly cells (`runTwoWaySensitivity`)
  - deterministic ranking helper (`rankStrategyRuns`)
- Structured analysis warnings (`AnalysisWarning`) surfaced directly in strategy/sweep/scenario outputs
- Rule-based research summary builders (`buildResearchSummaries`) for decision-ready but descriptive recommendations
- Export-ready flat rows for downstream CSV pipelines:
  - backtest summary rows
  - strategy comparison rows
  - parameter sweep rows
  - scenario rows
  - one-way/two-way sensitivity rows
  - diagnostics rows

Core files:
- `src/analysis.ts`
- `src/reporting.ts`
- `src/analysis-cli.ts` (minimal script entry point)

### Minimal CLI usage

Build first:

```bash
npm run build
```

Run modes:

```bash
node dist/src/analysis-cli.js comparison <days.json> <config.json> <payload.json>
node dist/src/analysis-cli.js sweep <days.json> <config.json> <payload.json>
node dist/src/analysis-cli.js scenario <days.json> <config.json> <payload.json>
node dist/src/analysis-cli.js backtest <days.json> <config.json> [payload.json]
```

Payload JSON provides typed strategy variants, sweep grids, or scenario definitions.

## Model validation harness

Run the automated model validation suite:

```bash
npm run validate:model
```

The harness prints a human-readable PASS/FAIL/WARN report for each validation case, including actual values and expected conditions. It also prints a summary with total passed, total failed, and warnings. The command exits non-zero when any core validation fails.