"""评分卡差分审计与涨幅停表（v7 机制第 3 项，纯函数 + 标准库 only）。 只做这一项，不碰其它 v7 机制项。本模块不改动 ``cloud/audit_loop_driver.py`` 的语义，也不改动 ``cloud/audit_scorecard.py``：它是评分卡侧的停表机制，不是 审计循环本身。审计循环的 pushback 上限 3、重建预算 1、 版本变更重置思路只作参考，不在本模块里复写或放宽。 三张表分开记分，绝不只记平均分 -------------------------------- 每轮 ledger 条目同时记 ``code`` / ``production`` / ``product`` 三张表各自的分数（任一表未知记 ``None``，不估算）。 ``average_for_reference_only`` 只作参考信息，停表判定只看 代码表（``code``），绝不用平均分判定——与 audit_scorecard “平均分绝不能作为达标依据”的规则一致。 阈值未拍板 ---------- ``STAGNATION_THRESHOLD`` 的值 0.5 标注 ``source="test_default_unapproved"``（测试默认值、未拍板）， 与 audit_scorecard 的 ``DEFAULT_THRESHOLDS`` 口径一致。 生产阈值须用户拍板后由调用方显式传入 ``threshold`` 才能替换； 本模块绝不把测试初值写成生产值，也不替用户决定 B/C 与阈值。 与已定语义的关系（本模块不改它们） ---------------------------------- - #238 ``evaluate_feedback`` 的 ``auto_apply`` 保持 False； 本模块没有 auto_apply 路径。 - #247 纠正为 pass 本身不解封；本模块不做解封、不做 re-audit、不碰门禁状态，只返回停表判定。 - v1.1 契约不变；本模块不增维、不改 7 维定义。 - 停表触发时返回 ``escalate`` 语义，不再自动推回： 结果里 ``auto_pushback`` 恒为 False，且 ``escalation_grants_user_acceptance`` 恒为 False （escalate 从不 tick 用户验收，与 audit_loop_driver 一致）。 (a) 差分范围输入：``audit_scope(baseline_snapshot, current_snapshot, claimed_fixed)`` ---------------------------------------------------------------- 快照形式（二选一，两种都接受）： - 文件路径集合：``set`` / ``list`` / ``tuple``，元素为路径字符串。 此时变更 = 对称差（新增 + 删除）；交集 = 未变更。 - 快照 dict：键为路径，值为内容指纹（hash/内容字符串），或 ``{"files": <路径集合或路径->指纹 dict>}`` 形式。 此时变更 = 新增 + 删除 + 同路径指纹不同（修改）；指纹相同 的路径 = 未变更。 审计范围 = 变更文件 + 调用方声称修好的项（``claimed_fixed``）。 未变更文件进 ``out_of_scope``，不进审计包；基线外（即不在 变更集内、也不在声称修好集内）的文件一律不进包。 ``claimed_fixed`` 是项 id（检查名/维 id 等字符串），不是文件 路径；它与文件集分开返回，调用方按项复核，不与文件混算。 (b) 涨幅 ledger：``ScorecardGainLedger``（内存）与 ``SqliteScorecardGainLedger``（SQLite） ------------------------------------------------ - 内存 ledger：append-only 列表，``append()`` 存规范化后的 条目副本，``rounds()`` 返回副本（调用方改返回结果不影响 已存条目）。模块级函数 ``append_round`` / ``read_rounds`` 接受 ledger 对象或普通 list，方便测试与调用方复用。 - SQLite ledger：同一列名、同一追加语义的 SQLite 表 ``scorecard_gain_rounds``（见 ``SQLITE_DDL``），用标准库 ``sqlite3``、``?`` 占位符。``PG_DDL`` 是与之列对应的 Postgres 建表语句文本，仅作仓库 DB 模式兼容写法： 真实 PG 在本项中不接通、不执行、不验证，只用 SQLite（内存或文件）测试并明说。 - 条目校验：``rubric_version`` 必须为非空字符串，否则 ``ValueError``；三张表分数各为 ``None`` 或 0-10 的数， 超范围或非数值 likewise ``ValueError``；bool 不算数值。 (c) 停表判定：``check_stagnation(history)`` -------------------------------------------- - 只看 trailing 同 rubric_version 序列：从最新一轮往回取 与最新轮 ``rubric_version`` 相同的连续轮次；改标尺即新 序列，旧标尺的轮次不连算。 - 该序列内相邻两轮代码表分数之差为一轮涨幅；分数为 1 位 小数（与 audit_scorecard 的 _round1 一致），涨幅按 1 位小数舍入后再与阈值比较，避免 8.8-8.3 这类二进制 浮点残差把恰好 0.5 误判为 <0.5。 - 涨幅 < 阈值（含负涨幅，即代码表下滑）记为小涨幅； 涨幅 >= 阈值，或涨幅未知（任一端分数为 None），打断 连续计数。连续两轮小涨幅（即该序列内最近两次涨幅 均为小涨幅，至少需要 3 轮）即触发停表。 - 触发返回 ``{"decision": "escalate", "reason": "stagnation", ...}``； 未触发返回 ``{"decision": "continue", ...}``。两种结果都 不含 pushback 动作；触发时 ``auto_pushback`` 为 False。 """ from __future__ import annotations import sqlite3 from cloud.db import connect as _db_connect TABLES = ("code", "production", "product") # 停表阈值：测试默认值、未拍板。生产阈值须用户拍板后显式传入。 STAGNATION_THRESHOLD = {"value": 0.5, "source": "test_default_unapproved"} # 触发所需连续小涨幅轮数（2 次小涨幅 = 序列内至少 3 轮）。 STAGNATION_CONSECUTIVE_GAINS = 2 SQLITE_DDL = ( "CREATE TABLE IF NOT EXISTS scorecard_gain_rounds (" "id INTEGER PRIMARY KEY AUTOINCREMENT, " "rubric_version TEXT NOT NULL, " "code REAL, " "production REAL, " "product REAL, " "average_for_reference_only REAL" ")" ) # 与 SQLITE_DDL 列对应的 Postgres 建表文本。仅作模式兼容写法， # 本项不接通真实 PG、不执行、不验证；测试只覆盖 SQLite。 PG_DDL = ( "CREATE TABLE IF NOT EXISTS scorecard_gain_rounds (" "id SERIAL PRIMARY KEY, " "rubric_version TEXT NOT NULL, " "code DOUBLE PRECISION, " "production DOUBLE PRECISION, " "product DOUBLE PRECISION, " "average_for_reference_only DOUBLE PRECISION" ")" ) # ------------------------------------------------------------------ # (a) 差分范围输入 # ------------------------------------------------------------------ def _fingerprint(value): """快照 dict 值的规范指纹：hash/sha256/content 字段优先，否则原值。""" if isinstance(value, dict): for key in ("sha256", "hash", "content"): if value.get(key) is not None: return value[key] return repr(sorted(value.items())) return value def _snapshot_mapping(snapshot): """把快照归一化为 {路径: 指纹或 None}。 路径集合形式：指纹为 None（只比存在性）。 快照 dict 形式：键为路径，值为指纹；{"files": ...} 形式先解包。 None 快照视为空快照。 """ if snapshot is None: return {} if isinstance(snapshot, dict): inner = snapshot.get("files", snapshot) if "files" in snapshot else snapshot if isinstance(inner, dict): return {str(path): _fingerprint(value) for path, value in inner.items()} if isinstance(inner, (set, list, tuple)): return {str(path): None for path in inner} raise TypeError("snapshot files must be a mapping or a path collection") if isinstance(snapshot, (set, list, tuple)): return {str(path): None for path in snapshot} raise TypeError("snapshot must be a path collection, a mapping, or None") def _normalize_claimed(claimed_fixed): """声称修好的项：None -> []；单个字符串 -> [它]；否则去重排序。""" if claimed_fixed is None: return [] if isinstance(claimed_fixed, str): return [claimed_fixed] return sorted({str(item) for item in claimed_fixed}) def audit_scope(baseline_snapshot, current_snapshot, claimed_fixed=None): """算出差分审计范围。 返回 {"in_scope": {"files": [...], "claimed_fixed": [...]}, "out_of_scope": {"files": [...]}}。 in_scope.files = 变更文件（新增 + 删除 + 修改）； out_of_scope.files = 两快照中都出现且指纹相同（路径集合 形式下即交集）的未变更文件；claimed_fixed 原样进包， 与文件集分开，不因文件未变更而被排除。 """ baseline = _snapshot_mapping(baseline_snapshot) current = _snapshot_mapping(current_snapshot) # 以存在性为准：只在一侧出现的路径必为变更；路径集合形式下 # 指纹均为 None，不能只比指纹（缺失侧 get 缺省也是 None， # 会把新增/删除误判为未变更），故先判存在性再比指纹。 changed = sorted( path for path in set(baseline) | set(current) if path not in baseline or path not in current or baseline[path] != current[path] ) unchanged = sorted( path for path in set(baseline) & set(current) if baseline[path] == current[path] ) return { "in_scope": { "files": changed, "claimed_fixed": _normalize_claimed(claimed_fixed), }, "out_of_scope": {"files": unchanged}, } # ------------------------------------------------------------------ # (b) 涨幅 ledger：条目规范化 # ------------------------------------------------------------------ def _is_number(value): return isinstance(value, (int, float)) and not isinstance(value, bool) def normalize_round(rubric_version, code=None, production=None, product=None, entry=None): """规范化一轮 ledger 条目（返回新 dict，不修改入参）。 接受两种调用：显式三表分数，或 entry dict（含 flat 的 code/production/product，或嵌套的 scores dict）。 平均分只在三表全已知时算出，且只作参考，永不用于停表。 """ if entry is not None: if not isinstance(entry, dict): raise TypeError("entry must be a dict") scores = entry.get("scores") if isinstance(entry.get("scores"), dict) else entry rubric_version = entry.get("rubric_version", rubric_version) code = scores.get("code", code) if code is None else code production = scores.get("production", production) if production is None else production product = scores.get("product", product) if product is None else product if not isinstance(rubric_version, str) or not rubric_version: raise ValueError("rubric_version must be a non-empty string") values = {} for name, value in (("code", code), ("production", production), ("product", product)): if value is None: values[name] = None elif _is_number(value) and 0 <= float(value) <= 10: values[name] = round(float(value) + 1e-9, 1) else: raise ValueError("%s must be None or a number in 0..10, got %r" % (name, value)) known = [values[name] for name in TABLES] average = round(sum(known) / len(known) + 1e-9, 1) if all(v is not None for v in known) else None return { "rubric_version": rubric_version, "code": values["code"], "production": values["production"], "product": values["product"], "average_for_reference_only": average, "average_is_not_pass_criterion": True, } class ScorecardGainLedger: """内存涨幅 ledger：append-only，存条目副本，读出副本。""" def __init__(self): self._rounds = [] def append(self, rubric_version=None, code=None, production=None, product=None, entry=None): normalized = normalize_round(rubric_version, code, production, product, entry) self._rounds.append(normalized) return dict(normalized) def rounds(self): return [dict(entry) for entry in self._rounds] # history() 是 rounds() 的别名，供 check_stagnation 直接接受 ledger。 def history(self): return self.rounds() def append_round(ledger, rubric_version=None, code=None, production=None, product=None, entry=None): """向 ledger 追加一轮：ledger 对象（有 .append）或普通 list 均可。""" normalized = normalize_round(rubric_version, code, production, product, entry) if hasattr(ledger, "append") and not isinstance(ledger, list): # ledger 对象自身的 append 已做规范化；为避免双重规范化 # 带来的舍入差异，这里直接传规范化后的 entry。 ledger.append(entry=normalized) return dict(normalized) ledger.append(normalized) return dict(normalized) def read_rounds(ledger): """读出 ledger 全部轮次副本：ledger 对象（有 .rounds）或 list 均可。""" if hasattr(ledger, "rounds"): return [dict(entry) for entry in ledger.rounds()] return [dict(entry) for entry in ledger] class SqliteScorecardGainLedger: """SQLite 涨幅 ledger：与内存 ledger 同列、同追加语义。 db_path 为 ":memory:"（默认）或文件路径；传入 sqlite3 连接亦可（此时 close() 不关闭调用方连接）。真实 PG 不接通：PG_DDL 只是模式兼容文本，不在本类中执行。 """ def __init__(self, db_path=":memory:", connection=None): if connection is not None: self._conn = connection self._owns_conn = False else: # 层规则：服务层不得直连驱动，须走 cloud.db.connect # （其 SQLite 路径已设 WAL + busy_timeout + Row）。 self._conn = _db_connect(str(db_path)) self._owns_conn = True self._conn.execute(SQLITE_DDL) self._conn.commit() def append(self, rubric_version=None, code=None, production=None, product=None, entry=None): normalized = normalize_round(rubric_version, code, production, product, entry) self._conn.execute( "INSERT INTO scorecard_gain_rounds" " (rubric_version, code, production, product, average_for_reference_only)" " VALUES (?, ?, ?, ?, ?)", (normalized["rubric_version"], normalized["code"], normalized["production"], normalized["product"], normalized["average_for_reference_only"]), ) self._conn.commit() return dict(normalized) def rounds(self): rows = self._conn.execute( "SELECT rubric_version, code, production, product," " average_for_reference_only FROM scorecard_gain_rounds ORDER BY id" ).fetchall() out = [] for row in rows: mapping = dict(row) if isinstance(row, sqlite3.Row) else dict(row) entry = { "rubric_version": mapping["rubric_version"], "code": mapping["code"], "production": mapping["production"], "product": mapping["product"], "average_for_reference_only": mapping["average_for_reference_only"], "average_is_not_pass_criterion": True, } out.append(entry) return out def history(self): return self.rounds() def close(self): if self._owns_conn: self._conn.close() # ------------------------------------------------------------------ # (c) 停表判定 # ------------------------------------------------------------------ def _history_entries(history): """接受 list/tuple 或 ledger 对象（有 .rounds/.history），返回条目 list。""" if history is None: return [] if hasattr(history, "rounds"): return list(history.rounds()) if hasattr(history, "history"): return list(history.history()) return list(history) def _code_score(entry): """取一轮的代码表分数：flat 的 code，或嵌套 scores.code；缺失为 None。""" if not isinstance(entry, dict): return None if entry.get("code") is not None: return entry["code"] scores = entry.get("scores") if isinstance(scores, dict): return scores.get("code") return None def _trailing_run(entries): """最新 rubric_version 的 trailing 连续序列（改标尺即新序列）。""" if not entries: return [] latest_version = entries[-1].get("rubric_version") if isinstance(entries[-1], dict) else None run = [] for entry in reversed(entries): version = entry.get("rubric_version") if isinstance(entry, dict) else None if version != latest_version: break run.append(entry) run.reverse() return run def code_gains(history): """trailing 同标尺序列内相邻两轮的代码表涨幅 list。 每项为 1 位小数舍入后的涨幅，或 None（任一端分数未知）。 全序列的涨幅不返回：旧标尺轮次不连算。 """ run = _trailing_run(_history_entries(history)) scores = [_code_score(entry) for entry in run] gains = [] for prev_score, cur_score in zip(scores, scores[1:]): if prev_score is None or cur_score is None: gains.append(None) elif not _is_number(prev_score) or not _is_number(cur_score): gains.append(None) else: gains.append(round(float(cur_score) - float(prev_score) + 1e-9, 1)) return gains def _resolve_threshold(threshold): """阈值解析：None -> 测试默认值；数字 -> 该值（来源仍标测试默认， 除非调用方显式传 {"value":..., "source": "user_approved"}）； dict -> 取 value/source。""" if threshold is None: return STAGNATION_THRESHOLD["value"], STAGNATION_THRESHOLD["source"] if isinstance(threshold, dict): return threshold.get("value", STAGNATION_THRESHOLD["value"]), threshold.get( "source", STAGNATION_THRESHOLD["source"]) return threshold, STAGNATION_THRESHOLD["source"] def check_stagnation(history, threshold=None): """停表判定：trailing 同标尺序列内连续两轮代码表涨幅 < 阈值即停。 触发返回 decision="escalate"、reason="stagnation"，且 auto_pushback=False（不再自动推回）； 未触发返回 decision="continue"。两种结果的 escalation_grants_user_acceptance 均为 False。 """ threshold_value, threshold_source = _resolve_threshold(threshold) entries = _history_entries(history) run = _trailing_run(entries) gains = code_gains(entries) consecutive = 0 for gain in reversed(gains): if gain is not None and gain < threshold_value: consecutive += 1 else: break latest_version = run[-1].get("rubric_version") if run else None base = { "rubric_version": latest_version, "run_rounds": len(run), "code_gains": gains, "consecutive_small_gains": consecutive, "threshold": threshold_value, "threshold_source": threshold_source, "auto_pushback": False, "escalation_grants_user_acceptance": False, } if consecutive >= STAGNATION_CONSECUTIVE_GAINS: result = {"decision": "escalate", "reason": "stagnation"} result.update(base) return result result = {"decision": "continue", "reason": "not_stagnant"} result.update(base) return result