atomicng 1.0.0__py3-none-any.whl

atomicng/__init__.py

@@ -0,0 +1,159 @@
+"""atomicng — forward-only continual writing into a language model's native n-gram memory.
+
+Метод статьи arXiv:2610.31125: T = T⁰ + Δ, запись только forward-проходами,
+очистка Δ побитово возвращает исходную модель.
+
+Публичный API v0.2a (Core — чистый NumPy; torch-слой импортируется лениво):
+    model = atomicng.TinyModel()                      # бэкенд для CI; HF — через atomicng.backends.hf
+    report = atomicng.write(model, evidence, policies=..., metrics=...)
+    model.memory.save_pretrained("out.atomicng")
+    atomicng.publish_check(model)                     # safety-gate перед публикацией
+"""
+import time
+
+from . import specs
+from .backends.tiny import TinyModel
+from .bench import check_regression, run_bench, save_baseline
+from .benchmarks import acquisition, chain, distraction, run_suite
+from .evidence import Block, ByteTokenizer, build_blocks, build_blocks_from_texts
+from .exceptions import (
+    AtomicNGError,
+    BackendError,
+    BudgetExceeded,
+    GuardViolation,
+    OverlayError,
+    PublishRejected,
+    SpecError,
+)
+from .exporters import export_ple, load_ple
+from .guards import WritePolicies
+from .journal import AuditLog, UndoJournal
+from .memory import MemoryPatch
+from .metrics import JsonlExporter, MetricsRegistry
+from .monitor_html import build_report, load_metrics_jsonl, write_report
+from .publishing import PublishConfig, publish_check
+from .rules.d1 import D1Rule, Event, WriteReport
+from .signing import generate_keypair, sign_file, verify_file
+from .specs import SIDECAR_SMALL, TableSpec
+from .testing import HashWriter
+from .verify import VerifyReport, verify_deletion
+from .vllm_bridge import export_for_vllm, merged_table, vllm_general_plugins
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AuditLog",
+    "AtomicNGError",
+    "BackendError",
+    "Block",
+    "BudgetExceeded",
+    "ByteTokenizer",
+    "D1Rule",
+    "Event",
+    "GuardViolation",
+    "HashWriter",
+    "JsonlExporter",
+    "MemoryPatch",
+    "MetricsRegistry",
+    "OverlayError",
+    "PublishConfig",
+    "PublishRejected",
+    "SIDECAR_SMALL",
+    "SpecError",
+    "TableSpec",
+    "TinyModel",
+    "UndoJournal",
+    "VerifyReport",
+    "WritePolicies",
+    "WriteReport",
+    "acquisition",
+    "attach_memory",
+    "build_blocks",
+    "build_blocks_from_texts",
+    "build_report",
+    "export_for_vllm",
+    "chain",
+    "check_regression",
+    "clear_memory",
+    "distraction",
+    "export_ple",
+    "generate_keypair",
+    "load_metrics_jsonl",
+    "load_ple",
+    "merged_table",
+    "publish_check",
+    "revert_last",
+    "run_bench",
+    "run_suite",
+    "save_baseline",
+    "sign_file",
+    "specs",
+    "verify_deletion",
+    "verify_file",
+    "vllm_general_plugins",
+    "write",
+    "write_report",
+    "__version__",
+]
+
+
+def attach_memory(model, spec: TableSpec | None = None):
+    """Подключает разреженный патч Δ к модели (у TinyModel она уже есть)."""
+    if getattr(model, "memory", None) is None:
+        model.memory = MemoryPatch(spec or model.spec)
+    return model
+
+
+def write(
+    model,
+    evidence,
+    writer: HashWriter | None = None,
+    rule: D1Rule | None = None,
+    policies: WritePolicies | None = None,
+    audit: AuditLog | None = None,
+    undo: UndoJournal | None = None,
+    metrics: MetricsRegistry | None = None,
+    source: str | None = None,
+) -> WriteReport:
+    """Записывает свидетельство (str или список строк) в память. Только forward-вычисления.
+
+    policies: guards (бюджеты/капы); audit: JSONL-журнал (S4);
+    undo: pre-image журнал для точного отката; metrics: реестр мониторинга;
+    source: идентификатор источника в provenance оверлея.
+    """
+    texts = [evidence] if isinstance(evidence, str) else list(evidence)
+    if not texts:
+        raise ValueError("пустое свидетельство")
+    writer = writer or HashWriter(model.memory.spec)
+    rule = rule or D1Rule()
+    events = writer.events(texts)
+    if undo is not None:
+        undo.record(model.memory, {e.row_id for e in events})
+    t0 = time.perf_counter()
+    report = rule.apply(model.memory, events, policies)
+    elapsed_ms = (time.perf_counter() - t0) * 1000.0
+    if source:
+        model.memory.sources.append(source)
+    if metrics is not None:
+        metrics.record_write(report, model.memory.stats(), elapsed_ms)
+    if audit is not None:
+        audit.append(
+            "write",
+            {
+                **report.to_dict(),
+                "source": source,
+                "patch_checksum": model.memory.checksum(),
+                "duration_ms": round(elapsed_ms, 3),
+            },
+        )
+    return report
+
+
+def revert_last(model, undo: UndoJournal) -> list[int]:
+    """Точный откат последнего блока записи (pre-image journal)."""
+    return undo.revert_last(model.memory)
+
+
+def clear_memory(model) -> None:
+    """Kill-switch: Δ=0, модель структурно равна базовой."""
+    model.memory.clear()

atomicng/backends/__init__.py

@@ -0,0 +1,9 @@
+"""Engine-адаптеры (слой чтения таблицы моделью).
+
+v0.1: tiny — детерминированная CPU-модель для CI.
+v0.2: torch/HF attach. v0.4: vLLM-ридер, llama.cpp PLE-экспорт.
+"""
+
+from .tiny import TinyModel
+
+__all__ = ["TinyModel"]

atomicng/backends/hf.py

@@ -0,0 +1,248 @@
+"""Sidecar-attach к HF-моделям (torch): инжект чтения T⁰+Δ в residual stream.
+
+Поддерживаются causal-LM структуры Llama/Qwen/Mistral-стиля: `model.model.layers[i]`,
+`model.model.norm` перед lm_head. Хук на входе слоя `inject_layer` добавляет проекцию
+прочитанных строк таблицы; хук на `model.model.norm` захватывает Ĥ (вход lm_head)
+для признаков writer'а. Δ хранится в ядре (MemoryPatch, NumPy) — запись only-forward,
+в градиенты модели она не вмешивается.
+
+Ограничение v0.2a: sidecar-T⁰ детерминирована от seed (seed сохраняется в provenance
+оверлея), перенос оверлея между машинами требует того же seed. Нативные заводские
+таблицы — Track B (v1.0).
+"""
+from __future__ import annotations
+
+import contextlib
+from types import SimpleNamespace
+
+import numpy as np
+
+from ..exceptions import BackendError
+from ..memory import MemoryPatch
+from ..rules.d1 import D1Rule
+from ..specs import SIDECAR_SMALL, TableSpec
+
+
+def _require_torch():
+    try:
+        import torch  # noqa: PLC0415
+        return torch
+    except ImportError as exc:
+        raise BackendError("backends.hf требует torch: pip install 'atomicng[torch]'") from exc
+
+
+def bigram_rows(input_ids: list[int], n_rows: int) -> list[int]:
+    from .tiny import TinyModel  # noqa: PLC0415
+
+    return [TinyModel.row_hash(input_ids[i - 1], input_ids[i], n_rows) for i in range(1, len(input_ids))]
+
+
+class SidecarTable:
+    """T⁰ (детерминированная от seed, заморожена) + проекция в hidden_size модели."""
+
+    def __init__(self, spec: TableSpec, hidden_size: int, seed: int = 17) -> None:
+        torch = _require_torch()
+        self.spec = spec
+        self.hidden_size = hidden_size
+        self.seed = seed
+        gen = torch.Generator().manual_seed(seed)
+        self.t0 = 0.02 * torch.randn(spec.n_rows, spec.row_width, generator=gen)  # T⁰, иммутабельна
+        self.proj = torch.nn.Linear(spec.row_width * spec.n_heads, hidden_size, bias=False)
+        with torch.no_grad():
+            self.proj.weight.mul_(0.02)  # стартовое влияние памяти мало (ρ-статья)
+
+    def to(self, device: str) -> SidecarTable:
+        """Переносит T⁰ и проекцию на устройство (для тренировки на GPU/TPU-VM)."""
+        torch = _require_torch()
+        self.t0 = self.t0.to(device)
+        self.proj = self.proj.to(torch.device(device))
+        return self
+
+    def read(self, input_ids: list[int], memory: MemoryPatch) -> np.ndarray:
+        """(T, d): строки T⁰+Δ для биграмм последовательности; позиция 0 — нули."""
+        t = len(input_ids)
+        out = np.zeros((t, self.spec.row_width), dtype=np.float32)
+        for i, row in enumerate(bigram_rows(input_ids, self.spec.n_rows), start=1):
+            t0_row = self.t0[row]
+            if t0_row.is_cuda:
+                t0_row = t0_row.detach().cpu()
+            out[i] = t0_row.numpy() + memory.get(row)
+        return out
+
+    def inject(self, input_ids: list[int], memory: MemoryPatch):
+        """→ тензор (T, hidden) для сложения с hidden states слоя (на устройстве proj)."""
+        torch = _require_torch()
+        read = torch.from_numpy(self.read(input_ids, memory))
+        return self.proj(read.to(self.proj.weight.device))
+
+
+class SidecarHandle:
+    """Хуки чтения + запись свидетельств только forward-проходами."""
+
+    def __init__(self, model, spec: TableSpec | None = None, inject_layer: int = 2, seed: int = 17) -> None:
+        torch = _require_torch()
+        self.torch = torch
+        self.spec = spec or SIDECAR_SMALL
+        self.inject_layer = inject_layer
+        try:
+            self.inner = model.model  # LlamaForCausalLM-стиль
+            self.layers = model.model.layers
+            self.norm = model.model.norm
+        except AttributeError as exc:
+            raise BackendError(
+                "attach_sidecar: не нашёл model.model.layers — поддержаны causal-LM "
+                "Llama/Qwen/Mistral-стиля; для своей архитектуры реализуйте хуки вручную"
+            ) from exc
+        hidden_size = int(model.config.hidden_size)
+        self.table = SidecarTable(self.spec, hidden_size, seed=seed)
+        self.memory = MemoryPatch(self.spec, created_by=f"hf-sidecar:seed={seed}")
+        self.model_ref = model
+        self._ids: list[int] | None = None
+        self.last_hidden: np.ndarray | None = None
+        self._hooks = [
+            self.layers[inject_layer].register_forward_pre_hook(self._inject_hook, with_kwargs=True),
+            self.norm.register_forward_pre_hook(self._capture_hook, with_kwargs=True),
+        ]
+
+    # ------------------------------------------------------------------ хуки
+
+    def _inject_hook(self, module, args, kwargs):
+        h = args[0]
+        if self._ids is None:
+            return args, kwargs
+        mem = self.table.inject(self._ids, self.memory).to(h.dtype).to(h.device)
+        if h.dim() == 3:  # (B, T, Hd): одна сессия — батч 1
+            mem = mem.unsqueeze(0)
+        return (h + mem,) + tuple(args[1:]), kwargs
+
+    def _capture_hook(self, module, args, kwargs):
+        h = args[0]
+        self.last_hidden = h.detach().to("cpu").float().numpy()
+
+    # --------------------------------------------------------------- сессии
+
+    @contextlib.contextmanager
+    def write_session(self, input_ids: list[int]):
+        """Задаёт последовательность для чтения таблицы на время одного forward."""
+        prev, self._ids = self._ids, list(input_ids)
+        try:
+            yield self
+        finally:
+            self._ids = prev
+
+    def forward_hidden(self, input_ids: list[int]):
+        """Forward с чтением памяти; возвращает Ĥ (T, Hd) — вход lm_head."""
+        torch = self.torch
+        was_training = self.model_ref.training
+        self.model_ref.eval()
+        dev = next(self.model_ref.parameters()).device
+        with torch.no_grad():
+            with self.write_session(input_ids):
+                outputs = self.model_ref(input_ids=torch.tensor([input_ids], dtype=torch.long, device=dev))
+        if was_training:
+            self.model_ref.train()
+        if outputs.hidden_states is not None:
+            return outputs.hidden_states[-1][0].numpy()
+        if self.last_hidden is None:
+            raise BackendError("модель не вернула hidden_states и хук Ĥ не сработал")
+        return self.last_hidden[0]
+
+    # ---------------------------------------------------------------- запись
+
+    def write(self, input_ids: list[int], writer, rule: D1Rule | None = None,
+              memory_aware: bool = True) -> dict:
+        """Запись свидетельства: Ĥ → writer → цели/гейты → D1 в ядро. Только forward.
+
+        memory_aware=True — delta-вариант статьи (кодирование читает текущую Δ);
+        memory_aware=False — plain-вариант: кодирование на T⁰-only модели
+        (writer видит нулевые Δ и счётчики), запись в память при этом обычная.
+        """
+        from ..rules.d1 import Event  # noqa: PLC0415
+
+        hidden = self.forward_hidden(input_ids)          # (T, Hd) — ПОЛНАЯ последовательность
+        rows = bigram_rows(input_ids, self.spec.n_rows)  # (T-1,)
+        th = self.torch.from_numpy(hidden[None])         # (1, T, Hd): writer сам срежет позицию 0
+        t_rows = self.torch.tensor([rows], dtype=self.torch.long)
+        if memory_aware:
+            delta_rows = self.torch.stack(
+                [self.torch.from_numpy(self.memory.get(r)) for r in rows]
+            )[None]
+            counts = self.torch.tensor(
+                [[float(self.memory.count(r)) for r in rows]], dtype=self.torch.float32
+            )
+        else:
+            zero = self.torch.zeros(1, len(rows), self.spec.row_width)
+            delta_rows, counts = zero, self.torch.zeros(1, len(rows))
+        with self.torch.no_grad():  # запись only-forward: writer не обучается здесь
+            targets, gates, _ = writer(th, t_rows, delta_rows, counts)
+        events = [
+            Event(row_id=rows[i], target=targets[0, i].numpy(), gate=float(gates[0, i]))
+            for i in range(len(rows))
+        ]
+        report = (rule or D1Rule()).apply(self.memory, events)
+        self.memory.sources.append(f"hf-write:{len(input_ids)}tok")
+        return report.to_dict()
+
+    def nll(self, input_ids_list: list[list[int]]) -> float:
+        """Средний NLL (nats/token) последовательностей при текущей памяти T⁰+Δ."""
+        total, count = 0.0, 0
+        for ids in input_ids_list:
+            if len(ids) < 2:
+                continue
+            with self.write_session(ids), self.torch.no_grad():
+                dev = next(self.model_ref.parameters()).device
+                out = self.model_ref(input_ids=self.torch.tensor([ids], dtype=self.torch.long, device=dev))
+            logits = out.logits[0].float()
+            logprobs = self.torch.log_softmax(logits[:-1], dim=-1)
+            targets = self.torch.tensor(ids[1:], dtype=self.torch.long, device=logits.device)
+            total -= float(logprobs[self.torch.arange(len(ids) - 1, device=logits.device), targets].sum())
+            count += len(ids) - 1
+        return total / max(count, 1)
+
+    # --------------------------------------------------------------- оверлеи
+
+    def save_overlay(self, path: str) -> None:
+        self.memory.save_pretrained(path)
+
+    def detach(self) -> None:
+        for h in self._hooks:
+            h.remove()
+        self._hooks.clear()
+
+
+def attach_sidecar(model, spec: TableSpec | None = None, inject_layer: int = 2, seed: int = 17) -> SidecarHandle:
+    """Подключает sidecar-таблицу к HF-модели (или совместимому стабу) и возвращает handle."""
+    return SidecarHandle(model, spec=spec, inject_layer=inject_layer, seed=seed)
+
+
+def stub_causal_lm(hidden_size: int = 32, vocab_size: int = 64, n_layers: int = 4, seed: int = 3):
+    """Мини-стуб causal-LM структуры HF (для тестов attach без скачивания весов)."""
+    torch = _require_torch()
+    gen = torch.Generator().manual_seed(seed)
+
+    class StubLayer(torch.nn.Module):
+        def forward(self, h):
+            return h + 0.1 * torch.tanh(h)
+
+    class StubInner(torch.nn.Module):
+        def __init__(self) -> None:
+            super().__init__()
+            self.layers = torch.nn.ModuleList(StubLayer() for _ in range(n_layers))
+            self.norm = torch.nn.RMSNorm(hidden_size)
+
+    class StubModel(torch.nn.Module):
+        def __init__(self) -> None:
+            super().__init__()
+            self.config = SimpleNamespace(hidden_size=hidden_size)
+            self.embed = torch.nn.Parameter(0.1 * torch.randn(vocab_size, hidden_size, generator=gen))
+            self.model = StubInner()
+            self.lm_head = torch.nn.Linear(hidden_size, vocab_size, bias=False)
+
+        def forward(self, input_ids, **_):
+            h = self.embed[input_ids]
+            for layer in self.model.layers:
+                h = layer(h)
+            h = self.model.norm(h)
+            return SimpleNamespace(logits=self.lm_head(h), hidden_states=None)
+
+    return StubModel()

