Add a shared error-code catalog so failures can be traced by stable codes.

Services can resolve legacy aliases and expose the catalog over CLI and HTTP instead of ad-hoc error strings.

Co-authored-by: Cursor <cursoragent@cursor.com>

errcode/code.go

@@ -0,0 +1,50 @@
+// Package errcode 定义跨系统共用的错误码契约。
+//
+// 码格式为「域.助记名」（domain.mnemonic）。本包不依赖 HTTP、日志或任何产品类型：
+// 调用方用 Registry 登记定义，用 E 携带码在进程内传递，用 JSON 跨进程传输。
+// 未知码必须经 Registry.Resolve 回落到 sys.unknown_code，不得静默当成成功。
+package errcode
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// 域 2–32 字符，助记名 2–64 字符。域允许连字符，助记名允许下划线。
+var codePattern = regexp.MustCompile(`^[a-z][a-z0-9-]{1,31}\.[a-z][a-z0-9_]{1,63}$`)
+
+// Code 是已规范化的错误码。空字符串不是合法码。
+type Code string
+
+// Valid 报告码是否符合 domain.mnemonic 格式。
+func (c Code) Valid() bool { return codePattern.MatchString(string(c)) }
+
+// Domain 返回点号前的域；格式不合法时返回空字符串。
+func (c Code) Domain() string {
+	d, _, ok := strings.Cut(string(c), ".")
+	if !ok || !c.Valid() {
+		return ""
+	}
+	return d
+}
+
+// Mnemonic 返回点号后的助记名；格式不合法时返回空字符串。
+func (c Code) Mnemonic() string {
+	_, m, ok := strings.Cut(string(c), ".")
+	if !ok || !c.Valid() {
+		return ""
+	}
+	return m
+}
+
+func (c Code) String() string { return string(c) }
+
+// ParseCode 校验并返回码。
+func ParseCode(s string) (Code, error) {
+	c := Code(s)
+	if !c.Valid() {
+		return "", fmt.Errorf("errcode: invalid code %q", s)
+	}
+	return c, nil
+}