trajectory

type AttrSpec struct {
	// Name 属性名（必是 otel.go 里的某个 Attr* 常量，且全表不重复）。
	Name string
	// Source 来源字段：Row 上的哪一个字段（派生值写清怎么算出来的）。
	Source string
	// Domain 取值域。
	Domain Domain
	// Card 基数上界。
	Card Cardinality
	// LabelSafe 能否作为 metric label；为真必须「枚举取值 + 本仓给得出上界」。
	LabelSafe bool
}

type Cardinality struct {
	// Max 本仓能保证的取值上界；0 = 本仓定不出上界。
	Max int
	// Why 上界依据（Max 为 0 时写清为什么定不出）。
	Why string
}

type Domain struct {
	// Kind 取值形态，取 **Go 类型名**（string / int64 / float64 / bool）。
	// 见头注「Go 类型为什么进契约」。
	Kind string
	// Values 枚举取值（按本仓词表顺序）；空 = 非枚举。
	Values []string
	// Note 取值域说明。非枚举必写（枚举的取值域已由 Values 表达完整）。
	Note string
}

type ForbiddenLabel struct {
	// Name 语义名。
	Name string
	// Why 为什么禁止。
	Why string
}

type Issue struct {
	// Pairing 缺口类目（missing_result / duplicate_result / unpaired_result /
	// duplicate_call）。
	Pairing Pairing
	// CallID 相关工具调用标识（无关联调用时为空）。
	CallID string
	// Seq 相关行的序号。
	Seq int
}

type Kind string

type Options struct {
	// Summarize 摘要注入点：宿主自定义行标签（展示文案归宿主，内核不认识
	// 任何领域词）。返回空串时沿用本包的通用标签；nil 时全程用通用标签。
	//
	// 只在行创建时调用一次——行的可读字段（类目、标识、工具名、时刻）在创建
	// 后不再变化，故摘要不需要跟着配对状态刷新。
	Summarize func(Row) string
}

type Pairing string

type Projector struct {
	// contains filtered or unexported fields
}

type Row struct {
	// Seq 行序号（1 起，按创建顺序）：宿主据此排序，投影内稳定。
	Seq int
	// Kind 行类目。
	Kind Kind
	// ID 行标识：轮次行 "turn#1"；带环节号的步骤行 "step#7"；
	// 工具行 "tool#<call_id>"；无自然键的行用 "step#-<seq>" 形式兜底
	// （"-" 前缀表示「这个标识是投影生成的，不是业务自然键」）。
	// 格式的唯一生成点是 turnRowID / stepRowID / toolRowID / seqID——otel 的
	// 父子关系复用同一组函数，另写一份格式父子就会连不上。
	ID string
	// Turn 所属轮次序号（1 起）；轮次之外的事件为 0。
	Turn int
	// HasStep 是否带环节号（环节号 0 是合法值，故用独立标志位表达「有没有」）。
	HasStep bool
	// StepID 所属环节号（HasStep 为真时有效）。
	StepID uint64
	// CallID 工具调用标识（仅工具行；配对键）。
	CallID string
	// Tool 工具名（仅工具行）。
	Tool string
	// StartAt 起始时刻（取自事件时刻；缺失时零值）。
	StartAt time.Time
	// EndAt 结束时刻（取自事件时刻；未收口时零值）。
	EndAt time.Time
	// Status 收口状态。
	Status Status
	// Pairing 配对状态（仅工具行）。
	Pairing Pairing
	// DupResults 重复结果计数（同一 call_id 收到第二个及以后的结果时累加）。
	DupResults int
	// Summary 行摘要（默认通用标签；宿主可用 Options.Summarize 覆盖）。
	Summary string
}

type Span struct {
	// Name span 名（低基数，取值域见 Kind）。
	Name string
	// ParentID 父 span 的行标识（与 Row.ID 同源，见头注「trace 边界」）；
	// 空 = 根，宿主应为它开一个新 trace。
	ParentID string
	// Status span 状态。
	Status SpanStatus
	// StartAt 起点（未收口时为零值，宿主导出时可自行取当前时刻）。
	StartAt time.Time
	// EndAt 终点（未收口时为零值）。
	EndAt time.Time
	// Attributes 属性表（键取本文件的 Attr* 常量，值是 string/int64/float64）。
	Attributes map[string]any
}

type SpanStatus string

type Status string

type TraceGranularity string