staging

type AllowAlwaysGuard struct{}

type DependencyGuard interface {
	// AllowTransition reports whether r may move to to.
	//
	// AllowTransition 判定 r 能否转移到 to.
	AllowTransition(ctx context.Context, r Record, to State) (allow bool, err error)
}

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

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

type Query struct {
	// SessionID filters to Records of a single Agent session. Empty
	// string does not constrain.
	//
	// SessionID 过滤单个 Agent session 的 Record. 空字符串不约束.
	SessionID string

	// States filters to Records currently in any of the listed
	// states. Empty slice does not constrain.
	//
	// States 过滤当前处于列表中任一状态的 Record. 空 slice 不约束.
	States []State

	// Since filters to Records whose UpdatedAt is at or after the
	// given time. Zero time does not constrain.
	//
	// Since 过滤 UpdatedAt 在给定时间或之后的 Record. 零值不约束.
	Since time.Time

	// Limit caps the number of Records returned. 0 means no limit.
	// Store implementations SHOULD honor a sane default upper bound
	// even when Limit is 0 to protect against pathological queries.
	//
	// Limit 限制返回 Record 数. 0 表示无限制. Store 实现即使 Limit=0
	// 也应设一个合理上限以防病态查询.
	Limit int
}

type Record struct {
	// ID is the globally unique record identifier assigned at Stage
	// time by the Store implementation (UUID for SQL, monotonic int
	// for InMemoryStore). Callers MUST treat it as opaque.
	//
	// ID 是 Stage 时由 Store 实现分配的全局唯一标识 (SQL 用 UUID,
	// InMemoryStore 用单调递增 int). 调用方视为不透明值.
	ID string

	// SessionID groups Records emitted within one Agent session.
	// Required: Stage rejects empty SessionID. Platform layers use
	// it to reconstruct per-session audit trails and to implement
	// session-level batch operations (bulk cancel, session rollback).
	//
	// SessionID 把同一 Agent session 产出的 Record 归簇. 必填:
	// Stage 拒绝空 SessionID. 平台层据此还原 session 级审计链, 并实现
	// session 级批量操作 (批量取消 / session 回滚).
	SessionID string

	// State is the current lifecycle state. Transitions are validated
	// against the static matrix (IsLegal) + DependencyGuard before
	// being persisted by a Store.
	//
	// State 是当前生命周期状态. transition 先过静态矩阵 (IsLegal) +
	// DependencyGuard, 然后才由 Store 持久化.
	State State

	// Diff is the decision payload that both tech and biz Validators
	// review. SourceTool dispatches decode; Raw carries the
	// serialized decision (opaque to staging); Metadata carries
	// free-form context. The whole decision package sits in a
	// single Diff -- product decision I (bundle-level atomicity).
	//
	// Diff 是两层 Validator 都审的决策载荷. SourceTool 分发 decode;
	// Raw 承载序列化决策 (对 staging 不透明); Metadata 承载自由上下文.
	// 整个决策包装在一个 Diff 里 -- 产品决策 I (决策包级原子).
	Diff validator.DiffInput

	// TechVerdict is populated by Store.UpdateTechVerdict when the
	// tech tier approves or blocks. Zero value (empty ValidatorName)
	// means the tech tier has not yet reviewed this Record. Consumers
	// querying the Store for audit purposes read Severity / Reason
	// off this field to explain the rejected_tech outcome or the
	// tech-passed advisory (Warn) on an approved Record.
	//
	// TechVerdict 在技术层放行或阻断时由 Store.UpdateTechVerdict 填充.
	// 零值 (ValidatorName 为空) 表示技术层尚未审. 审计场景的消费方
	// 从 Severity / Reason 读取以解释 rejected_tech 结果, 或放行
	// Record 上技术层留下的 advisory (Warn) 信息.
	TechVerdict validator.Verdict

	// BizVerdict is populated by Store.UpdateBizVerdict when the
	// biz (ML / rules / LLM) tier approves or blocks. Zero value
	// means the biz tier has not yet reviewed.
	//
	// BizVerdict 在业务层 (ML / 规则 / LLM) 放行或阻断时由
	// Store.UpdateBizVerdict 填充. 零值表示业务层尚未审.
	BizVerdict validator.Verdict

	// ExecutionError is populated by Store.MarkFailed with the
	// caller-supplied reason when a previously approved Record
	// fails at production commit time. Empty string on any
	// non-failed Record.
	//
	// ExecutionError 由 Store.MarkFailed 在放行后的 Record 生产
	// commit 失败时填入调用方提供的 reason. 非 failed 状态 Record
	// 为空字符串.
	ExecutionError string

	// ExecutionProof is populated by Store.MarkExecuted with the
	// caller-supplied opaque evidence that a previously approved
	// Record really landed in production. Typical shapes (decided
	// by the caller, not core): WMS return receipt, idempotency
	// key, transaction id. staging does not inspect it; it is
	// stored verbatim for audit chain integrity.
	//
	// ExecutionProof 由 Store.MarkExecuted 在放行后的 Record 真正
	// 落地生产时填入调用方提供的 opaque 证据. 典型形态 (调用方决定,
	// 非 core): WMS 回单 / 幂等 key / 事务 id. staging 不解读,
	// 原样存储供审计链完整性.
	ExecutionProof any

	// CreatedAt records when the Record was first staged. Set by
	// Store.Stage and never changes afterwards.
	//
	// CreatedAt 记录 Record 首次被 stage 的时刻. 由 Store.Stage 写入,
	// 此后不再变化.
	CreatedAt time.Time

	// UpdatedAt records the most recent transition time. Doubles as
	// the "entered current state at" timestamp, because every
	// transition updates it. Store.ListStuck filters on UpdatedAt
	// to surface Records that have been in a state too long (a
	// common watchdog pattern for the approved -> executed external
	// arc).
	//
	// UpdatedAt 记录最近一次 transition 时刻. 也兼作 "进入当前状态的
	// 时间" 戳 -- 每次 transition 都更新. Store.ListStuck 基于
	// UpdatedAt 过滤找出在某状态滞留过久的 Record (approved ->
	// executed 外部 arc 的常见 watchdog 模式).
	UpdatedAt time.Time

	// Metadata mirrors validator.DiffInput.Metadata at Record level.
	// Intended for caller-defined context: tenant id, priority tier,
	// correlation id for tracing, the "upstream record ids" field a
	// DependencyGuard implementation consults, etc. staging reads
	// none of it; it is forwarded verbatim through Store.
	//
	// Metadata 对齐 validator.DiffInput.Metadata 的 Record 级位.
	// 用于调用方定义的上下文: tenant id / 优先级 / 追踪 correlation
	// id / DependencyGuard 实现读取的 "上游 record id" 字段等等.
	// staging 不读取其中任何字段, Store 原样转发.
	Metadata map[string]any
}

