yumoqing/pbl_runtime_ext
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

deliver: 交付收口（引擎代为提交）

Browse Source
This commit is contained in:
agent.develop 2026-09-19 13:07:15 +08:00
parent af83f15b37
commit e660480fcb
11 changed files with 2054 additions and 2087 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
pbl_runtime_ext/__init__.py
View File

@ -6,7 +6,46 @@
包出口： 包出口：
from pbl_runtime_ext.init import load_pbl_runtime_ext from pbl_runtime_ext.init import load_pbl_runtime_ext
M11b 契约（必须与 init.py 的 env 注册、m11b_api.py 的实现三处同步，缺一即 NameError）：
apply_runtime_event / poll_events / read_states / assert_append_only
pbl_runtime_broadcast_pull / pbl_runtime_broadcast_stats
""" """
__all__ = ["init", "tables", "tx_event", "api"] from .init import load_pbl_runtime_ext # noqa: F401 包出口（挂载唯一入口）
__version__ = "1.0.0"
# ---- M11a ----
from .tables import TABLES, ensure_tables, self_check as tables_self_check # noqa: F401
from .tx_event import (TxError, append_event, find_by_idem, list_events, # noqa: F401
next_seq)
# ---- M11b：实现定义 + 包导出 + init.py env 注册（三处同步）----
from .m11b_config import (EVENT_TABLE, SLA_ADJUDICATE_MS, SLA_BROADCAST_MS, # noqa: F401
SLA_END_TO_END_MS, POLL_FALLBACK_MS, STATE_TABLE,
SNAPSHOT_TABLE, contracts, sla_ms)
from .rtx_db import (RtxError, dbname, q_all, q_one, transaction) # noqa: F401
from .partitions import ensure_forward_partitions # noqa: F401
from .broadcast import BroadcastHub, channel_of, get_hub # noqa: F401
from .latency import LatencyTracker, Timer, summary as latency_summary # noqa: F401
from .tx_write import (apply_runtime_event, assert_append_only, # noqa: F401
idem_key_of, poll_events, read_states)
from .m11b_api import (pbl_runtime_broadcast_pull, # noqa: F401
pbl_runtime_broadcast_stats)
__all__ = [
# 挂载
"load_pbl_runtime_ext", "TABLES", "ensure_tables", "tables_self_check",
# M11a
"TxError", "append_event", "find_by_idem", "list_events", "next_seq",
# M11b 契约
"apply_runtime_event", "poll_events", "read_states", "assert_append_only",
"pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats",
"idem_key_of", "contracts",
# M11b 基础设施
"RtxError", "dbname", "q_all", "q_one", "transaction",
"ensure_forward_partitions", "BroadcastHub", "channel_of", "get_hub",
"LatencyTracker", "Timer", "latency_summary", "sla_ms",
"EVENT_TABLE", "STATE_TABLE", "SNAPSHOT_TABLE",
"SLA_ADJUDICATE_MS", "SLA_BROADCAST_MS", "SLA_END_TO_END_MS", "POLL_FALLBACK_MS",
]
__version__ = "1.1.0"

47
pbl_runtime_ext/api.py
View File

@ -241,30 +241,47 @@ async def pbl_session_member_add(**kw):
return {'ok': True, 'members': cnt + 1, 'max_members': MAX_MEMBERS, 'deduped': False} return {'ok': True, 'members': cnt + 1, 'max_members': MAX_MEMBERS, 'deduped': False}
# ================================================================== M11b 覆盖 # ================================================================== M11b 契约汇总
# M11b（单事务事件+状态写入、按月分区、提交后广播、3s 轮询兜底）是**权威实现**： # M11b（单事务事件+状态写入、按月 RANGE 分区、提交后广播、3s 轮询兜底）的**权威实现**在：
# 同名契约在此覆盖上方 M11a 版本，避免两套逻辑漂移；返回结构向后兼容（只增字段）。 # tx_write.py apply_runtime_event / poll_events / read_states / assert_append_only
# 主链路：m11b_api → tx_write.apply_runtime_event（一个事务写 事件+实体状态+快照 # m11b_api.py pbl_runtime_broadcast_pull / pbl_runtime_broadcast_stats（协程包装）
# → 提交后才广播 → 分段计时裁决/广播/端到端并与 SLA 预算比对）。 # broadcast.py 提交后扇出 + 每通道环形缓冲；partitions.py 月分区预建；
from .m11b_api import ( # noqa: E402 契约层覆盖（放最后，导入即生效） # rtx_db.py 规范 sqlor 入口 + 单事务（探测不到 begin/commit/rollback 即 fail-closed）
contracts as m11b_contracts, # 本文件上方 6 个函数是 M11a 的 dspy 契约（走 pbl_common 适配的 sql_exec/sql_rows），
pbl_entity_state_apply, # 保留以向后兼容；本段**只再导出** M11b 新契约并汇总 CONTRACTS 清单，不重复实现，
pbl_entity_state_get, # 避免两套逻辑漂移（QC #5：本段改动要点 = 修正原先从 m11b_api 导入 5 个不存在的
pbl_runtime_broadcast_pull, # 名字 pbl_entity_state_apply/pbl_entity_state_get/pbl_runtime_event_append/
pbl_runtime_event_append, # pbl_runtime_event_poll/pbl_world_broadcast 导致的 ImportError，并去掉
# pbl_runtime_broadcast_pull 的重复导入行）。
#
# 铁律（QC #1）：新增契约必须三处同步 —— ① 实现（tx_write/m11b_api）
# ② 包导出（__init__.py）③ env 注册（init.py._registrations / M11B_ENV_REGISTRATIONS）。
# init.py 挂载时按清单核对，漏项直接 RuntimeError 拒绝启动，不留到线上 NameError。
from .m11b_api import ( # noqa: E402 仅再导出 m11b_api 中真实存在的名字
apply_runtime_event,
assert_append_only,
poll_events,
pbl_runtime_broadcast_pull, pbl_runtime_broadcast_pull,
pbl_runtime_broadcast_stats, pbl_runtime_broadcast_stats,
pbl_runtime_event_poll, read_states,
pbl_world_broadcast,
) )
from .m11b_config import sla_ms # noqa: E402
CONTRACTS = { CONTRACTS = {
# M11a（dspy 端点，向后兼容）
"pbl_runtime_event_append": pbl_runtime_event_append, "pbl_runtime_event_append": pbl_runtime_event_append,
"pbl_runtime_event_poll": pbl_runtime_event_poll, "pbl_runtime_event_poll": pbl_runtime_event_poll,
"pbl_runtime_broadcast_pull": pbl_runtime_broadcast_pull,
"pbl_runtime_broadcast_stats": pbl_runtime_broadcast_stats,
"pbl_entity_state_get": pbl_entity_state_get, "pbl_entity_state_get": pbl_entity_state_get,
"pbl_entity_state_apply": pbl_entity_state_apply, "pbl_entity_state_apply": pbl_entity_state_apply,
"pbl_world_broadcast": pbl_world_broadcast, "pbl_world_broadcast": pbl_world_broadcast,
"pbl_session_member_add": pbl_session_member_add, "pbl_session_member_add": pbl_session_member_add,
# M11b（新增 dspy 端点 + 内部契约）
"pbl_runtime_broadcast_pull": pbl_runtime_broadcast_pull,
"pbl_runtime_broadcast_stats": pbl_runtime_broadcast_stats,
"apply_runtime_event": apply_runtime_event,
"poll_events": poll_events,
"read_states": read_states,
"assert_append_only": assert_append_only,
} }
M11B_SLA = sla_ms()

394
pbl_runtime_ext/broadcast.py
View File

@ -1,245 +1,150 @@
"""M11b 提交后广播（post-commit broadcast）+ 3s 轮询兜底。 # -*- coding: utf-8 -*-
"""broadcast —— 进程内广播枢纽（**提交后**才发布，M11b）。
铁律与语义 铁律：
---------- 1. 只有 ``publish_after_commit`` 被调用（即事务已 commit）才向订阅者扇出，
1. **只在事务提交成功后广播**：广播内容必须是已落库的事实。提交失败绝不广播， 杜绝「事件回滚了但客户端已收到」的幽灵更新。
否则客户端会收到数据库里不存在的状态（幽灵更新，无法收敛）。 2. 每通道环形缓冲（默认 512 条），让 3s 轮询兜底（poll_events）能命中内存，
2. **广播是尽力而为（best-effort），不是投递保证**：推送通道（websocket/SSE） 未命中或有缺口时由调用方退回查库。
抖动、进程重启都可能丢事件。丢广播**不撤销已提交事实**，客户端用 3. 扇出耗时打点，对照 SLA_BROADCAST_MS=300ms；超阈值记入 stats 供 QC 复核。
`since_seq` 轮询补齐（兜底周期 3s），保证最终一致、不丢数据。 4. 本模块零外部依赖（纯内存 + asyncio），不碰数据库，因此可离线单测。
3. **环形缓冲**：每个会话在内存里保留最近 N 条已提交事件，供
`pbl_runtime_broadcast_pull` 做毫秒级增量拉取（比查库轻），
缓冲被覆盖时客户端自动退回查库轮询（poll 契约），不会漏。
4. 广播耗时计入 SLA（≤300ms）：推送在后台线程做，主请求只负责入队 +
记录 accepted；`pull` 契约用于验证「事件确实可被消费」。
线程安全：所有状态变更都在 RLock 下；推送回调在后台 worker 线程执行，
回调异常只计数不影响主链路。
""" """
import collections
import logging import inspect
import threading import threading
import time import time
from collections import deque
from .m11b_config import ( from .m11b_config import (CHANNEL_PREFIX, HUB_BUFFER_PER_CHANNEL, HUB_MAX_CHANNELS,
BROADCAST_QUEUE_SIZE, SLA_BROADCAST_MS)
BROADCAST_THREADS,
POLL_FALLBACK_INTERVAL_MS,
SLA_BROADCAST_MS,
)
log = logging.getLogger("pbl_runtime_ext.broadcast")
def _now_ms(): def channel_of(world_id, tenant_id):
return int(time.time() * 1000) """通道命名：pbl.world.<tenant>.<world>（租户隔离在通道层就生效）。"""
return "%s.%s.%s" % (CHANNEL_PREFIX, tenant_id, world_id)
class _Worker(object):
"""极简后台推送线程（daemon），避免引入线程池依赖。"""
def __init__(self, hub, idx):
self.hub = hub
self.idx = idx
self.stop = threading.Event()
self.thread = threading.Thread(
target=self._run, name="pbl-bcast-%d" % idx)
self.thread.daemon = True
def start(self):
try:
self.thread.start()
except Exception as exc: # noqa: BLE001
log.warning("广播 worker 启动失败（退回纯轮询）: %s", exc)
def _run(self):
while not self.stop.is_set():
item = self.hub._next_job()
if item is None:
self.stop.wait(0.01)
continue
self.hub._deliver(*item)
class BroadcastHub(object): class BroadcastHub(object):
"""会话级广播中心：入队 → 后台推送 → 环形缓冲供 pull/轮询补齐。""" """环形缓冲 + 订阅者扇出。线程安全（多 worker 各自持有，跨进程由 DB 轮询兜底）。"""
def __init__(self, capacity=BROADCAST_QUEUE_SIZE, workers=BROADCAST_THREADS): def __init__(self, buffer_size=None, max_channels=None):
self._buffer_size = int(buffer_size or HUB_BUFFER_PER_CHANNEL)
self._max_channels = int(max_channels or HUB_MAX_CHANNELS)
self._lock = threading.RLock() self._lock = threading.RLock()
self._cond = threading.Condition(self._lock) self._buffers = {} # channel -> deque[event]
self._queue = collections.deque(maxlen=int(capacity)) self._subs = {} # channel -> set(callback)
self._buffers = {} # session_key -> deque(events) self._seq = 0 # 全局单调游标（poll 增量依据）
self._capacity = int(capacity) self.published = 0
self._pushers = [] # [(name, callable)] self.subscriber_errors = 0
self._stats = { self.latencies_ms = deque(maxlen=200)
"published": 0, "delivered": 0, "push_failed": 0, self.sla_breaches = 0
"pulls": 0, "pull_hit": 0, "pull_miss": 0,
"sla_breached": 0, "last_broadcast_ms": 0, "max_broadcast_ms": 0,
}
self._workers = []
if workers and int(workers) > 0:
for i in range(int(workers)):
w = _Worker(self, i)
w.start()
self._workers.append(w)
# -------------------------------------------------- 通道注册 # -- 订阅 -------------------------------------------------------------
def register_push(self, fn, name="custom"): def subscribe(self, channel, cb):
"""注册推送通道（ws/sse）。fn(session_key, event) -> truthy/awaitable。"""
if not callable(fn):
raise TypeError("push 回调必须可调用")
with self._lock: with self._lock:
self._pushers.append((name, fn)) self._subs.setdefault(channel, set()).add(cb)
return name return cb
def unregister_push(self, name): def unsubscribe(self, channel, cb):
with self._lock: with self._lock:
self._pushers = [(n, f) for (n, f) in self._pushers if n != name] self._subs.get(channel, set()).discard(cb)
# -------------------------------------------------- 发布 def channels(self):
def publish(self, session_key, event):
"""提交后调用：先入环形缓冲（保证可被 pull 到），再排入推送队列。
返回 {"accepted", "buffered", "channel", "seq_no", "pull_deadline_ms"}。
本方法不阻塞等待推送结果 —— 广播预算 ≤300ms 包含推送，主链路只记账号。
"""
t0 = _now_ms()
with self._lock: with self._lock:
buf = self._buffers.setdefault( return sorted(self._buffers.keys())
str(session_key), collections.deque(maxlen=self._capacity))
buf.append(event) # -- 发布（提交后）----------------------------------------------------
self._stats["published"] += 1 def publish(self, channel, event):
channels = [n for n, _f in self._pushers] """把已提交事件放入缓冲并扇出。返回广播延迟 ms。"""
self._queue.append((session_key, event, t0)) t0 = time.perf_counter()
with self._lock:
self._seq += 1
evt = dict(event or {})
evt["cursor"] = self._seq
evt["channel"] = channel
evt.setdefault("published_at", time.time())
buf = self._buffers.get(channel)
if buf is None:
if len(self._buffers) >= self._max_channels:
# 通道数上限：淘汰最久未用通道（防内存无限增长）
oldest = next(iter(self._buffers))
self._buffers.pop(oldest, None)
self._subs.pop(oldest, None)
buf = deque(maxlen=self._buffer_size)
self._buffers[channel] = buf
buf.append(evt)
self.published += 1
subs = list(self._subs.get(channel, ()))
for cb in subs:
try: try:
self._cond.notify() r = cb(evt)
if inspect.isawaitable(r):
close = getattr(r, "close", None)
if callable(close):
close() # 不在此处 await：交给事件循环的订阅者自行调度
except Exception: # noqa: BLE001 except Exception: # noqa: BLE001
pass
accepted = bool(channels)
# 无后台 worker（降级/自检模式）时同步投递，保证广播语义仍然成立
if not self._workers and channels:
self._deliver(session_key, event, t0)
cost = _now_ms() - t0
with self._lock:
self._stats["last_broadcast_ms"] = cost
self._stats["max_broadcast_ms"] = max(self._stats["max_broadcast_ms"], cost)
if cost > SLA_BROADCAST_MS:
self._stats["sla_breached"] += 1
return {"accepted": accepted, "buffered": True,
"channel": "websocket" if accepted else "poll_fallback",
"channels": channels,
"seq_no": (event or {}).get("seq_no"),
"enqueue_ms": cost,
"budget_ms": SLA_BROADCAST_MS,
"pull_fallback_interval_ms": POLL_FALLBACK_INTERVAL_MS}
publish_event = publish # 兼容别名
# -------------------------------------------------- 消费（pull）
def pull(self, session_key, since_seq=0, limit=200):
"""从环形缓冲拉增量。miss（缓冲已覆盖）时返回 need_poll=True，
客户端据此退回查库轮询契约（pbl_runtime_event_poll）。
"""
since = int(since_seq or 0)
lim = max(1, min(int(limit or 200), 500))
with self._lock:
self._stats["pulls"] += 1
buf = self._buffers.get(str(session_key))
if not buf:
self._stats["pull_miss"] += 1
return {"events": [], "count": 0, "last_seq": since,
"buffered": False, "need_poll": True,
"poll_interval_ms": POLL_FALLBACK_INTERVAL_MS}
events = [e for e in buf if int(e.get("seq_no") or 0) > since]
events = events[:lim]
oldest = int(buf[0].get("seq_no") or 0) if buf else 0
covered = (not events) or (oldest <= since + 1) or (since == 0)
last_seq = int(events[-1].get("seq_no")) if events else since
if events:
self._stats["pull_hit"] += 1
if not covered:
self._stats["pull_miss"] += 1
else:
self._stats["pull_hit"] += 0
return {"events": events, "count": len(events), "last_seq": last_seq,
"buffered": True, "need_poll": not covered,
"poll_interval_ms": POLL_FALLBACK_INTERVAL_MS}
def buffered_events(self, session_key):
with self._lock:
return list(self._buffers.get(str(session_key), []))
def forget(self, session_key):
"""会话结束时释放内存缓冲。"""
with self._lock:
self._buffers.pop(str(session_key), None)
# -------------------------------------------------- 内部推送
def _next_job(self):
with self._cond:
if not self._queue:
return None
return self._queue.popleft()
def _deliver(self, session_key, event, enqueued_ms=None):
ok_any = False
for name, fn in list(self._pushers_snapshot()):
try:
res = fn(session_key, event)
if hasattr(res, "__await__"):
res = _run_coro(res)
if res is None or res is False:
raise RuntimeError("push 返回 %r" % (res,))
ok_any = True
except Exception as exc: # noqa: BLE001
log.warning("广播通道 %s 投递失败（客户端 3s 轮询补齐）: %s", name, exc)
with self._lock: with self._lock:
self._stats["push_failed"] += 1 self.subscriber_errors += 1
if ok_any: elapsed = (time.perf_counter() - t0) * 1000.0
with self._lock:
self._stats["delivered"] += 1
if enqueued_ms is not None:
cost = _now_ms() - int(enqueued_ms)
with self._lock:
self._stats["last_broadcast_ms"] = cost
self._stats["max_broadcast_ms"] = max(self._stats["max_broadcast_ms"], cost)
if cost > SLA_BROADCAST_MS:
self._stats["sla_breached"] += 1
return ok_any
def _pushers_snapshot(self):
with self._lock: with self._lock:
return list(self._pushers) self.latencies_ms.append(round(elapsed, 3))
if elapsed > SLA_BROADCAST_MS:
self.sla_breaches += 1
return elapsed
# -------------------------------------------------- 观测 # -- 拉取 -------------------------------------------------------------
def pull(self, channel, after_cursor=None, limit=200):
"""从环形缓冲取增量。返回 (events, truncated)；
truncated=True 表示请求游标早于缓冲最旧记录（有缺口），调用方须退回查库。"""
limit = max(1, min(int(limit or 200), self._buffer_size))
with self._lock:
buf = self._buffers.get(channel)
if not buf:
return [], False
events = list(buf)
oldest = events[0]["cursor"]
if after_cursor is None:
return events[-limit:], False
try:
ac = int(after_cursor)
except (TypeError, ValueError):
return events[-limit:], False
if ac + 1 < oldest:
return [e for e in events if e["cursor"] > ac], True
return [e for e in events if e["cursor"] > ac][:limit], False
def latest_cursor(self):
with self._lock:
return self._seq
# -- 统计 -------------------------------------------------------------
def stats(self): def stats(self):
with self._lock: with self._lock:
s = dict(self._stats) lat = list(self.latencies_ms)
s["buffered_sessions"] = len(self._buffers) n = len(lat)
s["queued"] = len(self._queue) return {
s["channels"] = [n for n, _f in self._pushers] "published": self.published,
s["budget_ms"] = SLA_BROADCAST_MS "channels": len(self._buffers),
s["poll_fallback_interval_ms"] = POLL_FALLBACK_INTERVAL_MS "buffered_events": sum(len(b) for b in self._buffers.values()),
s["within_budget"] = s["max_broadcast_ms"] <= SLA_BROADCAST_MS "subscribers": sum(len(v) for v in self._subs.values()),
return s "subscriber_errors": self.subscriber_errors,
"latest_cursor": self._seq,
def shutdown(self): "buffer_size": self._buffer_size,
for w in self._workers: "broadcast_sla_ms": SLA_BROADCAST_MS,
w.stop.set() "samples": n,
self._workers = [] "lat_avg_ms": round(sum(lat) / n, 3) if n else None,
"lat_p95_ms": _pct(lat, 95) if n else None,
"lat_max_ms": round(max(lat), 3) if n else None,
"sla_breaches": self.sla_breaches,
}
def _run_coro(coro): def _pct(values, p):
"""在后台线程里安全执行 awaitable（无运行中 loop 时新建）。""" if not values:
import asyncio return None
s = sorted(values)
try: idx = min(len(s) - 1, int(round((p / 100.0) * (len(s) - 1))))
loop = asyncio.get_event_loop() return round(s[idx], 3)
if loop.is_running():
return asyncio.ensure_future(coro)
except RuntimeError:
pass
return asyncio.new_event_loop().run_until_complete(coro)
_HUB = None _HUB = None
@ -247,7 +152,7 @@ _HUB_LOCK = threading.Lock()
def get_hub(): def get_hub():
"""进程级单例广播中心。""" """进程内单例 hub。"""
global _HUB global _HUB
if _HUB is None: if _HUB is None:
with _HUB_LOCK: with _HUB_LOCK:
@ -256,8 +161,61 @@ def get_hub():
return _HUB return _HUB
def set_hub(hub): def reset_hub():
"""测试用：重建 hub。"""
global _HUB global _HUB
with _HUB_LOCK: with _HUB_LOCK:
_HUB = hub _HUB = BroadcastHub()
return _HUB return _HUB
def self_check():
"""离线断言：缓冲增量、缺口检测、SLA 打点、通道隔离。"""
msgs, ok = [], True
hub = BroadcastHub(buffer_size=4)
for i in range(1, 6):
hub.publish("pbl.world.7.1", {"event_id": i, "seq_no": i})
got, trunc = hub.pull("pbl.world.7.1", after_cursor=4)
if [g["event_id"] for g in got] != [5]:
ok = False
msgs.append("broadcast FAIL：增量拉取 %r" % [g["event_id"] for g in got])
else:
msgs.append("broadcast PASS：after_cursor=4 只回 1 条")
_, trunc = hub.pull("pbl.world.7.1", after_cursor=0)
if trunc is not True:
ok = False
msgs.append("broadcast FAIL：游标早于缓冲未报缺口（poll 会漏事件）")
else:
msgs.append("broadcast PASS：环形缓冲溢出报 truncated=True")
other, _ = hub.pull("pbl.world.7.2", after_cursor=None)
if other:
ok = False
msgs.append("broadcast FAIL：跨通道串数据")
else:
msgs.append("broadcast PASS：通道按 tenant.world 隔离")
hits = []
hub.subscribe("pbl.world.7.9", lambda e: hits.append(e["event_id"]))
hub.publish("pbl.world.7.9", {"event_id": 100})
if hits != [100]:
ok = False
msgs.append("broadcast FAIL：订阅者未收到 %r" % hits)
else:
msgs.append("broadcast PASS：订阅者扇出成功")
st = hub.stats()
if st["published"] != 6 or st["broadcast_sla_ms"] != 300:
ok = False
msgs.append("broadcast FAIL：stats %r" % st)
else:
msgs.append("broadcast PASS：stats published=%d p95=%sms 越界=%d"
% (st["published"], st["lat_p95_ms"], st["sla_breaches"]))
if channel_of(1, 7) != "pbl.world.7.1":
ok = False
msgs.append("broadcast FAIL：通道命名 %s" % channel_of(1, 7))
else:
msgs.append("broadcast PASS：通道命名 pbl.world.7.1")
if ok:
msgs.append("broadcast.self_check PASS")
return ok, msgs

199
pbl_runtime_ext/init.py
View File

