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:

npm run build

Run modes:

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:

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.