kiploks · dedalik · Apr 14, 2026 · Apr 14, 2026
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.2.0
+0.3.0
diff --git a/docs/MONTE_CARLO_SIMULATION_IMPLEMENTATION.md b/docs/MONTE_CARLO_SIMULATION_IMPLEMENTATION.md
@@ -11,4 +11,6 @@ Public Open Core documentation for Monte-related features in `@kiploks/engine-co
 
 **Window bootstrap** (`monteCarloValidation`) is computed inside the professional WFA pipeline when applicable. For precomputed WFA, `AnalyzeConfig.monteCarloBootstrapN` sets bootstrap iteration count (see contracts).
 
+**Call-site options:** `runProfessionalWfa` / `buildProfessionalWfa` accept **`monteCarloMode`** (`legacy` \| `auto` \| `new_only`) and **`enablePathMc`** to control when path-based Monte Carlo is eligible versus per-window bootstrap (see [**WFA_PROFESSIONAL.md**](./WFA_PROFESSIONAL.md) §5 and the option types in `@kiploks/engine-contracts`). Host applications map their own configuration (env flags, feature toggles, remote config) to these fields; that wiring is not part of the published engine packages.
+
 **Example:** [`examples/monte-carlo-example.md`](examples/monte-carlo-example.md). Golden regression fixture: [`examples/monte-carlo-seed42.json`](examples/monte-carlo-seed42.json).
diff --git a/docs/WFA_PROFESSIONAL.md b/docs/WFA_PROFESSIONAL.md
@@ -107,6 +107,8 @@ Key fields:
 
 **What it does not do:** No path-dependent simulation (no synthetic full equity curves drawn step-by-step, no shock model over returns beyond window resampling, no strategy-path Monte Carlo).
 
+**`monteCarloMode` / `enablePathMc` (optional):** In addition to window bootstrap above, the professional pipeline may emit **`method: "path_mc_v1"`** (path simulation from stored equity curves) or **`method: "unavailable"`** with a **`reasonCode`**, depending on mode, `enablePathMc`, and data eligibility. See [**MONTE_CARLO_PATH.md**](./MONTE_CARLO_PATH.md) and `wfaProfessional.ts` / `wfaProfessional.test.ts` for selection rules. When path MC cannot run, institutional grade aggregation still needs a bounded MC signal: the engine applies a **neutral Monte Carlo contribution** and records **`mc_unavailable_neutral_score_50`** plus **`mc_unavailable_reason:*`** entries in **`professionalMeta.approximationsUsed`**.
+
 Key fields:
 
 - `actualMeanReturn: number`

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@kiploks/engine-monorepo",
   "private": true,
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Kiploks Open Core engine - npm packages: contracts, core, adapters, CLI, test vectors. This folder is the git root of the published engine repository.",
   "keywords": [
     "algorithmic-trading",

diff --git a/packages/adapters/package.json b/packages/adapters/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kiploks/engine-adapters",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -12,6 +12,22 @@
   "bugs": {
     "url": "https://github.com/kiploks/engine/issues"
   },
+  "keywords": [
+    "algorithmic-trading",
+    "walk-forward-analysis",
+    "wfa",
+    "backtest",
+    "backtest-validation",
+    "trading-strategy",
+    "quantitative-finance",
+    "typescript",
+    "kiploks",
+    "open-core",
+    "risk-metrics",
+    "reproducible-analytics",
+    "out-of-sample",
+    "trading-research"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -29,7 +45,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@kiploks/engine-contracts": "0.2.0"
+    "@kiploks/engine-contracts": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kiploks/engine-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -12,6 +12,22 @@
   "bugs": {
     "url": "https://github.com/kiploks/engine/issues"
   },
+  "keywords": [
+    "algorithmic-trading",
+    "walk-forward-analysis",
+    "wfa",
+    "backtest",
+    "backtest-validation",
+    "trading-strategy",
+    "quantitative-finance",
+    "typescript",
+    "kiploks",
+    "open-core",
+    "risk-metrics",
+    "reproducible-analytics",
+    "out-of-sample",
+    "trading-research"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -33,9 +49,9 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@kiploks/engine-contracts": "0.2.0",
-    "@kiploks/engine-core": "0.2.0",
-    "@kiploks/engine-adapters": "0.2.0"
+    "@kiploks/engine-contracts": "0.3.0",
+    "@kiploks/engine-core": "0.3.0",
+    "@kiploks/engine-adapters": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

diff --git a/packages/contracts/package.json b/packages/contracts/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@kiploks/engine-contracts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -12,6 +12,22 @@
   "bugs": {
     "url": "https://github.com/kiploks/engine/issues"
   },
+  "keywords": [
+    "algorithmic-trading",
+    "walk-forward-analysis",
+    "wfa",
+    "backtest",
+    "backtest-validation",
+    "trading-strategy",
+    "quantitative-finance",
+    "typescript",
+    "kiploks",
+    "open-core",
+    "risk-metrics",
+    "reproducible-analytics",
+    "out-of-sample",
+    "trading-research"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {

diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
@@ -3,7 +3,7 @@
  * Keep these exports stable across minor releases.
  */
 
-export const ENGINE_VERSION = "0.2.0";
+export const ENGINE_VERSION = "0.3.0";
 export const ANALYSIS_ENGINE_VERSION = "3.0";
 export const FORMULA_VERSION = "2.2.0";
 export const RISK_ANALYSIS_VERSION = 1;
@@ -162,6 +162,13 @@ export type WfaProfessionalInput = {
 
 export type WfaProfessionalOptions = {
   seed?: number;
+  permutationN?: number;
+  bootstrapN?: number;
+  monteCarloMode?: "legacy" | "auto" | "new_only";
+  enablePathMc?: boolean;
+  pathSimulations?: number;
+  maxEquityPoints?: number;
+  cpuBudgetMs?: number;
 };
 
 export type {
@@ -186,6 +193,11 @@ export type {
   RobustnessScoreTextPayload,
   RobustnessScore,
   WalkForwardAnalysisTextPayload,
+  ProfessionalMonteCarloMethod,
+  ProfessionalMonteCarloReasonCode,
+  ProfessionalMonteCarloValidation,
+  ProfessionalWfa,
+  ProfessionalMeta,
   WalkForwardAnalysis,
   TestResultData,
 } from "./testResultData";
diff --git a/packages/contracts/src/testResultData.ts b/packages/contracts/src/testResultData.ts
@@ -40,6 +40,61 @@ export interface WalkForwardAnalysisTextPayload {
   verdictExplanation?: string;
 }
 
+export type ProfessionalMonteCarloMethod =
+  | "path_mc_v1"
+  | "window_iid_bootstrap"
+  | "unavailable"
+  | "window_iid_bootstrap_legacy_snapshot";
+
+export type ProfessionalMonteCarloReasonCode =
+  | "insufficient_windows"
+  | "missing_equity_curve"
+  | "insufficient_curve_points"
+  | "insufficient_curve_span"
+  | "flat_equity"
+  | "cpu_budget_exceeded";
+
+export interface ProfessionalMonteCarloValidation {
+  method?: ProfessionalMonteCarloMethod;
+  version?: string;
+  iterations?: number;
+  seed?: number;
+  reasonCode?: ProfessionalMonteCarloReasonCode;
+  warnings?: string[];
+  actualMeanReturn?: number;
+  confidenceInterval95?: [number, number];
+  confidenceInterval68?: [number, number];
+  probabilityPositive?: number;
+  verdict?: "CONFIDENT" | "PROBABLE" | "UNCERTAIN" | "DOUBTFUL";
+}
+
+export interface ProfessionalWfa {
+  equityCurveAnalysis?: unknown;
+  wfeAdvanced?: unknown;
+  parameterStability?: unknown;
+  regimeAnalysis?: unknown;
+  monteCarloValidation?: ProfessionalMonteCarloValidation;
+  stressTest?: unknown;
+  institutionalGrade?: string;
+  institutionalGradeOverride?: unknown;
+  institutionalGradeOverrideReason?: string;
+  recommendation?: string;
+}
+
+export interface ProfessionalMeta {
+  version: string;
+  engineFormulaVersion?: string;
+  inputsSummary: {
+    periodCount: number;
+    hasPerformanceTransfer: boolean;
+    hasValidationMaxDD: boolean;
+    curvePointCount?: number;
+    monteCarloBootstrapIterations?: number;
+  };
+  guardsTriggered: string[];
+  approximationsUsed: string[];
+}
+
 export interface WalkForwardAnalysis {
   performanceTransfer: { windows: unknown[] };
   wfe?: number;
@@ -59,8 +114,8 @@ export interface WalkForwardAnalysis {
   isDisabled?: boolean;
   textPayload?: WalkForwardAnalysisTextPayload;
   /** Core can enrich these fields with professional block structures. */
-  professional?: unknown;
-  professionalMeta?: unknown;
+  professional?: ProfessionalWfa;
+  professionalMeta?: ProfessionalMeta;
 }
 
 export interface TestResultData {
Original file line number	Diff line number	Diff line change
Expand Up		@@ -11,4 +11,6 @@ Public Open Core documentation for Monte-related features in `@kiploks/engine-co

		Window bootstrap (`monteCarloValidation`) is computed inside the professional WFA pipeline when applicable. For precomputed WFA, `AnalyzeConfig.monteCarloBootstrapN` sets bootstrap iteration count (see contracts).

		Call-site options: `runProfessionalWfa` / `buildProfessionalWfa` accept `monteCarloMode` (`legacy` \\| `auto` \\| `new_only`) and `enablePathMc` to control when path-based Monte Carlo is eligible versus per-window bootstrap (see [WFA_PROFESSIONAL.md](./WFA_PROFESSIONAL.md) §5 and the option types in `@kiploks/engine-contracts`). Host applications map their own configuration (env flags, feature toggles, remote config) to these fields; that wiring is not part of the published engine packages.

		Example: [`examples/monte-carlo-example.md`](examples/monte-carlo-example.md). Golden regression fixture: [`examples/monte-carlo-seed42.json`](examples/monte-carlo-seed42.json).