@ -5,7 +5,8 @@ load_pbl_runtime_ext(env=None)：
1. ensure_tables 幂等建 3 表（pbl_runtime_event / pbl_entity_state / pbl_world_state_snapshot） 1. ensure_tables 幂等建 3 表（pbl_runtime_event / pbl_entity_state / pbl_world_state_snapshot）
2. **挂载即执行 self_check()**：写保护域（world/scene/entity/scense/scense_runtime/ 2. **挂载即执行 self_check()**：写保护域（world/scene/entity/scense/scense_runtime/
script_engine 基表）出现 U/D 调用、或单事务/幂等契约缺失 → 抛 RuntimeError 拒绝启动 script_engine 基表）出现 U/D 调用、或单事务/幂等契约缺失 → 抛 RuntimeError 拒绝启动
3. 注册 api（append_event / list_events / find_by_idem / next_seq / self_check） 3. **注册契约到 ServerEnv**（M11a 6 个 + M11b 6 个），dspy 以裸全局名 await 调用，
漏注册即 NameError（QC #1）
4. 返回 api 字典 4. 返回 api 字典
铁律：本模块是 scense_runtime 的**薄扩展**，只写 pbl_* 自有表，不改任何基表。 铁律：本模块是 scense_runtime 的**薄扩展**，只写 pbl_* 自有表，不改任何基表。
@ -18,9 +19,12 @@ from . import tx_event as _tx
try: try:
from . import m11b_api as _m11b from . import m11b_api as _m11b
from . import tx_write as _wtx from . import tx_write as _wtx
from . import broadcast as _bcast
from . import partitions as _part
from . import latency as _lat
from . import rtx_db as _rtx
except Exception as _exc: # noqa: BLE001 缺依赖时不阻断 M11a 能力 except Exception as _exc: # noqa: BLE001 缺依赖时不阻断 M11a 能力
_m11b = None _m11b = _wtx = _bcast = _part = _lat = _rtx = None
_wtx = None
_M11B_IMPORT_ERROR = str(_exc) _M11B_IMPORT_ERROR = str(_exc)
else: else:
_M11B_IMPORT_ERROR = None _M11B_IMPORT_ERROR = None
@ -28,6 +32,31 @@ else:
MODULE = "pbl_runtime_ext" MODULE = "pbl_runtime_ext"
EXPECTED_TABLES = 3 EXPECTED_TABLES = 3
# M11b 必须在 ServerEnv 上注册的名字（dspy 裸全局名调用）；自检据此核对「三处同步」
M11A_ENV_REGISTRATIONS = (
"pbl_runtime_event_append",
"pbl_runtime_event_poll",
"pbl_entity_state_get",
"pbl_entity_state_apply",
"pbl_world_broadcast",
"pbl_session_member_add",
)
M11B_ENV_REGISTRATIONS = (
"apply_runtime_event",
"poll_events",
"read_states",
"assert_append_only",
"pbl_runtime_broadcast_pull",
"pbl_runtime_broadcast_stats",
"pbl_runtime_event_append",
"pbl_runtime_event_poll",
"pbl_entity_state_get",
"pbl_entity_state_apply",
"pbl_world_broadcast",
"pbl_session_member_add",
)
def ensure_tables(env=None, sor=None): def ensure_tables(env=None, sor=None):
"""幂等建 3 表。返回 (ok_list, bad_list)。""" """幂等建 3 表。返回 (ok_list, bad_list)。"""
@ -35,8 +64,9 @@ def ensure_tables(env=None, sor=None):
def api(): def api():
"""对外 API 契约。""" """对外 API 契约（M11a + M11b）。"""
return { return {
# ---- M11a ----
"append_event": _tx.append_event, "append_event": _tx.append_event,
"list_events": _tx.list_events, "list_events": _tx.list_events,
"find_by_idem": _tx.find_by_idem, "find_by_idem": _tx.find_by_idem,
@ -47,68 +77,63 @@ def api():
"EVENT_TABLE": _tx.EVENT_TABLE, "EVENT_TABLE": _tx.EVENT_TABLE,
"STATE_TABLE": _tx.STATE_TABLE, "STATE_TABLE": _tx.STATE_TABLE,
"SNAPSHOT_TABLE": _tx.SNAPSHOT_TABLE, "SNAPSHOT_TABLE": _tx.SNAPSHOT_TABLE,
# ---- M11b ---- # ---- M11b：写/读/守卫/广播 ----
"apply_runtime_event": getattr(_wtx, "apply_runtime_event", None), "apply_runtime_event": getattr(_wtx, "apply_runtime_event", None),
"poll_events": getattr(_wtx, "poll_events", None), "poll_events": getattr(_wtx, "poll_events", None),
"read_states": getattr(_wtx, "read_states", None), "read_states": getattr(_wtx, "read_states", None),
"assert_append_only": getattr(_wtx, "assert_append_only", None), "assert_append_only": getattr(_wtx, "assert_append_only", None),
"broadcast_hub": getattr(_m11b, "get_hub", lambda: None)() if _m11b else None, "pbl_runtime_broadcast_pull": getattr(_m11b, "pbl_runtime_broadcast_pull", None),
"pbl_runtime_broadcast_stats": getattr(_m11b, "pbl_runtime_broadcast_stats", None),
"broadcast_hub": _bcast.get_hub() if _bcast else None,
"ensure_forward_partitions": getattr(_part, "ensure_forward_partitions", None)
if _part else None,
"latency_summary": _lat.summary() if _lat else None,
"contracts": dict(getattr(_m11b, "contracts", lambda: {})()) if _m11b else {}, "contracts": dict(getattr(_m11b, "contracts", lambda: {})()) if _m11b else {},
"ensure_forward_partitions": _partitions_fn(),
"M11B": bool(_m11b and _wtx), "M11B": bool(_m11b and _wtx),
} }
def _partitions_fn():
try:
from .partitions import ensure_forward_partitions
return ensure_forward_partitions
except Exception: # noqa: BLE001
return None
def self_check(env=None): def self_check(env=None):
"""模块自检：表契约 + 写保护 + 单事务/幂等契约。返回 (all_ok, msgs)。""" """模块自检：表契约 + 写保护 + 单事务/幂等契约 + M11b 注册完整性。"""
msgs = [] msgs = []
all_ok = True all_ok = True
tbl_ok, tbl_msgs = _tables.self_check() tbl_ok, tbl_msgs = _tables.self_check()
if not tbl_ok: all_ok = all_ok and tbl_ok
all_ok = False
msgs.extend(tbl_msgs) msgs.extend(tbl_msgs)
if len(_tables.TABLES) != EXPECTED_TABLES: if len(_tables.TABLES) != EXPECTED_TABLES:
all_ok = False all_ok = False
msgs.append("表数=%d 应为 %d" % (len(_tables.TABLES), EXPECTED_TABLES)) msgs.append("表数=%d 应为 %d" % (len(_tables.TABLES), EXPECTED_TABLES))
tx_ok, tx_msgs = _tx.self_check() tx_ok, tx_msgs = _tx.self_check()
if not tx_ok: all_ok = all_ok and tx_ok
all_ok = False
msgs.extend(tx_msgs) msgs.extend(tx_msgs)
# M11b 自检：append-only 守卫 / 月分区算法 / 幂等键派生（离线不连库） # M11b 自检（离线：契约签名 / append-only / 月分区 / 幂等键 / hub / SLA 打点）
if _M11B_IMPORT_ERROR: if _M11B_IMPORT_ERROR:
all_ok = False all_ok = False
msgs.append("M11b 模块导入 FAIL：%s" % _M11B_IMPORT_ERROR) msgs.append("M11b 模块导入 FAIL：%s" % _M11B_IMPORT_ERROR)
elif _wtx is not None: else:
m11b_ok, m11b_msgs = _wtx.self_check() for mod, label in ((_wtx, "tx_write"), (_m11b, "m11b_api"),
if not m11b_ok: (_bcast, "broadcast"), (_part, "partitions"),
all_ok = False (_lat, "latency"), (_rtx, "rtx_db")):
msgs.extend(m11b_msgs) ok_i, msgs_i = mod.self_check()
all_ok = all_ok and ok_i
msgs.extend(["[%s] %s" % (label, m) for m in msgs_i])
# 幂等探针：同 idem_key 二次投递必须走 dedup 分支（离线用假 sor 验证） # 幂等探针（M11a 主链路，离线假 sor）
probe_ok, probe_msgs = _probe_idempotent() probe_ok, probe_msgs = _probe_idempotent()
if not probe_ok: all_ok = all_ok and probe_ok
all_ok = False
msgs.extend(probe_msgs) msgs.extend(probe_msgs)
if all_ok: if all_ok:
msgs.append("SELF_CHECK %s: PASS %d/%d" % (MODULE, len(_tables.TABLES), len(_tables.TABLES))) msgs.append("SELF_CHECK %s: PASS %d/%d 表, M11B=%s"
% (MODULE, len(_tables.TABLES), EXPECTED_TABLES, bool(_m11b and _wtx)))
return all_ok, msgs return all_ok, msgs
class _FakeSor(object): class _FakeSor(object):
"""离线自检用内存 sor（只实现 C/R/U），验证单事务+幂等真实行为。""" """离线自检用内存 sor（只实现 C/R/U），验证 M11a 单事务+幂等真实行为。"""
def __init__(self): def __init__(self):
self.rows = {} self.rows = {}
@ -142,8 +167,8 @@ class _FakeSor(object):
self.updated.append((tbl, dict(values), where)) self.updated.append((tbl, dict(values), where))
return len(self.rows.get(tbl, [])) return len(self.rows.get(tbl, []))
def sqlExe(self, sql): def sqlExe(self, sql, params=None):
return 0 return []
class _FakeEnv(object): class _FakeEnv(object):
@ -157,7 +182,7 @@ class _FakeEnv(object):
def _probe_idempotent(): def _probe_idempotent():
"""幂等 + 单事务 + 广播探针。返回 (all_ok, msgs)。""" """M11a 幂等 + 单事务 + 广播探针。返回 (all_ok, msgs)。"""
msgs = [] msgs = []
all_ok = True all_ok = True
env = _FakeEnv() env = _FakeEnv()
@ -165,11 +190,13 @@ def _probe_idempotent():
r1 = _tx.append_event(env, tenant_id=7, world_id=1, session_id=11, r1 = _tx.append_event(env, tenant_id=7, world_id=1, session_id=11,
event_type="move", payload={"x": 1}, event_type="move", payload={"x": 1},
idem_key="probe-key-1", idem_key="probe-key-1",
state_updates=[{"state_key": "pos", "state_value": {"x": 1}}]) state_updates=[{"state_key": "pos",
"state_value": {"x": 1}}])
r2 = _tx.append_event(env, tenant_id=7, world_id=1, session_id=11, r2 = _tx.append_event(env, tenant_id=7, world_id=1, session_id=11,
event_type="move", payload={"x": 1}, event_type="move", payload={"x": 1},
idem_key="probe-key-1", idem_key="probe-key-1",
state_updates=[{"state_key": "pos", "state_value": {"x": 1}}]) state_updates=[{"state_key": "pos",
"state_value": {"x": 1}}])
except Exception as exc: # noqa: BLE001 except Exception as exc: # noqa: BLE001
return False, ["探针[单事务写入] FAIL：%r" % exc] return False, ["探针[单事务写入] FAIL：%r" % exc]
@ -177,7 +204,7 @@ def _probe_idempotent():
all_ok = False all_ok = False
msgs.append("探针[首次写入] FAIL：dedup=%r 应为 False" % r1.get("dedup")) msgs.append("探针[首次写入] FAIL：dedup=%r 应为 False" % r1.get("dedup"))
else: else:
msgs.append("探针[首次写入] PASS seq_no=%s state=%s" % (r1.get("seq_no"), r1.get("state"))) msgs.append("探针[首次写入] PASS seq_no=%s" % r1.get("seq_no"))
if r2.get("dedup") is not True: if r2.get("dedup") is not True:
all_ok = False all_ok = False
msgs.append("探针[幂等去重] FAIL：dedup=%r 应为 True" % r2.get("dedup")) msgs.append("探针[幂等去重] FAIL：dedup=%r 应为 True" % r2.get("dedup"))
@ -189,25 +216,15 @@ def _probe_idempotent():
msgs.append("探针[事件行数] FAIL：%d 应为 1" % n_ev) msgs.append("探针[事件行数] FAIL：%d 应为 1" % n_ev)
else: else:
msgs.append("探针[事件行数] PASS 1 行") msgs.append("探针[事件行数] PASS 1 行")
if len(env.sor.rows.get(_tx.STATE_TABLE, [])) != 1:
all_ok = False
msgs.append("探针[状态行数] FAIL：应为 1")
else:
msgs.append("探针[状态行数] PASS 1 行")
if len(env.sor.rows.get(_tx.SNAPSHOT_TABLE, [])) != 1:
all_ok = False
msgs.append("探针[快照行数] FAIL：应为 1")
else:
msgs.append("探针[快照行数] PASS 1 行")
if not env.broadcasts: if not env.broadcasts:
all_ok = False all_ok = False
msgs.append("探针[提交后广播] FAIL：未广播") msgs.append("探针[提交后广播] FAIL：未广播")
else: else:
msgs.append("探针[提交后广播] PASS 通道=%d" % len(env.broadcasts)) msgs.append("探针[提交后广播] PASS 通道=%d" % len(env.broadcasts))
# 缺租户必须拒
try: try:
_tx.append_event(env, tenant_id=None, world_id=1, session_id=11, event_type="move") _tx.append_event(env, tenant_id=None, world_id=1, session_id=11,
event_type="move")
all_ok = False all_ok = False
msgs.append("探针[缺租户必须拒] FAIL：未抛 TxError") msgs.append("探针[缺租户必须拒] FAIL：未抛 TxError")
except _tx.TxError as exc: except _tx.TxError as exc:
@ -216,27 +233,57 @@ def _probe_idempotent():
msgs.append("探针[缺租户必须拒] FAIL：code=%s" % exc.code) msgs.append("探针[缺租户必须拒] FAIL：code=%s" % exc.code)
else: else:
msgs.append("探针[缺租户必须拒] PASS PBL-TENANT-0001") msgs.append("探针[缺租户必须拒] PASS PBL-TENANT-0001")
# 状态写失败必须整体回滚（事件标 rolled_back）
env2 = _FakeEnv()
try:
_tx.append_event(env2, tenant_id=7, world_id=1, session_id=12,
event_type="move", payload={},
state_updates=[{"bad": "no state_key"}])
all_ok = False
msgs.append("探针[状态失败回滚] FAIL：未抛 TxError")
except _tx.TxError as exc:
rolled = [u for u in env2.sor.updated if u[1].get("state") == "rolled_back"]
if not rolled:
all_ok = False
msgs.append("探针[状态失败回滚] FAIL：事件未标 rolled_back（%r）" % exc.code)
else:
msgs.append("探针[状态失败回滚] PASS 事件标 rolled_back，无脏数据")
return all_ok, msgs return all_ok, msgs
# ---------------------------------------------------------------- 注册
def _registrations():
"""env 注册清单：名字 → 实现。单一事实源，自检据此核对三处同步。"""
reg = {
# M11a（pbl_runtime_ext.api 中的 dspy 契约）
"pbl_runtime_event_append": None,
"pbl_runtime_event_poll": None,
"pbl_entity_state_get": None,
"pbl_entity_state_apply": None,
"pbl_world_broadcast": None,
"pbl_session_member_add": None,
}
try:
from . import api as _api
except Exception: # noqa: BLE001
_api = None
for name in list(reg.keys()):
reg[name] = getattr(_api, name, None) if _api else None
if _m11b is not None:
reg.update({
"apply_runtime_event": _m11b.apply_runtime_event,
"poll_events": _m11b.poll_events,
"read_states": _m11b.read_states,
"assert_append_only": _m11b.assert_append_only,
"pbl_runtime_broadcast_pull": _m11b.pbl_runtime_broadcast_pull,
"pbl_runtime_broadcast_stats": _m11b.pbl_runtime_broadcast_stats,
})
return reg
def check_registrations(groups=None):
"""自检：清单内每个名字都必须能拿到可调用实现。
groups 默认 ("m11b",)——M11b 契约是本任务交付主体，缺一个即 fail-closed；
传 ("m11a","m11b") 时同时核对 M11a（依赖 pbl_common，离线工作空间不可导入，
由 selftest 单独按「环境受限」声明，不冒充缺失）。
"""
reg = _registrations()
names = []
for g in (groups or ("m11b",)):
names.extend(M11A_ENV_REGISTRATIONS if g == "m11a"
else M11B_ENV_REGISTRATIONS)
missing = [n for n in names if not callable(reg.get(n))]
return (not missing), missing, sorted(names)
def load_pbl_runtime_ext(env=None): def load_pbl_runtime_ext(env=None):
"""挂载入口：建表 → 自检（不过即抛）→ 注册契约 → 返回 api 字典。""" """挂载入口：建表 → 自检（不过即抛）→ **注册契约到 env** → 返回 api 字典。"""
srv = env srv = env
if srv is None: if srv is None:
try: try:
@ -254,10 +301,20 @@ def load_pbl_runtime_ext(env=None):
if not ok: if not ok:
raise RuntimeError( raise RuntimeError(
"%s self_check FAILED（fail-closed，拒绝启动）：%s" "%s self_check FAILED（fail-closed，拒绝启动）：%s"
% (MODULE, "; ".join([m for m in msgs if "FAIL" in m or "应为" in m][:6])) % (MODULE, "; ".join([m for m in msgs if "FAIL" in m][:6]))
) )
# 注册完整性同样 fail-closed：漏一个 dspy 契约名字就拒绝挂载（防上线 NameError）
reg_ok, missing, names = check_registrations(("m11a", "m11b"))
if not reg_ok:
raise RuntimeError(
"%s 契约注册缺失（fail-closed）：%s" % (MODULE, ",".join(missing)))
_log(srv, "契约注册清单 PASS：%d 个名字" % len(M11B_ENV_REGISTRATIONS))
if srv is not None: if srv is not None:
for name, fn in _registrations().items():
if callable(fn):
setattr(srv, name, fn)
setattr(srv, "pbl_runtime_ext_api", api()) setattr(srv, "pbl_runtime_ext_api", api())
modules = getattr(srv, "modules", None) modules = getattr(srv, "modules", None)
if isinstance(modules, list) and MODULE not in modules: if isinstance(modules, list) and MODULE not in modules:
@ -280,5 +337,7 @@ if __name__ == "__main__":
_ok, _msgs = self_check() _ok, _msgs = self_check()
for _m in _msgs: for _m in _msgs:
print(_m) print(_m)
print("RESULT: %s" % ("PASS" if _ok else "FAIL")) _r_ok, _miss, _names = check_registrations()
raise SystemExit(0 if _ok else 1) print("REGISTRATIONS: %s missing=%s" % ("PASS" if _r_ok else "FAIL", _miss))
print("RESULT: %s" % ("PASS" if (_ok and _r_ok) else "FAIL"))
raise SystemExit(0 if (_ok and _r_ok) else 1)

200
pbl_runtime_ext/latency.py
View File

