sink

type FileConfig struct {
	// Path is the absolute or relative path to the log file.  When set,
	// Dir and DefaultFilename are ignored.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Dir is the directory in which the sink writes the log when Path is
	// empty.  Must be set in that case.  Relative directories are resolved
	// against cwd at NewFileSink time.
	Dir string `json:"dir,omitempty" yaml:"dir,omitempty"`

	// MaxSizeMB triggers rotation when the file grows past this size.
	// Zero means lumberjack's default (100 MB).
	MaxSizeMB int `json:"max_size_mb,omitempty" yaml:"max_size_mb,omitempty"`

	// MaxBackups is the number of rotated files to keep.
	// Zero means keep all (lumberjack default).
	MaxBackups int `json:"max_backups,omitempty" yaml:"max_backups,omitempty"`

	// MaxAgeDays is the maximum age in days for rotated files.
	// Zero means no age-based deletion (lumberjack default).
	MaxAgeDays int `json:"max_age_days,omitempty" yaml:"max_age_days,omitempty"`

	// DefaultFilename is consulted when Path is empty.  It returns just the
	// basename; the sink joins it with Dir.  When nil, a generic
	// "sink_<RFC3339-utc-second>.log" filename is used.  Made a function so
	// callers can encode their own naming convention (eg
	// "stackql_mcp_server_<timestamp>.log") without bringing the format
	// string into the sink package.
	DefaultFilename func(time.Time) string `json:"-" yaml:"-"`
}

type OTelAnyValue struct {
	StringValue *string  `json:"stringValue,omitempty"`
	IntValue    *string  `json:"intValue,omitempty"`
	DoubleValue *float64 `json:"doubleValue,omitempty"`
	BoolValue   *bool    `json:"boolValue,omitempty"`
}

type OTelAttribute struct {
	Key   string       `json:"key"`
	Value OTelAnyValue `json:"value"`
}

type OTelLogRecord struct {
	Time     time.Time
	Severity int
	Body     string
	// Attributes are emitted in order; empty string values are dropped.
	Attributes []OTelAttribute
	// TraceParent is a caller-supplied W3C traceparent, honoured when well
	// formed; otherwise one trace id is generated per CorrelationKey (e.g. a
	// session) so related records correlate.
	TraceParent    string
	CorrelationKey string
}

type OTelLogsData struct {
	ResourceLogs []OTelResourceLogs `json:"resourceLogs"`
}

type OTelRecorder interface {
	OTelLogRecords() []OTelLogRecord
}

type OTelResource struct {
	ServiceName    string
	ServiceVersion string
	// Attributes are appended after service.name / service.version.
	Attributes []OTelAttribute
}

type OTelResourceLogs struct {
	Resource  otelResource    `json:"resource"`
	ScopeLogs []OTelScopeLogs `json:"scopeLogs"`
	SchemaURL string          `json:"schemaUrl"`
}

type OTelScope struct {
	Name      string
	Version   string
	SchemaURL string
}

type OTelScopeLogs struct {
	Scope      otelInstrumentationScope `json:"scope"`
	LogRecords []OTelWireLogRecord      `json:"logRecords"`
	SchemaURL  string                   `json:"schemaUrl"`
}

type OTelWireLogRecord struct {
	TimeUnixNano         string          `json:"timeUnixNano"`
	ObservedTimeUnixNano string          `json:"observedTimeUnixNano"`
	SeverityNumber       int             `json:"severityNumber"`
	SeverityText         string          `json:"severityText"`
	Body                 OTelAnyValue    `json:"body"`
	Attributes           []OTelAttribute `json:"attributes"`
	TraceID              string          `json:"traceId"`
	SpanID               string          `json:"spanId"`
}

type Sink interface {
	// Record serialises and writes one payload.  Errors include transport
	// failures (full disk, broken pipe, etc) and marshalling failures.
	Record(ctx context.Context, payload any) error
	// Close flushes any buffered state and releases the underlying resource.
	Close() error
}