[REFACTOR]: Add shared linear trace runner

[Spencer Schoenberg (spencrr)]

Description

Adds the linear trace runner shared by attack and probe strategies. run_trace_async drives a conversation with an optional online stop_when check, keeps separate raw and annotated turn histories, and records TraceEndReason. evaluate_final_trace_async evaluates the final trace once. It reuses the latest online evaluation only when the evaluator, raw turns, manifest, and observability level are all identical.

The runner does not own session lifetime, polarity, cleanup, or exception conversion; those remain strategy and BaseExecution responsibilities. Driver history receives a shallow copy, evaluator contexts contain annotation-free turns, and reused evaluator evidence is copied defensively.

EvaluationRecord, TraceRun, run_trace_async, and evaluate_final_trace_async are exported from rampart.core for custom strategies and documented in the API reference. Built-in probes adopt them in #149 and XPIA in #150.

Breaking changes

None. This PR adds APIs and does not change existing strategies.

Checklist

• pre-commit run --all-files passes
• Tests added or updated for changes — termination reasons, raw and annotated histories, stop behavior, exact-context reuse, changed observability and manifest, optional-evidence copying, post-run mutation, exceptions, and turn budgets
• Documentation updated

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation matches the documented contract and has thorough focused test coverage.

Review effort: Balanced
Findings: None

What changed in this PR

Adds a shared linear trace runner for future attack and probe strategies, including final-trace evaluation reuse.

Changes:

• Adds trace execution, termination tracking, and final evaluation helpers.
• Exports and documents the new core APIs.
• Adds comprehensive unit coverage for stopping, histories, reuse, mutation, and budgets.

File	Description
rampart/​core/​trace.py	Implements shared trace execution and evaluation reuse.
rampart/​core/​__init__.py	Exports the new public APIs.
docs/​api/​core-protocols.md	Adds API reference entries.
tests/​unit/​core/​test_trace.py	Tests trace execution and reuse behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.