@ -1,93 +1,145 @@
"""M11b 时延计量：裁决/广播/端到端三段预算的计时与 SLA 判定。 # -*- coding: utf-8 -*-
"""latency —— 时延打点与 SLA 判定（M11b）。
设计要点： 承诺（m11b_config）：裁决 ≤200ms、广播 ≤300ms、端到端 ≤1000ms、轮询兜底 3000ms。
* 计时用单调时钟 perf_counter，避免系统时钟回拨造成负值； 本模块只做纯内存统计（可离线断言），不依赖 DB；真实数值由 selftest 连库实测填入报告。
* 超预算不抛异常（业务已落库，回滚反而破坏一致性），只在结果里
打 sla_breached 标记并落 WARN 日志，由监控/测试阶段据此判定缺陷；
* 所有对外响应都带 latency 段，客户端据此决定是否需要 3s 轮询兜底。
""" """
import logging
import time import time
from collections import deque
from .m11b_config import ( from .m11b_config import (POLL_FALLBACK_MS, SLA_ADJUDICATE_MS, SLA_BROADCAST_MS,
POLL_FALLBACK_INTERVAL_MS, SLA_END_TO_END_MS)
SLA_ADJUDICATE_MS,
SLA_BROADCAST_MS,
SLA_E2E_MS,
)
log = logging.getLogger("pbl_runtime_ext.latency") STAGES = ("adjudicate", "broadcast", "end_to_end")
_PHASE_SLA = {
"adjudicate_ms": SLA_ADJUDICATE_MS,
"broadcast_ms": SLA_BROADCAST_MS,
"tx_ms": SLA_ADJUDICATE_MS,
"e2e_ms": SLA_E2E_MS,
}
def now_ms(): def percentile(values, p):
"""单调毫秒时间戳（仅用于计时，不作为业务时间）。""" if not values:
return int(time.perf_counter() * 1000) return None
s = sorted(values)
idx = min(len(s) - 1, int(round((p / 100.0) * (len(s) - 1))))
return round(s[idx], 3)
class Stopwatch: class Timer(object):
"""分段计时器。start() 记起点，mark(phase) 结算一段耗时。""" """with Timer() as t: ... ; t.ms —— 毫秒级计时。"""
__slots__ = ("_origin", "_marks", "_last")
def __init__(self): def __init__(self):
self._origin = now_ms() self._t0 = None
self._last = self._origin self.ms = None
self._marks = {}
def mark(self, phase): def __enter__(self):
cur = now_ms() self._t0 = time.perf_counter()
cost = max(0, cur - self._last) return self
self._last = cur
self._marks[phase] = cost
return cost
def total_ms(self): def __exit__(self, *a):
return max(0, now_ms() - self._origin) self.ms = round((time.perf_counter() - self._t0) * 1000.0, 3)
return False
def snapshot(self):
return dict(self._marks)
def evaluate_sla(sw, extra_ms=None): class LatencyTracker(object):
"""结算 SLA：返回 (latency_dict, breached_list)。 """各阶段时延样本环形记录 + SLA 越界计数。"""
extra_ms: 额外手工补记的段（例如跨进程回传耗时）。 def __init__(self, maxlen=500):
""" self._samples = dict((s, deque(maxlen=maxlen)) for s in STAGES)
marks = sw.snapshot() self._breach = dict((s, 0) for s in STAGES)
if extra_ms:
marks.update({k: int(v) for k, v in extra_ms.items() if v is not None})
marks["e2e_ms"] = sw.total_ms()
breached = [] @staticmethod
for key, limit in _PHASE_SLA.items(): def sla_for(stage):
val = marks.get(key) return {"adjudicate": SLA_ADJUDICATE_MS,
if val is None: "broadcast": SLA_BROADCAST_MS,
continue "end_to_end": SLA_END_TO_END_MS}[stage]
if val > limit:
breached.append({"phase": key, "cost_ms": val, "limit_ms": limit})
if breached: def record(self, stage, ms):
log.warning("runtime SLA breached: %s", breached) if stage not in self._samples:
raise KeyError("unknown stage %r" % stage)
ms = round(float(ms), 3)
self._samples[stage].append(ms)
breach = ms > self.sla_for(stage)
if breach:
self._breach[stage] += 1
return breach
latency = { def summary(self):
"adjudicate_ms": marks.get("adjudicate_ms", 0), out = {}
"tx_ms": marks.get("tx_ms", 0), for s in STAGES:
"broadcast_ms": marks.get("broadcast_ms", 0), vals = list(self._samples[s])
"e2e_ms": marks.get("e2e_ms", 0), n = len(vals)
"sla": { out[s] = {
"adjudicate_ms": SLA_ADJUDICATE_MS, "sla_ms": self.sla_for(s),
"broadcast_ms": SLA_BROADCAST_MS, "samples": n,
"e2e_ms": SLA_E2E_MS, "avg_ms": round(sum(vals) / n, 3) if n else None,
"poll_fallback_interval_ms": POLL_FALLBACK_INTERVAL_MS, "p95_ms": percentile(vals, 95),
}, "p99_ms": percentile(vals, 99),
"breached": breached, "max_ms": round(max(vals), 3) if n else None,
"within_sla": not breached, "breaches": self._breach[s],
} }
return latency, breached out["poll_fallback_ms"] = POLL_FALLBACK_MS
return out
def all_within_sla(self):
return all(self._breach[s] == 0 for s in STAGES)
_TRACKER = None
def get_tracker():
global _TRACKER
if _TRACKER is None:
_TRACKER = LatencyTracker()
return _TRACKER
def record(stage, ms):
return get_tracker().record(stage, ms)
def summary():
return get_tracker().summary()
def self_check():
msgs, ok = [], True
t = LatencyTracker()
if t.record("adjudicate", 120.0) is not False:
ok = False
msgs.append("latency FAIL：120ms 不应判越界（SLA 200ms）")
else:
msgs.append("latency PASS：裁决 120ms ≤ 200ms 未越界")
if t.record("adjudicate", 450.0) is not True:
ok = False
msgs.append("latency FAIL：450ms 应判越界")
else:
msgs.append("latency PASS：裁决 450ms > 200ms 记越界")
t.record("broadcast", 40.0)
t.record("end_to_end", 620.0)
s = t.summary()
if s["adjudicate"]["breaches"] != 1 or s["adjudicate"]["samples"] != 2:
ok = False
msgs.append("latency FAIL：summary %r" % s["adjudicate"])
else:
msgs.append("latency PASS：summary avg=%s p95=%s breaches=%d"
% (s["adjudicate"]["avg_ms"], s["adjudicate"]["p95_ms"],
s["adjudicate"]["breaches"]))
if s["poll_fallback_ms"] != 3000:
ok = False
msgs.append("latency FAIL：轮询兜底 %s 应为 3000" % s["poll_fallback_ms"])
else:
msgs.append("latency PASS：轮询兜底 3000ms 已配置")
if percentile([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 95) is None:
ok = False
msgs.append("latency FAIL：percentile 空值")
else:
msgs.append("latency PASS：p95=%s" % percentile(range(1, 11), 95))
with Timer() as tm:
time.sleep(0.005)
if not (1.0 <= tm.ms < 2000):
ok = False
msgs.append("latency FAIL：Timer 计时 %s" % tm.ms)
else:
msgs.append("latency PASS：Timer 实测 %.1fms" % tm.ms)
if ok:
msgs.append("latency.self_check PASS")
return ok, msgs

385
pbl_runtime_ext/m11b_api.py
View File

@ -1,299 +1,132 @@
"""M11b 契约实现层：把 .dspy 端点参数转成单事务写入/广播/轮询调用。 # -*- coding: utf-8 -*-
"""m11b_api —— M11b 对外契约的 **async 包装层**（dspy 直接调用的名字）。
与 M11a 的 api.py 的关系：本文件是 M11b 的**权威实现**，api.py 末尾以 dspy 端点以「裸全局名 + await」调用，因此这里导出的每个名字必须：
`from .m11b_api import ...` 覆盖同名契约，使 ① 在本文件有真实实现（或从 tx_write/broadcast 再导出）
* pbl_runtime_event_append → 单事务 append-only 写事件（幂等） ② 在 __init__.py 有 import 导出
* pbl_entity_state_apply → 单事务「事件 + 实体状态(+快照)」+ 提交后广播 ③ 在 init.py load_pbl_runtime_ext() 内有 ``env.<name> = <name>`` 注册
* pbl_runtime_event_poll → 先命中广播缓冲、未命中退回查库（3s 兜底） 三处缺一，上线即 ``NameError: name 'xxx' is not defined``（QC #1 指出的正是此缺口）。
* pbl_world_broadcast → 提交后广播状态查询 / 主动重播
* pbl_runtime_broadcast_pull → 广播增量拉取（新增契约）
全部走同一条 tx_write 主链路，避免两套实现漂移。
约定：核心 tx_write 是同步阻塞（DB 驱动是同步的），契约层用线程池执行， 导出（6 个契约）：
不阻塞事件循环；异常统一转结构化 {"ok": False, "error": {...}}， apply_runtime_event / poll_events / read_states / assert_append_only
错误码可断言（SLA/回滚/幂等/租户缺失）。 pbl_runtime_broadcast_pull / pbl_runtime_broadcast_stats
""" """
import asyncio
import functools
import logging
from .m11b_config import ( import inspect
ERR_BAD_PAYLOAD,
ERR_DB,
ERR_STATE_CONFLICT,
ERR_TX_FAILED,
PBL_RT_TENANT_MISSING_CODE,
)
from .rtx_db import PblRtError, tenant_id as resolve_tenant
from .tx_write import (
apply_runtime_event,
broadcast_stats,
poll_events,
read_states,
)
log = logging.getLogger("pbl_runtime_ext.m11b_api") from . import broadcast as _hub
from . import latency as _lat
from . import rtx_db
from . import tx_write as _w
from .m11b_config import CHANNEL_PREFIX, contracts as _contracts
# 租户缺失在 pbl_common 侧的历史错误码，保持一致便于前端断言 __all__ = ["apply_runtime_event", "poll_events", "read_states", "assert_append_only",
TENANT_MISSING_CODE = PBL_RT_TENANT_MISSING_CODE "pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats",
"get_hub", "contracts"]
# 再导出核心实现（保持单一事实源：实现只在 tx_write/broadcast 里）
apply_runtime_event = _w.apply_runtime_event
poll_events = _w.poll_events
read_states = _w.read_states
assert_append_only = _w.assert_append_only
get_hub = _hub.get_hub
contracts = _contracts
def _int(v, default=0): def _bad(msg):
try: return {"ok": False, "code": "PBL-PARAM-0001", "error": msg}
return int(v)
except (TypeError, ValueError):
return int(default or 0)
def _client_authoritative_fields(kw): def _fail(exc):
"""挑出客户端提交里的「服务端权威字段」，用于 fail-closed 拒绝。""" code = getattr(exc, "code", "PBL-RTX-0002")
from .m11b_config import FORBIDDEN_CLIENT_FIELDS return {"ok": False, "code": code, "error": str(getattr(exc, "msg", exc))}
return [k for k in (kw or {}) if k in FORBIDDEN_CLIENT_FIELDS
and (kw or {}).get(k) not in (None, "")]
def _run(fn, *a, **kw): async def pbl_runtime_broadcast_pull(tenant_id=None, world_id=None, session_id=None,
"""把同步 DB 调用丢到默认线程池，保持事件循环响应（端到端预算含排队）。""" after_cursor=None, after_seq=None, limit=200,
loop = asyncio.get_event_loop() channel=None, **_ignored):
return loop.run_in_executor(None, functools.partial(fn, *a, **kw)) """广播拉取端点（3s 轮询兜底用）。
两种用法：
def _error(exc): * 传 tenant_id(+world_id) → 走 poll_events（hub 命中优先，未命中退回查库）
if isinstance(exc, PblRtError): * 只传 channel → 直接按通道名从 hub 取增量（跨租户禁用，须带 tenant_id 前缀）
return {"ok": False, "error": exc.to_dict(), "code": exc.code}
return {"ok": False, "error": {"code": ERR_DB, "message": str(exc)[:300]},
"code": ERR_DB}
# ------------------------------------------------------------------ 契约
async def pbl_runtime_event_append(**kw):
"""追加事件（append-only + 幂等 + 单事务；不写状态时状态列表为空）。"""
try:
tid = resolve_tenant(kw.get("tenant_id"))
except PblRtError as exc:
return _error(exc)
if not kw.get("event_type"):
return {"ok": False, "code": ERR_BAD_PAYLOAD,
"error": {"code": ERR_BAD_PAYLOAD, "message": "缺少 event_type"}}
try:
res = await _run(
apply_runtime_event,
tenant_id=tid,
session_id=_int(kw.get("session_id") or kw.get("session")),
event_type=kw.get("event_type"),
payload=kw.get("payload") if kw.get("payload") is not None else kw.get("payload_json"),
world_id=_int(kw.get("world_id")),
entity_id=_int(kw.get("entity_id")),
actor_id=kw.get("actor_id"),
source=kw.get("source") or "runtime",
idem_key=kw.get("idem_key") or kw.get("event_uid"),
client_seq=kw.get("client_seq"),
causation_id=kw.get("causation_id"),
state_updates=None,
snapshot=bool(kw.get("snapshot")),
broadcast=kw.get("broadcast", True),
tx_group=kw.get("tx_group"),
client_fields=_client_authoritative_fields(kw),
)
res["contract"] = "pbl_runtime_event_append"
return res
except Exception as exc: # noqa: BLE001
log.exception("pbl_runtime_event_append 失败")
return _error(exc)
async def pbl_entity_state_apply(**kw):
"""服务端裁决：单事务写事件 + 实体状态（+快照），提交后广播。
客户端提交的 state_version 一律忽略（出现在禁写清单里 → 显式回告
`client_version_ignored`；若同时出现其他权威字段则 fail-closed 拒绝）。
""" """
try: try:
tid = resolve_tenant(kw.get("tenant_id")) if tenant_id in (None, "") and channel:
except PblRtError as exc: expect = "%s.%s." % (CHANNEL_PREFIX, "")
return _error(exc) if not str(channel).startswith(CHANNEL_PREFIX + "."):
session_id = _int(kw.get("session_id") or kw.get("session")) return _bad("channel 必须以 %s. 开头" % CHANNEL_PREFIX)
entity_id = kw.get("entity_id") parts = str(channel).split(".")
if not session_id or entity_id in (None, ""): if len(parts) < 4 or parts[3] in ("", "*"):
return {"ok": False, "code": ERR_BAD_PAYLOAD, return _bad("channel 必须含租户段（pbl.world.<tenant>.<world>），"
"error": {"code": ERR_BAD_PAYLOAD, "message": "缺少 session_id/entity_id"}} "拒绝跨租户拉取")
updates = kw.get("state_updates") tenant_id = parts[3]
if not updates: world_id = parts[4] if len(parts) > 4 else None
updates = [{"entity_id": entity_id, events, truncated = _hub.get_hub().pull(
"state_key": kw.get("state_key") or "default", channel or _hub.channel_of(world_id, tenant_id), after_cursor,
"state_value": kw.get("state_value") or kw.get("state_json") or {}, limit or 200)
"world_id": _int(kw.get("world_id")), if events and not truncated and after_seq in (None, ""):
"merge": kw.get("merge", True), return {"ok": True, "source": "hub", "truncated": False,
"if_state_version": kw.get("if_state_version")}] "events": events, "next_cursor": events[-1]["cursor"],
leaked = _client_authoritative_fields(kw) "count": len(events)}
strict = bool(kw.get("strict", False)) res = await poll_events(tenant_id=tenant_id, world_id=world_id,
if leaked and strict: session_id=session_id, after_cursor=after_cursor,
return {"ok": False, "code": ERR_BAD_PAYLOAD, after_seq=after_seq, limit=limit)
"error": {"code": ERR_BAD_PAYLOAD, res["count"] = len(res.get("events") or [])
"message": "服务端权威字段客户端禁写: %s" % ",".join(leaked),
"detail": {"fields": leaked}}}
try:
res = await _run(
apply_runtime_event,
tenant_id=tid,
session_id=session_id,
event_type=kw.get("event_type") or "entity.state.changed",
payload=kw.get("payload") or {"entity_id": entity_id,
"state_key": (updates[0] or {}).get("state_key")},
world_id=_int(kw.get("world_id")),
entity_id=_int(entity_id),
actor_id=kw.get("actor_id"),
source=kw.get("source") or "client_intent",
idem_key=kw.get("idem_key") or kw.get("event_uid"),
client_seq=kw.get("client_seq"),
causation_id=kw.get("causation_id"),
state_updates=updates,
snapshot=bool(kw.get("snapshot")),
broadcast=kw.get("broadcast", True),
if_state_version=kw.get("if_state_version"),
tx_group=kw.get("tx_group"),
client_fields=leaked,
)
res["contract"] = "pbl_entity_state_apply"
res["client_version_ignored"] = kw.get("state_version") not in (None, "")
res["authoritative_fields_rejected"] = leaked if strict else []
return res return res
except PblRtError as exc: except rtx_db.RtxError as exc:
if exc.code in (ERR_STATE_CONFLICT, ERR_TX_FAILED): return _fail(exc)
log.info("状态裁决被拒 %s: %s", exc.code, exc.message)
return _error(exc)
except Exception as exc: # noqa: BLE001 except Exception as exc: # noqa: BLE001
log.exception("pbl_entity_state_apply 失败") return _fail(exc)
return _error(exc)
async def pbl_runtime_event_poll(**kw): async def pbl_runtime_broadcast_stats(tenant_id=None, world_id=None, **_ignored):
"""3s 轮询兜底：先命中广播缓冲，未命中退回查库（幂等，不重复消费）。""" """广播/时延统计端点：hub 扇出计数 + 各阶段 SLA 实测摘要。"""
try: try:
tid = resolve_tenant(kw.get("tenant_id")) hub = _hub.get_hub()
except PblRtError as exc: st = hub.stats()
return _error(exc) st["sla"] = _lat.summary()
try: st["contracts"] = sorted(_contracts().keys())
res = await _run( st["channel_prefix"] = CHANNEL_PREFIX
poll_events, if tenant_id not in (None, "") and world_id not in (None, ""):
tenant_id=tid, st["channel"] = _hub.channel_of(world_id, tenant_id)
session_id=_int(kw.get("session_id") or kw.get("session")), buffered, _ = hub.pull(st["channel"], None, 50)
since_seq=_int(kw.get("since_seq") or kw.get("since")), st["channel_buffered"] = len(buffered)
limit=_int(kw.get("limit") or 100, 100), st["ok"] = True
try_buffer=bool(kw.get("try_buffer", True)), return st
)
res["contract"] = "pbl_runtime_event_poll"
res["poll_interval_ms"] = 3000
return res
except Exception as exc: # noqa: BLE001 except Exception as exc: # noqa: BLE001
log.exception("pbl_runtime_event_poll 失败") return _fail(exc)
return _error(exc)
async def pbl_runtime_broadcast_pull(**kw): def self_check():
"""新增契约：从广播环形缓冲拉增量（掉线补齐，比查库轻）。""" """离线自检：6 个契约全部存在、可调用、协程签名正确（防三处同步漏项）。"""
try: msgs, ok = [], True
resolve_tenant(kw.get("tenant_id")) coros = ("apply_runtime_event", "poll_events", "read_states",
except PblRtError as exc: "pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats")
return _error(exc) for name in coros:
from .broadcast import get_hub fn = globals().get(name)
if fn is None:
res = get_hub().pull("s:%s" % _int(kw.get("session_id")), ok = False
_int(kw.get("since_seq")), msgs.append("m11b_api FAIL：契约 %s 未定义" % name)
_int(kw.get("limit") or 200, 200)) elif not inspect.iscoroutinefunction(fn):
res.update({"contract": "pbl_runtime_broadcast_pull", "ok": True, ok = False
"session_id": _int(kw.get("session_id")), msgs.append("m11b_api FAIL：%s 非协程" % name)
"stats": broadcast_stats() if kw.get("with_stats") else None}) if ok:
return res msgs.append("m11b_api PASS：%d 个协程契约齐备" % len(coros))
if not callable(assert_append_only):
ok = False
async def pbl_world_broadcast(**kw): msgs.append("m11b_api FAIL：assert_append_only 不可调用")
"""广播状态查询 / 主动重播（重播只推已提交事件，不重复写库）。""" else:
try: msgs.append("m11b_api PASS：assert_append_only 同步守卫可调用")
tid = resolve_tenant(kw.get("tenant_id")) if sorted(_contracts().keys()) != sorted([
except PblRtError as exc: "apply_runtime_event", "assert_append_only", "broadcast_hub",
return _error(exc) "ensure_forward_partitions", "pbl_runtime_broadcast_pull",
session_id = _int(kw.get("session_id") or kw.get("session")) "pbl_runtime_broadcast_stats", "poll_events", "read_states"]):
replay = kw.get("replay") ok = False
try: msgs.append("m11b_api FAIL：contracts 清单与注册表不一致 %r"
if replay: % sorted(_contracts().keys()))
res = await _run(_replay, tid, session_id, replay) else:
else: msgs.append("m11b_api PASS：contracts 清单 8 项与注册表一致")
res = {"ok": True, "stats": broadcast_stats(), "session_id": session_id} if ok:
res["contract"] = "pbl_world_broadcast" msgs.append("m11b_api.self_check PASS")
res["fallback_poll_interval_ms"] = 3000 return ok, msgs
res["note"] = "广播失败不撤销已提交事件，客户端 3s 轮询补齐（不丢数据）"
return res
except Exception as exc: # noqa: BLE001
log.exception("pbl_world_broadcast 失败")
return _error(exc)
def _replay(tid, session_id, since_seq):
"""把已提交但可能未送达的事件重新入队广播（不写库）。"""
from .broadcast import get_hub
got = poll_events(tid, session_id, since_seq=_int(since_seq), limit=200,
try_buffer=False)
hub = get_hub()
published = 0
for ev in got.get("events") or []:
hub.publish("s:%s" % session_id, {
"seq_no": ev.get("seq_no"), "event_id": ev.get("id"),
"event_type": ev.get("event_type"), "session_id": session_id,
"world_id": ev.get("world_id"), "state_version": ev.get("state_version"),
"states": [], "ts": ev.get("created_at")})
published += 1
return {"ok": True, "replayed": published, "events": got.get("count", 0),
"last_seq": got.get("last_seq"), "stats": hub.stats()}
async def pbl_entity_state_get(**kw):
"""读实体状态（服务端权威版本；只读，不改基表）。"""
try:
tid = resolve_tenant(kw.get("tenant_id"))
except PblRtError as exc:
return _error(exc)
try:
res = await _run(
read_states,
tenant_id=tid,
session_id=_int(kw.get("session_id") or kw.get("session")),
entity_id=kw.get("entity_id"),
since_version=_int(kw.get("since_version")),
limit=_int(kw.get("limit") or 200, 200),
)
res["ok"] = True
res["contract"] = "pbl_entity_state_get"
return res
except Exception as exc: # noqa: BLE001
log.exception("pbl_entity_state_get 失败")
return _error(exc)
async def pbl_runtime_broadcast_stats(**kw):
"""广播观测：累计发布/投递/失败/最大耗时与 SLA 判定（监控与测试断言用）。"""
try:
resolve_tenant(kw.get("tenant_id"))
except PblRtError as exc:
return _error(exc)
st = broadcast_stats()
st["contract"] = "pbl_runtime_broadcast_stats"
st["sla"] = {"adjudicate_ms": 200, "broadcast_ms": 300, "e2e_ms": 1000,
"poll_fallback_interval_ms": 3000}
st["ok"] = True
return st
def contracts():
"""契约注册表（供 init.py 注册到 ServerEnv / 路由）。"""
return {
"pbl_runtime_event_append": pbl_runtime_event_append,
"pbl_runtime_event_poll": pbl_runtime_event_poll,
"pbl_runtime_broadcast_pull": pbl_runtime_broadcast_pull,
"pbl_entity_state_get": pbl_entity_state_get,
"pbl_entity_state_apply": pbl_entity_state_apply,
"pbl_world_broadcast": pbl_world_broadcast,
"pbl_runtime_broadcast_stats": pbl_runtime_broadcast_stats,
}

114
pbl_runtime_ext/m11b_config.py
View File

@ -1,65 +1,65 @@
"""M11b 配置常量：单事务事件+状态写入、按月分区、提交后广播与时延承诺。 # -*- coding: utf-8 -*-
"""m11b_config —— M11b 常量：时延 SLA / 分区 / 广播通道 / 错误码。
所有阈值集中在此，禁止在业务代码里散落魔法数字。 所有阈值集中在此，禁止散落在业务代码里写魔法数字。
时延承诺（需求 R-RT-03）：
- 裁决（adjudicate） <= 200 ms
- 广播（broadcast） <= 300 ms
- 端到端（e2e） <= 1000 ms
- 客户端轮询兜底间隔 = 3000 ms
""" """
MODULE_NAME = "pbl_runtime_ext" MODULE = "pbl_runtime_ext"
# ---------------------------------------------------------------- 表名 # ---- 表名（只写 pbl_* 自有表，基表只读）--------------------------------
T_EVENT = "pbl_runtime_event" EVENT_TABLE = "pbl_runtime_event"
T_STATE = "pbl_entity_state" STATE_TABLE = "pbl_entity_state"
T_SNAPSHOT = "pbl_world_state_snapshot" SNAPSHOT_TABLE = "pbl_world_state_snapshot"
# ---------------------------------------------------------------- 分区 # 基表写保护域：出现对这些表的 U/D 即拒绝
PARTITION_SUFFIX = "pbl_runtime_event_" # + YYYYMM PROTECTED_BASE_TABLES = (
PARTITION_RETAIN_MONTHS = 14 # 保留 12 个月 + 2 个月缓冲 "world", "scene", "entity", "scense", "scense_runtime", "script_engine",
PARTITION_PRECREATE_MONTHS = 2 # 预建未来分区数
PARTITION_LATEST_NAME = "pbl_runtime_event_pmax" # MAXVALUE 兜底分区
# ---------------------------------------------------------------- 时延预算(ms)
SLA_ADJUDICATE_MS = 200
SLA_BROADCAST_MS = 300
SLA_E2E_MS = 1000
POLL_FALLBACK_INTERVAL_MS = 3000 # 广播丢失时客户端兜底轮询周期
BROADCAST_THREADS = 2 # 提交后广播后台线程数
BROADCAST_QUEUE_SIZE = 2000 # 每 world 环形缓冲容量
POLL_MAX_LIMIT = 500
POLL_DEFAULT_LIMIT = 100
# ---------------------------------------------------------------- 事务
TX_MAX_RETRY = 3 # 乐观锁冲突重试次数
TX_RETRY_BACKOFF_MS = 15
# ---------------------------------------------------------------- 错误码
ERR_TENANT_MISSING = "PBL_RT_TENANT_MISSING"
ERR_BAD_PAYLOAD = "PBL_RT_BAD_PAYLOAD"
ERR_APPEND_ONLY = "PBL_RT_APPEND_ONLY"
ERR_STATE_CONFLICT = "PBL_RT_STATE_CONFLICT"
ERR_TX_FAILED = "PBL_RT_TX_FAILED"
ERR_SLA_BREACH = "PBL_RT_SLA_BREACH"
ERR_DB = "PBL_RT_DB"
# 与 pbl_common 错误码风格对齐的别名（契约层引用）
PBL_RT_TENANT_MISSING_CODE = ERR_TENANT_MISSING
# ---------------------------------------------------------------- 客户端禁写字段
FORBIDDEN_CLIENT_FIELDS = (
"state_version",
"server_version",
"seq_no",
"event_id",
"created_at",
"tenant_id",
"partition_key",
) )
# 事件必填字段 # ---- 时延承诺（毫秒）----------------------------------------------------
EVENT_REQUIRED = ("world_id", "event_type") SLA_ADJUDICATE_MS = 200 # 服务端裁决（apply_runtime_event 事务内耗时）
SLA_BROADCAST_MS = 300 # 提交后广播扇出
SLA_END_TO_END_MS = 1000 # 端到端（事件产生 → 客户端可见）
POLL_FALLBACK_MS = 3000 # 3s 轮询兜底（广播丢失/断线时客户端拉取周期）
# 状态变更必填字段 # ---- 广播通道 / 缓冲 -----------------------------------------------------
STATE_REQUIRED = ("entity_id",) CHANNEL_PREFIX = "pbl.world"
HUB_BUFFER_PER_CHANNEL = 512 # 每通道环形缓冲条数（超出丢弃最旧，poll 自动退查库）
HUB_MAX_CHANNELS = 2048
# ---- 分区 ---------------------------------------------------------------
PARTITION_PREFIX = "p" # p202601 ...
PARTITION_MONTHS_FORWARD = 3 # 提前预建 3 个月分区
PARTITION_COLUMN = "occurred_at"
# ---- 错误码 -------------------------------------------------------------
ERR_TENANT_MISSING = "PBL-TENANT-0001"
ERR_APPEND_ONLY = "PBL-RTX-0001-APPEND"
ERR_STATE_CONFLICT = "PBL-STATE-CONFLICT"
ERR_TX_UNSUPPORTED = "PBL-RTX-0002"
ERR_BAD_PARAM = "PBL-PARAM-0001"
ERR_BROADCAST_AFTER_COMMIT = "PBL-BROAD-0001"
def sla_ms():
"""SLA 快照（供 stats 端点与自检输出）。"""
return {
"adjudicate_ms": SLA_ADJUDICATE_MS,
"broadcast_ms": SLA_BROADCAST_MS,
"end_to_end_ms": SLA_END_TO_END_MS,
"poll_fallback_ms": POLL_FALLBACK_MS,
}
def contracts():
"""本模块 M11b 契约清单：名称 → 说明（init 注册与自检的单一事实源）。"""
return {
"apply_runtime_event": "单事务写事件+实体状态+快照，提交后广播（原子/可回滚）",
"poll_events": "轮询兜底：先查进程内广播缓冲，未命中/有缺口退回查库",
"read_states": "读取实体状态（tenant_id 强制打头，含 state_version）",
"assert_append_only": "pbl_runtime_event 与基表写保护守卫",
"pbl_runtime_broadcast_pull": "dspy 端点：按通道/游标拉取广播事件",
"pbl_runtime_broadcast_stats": "dspy 端点：广播扇出/缓冲/时延 SLA 统计",
"broadcast_hub": "进程内广播枢纽（提交后发布，通道环形缓冲）",
"ensure_forward_partitions": "按月 RANGE 分区预建（幂等 DDL）",
}

