// Package transcode 是 design/25「转码能力」的本地能力包实现：一条
// 「字节 + 源格式 + 目标格式 → 字节 + 目标格式 + 元信息」的进程内、同步、
// 纯函数式转换（不触网、不落盘、不读数据库）。它被设计为可被其它模块、
// 编译期系统插件与工具面（agent / MCP）复用，落地方式见 design/25 §1.3.2
// 的「两层注册」。
//
// 本包的所有失败一律是 errors.go 里的具名哨兵（或包裹它），绝不返回部分
// 结果假装成功（design/25 §2.4 / §5.4）。
package transcode

import "errors"

// design/25 §2.4 的八个哨兵。调用方用 errors.Is 判定；一律 %w 包裹，
// 绝不静默吞掉。错误文案是哨兵 + 可读短句：上游/解码器的错误原文只进日志，
// 不进用户可见正文（与 channelbridge 的「原因短语不含上游回显」同一条纪律）。
var (
	// ErrUnsupportedFormat 源或目标格式未知 / 魔数嗅不出 / 注册表里没有这条路。
	// 调用方应诚实提示；按内容发生的失败不熔断。
	ErrUnsupportedFormat = errors.New("transcode: unsupported format")
	// ErrInputTooLarge 输入字节超过 MaxInputBytes，或可确证的时长超过
	// MaxDuration。在解码前拒绝（一行都不解）。
	ErrInputTooLarge = errors.New("transcode: input too large")
	// ErrOutputTooLarge 解码产物超过 MaxOutputBytes。在解码前即可确证时先拒绝，
	// 否则边走边计数、命中即停。
	ErrOutputTooLarge = errors.New("transcode: output too large")
	// ErrDecodeFailed 字节损坏 / 头非法 / 帧截断。与「格式不支持」分开：
	// 一个是「不会」，一个是「坏了」。
	ErrDecodeFailed = errors.New("transcode: decode failed")
	// ErrEncodeFailed 目标侧构造失败（如 WAV 头写不出）。
	ErrEncodeFailed = errors.New("transcode: encode failed")
	// ErrTimeout ctx 超时被检出。记 WARN、诚实提示、不重试（同步路径由调用方决定）。
	ErrTimeout = errors.New("transcode: timeout")
	// ErrBusy 并发槽已满，快速失败、不排队（绝不入无界队列）。
	ErrBusy = errors.New("transcode: busy")
	// ErrNoBackend 选了外部后端但主机上找不到 / 不可用。本期默认路径是进程内
	// 纯 Go，故暂无触发点；哨兵先行登记，供 design/25 §4.3 的可选后端复用。
	ErrNoBackend = errors.New("transcode: no backend")
)

// 以下两个不是 design/25 §2.4 的八个转码哨兵：它们描述的是「注册表里放进了
// 不合法的东西」和「工具面的入参不合法」，属包内自有的构造期/入参错误。
var (
	// ErrDuplicate 同一个「源→目标」被注册了两次（与 registry.Register 的
	// 「重名报错」纪律同源）。
	ErrDuplicate = errors.New("transcode: codec already registered")
	// ErrInvalidCodec 注册项不合法：nil、源或目标格式为空、或源等于目标。
	ErrInvalidCodec = errors.New("transcode: invalid codec")
	// ErrBadArgs 工具面入参不合法（非对象、缺字段、类型不对）。
	ErrBadArgs = errors.New("transcode: bad arguments")
)