Spaces:

warenterprise
/

trace2mcp

Running

trace2mcp / docs /ARCHITECTURE.md

War Enterprise

Release Trace2MCP 0.2.2

1dc3b5a verified 2 months ago

4.02 kB

# Architecture

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

## Data flow

```text
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:

```text
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.

	# Architecture

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

	## Data flow

	```text
	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:

	```text
	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.