traceinspect

Documentation

Index

• Constants
• func RenderBodyDiff(d BodyDiff) string
• func RenderExplainText(ledger []TurnLedger) string
• func RenderText(rep Report) string
• type BodyDiff
  • func DiffBodyFiles(pathA, pathB string) (BodyDiff, error)
  • func DiffBytes(a, b []byte) BodyDiff
• type CountSummary
• type EpochSummary
• type PrefixReasonSummary
• type Report
  • func InspectFile(path string) (Report, error)
• type TurnLedger
  • func ExplainFile(path string) ([]TurnLedger, error)

Constants

const (
	WhyExpectedMiss = "expected-miss" // first turn of an epoch
	WhyCompaction   = "compaction"    // compaction record preceded this turn
	WhyDrift        = "drift"         // prefix hash changed since last turn
	WhyEviction     = "eviction"      // provider-side body eviction (no preceding event)
)

Why labels for TurnLedger.Why.

const EvictionThreshold = 9000

EvictionThreshold is the cache_hit_tokens ceiling below which a turn > 1 is considered a full-body cache eviction. Derived from bench evidence (~9 k).

Functions

func RenderBodyDiff

func RenderBodyDiff(d BodyDiff) string

RenderBodyDiff formats a BodyDiff as a human-readable verdict.

func RenderExplainText

func RenderExplainText(ledger []TurnLedger) string

RenderExplainText formats the ledger as a fixed-width text table.

func RenderText

func RenderText(rep Report) string

Types

type BodyDiff

type BodyDiff struct {
	LenA         int    // earlier-turn body length, bytes
	LenB         int    // later-turn body length, bytes
	DivergeAt    int    // offset of first differing byte; == min(LenA,LenB) when one is a prefix of the other
	Diverged     bool   // a byte differs within the overlap [0,min(LenA,LenB))
	AIsPrefixOfB bool   // earlier body is a clean leading prefix of the later (cache-stable)
	ContextA     string // printable window of A around DivergeAt (only when Diverged)
	ContextB     string // printable window of B around DivergeAt (only when Diverged)
}

BodyDiff is the result of comparing two canonical wire-request bodies — the bytes MarshalCacheStable produced for two consecutive turns. For DeepSeek prefix-cache stability, the earlier turn's body MUST be a clean leading prefix of the later turn's body: only the appended tail should differ. Any divergence INSIDE the shared region is a historical-message byte change, which invalidates the prefix cache from that offset and forces a full-body re-send — the Layer-2 eviction this instrument hunts.

func DiffBodyFiles

func DiffBodyFiles(pathA, pathB string) (BodyDiff, error)

DiffBodyFiles reads two wire-body dump files (turn_NNNN.json, written by the DEEPSEEKCODE_WIRE_DUMP capture) and diffs them. pathA must be the earlier turn, pathB the later.

func DiffBytes

func DiffBytes(a, b []byte) BodyDiff

DiffBytes compares two wire bodies and reports the first divergence. a is the earlier turn, b the later. Never panics on empty input.

type CountSummary

type CountSummary struct {
	Name  string
	Count int
}

CountSummary counts one repair kind or tool value.

type EpochSummary

type EpochSummary struct {
	EpochID     string
	Role        string
	ParentEpoch string
	ShortHash   string
	UsageTurns  int
	Done        bool
}

type PrefixReasonSummary

type PrefixReasonSummary struct {
	Reason string
	Count  int
}

PrefixReasonSummary counts one prefix.snapshot Reason value.

type Report

type Report struct {
	Path            string
	TotalUsageTurns int
	CacheHitTokens  int
	CacheMissTokens int
	OutputTokens    int
	CostCNY         float64
	CacheHitRate    float64
	RootEpochs      int
	SubagentEpochs  int

	// UniquePrefixHashes counts distinct static_prefix_hash values seen
	// across prefix.snapshot records. A stable run has exactly 1; drift
	// produces 2+.
	UniquePrefixHashes int

	// ExpectedCacheMisses counts prefix.snapshot records where the epoch
	// was newly created (first snapshot for that epoch), indicating an
	// expected cache miss for the first turn of that epoch.
	ExpectedCacheMisses int

	// CacheSavingsCNY is the difference between what the run would have
	// cost at full cache-miss pricing and what it actually cost, computed
	// from the usage records' cache hit/miss token split.
	CacheSavingsCNY float64

	// T6.4: lifecycle records the gate inspects. A clean summary that omits
	// these would mask exactly the events the Cache Reliability gate fails on.
	CompactionCount    int
	DriftBlockedCount  int
	PendingChangeCount int

	// PrefixReasons counts non-empty Reason values from prefix.snapshot records.
	PrefixReasons []PrefixReasonSummary

	// RepairKinds counts non-empty Kind values from repair records.
	RepairKinds []CountSummary

	// RepairTools counts non-empty Tool values from repair records.
	RepairTools []CountSummary

	// Realized (sum of usage cost_cny) vs the budget gate's projected cost
	// (sum of projected_cny on budget.* records). BudgetEvents counts how many
	// budget records contributed a projection.
	ProjectedCNY float64
	BudgetEvents int

	Epochs []EpochSummary
}

func InspectFile

func InspectFile(path string) (Report, error)

type TurnLedger

type TurnLedger struct {
	Turn         int
	EpochID      string
	HitTokens    int
	MissTokens   int
	OutputTokens int
	CostCNY      float64
	Evicted      bool   // true if a full-body eviction is detected
	Why          string // human-readable eviction cause (empty when Evicted==false and not an expected miss)
}

TurnLedger is a single-turn cache row for the explain ledger.

func ExplainFile

func ExplainFile(path string) ([]TurnLedger, error)

ExplainFile reads a JSONL trace and returns a per-turn ledger in emission order. It classifies each usage record with an eviction flag and a Why label.