trace

type BudgetEvent struct {
	Effect    string `json:"effect"`
	Used      int    `json:"used"`
	Limit     int    `json:"limit"`     // -1 if unlimited
	Remaining int    `json:"remaining"` // -1 if unlimited
	Physical  int    `json:"physical"`  // Physical usage count
}

type Collector struct {

	// OnEvent is called for each trace event as it is recorded.
	// Used by WASM to stream events to JavaScript in real-time.
	// Nil means no streaming (events are only accumulated in events[]).
	OnEvent func(TraceEvent)
	// contains filtered or unexported fields
}

type CompareResult struct {
	Match      bool       `json:"match"`
	Mismatches []Mismatch `json:"mismatches,omitempty"`
	BaselineN  int        `json:"baseline_events"`
	ReplayN    int        `json:"replay_events"`
}

type ContractEvent struct {
	Kind     string `json:"kind"` // "requires", "ensures", "invariant"
	Passed   bool   `json:"passed"`
	Message  string `json:"message"`
	Location string `json:"location"`
	Function string `json:"function"`
}

type EffectEvent struct {
	EffectName    string   `json:"effect_name"`             // e.g., "IO", "FS", "Net"
	OpName        string   `json:"op_name"`                 // e.g., "println", "readFile"
	Args          []string `json:"args,omitempty"`          //
	Result        string   `json:"result,omitempty"`        //
	Deterministic *bool    `json:"deterministic,omitempty"` // nil=unknown, true=deterministic, false=non-deterministic
}

type ErrorEvent struct {
	Message  string `json:"message"`
	Location string `json:"location,omitempty"`
}

type EventType string

type ExportConfig struct {
	MinScore  float64 // Minimum quality score (0.0-1.0), default 0.0
	SourceDir string  // Directory to resolve source files from
}

type FunctionEvent struct {
	Name       string   `json:"name"`
	Args       []string `json:"args,omitempty"`
	Result     string   `json:"result,omitempty"`
	DurationNS int64    `json:"duration_ns,omitempty"`
}

type Mismatch struct {
	Index    int    `json:"index"`             // Event index where mismatch occurred
	Field    string `json:"field"`             // Which field differs
	Expected string `json:"expected"`          // Value from baseline trace
	Actual   string `json:"actual"`            // Value from replay trace
	Context  string `json:"context,omitempty"` // Human-readable context
}

type ModuleEvent struct {
	Name       string   `json:"name"`
	DurationNS int64    `json:"duration_ns,omitempty"`
	Caps       []string `json:"caps,omitempty"`
}

type Tier int

type TraceEvent struct {
	Version     string    `json:"version"`
	Event       EventType `json:"event"`
	TimestampNS int64     `json:"timestamp_ns"`
	Depth       int       `json:"depth,omitempty"`

	// OTEL-compatible span identifiers (M-WASM-TRACE).
	// TraceID is consistent across all events in one execution.
	// SpanID/ParentSpanID form a parent-child tree for distributed tracing.
	TraceID      string `json:"trace_id,omitempty"`
	SpanID       string `json:"span_id,omitempty"`
	ParentSpanID string `json:"parent_span_id,omitempty"`

	// Event-specific payload (exactly one is non-nil per event)
	Module   *ModuleEvent   `json:"module,omitempty"`
	Function *FunctionEvent `json:"function,omitempty"`
	Effect   *EffectEvent   `json:"effect,omitempty"`
	Contract *ContractEvent `json:"contract,omitempty"`
	Budget   *BudgetEvent   `json:"budget,omitempty"`
	Error    *ErrorEvent    `json:"error,omitempty"`
}

type TraceScore struct {
	Total            float64        `json:"total"`             // Weighted total 0.0-1.0
	Completion       float64        `json:"completion"`        // Did program complete without errors?
	Complexity       float64        `json:"complexity"`        // Number of functions, effects, depth
	ContractCoverage float64        `json:"contract_coverage"` // Percentage of contracts that passed
	BudgetEfficiency float64        `json:"budget_efficiency"` // Used budget vs declared budget
	EffectDiversity  float64        `json:"effect_diversity"`  // Uses multiple effect types
	Stats            TraceStats     `json:"stats"`             // Raw statistics
	EffectBreakdown  map[string]int `json:"effect_breakdown"`  // Per-effect invocation counts
	FunctionCounts   map[string]int `json:"function_counts"`   // Per-function call counts
}

type TraceStats struct {
	TotalEvents       int  `json:"total_events"`
	FunctionCalls     int  `json:"function_calls"` // Enter events
	DistinctFunctions int  `json:"distinct_functions"`
	EffectCalls       int  `json:"effect_calls"`
	DistinctEffects   int  `json:"distinct_effects"`
	ContractChecks    int  `json:"contract_checks"`
	ContractsPassed   int  `json:"contracts_passed"`
	BudgetEvents      int  `json:"budget_events"`
	MaxDepth          int  `json:"max_depth"`
	HasErrors         bool `json:"has_errors"`
	HasModuleEnd      bool `json:"has_module_end"`
}

type TracingOptions struct {
	Tier Tier
	// MaxSpansPerTrace caps spans per trace. 0 = no budget (M2 populates this).
	MaxSpansPerTrace int
}

type TrainingExample struct {
	Source   string       `json:"source"`   // AILANG source code
	Trace    string       `json:"trace"`    // JSONL trace events (newline-separated)
	Score    float64      `json:"score"`    // Quality score 0.0-1.0
	Metadata TrainingMeta `json:"metadata"` // Summary metadata
}

type TrainingMeta struct {
	Module    string   `json:"module,omitempty"`  // Module name
	Caps      []string `json:"caps,omitempty"`    // Capabilities used
	Functions int      `json:"functions"`         // Distinct function count
	Effects   []string `json:"effects,omitempty"` // Distinct effect names
	MaxDepth  int      `json:"max_depth"`         // Maximum call depth
	Events    int      `json:"events"`            // Total event count
}