observability

type Attr struct {
	Key   string
	Value string
}

type BuzzHostCall struct {
	Callable string
	Outcome  string
	Duration float64
}

type Config struct {
	Enabled        bool              // gates exporter setup; false = no-op
	Endpoint       string            // OTLP collector host:port (no scheme); required when Enabled
	Protocol       string            // "grpc" (default) or "http"
	Insecure       bool              // disable TLS for the OTLP exporter
	Headers        map[string]string // static headers on every OTLP request
	ServiceName    string            // resource attribute service.name
	ServiceVersion string            // resource attribute service.version
	SampleRatio    float64           // head-based trace sampling ratio [0,1]
	WorkspaceRoot  string            // stamped as magus.workspace.root when set
	// LocalCollect builds an always-on in-process metrics collector even when Enabled is false
	// (no external export), so the daemon can serve OTLP snapshots to the /dashboard. The CLI
	// leaves this false to keep one-shot invocations a true no-op.
	LocalCollect bool
}

type MCPCall struct {
	Tool        string
	Outcome     string
	InputBytes  int64
	OutputBytes int64
	Duration    float64
}

type Provider interface {
	Enabled() bool
	RecordCacheHit(ctx context.Context, attrs ...Attr)
	RecordCacheMiss(ctx context.Context, attrs ...Attr)
	RecordCacheError(ctx context.Context, attrs ...Attr)
	RecordCacheDuration(ctx context.Context, secs float64, attrs ...Attr)                     // magus.cache.duration histogram
	RecordCacheSaved(ctx context.Context, secs float64)                                       // magus.cache.saved.duration histogram
	RecordGraphQuery(ctx context.Context, secs float64, attrs ...Attr)                        // magus.graph.query.duration histogram
	RecordRemoteOp(ctx context.Context, op RemoteOp)                                          // magus.cache.remote.* metrics
	StartSpan(ctx context.Context, name string, attrs ...Attr) (context.Context, func(error)) // end fn marks failure on non-nil error
	RecordTargetRun(ctx context.Context, secs float64, attrs ...Attr)                         // magus.target.runs + magus.target.duration
	RecordPoolAcquire(ctx context.Context, waitSecs float64, n int64)                         // magus.pool.wait.duration + slots.running+n
	RecordPoolRelease(ctx context.Context, n int64)                                           // slots.running-n
	RecordPoolWaiting(ctx context.Context, delta int64)                                       // magus.pool.slots.queued += delta

	// MCP tool call family: magus.mcp.tool.*.
	RecordMCPCall(ctx context.Context, c MCPCall)

	// Filesystem sandbox families: magus.sandbox.*.
	RecordSandboxApply(ctx context.Context, secs float64, outcome, scope string) // magus.sandbox.apply.duration
	RecordSandboxRules(ctx context.Context, r SandboxRules)                      // magus.sandbox.rules + magus.sandbox.env.rules
	RecordSandboxCheck(ctx context.Context, access, decision, project string)    // magus.sandbox.checks
	RecordSandboxEnvDropped(ctx context.Context, project string, n int64)        // magus.sandbox.env.dropped

	// Buzz language families: magus.buzz.*.
	RecordBuzzExec(ctx context.Context, secs float64, mode, outcome string)          // magus.buzz.exec.duration
	RecordBuzzCompile(ctx context.Context, secs float64, phase, mode string)         // magus.buzz.compile.duration
	RecordBuzzHostCall(ctx context.Context, c BuzzHostCall)                          // magus.buzz.host.call.{duration,count}
	RecordBuzzSessionReuse(ctx context.Context, outcome string)                      // magus.buzz.session.pool.reuse
	RecordBuzzSessionIdle(ctx context.Context, delta int64)                          // magus.buzz.session.pool.idle
	RecordBuzzSessionEviction(ctx context.Context, source string)                    // magus.buzz.session.pool.evictions
	RecordBuzzSessionWarm(ctx context.Context, secs float64, source string)          // magus.buzz.session.warm.duration
	RecordBuzzImport(ctx context.Context, secs float64, kind, outcome string)        // magus.buzz.import.duration
	RecordBuzzSpellResolve(ctx context.Context, secs float64, spell, builtin string) // magus.buzz.spell.resolve.duration
	RecordBuzzSpellBuiltinsWarm(ctx context.Context, secs float64, spell string)     // magus.buzz.spell.builtins.warm
	RecordBuzzJITRun(ctx context.Context)                                            // magus.buzz.jit.runs
	RecordBuzzVMFault(ctx context.Context, kind string)                              // magus.buzz.vm.faults

	// Agent-surface families: magus.lease.*, magus.attention.*, magus.review.*. Every
	// attribute here is a bounded enum the caller has already validated; an id, a path, a
	// lease label or a remark body must never reach one.
	RecordLeaseRegistration(ctx context.Context, verdict string)              // magus.lease.registrations
	RecordAttentionDisposition(ctx context.Context, secs float64, sev string) // magus.attention.disposition.duration
	RecordReviewRemark(ctx context.Context, author string)                    // magus.review.remarks
	RecordReviewPublish(ctx context.Context, verdict string, downgraded bool) // magus.review.publishes
	// Snapshot returns the current metrics as standard OTLP protobuf, or (nil, nil) when this
	// provider is not collecting locally. OTLP is the export format for real monitoring
	// backends; it is never put on the dashboard's wire.
	Snapshot(ctx context.Context) ([]byte, error)
	Shutdown(ctx context.Context) error
}

type RemoteOp struct {
	Method   string
	Outcome  string
	Duration float64 // wall-clock seconds
	Bytes    int64
}

type SandboxRules struct {
	Read     int64
	Write    int64
	Exec     int64
	EnvExact int64
	EnvGlob  int64
	Scope    string
}