refactor: add CHECK constraints and drop redundant index in v3 tables

app/question_gen/run_store.py

@@ -183,7 +183,7 @@ CREATE TABLE IF NOT EXISTS facts (
     fact_type          TEXT,
     difficulty_tier    INTEGER,
     verifier_refs      TEXT,
-    cross_agree        INTEGER,
+    cross_agree        INTEGER CHECK(cross_agree IN (0, 1)),
     negative_at_target TEXT,
     session_id         TEXT,
     ts                 TEXT
@@ -195,8 +195,8 @@ CREATE TABLE IF NOT EXISTS unit_verdict (
     unit_id      TEXT NOT NULL,
     pair_id      TEXT,
     sub_pattern  TEXT,
-    stage        INTEGER NOT NULL,
-    verdict      TEXT,
+    stage        INTEGER NOT NULL CHECK(stage BETWEEN 1 AND 6),
+    verdict      TEXT CHECK(verdict IN ('pass', 'fail', 'abstain')),
     reason       TEXT,
     metric_value REAL,
     model        TEXT,
@@ -234,7 +234,7 @@ CREATE TABLE IF NOT EXISTS quarantine (
 _DDL_RESUME_STATE = """
 CREATE TABLE IF NOT EXISTS resume_state (
     unit_id            TEXT PRIMARY KEY,
-    status             TEXT,
+    status             TEXT CHECK(status IN ('pending', 'accepted', 'rejected')),
     config_fingerprint TEXT,
     seq_offset         INTEGER
 );
@@ -251,7 +251,7 @@ _DDL_V3_TABLES = [
 _DDL_V3_INDEXES = [
     "CREATE INDEX IF NOT EXISTS idx_facts_video ON facts(video_id);",
     "CREATE INDEX IF NOT EXISTS idx_facts_session ON facts(session_id);",
-    "CREATE INDEX IF NOT EXISTS idx_uv_unit ON unit_verdict(unit_id);",
+    # unit_verdict(unit_id) 无需独立索引：主键 (unit_id, stage) 的左前缀已覆盖 unit_id 查询。
     "CREATE INDEX IF NOT EXISTS idx_uv_sub_pattern ON unit_verdict(sub_pattern);",
     "CREATE INDEX IF NOT EXISTS idx_quar_sub_pattern ON quarantine(sub_pattern);",
     "CREATE INDEX IF NOT EXISTS idx_resume_status ON resume_state(status);",
@@ -848,6 +848,10 @@ class QuestionGenStore:
         同一 (unit_id, stage) 重跑时以 upsert 覆盖旧行——每 unit 每层仅保留最新一条，
         便于断点续跑重放而不残留过期裁决。
 
+        覆盖语义：ON CONFLICT DO UPDATE 用 ``excluded.*`` **整行覆盖**全部非键列
+        （含可空的 metric_value/model 及 ts）——只保留每层最新完整裁决，不支持部分字段
+        更新。调用方每次必须传完整行，否则会用 metric_value=None/model=None 误抹先前非空值。
+
         Parameters
         ----------
         unit_id : str
@@ -921,6 +925,9 @@ class QuestionGenStore:
 
         同一 pair_id 重算时以 upsert 覆盖旧行——每 pair 仅保留最新一组度量。
 
+        覆盖语义：ON CONFLICT DO UPDATE 用 ``excluded.*`` **整行覆盖**全部非键列（含 ts），
+        不支持部分字段更新；调用方每次必须传完整度量行。
+
         Parameters
         ----------
         pair_id : str
@@ -980,7 +987,8 @@ class QuestionGenStore:
         """将失败题的内容指纹写入隔离区黑名单（quarantine 表，主键 content_fingerprint）。
 
         同一 content_fingerprint 重复调用以 upsert 覆盖——保证语义相同题面只占一行，
-        补构造前查此表当黑名单去重。
+        补构造前查此表当黑名单去重。覆盖语义：ON CONFLICT DO UPDATE 用 ``excluded.*``
+        **整行覆盖**全部非键列（含 ts），不支持部分字段更新。
 
         Parameters
         ----------
@@ -1025,6 +1033,9 @@ class QuestionGenStore:
         由调用方据此判定旧进度作废并重跑。本表无 ts 列（schema 未定义），但方法体仍禁
         进程内 now，保持 v3 观测一致的幂等可复现语义。
 
+        覆盖语义：ON CONFLICT DO UPDATE 用 ``excluded.*`` **整行覆盖**全部非键列，不支持
+        部分字段更新；调用方每次必须传完整状态行。
+
         Parameters
         ----------
         unit_id : str