Why Trenchbird records why something is unknown

[TrenchBird]

One of the first things cold-agent testing exposed in Trenchbird was that simply recording:

{
  "routeTransparency": "unknown"
}

wasn’t enough.

The artifact was honest — it did not pretend the route had been reconstructed — but an artifact-only consumer still could not tell why the route was unknown without reading Trenchbird’s documentation.

That matters for an evidence system.

In v1.1, Trenchbird now records the limitation reason alongside the observation:

{
  "code": "ROUTE_TRANSPARENCY_UNKNOWN",
  "category": "inspection_limitation",
  "details": {
    "routeTransparency": "unknown",
    "reason": "decoder_unavailable"
  }
}

The distinction is important because transaction inspection and route understanding are different questions.

A transaction can have:

{
  "inspectionCompleteness": "complete",
  "routeTransparency": "unknown"
}

without contradiction.

Trenchbird may successfully inspect the unsigned transaction bytes, resolve the relevant transaction structure, observe required signers, and record invoked program IDs while still lacking enough interpretation to reconstruct the swap route.

It also does not use Jupiter router claims, program IDs, account presence, or instruction references to manufacture route certainty.

Those remain separate pieces of evidence.

The cold test that found this was simple: give an agent only the artifact and ask why route transparency is unknown.

Before the change, the artifact could tell the agent that it was unknown.

After the change, it can also tell the agent why.

That is the direction I want Trenchbird’s evidence model to follow:

preserve what is known, preserve what is unknown, and preserve enough context to understand the difference.