package shadowdb

import "errors"

// Sentinel errors for Opener and Session failures. Implementations
// wrap these with %w so callers classify with errors.Is.
//
// Opener 与 Session 的哨兵错误. 实现以 %w 包装, 调用方用 errors.Is
// 分类.
var (
	// ErrSessionNotFound is returned by Close / Reap when the
	// sessionID is unknown to the Opener. Typically indicates a
	// double-close or a crash-recovery attempt on a reaped session.
	//
	// ErrSessionNotFound 在 Close / Reap 遇到 Opener 不认识的
	// sessionID 时返回. 通常意味着重复 Close 或在已 Reap 的
	// session 上做崩溃恢复.
	ErrSessionNotFound = errors.New("shadowdb: session not found")

	// ErrInvalidIdentifier is returned when Options.ShadowTable or
	// Options.SeedFromTable does not match the plain SQL identifier
	// pattern [a-zA-Z_]\w*. Quoted identifiers (backtick / double
	// quote) are deliberately rejected -- same policy as
	// tools/builtin.SQLCASTool for consistency across the SQL toolchain.
	//
	// ErrInvalidIdentifier 在 Options.ShadowTable 或 Options.SeedFromTable
	// 不匹配纯 SQL 标识符模式 [a-zA-Z_]\w* 时返回. 反引号 / 双引号
	// 标识符刻意拒绝 -- 与 tools/builtin.SQLCASTool 策略一致, 保持
	// SQL 工具链标识符契约统一.
	ErrInvalidIdentifier = errors.New("shadowdb: invalid SQL identifier")

	// ErrEmptySessionID is returned by Open on an empty sessionID.
	// Empty IDs would merge all anonymous sessions into one filter
	// bucket (session_id='') and defeat isolation.
	//
	// ErrEmptySessionID 在 Open 接到空 sessionID 时返回. 空 ID 会把
	// 所有匿名 session 合并到同一 filter 桶 (session_id=''), 使隔离
	// 完全失效.
	ErrEmptySessionID = errors.New("shadowdb: sessionID must be non-empty")

	// ErrDuplicateSession is returned by Open when sessionID is
	// already tracked as an open session. Callers should Close the
	// prior session before re-opening the same ID, or use a fresh
	// ID.
	//
	// ErrDuplicateSession 在 Open 遇到已存在的 sessionID 时返回.
	// 调用方应先 Close 旧 session 再以同 ID 重开, 或直接换用新 ID.
	ErrDuplicateSession = errors.New("shadowdb: sessionID already open")
)