Release v0.3.0-alpha.30: defensive samples validation in bridge

Bug #31 surfaced by the round-3 input-validation probe. The MCP tool
layer's Pydantic validation rejects samples<1 cleanly, but direct
callers (integration tests, automation scripts, future Python
clients) bypassed that. samples=-1 reached the XLL which threw an
opaque C++ exception (OLE error 0xe06d7363), surfacing to the user
as "Application.Run failed" — useless.

Fix: defensive sanity check at the bridge boundary. samples >= 1 is
enforced and a 10M soft cap rejects clearly rather than letting
MRService.dll thrash on absurd inputs.

Round 3 also verified (no fixes needed):
- MCP tool envelope shapes are correct per the alpha.17 sweep
- All 40 tool descriptions have the ModelRisk: brand prefix
- 9 distribution families round-trip through insert_distribution
- MCP resources (5 modelrisk:// URIs) registered and readable
- 50K-iteration sim completes in 18.4s wall-clock
- End-to-end convert workflow on noMR produces real randomness

404 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vosesoft

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to ModelRisk MCP. Follows [Keep a Changelog](https://keepach
 
 ## [Unreleased]
 
+## [0.3.0-alpha.30] — 2026-05-22
+
+### Fixed
+
+- **Bug #31 — `samples<=0` passed to `bridge.run_simulation` reached the XLL and triggered an opaque C++ exception** (`OLE error 0xe06d7363`). The MCP tool layer's Pydantic validation enforces `ge=1`, but direct callers (integration tests, automation scripts, future Python clients) bypassed that. Surfaced by the round-3 input-validation probe. Fix: defensive sanity check at the bridge boundary (`samples >= 1` and a 10M soft cap) so every code path produces a clear actionable error before invoking ModelRisk's XLL. The message names the offending value and explains why we're rejecting it.
+
+### Verified end-to-end (no fixes needed)
+
+Round 3 confirmed:
+- **MCP tool envelope shapes**: all `list_*` and `find_*` tools return the alpha.17 `{noun: [...], count: N}` envelope correctly. Brand prefix on all 40 tool descriptions.
+- **Distribution catalogue breadth**: 9 of 11 sampled families (Lognormal, Uniform, Triangle, Beta, Gamma, Weibull, Poisson, Binomial, Bernoulli) round-trip through `insert_distribution`. The other two failures were test-script errors (`VoseExpon`'s param is `beta` not `mean`; the discrete uniform is `VoseDiscreteU`, not `VoseDiscreteUniform`).
+- **MCP resources**: 5 resources registered (`modelrisk://audit-rules`, `/distributions`, `/functions`, `/methodology`, `/workbook/current`) and readable.
+- **50K-iteration stress**: simulation completes in 18.4s wall-clock; all 50K samples readable in 0.13s.
+- **End-to-end convert workflow** (separate run): non-MR workbook → `discover_inputs` → `propose_distributions_for_inputs` → `replace_constant_with_distribution` → `wrap_with_output` → `run_simulation` → `get_simulation_results` → `build_executive_report`. Produced real randomness (mean $34.9M, stdev $537) on a fully-converted noMR model.
+
+### Tests
+
+404 unit tests pass.
+
 ## [0.3.0-alpha.29] — 2026-05-22
 
 ### Polished

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelrisk-mcp"
-version = "0.3.0a29"
+version = "0.3.0a30"
 description = "Open MCP server bridging Anthropic Claude (and any MCP-compatible client) with the ModelRisk Excel add-in."
 readme = "README.md"
 requires-python = ">=3.11"

server.json

@@ -3,12 +3,12 @@
   "name": "io.github.vosesoftware/modelrisk-mcp",
   "title": "ModelRisk",
   "description": "Read, build, fit, and run Monte Carlo risk models in Excel through Vose Software's ModelRisk.",
-  "version": "0.3.0a29",
+  "version": "0.3.0a30",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "modelrisk-mcp",
-      "version": "0.3.0a29",
+      "version": "0.3.0a30",
       "transport": {
         "type": "stdio"
       }

src/modelrisk_mcp/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.0a29"
+__version__ = "0.3.0a30"

src/modelrisk_mcp/bridge/simulation.py

@@ -165,6 +165,16 @@ def run_simulation(
         The call blocks until the simulation completes — that's how
         `VoseStartSimulCustom12` is implemented (synchronous Application.Run).
 
+        Bug #31 (alpha.30): defensive sanity check on `samples`.
+        When a non-MCP caller (a direct script, an integration test,
+        future Python clients) passes `samples <= 0`, the value used
+        to flow straight through to the XLL which would throw a
+        C++ exception (OLE error 0xe06d7363). The user saw
+        "Application.Run failed" — opaque. The MCP tool layer's
+        Pydantic field validates `ge=1` but the bridge had no such
+        guard. Adding it here ensures every caller path produces a
+        clear message before hitting the XLL.
+
         `output_names`, when supplied, is threaded into the XLL command's
         options payload as `[CntNames]:N` + `[name0]:...` etc. The
         original C++ header comment claims "empty → all outputs" but
@@ -180,6 +190,22 @@ def run_simulation(
         Raises SimulationFailedError if the file doesn't appear after
         the save call returns.
         """
+        if samples < 1:
+            raise SimulationFailedError(
+                f"samples must be >= 1; got {samples}. ModelRisk's "
+                f"XLL command would throw an opaque C++ exception "
+                f"otherwise."
+            )
+        if samples > 10_000_000:
+            # Soft cap: nothing in the bridge enforces this, but
+            # production users rarely want more than a few million
+            # iterations and the .vmrs file gets huge. Reject with
+            # a clear message rather than letting MRService thrash.
+            raise SimulationFailedError(
+                f"samples={samples} exceeds the 10M soft cap. "
+                f"If you genuinely need more, run multiple sims and "
+                f"aggregate."
+            )
         wb_info = self._resolve_workbook(workbook_name)
         opts = SimulationOptions(
             samples=samples,

tests/unit/test_server_boot.py

@@ -5,7 +5,7 @@
 
 
 def test_version_is_set() -> None:
-    assert __version__ == "0.3.0a29"
+    assert __version__ == "0.3.0a30"
 
 
 def test_server_name() -> None: