docs/ARCHITECTURE.md

Architecture

Trace2MCP is organized around a narrow boundary: traces describe what happened; workflows describe what can be replayed safely.

Data flow

Recorder / JSON importer
          │
          ▼
       Trace v1
          │
          ├── validation
          ├── failed-event filtering
          ├── input/result reference inference
          ├── safe read deduplication
          └── dependency-cycle detection
          │
          ▼
       Workflow
          │
          ├── local runtime
          ├── replay benchmark
          └── MCP code generation

Trace

A trace is historical evidence. It contains runtime inputs and an ordered list of observed tool events. Each event has an identifier, tool name, arguments, result, completion status, and side-effect classification.

Trace2MCP treats argument/result content as potentially sensitive. Recording and sharing are separate trust decisions.

Hugging Face Session Trace JSONL can be imported as a trace source. Because Session Trace producers do not share one universal side-effect classification, unclassified tool calls enter as unknown and remain blocked until trusted metadata or a human review marks them as read-only.

Compiler

The compiler turns concrete observed values into references. For example, if a later argument equals an earlier event's company_id result, the workflow can refer to that node's result path rather than preserving the concrete ID.

Only successful events are candidates for automatic compilation. Repeated safe reads may be deduplicated. Dependencies form a DAG; cycles stop compilation.

Compilation is structural, not a proof of semantic equivalence. A workflow should be replayed against representative cases before use.

Runtime

The runtime resolves input and node-result references, groups ready nodes into layers, and executes independent nodes concurrently. Tool names resolve through an explicit registry; trace data never selects arbitrary Python imports.

Every supported managed invocation uses this live-runtime order:

workflow/reference/integrity verification
                 ↓
exact handler + reviewed contract binding
                 ↓
Trace2MCP policy + approval + input schema
                 ↓
optional generic RuntimeGuard (HOL Guard adapter)
                 ↓
same exact handler + output schema

The optional guard cannot replace or weaken an earlier Trace2MCP check. It is not used during compilation or frozen replay, and it is disabled by default.

Side effects are denied by default. Applications that enable them must add their own authorization, idempotency, review, and rollback controls. Neither the dispatcher nor an optional policy guard is an operating-system sandbox for arbitrary Python inside an authorized handler.

Benchmarking

There are two different measurements:

1. Recorded-duration model: sums the event durations for the sequential path and compares that with the DAG's weighted critical path.
2. Replay wall time: runs controlled offline waits or registered tools and measures elapsed time.

The Space emphasizes the first model so every number can be inspected directly in the pasted JSON. Neither measurement predicts production performance by itself. Network jitter, rate limits, caches, model calls, and service contention must be measured in the target environment.

Threat model

Trace2MCP assumes traces, generated workflows, and tool results can be hostile. The prototype reduces risk by keeping automatic compilation read-only and using an explicit tool registry, but it is not a sandbox. Before production use:

• redact secrets and personal data;
• allowlist tool names and argument schemas;
• enforce timeouts and resource limits;
• validate outputs at every trust boundary;
• require human authorization for consequential actions;
• log workflow version, inputs, approvals, and results;
• test retries and partial failures.