// Package staging manages the decision-package staging table that
// sits between an Agent's raw decision output and production commit.
// A single Record represents one Agent decision (product decision
// #1: one decision = one Record, not per tool call). A Record
// traverses a 7-state machine:
//
//	pending_tech -> rejected_tech | pending_ml
//	pending_ml   -> rejected_ml   | approved
//	approved     -> executed      | failed
//
// Transitions split into two control regimes (product decision Y):
//
//   - Internal, pulled by staging.Engine: draft staging calls the
//     tech-tier validator.Validator, then the biz-tier Validator, to
//     drive the first two rows. Engine owns the transition atomically.
//   - External, pushed by the platform layer: once a Record reaches
//     approved, the caller that actually writes to production (WMS
//     API, SQL commit, HTTP POST, ...) calls MarkExecuted or
//     MarkFailed on the Store to close the loop. core has no
//     authority over the production-write path, so it cannot drive
//     the final arc itself.
//
// Both tiers reuse validator.Validator (product decision X). A
// separate TechValidator / BizValidator interface would duplicate the
// same contract ("review a staged diff, emit a Verdict") and block
// reuse of reflector.EvaluatorAsValidator for customers who want to
// plug an Evaluator as either tier. Verdict.Score + Severity (Warn /
// Block) carry enough signal to express both "SQL ran but plan is
// poor" (Warn) and "ML scored 0.3" (Score=0.3 + Warn).
//
// Customers access staging through a pull-only API (product decision
// #5): core never pushes into customer databases. Query the Store
// on demand; build whatever integration (cron job, dashboard) fits.
//
// staging 管理决策包级的 staging 表, 位于 Agent 原始决策产出与生产
// commit 之间. 一条 Record 代表一次 Agent 决策 (产品决策 #1: 一次
// 决策 = 一条 Record, 不是每个工具调用一条). Record 走 7 状态机:
//
//	pending_tech -> rejected_tech | pending_ml
//	pending_ml   -> rejected_ml   | approved
//	approved     -> executed      | failed
//
// transition 分两种控制模式 (产品决策 Y):
//
//   - 内部, staging.Engine 主动拉动: draft staging 先调技术层
//     validator.Validator, 再调业务层 Validator, 推动前两行.
//     Engine 以原子 transition 拥有该步.
//   - 外部, 平台层主动推入: Record 到达 approved 后, 真正写生产
//     (WMS API / SQL commit / HTTP POST 等) 的调用方再调 Store 的
//     MarkExecuted 或 MarkFailed 闭环. core 对生产写路径无权限,
//     无法自行驱动最后一段 arc.
//
// 两层都复用 validator.Validator (产品决策 X). 另造
// TechValidator / BizValidator 只是复制同一契约 ("审 staged diff
// 产 Verdict"), 并且阻断客户把 Evaluator 经 reflector.EvaluatorAsValidator
// 适配进任一层. Verdict.Score + Severity (Warn / Block) 的组合足以
// 表达 "SQL 过了但 plan 差" (Warn) 与 "ML 打分 0.3" (Score=0.3 + Warn).
//
// 客户接入 staging 走 pull-only API (产品决策 #5): core 不向客户库
// 推送, 客户按需查 Store, 自己搭接集成 (cron / dashboard) 即可.
package staging