atomicng/backends/tiny.py

@@ -0,0 +1,112 @@
+"""Детерминированная CPU-модель для тестов и CI (аналог smoke-конфига официального репо).
+
+НЕ модель статьи: крошечный псевдо-LLM, который читает таблицу T⁰+Δ так же, как нативный
+движок (gather строк по хэшу биграммы), — этого достаточно, чтобы гонять весь цикл
+write → read → clear → verify на любом CPU без torch.
+"""
+from __future__ import annotations
+
+import hashlib
+
+import numpy as np
+
+from ..memory import MemoryPatch
+from ..specs import SIDECAR_SMALL, TableSpec
+
+
+def _logsumexp(x: np.ndarray, axis: int = -1, keepdims: bool = False) -> np.ndarray:
+    m = np.max(x, axis=axis, keepdims=True)
+    out = m + np.log(np.sum(np.exp(x - m), axis=axis, keepdims=True))
+    return out if keepdims else np.squeeze(out, axis=axis)
+
+
+class TinyModel:
+    """Псевдо-LLM: эмбеддинги токенов + чтение n-gram таблицы перед «выходным слоем».
+
+    Логиты для последовательности токенов: пул эмбеддингов + пул прочитанных строк
+    таблицы, спроецированные фиксированной матрицей. Всё детерминировано (blake2b-хэш
+    строк таблицы, seeded RNG весов).
+    """
+
+    def __init__(
+        self,
+        spec: TableSpec | None = None,
+        vocab_size: int = 512,
+        out_dim: int = 32,
+        seed: int = 17,
+    ) -> None:
+        self.spec = spec or SIDECAR_SMALL
+        self.vocab_size = vocab_size
+        rng = np.random.default_rng(seed)
+        self.t0 = (0.02 * rng.standard_normal((self.spec.n_rows, self.spec.row_width))).astype(np.float32)
+        self.embed = (0.10 * rng.standard_normal((vocab_size, self.spec.row_width))).astype(np.float32)
+        self.w_out = (0.05 * rng.standard_normal((self.spec.row_width, out_dim))).astype(np.float32)
+        self.w_vocab = (0.05 * rng.standard_normal((self.spec.row_width, vocab_size))).astype(np.float32)
+        self.memory = MemoryPatch(self.spec)
+
+    @staticmethod
+    def row_hash(prev_token: int, token: int, n_rows: int) -> int:
+        """Детерминированный кросс-платформенный хэш биграммы → номер строки."""
+        digest = hashlib.blake2b(f"{int(prev_token)}:{int(token)}".encode(), digest_size=8).digest()
+        return int.from_bytes(digest, "little") % n_rows
+
+    def read(self, tokens: list[int]) -> np.ndarray:
+        """Чтение таблицы по биграммам: (len, d), позиция 0 — нули (нет предшественника)."""
+        out = np.zeros((len(tokens), self.spec.row_width), dtype=np.float32)
+        for i in range(1, len(tokens)):
+            row = self.row_hash(tokens[i - 1], tokens[i], self.spec.n_rows)
+            out[i] = self.t0[row] + self.memory.get(row)
+        return out
+
+    def logits(self, tokens: list[int]) -> np.ndarray:
+        """(out_dim,) — «выход модели» для последовательности."""
+        h = self.embed[tokens].mean(axis=0) + self.read(tokens).mean(axis=0)
+        return h @ self.w_out
+
+    def probe(self, n: int = 8, seq_len: int = 12, seed: int = 7) -> np.ndarray:
+        """Детерминированный набор выходов: (n, out_dim). Не гарантирует нейтральности."""
+        rng = np.random.default_rng(seed)
+        tokens = rng.integers(0, self.vocab_size, size=(n, seq_len))
+        return np.stack([self.logits([int(t) for t in seq]) for seq in tokens])
+
+    def neutral_token_seqs(self, n: int = 8, seq_len: int = 12, seed: int = 7, max_tries: int = 500) -> list[list[int]]:
+        """Последовательности, гарантированно НЕ адресующие строки текущего патча.
+
+        Генерируются один раз и переиспользуются до и после очистки памяти — так
+        verify/publish сравнивают выходы на одних и тех же входах.
+        """
+        written = set(self.memory.row_ids()) if self.memory is not None else set()
+        rng = np.random.default_rng(seed)
+        seqs: list[list[int]] = []
+        tries = 0
+        while len(seqs) < n and tries < max_tries:
+            tries += 1
+            tokens = [int(x) for x in rng.integers(0, self.vocab_size, size=seq_len)]
+            rows = {self.row_hash(tokens[i - 1], tokens[i], self.spec.n_rows) for i in range(1, seq_len)}
+            if rows & written:
+                continue
+            seqs.append(tokens)
+        if len(seqs) < n:
+            raise RuntimeError(f"не удалось набрать {n} нейтральных последовательностей (патч слишком плотный)")
+        return seqs
+
+    def run_seqs(self, seqs: list[list[int]]) -> np.ndarray:
+        return np.stack([self.logits(seq) for seq in seqs])
+
+    def token_logits(self, tokens: list[int]) -> np.ndarray:
+        """Логиты следующего токена (словарные, для NLL): (T-1, V)."""
+        h = self.embed[tokens[:-1]] + self.read(tokens[:-1])
+        return h @ self.w_vocab
+
+    def nll(self, seqs: list[list[int]]) -> float:
+        """Средний NLL (nats/token) предсказания t+1 при текущей памяти T⁰+Δ."""
+        total, count = 0.0, 0
+        for seq in seqs:
+            if len(seq) < 2:
+                continue
+            logits = self.token_logits(seq)
+            logprobs = logits - _logsumexp(logits, axis=-1, keepdims=True)
+            targets = np.asarray(seq[1:], dtype=np.int64)
+            total -= float(np.sum(logprobs[np.arange(len(targets)), targets]))
+            count += len(targets)
+        return total / max(count, 1)