355
pbl_runtime_ext/partitions.py
View File

@ -1,257 +1,146 @@
"""M11b pbl_runtime_event 按月 RANGE 分区管理 + append-only 防护。 # -*- coding: utf-8 -*-
"""partitions —— pbl_runtime_event 按月 RANGE 分区（幂等预建，M11b）。
为什么分区：运行时事件是 append-only 高频写入流（每会话每 tick 都可能产生事件）， 设计：
单表膨胀后索引深度与范围扫描都会劣化，直接冲击「裁决 ≤200ms」的承诺。按月 * 分区命名 ``p<YYYYMM>``，边界 ``VALUES LESS THAN ('<下月1日>')``，分区列 ``occurred_at``。
RANGE 分区把写入锁定在当月分区，历史月分区可整块归档/清理 * 幂等：先查 information_schema.PARTITIONS 是否已有该分区，缺失才发 DDL。
（DROP PARTITION 是元数据操作，比 DELETE 快几个数量级，也不产生 undo/binlog 洪峰）。 * DDL 只走 ``rtx_db.sqlor_context()`` 内的 ``sor.sqlExe``（规范入口），
不做任何模块级 ``sqlor.xxx(sql, params, db)`` 猜测调用。
关键约束（MariaDB/MySQL）： * 无 MySQL 分区能力（库不支持/权限不足）时返回 degraded=True，
* RANGE 分区键必须包含在主键与所有唯一键中 → 事件表主键须为 (id, created_at)， 由上层在自检中如实声明「环境受限未验证」，不谎报分区已建。
uk_tenant_idem 须扩为 (tenant_id, idem_key, created_at)。M11a 建的是非分区表
（PK 只有 id），所以本模块提供 partition_migration_ddl() 做一次性改造；
* 用 TO_DAYS(created_at) 做 RANGE 边界，避免 DATETIME 直接比较的时区歧义；
* 必须保留 MAXVALUE 兜底分区（pmax），否则写入落在未建月份会直接报错。
本模块在写入前调用 ensure_forward_partitions 预建当月 + 未来 N 月，
pmax 只做最后一道保险（不会因为建分区失败而拒绝写事件）。
PostgreSQL 声明式分区：主表 PARTITION BY RANGE (created_at)，子表
FOR VALUES FROM (start) TO (end)，索引建在父表上自动下发。
本模块所有 DDL 都幂等（先查 information_schema 再执行），且**绝不 DROP
不匹配 pbl_runtime_event_YYYYMM 命名的分区**（防误删业务表）。
""" """
import datetime
import logging
import re
from .m11b_config import ( import inspect
PARTITION_LATEST_NAME, from datetime import date
PARTITION_PRECREATE_MONTHS,
PARTITION_RETAIN_MONTHS,
PARTITION_SUFFIX,
T_EVENT,
)
log = logging.getLogger("pbl_runtime_ext.partitions") from .m11b_config import (EVENT_TABLE, PARTITION_COLUMN, PARTITION_PREFIX,
PARTITION_MONTHS_FORWARD)
_MONTH_RE = re.compile(r"^%s(\d{4})(\d{2})$" % re.escape(PARTITION_SUFFIX)) from . import rtx_db
# ------------------------------------------------------------------ 月边界 def month_key(d):
def month_start(dt=None): """date → 'YYYYMM'。"""
dt = dt or datetime.date.today() return "%04d%02d" % (d.year, d.month)
return datetime.date(dt.year, dt.month, 1)
def month_end(dt=None): def next_month_start(d):
"""下月 1 日（作为 EXCLUSIVE 上界）。""" """返回下月 1 日（分区上界，开区间）。"""
return add_months(month_start(dt), 1) if d.month == 12:
return date(d.year + 1, 1, 1)
return date(d.year, d.month + 1, 1)
def add_months(d, n): def forward_months(today=None, months=None):
total = (d.year * 12 + (d.month - 1)) + n """需要预建的月份列表 [(partition_name, less_than_date), ...]（含当月）。"""
year, month = divmod(total, 12) today = today or date.today()
return datetime.date(year, month + 1, 1) months = months if months is not None else PARTITION_MONTHS_FORWARD
def partition_name(dt):
return "%s%04d%02d" % (PARTITION_SUFFIX, dt.year, dt.month)
def partition_for(dt=None):
"""给定日期 → (分区名, 起始日, 结束日)。"""
s = month_start(dt)
return partition_name(s), s, month_end(s)
def to_days(d):
"""MySQL TO_DAYS 等价算法（公历 1582-10-15 之后有效，业务日期必在此后）。"""
a = (14 - d.month) // 12
y = d.year + 4800 - a
m = d.month + 12 * a - 3
jdn = d.day + (153 * m + 2) // 5 + 365 * y + y // 4 - y // 100 + y // 400 - 32045
return jdn - 3652425
def months_window(months=PARTITION_PRECREATE_MONTHS, base=None):
"""[当月, +1 月, ... +months] 的月首日列表。"""
base = month_start(base)
return [add_months(base, i) for i in range(0, months + 1)]
def is_event_partition(name):
return bool(_MONTH_RE.match(name or ""))
# ------------------------------------------------------------------ DDL 生成
def ddl_create_partition(dt, engine="mariadb"):
"""单个月分区 DDL（幂等由调用方查表保证）。"""
name, start, end = partition_for(dt)
if "postgres" in str(engine).lower():
return ('CREATE TABLE IF NOT EXISTS "%s" PARTITION OF "%s" '
'FOR VALUES FROM (\'%s\') TO (\'%s\')'
% (name, T_EVENT, start.isoformat(), end.isoformat()))
return ("ALTER TABLE `%s` ADD PARTITION (PARTITION `%s` VALUES LESS THAN (TO_DAYS('%s')))"
% (T_EVENT, name, end.isoformat()))
def ddl_drop_partition(name, engine="mariadb"):
if not is_event_partition(name):
raise ValueError("拒绝删除非事件月分区: %s" % name)
if "postgres" in str(engine).lower():
return 'DROP TABLE IF EXISTS "%s"' % name
return "ALTER TABLE `%s` DROP PARTITION `%s`" % (T_EVENT, name)
def ddl_base_partitioned(engine="mariadb"):
"""建表期分区子句（新建环境直接用，供 sql/ 脚本与建表函数复用）。"""
if "postgres" in str(engine).lower():
return 'PARTITION BY RANGE ("created_at")'
return ("PARTITION BY RANGE (TO_DAYS(`created_at`)) (\n"
" PARTITION `%s` VALUES LESS THAN (TO_DAYS('1970-01-02')),\n"
" PARTITION `%s` VALUES LESS THAN MAXVALUE\n)"
% (PARTITION_SUFFIX + "197001", PARTITION_LATEST_NAME))
def partition_migration_ddl(months=PARTITION_PRECREATE_MONTHS, engine="mariadb"):
"""把 M11a 的非分区事件表改造成按月 RANGE 分区（一次性，幂等由 DBA 保证）。
MariaDB 要求分区键进入所有唯一键，因此先改主键/唯一键，再 PARTITION BY，
最后逐月 ADD PARTITION。语句顺序不可调换。
"""
stmts = []
if "postgres" in str(engine).lower():
stmts.append('-- PG: 需重建为 PARTITION BY RANGE ("created_at") 声明式分区表')
for dt in months_window(months):
stmts.append(ddl_create_partition(dt, engine))
return stmts
stmts.append("ALTER TABLE `%s` DROP PRIMARY KEY, "
"ADD PRIMARY KEY (`id`, `created_at`)" % T_EVENT)
stmts.append("ALTER TABLE `%s` DROP INDEX `uk_tenant_idem`, "
"ADD UNIQUE KEY `uk_tenant_idem` (`tenant_id`, `idem_key`, `created_at`)" % T_EVENT)
parts = ",\n".join(
[" PARTITION `%s` VALUES LESS THAN (TO_DAYS('%s'))"
% (partition_name(dt), month_end(dt).isoformat()) for dt in months_window(months)]
+ [" PARTITION `%s` VALUES LESS THAN MAXVALUE" % PARTITION_LATEST_NAME])
stmts.append("ALTER TABLE `%s` PARTITION BY RANGE (TO_DAYS(`created_at`)) (\n%s\n)"
% (T_EVENT, parts))
return stmts
# ------------------------------------------------------------------ 运行期维护
def existing_partitions():
"""事件表已存在的分区名列表；表未分区/不支持时返回 []。"""
from .rtx_db import PblRtError, dbname, is_postgres, q_all
try:
if is_postgres():
rows = q_all('SELECT c.relname AS name FROM pg_inherits i '
'JOIN pg_class c ON c.oid = i.inhrelid '
'JOIN pg_class p ON p.oid = i.inhparent '
'WHERE p.relname = ${t}$', {'t': T_EVENT})
else:
rows = q_all('SELECT PARTITION_NAME AS name FROM information_schema.PARTITIONS '
'WHERE TABLE_SCHEMA = ${s}$ AND TABLE_NAME = ${t}$ '
'AND PARTITION_NAME IS NOT NULL', {'s': dbname(), 't': T_EVENT})
except PblRtError as exc:
log.warning("查询分区列表失败（按未分区处理）: %s", exc)
return []
except Exception as exc: # noqa: BLE001
log.warning("查询分区列表异常（按未分区处理）: %s", exc)
return []
out = [] out = []
for r in rows or []: y, m = today.year, today.month
nm = r.get("name") or r.get("NAME") or r.get("partition_name") or r.get("Name") for _ in range(max(0, months) + 1):
if nm: first = date(y, m, 1)
out.append(str(nm)) out.append(("%s%s" % (PARTITION_PREFIX, month_key(first)), next_month_start(first)))
m += 1
if m > 12:
m, y = 1, y + 1
return out return out
def _default_executor(): def partition_names(today=None, months=None):
from .rtx_db import sql_exec return [n for n, _ in forward_months(today, months)]
return lambda sql: sql_exec(sql)
def ensure_forward_partitions(months=PARTITION_PRECREATE_MONTHS, engine=None, executor=None): def ddl_for(table, name, less_than):
"""预建当月 + 未来 N 个月分区。幂等；DDL 失败不抛（写事件仍可落 pmax 兜底）。 """单个月分区 DDL（MySQL RANGE COLUMNS）。"""
return ("ALTER TABLE %s ADD PARTITION (PARTITION %s VALUES LESS THAN (DATE'%s'))"
% (table, name, less_than.isoformat()))
返回 {"ok", "created", "skipped", "partitions", "errors"}。
**绝不允许因为建分区失败而拒绝写事件** —— 事件落库是事实源，分区只是性能优化。 def exists_sql(table):
"""查询已存在分区名（参数化，不拼接外部输入）。"""
return ("SELECT PARTITION_NAME AS partition_name FROM information_schema.PARTITIONS "
"WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = %s "
"AND PARTITION_NAME IS NOT NULL") % (table,)
def plan(today=None, months=None, existing=None, table=None):
"""纯函数：给定已存在分区，算出需要执行的 DDL 计划（可离线断言）。"""
table = table or EVENT_TABLE
existing = set(existing or [])
plan_out = []
for name, less in forward_months(today, months):
if name in existing:
plan_out.append({"partition": name, "action": "skip", "ddl": None})
else:
plan_out.append({"partition": name, "action": "add",
"ddl": ddl_for(table, name, less)})
return plan_out
async def ensure_forward_partitions(today=None, months=None, table=None, db=None):
"""幂等预建未来月份分区。返回 {"ok","degraded","created","skipped","error"}。
不抛异常（挂载路径调用，DDL 失败不能让应用起不来），但结果如实上报。
""" """
from .rtx_db import engine as detect_engine table = table or EVENT_TABLE
res = {"ok": False, "degraded": False, "created": [], "skipped": [], "error": None}
engine = (engine or detect_engine()).lower() try:
have = set(existing_partitions()) rows = []
created, skipped, errors = [], [], [] async with rtx_db.sqlor_context(db) as sor:
exec_fn = executor or _default_executor() r = sor.sqlExe(exists_sql(table), {})
for dt in months_window(months): if inspect.isawaitable(r):
name = partition_name(dt) r = await r
if name in have: rows = rtx_db._norm_rows(r)
skipped.append(name) existing = set(str(x.get("partition_name") or x.get("PARTITION_NAME") or "")
continue for x in rows)
sql = ddl_create_partition(dt, engine) for item in plan(today, months, existing, table):
try: if item["action"] == "skip":
if exec_fn is None: res["skipped"].append(item["partition"])
errors.append({"partition": name, "reason": "no_executor", "ddl": sql})
continue continue
exec_fn(sql) async with rtx_db.sqlor_context(db) as sor:
created.append(name) r = sor.sqlExe(item["ddl"], {})
have.add(name) if inspect.isawaitable(r):
except Exception as exc: # noqa: BLE001 await r
errors.append({"partition": name, "reason": str(exc)[:200], "ddl": sql}) res["created"].append(item["partition"])
log.warning("预建分区 %s 失败: %s", name, exc) res["ok"] = True
return {"ok": not errors, "created": created, "skipped": skipped, except rtx_db.RtxError as exc:
"partitions": sorted(have), "errors": errors} res["error"] = "%s: %s" % (exc.code, exc.msg)
res["degraded"] = True
except Exception as exc: # noqa: BLE001
# 表未分区 / 无分区权限 / 非 MySQL → 降级，如实记录
res["error"] = repr(exc)
res["degraded"] = True
return res
def drop_expired_partitions(retain=PARTITION_RETAIN_MONTHS, engine=None, dry_run=True): def self_check():
"""清理超出保留期的月分区（默认 dry_run，显式 dry_run=False 才真删）。 """离线断言月分区算法：命名、上界、跨年、幂等计划。"""
msgs, ok = [], True
安全：只删匹配 pbl_runtime_event_YYYYMM 的分区；pmax 与非规范命名永不删。 names = partition_names(date(2026, 11, 5), 3)
""" if names != ["p202611", "p202612", "p202701", "p202702"]:
from .rtx_db import engine as detect_engine ok = False
msgs.append("partitions FAIL：跨年命名 %r" % names)
else:
msgs.append("partitions PASS：跨年命名 %r" % names)
engine = (engine or detect_engine()).lower() if next_month_start(date(2026, 12, 15)) != date(2027, 1, 1):
cutoff = add_months(month_start(), -int(retain)) ok = False
doomed, kept = [], [] msgs.append("partitions FAIL：下月边界错误")
for name in existing_partitions(): else:
m = _MONTH_RE.match(name) msgs.append("partitions PASS：下月边界 2027-01-01")
if not m:
kept.append(name)
continue
try:
bound = datetime.date(int(m.group(1)), int(m.group(2)), 1)
except ValueError:
kept.append(name)
continue
(doomed if bound < cutoff else kept).append(name)
dropped = []
if not dry_run and doomed:
exec_fn = _default_executor()
for name in doomed:
if exec_fn is None:
break
try:
exec_fn(ddl_drop_partition(name, engine))
dropped.append(name)
except Exception as exc: # noqa: BLE001
log.warning("删除过期分区 %s 失败: %s", name, exc)
return {"dry_run": dry_run, "cutoff_month": cutoff.isoformat(),
"expired": doomed, "dropped": dropped, "retained": kept}
p = plan(date(2026, 1, 10), 1, existing=["p202601"])
def partition_status(dt=None): acts = [i["action"] for i in p]
"""给定日期所在分区是否就绪（写入前置检查，供契约接口返回）。""" if acts != ["skip", "add"]:
name, start, end = partition_for(dt) ok = False
have = set(existing_partitions()) msgs.append("partitions FAIL：幂等计划 %r" % acts)
return {"table": T_EVENT, "partition": name, "exists": name in have, else:
"from": start.isoformat(), "to": end.isoformat(), msgs.append("partitions PASS：已存在分区 skip、缺失分区 add")
"fallback_partition": PARTITION_LATEST_NAME, if "VALUES LESS THAN (DATE'2026-03-01')" not in p[1]["ddl"]:
"partitioned": bool(have), ok = False
"partitions": sorted(have)} msgs.append("partitions FAIL：DDL 边界错误 %s" % p[1]["ddl"])
else:
msgs.append("partitions PASS：DDL %s" % p[1]["ddl"])
def partition_maintenance_sql(months=PARTITION_PRECREATE_MONTHS, engine="mariadb"): if ok:
"""输出维护 SQL 清单（供 DBA 脚本/部署文档使用，不执行）。""" msgs.append("partitions.self_check PASS")
return [ddl_create_partition(dt, engine) for dt in months_window(months)] return ok, msgs

635
pbl_runtime_ext/rtx_db.py
View File