type State string

type Store interface {
	// Stage persists a pending_tech Record and returns it with its
	// ID populated. The passed-in Record's State MUST be
	// pending_tech; any other state returns ErrIllegalTransition.
	// SessionID MUST be non-empty -- empty SessionID is a
	// programming error surfaced immediately.
	//
	// Stage 持久化 pending_tech Record 并回填 ID. 入参 Record 的
	// State 必须为 pending_tech, 其他状态返回 ErrIllegalTransition.
	// SessionID 必须非空 -- 空 SessionID 属编程错误立即暴露.
	Stage(ctx context.Context, r Record) (Record, error)

	// Get returns the Record with the given ID, or ErrRecordNotFound.
	//
	// Get 按 ID 返回 Record, 未找到返回 ErrRecordNotFound.
	Get(ctx context.Context, id string) (Record, error)

	// List returns Records matching q, ordered by CreatedAt ascending.
	// Empty Query returns everything (subject to the Store's default
	// upper bound -- see Query.Limit godoc).
	//
	// List 返回匹配 q 的 Record, 按 CreatedAt 升序. 空 Query 返回全部
	// (受 Store 默认上限约束 -- 见 Query.Limit godoc).
	List(ctx context.Context, q Query) ([]Record, error)

	// ListBySession is a convenience over List with Query{SessionID:
	// sessionID}. Returns Records of the given Agent session ordered
	// by CreatedAt. Distinct method because per-session lookups are
	// hot-path for audit UIs and deserve a named API.
	//
	// ListBySession 是 List 带 Query{SessionID: sessionID} 的便捷包装.
	// 返回指定 Agent session 的 Record, 按 CreatedAt 升序. 单独
	// 列出因为 per-session 查询是审计 UI 热路径, 值得专名.
	ListBySession(ctx context.Context, sessionID string) ([]Record, error)

	// ListStuck returns Records that have been in state for at
	// least olderThan duration, measured from Record.UpdatedAt
	// against time.Now(). Intended for platform-layer watchdogs:
	// approved Records that do not transition to executed/failed
	// within a business-defined SLA are the canonical use case
	// (decision Y's external-push arc has no internal timeout).
	//
	// ListStuck 返回在某状态滞留至少 olderThan 的 Record, 从
	// Record.UpdatedAt 对 time.Now() 测量. 用于平台层 watchdog:
	// approved Record 未在业务 SLA 内推进到 executed/failed 是典型
	// 场景 (决策 Y 的外部推 arc 无内置超时).
	ListStuck(ctx context.Context, state State, olderThan time.Duration) ([]Record, error)

	// UpdateTechVerdict transitions pending_tech -> rejected_tech or
	// pending_ml based on v.Approved and stamps v into
	// Record.TechVerdict. Returns ErrIllegalTransition if the
	// Record is not in pending_tech. UpdatedAt is refreshed.
	//
	// UpdateTechVerdict 按 v.Approved 把 pending_tech 推至
	// rejected_tech 或 pending_ml, 同时把 v 写入 Record.TechVerdict.
	// 当前状态非 pending_tech 返回 ErrIllegalTransition. UpdatedAt
	// 刷新.
	UpdateTechVerdict(ctx context.Context, id string, v validator.Verdict) (Record, error)

	// UpdateBizVerdict transitions pending_ml -> rejected_ml or
	// approved based on v.Approved and stamps v into
	// Record.BizVerdict. Returns ErrIllegalTransition if the
	// Record is not in pending_ml. UpdatedAt is refreshed.
	//
	// UpdateBizVerdict 按 v.Approved 把 pending_ml 推至 rejected_ml
	// 或 approved, 同时把 v 写入 Record.BizVerdict. 当前状态非
	// pending_ml 返回 ErrIllegalTransition. UpdatedAt 刷新.
	UpdateBizVerdict(ctx context.Context, id string, v validator.Verdict) (Record, error)

	// MarkExecuted transitions approved -> executed and stamps
	// proof into Record.ExecutionProof. Idempotent: second call on
	// executed Record returns the stored Record with the ORIGINAL
	// proof preserved and nil error (proof is written once at
	// first transition; subsequent calls do not overwrite).
	//
	// Other source states return ErrIllegalTransition (pending_*,
	// rejected_*) or ErrAlreadyFinal (failed).
	//
	// MarkExecuted 把 approved 推至 executed 并把 proof 写入
	// Record.ExecutionProof. 幂等: 对 executed Record 的二次调用返回
	// 存储记录 (保留首次 transition 时的 proof) 与 nil error --
	// proof 仅首次 transition 写入, 后续调用不覆盖.
	//
	// 其他源状态返回 ErrIllegalTransition (pending_* / rejected_*)
	// 或 ErrAlreadyFinal (failed).
	MarkExecuted(ctx context.Context, id string, proof any) (Record, error)

	// MarkFailed transitions approved -> failed and stamps reason
	// into Record.ExecutionError. Idempotent on already-failed
	// source (original reason preserved).
	//
	// Other source states return ErrIllegalTransition or
	// ErrAlreadyFinal (executed) per the same taxonomy as
	// MarkExecuted.
	//
	// MarkFailed 把 approved 推至 failed 并把 reason 写入
	// Record.ExecutionError. 对已 failed 源幂等 (保留原 reason).
	//
	// 其他源状态按 MarkExecuted 相同分类返回 ErrIllegalTransition
	// 或 ErrAlreadyFinal (executed).
	MarkFailed(ctx context.Context, id string, reason string) (Record, error)
}

type TenantDenyGuard struct {
	// BlockedTenants maps tenant id to bool (true = blocked).
	// A nil or empty map denies nothing.
	//
	// BlockedTenants 把 tenant id 映射到 bool (true = 被禁).
	// nil 或空 map 不拒任何 tenant.
	BlockedTenants map[string]bool
}