From 3e457215965ae14f9545b63bb6e957857e53e99c Mon Sep 17 00:00:00 2001 From: codeasier <48463012+codeasier@users.noreply.github.com> Date: Sun, 11 Oct 2026 12:48:38 +0800 Subject: [PATCH] test: measure report integrity cost and preserve mutation guards --- docs/en/sharded-snapshotdb.md | 16 + docs/zh/sharded-snapshotdb.md | 13 + tests/core/test_report_content_integrity.py | 423 ++++++++++++++++++++ 3 files changed, 452 insertions(+) create mode 100644 tests/core/test_report_content_integrity.py diff --git a/docs/en/sharded-snapshotdb.md b/docs/en/sharded-snapshotdb.md index 53bf44a..7720b02 100644 --- a/docs/en/sharded-snapshotdb.md +++ b/docs/en/sharded-snapshotdb.md @@ -294,6 +294,22 @@ validation reads) is: | Native-v2 cold | 2B + 2M; one full validator | 2B + 2M; one full validator | | Unchanged in-process warm | B + M; no full validator | No hash reads or full validator | +For an unchanged default-mode dataset, `peak_memory_report` inspects once, then +checks the complete manifest and **all devices' members** after each composed +query. A normal peak plus attribution therefore hashes **4(B + M) cold** or +**3(B + M) warm**; a no-peak early return has one guard and hashes **3(B + M) cold** +or **2(B + M) warm**. Cold reports run one full validator; warm reports run none. +These are logical hash-read bytes, not physical disk I/O: OS page caching can +reduce disk reads. They also exclude SQLite/query reads and header preflights. +The phase/byte regressions in `tests/core/test_report_content_integrity.py` use a +real sparse native empty range; the compatibility no-peak case injects only that +result branch after a real query, since finalized v1 requires contiguous IDs and +non-NULL counters. Both real guards remain covered, including hidden-token +changes to another device and changes that attribution could otherwise restore. +This records the existing integrity cost, not a speedup or resolution of +[issue #238](https://github.com/codeasier/pt-snap-cli/issues/238). Reducing passes +requires a separately established stable-read boundary or explicit contract change. + Both modes revalidate after manifest/member replacement and evict failed or cancelled admissions; a new process starts cold. If a filesystem hides **all** change tokens after content tampering, default strong mode detects the changed diff --git a/docs/zh/sharded-snapshotdb.md b/docs/zh/sharded-snapshotdb.md index f89cfad..417d07b 100644 --- a/docs/zh/sharded-snapshotdb.md +++ b/docs/zh/sharded-snapshotdb.md @@ -238,6 +238,19 @@ POSIX change token 的平台在此模式下每次完整重验。immutable 模式 | 原生 v2 cold | 2B + 2M;一次完整 validator | 2B + 2M;一次完整 validator | | 同进程未变更 warm | B + M;无完整 validator | 无哈希读取、无完整 validator | +默认模式下内容未变时,`peak_memory_report` 只 inspect 一次,随后每个组合查询结束都 +检查完整 manifest 和**所有设备的成员**。正常 peak 加 attribution 共哈希 +**cold 4(B + M)**、**warm 3(B + M)**;无峰值提前返回只有一次 guard,共哈希 +**cold 3(B + M)**、**warm 2(B + M)**。cold 报告运行一次完整 validator,warm 不运行。 +这是逻辑哈希读取字节数,不是物理磁盘 I/O;OS page cache 可能减少磁盘读取,且上述 +数字不包含 SQLite/查询读取和 header 预检。`tests/core/test_report_content_integrity.py` +按阶段与实际读取字节回归:原生模式使用真实稀疏空范围;兼容 v1 要求连续 ID 和非 NULL +计数,因此兼容模式的无峰值用例只在真实查询后注入该结果分支。两个真实 guard 均被 +覆盖,包括隐藏 change token 后另一设备的变更,以及原本可在 attribution 时恢复的 +中途变更。这记录现有完整性成本,不代表提速或解决 +[issue #238](https://github.com/codeasier/pt-snap-cli/issues/238)。减少遍数需要另行建立 +稳定读取边界或明确变更合同。 + 两模式在 manifest/成员替换后重新完整校验;失败或取消的准入会驱逐缓存,新进程仍从 cold 开始。如果内容篡改后文件系统隐藏了**所有** change token,默认强验证仍检测内容 变化,而 immutable 可能复用旧校验结果;此输入违反显式 opt-in 合同。这些仅为进程内 diff --git a/tests/core/test_report_content_integrity.py b/tests/core/test_report_content_integrity.py new file mode 100644 index 0000000..5c5e8cc --- /dev/null +++ b/tests/core/test_report_content_integrity.py @@ -0,0 +1,423 @@ +"""Issue #238: measure report hashing without weakening either content guard. + +These are logical bytes returned by real hash reads, not physical disk I/O. +No timing threshold or assumption about the operating system's page cache. +""" + +import dataclasses +import os +import sqlite3 +from collections import Counter +from contextlib import closing, contextmanager +from pathlib import Path + +import pytest + +from pt_snap_cli.core import dataset_resolver as resolver +from pt_snap_cli.core import native_dataset_contract as native +from pt_snap_cli.core import query_service as queries +from pt_snap_cli.core.dataset_files import hash_file +from pt_snap_cli.core.errors import DatabaseSchemaError, QueryTimeoutError +from pt_snap_cli.core.report_service import ReportService +from tests.test_dataset_focus import make_dataset +from tests.test_native_dataset import dataset as native_dataset + + +@pytest.fixture(autouse=True) +def isolate(tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("HOME", str(tmp_path)) + monkeypatch.setattr(Path, "home", lambda: tmp_path) + for name in ("PT_SNAP_DB_PATH", "PT_SNAP_QUERY_TIMEOUT", "PT_SNAP_DATASET_CACHE"): + monkeypatch.delenv(name, raising=False) + resolver._VALIDATED.clear() + yield + resolver._VALIDATED.clear() + + +@pytest.fixture(params=["compatibility", "native"]) +def artifact(request, tmp_path): + root = ( + make_dataset(tmp_path / "dataset", devices=(0, 1), slices=2) + if request.param == "compatibility" + else native_dataset(tmp_path) + ) + resolver._VALIDATED.clear() # Producer validation is not reader admission. + return root, request.param + + +@dataclasses.dataclass +class HashRead: + phase: str + path: Path + bytes_read: int = 0 + completed: bool = False + + +class ReportWork: + def __init__(self): + self.phases = [] + self.events = [] + self.hashes = [] + self.readers = [] + self.connections = [] + self.inspections = [] + self.validators = Counter() + self.guards = 0 + self.read_limit = None + self.before_read = None + self.after_read = None + + @contextmanager + def phase(self, name): + self.events.append(name + ":start") + self.phases.append(name) + try: + yield + except BaseException: + self.events.append(name + ":failed") + raise + else: + self.events.append(name + ":done") + finally: + self.phases.pop() + + def counts(self, phase): + return Counter(item.path for item in self.hashes if item.phase == phase) + + def assert_closed(self): + assert all(reader.closed for reader in self.readers) + for connection in self.connections: + with pytest.raises(sqlite3.ProgrammingError, match="closed"): + connection.execute("SELECT 1") + + +@pytest.fixture +def work(monkeypatch): + """Wrap both imported hash aliases; count only bytes the real hasher reads.""" + work = ReportWork() + active = [] + real_open, real_connect = Path.open, sqlite3.connect + + class Reader: + def __init__(self, source, item, budget): + self.source, self.item, self.budget = source, item, budget + + def __enter__(self): + self.source.__enter__() + return self + + def __exit__(self, *args): + return self.source.__exit__(*args) + + def read(self, size): + if work.before_read is not None: + work.before_read(self.item) + data = self.source.read(min(size, work.read_limit) if work.read_limit else size) + self.item.bytes_read += len(data) + if work.after_read is not None: + work.after_read(self.item, self.budget, data) + return data + + def opened(path, *args, **kwargs): + source = real_open(path, *args, **kwargs) + if active and path == active[-1][0].path: + work.readers.append(source) + return Reader(source, *active[-1]) + return source + + def hashed(path, **kwargs): + item = HashRead(work.phases[-1], path) + work.hashes.append(item) + active.append((item, kwargs.get("budget"))) + try: + result = hash_file(path, **kwargs) + item.completed = True + return result + finally: + active.pop() + + def connect(*args, **kwargs): + connection = real_connect(*args, **kwargs) + work.connections.append(connection) + return connection + + inspect, guard = resolver.DatasetResolver.inspect, resolver.ResolvedDataset.require_unchanged + + def inspected(self, *args, **kwargs): + with work.phase("inspect"): + result = inspect(self, *args, **kwargs) + work.inspections.append(result) + return result + + def guarded(self, *args, **kwargs): + work.guards += 1 + with work.phase(f"guard{work.guards}"): + return guard(self, *args, **kwargs) + + for name in ("validate_dataset", "validate_native_dataset"): + original = getattr(resolver, name) + + def validated(*args, _original=original, _name=name, **kwargs): + work.validators[_name] += 1 + with work.phase("validator"): + return _original(*args, **kwargs) + + monkeypatch.setattr(resolver, name, validated) + for name, phase in (("global_query", "peak"), ("event_attribution", "attribution")): + original = getattr(queries, name) + + def queried(*args, _original=original, _phase=phase, **kwargs): + with work.phase(_phase): + return _original(*args, **kwargs) + + monkeypatch.setattr(queries, name, queried) + monkeypatch.setattr(Path, "open", opened) + monkeypatch.setattr(sqlite3, "connect", connect) + monkeypatch.setattr(resolver, "_hash_file", hashed) + monkeypatch.setattr(native, "_hash_file", hashed) + monkeypatch.setattr(resolver.DatasetResolver, "inspect", inspected) + monkeypatch.setattr(resolver.ResolvedDataset, "require_unchanged", guarded) + return work + + +@pytest.fixture(params=[False, True], ids=["cold", "warm"]) +def admission(artifact, request): + root, _ = artifact + if request.param: + assert resolver.DatasetResolver().inspect(root) is not None + return request.param + + +def report(root, **kwargs): + service = ReportService() + try: + return service.peak_memory_report(root, device_id=0, **kwargs) + finally: + service.close() + + +@pytest.mark.parametrize("empty", [False, True], ids=["peak", "no-peak"]) +def test_report_phase_hash_calls_and_actual_read_bytes( + artifact, admission, work, monkeypatch, empty +): + root, layout = artifact + params = {} + if empty and layout == "native": + params = {"start_id": 18, "end_id": 26} # Real sparse-ID empty range. + elif empty: + # Valid compatibility-v1 has contiguous IDs and non-NULL counters, so + # no in-bounds empty peak exists. Inject only the no-peak result branch + # after a real query; admission and its guard still execute unchanged. + original = queries.global_query + + def no_peak(*args, **kwargs): + result = original(*args, **kwargs) + return dataclasses.replace(result, rows=[dict.fromkeys(result.rows[0])]) + + monkeypatch.setattr(queries, "global_query", no_peak) + result = report(root, **params) + paths = [root / "manifest.json", *sorted(root.glob("*/*.db"))] + expected_inspect = Counter(dict.fromkeys(paths, 1 if admission else 2)) + expected_validator = Counter() + if not admission and layout == "native": + expected_inspect = Counter({paths[0]: 2}) + expected_validator = Counter(dict.fromkeys(paths[1:], 2)) + assert work.counts("inspect") == expected_inspect + assert work.counts("validator") == expected_validator + assert work.counts("guard1") == Counter(dict.fromkeys(paths, 1)) + assert work.counts("guard2") == (Counter() if empty else Counter(dict.fromkeys(paths, 1))) + assert len(work.inspections) == 1 + validator = "validate_dataset" if layout == "compatibility" else "validate_native_dataset" + assert work.validators == (Counter() if admission else Counter({validator: 1})) + assert all( + item.completed and item.bytes_read == item.path.stat().st_size for item in work.hashes + ) + passes = (1 if admission else 2) + (1 if empty else 2) + assert sum(item.bytes_read for item in work.hashes) == passes * sum( + path.stat().st_size for path in paths + ) + expected_events = ["inspect:start"] + if not admission: + expected_events += ["validator:start", "validator:done"] + expected_events += ["inspect:done", "peak:start", "peak:done", "guard1:start", "guard1:done"] + if not empty: + expected_events += ["attribution:start", "attribution:done", "guard2:start", "guard2:done"] + assert work.events == expected_events + assert (result.event_id is None) == empty + if empty: + assert result.callstack_groups == [] and result.allocator_gap is None + assert result.scope["fingerprint"] == work.inspections[0].fingerprint + # A warm sparse native range can exclude every shard before SQLite opens. + assert bool(work.connections) == (not (admission and empty and layout == "native")) + work.assert_closed() + + +def change_content(root, target): + path = ( + root / "manifest.json" + if target == "manifest" + else root / f"device_{1 if target == 'other-device' else 0}/slice_00000.db" + ) + before, contents = path.stat(), path.read_bytes() + if target == "manifest": + # JSON whitespace only: same length and meaning, different content hash. + changed = contents.replace(b" ", b"\t", 1) + assert changed != contents + path.write_bytes(changed) + else: + device = 1 if target == "other-device" else 0 + with closing(sqlite3.connect(path)) as conn, conn: + conn.execute(f"UPDATE trace_entry_{device} SET reserved=reserved+1 WHERE id>=0") + os.utime(path, ns=(before.st_atime_ns, before.st_mtime_ns)) + assert path.stat().st_size == before.st_size + assert path.stat().st_mtime_ns == before.st_mtime_ns + assert path.read_bytes() != contents + return path, contents + + +@pytest.mark.parametrize("stage", ["peak", "attribution"]) +@pytest.mark.parametrize("target", ["member", "other-device", "manifest"]) +def test_hidden_content_change_fails_at_each_report_guard( + artifact, work, monkeypatch, stage, target +): + root, _ = artifact + name = "global_query" if stage == "peak" else "event_attribution" + original = getattr(queries, name) + changes = [] + + def changed(*args, **kwargs): + result = original(*args, **kwargs) + pinned = work.inspections[0] + changes.append(change_content(root, target)) + # Simulate all generation tokens being hidden, not merely restored mtime. + monkeypatch.setattr(resolver, "_generation", lambda *a: pinned.generation) + return result + + monkeypatch.setattr(queries, name, changed) + guard = 1 if stage == "peak" else 2 + with pytest.raises(DatabaseSchemaError, match="content changed during operation"): + report(root) + assert len(changes) == 1 and work.guards == guard + assert work.events[-1] == f"guard{guard}:failed" + if stage == "peak": + assert "attribution:start" not in work.events + assert changes[0][0] in work.counts(f"guard{guard}") + # A pinned guard refuses the report but does not evict resolver admission. + assert resolver._VALIDATED[root].resolved.fingerprint == work.inspections[0].fingerprint + work.assert_closed() + + +def test_first_guard_rejects_change_even_if_attribution_would_restore_it( + artifact, work, monkeypatch +): + root, _ = artifact + peak, attribution = queries.global_query, queries.event_attribution + changes, restored = [], [] + + def changed(*args, **kwargs): + result = peak(*args, **kwargs) + changes.append(change_content(root, "member")) + monkeypatch.setattr(resolver, "_generation", lambda *a: work.inspections[0].generation) + return result + + def restore_then_attribute(*args, **kwargs): + path, contents = changes[0] + path.write_bytes(contents) + restored.append(path) + return attribution(*args, **kwargs) + + monkeypatch.setattr(queries, "global_query", changed) + monkeypatch.setattr(queries, "event_attribution", restore_then_attribute) + with pytest.raises(DatabaseSchemaError, match="content changed during operation"): + report(root) + assert changes and not restored + assert work.guards == 1 and work.events[-1] == "guard1:failed" + assert "attribution:start" not in work.events + work.assert_closed() + + +def test_compatibility_cold_report_brackets_validator_and_refuses_cache_admission( + tmp_path, work, monkeypatch +): + root = make_dataset(tmp_path / "dataset", devices=(0, 1), slices=2) + validator, generation = resolver.validate_dataset, resolver._generation + baseline = [] + + def pinned(*args): + if not baseline: + baseline.append(generation(*args)) + return baseline[0] + + def changed(*args, **kwargs): + result = validator(*args, **kwargs) + change_content(root, "other-device") + return result + + monkeypatch.setattr(resolver, "_generation", pinned) + monkeypatch.setattr(resolver, "validate_dataset", changed) + with pytest.raises(DatabaseSchemaError, match="content changed during inspection"): + report(root) + assert root not in resolver._VALIDATED + assert work.guards == 0 and "peak:start" not in work.events + assert work.validators == Counter({"validate_dataset": 1}) + assert work.counts("inspect")[root / "manifest.json"] == 1 + assert all(work.counts("inspect")[path] == 2 for path in root.glob("*/*.db")) + assert all( + item.completed and item.bytes_read == item.path.stat().st_size for item in work.hashes + ) + work.assert_closed() + + +@pytest.mark.parametrize("phase", ["inspect", "guard1", "guard2"]) +@pytest.mark.parametrize("failure", ["timeout", "read-error"]) +def test_partial_hash_failure_closes_resources_and_preserves_cache_contract( + artifact, admission, work, phase, failure +): + root, layout = artifact + fired = [] + + def expire(item, budget, data): + if item.phase == phase and data and not fired: + fired.append(item) + budget.started -= 100 + + def fail_read(item): + if item.phase == phase and item.bytes_read and not fired: + fired.append(item) + raise OSError("injected hash read failure") + + # Force a short successful read before cancellation; file size * call count + # would overstate work, including on the very first manifest hash. + work.read_limit = 17 + if failure == "timeout": + work.after_read = expire + else: + work.before_read = fail_read + error = QueryTimeoutError if failure == "timeout" else DatabaseSchemaError + with pytest.raises(error): + report(root, timeout_s=10) + assert len(fired) == 1 + assert fired[0].bytes_read == 17 < fired[0].path.stat().st_size + assert not fired[0].completed + assert work.hashes[-1] is fired[0] + assert all( + item.completed and item.bytes_read == item.path.stat().st_size for item in work.hashes[:-1] + ) + assert (root in resolver._VALIDATED) == (phase != "inspect") + assert all(reader.closed for reader in work.readers) + for connection in work.connections: + with pytest.raises(sqlite3.ProgrammingError, match="closed"): + connection.execute("SELECT 1") + # The next operation must still succeed; guard failure is not a fabricated + # cache-eviction contract. Inspection cancellation does evict its admission. + work.after_read = None + work.before_read = None + work.read_limit = None + validators = work.validators.copy() + assert report(root).event_id is not None + if phase == "inspect": + name = "validate_dataset" if layout == "compatibility" else "validate_native_dataset" + validators[name] += 1 + assert work.validators == validators + work.assert_closed()