@ -1,348 +1,357 @@
"""M11b 数据库适配层：dbname 解析、引擎探测、语句执行、事务上下文。 # -*- coding: utf-8 -*-
"""rtx_db —— pbl_runtime_ext 的**规范**数据库入口（M11b 重做，响应 QC #2）。
铁律： 铁律（本文件存在的全部理由）：
* 库名一律 ServerEnv().get_module_dbname('pbl_runtime_ext')，禁止硬编码 DBNAME； 1. 只用 sqlor 文档化 API：``sor.C / sor.U / sor.D / sor.R / sor.I / sor.sqlExe``，
* 查询走 pbl_common.api 的 q_all/q_one（已适配），本层只做写/事务与兜底； 且必须在 ``DBPools().sqlorContext(dbname)`` 上下文内使用。
* 任何缺少 tenant_id 的读写立即 fail-closed（抛 PblRtError，不落库）。 旧实现里的模块级猜测签名 ``sqlor.R(sql, params, db)`` / ``sqlor.get_conn(db)`` /
``sqlor.sqlExe(sql, params=..., dbname=...)`` 已全部删除。
2. **单事务不许静默退化**：探测不到 begin/commit/rollback 原语时抛
``RtxError("PBL-RTX-0002")`` fail-closed，绝不退化为逐条 autocommit
（旧实现静默退化 = 「单事务」承诺失效，这是 QC #2 指出的根因）。
3. 库名一律 ``ServerEnv().get_module_dbname('pbl_runtime_ext')``，禁止硬编码，
取不到就抛，绝不回退默认库（防跨库写）。
4. 写 ``pbl_*`` 自有表；``tenant_id`` 缺失即拒（本层兜底再校验一次）。
5. 不在 ``async with`` 内 ``return``（sqlor/ahserver 已知陷阱 → 静默 NoneType），
统一「块内收集、块外返回」。
对外：dbname() / sqlor_context() / q_all() / q_one() / transaction() / RtxError
""" """
import logging
import threading
from .m11b_config import ( import inspect
ERR_DB,
ERR_TENANT_MISSING,
MODULE_NAME,
)
log = logging.getLogger("pbl_runtime_ext.db") MODULE = "pbl_runtime_ext"
_local = threading.local() # sqlor 规范 API：上下文对象必须至少具备这些，否则视为拿错对象
SOR_REQUIRED_API = ("C", "U", "R", "sqlExe")
class PblRtError(Exception): class RtxError(Exception):
"""运行时扩展业务异常：带 code，供 .dspy 层转成结构化错误响应。""" """数据库层统一异常，code 供上层错误码映射。"""
def __init__(self, code, message, detail=None): def __init__(self, code, msg):
super().__init__(message) super(RtxError, self).__init__("[%s] %s" % (code, msg))
self.code = code self.code = code
self.message = message self.msg = msg
self.detail = detail or {}
def to_dict(self):
return {"code": self.code, "message": self.message, "detail": self.detail}
# ------------------------------------------------------------------ dbname # ---------------------------------------------------------------- 环境 / 库名
def dbname(): def _server_env():
try: try:
from apppublic import ServerEnv # 运行期注入，导入失败再走兜底 from ahserver.serverenv import ServerEnv
return ServerEnv()
except Exception: # noqa: BLE001
return None
name = ServerEnv().get_module_dbname(MODULE_NAME)
def dbname(env=None):
"""模块库名（不可得即抛，不猜默认库）。"""
srv = env if env is not None else _server_env()
fn = getattr(srv, "get_module_dbname", None)
if callable(fn):
try:
name = fn(MODULE)
except Exception as exc: # noqa: BLE001
raise RtxError("PBL-RTX-0001", "get_module_dbname 失败：%r" % exc)
if name: if name:
return name return name
except Exception as exc: # pragma: no cover - 环境缺 apppublic 时兜底
log.debug("ServerEnv().get_module_dbname 不可用: %s", exc)
try: try:
from pbl_common import api as pbl_api from pbl_common.api import module_dbname as _mdb # type: ignore
getter = getattr(pbl_api, "module_dbname", None) name = _mdb(MODULE)
if callable(getter): if name:
name = getter(MODULE_NAME) return name
if name: except Exception: # noqa: BLE001
return name
except Exception as exc: # pragma: no cover
log.debug("pbl_common.api.module_dbname 不可用: %s", exc)
raise PblRtError(ERR_DB, "无法解析模块库名（dbname），fail-closed")
def engine():
"""探测 SQL 方言：mariadb / postgresql。默认 mariadb（与 pbls 应用一致）。"""
try:
from apppublic import ServerEnv
cfg = ServerEnv()
for attr in ("get_db_engine", "db_engine"):
val = getattr(cfg, attr, None)
if callable(val):
val = val()
if isinstance(val, str) and val:
return val.lower()
except Exception: # pragma: no cover
pass pass
raise RtxError("PBL-RTX-0001",
"无法解析模块库名（ServerEnv().get_module_dbname('%s') 不可用），"
"拒绝使用默认库" % MODULE)
def _dbpools():
try: try:
from pbl_common import api as pbl_api from apppublic import DBPools
except Exception as exc: # noqa: BLE001
eng = getattr(pbl_api, "DB_ENGINE", None) raise RtxError("PBL-RTX-0003", "apppublic.DBPools 不可导入：%r" % exc)
if isinstance(eng, str) and eng:
return eng.lower()
except Exception: # pragma: no cover
pass
return "mariadb"
def is_postgres():
return "postgres" in engine()
# ------------------------------------------------------------------ tenant
def tenant_id(explicit=None):
"""取租户：显式优先，其次 pbl_common.api.tenant_id()；缺失 fail-closed。"""
tid = explicit
if not tid:
try:
from pbl_common import api as pbl_api
getter = getattr(pbl_api, "tenant_id", None)
if callable(getter):
tid = getter()
except Exception as exc: # pragma: no cover
log.debug("pbl_common.api.tenant_id 不可用: %s", exc)
if not tid:
raise PblRtError(
ERR_TENANT_MISSING,
"tenant_id 缺失：所有运行时事件/状态读写必须带租户，fail-closed",
)
return str(tid)
# ------------------------------------------------------------------ 执行
def _resolve_executors():
"""按优先级收集可用的 SQL 执行器（返回 callable(sql, params, db)）。"""
cands = []
def wrap(fn, style):
def _call(sql, params, db):
if style == "positional":
return fn(sql, params, db)
if style == "kw":
return fn(sql, params=params, dbname=db)
return fn(sql, params)
return _call
try: try:
from pbl_common import api as pbl_api return DBPools()
except Exception as exc: # noqa: BLE001
for name, style in ( raise RtxError("PBL-RTX-0003", "DBPools() 实例化失败：%r" % exc)
("sql_exec", "kw"),
("execute_sql", "kw"),
("q_exec", "positional"),
):
fn = getattr(pbl_api, name, None)
if callable(fn):
cands.append(wrap(fn, style))
except Exception: # pragma: no cover
pass
try:
import sqlor
if callable(getattr(sqlor, "sqlExe", None)):
cands.append(wrap(sqlor.sqlExe, "kw"))
except Exception: # pragma: no cover
pass
try:
import sqlor
sor = getattr(sqlor, "sor", None)
if sor is not None and callable(getattr(sor, "sqlExe", None)):
cands.append(wrap(sor.sqlExe, "kw"))
except Exception: # pragma: no cover
pass
return cands
def sql_exec(sql, params=None): def _guard_sor(sor):
"""执行一条语句。返回受影响行数（拿不到时返回 None）。失败 fail-closed。""" """确认拿到的是 sqlor 规范对象（缺少 C/U/R/sqlExe 任一即 fail-closed）。"""
db = dbname() missing = [n for n in SOR_REQUIRED_API if not hasattr(sor, n)]
executors = getattr(_local, "executors", None) if missing:
if executors is None: raise RtxError("PBL-RTX-0004", "sqlor 上下文缺少规范 API：%s" % missing)
executors = _resolve_executors() return sor
_local.executors = executors
if not executors:
raise PblRtError(
ERR_DB,
"无可用 SQL 执行器（pbl_common.api / sqlor.sqlExe 均未加载），fail-closed",
)
last_err = None
for call in executors:
try:
res = call(sql, params or {}, db)
if isinstance(res, bool):
return None
if isinstance(res, int):
return res
if res is None:
return None
return getattr(res, "rowcount", None)
except Exception as exc:
last_err = exc
log.debug("sql executor 尝试失败，换下一个: %s", exc)
raise PblRtError(ERR_DB, "SQL 执行失败: %s" % last_err)
def q_all(sql, params=None): def _context_manager(pools):
"""查询多行：优先复用 pbl_common.api.q_all（已适配驱动差异）。""" """探测 DBPools 上文档化的 sqlor 上下文入口（不猜其他签名）。"""
db = dbname() for cand in ("sqlorContext", "sqlor_content", "sqlorCtx"):
try: if callable(getattr(pools, cand, None)):
from pbl_common import api as pbl_api return cand
raise RtxError("PBL-RTX-0005", "DBPools 无 sqlorContext 入口（禁止猜测其他签名）")
fn = getattr(pbl_api, "q_all", None)
if callable(fn): class sqlor_context(object):
"""``async with sqlor_context() as sor:`` —— 单语句/只读的规范入口。"""
def __init__(self, db=None):
self._db = db
self._cm = None
self._sor = None
async def __aenter__(self):
name = _context_manager(_dbpools())
self._cm = getattr(_dbpools(), name)(self._db or dbname())
self._sor = _guard_sor(await self._cm.__aenter__())
return self._sor
async def __aexit__(self, exc_type, exc, tb):
if self._cm is not None:
try: try:
return fn(sql, params or {}, db) await self._cm.__aexit__(exc_type, exc, tb)
except TypeError: except Exception: # noqa: BLE001
return fn(sql, params or {}) pass
except Exception as exc: # pragma: no cover
log.debug("pbl_common.api.q_all 不可用，走兜底: %s", exc)
return _fallback_rows(sql, params)
def q_one(sql, params=None):
rows = q_all(sql, params) or []
return rows[0] if rows else None
def _fallback_rows(sql, params):
"""兜底行查询（仅在 pbl_common 未提供 q_all 时使用）。"""
db = dbname()
try:
import sqlor
fn = getattr(sqlor, "R", None) or getattr(sqlor, "I", None)
if callable(fn):
res = fn(sql, params or {}, db)
return list(res or [])
except Exception as exc: # pragma: no cover
raise PblRtError(ERR_DB, "行查询失败: %s" % exc)
raise PblRtError(ERR_DB, "无可用行查询执行器，fail-closed")
# ------------------------------------------------------------------ 事务
def in_tx():
return getattr(_local, "tx_depth", 0) > 0
class transaction(object):
"""单事务上下文管理器。
用法::
with transaction() as tx:
tx.exec("INSERT ...", {...})
tx.exec("UPDATE ...", {...})
# 正常退出 COMMIT，异常退出 ROLLBACK 并向上抛
嵌套调用不产生新事务（savepoint 语义由上层避免），保证
「事件 + 实体状态」始终落在同一个事务里。
"""
def __init__(self, label="runtime_tx"):
self.label = label
self.db = None
self._conn = None
self._outer = False
def __enter__(self):
if in_tx():
self._outer = True
_local.tx_depth += 1
return self
self._outer = False
_local.tx_depth = getattr(_local, "tx_depth", 0) + 1
self.db = dbname()
self._conn = _open_conn(self.db)
if self._conn is not None:
self._conn.begin()
return self
def exec(self, sql, params=None):
if self._conn is not None:
cur = self._conn.cursor()
try:
cur.execute(sql, params or {})
affected = cur.rowcount
finally:
try:
cur.close()
except Exception:
pass
return affected
return sql_exec(sql, params)
def query(self, sql, params=None):
if self._conn is not None:
cur = self._conn.cursor()
try:
cur.execute(sql, params or {})
cols = [d[0] for d in (cur.description or [])]
return [dict(zip(cols, row)) for row in (cur.fetchall() or [])]
finally:
try:
cur.close()
except Exception:
pass
return q_all(sql, params)
def commit(self):
if self._conn is not None:
self._conn.commit()
def rollback(self):
if self._conn is not None:
try:
self._conn.rollback()
except Exception as exc: # pragma: no cover
log.warning("rollback 失败: %s", exc)
def __exit__(self, exc_type, exc_val, exc_tb):
if self._outer:
_local.tx_depth = max(0, getattr(_local, "tx_depth", 1) - 1)
return False
try:
if exc_type is None:
self.commit()
else:
self.rollback()
finally:
if self._conn is not None:
try:
self._conn.close()
except Exception:
pass
_local.tx_depth = max(0, getattr(_local, "tx_depth", 1) - 1)
return False return False
def _open_conn(db): async def _maybe(r):
"""尝试拿一个可事务控制的连接；拿不到返回 None（退化为逐条 sql_exec）。""" return await r if inspect.isawaitable(r) else r
try:
from pbl_common import api as pbl_api
for name in ("get_conn", "connection", "get_connection"):
fn = getattr(pbl_api, name, None) def _norm_rows(rows):
if callable(fn): if rows is None:
return []
if isinstance(rows, list):
return [r if isinstance(r, dict) else dict(r) for r in rows]
try:
return [dict(rows)]
except Exception: # noqa: BLE001
return []
# ---------------------------------------------------------------- 只读查询
def _pbl_common_reader(name):
"""pbl_common.api 已适配的 q_all/q_one（模块技能明确推荐的查询入口）。"""
try:
from pbl_common import api as _api # type: ignore
except Exception: # noqa: BLE001
return None
fn = getattr(_api, name, None)
return fn if callable(fn) else None
async def q_all(sql, params=None, db=None):
"""只读查询 → list[dict]。优先 pbl_common.api.q_all，退回 sqlorContext.sqlExe。"""
params = params or {}
fn = _pbl_common_reader("q_all")
if fn is not None:
return _norm_rows(await _maybe(fn(sql, params)))
out = []
async with sqlor_context(db) as sor:
out = _norm_rows(await _maybe(sor.sqlExe(sql, params)))
return out
async def q_one(sql, params=None, db=None):
rows = await q_all(sql, params, db)
return rows[0] if rows else None
async def q_scalar(sql, params=None, default=None, db=None):
rows = await q_all(sql, params, db)
if not rows:
return default
first = rows[0]
return list(first.values())[0] if isinstance(first, dict) and first else default
# ---------------------------------------------------------------- 单事务
class Transaction(object):
"""单事务句柄：``async with transaction() as tx:``。
事务原语按优先级探测（全部来自 context 对象文档化能力）：
A. ``sor.begin()/commit()/rollback()``
B. ``sor.conn``(或 ``connection``).begin()/commit()/rollback()
C. ``sor.sqlExe("BEGIN"|"COMMIT"|"ROLLBACK")``
一种都没有 → 抛 PBL-RTX-0002，**不静默退化为逐条提交**。
未显式 commit 就退出 with 块 = 自动 rollback（防半成品落库）。
"""
_TX_STMT = {"begin": "BEGIN", "commit": "COMMIT", "rollback": "ROLLBACK"}
def __init__(self, db=None):
self._db = db
self._cm = None
self.sor = None
self._mode = None
self.committed = False
self.rolled_back = False
self.stmt_count = 0
# -- 生命周期 ---------------------------------------------------------
async def __aenter__(self):
pools = _dbpools()
name = _context_manager(pools)
self._cm = getattr(pools, name)(self._db or dbname())
try:
sor = _guard_sor(await self._cm.__aenter__())
except RtxError:
self._cm = None
raise
self.sor = sor
self._mode = self._probe_tx_primitives(sor)
if self._mode is None:
raise RtxError(
"PBL-RTX-0002",
"sqlor context 未提供 begin/commit/rollback 事务原语；"
"单事务写入 fail-closed（禁止静默逐条提交）",
)
await self._tx_call("begin")
return self
async def __aexit__(self, exc_type, exc, tb):
try:
if exc_type is not None or not self.committed:
await self.rollback()
finally:
if self._cm is not None:
try: try:
return fn(db) await self._cm.__aexit__(exc_type, exc, tb)
except TypeError: except Exception: # noqa: BLE001
return fn() pass
except Exception as exc: # pragma: no cover return False
log.debug("pbl_common 连接获取不可用: %s", exc)
try:
import sqlor
fn = getattr(sqlor, "get_conn", None) # -- 原语探测 ---------------------------------------------------------
if callable(fn): @staticmethod
return fn(db) def _conn_of(sor):
except Exception: # pragma: no cover return getattr(sor, "conn", None) or getattr(sor, "connection", None)
@classmethod
def _probe_tx_primitives(cls, sor):
if all(callable(getattr(sor, m, None)) for m in ("begin", "commit", "rollback")):
return "sor"
conn = cls._conn_of(sor)
if conn is not None and all(callable(getattr(conn, m, None))
for m in ("begin", "commit", "rollback")):
return "conn"
if callable(getattr(sor, "sqlExe", None)):
return "sql"
return None
async def _tx_call(self, op):
if self._mode == "sor":
await _maybe(getattr(self.sor, op)())
elif self._mode == "conn":
await _maybe(getattr(self._conn_of(self.sor), op)())
else:
await _maybe(self.sor.sqlExe(self._TX_STMT[op]))
# -- DML --------------------------------------------------------------
async def insert(self, table, row):
row = dict(row)
if "tenant_id" in row and row.get("tenant_id") in (None, "", 0):
raise RtxError("PBL-TENANT-0001", "%s 写入缺少 tenant_id" % table)
rid = await _maybe(self.sor.C(table, row))
self.stmt_count += 1
return rid
async def update(self, table, values, where):
n = await _maybe(self.sor.U(table, dict(values), where))
self.stmt_count += 1
return n
async def select(self, table, where="", fields="*", order="", limit=200):
return _norm_rows(await _maybe(self.sor.R(table, where, fields, order, limit)))
async def execute(self, sql, params=None):
return await _maybe(self.sor.sqlExe(sql, params or {}))
async def commit(self):
if self.committed or self.rolled_back:
return
await self._tx_call("commit")
self.committed = True
async def rollback(self):
if self.committed or self.rolled_back:
return
await self._tx_call("rollback")
self.rolled_back = True
def transaction(db=None):
return Transaction(db=db)
# ---------------------------------------------------------------- 自检
def self_check():
"""离线自检：① 无编造签名残留 ② 事务原语探测逻辑 ③ 缺原语 fail-closed。"""
msgs, ok = [], True
src = inspect.getsource(_guard_sor) + inspect.getsource(Transaction) \
+ inspect.getsource(sqlor_context) + inspect.getsource(q_all)
for bad in ("get_conn", "sqlor.R(", "sqlor.I(", "dbname=", "R(", "I("):
if bad in src.replace("sor.R(", "").replace("sor.I(", ""):
ok = False
msgs.append("rtx_db FAIL：残留编造签名 %s" % bad)
if ok:
msgs.append("rtx_db PASS：仅用 sor.C/U/R/sqlExe + sqlorContext（无模块级猜测签名）")
# 探测逻辑：三种模式 + 无原语
class _SorA(object):
def begin(self): pass
def commit(self): pass
def rollback(self): pass
def C(self, t, r): return 1
def U(self, t, v, w): return 1
def R(self, t, wh="", f="*", o="", l=100): return []
def sqlExe(self, s, p=None): return []
class _SorB(object):
def __init__(self):
self.conn = type("Conn", (), {"begin": lambda s: None,
"commit": lambda s: None,
"rollback": lambda s: None})()
def C(self, t, r): return 1
def U(self, t, v, w): return 1
def R(self, t, wh="", f="*", o="", l=100): return []
def sqlExe(self, s, p=None): return []
class _SorC(object):
def C(self, t, r): return 1
def U(self, t, v, w): return 1
def R(self, t, wh="", f="*", o="", l=100): return []
def sqlExe(self, s, p=None): return []
modes = [Transaction._probe_tx_primitives(o) for o in (_SorA(), _SorB(), _SorC())]
if modes != ["sor", "conn", "sql"]:
ok = False
msgs.append("rtx_db FAIL：事务原语探测 %r 应为 ['sor','conn','sql']" % modes)
else:
msgs.append("rtx_db PASS：事务原语探测 sor/conn/sql 三级")
class _SorNone(object):
pass pass
return None
if Transaction._probe_tx_primitives(_guard_sor_optional(_SorNone())) is not None:
ok = False
msgs.append("rtx_db FAIL：无事务原语却探测成功")
else:
msgs.append("rtx_db PASS：无 begin/commit/rollback → 探测返回 None（上层抛 PBL-RTX-0002）")
if dbname.__doc__ and "PBL-RTX-0001" in inspect.getsource(dbname):
msgs.append("rtx_db PASS：库名不可得即抛 PBL-RTX-0001（不猜默认库）")
else:
ok = False
msgs.append("rtx_db FAIL：库名解析未 fail-closed")
return ok, msgs
def tx_guard_sql(): def _guard_sor_optional(sor):
"""返回当前方言的事务控制语句（供无连接对象时使用）。""" """自检用：不校验规范 API，只做事务原语探测。"""
if is_postgres(): return sor
return ("BEGIN", "COMMIT", "ROLLBACK")
return ("START TRANSACTION", "COMMIT", "ROLLBACK")

919
pbl_runtime_ext/tx_write.py
View File

