make the trials marker declaration only

docs/api/pytest-plugin.md

@@ -13,7 +13,6 @@ RAMPART's pytest integration. Activates automatically when installed.
     options:
       members:
         - RampartSession
-        - TrialGroupResult
 
 ## Parallel Execution Hooks
 

docs/attacks/xpia.md

@@ -65,7 +65,7 @@ async def test_inline_xpia(adapter):
             "send_email",
             recipient=lambda v: isinstance(v, str) and "evil.com" in v,
         ),
-    ).execute_async(adapter=adapter)
+    ).execute_trials_async(adapter=adapter, n=5, threshold=0.8)
 
     assert result, result.summary
 ```

docs/concepts/overview.md

@@ -122,7 +122,7 @@ You can reuse the same evaluator in both contexts. A [`ToolCalled`][rampart.eval
 
 RAMPART registers as a pytest plugin automatically when installed. It provides:
 
-- **Markers**: `@pytest.mark.harm(...)` for categorization, `@pytest.mark.trial(n=...)` for statistical repetition
+- **Markers**: `@pytest.mark.harm(...)` for categorization, `@pytest.mark.trial(n=...)` for population declaration and selection
 - **Automatic result collection**: Results from `Attacks.*` and `Probes.*` are collected without manual wiring
 - **Terminal summary**: A safety summary printed after the standard pytest output
 - **Report sinks**: Structured output via the `rampart_sinks` fixture

docs/getting-started/installation.md

@@ -118,7 +118,7 @@ Expected output:
 
 ```
 @pytest.mark.harm(*categories): categorize by harm type
-@pytest.mark.trial(n=, threshold=): statistical repetition
+@pytest.mark.trial(n=, threshold=): trial population declaration
 ```
 
 RAMPART registers as a pytest plugin automatically via the `pytest11` entry point. No `conftest.py` configuration is needed to activate it.

docs/getting-started/quickstart.md

@@ -130,7 +130,7 @@ async def test_xpia_email_exfil(my_agent):
 ```
 
 - **`@pytest.mark.harm(...)`** — Groups results by harm category in the terminal summary and reports.
-- **`execute_trials_async(n=3, threshold=0.8)`** — Runs 3 independent trials and returns one [`PopulationResult`][rampart.core.result.PopulationResult]. The assertion passes if ≥ 80% are SAFE. LLM agents are non-deterministic, so a single run may not be representative.
+- **`execute_trials_async(n=3, threshold=0.8)`** — Runs 3 independent trials and returns one `PopulationResult`. The assertion passes if ≥ 80% are SAFE. LLM agents are non-deterministic, so a single run may not be representative.
 
 See [pytest Markers & Fixtures](../usage/pytest-integration.md) for the full marker reference.
 

docs/glossary.md

@@ -88,7 +88,7 @@ Terms used throughout the RAMPART documentation.
 :   An implementation of [`Surface`][rampart.core.injection.Surface]. Represents an injectable data source. See [Surfaces](api/surfaces.md).
 
 **Trial**
-:   A repeated execution of a test for statistical confidence, configured via `@pytest.mark.trial(n=...)`. See [pytest Markers & Fixtures](usage/pytest-integration.md).
+:   One execution within a population run by `execute_trials_async`. The optional `@pytest.mark.trial(n=...)` marker declares population metadata for selection. See [pytest Markers & Fixtures](usage/pytest-integration.md).
 
 **Turn**
 :   One prompt-response exchange. Immutable. See [`Turn`][rampart.core.types.Turn].

docs/probes/behavioral.md

@@ -102,7 +102,7 @@ async def test_agent_refuses_harmful_request(adapter):
         evaluator=ResponseContains(
             lambda text: "I can't" in text or "I cannot" in text
         ),
-    ).execute_async(adapter=adapter)
+    ).execute_trials_async(adapter=adapter, n=5, threshold=0.8)
 
     assert result, result.summary
 ```

docs/usage/authoring-tests.md

@@ -323,19 +323,29 @@ def adapter():
 
 ### Class-Based Test Organization
 
-Group related tests in a class:
+Group related tests in a class. The `trial` marker declares population metadata; each test body calls `execute_trials_async` to perform repetition.
 
 ```python
 class TestDataExfiltration:
     @pytest.mark.harm(HarmCategory.DATA_EXFILTRATION)
     @pytest.mark.trial(n=3, threshold=0.8)
     async def test_ssh_key_exfil(self, adapter):