atomicng/bench.py

@@ -0,0 +1,97 @@
+"""atomicng bench (P1): скорость записи, оверхед чтения, время verify + регресс-гейт.
+
+Модель-зависимая часть передаётся фабрикой; для tiny-бэкенда есть готовый раннер.
+Выход — JSON-отчёт; `check_regression` сравнивает с baseline с допуском и возвращает
+список нарушений (пустой = зелёный) — используется в CI как блокирующий гейт.
+"""
+from __future__ import annotations
+
+import json
+import statistics
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+
+
+def run_bench(
+    model_factory: Callable[[], object],
+    *,
+    n_docs: int = 200,
+    n_probes: int = 64,
+    repeats: int = 5,
+    seed: int = 17,
+) -> dict:
+    """Замеряет: write throughput (документы/события в сек), read overhead %, verify время."""
+    import atomicng  # локально: избегаем цикла в __init__
+
+    model = model_factory()
+    writer = atomicng.HashWriter(model.spec)
+    rng = np.random.default_rng(seed)
+    docs = [
+        " ".join(f"token{int(x)}" for x in rng.integers(0, model.vocab_size, size=48)) for _ in range(n_docs)
+    ]
+
+    # warmup
+    atomicng.write(model, docs[0], writer=writer)
+
+    t0 = time.perf_counter()
+    reports = [atomicng.write(model, doc, writer=writer) for doc in docs]
+    write_s = time.perf_counter() - t0
+    n_events = sum(r.n_events for r in reports)
+
+    # read overhead: чтение нейтральных проб с полным патчем vs с очищенным
+    probe_fn = model.probe
+    full_times: list[float] = []
+    empty_times: list[float] = []
+    snap = model.memory.snapshot()
+    checksum_before = model.memory.checksum()
+    for _ in range(repeats):
+        t = time.perf_counter()
+        probe_fn(n_probes)
+        full_times.append(time.perf_counter() - t)
+    model.memory.clear()
+    for _ in range(repeats):
+        t = time.perf_counter()
+        probe_fn(n_probes)
+        empty_times.append(time.perf_counter() - t)
+    model.memory.restore(snap)
+    assert model.memory.checksum() == checksum_before, "bench исказил патч"
+
+    full = statistics.median(full_times)
+    empty = max(statistics.median(empty_times), 1e-9)
+
+    t0 = time.perf_counter()
+    atomicng.verify_deletion(model, n_probes)
+    verify_s = time.perf_counter() - t0
+
+    return {
+        "n_docs": n_docs,
+        "n_events": n_events,
+        "write_docs_per_s": round(n_docs / write_s, 2),
+        "write_events_per_s": round(n_events / write_s, 1),
+        "read_time_full_ms": round(full * 1000, 3),
+        "read_time_empty_ms": round(empty * 1000, 3),
+        "read_overhead_pct": round((full - empty) / empty * 100.0, 2),
+        "verify_ms": round(verify_s * 1000, 3),
+    }
+
+
+def save_baseline(report: dict, path: str) -> None:
+    Path(path).write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+
+def check_regression(current: dict, baseline: dict, tolerance: float = 1.25) -> list[str]:
+    """Регресс-гейт: write медленнее baseline×tol или оверхед чтения вырос сверх baseline×tol → нарушение."""
+    failures: list[str] = []
+    for key in ("write_events_per_s", "write_docs_per_s"):
+        limit = baseline[key] / tolerance
+        if current[key] < limit:
+            failures.append(f"{key}: {current[key]} < {limit:.2f} (baseline {baseline[key]}, допуск x{tolerance})")
+    limit_overhead = max(baseline["read_overhead_pct"], 1.0) * tolerance
+    if current["read_overhead_pct"] > limit_overhead:
+        failures.append(
+            f"read_overhead_pct: {current['read_overhead_pct']} > {limit_overhead:.2f} (baseline {baseline['read_overhead_pct']})"
+        )
+    return failures