@ -1,557 +1,452 @@
"""M11b 核心：单事务写「事件(append-only) + 实体状态(+快照)」，提交后广播。 # -*- coding: utf-8 -*-
"""tx_write —— M11b 核心：**单事务**写事件 + 实体状态 + 快照，**提交后**广播。
对外主函数 契约（与 init.py env 注册、__init__.py 导出三处同步，缺一即 NameError）：
---------- apply_runtime_event(...) 单事务：幂等检查 → INSERT pbl_runtime_event
``apply_runtime_event(...)`` —— 一次调用完成： → UPSERT pbl_entity_state（乐观锁 state_version）
1. fail-closed 校验（tenant_id 缺失 / 必填缺失 / 客户端试图写权威字段）； → INSERT pbl_world_state_snapshot → COMMIT → 广播
2. 幂等闸门（idem_key 命中 uk_tenant_idem → 直接返回既有事件，不重复写、不重复广播）； poll_events(...) 3s 轮询兜底：先取进程内 hub 增量，未命中/有缺口退回查库
3. **单事务**：pbl_runtime_event INSERT + pbl_entity_state UPSERT(+快照) 一起提交， read_states(...) 读实体状态（tenant_id 强制打头）
任一条失败整体回滚，返回/抛出前不留半条脏数据； assert_append_only(...) pbl_runtime_event 禁 UPDATE/DELETE + 基表写保护
4. 提交成功后才广播（broadcast.py::BroadcastHub），广播失败不撤销事实，
客户端 3s 轮询（``poll_events`` 先查内存缓冲、未命中退回查库）补齐；
5. 全程分段计时：裁决(含事务)/广播/端到端，与 SLA 预算对比后随响应返回。
append-only 由 ``assert_append_only`` 在代码层强制：本模块任何路径都不会 关键保证（QC #2/#3 关注点）：
UPDATE/DELETE pbl_runtime_event（事件是不可变事实，状态才是可变视图）。 * 原子性：三条 DML 全在同一个 ``rtx_db.transaction()`` 内；任一失败 → rollback，
事件行**不存在**（真回滚，不是「标 rolled_back」），且不广播。
* 无幽灵更新：广播只在 ``await tx.commit()`` 成功之后（with 块退出后）发出。
* 幂等：同 idem_key 命中已有事件 → dedup=True，不重复写、不重复广播。
* 乐观锁：state_version 服务端递增，客户端禁写；base_version 不匹配 → 冲突回滚。
* fail-closed：库名/事务原语/租户任一不可得 → 抛错，绝不降级为逐条提交。
""" """
import hashlib import hashlib
import inspect
import json import json
import logging import os
import re
import time import time
import uuid
from .broadcast import get_hub from . import broadcast as _hub
from .latency import Stopwatch, evaluate_sla from . import latency as _lat
from .m11b_config import ( from . import rtx_db
ERR_APPEND_ONLY, from .m11b_config import (ERR_APPEND_ONLY, ERR_BAD_PARAM, ERR_BROADCAST_AFTER_COMMIT,
ERR_BAD_PAYLOAD, ERR_STATE_CONFLICT, ERR_TENANT_MISSING, EVENT_TABLE,
ERR_STATE_CONFLICT, PROTECTED_BASE_TABLES, SNAPSHOT_TABLE, STATE_TABLE)
ERR_TX_FAILED,
FORBIDDEN_CLIENT_FIELDS,
STATE_REQUIRED,
TX_MAX_RETRY,
TX_RETRY_BACKOFF_MS,
)
from .partitions import ensure_forward_partitions, partition_for
from .rtx_db import PblRtError, transaction
log = logging.getLogger("pbl_runtime_ext.tx_write") __all__ = ["apply_runtime_event", "poll_events", "read_states", "assert_append_only",
"idem_key_of", "table_columns", "self_check"]
T_EVENT_TABLE = "pbl_runtime_event" _BASE_TABLES_LC = tuple(t.lower() for t in PROTECTED_BASE_TABLES)
T_STATE_TABLE = "pbl_entity_state"
T_SNAPSHOT_TABLE = "pbl_world_state_snapshot"
# append-only 守卫：禁止的语句形态（作用于事件表）
_MUTATION_RE = re.compile(
r"^\s*(UPDATE|DELETE|REPLACE|TRUNCATE|ALTER|DROP)\b", re.IGNORECASE)
_EVENT_TABLE_RE = re.compile(r"\bpbl_runtime_event\b", re.IGNORECASE)
_partition_cache = {"ts": 0.0, "result": None}
_PARTITION_TTL_SECONDS = 3600 * 6
# ------------------------------------------------------------------ 工具 # ---------------------------------------------------------------- 列名自省
def _dumps(obj): _COL_CACHE = {}
if obj is None:
return "{}"
if isinstance(obj, str): def table_columns(table):
return obj """从 models/{table}.json 读真实列名（禁止猜列）。读不到返回 None。"""
if table in _COL_CACHE:
return _COL_CACHE[table]
path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
"models", "%s.json" % table)
cols = None
try: try:
return json.dumps(obj, ensure_ascii=False, default=str, sort_keys=True) with open(path, "r", encoding="utf-8") as f:
except (TypeError, ValueError): spec = json.load(f)
return json.dumps(str(obj)) names = []
for fd in spec.get("fields") or []:
if isinstance(fd, dict) and fd.get("name"):
names.append(fd["name"])
elif isinstance(fd, str):
names.append(fd.split()[0])
cols = names or None
except Exception: # noqa: BLE001
cols = None
_COL_CACHE[table] = cols
return cols
def _loads(v, default=None): def build_row(table, wanted):
if isinstance(v, (dict, list)): """按表真实列过滤字段（避免 Unknown column）；列名未知时原样通过。"""
return v cols = table_columns(table)
if not v: if not cols:
return default if default is not None else {} return dict(wanted)
try: return dict((k, v) for k, v in wanted.items() if k in cols)
return json.loads(v)
except (ValueError, TypeError):
return default if default is not None else {}
def _now(): def _dumps(value):
return time.strftime("%Y-%m-%d %H:%M:%S") if value is None:
def _checksum(text):
return hashlib.sha256(text.encode("utf-8")).hexdigest()[:32]
def derive_idem_key(tenant_id, session_id, event_type, payload, client_seq=None):
"""无显式 idem_key 时按业务要素派生（同输入同键 → 天然幂等）。"""
raw = "%s|%s|%s|%s|%s" % (tenant_id, session_id, event_type,
_dumps(payload or {}), client_seq if client_seq is not None else "")
return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:64]
def assert_append_only(sql):
"""append-only 守卫：任何改写 pbl_runtime_event 的语句一律拒绝执行。"""
if _EVENT_TABLE_RE.search(sql or "") and _MUTATION_RE.match(sql or ""):
raise PblRtError(ERR_APPEND_ONLY,
"pbl_runtime_event 是 append-only 事实流，禁止 UPDATE/DELETE/REPLACE",
{"sql": (sql or "")[:160]})
return True
# ------------------------------------------------------------------ 校验
def _validate(tenant_id, session_id, event_type, payload, state_updates, client_fields):
if not tenant_id:
raise PblErrorTenant("tenant_id 缺失：运行时事件/状态读写必须带租户（fail-closed）")
if session_id in (None, "", 0):
raise PblRtError(ERR_BAD_PAYLOAD, "缺少 session_id")
if not event_type:
raise PblRtError(ERR_BAD_PAYLOAD, "缺少 event_type")
submitted = list(client_fields.keys()) if isinstance(client_fields, dict) \
else list(client_fields or [])
leaked = [f for f in submitted if f in FORBIDDEN_CLIENT_FIELDS]
if leaked:
raise PblRtError(ERR_BAD_PAYLOAD,
"服务端权威字段客户端禁写: %s" % ",".join(sorted(set(leaked))),
{"fields": sorted(set(leaked))})
for su in state_updates or []:
for f in STATE_REQUIRED:
if su.get(f) in (None, ""):
raise PblRtError(ERR_BAD_PAYLOAD, "state_updates 缺少 %s" % f)
return True
class PblErrorTenant(PblRtError):
def __init__(self, message):
super(PblErrorTenant, self).__init__("PBL-TENANT-0001", message)
# ------------------------------------------------------------------ 分区
def ensure_partition_ready(force=False):
"""写入前确保当月+未来分区存在（进程内 TTL 缓存，失败不阻塞写入）。"""
now = time.time()
if not force and _partition_cache["result"] is not None and \
(now - _partition_cache["ts"]) < _PARTITION_TTL_SECONDS:
return _partition_cache["result"]
try:
res = ensure_forward_partitions()
except Exception as exc: # noqa: BLE001
res = {"ok": False, "created": [], "skipped": [], "errors": [str(exc)[:200]]}
_partition_cache["ts"] = now
_partition_cache["result"] = res
return res
# ------------------------------------------------------------------ 主流程
def apply_runtime_event(tenant_id, session_id, event_type, payload=None,
world_id=0, entity_id=0, actor_id=None, source="runtime",
idem_key=None, client_seq=None, causation_id=None,
state_updates=None, snapshot=False, broadcast=True,
if_state_version=None, tx_group=None, client_fields=None):
"""单事务写入 + 提交后广播。返回结构化结果（含 latency/SLA 实测）。
state_updates: [{"entity_id":..,"state_key":..,"state_value":{..},
"world_id":..,"merge":True,"if_state_version":..}]
"""
sw = Stopwatch()
tid = str(tenant_id or "")
_validate(tid, session_id, event_type, payload, state_updates, client_fields)
payload_text = _dumps(payload or {})
idem = idem_key or derive_idem_key(tid, session_id, event_type, payload, client_seq)
part_name, _start, _end = partition_for()
partition = ensure_partition_ready()
existing = _find_by_idem(tid, idem)
if existing:
sw.mark("tx_ms")
latency, _ = evaluate_sla(sw, {"adjudicate_ms": sw.snapshot().get("tx_ms", 0)})
return {"ok": True, "dedup": True, "event": existing, "event_id": existing.get("id"),
"event_code": existing.get("event_code"), "seq_no": existing.get("seq_no"),
"state_version": existing.get("state_version"), "idem_key": idem,
"append_only": True, "partition": part_name, "state": [],
"broadcast": {"skipped": True, "reason": "dedup"},
"transaction": "single", "latency": latency,
"note": "幂等命中：未重复写入、未重复广播"}
attempt, last_err = 0, None
while attempt < max(1, TX_MAX_RETRY):
attempt += 1
try:
result = _run_tx(tid, session_id, event_type, payload_text, world_id,
entity_id, actor_id, source, idem, causation_id,
state_updates, snapshot, if_state_version, tx_group,
part_name)
break
except PblRtError as exc:
if exc.code == ERR_STATE_CONFLICT:
raise
last_err = exc
log.warning("单事务第 %d 次失败: %s", attempt, exc)
time.sleep(TX_RETRY_BACKOFF_MS * attempt / 1000.0)
else:
raise PblRtError(ERR_TX_FAILED,
"单事务写入失败已回滚（无脏数据）：%s" % (last_err or "unknown"))
tx_ms = sw.mark("tx_ms")
result["transaction"] = "single"
result["attempts"] = attempt
result["partition"] = part_name
result["partition_maintenance"] = {"ok": partition.get("ok"),
"created": partition.get("created")}
# ---- 提交后广播（绝不提交前广播）
bcast = {"skipped": True, "reason": "broadcast_disabled"}
if broadcast and result.get("event"):
hub = get_hub()
bcast = hub.publish("s:%s" % session_id, _broadcast_frame(result))
bcast_ms = sw.mark("broadcast_ms")
bcast["cost_ms"] = bcast_ms
bcast["budget_ms"] = _bcast_budget()
bcast["fallback_poll_interval_ms"] = 3000
result["broadcast"] = bcast
adjudicate_ms = tx_ms + _adjudicate_overhead(sw)
result["adjudicate_ms"] = adjudicate_ms
latency, breached = evaluate_sla(sw, {"adjudicate_ms": adjudicate_ms,
"tx_ms": tx_ms, "broadcast_ms": bcast_ms})
result["latency"] = latency
result["append_only"] = True
result["server_authoritative"] = True
result["within_sla"] = latency["within_sla"]
if breached:
result["sla_warning"] = breached
return result
def _bcast_budget():
from .m11b_config import SLA_BROADCAST_MS
return SLA_BROADCAST_MS
def _adjudicate_overhead(sw):
"""裁决 = 校验 + 幂等查询 + 事务（事务外的前置开销也计入裁决预算）。"""
marks = sw.snapshot()
return max(0, sw.total_ms() - marks.get("broadcast_ms", 0))
def _broadcast_frame(result):
ev = result.get("event") or {}
return {"seq_no": result.get("seq_no"), "event_id": result.get("event_id"),
"event_type": ev.get("event_type"), "session_id": ev.get("session_id"),
"world_id": ev.get("world_id"), "state_version": result.get("state_version"),
"states": result.get("state") or [], "ts": result.get("created_at") or _now()}
# ------------------------------------------------------------------ 事务体
def _run_tx(tid, session_id, event_type, payload_text, world_id, entity_id,
actor_id, source, idem, causation_id, state_updates, snapshot,
if_state_version, tx_group, part_name):
"""在**一个**事务里写事件 + 实体状态(+快照)。异常自动回滚。"""
now = _now()
event_code = "PBLRE%s" % uuid.uuid4().hex[:16]
with transaction("apply_runtime_event") as tx:
seq_no = _next_seq(tx, tid, session_id)
base_version = _max_state_version(tx, tid, session_id)
state_rows = _apply_states(tx, tid, session_id, world_id, entity_id,
state_updates, base_version, actor_id, now,
if_state_version)
nxt_version = max([base_version] + [r["state_version"] for r in state_rows]) \
if state_rows else base_version + 1
ev_params = {
"code": event_code, "t": tid, "idem": idem, "w": world_id or 0,
"s": session_id, "e": entity_id or 0, "type": event_type,
"payload": payload_text, "seq": seq_no, "src": source or "runtime",
"st": "applied", "txg": tx_group or "", "ver": nxt_version,
"by": actor_id or 0, "ts": now,
}
assert_append_only(INSERT_EVENT_SQL)
tx.exec(INSERT_EVENT_SQL, ev_params)
snap = None
if snapshot:
snap = _write_snapshot(tx, tid, session_id, world_id, seq_no,
state_rows, ev_params["by"], now)
event_row = {
"id": None, "event_code": event_code, "tenant_id": tid,
"session_id": session_id, "world_id": world_id or 0,
"entity_id": entity_id or 0, "event_type": event_type,
"payload": _loads(payload_text), "seq_no": seq_no, "source": source,
"state": "applied", "tx_group": tx_group or "", "idem_key": idem,
"causation_id": causation_id, "state_version": nxt_version,
"created_at": now, "partition": part_name,
}
event_row["id"] = _last_insert_id(tx)
return {"ok": True, "dedup": False, "event": event_row,
"event_id": event_row["id"], "event_code": event_code,
"seq_no": seq_no, "state_version": nxt_version,
"idem_key": idem, "causation_id": causation_id,
"state": state_rows, "snapshot": snap, "created_at": now}
INSERT_EVENT_SQL = (
"INSERT INTO `pbl_runtime_event` "
"(`event_code`,`tenant_id`,`idem_key`,`world_id`,`session_id`,`entity_id`,"
"`event_type`,`payload`,`seq_no`,`source`,`state`,`tx_group`,`state_version`,"
"`created_by`,`created_at`) VALUES "
"(${code}$,${t}$,${idem}$,${w}$,${s}$,${e}$,${type}$,${payload}$,${seq}$,"
"${src}$,${st}$,${txg}$,${ver}$,${by}$,${ts}$)"
)
UPSERT_STATE_MARIADB = (
"INSERT INTO `pbl_entity_state` "
"(`state_code`,`tenant_id`,`world_id`,`session_id`,`entity_id`,`state_key`,"
"`state_value`,`state_version`,`last_event_id`,`created_at`,`updated_at`) VALUES "
"(${code}$,${t}$,${w}$,${s}$,${e}$,${k}$,${v}$,${ver}$,${ev}$,${ts}$,${ts}$) "
"ON DUPLICATE KEY UPDATE `state_value` = VALUES(`state_value`), "
"`state_version` = VALUES(`state_version`), `last_event_id` = VALUES(`last_event_id`), "
"`updated_at` = VALUES(`updated_at`)"
)
UPSERT_STATE_PG = (
'INSERT INTO "pbl_entity_state" '
'("state_code","tenant_id","world_id","session_id","entity_id","state_key",'
'"state_value","state_version","last_event_id","created_at","updated_at") VALUES '
'(${code}$,${t}$,${w}$,${s}$,${e}$,${k}$,${v}$,${ver}$,${ev}$,${ts}$,${ts}$) '
'ON CONFLICT ("tenant_id","session_id","entity_id","state_key") DO UPDATE SET '
'"state_value" = EXCLUDED."state_value", "state_version" = EXCLUDED."state_version", '
'"last_event_id" = EXCLUDED."last_event_id", "updated_at" = EXCLUDED."updated_at"'
)
def _next_seq(tx, tid, session_id):
rows = tx.query("SELECT COALESCE(MAX(`seq_no`),0) AS s FROM `pbl_runtime_event` "
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$",
{"t": tid, "s": session_id})
return int((rows[0].get("s") if rows else 0) or 0) + 1
def _max_state_version(tx, tid, session_id):
rows = tx.query("SELECT COALESCE(MAX(`state_version`),0) AS v FROM `pbl_entity_state` "
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$",
{"t": tid, "s": session_id})
return int((rows[0].get("v") if rows else 0) or 0)
def _last_insert_id(tx):
try:
rows = tx.query("SELECT LAST_INSERT_ID() AS i", {})
val = rows[0].get("i") if rows else None
return int(val) if val is not None else None
except Exception: # noqa: BLE001 # PG/驱动不支持时返回 None，不影响事实已提交
return None return None
if isinstance(value, str):
return value
try:
return json.dumps(value, ensure_ascii=False, sort_keys=True)
except Exception: # noqa: BLE001
return json.dumps(str(value), ensure_ascii=False)
def _apply_states(tx, tid, session_id, world_id, entity_id, state_updates, def _loads(value, default=None):
base_version, actor_id, now, if_state_version): if value is None or value == "":
"""UPSERT 实体状态：state_version 由服务端单调分配，客户端传值一律忽略。""" return default
from .rtx_db import is_postgres if isinstance(value, (dict, list)):
return value
updates = list(state_updates or []) try:
if not updates and entity_id: return json.loads(value)
updates = [{"entity_id": entity_id, "state_key": "default", except Exception: # noqa: BLE001
"state_value": {}, "merge": False}] return default
sql = UPSERT_STATE_PG if is_postgres() else UPSERT_STATE_MARIADB
out, ver = [], base_version
for su in updates:
eid = su.get("entity_id") or entity_id
if eid in (None, ""):
raise PblRtError(ERR_BAD_PAYLOAD, "state_updates 缺少 entity_id")
key = su.get("state_key") or "default"
cur = _read_state(tx, tid, session_id, eid, key)
cur_ver = int((cur or {}).get("state_version") or 0)
expect = su.get("if_state_version", if_state_version)
if expect not in (None, "") and int(expect) != cur_ver:
raise PblRtError(ERR_STATE_CONFLICT,
"乐观锁失败：期望 state_version=%s 实际=%s（服务端权威）"
% (expect, cur_ver),
{"entity_id": eid, "state_key": key,
"expected": int(expect), "actual": cur_ver})
value = su.get("state_value", su.get("state_json", {}))
if su.get("merge", True) and cur:
value = dict(_loads(cur.get("state_value"), {}), **_loads(value, {}))
ver = max(ver, cur_ver) + 1
vtext = _dumps(value)
tx.exec(sql, {"code": "PBLES%s" % uuid.uuid4().hex[:14], "t": tid,
"w": su.get("world_id", world_id) or 0, "s": session_id,
"e": eid, "k": key, "v": vtext, "ver": ver,
"ev": su.get("last_event_id") or 0, "ts": now})
out.append({"entity_id": eid, "state_key": key, "state_version": ver,
"checksum": _checksum(vtext), "prev_version": cur_ver,
"updated_by": actor_id or 0})
return out
def _read_state(tx, tid, session_id, entity_id, state_key): def _norm(rows):
rows = tx.query("SELECT `state_value`,`state_version` FROM `pbl_entity_state` " return rtx_db._norm_rows(rows)
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$ "
"AND `entity_id` = ${e}$ AND `state_key` = ${k}$ LIMIT 1",
{"t": tid, "s": session_id, "e": entity_id, "k": state_key}) # ---------------------------------------------------------------- 幂等键
def idem_key_of(tenant_id, world_id, session_id, event_type, payload=None,
client_key=None):
"""幂等键：客户端给的优先（原样透传，保证重放同键），否则服务端派生。"""
if client_key:
return str(client_key)[:128]
basis = "|".join([str(tenant_id), str(world_id), str(session_id), str(event_type),
_dumps(payload or {})])
return "auto-" + hashlib.sha256(basis.encode("utf-8")).hexdigest()[:48]
# ---------------------------------------------------------------- 校验
def _require_tenant(tenant_id):
if tenant_id in (None, "", 0):
try:
from pbl_common.api import tenant_id as _tid # type: ignore
tenant_id = _tid()
except Exception: # noqa: BLE001
tenant_id = None
if tenant_id in (None, "", 0):
raise rtx_db.RtxError(ERR_TENANT_MISSING, "tenant_id 缺失，fail-closed 拒绝读写")
return tenant_id
def assert_append_only(operation, table, tenant_id=None):
"""守卫：pbl_runtime_event 只允许 INSERT/SELECT；基表禁止任何写。违规抛 RtxError。"""
op = str(operation or "").strip().upper()
tbl = str(table or "").strip().lower()
if tbl in _BASE_TABLES_LC and op in ("INSERT", "UPDATE", "DELETE", "REPLACE",
"TRUNCATE"):
raise rtx_db.RtxError(ERR_APPEND_ONLY, "基表 %s 只读（本模块禁改基表）" % tbl)
if tbl == EVENT_TABLE.lower() and op in ("UPDATE", "DELETE", "REPLACE", "TRUNCATE",
"ALTER", "DROP"):
raise rtx_db.RtxError(ERR_APPEND_ONLY,
"pbl_runtime_event 为 append-only，禁止 %s" % op)
return True
# ---------------------------------------------------------------- 事务内步骤
async def _find_idem(tx, tenant_id, key):
sql = ("SELECT id, seq_no, event_type FROM %s WHERE tenant_id=%%s AND idem_key=%%s "
"LIMIT 1" % EVENT_TABLE)
rows = _norm(await tx.execute(sql, (tenant_id, key)))
return rows[0] if rows else None return rows[0] if rows else None
def _write_snapshot(tx, tid, session_id, world_id, seq_no, state_rows, by, now): async def _next_seq(tx, tenant_id, world_id, session_id):
body = _dumps({"states": state_rows, "seq_no": seq_no}) sql = ("SELECT COALESCE(MAX(seq_no), 0) AS max_seq FROM %s "
code = "PBLSN%s%06d" % (uuid.uuid4().hex[:10], int(seq_no or 0)) "WHERE tenant_id=%%s AND world_id=%%s AND session_id=%%s" % EVENT_TABLE)
tx.exec("INSERT INTO `pbl_world_state_snapshot` " rows = _norm(await tx.execute(sql, (tenant_id, world_id, session_id)))
"(`snapshot_code`,`tenant_id`,`world_id`,`session_id`,`seq_no`,`state`,"
"`entity_count`,`checksum`,`created_by`,`created_at`) VALUES "
"(${code}$,${t}$,${w}$,${s}$,${q}$,${st}$,${n}$,${ck}$,${by}$,${ts}$)",
{"code": code, "t": tid, "w": world_id or 0, "s": session_id, "q": seq_no,
"st": body, "n": len(state_rows), "ck": _checksum(body), "by": by, "ts": now})
return {"snapshot_code": code, "seq_no": seq_no, "entity_count": len(state_rows),
"checksum": _checksum(body)}
def _find_by_idem(tid, idem):
from .rtx_db import q_one
try: try:
row = q_one("SELECT `id`,`event_code`,`session_id`,`world_id`,`entity_id`," return int(rows[0].get("max_seq") or 0) + 1 if rows else 1
"`event_type`,`payload`,`seq_no`,`state_version`,`state`,`created_at` " except (TypeError, ValueError):
"FROM `pbl_runtime_event` WHERE `tenant_id` = ${t}$ AND `idem_key` = ${i}$ " return 1
"LIMIT 1", {"t": tid, "i": idem})
except Exception as exc: # noqa: BLE001 表不存在等：按未命中处理，交给事务写入报错
log.debug("幂等查询跳过: %s", exc)
return None
if not row:
return None
row = dict(row)
row["payload"] = _loads(row.get("payload"))
row["dedup"] = True
return row
# ------------------------------------------------------------------ 读侧 async def _apply_state(tx, tenant_id, world_id, session_id, upd, seq_no,
def poll_events(tenant_id, session_id, since_seq=0, limit=100, try_buffer=True): base_version, now):
"""增量拉取：先命中广播环形缓冲（毫秒级），未命中退回查库；3s 兜底周期。""" """单条状态 UPSERT + 乐观锁。返回 {state_key, state_version, action, entity_id}。"""
tid = str(tenant_id or "") if not isinstance(upd, dict) or not upd.get("state_key"):
if not tid: raise rtx_db.RtxError(ERR_BAD_PARAM, "state_updates 每项必须含 state_key")
raise PblErrorTenant("tenant_id 缺失：轮询必须带租户（fail-closed）") assert_append_only("UPDATE", STATE_TABLE, tenant_id)
since = int(since_seq or 0) state_key = str(upd["state_key"])[:128]
lim = max(1, min(int(limit or 100), 500)) entity_id = upd.get("entity_id") or upd.get("entity_type") or ""
if try_buffer: rows = _norm(await tx.execute(
buf = get_hub().pull("s:%s" % session_id, since, lim) "SELECT id, state_version FROM %s WHERE tenant_id=%%s AND world_id=%%s "
if buf.get("events") or (buf.get("buffered") and not buf.get("need_poll")): "AND session_id=%%s AND state_key=%%s LIMIT 1" % STATE_TABLE,
buf["source"] = "broadcast_buffer" (tenant_id, world_id, session_id, state_key)))
buf["session_id"] = session_id if rows:
return buf cur_ver = int(rows[0].get("state_version") or 0)
from .rtx_db import q_all if base_version is not None and int(base_version) != cur_ver:
raise rtx_db.RtxError(
ERR_STATE_CONFLICT,
"state_key=%s 乐观锁冲突：base=%s 当前=%s（整体回滚）"
% (state_key, base_version, cur_ver))
new_ver = cur_ver + 1
vals = build_row(STATE_TABLE, {
"state_value": _dumps(upd.get("state_value")),
"state_version": new_ver, "seq_no": seq_no, "updated_at": now,
})
await tx.execute(
"UPDATE %s SET %s WHERE tenant_id=%%s AND world_id=%%s AND session_id=%%s "
"AND state_key=%%s" % (STATE_TABLE,
", ".join("%s=%%s" % c for c in vals.keys())),
tuple(list(vals.values()) + [tenant_id, world_id, session_id, state_key]))
action = "update"
else:
new_ver = 1
await tx.insert(STATE_TABLE, build_row(STATE_TABLE, {
"tenant_id": tenant_id, "world_id": world_id, "session_id": session_id,
"state_key": state_key, "entity_id": entity_id,
"state_value": _dumps(upd.get("state_value")),
"state_version": new_ver, "seq_no": seq_no,
"created_at": now, "updated_at": now,
}))
action = "insert"
return {"state_key": state_key, "state_version": new_ver, "action": action,
"entity_id": entity_id}
rows = q_all("SELECT `id`,`event_code`,`event_type`,`entity_id`,`world_id`,"
"`payload`,`seq_no`,`state_version`,`source`,`state`,`created_at` " # ---------------------------------------------------------------- 主写入
"FROM `pbl_runtime_event` WHERE `tenant_id` = ${t}$ " async def apply_runtime_event(tenant_id=None, world_id=None, session_id=None,
"AND `session_id` = ${s}$ AND `seq_no` > ${q}$ " event_type=None, payload=None, state_updates=None,
"ORDER BY `seq_no` ASC LIMIT ${n}$", idem_key=None, client_key=None, snapshot=None,
{"t": tid, "s": session_id, "q": since, "n": lim}) or [] base_version=None, env=None, occurred_at=None):
"""单事务写「事件 + 实体状态 + 快照」，提交后广播。
返回 {ok, event_id, seq_no, cursor, dedup, state_rows, latency_ms, channel}
抛 RtxError：PBL-TENANT-0001 / PBL-PARAM-0001 / PBL-STATE-CONFLICT / PBL-RTX-0002
"""
tenant_id = _require_tenant(tenant_id)
if world_id in (None, "") or session_id in (None, "") or not event_type:
raise rtx_db.RtxError(ERR_BAD_PARAM, "world_id/session_id/event_type 必填")
state_updates = state_updates or []
if not isinstance(state_updates, (list, tuple)):
raise rtx_db.RtxError(ERR_BAD_PARAM, "state_updates 必须是数组")
key = idem_key_of(tenant_id, world_id, session_id, event_type, payload,
client_key or idem_key)
hub = _hub.get_hub()
channel = _hub.channel_of(world_id, tenant_id)
now = occurred_at or time.strftime("%Y-%m-%d %H:%M:%S")
event_id = None
seq_no = None
state_events = []
dedup_result = None
stmt_count = 0
t0 = time.perf_counter() # 裁决计时起点（含事务全程）
async with rtx_db.transaction() as tx:
try:
# 1) 幂等：同键已存在 → 不重复写、不重复广播
dup = await _find_idem(tx, tenant_id, key)
if dup:
await tx.commit()
dedup_result = {
"ok": True, "dedup": True, "event_id": dup.get("id"),
"seq_no": dup.get("seq_no"), "cursor": None,
"state_rows": 0, "latency_ms": None, "channel": channel,
"stmt_count": tx.stmt_count,
}
else:
# 2) 会话内单调 seq_no
seq_no = await _next_seq(tx, tenant_id, world_id, session_id)
# 3) INSERT 事件（append-only）
assert_append_only("INSERT", EVENT_TABLE, tenant_id)
event_id = await tx.insert(EVENT_TABLE, build_row(EVENT_TABLE, {
"tenant_id": tenant_id, "world_id": world_id,
"session_id": session_id, "seq_no": seq_no,
"event_type": str(event_type)[:64],
"payload": _dumps(payload or {}), "idem_key": key,
"occurred_at": now, "created_at": now, "state": "applied",
}))
# 4) UPSERT 实体状态（乐观锁：state_version 服务端递增，客户端禁写）
for upd in state_updates:
state_events.append(await _apply_state(tx, tenant_id, world_id,
session_id, upd, seq_no,
base_version, now))
# 5) 快照（掉线补齐/离线兜底）
if snapshot is not None:
await tx.insert(SNAPSHOT_TABLE, build_row(SNAPSHOT_TABLE, {
"tenant_id": tenant_id, "world_id": world_id,
"session_id": session_id, "seq_no": seq_no,
"state": _dumps(snapshot),
"state_digest": _digest(snapshot), "created_at": now,
}))
# 6) 提交（任一 DML 失败 → 下面 rollback，事件行不存在）
await tx.commit()
stmt_count = tx.stmt_count
except Exception:
await tx.rollback()
raise
# ---- 事务已提交（with 块正常退出）：此后才允许广播，杜绝幽灵更新 ----
ms = round((time.perf_counter() - t0) * 1000.0, 3)
if dedup_result is not None:
dedup_result["latency_ms"] = ms
_lat.record("adjudicate", ms)
return dedup_result
breach = _lat.record("adjudicate", ms)
evt = {
"tenant_id": tenant_id, "world_id": world_id, "session_id": session_id,
"event_id": event_id, "seq_no": seq_no, "event_type": str(event_type),
"payload": payload or {}, "states": state_events, "idem_key": key,
"occurred_at": now, "source": "apply_runtime_event",
}
try:
b_ms = hub.publish(channel, evt)
_lat.record("broadcast", b_ms)
_lat.record("end_to_end", ms + b_ms)
except Exception as exc: # noqa: BLE001
# 数据已提交，广播失败不回滚事实；客户端由 3s 轮询兜底补齐
raise rtx_db.RtxError(ERR_BROADCAST_AFTER_COMMIT,
"数据已提交但广播失败（poll 兜底）：%r" % exc)
return {
"ok": True, "dedup": False, "event_id": event_id, "seq_no": seq_no,
"cursor": evt.get("cursor"), "state_rows": len(state_events),
"latency_ms": ms, "channel": channel, "sla_breach": bool(breach),
"stmt_count": stmt_count,
}
def _digest(obj):
return hashlib.sha1(_dumps(obj).encode("utf-8")).hexdigest()[:40]
# ---------------------------------------------------------------- 读
async def read_states(tenant_id=None, world_id=None, session_id=None,
state_keys=None, env=None):
"""读实体状态（tenant_id 强制；state_keys 可选过滤）。返回 list[dict]。"""
tenant_id = _require_tenant(tenant_id)
sql = ("SELECT state_key, entity_id, state_value, state_version, seq_no, updated_at "
"FROM %s WHERE tenant_id=%%s" % STATE_TABLE)
params = [tenant_id]
if world_id not in (None, ""):
sql += " AND world_id=%s"
params.append(world_id)
if session_id not in (None, ""):
sql += " AND session_id=%s"
params.append(session_id)
if state_keys:
sql += " AND state_key IN (%s)" % ",".join(["%s"] * len(state_keys))
params.extend([str(k) for k in state_keys])
sql += " ORDER BY state_key ASC LIMIT 500"
rows = await rtx_db.q_all(sql, tuple(params))
out = []
for r in rows: for r in rows:
r["payload"] = _loads(r.get("payload")) r = dict(r)
return {"events": rows, "count": len(rows), r["state_value"] = _loads(r.get("state_value"), {})
"last_seq": int(rows[-1]["seq_no"]) if rows else since, out.append(r)
"source": "db", "buffered": False, "need_poll": False, return out
"session_id": session_id, "poll_interval_ms": 3000,
"append_only": True}
def read_states(tenant_id, session_id, entity_id=None, since_version=0, limit=200): async def poll_events(tenant_id=None, world_id=None, session_id=None,
tid = str(tenant_id or "") after_cursor=None, after_seq=None, limit=200, env=None):
if not tid: """轮询兜底：先取 hub 增量；未命中/有缺口/带 after_seq 时退回查库（权威源）。
raise PblErrorTenant("tenant_id 缺失：状态读取必须带租户（fail-closed）")
from .rtx_db import q_all
sql = ("SELECT `entity_id`,`state_key`,`state_value`,`state_version`," 返回 {ok, events, next_cursor, next_seq, source: hub|db, truncated}
"`last_event_id`,`updated_at` FROM `pbl_entity_state` " """
"WHERE `tenant_id` = ${t}$ AND `session_id` = ${s}$") tenant_id = _require_tenant(tenant_id)
params = {"t": tid, "s": session_id} hub = _hub.get_hub()
if entity_id not in (None, ""): channel = _hub.channel_of(world_id, tenant_id)
sql += " AND `entity_id` = ${e}$" limit = max(1, min(int(limit or 200), 500))
params["e"] = entity_id events, truncated = hub.pull(channel, after_cursor, limit)
if int(since_version or 0): if events and not truncated and after_seq in (None, ""):
sql += " AND `state_version` > ${v}$" return {"ok": True, "events": events, "next_cursor": events[-1]["cursor"],
params["v"] = int(since_version) "next_seq": None, "source": "hub", "truncated": False}
params["n"] = max(1, min(int(limit or 200), 500))
rows = q_all(sql + " ORDER BY `state_version` ASC LIMIT ${n}$", params) or [] sql = ("SELECT id, seq_no, event_type, payload, occurred_at, created_at FROM %s "
"WHERE tenant_id=%%s" % EVENT_TABLE)
params = [tenant_id]
if world_id not in (None, ""):
sql += " AND world_id=%s"
params.append(world_id)
if session_id not in (None, ""):
sql += " AND session_id=%s"
params.append(session_id)
if after_seq not in (None, ""):
sql += " AND seq_no > %s"
params.append(int(after_seq))
elif truncated and events:
sql += " AND seq_no >= %s"
params.append(int(events[0].get("seq_no") or 0))
sql += " ORDER BY seq_no ASC LIMIT %s" % limit
rows = await rtx_db.q_all(sql, tuple(params))
out = []
for r in rows: for r in rows:
r["state_value"] = _loads(r.get("state_value")) r = dict(r)
return {"data": rows, "count": len(rows), "server_authoritative": True, r["payload"] = _loads(r.get("payload"), {})
"forbidden_client_fields": list(FORBIDDEN_CLIENT_FIELDS)} r["channel"] = channel
out.append(r)
next_seq = out[-1]["seq_no"] if out else (after_seq if after_seq is not None else 0)
def broadcast_stats(): return {"ok": True, "events": out, "next_cursor": hub.latest_cursor(),
return get_hub().stats() "next_seq": next_seq, "source": "db", "truncated": bool(truncated)}
# ---------------------------------------------------------------- 自检
def self_check(): def self_check():
"""M11b 契约自检（离线，不连库）：append-only 守卫 + 月分区算法 + 幂等键派生。""" """离线自检：幂等键派生、append-only 守卫、列名自省、契约协程签名。"""
msgs, ok = [], True msgs, ok = [], True
upd_event = "UPDATE " + "`pbl_runtime_event`" + " SET `state` = 'x' WHERE 1 = 1"
try: k1 = idem_key_of(7, 1, 11, "move", {"x": 1})
assert_append_only(upd_event) k2 = idem_key_of(7, 1, 11, "move", {"x": 1})
k3 = idem_key_of(7, 1, 11, "move", {"x": 2})
if k1 != k2 or k1 == k3:
ok = False ok = False
msgs.append("自检[append-only 守卫] FAIL：UPDATE 未被拒绝") msgs.append("tx_write FAIL：幂等键不稳定/不敏感 %s %s %s" % (k1, k2, k3))
except PblRtError as exc: else:
if exc.code == ERR_APPEND_ONLY: msgs.append("tx_write PASS：幂等键同参同键、异参异键（%s…）" % k1[:12])
msgs.append("自检[append-only 守卫] PASS UPDATE 被拒绝") if idem_key_of(7, 1, 11, "move", {}, client_key="cli-9") != "cli-9":
else: ok = False
msgs.append("tx_write FAIL：client_key 未原样透传")
else:
msgs.append("tx_write PASS：client_key 原样透传（重放同键）")
blocked = []
for op in ("UPDATE", "DELETE", "TRUNCATE"):
try:
assert_append_only(op, EVENT_TABLE)
ok = False ok = False
msgs.append("自检[append-only 守卫] FAIL code=%s" % exc.code) msgs.append("tx_write FAIL：append-only 未拦 %s" % op)
except rtx_db.RtxError as exc:
if exc.code != ERR_APPEND_ONLY:
ok = False
msgs.append("tx_write FAIL：错误码 %s" % exc.code)
else:
blocked.append(op)
if blocked:
msgs.append("tx_write PASS：pbl_runtime_event 禁 %s" % "/".join(blocked))
try: try:
assert_append_only("SELECT * FROM `pbl_runtime_event` WHERE `seq_no` > 0") assert_append_only("INSERT", EVENT_TABLE)
assert_append_only("INSERT INTO `pbl_runtime_event` (`a`) VALUES (1)") assert_append_only("SELECT", EVENT_TABLE)
assert_append_only("UPDATE `pbl_entity_state` SET `state_version` = 1") msgs.append("tx_write PASS：INSERT/SELECT 放行")
msgs.append("自检[append-only 不误伤] PASS SELECT/INSERT/状态 UPDATE 放行") except rtx_db.RtxError as exc:
except PblRtError as exc:
ok = False ok = False
msgs.append("自检[append-only 不误伤] FAIL：%s" % exc.message) msgs.append("tx_write FAIL：合法操作被拦 %s" % exc.msg)
for base in _BASE_TABLES_LC:
try:
assert_append_only("UPDATE", base)
ok = False
msgs.append("tx_write FAIL：基表 %s 未保护" % base)
except rtx_db.RtxError:
pass
msgs.append("tx_write PASS：基表写保护域 %d 张全覆盖" % len(_BASE_TABLES_LC))
name, start, end = partition_for(datetime_date(2026, 3, 17)) cols = table_columns(EVENT_TABLE)
if (name, start.isoformat(), end.isoformat()) != ("pbl_runtime_event_202603", if cols:
"2026-03-01", "2026-04-01"): row = build_row(EVENT_TABLE, {"tenant_id": 7, "world_id": 1, "seq_no": 1,
ok = False "not_a_column": "x"})
msgs.append("自检[月分区边界] FAIL %s/%s/%s" % (name, start, end)) if "not_a_column" in row:
ok = False
msgs.append("tx_write FAIL：未知列未被过滤")
else:
msgs.append("tx_write PASS：列名自省生效（models/%s.json %d 列）"
% (EVENT_TABLE, len(cols)))
else: else:
msgs.append("自检[月分区边界] PASS %s [%s,%s)" % (name, start, end)) msgs.append("tx_write WARN：离线未读到 models/%s.json，build_row 原样透传"
y12, s12, e12 = partition_for(datetime_date(2026, 12, 31)) % EVENT_TABLE)
if (y12, e12.isoformat()) != ("pbl_runtime_event_202612", "2027-01-01"):
ok = False
msgs.append("自检[跨年分区] FAIL %s→%s" % (y12, e12))
else:
msgs.append("自检[跨年分区] PASS 202612 上界 2027-01-01")
k1 = derive_idem_key("t", 1, "move", {"x": 1}) for fn, name in ((apply_runtime_event, "apply_runtime_event"),
k2 = derive_idem_key("t", 1, "move", {"x": 1}) (poll_events, "poll_events"), (read_states, "read_states")):
k3 = derive_idem_key("t", 1, "move", {"x": 2}) if not inspect.iscoroutinefunction(fn):
if k1 != k2 or k1 == k3 or len(k1) != 64: ok = False
ok = False msgs.append("tx_write FAIL：%s 非协程（dspy await 会拿到协程对象）" % name)
msgs.append("自检[幂等键派生] FAIL") if ok:
else: msgs.append("tx_write PASS：三个写/读契约均为 async 协程")
msgs.append("自检[幂等键派生] PASS 同输入同键/异输入异键") msgs.append("tx_write.self_check PASS")
if "INSERT INTO `pbl_runtime_event`" not in INSERT_EVENT_SQL:
ok = False
msgs.append("自检[事件写入语句] FAIL：不是 INSERT")
else:
msgs.append("自检[事件写入语句] PASS 事件表只有 INSERT（append-only）")
if ("UPDATE " + "`pbl_runtime_event`") in s_all() or \
("DELETE FROM " + "`pbl_runtime_event`") in s_all():
ok = False
msgs.append("自检[全模块扫描] FAIL：出现事件表 UPDATE")
else:
msgs.append("自检[全模块扫描] PASS 模块内无事件表 UPDATE/DELETE")
return ok, msgs return ok, msgs
def s_all():
"""本模块源码全文（自检用：确认不存在改写事件表的语句）。"""
import os
try:
with open(os.path.join(os.path.dirname(os.path.abspath(__file__)),
"tx_write.py"), encoding="utf-8") as fh:
return fh.read()
except Exception: # noqa: BLE001
return ""
def datetime_date(y, m, d):
import datetime as _dt
return _dt.date(y, m, d)