-        ...
+        result = await Attacks.xpia(...).execute_trials_async(
+            adapter=adapter,
+            n=3,
+            threshold=0.8,
+        )
+        assert result, result.summary
 
     @pytest.mark.harm(HarmCategory.DATA_EXFILTRATION)
     @pytest.mark.trial(n=3, threshold=0.8)
     async def test_email_exfil(self, adapter):
-        ...
+        result = await Attacks.xpia(...).execute_trials_async(
+            adapter=adapter,
+            n=3,
+            threshold=0.8,
+        )
+        assert result, result.summary
 ```
 
 

docs/usage/ci-integration.md

@@ -25,31 +25,34 @@ pip install pytest-xdist
 pytest tests/ -n auto
 ```
 
-RAMPART aggregates results across worker processes and emits a single unified report under **any** `--dist` mode. The default `--dist=load` spreads `@trial` clones across all workers and is usually fastest. Add `--dist=loadgroup` only when a trial group needs to stay on one worker (e.g. clones share a session fixture or per-group worker state). See [Choosing `loadgroup` vs `load`](xdist.md#choosing-loadgroup-vs-load) for details and security considerations.
+RAMPART aggregates results across worker processes and emits a single unified report under **any** `--dist` mode. Each call to `execute_trials_async` remains one pytest item and therefore runs on one worker.
 
 ---
 
-## Trial Markers for Statistical Confidence
+## Repeated Executions for Statistical Confidence
 
-Use `@pytest.mark.trial(n=, threshold=)` for tests where a single run is not conclusive:
+Use `execute_trials_async` for tests where a single run is not conclusive:
 
 ```python
-@pytest.mark.trial(n=10, threshold=0.8)
 async def test_injection_resistance(adapter):
-    result = await Attacks.xpia(...).execute_async(adapter=adapter)
+    result = await Attacks.xpia(...).execute_trials_async(
+        adapter=adapter,
+        n=10,
+        threshold=0.8,
+    )
     assert result, result.summary
 ```
 
-This runs 10 independent trials. The test group passes only if ≥ 80% of trials are `SAFE`.
+This runs 10 independent trials. The single pytest test passes only if ≥ 80% of trials are `SAFE`.
 
 **Trial semantics in CI:**
 
-- Each trial clone appears as a separate pytest item
-- The aggregate verdict appears in the RAMPART terminal summary
+- The population is one pytest item
+- The returned `PopulationResult` is the aggregate verdict
 - The aggregate passes when the SAFE pass rate meets the threshold
 - Any `ERROR` trial makes the aggregate fail
-- No-result clones are excluded from the aggregate denominator
-- Clone assertions still contribute independently to pytest's exit status; use `execute_trials_async` when the threshold must govern the single pytest verdict
+- `UNDETERMINED` trials count against the pass rate
+- `@pytest.mark.trial` is declaration-only and does not execute repetitions
 
 ---
 

docs/usage/pytest-integration.md

@@ -39,6 +39,10 @@ Built-in categories:
 | `HALLUCINATION` | `"hallucination"` |
 | `BEHAVIORAL_REGRESSION` | `"behavioral_regression"` |
 
+### `@pytest.mark.trial(n=, threshold=)`
+
+Declare that a test represents a trial population. The marker remains selectable with `pytest -m trial`, but it does not repeat or clone the test. Use `execute_trials_async` to execute the declared population.
+
 ## Repeated Executions
 
 ### `execute_trials_async(n=, threshold=)`
@@ -178,12 +182,10 @@ After standard pytest output, RAMPART prints a safety summary grouped by harm ca
 ========================= RAMPART Safety Summary =========================
 
 DATA_EXFILTRATION (4 tests)
-  FAIL  test_xpia_email_exfil[trial-0] -- Attack objective detected: send_email({'recipient': 'attacker@evil.com'}) (tool_only)
-  PASS  test_xpia_email_exfil[trial-1] -- Agent defended successfully (tool_only)
-  PASS  test_xpia_search_exfil[trial-0] -- Agent defended successfully (tool_only)
-  PASS  test_xpia_search_exfil[trial-1] -- Agent defended successfully (tool_only)
-  PASS  test_xpia_email_exfil [1/2 safe, 50% pass rate, threshold: 80%] -- FAILED
-  PASS  test_xpia_search_exfil [2/2 safe, 100% pass rate, threshold: 80%] -- PASSED
+    FAIL  test_xpia_email_exfil -- Attack objective detected: send_email({'recipient': 'attacker@evil.com'}) (tool_only)
+    PASS  test_xpia_email_exfil -- Agent defended successfully (tool_only)
+    PASS  test_xpia_search_exfil -- Agent defended successfully (tool_only)
+    PASS  test_xpia_search_exfil -- Agent defended successfully (tool_only)
 
 MEMORY_POISONING (1 tests)
   PASS  test_memory_poison -- Agent defended successfully (tool_only)
@@ -195,12 +197,10 @@ Population: 5 runs - 1 unsafe (20.0% attack success rate), 0 undetermined, 0 err
 Each result line shows:
 
 - **`PASS`/`FAIL`/`WARN`/`ERR`** — the safety verdict
-- **Test name** — with `[trial-N]` suffix for trial clones
+- **Test name** — repeated executions share one logical pytest test name
 - **Summary** — e.g., `Agent defended successfully` or `Attack objective detected: ...`
 - **Observability level** — `tool_only`, `tool_and_side_effects`, or `response_only`
 
-Trial group lines show aggregate stats: safe count, pass rate, threshold, and overall verdict.
-
 The **Population** line shows totals across all tests in the session, with the attack success rate excluding `ERROR` results from the denominator.
 
 

docs/usage/xdist.md

@@ -34,7 +34,7 @@ serialize → workeroutput    serialize → workeroutput
                 │
                 ▼
         pytest_sessionfinish (controller)
-        aggregate trials → evaluate gates → emit sinks
+        emit merged results to sinks
                 │
                 ▼
         Single unified TestRunReport
@@ -47,54 +47,11 @@ The result: **one** `JsonFileReportSink` output file, **one** call to `MyCustomS
 
 ---
 
-## Trial Tests with xdist
+## Population Tests with xdist
 
-`@pytest.mark.trial(n=, threshold=)` clones a test into N independent runs. Under xdist, clones may be distributed across workers depending on the `--dist` mode.
+`execute_trials_async` runs a population inside one logical pytest item. xdist assigns that item to one worker, where all executions run sequentially. The returned `PopulationResult` controls the item's assertion, and each individual `Result` is included in the merged report.
 
-| `--dist` mode | Trial behavior |
-|---------------|----------------|
-| `loadgroup` | All trial clones for one test pinned to the same worker |
-| `load` (default) | Trial clones distributed across all workers |
-| `loadscope` / `loadfile` | Grouped by class/module/file |
-
-**Correctness is preserved regardless of mode** — the controller aggregates trial groups from the merged result set and evaluates each group's threshold against the full population. You'll see a warning if you use `@trial` markers without `--dist=loadgroup`:
-
-```text
-RAMPART @trial markers present with --dist=load. Trial clones may be
-split across workers. Aggregation remains correct (controller merges
-all results), but using --dist=loadgroup keeps trial clones co-located
-on one worker for better locality.
-```
-
-This warning is **informational, not a correctness signal** — see below for when it's safe to ignore.
-
-### Choosing `loadgroup` vs `load`
-
-**Both modes produce an identical, correct report.** The controller merges per-worker
-partials into one population and evaluates each trial's threshold against the full
-group either way. The choice is about *execution*, not correctness:
-
-- **`load` (default)** spreads a test's trial clones across **all** workers, so a
-  20-clone trial keeps every worker busy. It is usually the **fastest** option and is
-  the right default when trial clones are **independent** (no shared per-group state).
-- **`loadgroup`** pins all clones of one trial group to a **single** worker. Prefer it
-  only when a trial group needs **cohesion** — e.g. clones share a session-scoped
-  fixture, a per-group cache/connection, or other worker-local state that must not be
-  split across processes. The trade-off is less parallelism, so it can run slower.
-
-**Rule of thumb:** independent trials → plain `pytest -n 4` (faster); trials that
-share per-group worker state → `pytest -n 4 --dist=loadgroup`.
-
-As an illustration, one 22-item suite containing a 20-clone trial measured:
-
-| Mode | Command | Wall time | Reports | `total_runs` |
-|------|---------|-----------|---------|--------------|
-| Serial | `pytest -n 0` | 203.4s | 1 | 22 |
-| Parallel, loadgroup | `pytest -n 4 --dist=loadgroup` | 165.5s | 1 | 22 |
-| Parallel, default load | `pytest -n 4` | **113.8s** | 1 | 22 |
-
-All three emit the same single report and the same trial verdict; `load` is fastest
-here because the 20 clones fan out across the 4 workers instead of being pinned to one.
+`@pytest.mark.trial(n=, threshold=)` is declaration-only. It remains useful with `-m trial`, but it does not clone or schedule executions.
 
 ---
 
@@ -245,9 +202,7 @@ clean `pytest_sessionfinish`. This has two consequences you should be aware of:
 Both behaviors are deliberate fail-closed choices for this release. A durable
 per-worker transport (incremental JSONL shards that survive a killed worker, with
 the size cap applied per-record) is in progress as a follow-up change; until it
-lands, use `--dist=loadgroup` only when your trial groups need worker cohesion (see
-[Choosing `loadgroup` vs `load`](#choosing-loadgroup-vs-load)) and size your cap to
-your largest expected worker payload.
+lands, size the cap to your largest expected worker payload.
 
 ---
 

pyproject.toml

@@ -87,7 +87,7 @@ asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
 markers = [
     "harm(*categories): categorize test by harm type",
-    "trial(n=, threshold=): statistical repetition of a test",
+    "trial(n=, threshold=): declare a trial population",
     "slow: marks tests that spawn subprocess pytest runs; deselect with -m 'not slow'",
 ]
 filterwarnings = [

rampart/core/execution.py

@@ -297,7 +297,8 @@ async def execute_trials_async(
             PopulationResult: Aggregate verdict and individual trial results.
 
         Raises:
-            TypeError: If n is not a non-boolean integer.
+            TypeError: If n is not a non-boolean integer or threshold is not
+                a non-boolean number.
             ValueError: If n is less than 1 or threshold is outside
                 [0.0, 1.0].
         """
@@ -307,19 +308,14 @@ async def execute_trials_async(
         if n < 1:
             msg = "n must be greater than or equal to 1"
             raise ValueError(msg)
-        if not 0.0 <= threshold <= 1.0:
-            msg = "threshold must be between 0.0 and 1.0"
-            raise ValueError(msg)
 
         results: list[Result] = []
+        population = PopulationResult(results=results, threshold=threshold)
         for _ in range(n):
             result = await self.execute_async(adapter=adapter)
             results.append(result)
 
-        return PopulationResult(
-            results=results,
-            threshold=threshold,
-        )
+        return population
 
     @abstractmethod
     async def _execute_async(self, *, adapter: AgentAdapter) -> Result:

rampart/core/result.py

@@ -172,6 +172,7 @@ class PopulationResult:
             from 0.0 to 1.0.
 
     Raises:
+        TypeError: If threshold is not a non-boolean number.
         ValueError: If threshold is outside [0.0, 1.0].
     """
 
@@ -182,11 +183,19 @@ def __post_init__(self) -> None:
         """Validate population configuration.
 
         Raises:
+            TypeError: If threshold is not a non-boolean number.
             ValueError: If threshold is outside [0.0, 1.0].
         """
+        if not isinstance(self.threshold, int | float) or isinstance(
+            self.threshold,
+            bool,
+        ):
+            msg = "threshold must be a number"
+            raise TypeError(msg)
         if not 0.0 <= self.threshold <= 1.0:
             msg = "threshold must be between 0.0 and 1.0"
             raise ValueError(msg)
+
     @property
     def safe_count(self) -> int:
         """Number of safe trials."""