type Address struct {
	Address string `json:"address"`
	Name    string `json:"name,omitempty"`
}

type ArrayTrace struct {
	Spans []*SpanRecord
}

type Attachment struct {
	Filename    string `json:"filename"`
	MimeType    string `json:"mimeType"`
	Disposition string `json:"disposition"` // "attachment" | "inline" | ""
	ContentID   string `json:"contentId"`
	Content     []byte `json:"-"`
	Size        int    `json:"size"`
}

type ByteSignature struct {
	Offset    int
	HexPrefix string
}

type Diagnostic struct {
	Code     string `json:"code"`
	Severity string `json:"severity"` // "warn" | "error"
	Scope    string `json:"scope"`    // "envelope" | "structure" | "part"
	Detail   string `json:"detail,omitempty"`
	Path     string `json:"path,omitempty"`
}

type EmittedPart struct {
	Meta *PartMeta
	Body []byte
}

type FailureEvent struct {
	Scope            string
	DiagnosticCodes  []string
	ContentType      string
	Disposition      string
	TransferEncoding string
	BodyHead         []byte
	HeaderNames      []string
	Mailer           string
	StructurePath    string
}

type FailureFeatures struct {
	LibVersion       string   `json:"libVersion"`
	Scope            string   `json:"scope"`
	DiagnosticCodes  []string `json:"diagnosticCodes"`
	ContentType      string   `json:"contentType,omitempty"`
	Disposition      string   `json:"disposition,omitempty"`
	TransferEncoding string   `json:"transferEncoding,omitempty"`
	// ByteSignature is the hex of the offending part's leading bytes — structure, never content.
	ByteSignature string   `json:"byteSignature,omitempty"`
	HeaderNames   []string `json:"headerNames,omitempty"`
	// MailerFamily is the normalized X-Mailer/User-Agent family, e.g. "outlook".
	MailerFamily  string `json:"mailerFamily,omitempty"`
	StructurePath string `json:"structurePath,omitempty"`
}

type FailureSignature struct {
	// Hash is the finest-granularity hash — the primary dedup key.
	Hash     string            `json:"hash"`
	Features FailureFeatures   `json:"features"`
	Rollup   []SignatureRollup `json:"rollup"`
}

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

type HeaderMatch struct {
	Name    string
	Matches *regexp.Regexp
}

type Line struct {
	Bytes []byte
	Term  string // "\r\n" | "\n" | "" (last line, no terminator)
}

type MatchSpec struct {
	ContentType   string
	MainType      string
	Charset       string
	Disposition   string // "inline" | "attachment"
	Filename      *regexp.Regexp
	Header        *HeaderMatch
	ByteSignature *ByteSignature
	Predicate     func(meta *PartMeta, body []byte) bool
}

type Message struct {
	Headers     []Header               `json:"headers"`
	From        *Address               `json:"from,omitempty"`
	To          []Address              `json:"to"`
	Cc          []Address              `json:"cc"`
	Bcc         []Address              `json:"bcc"`
	ReplyTo     []Address              `json:"replyTo"`
	Subject     *string                `json:"subject"`
	MessageID   *string                `json:"messageId"`
	InReplyTo   *string                `json:"inReplyTo"`
	Date        *string                `json:"date"`
	Text        *string                `json:"text"`
	HTML        *string                `json:"html"`
	Attachments []Attachment           `json:"attachments"`
	Diagnostics []Diagnostic           `json:"diagnostics"`
	Annotations map[string]interface{} `json:"annotations"`
}

type Middleware struct {
	Name   string
	Phase  string
	Match  MatchSpec
	OnPart func(part *Part, next func())
}

type ParseOptions struct {
	Middleware []Middleware
	Trace      TraceHook
}

type Part struct {
	Meta        *PartMeta
	Body        []byte
	Text        *string
	HTML        *string
	ClassifyAs  string // "attachment" | "text" | "html" | ""
	Emitted     []EmittedPart
	Context     map[string]interface{}
	Diagnostics []Diagnostic
}

type PartMeta struct {
	Depth       int
	Headers     []Header
	ContentType string
	MainType    string
	Charset     string
	Format      string
	Delsp       bool
	Encoding    string
	Disposition string // "attachment" | "inline" | ""
	Filename    string
	ContentID   string
	Boundary    string
	IsMultipart bool
	Path        string
}

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

type SignatureRollup struct {
	// Level is the granularity label, coarse → fine.
	Level string `json:"level"`
	Hash  string `json:"hash"`
}

type Span interface {
	End(info SpanEnd)
}

type SpanEnd struct {
	InSize  int
	OutSize int
	Status  string // "ok" | "error"
	Error   string
}

type SpanRecord struct {
	Mw      string
	Path    string
	InSize  int
	OutSize int
	Status  string
	Error   string
}

type SplitHandlers struct {
	OnNodeStart  func(meta *PartMeta)               // headers complete; PartMeta computed. Fires for every node.
	OnBody       func(meta *PartMeta, chunk []byte) // a chunk of RAW body bytes for a leaf. May fire many.
	OnNodeEnd    func(meta *PartMeta)               // node finished (leaf body delivered, or container closed).
	OnDiagnostic func(d Diagnostic)                 // a non-fatal structural degradation.
}

type StructuredField struct {
	Value  string
	Params map[string]string
}

type TraceHook interface {
	Start(mwName string, meta *PartMeta) Span
}