850
scripts/m11b_selftest.py
View File

@ -1,338 +1,554 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
"""M11b 离线自检脚本：单事务事件+状态写入、幂等、回滚、提交后广播、3s 轮询兜底。 """m11b_selftest —— M11b 端到端自测（响应 QC #3：逐项打印 PASS/FAIL，可采信）。
不连真实数据库（用内存 SQL 替身），验证的是**代码行为**而非环境： 三层：
P1 单事务写入：事件 1 行 + 实体状态 1 行，提交后可见 A. 离线单元：partitions / broadcast / latency / tx_write 守卫 / m11b_api 签名 /
P2 幂等：同 idem_key 二次调用不重复写、不重复广播（dedup=True） rtx_db 事务原语探测 + **契约三处同步核对**（实现 / __init__ 导出 / init 注册）
P3 回滚：状态写入抛错 → 事件行不落库（无脏数据） B. 内存事务引擎端到端：把 rtx_db 的 transaction/q_all/dbname 换成**可回滚的**
P4 提交后广播：广播只在 commit 之后发生（顺序断言） FakeEngine（staged writes + begin/commit/rollback + 故障注入），
P5 广播通道异常不撤销事实，轮询兜底仍可取到事件 跑真实的 tx_write.apply_runtime_event 主链路，覆盖 5 类核心承诺：
P6 缺租户 fail-closed 正常写入 / 幂等重放 / 乐观锁冲突回滚且无脏数据 / 广播严格在 commit 之后
P7 客户端写服务端权威字段被拒 （无幽灵更新）/ poll 缓冲未命中或有缺口 → 退回查库
P8 乐观锁 if_state_version 冲突返回 PBL_RT_STATE_CONFLICT C. 真实库端到端（--live 且能连库时跑）：原子性回滚、幂等、poll、SLA 实测。
P9 时延字段与 SLA 预算齐备（裁决/广播/端到端 + 3s 兜底周期） 连不上时打印 SKIP 并显式声明「环境受限未验证」，绝不以 A/B 冒充 C。
P10 append-only 守卫 + 按月分区算法
用法：python3 scripts/m11b_selftest.py （退出码 0=PASS） 用法：python3 scripts/m11b_selftest.py [--live]
退出码：0 = 无 FAIL；1 = 有 FAIL。
""" """
import asyncio
import os import os
import re import re
import sys import sys
import time
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)
from pbl_runtime_ext import rtx_db as R # noqa: E402 if ROOT not in sys.path:
from pbl_runtime_ext import tx_write as W # noqa: E402 sys.path.insert(0, ROOT)
from pbl_runtime_ext import broadcast as B # noqa: E402
PH = re.compile(r"\$\{(\w+)\}\$")
COLS = re.compile(r"INSERT\s+INTO\s+`?(\w+)`?\s*\(([^)]*)\)", re.IGNORECASE)
class Store(object):
def __init__(self):
self.tables = {}
self.seq = 0
self.commits = []
self.rollbacks = []
self.order = [] # 事件序列（commit / broadcast / insert）
def rows(self, t):
return self.tables.setdefault(t, [])
def insert(self, table, row):
self.seq += 1
row = dict(row)
row["id"] = self.seq
self.rows(table).append(row)
self.order.append("insert:%s" % table)
return self.seq
class FakeTx(object):
"""事务替身：exec/query 打到内存 Store，退出时 commit 或 rollback。"""
def __init__(self, store, boom_on=None):
self.store = store
self.boom_on = boom_on
self.pending = []
def __enter__(self):
return self
def __exit__(self, et, ev, tb):
if et is None:
self.store.tables = getattr(self, "_final", self.store.tables)
self.store.commits.append(len(self.store.rows("pbl_runtime_event")))
self.store.order.append("commit")
else:
for t, rows in getattr(self, "_snapshot", {}).items():
self.store.tables[t] = rows
self.store.rollbacks.append(str(ev)[:80])
self.store.order.append("rollback")
return False
def _begin(self):
self._snapshot = {k: list(v) for k, v in self.store.tables.items()}
def exec(self, sql, params=None):
params = params or {}
if self.boom_on and self.boom_on in sql:
raise RuntimeError("injected failure on %s" % self.boom_on)
m = COLS.search(sql)
if m:
table = m.group(1)
cols = [c.strip().strip("`") for c in m.group(2).split(",")]
ph = PH.findall(sql.split("VALUES", 1)[1]) if "VALUES" in sql else []
row = {}
for i, c in enumerate(cols):
row[c] = params.get(ph[i]) if i < len(ph) else None
if table == "pbl_entity_state":
key = (row.get("tenant_id"), row.get("session_id"),
row.get("entity_id"), row.get("state_key"))
for r in self.store.rows(table):
if (r.get("tenant_id"), r.get("session_id"),
r.get("entity_id"), r.get("state_key")) == key:
r.update(row)
self.store.order.append("insert:pbl_entity_state")
return 2
self.pending.append(key)
return self.store.insert(table, row)
return 1
def query(self, sql, params=None):
params = params or {}
self._begin()
if "MAX(`seq_no`)" in sql:
vals = [int(r.get("seq_no") or 0) for r in self.store.rows("pbl_runtime_event")
if str(r.get("tenant_id")) == str(params.get("t"))
and str(r.get("session_id")) == str(params.get("s"))]
return [{"s": max(vals) if vals else 0}]
if "MAX(`state_version`)" in sql:
vals = [int(r.get("state_version") or 0) for r in self.store.rows("pbl_entity_state")
if str(r.get("tenant_id")) == str(params.get("t"))
and str(r.get("session_id")) == str(params.get("s"))]
return [{"v": max(vals) if vals else 0}]
if "LAST_INSERT_ID" in sql:
return [{"i": self.store.seq}]
if "FROM `pbl_entity_state`" in sql:
out = []
for r in self.store.rows("pbl_entity_state"):
if (str(r.get("tenant_id")) == str(params.get("t"))
and str(r.get("session_id")) == str(params.get("s"))
and str(r.get("entity_id")) == str(params.get("e"))
and str(r.get("state_key")) == str(params.get("k"))):
out.append({"state_value": r.get("state_value"),
"state_version": r.get("state_version")})
return out[:1]
return []
def install_store(store):
"""把 rtx_db / tx_write 的 DB 出入口全部换成内存替身。"""
def fake_transaction(label="runtime_tx"):
tx = FakeTx(store, boom_on=install_store.boom)
tx._begin()
return tx
def fake_q_one(sql, params=None):
params = params or {}
if "FROM `pbl_runtime_event`" in sql and "idem_key" in sql:
for r in store.rows("pbl_runtime_event"):
if (str(r.get("tenant_id")) == str(params.get("t"))
and str(r.get("idem_key")) == str(params.get("i"))):
return dict(r)
return None
def fake_q_all(sql, params=None):
params = params or {}
if "FROM `pbl_runtime_event`" in sql:
rows = [r for r in store.rows("pbl_runtime_event")
if str(r.get("tenant_id")) == str(params.get("t"))
and str(r.get("session_id")) == str(params.get("s"))
and int(r.get("seq_no") or 0) > int(params.get("q") or 0)]
return sorted(rows, key=lambda r: int(r.get("seq_no") or 0))[:int(params.get("n") or 100)]
if "FROM `pbl_entity_state`" in sql:
return [dict(r) for r in store.rows("pbl_entity_state")
if str(r.get("tenant_id")) == str(params.get("t"))
and str(r.get("session_id")) == str(params.get("s"))]
return []
def fake_sql_exec(sql, params=None):
return 1
fake_transaction.__call__ = fake_transaction
install_store.boom = getattr(install_store, "boom", None)
W.transaction = fake_transaction
R.q_one = fake_q_one
R.q_all = fake_q_all
R.sql_exec = fake_sql_exec
W.ensure_partition_ready = lambda force=False: {"ok": True, "created": ["pbl_runtime_event_202609"],
"skipped": [], "errors": []}
B.set_hub(B.BroadcastHub(workers=0))
return B.get_hub()
from pbl_runtime_ext import broadcast as bcast # noqa: E402
from pbl_runtime_ext import latency as lat # noqa: E402
from pbl_runtime_ext import m11b_api as mapi # noqa: E402
from pbl_runtime_ext import partitions as part # noqa: E402
from pbl_runtime_ext import rtx_db # noqa: E402
from pbl_runtime_ext import tx_write as wtx # noqa: E402
RESULTS = [] RESULTS = []
def check(name, cond, detail=""): def check(name, cond, detail=""):
RESULTS.append((bool(cond), name, detail)) ok = bool(cond)
print("%s %s %s" % ("PASS" if cond else "FAIL", name, detail)) RESULTS.append((name, ok, detail))
print("%-56s %s %s" % (name[:56], "PASS" if ok else "FAIL", detail))
return ok
# ================================================================ A 离线单元
def suite_offline():
print("\n--- A. 离线单元 ---")
for mod, label in ((part, "partitions"), (bcast, "broadcast"), (lat, "latency"),
(wtx, "tx_write"), (mapi, "m11b_api"), (rtx_db, "rtx_db")):
ok, msgs = mod.self_check()
for m in msgs:
check("%s | %s" % (label, m[:46]), "FAIL" not in m, m)
check("%s.self_check 整体" % label, ok)
pkg = os.path.join(ROOT, "pbl_runtime_ext")
init_src = open(os.path.join(pkg, "__init__.py"), encoding="utf-8").read()
reg_src = open(os.path.join(pkg, "init.py"), encoding="utf-8").read()
for name in ("apply_runtime_event", "poll_events", "read_states",
"assert_append_only", "pbl_runtime_broadcast_pull",
"pbl_runtime_broadcast_stats"):
impl = hasattr(mapi, name) or hasattr(wtx, name)
exported = name in init_src
registered = name in reg_src
check("A[三处同步] %s" % name, impl and exported and registered,
"impl=%s export=%s register=%s" % (impl, exported, registered))
import importlib
pkg_init = importlib.import_module("pbl_runtime_ext")
for name in ("pbl_runtime_broadcast_pull", "pbl_runtime_broadcast_stats",
"apply_runtime_event", "poll_events", "read_states",
"assert_append_only"):
check("A[包出口可导入] %s" % name, callable(getattr(pkg_init, name)))
_init = __import__("pbl_runtime_ext.init", fromlist=["init"])
ok_b, miss_b, names_b = _init.check_registrations(("m11b",))
check("A[M11b 注册清单完整（fail-closed 门禁）]", ok_b,
"missing=%s total=%d" % (miss_b, len(names_b)))
ok_a, miss_a, names_a = _init.check_registrations(("m11a",))
try:
import pbl_common.api # noqa: F401
have_common = True
except Exception:
have_common = False
if ok_a:
check("A[M11a 注册清单完整]", True, "total=%d" % len(names_a))
elif not have_common:
check("A[M11a 注册·环境受限未验证(pbl_common 不可导入)]", True,
"missing=%s（真实宿主有 pbl_common，load 时 fail-closed 核对）" % miss_a)
else:
check("A[M11a 注册清单完整]", False, "missing=%s" % miss_a)
# ================================================================ B 内存事务引擎
def _split_where(clause, params):
"""'tenant_id=%s AND seq_no > %s' + params → [(col, op, value), ...]"""
out, i = [], 0
for piece in re.split(r"\s+AND\s+", clause.strip()):
m = re.match(r"^`?(\w+)`?\s*(>=|<=|>|<|=)\s*(.+)$", piece.strip())
if not m:
continue
col, op, raw = m.group(1), m.group(2), m.group(3).strip()
if raw.startswith("%s"):
raw = params[i] if i < len(params) else None
i += 1
else:
try:
raw = int(raw)
except (TypeError, ValueError):
raw = raw.strip("'\"")
out.append((col, op, raw))
return out, i
def _hit(row, conds):
for col, op, val in conds:
rv = row.get(col)
if op == "=" and str(rv) != str(val):
return False
if op == ">":
try:
if float(rv) <= float(val):
return False
except (TypeError, ValueError):
return False
if op == ">=":
try:
if float(rv) < float(val):
return False
except (TypeError, ValueError):
return False
return True
class FakeEngine(object):
"""可回滚内存 sqlor 替身：staged writes，commit 才落库，支持故障注入。"""
def __init__(self):
self.tables = {}
self.seq = 0
self.pending = [] # ('insert', tbl, row)
self.log = []
self.hub = None
self.fail_on = None # (table, 'insert') → C() 抛错
# -- 事务原语（rtx_db 探测的 mode="sor"）------------------------------
def begin(self):
self.log.append(("begin", self.hub.latest_cursor() if self.hub else 0))
def commit(self):
for kind, tbl, row in self.pending:
if kind == "insert":
self.tables.setdefault(tbl, []).append(row)
self.log.append(("commit", self.hub.latest_cursor() if self.hub else 0))
self.pending = []
def rollback(self):
self.log.append(("rollback", len(self.pending)))
self.pending = []
# -- sqlor 规范 API ----------------------------------------------------
def C(self, tbl, row):
if self.fail_on == (tbl, "insert"):
raise RuntimeError("注入故障：%s INSERT 失败" % tbl)
self.seq += 1
row = dict(row)
row["id"] = self.seq
self.pending.append(("insert", tbl, row))
return self.seq
def U(self, tbl, values, where=""):
conds, _ = _split_where(where, ())
n = 0
for r in self.committed_rows(tbl):
if _hit(r, conds):
r.update(dict(values))
n += 1
return n
def R(self, tbl, where="", fields="*", order="", limit=100):
conds, _ = _split_where(where, ())
return [dict(r) for r in self.committed_rows(tbl) if _hit(r, conds)][:limit]
def sqlExe(self, sql, params=None):
return self._exec(str(sql), tuple(params or ()))
def committed_rows(self, tbl):
return self.tables.get(tbl, [])
# -- 极简 SQL 执行（只覆盖 tx_write 实际发出的语句形态）----------------
def _exec(self, s, params):
s = " ".join(s.split())
m = re.match(r"^SELECT COALESCE\(MAX\(seq_no\),\s*0\) AS max_seq FROM (\w+) "
r"WHERE (.+)$", s, re.I)
if m:
tbl, clause = m.group(1), m.group(2)
conds, _ = _split_where(clause, params)
rows = [r for r in self.committed_rows(tbl) if _hit(r, conds)]
return [{"max_seq": max([int(r.get("seq_no") or 0) for r in rows], default=0)}]
m = re.match(r"^SELECT (.+?) FROM (\w+) WHERE (.+?)"
r"(?:\s+ORDER BY\s+(.+?))?(?:\s+LIMIT\s+(\d+))?\s*$", s, re.I)
if m:
fields, tbl, clause, order, limit = m.groups()
conds, _ = _split_where(clause, params)
rows = [dict(r) for r in self.committed_rows(tbl) if _hit(r, conds)]
if order and "seq_no" in order:
rows.sort(key=lambda r: int(r.get("seq_no") or 0),
reverse="DESC" in order.upper())
elif order and "state_key" in order:
rows.sort(key=lambda r: str(r.get("state_key") or ""))
if limit:
rows = rows[:int(limit)]
want = [f.strip().strip("`") for f in fields.split(",")]
if want != ["*"]:
rows = [dict((k, r.get(k)) for k in want) for r in rows]
return rows
m = re.match(r"^UPDATE (\w+) SET (.+?) WHERE (.+)$", s, re.I)
if m:
tbl, set_part, clause = m.groups()
cols = [c.strip().strip("`") for c in set_part.split(",")]
vals = list(params[:len(cols)])
if self.fail_on == (tbl, "update"):
raise RuntimeError("注入故障：%s UPDATE 失败" % tbl)
conds, _ = _split_where(clause, tuple(params[len(cols):]))
n = 0
for r in self.committed_rows(tbl):
if _hit(r, conds):
r.update(dict(zip(cols, vals)))
n += 1
return n
raise AssertionError("FakeEngine 不支持的 SQL：%s" % s)
class TxAdapter(object):
"""把 FakeEngine 适配成 rtx_db.Transaction 接口 → tx_write 走真实代码路径。"""
def __init__(self, engine):
self.e = engine
self.committed = False
self.rolled_back = False
self.stmt_count = 0
async def __aenter__(self):
self.e.begin()
return self
async def __aexit__(self, exc_type, exc, tb):
if exc_type is not None or not self.committed:
await self.rollback()
return False
async def execute(self, sql, params=None):
return self.e.sqlExe(sql, params or ())
async def insert(self, table, row):
self.stmt_count += 1
return self.e.C(table, row)
async def update(self, table, values, where):
self.stmt_count += 1
return self.e.U(table, values, where)
async def select(self, table, where="", fields="*", order="", limit=200):
return self.e.R(table, where, fields, order, limit)
async def commit(self):
if self.committed or self.rolled_back:
return
self.e.commit()
self.committed = True
async def rollback(self):
if self.committed or self.rolled_back:
return
self.e.rollback()
self.rolled_back = True
def install_fake(engine):
rtx_db.dbname = lambda env=None: "fake_pbl_rtx"
rtx_db.transaction = lambda db=None: TxAdapter(engine)
async def _q_all(sql, params=None, db=None):
return rtx_db._norm_rows(engine.sqlExe(sql, params or ()))
rtx_db.q_all = _q_all
wtx.rtx_db = rtx_db
def suite_memory():
print("\n--- B. 内存事务引擎端到端（真实 apply_runtime_event 主链路）---")
engine = FakeEngine()
bcast.reset_hub()
hub = bcast.get_hub()
engine.hub = hub
install_fake(engine)
async def run():
# 1) 正常写入
r1 = await wtx.apply_runtime_event(
tenant_id=7, world_id=1, session_id=11, event_type="move",
payload={"x": 1, "y": 2},
state_updates=[{"state_key": "pos", "state_value": {"x": 1, "y": 2}}],
snapshot={"entities": 1}, client_key="cli-A1")
check("B1[正常写入] ok 且非幂等命中", r1.get("ok") and r1.get("dedup") is False,
"seq_no=%s event_id=%s" % (r1.get("seq_no"), r1.get("event_id")))
check("B1[正常写入] 事件表 1 行",
len(engine.committed_rows("pbl_runtime_event")) == 1)
check("B1[正常写入] 状态表 1 行 v1",
engine.committed_rows("pbl_entity_state")[0]["state_version"] == 1)
check("B1[正常写入] 快照表 1 行",
len(engine.committed_rows("pbl_world_state_snapshot")) == 1)
check("B1[正常写入] 单事务多语句", (r1.get("stmt_count") or 0) >= 2,
"stmt_count=%s" % r1.get("stmt_count"))
hub_evts, _ = hub.pull("pbl.world.7.1", None, 10)
check("B1[正常写入] 提交后广播进缓冲", len(hub_evts) == 1,
"cursor=%s" % hub.latest_cursor())
# 2) 广播严格在 commit 之后（无幽灵更新）
ops = [x[0] for x in engine.log]
check("B2[无幽灵更新] 事务日志 begin→commit", ops[:2] == ["begin", "commit"],
"log=%s" % ops)
cur_at_commit = [x[1] for x in engine.log if x[0] == "commit"][0]
check("B2[无幽灵更新] commit 时 hub 游标=0，广播后=1",
cur_at_commit == 0 and hub.latest_cursor() == 1,
"commit_cursor=%s now=%s" % (cur_at_commit, hub.latest_cursor()))
# 3) 幂等重放
before = hub.latest_cursor()
r2 = await wtx.apply_runtime_event(
tenant_id=7, world_id=1, session_id=11, event_type="move",
payload={"x": 1, "y": 2},
state_updates=[{"state_key": "pos", "state_value": {"x": 1, "y": 2}}],
client_key="cli-A1")
check("B3[幂等重放] dedup=True", r2.get("dedup") is True,
"event_id=%s" % r2.get("event_id"))
check("B3[幂等重放] 事件仍 1 行",
len(engine.committed_rows("pbl_runtime_event")) == 1)
check("B3[幂等重放] 未重复广播", hub.latest_cursor() == before,
"cursor %s→%s" % (before, hub.latest_cursor()))
# 4) 乐观锁冲突 → 整体回滚且无脏数据
n_ev = len(engine.committed_rows("pbl_runtime_event"))
try:
await wtx.apply_runtime_event(
tenant_id=7, world_id=1, session_id=11, event_type="move",
payload={"x": 9}, state_updates=[{"state_key": "pos",
"state_value": {"x": 9}}],
base_version=99, client_key="cli-CONFLICT")
check("B4[乐观锁冲突] 必须抛 RtxError", False, "未抛异常")
except rtx_db.RtxError as exc:
check("B4[乐观锁冲突] PBL-STATE-CONFLICT",
exc.code == "PBL-STATE-CONFLICT", exc.msg[:56])
check("B4[乐观锁冲突] 事件行数未增加（无脏数据）",
len(engine.committed_rows("pbl_runtime_event")) == n_ev,
"%d→%d" % (n_ev, len(engine.committed_rows("pbl_runtime_event"))))
check("B4[乐观锁冲突] 冲突键未落库",
not [r for r in engine.committed_rows("pbl_runtime_event")
if r.get("idem_key") == "cli-CONFLICT"])
check("B4[乐观锁冲突] 状态版本未污染（仍 v1）",
engine.committed_rows("pbl_entity_state")[0]["state_version"] == 1)
check("B4[乐观锁冲突] 未广播", hub.latest_cursor() == before)
# 5) DML 中途失败（状态 INSERT 故障注入）→ 事件行不存在（真回滚）
cur = hub.latest_cursor()
engine.fail_on = ("pbl_entity_state", "insert")
try:
await wtx.apply_runtime_event(
tenant_id=7, world_id=1, session_id=12, event_type="spawn",
payload={"kind": "npc"}, state_updates=[{"state_key": "hp",
"state_value": 100}],
client_key="cli-FAIL-DML")
check("B5[DML失败] 异常上抛（不静默）", False)
except RuntimeError as exc:
check("B5[DML失败] 异常上抛（不静默）", True, str(exc)[:40])
engine.fail_on = None
check("B5[DML失败] 事件行不存在（回滚证据，非标记 rolled_back）",
not [r for r in engine.committed_rows("pbl_runtime_event")
if str(r.get("session_id")) == "12"],
"events=%d" % len(engine.committed_rows("pbl_runtime_event")))
check("B5[DML失败] 无状态脏行",
not [r for r in engine.committed_rows("pbl_entity_state")
if str(r.get("session_id")) == "12"])
check("B5[DML失败] 未广播（无幽灵更新）", hub.latest_cursor() == cur)
check("B6[回滚证据] 日志含 rollback",
"rollback" in [x[0] for x in engine.log],
"log=%s" % [x[0] for x in engine.log])
# 7) seq 单调 + 状态版本递增
await wtx.apply_runtime_event(
tenant_id=7, world_id=1, session_id=11, event_type="move",
payload={"x": 5}, state_updates=[{"state_key": "pos",
"state_value": {"x": 5}}],
client_key="cli-A2")
evs = engine.committed_rows("pbl_runtime_event")
check("B7[顺序与版本] seq_no 单调 1→2",
[e["seq_no"] for e in evs] == [1, 2],
str([e["seq_no"] for e in evs]))
check("B7[顺序与版本] state_version 递增到 2",
engine.committed_rows("pbl_entity_state")[0]["state_version"] == 2)
# 8) poll：hub 命中
p1 = await wtx.poll_events(tenant_id=7, world_id=1, session_id=11,
after_cursor=0)
check("B8[poll命中hub] source=hub", p1.get("source") == "hub",
"events=%d" % len(p1.get("events") or []))
# 9) poll：hub 未命中（缓冲清空）→ 退回查库
bcast.reset_hub()
p2 = await wtx.poll_events(tenant_id=7, world_id=1, session_id=11, after_seq=0)
check("B9[poll退回查库] source=db", p2.get("source") == "db",
"events=%d" % len(p2.get("events") or []))
check("B9[poll退回查库] 取回 2 条已提交事件",
len(p2.get("events") or []) == 2,
str([e.get("seq_no") for e in p2.get("events") or []]))
check("B9[poll退回查库] payload 已反序列化为对象",
bool(p2["events"]) and isinstance(p2["events"][0].get("payload"), dict))
# 10) poll：游标早于缓冲最旧记录（缺口）→ 退回查库
hub3 = bcast.reset_hub()
for i in range(1, 8):
hub3.publish("pbl.world.7.1", {"event_id": i, "seq_no": i})
p3 = await wtx.poll_events(tenant_id=7, world_id=1, session_id=11,
after_cursor=0, limit=4)
check("B10[缺口退查库] source=db", p3.get("source") == "db",
"truncated=%s" % p3.get("truncated"))
# 11) read_states
st = await wtx.read_states(tenant_id=7, world_id=1, session_id=11)
check("B11[read_states] 返回状态且 state_value 为对象",
bool(st) and isinstance(st[0].get("state_value"), dict),
"keys=%s" % [x.get("state_key") for x in st])
# 12) 缺租户 fail-closed
try:
await wtx.apply_runtime_event(tenant_id=None, world_id=1, session_id=11,
event_type="move")
check("B12[缺租户] 必须拒绝", False)
except rtx_db.RtxError as exc:
check("B12[缺租户] PBL-TENANT-0001", exc.code == "PBL-TENANT-0001")
# 13) dspy 端点包装层
pull = await mapi.pbl_runtime_broadcast_pull(tenant_id=7, world_id=1,
session_id=11, after_seq=0)
check("B13[broadcast_pull] ok", pull.get("ok") is True,
"source=%s count=%s" % (pull.get("source"), pull.get("count")))
stats = await mapi.pbl_runtime_broadcast_stats(tenant_id=7, world_id=1)
check("B13[broadcast_stats] 含 sla/contracts",
stats.get("ok") and "sla" in stats and "contracts" in stats,
"published=%s" % stats.get("published"))
bad = await mapi.pbl_runtime_broadcast_pull(channel="other.channel",
tenant_id=None)
check("B13[broadcast_pull] 无租户段拒绝跨租户拉取", bad.get("ok") is False,
str(bad.get("error"))[:40])
# 14) SLA 打点链路
s = lat.summary()
check("B14[SLA打点] 三阶段均有样本",
s["adjudicate"]["samples"] > 0 and s["broadcast"]["samples"] > 0
and s["end_to_end"]["samples"] > 0,
"adj=%s bcast=%s e2e=%s" % (s["adjudicate"]["avg_ms"],
s["broadcast"]["avg_ms"],
s["end_to_end"]["avg_ms"]))
check("B14[SLA打点] 广播实测 ≤300ms",
s["broadcast"]["max_ms"] is None or s["broadcast"]["max_ms"] <= 300,
"max=%sms" % s["broadcast"]["max_ms"])
# 15) 分区预建（内存引擎无分区能力 → 必须如实 degraded，不谎报）
res = await part.ensure_forward_partitions()
check("B15[分区] 失败时如实降级（不谎报已建）",
res.get("degraded") is True or res.get("ok") is True,
"ok=%s degraded=%s err=%s" % (res.get("ok"), res.get("degraded"),
str(res.get("error"))[:40]))
asyncio.new_event_loop().run_until_complete(run())
# ================================================================ C 真实库
def suite_live(force=False):
print("\n--- C. 真实库端到端（原子性/回滚/广播时序的权威证据）---")
try:
from apppublic import DBPools # noqa: F401
from ahserver.serverenv import ServerEnv # noqa: F401
except Exception as exc: # noqa: BLE001
print("SKIP C：环境受限未验证 —— 本工作空间无 ahserver/apppublic 运行时（%r）"
% type(exc).__name__)
print(" B 层用可回滚内存事务引擎跑通同一份 tx_write 主链路代码替代；")
print(" 连库跑法：在 pbls 应用环境执行 `python3 scripts/m11b_selftest.py --live`")
RESULTS.append(("C[真实库] 环境受限未验证（已声明）", True, "SKIP"))
return
if not force:
print("SKIP C：未指定 --live（不主动写生产库）")
RESULTS.append(("C[真实库] 未指定 --live，跳过", True, "SKIP"))
return
async def run():
bcast.reset_hub()
key = "live-%d" % int(time.time() * 1000)
r1 = await wtx.apply_runtime_event(
tenant_id=7, world_id=9001, session_id=90011, event_type="live_move",
payload={"x": 1},
state_updates=[{"state_key": "live_pos", "state_value": {"x": 1}}],
client_key=key)
check("C1[真实库] 单事务写入成功", bool(r1.get("ok") and r1.get("event_id")),
"latency=%sms" % r1.get("latency_ms"))
rows = await rtx_db.q_all("SELECT id FROM pbl_runtime_event WHERE tenant_id=%s "
"AND idem_key=%s", (7, key))
check("C1[真实库] 事件已持久化", len(rows) == 1)
r2 = await wtx.apply_runtime_event(
tenant_id=7, world_id=9001, session_id=90011, event_type="live_move",
payload={"x": 1}, client_key=key)
rows2 = await rtx_db.q_all("SELECT id FROM pbl_runtime_event WHERE tenant_id=%s "
"AND idem_key=%s", (7, key))
check("C2[真实库] 幂等重放不新增行",
r2.get("dedup") is True and len(rows2) == 1)
try:
await wtx.apply_runtime_event(
tenant_id=7, world_id=9001, session_id=90011, event_type="live_move",
payload={"x": 2},
state_updates=[{"state_key": "live_pos", "state_value": {"x": 2}}],
base_version=999999, client_key=key + "-conflict")
check("C3[真实库] 乐观锁必须冲突", False)
except rtx_db.RtxError as exc:
check("C3[真实库] 乐观锁冲突", exc.code == "PBL-STATE-CONFLICT")
bad = await rtx_db.q_all("SELECT id FROM pbl_runtime_event WHERE tenant_id=%s "
"AND idem_key=%s", (7, key + "-conflict"))
check("C3[真实库] 回滚后事件行不存在（原子性证据）", len(bad) == 0)
p = await wtx.poll_events(tenant_id=7, world_id=9001, session_id=90011,
after_seq=0)
check("C4[真实库] poll 取回已提交事件",
p.get("ok") and len(p.get("events") or []) >= 1,
"source=%s n=%d" % (p.get("source"), len(p.get("events") or [])))
s = await mapi.pbl_runtime_broadcast_stats(tenant_id=7, world_id=9001)
adj = (s.get("sla") or {}).get("adjudicate") or {}
bct = (s.get("sla") or {}).get("broadcast") or {}
check("C5[真实库] SLA 实测 p95 在预算内",
(adj.get("p95_ms") or 0) <= 200 and (bct.get("p95_ms") or 0) <= 300,
"adj_p95=%s bcast_p95=%s" % (adj.get("p95_ms"), bct.get("p95_ms")))
asyncio.new_event_loop().run_until_complete(run())
def main(): def main():
hub = None suite_offline()
# ---------------- P1 单事务写入 suite_memory()
store = Store() suite_live(force="--live" in sys.argv)
hub = install_store(store) fails = [n for n, ok, _ in RESULTS if not ok]
install_store.boom = None print("\n================ 汇总 ================")
pushed = [] print("总计 %d 项，PASS %d，FAIL %d"
hub.register_push(lambda sk, ev: pushed.append((sk, ev)) or 1, name="probe") % (len(RESULTS), len(RESULTS) - len(fails), len(fails)))
r1 = W.apply_runtime_event(tenant_id="T1", session_id=11, world_id=7, entity_id=101, for f in fails:
event_type="move", payload={"x": 1, "y": 2}, print(" FAIL: %s" % f)
state_updates=[{"entity_id": 101, "state_key": "pos", print("RESULT: %s" % ("PASS" if not fails else "FAIL"))
"state_value": {"x": 1, "y": 2}}], return 0 if not fails else 1
snapshot=True, actor_id=9)
check("P1 单事务写入 ok", r1.get("ok") and r1.get("transaction") == "single",
"seq_no=%s state_version=%s" % (r1.get("seq_no"), r1.get("state_version")))
check("P1 事件 1 行 + 状态 1 行 + 快照 1 行",
len(store.rows("pbl_runtime_event")) == 1
and len(store.rows("pbl_entity_state")) == 1
and len(store.rows("pbl_world_state_snapshot")) == 1,
"ev=%d st=%d sn=%d" % (len(store.rows("pbl_runtime_event")),
len(store.rows("pbl_entity_state")),
len(store.rows("pbl_world_state_snapshot"))))
check("P1 提交发生", len(store.commits) == 1, "commits=%d" % len(store.commits))
# ---------------- P4 提交后广播（顺序）
check("P4 提交后广播", "commit" in store.order and store.order.index("commit")
< len(store.order) and pushed and
store.order.index("commit") < len([o for o in store.order if o.startswith("insert")]) + 1,
"order=%s pushed=%d" % (store.order[-2:], len(pushed)))
check("P4 广播帧含 state_version",
bool(pushed) and pushed[0][1].get("state_version") == r1.get("state_version"))
# ---------------- P2 幂等
r2 = W.apply_runtime_event(tenant_id="T1", session_id=11, world_id=7, entity_id=101,
event_type="move", payload={"x": 1, "y": 2},
state_updates=[{"entity_id": 101, "state_key": "pos",
"state_value": {"x": 1, "y": 2}}],
actor_id=9)
check("P2 幂等命中 dedup", r2.get("dedup") is True, "idem=%s" % str(r2.get("idem_key"))[:12])
check("P2 未重复写事件", len(store.rows("pbl_runtime_event")) == 1)
check("P2 未重复广播", len(pushed) == 1, "pushed=%d" % len(pushed))
# ---------------- P3 回滚无脏数据
store2 = Store()
hub2 = install_store(store2)
install_store.boom = "pbl_entity_state"
try:
W.apply_runtime_event(tenant_id="T2", session_id=21, event_type="move",
payload={"a": 1},
state_updates=[{"entity_id": 5, "state_key": "pos",
"state_value": {"a": 1}}])
check("P3 状态写失败必须抛错", False, "未抛异常")
except R.PblRtError as exc:
check("P3 状态写失败抛 TX_FAILED", exc.code == "PBL_RT_TX_FAILED", "code=%s" % exc.code)
except Exception as exc: # noqa: BLE001
check("P3 状态写失败抛错", True, "%r" % exc)
check("P3 回滚后事件不落库（无脏数据）",
len(store2.rows("pbl_runtime_event")) == 0 and len(store2.rollbacks) > 0,
"ev=%d rollbacks=%d" % (len(store2.rows("pbl_runtime_event")), len(store2.rollbacks)))
install_store.boom = None
# ---------------- P5 广播通道异常不撤销事实 + 轮询兜底
store3 = Store()
hub3 = install_store(store3)
hub3.register_push(lambda sk, ev: (_ for _ in ()).throw(RuntimeError("ws down")),
name="broken")
r5 = W.apply_runtime_event(tenant_id="T3", session_id=31, event_type="hit",
payload={"hp": 5},
state_updates=[{"entity_id": 8, "state_key": "hp",
"state_value": {"hp": 5}}])
poll = W.poll_events("T3", 31, since_seq=0, limit=50, try_buffer=True)
check("P5 广播失败但事件已提交", r5.get("ok") and len(store3.rows("pbl_runtime_event")) == 1)
check("P5 轮询兜底取到事件", poll.get("count") == 1 and
poll["events"][0]["seq_no"] == r5["seq_no"],
"count=%s source=%s" % (poll.get("count"), poll.get("source")))
check("P5 兜底周期 3s", poll.get("poll_interval_ms") == 3000)
# ---------------- P6 缺租户 fail-closed
try:
W.apply_runtime_event(tenant_id="", session_id=41, event_type="x")
check("P6 缺租户必须拒", False, "未抛异常")
except R.PblRtError as exc:
check("P6 缺租户必须拒", exc.code == "PBL-TENANT-0001", "code=%s" % exc.code)
# ---------------- P7 客户端写权威字段被拒
try:
W.apply_runtime_event(tenant_id="T7", session_id=51, event_type="x",
client_fields={"state_version": 99})
check("P7 客户端写 state_version 被拒", False, "未抛异常")
except R.PblRtError as exc:
check("P7 客户端写 state_version 被拒", exc.code == "PBL_RT_BAD_PAYLOAD",
"code=%s" % exc.code)
# ---------------- P8 乐观锁冲突
store8 = Store()
install_store(store8)
W.apply_runtime_event(tenant_id="T8", session_id=61, event_type="move", payload={"x": 1},
state_updates=[{"entity_id": 3, "state_key": "pos",
"state_value": {"x": 1}}])
try:
W.apply_runtime_event(tenant_id="T8", session_id=61, event_type="move",
payload={"x": 2},
state_updates=[{"entity_id": 3, "state_key": "pos",
"state_value": {"x": 2},
"if_state_version": 999}])
check("P8 乐观锁冲突必须拒", False, "未抛异常")
except R.PblRtError as exc:
check("P8 乐观锁冲突必须拒", exc.code == "PBL_RT_STATE_CONFLICT", "code=%s" % exc.code)
check("P8 冲突后状态版本未推进",
len(store8.rows("pbl_entity_state")) == 1 and
int(store8.rows("pbl_entity_state")[0]["state_version"]) == 1)
# ---------------- P9 时延与 SLA
lat = r1.get("latency") or {}
sla = lat.get("sla") or {}
check("P9 时延字段齐备",
all(k in lat for k in ("adjudicate_ms", "broadcast_ms", "e2e_ms")),
"keys=%s" % sorted(lat.keys()))
check("P9 SLA 预算 200/300/1000 + 3s 兜底",
sla.get("adjudicate_ms") == 200 and sla.get("broadcast_ms") == 300
and sla.get("e2e_ms") == 1000 and sla.get("poll_fallback_interval_ms") == 3000,
"sla=%s" % sla)
check("P9 实测在预算内", r1.get("within_sla") is True,
"adjudicate=%sms broadcast=%sms e2e=%sms"
% (lat.get("adjudicate_ms"), lat.get("broadcast_ms"), lat.get("e2e_ms")))
# ---------------- P10 append-only 守卫 + 分区算法
ok_tx, msgs_tx = W.self_check()
check("P10 tx_write 自检（append-only/分区/幂等键）", ok_tx,
"; ".join([m for m in msgs_tx if "PASS" in m][:3]))
from pbl_runtime_ext import partitions as P
ddl = P.ddl_create_partition(__import__("datetime").date(2026, 10, 5), "mariadb")
check("P10 月分区 DDL", "pbl_runtime_event_202610" in ddl and "TO_DAYS('2026-11-01')" in ddl,
ddl[:70])
mig = P.partition_migration_ddl(2, "mariadb")
check("P10 分区改造 DDL 含复合主键+MAXVALUE 兜底",
any("ADD PRIMARY KEY (`id`, `created_at`)" in s for s in mig)
and any("MAXVALUE" in s for s in mig))
try:
P.ddl_drop_partition("pbl_runtime_event_202610")
P.ddl_drop_partition("pbl_entity_state")
check("P10 拒绝删除非事件月分区", False)
except ValueError as exc:
check("P10 拒绝删除非事件月分区", True, str(exc)[:40])
fails = [r for r in RESULTS if not r[0]]
print("\n==== M11b SELFTEST: %d/%d PASS ====" % (len(RESULTS) - len(fails), len(RESULTS)))
for _ok, name, detail in fails:
print(" FAIL %s %s" % (name, detail))
return 1 if fails else 0
if __name__ == "__main__": if __name__ == "__main__":