package flyto

// observer.go - 消费者实现的可观测性接口.
//
// 精妙之处(CLEVER): 三个接口分离,按需实现--
// EventObserver 是必须项,MetricObserver / TraceObserver 通过 type assertion 可选接入.
// 消费者不需要为用不到的接口写空方法.
//
// 升华改进(ELEVATED): 与 pkg/engine 中的具体实现(NoopObserver,StderrObserver 等)
// 完全分离--此包只定义契约,具体实现由引擎包或消费者自行提供.

// EventObserver 核心事件接口(消费者必须实现以接收引擎内部事件).
//
// 注意:这里的"事件"是引擎内部运行事件(tool_result_pairing_repaired 等),
// 与 Event 接口(引擎输出事件流)是两个不同的概念.
//
// Shape: push (subscribe). Consumers register an implementation via
// engine.Config.Observer; the engine calls back asynchronously on state
// changes, no consumer response expected.
//
// 形态: 订阅 (push). 消费者经 engine.Config.Observer 注入实现, 引擎在状态
// 变更时异步回调, 不等消费者回应.
type EventObserver interface {
	// Event 记录离散事件.
	// name 例如 "tool_result_pairing_repaired",data 是结构化上下文.
	Event(name string, data map[string]any)

	// Error 记录错误(含上下文,用于告警).
	Error(err error, context map[string]any)
}

// MetricObserver 数值指标接口(可选,通过 type assertion 检测).
//
// Shape: push (subscribe). Engine emits numeric metric samples; consumer
// forwards to Prometheus / StatsD / OpenTelemetry etc.
//
// 形态: 订阅 (push). 引擎发数值指标样本, 消费者转给 Prometheus / StatsD /
// OpenTelemetry 等.
type MetricObserver interface {
	// Metric 记录数值指标.
	// 例如:name="api_latency_ms", value=123.4, tags={"model":"claude-sonnet-4-6"}
	Metric(name string, value float64, tags map[string]string)
}

// TraceObserver 调用链接口(可选,通过 type assertion 检测).
//
// Shape: push (subscribe). Engine emits span-start / span-end events for
// distributed tracing consumers (Jaeger / Zipkin / Tempo).
//
// 形态: 订阅 (push). 引擎发 span-start / span-end 事件给分布式追踪消费者
// (Jaeger / Zipkin / Tempo).
type TraceObserver interface {
	SpanStart(name string, tags map[string]string) string // 返回 span ID
	SpanEnd(spanID string, err error)
}