AKASHIC ZERO

【AKASHIC ZERO 公式技術叢書】本番Python自律運用ガードレール全書(SQLite WAL・Playwright冪等性

AKASHIC ZERO(シロイスタジオ(25xx STUDIO))の本番自動化基盤で実証された、SQLite WAL無副作用スナップショット読取、flock排他制御、Playwright At-Most-Once状態機械、Fail-Closed LLMルーター統合体系書。

pythonsqliteplaywrightai

収録章構成(全3章)

章タイトル文字数区分
第1章【Python実装】SQLite WAL無副作用スナップショット読取とflock競合制御:実機計測と検証コード17,929文字無料プレビュー収録
第2章AIの「直したら壊れた」ループを防ぐ設計:57行AGENTS.mdでトークン95%削減、別AIの3往復レビューと¥0ゲート32,780文字本編収蔵章
第3章Playwrightブラウザ自動投稿の『二重送信・CAPTCHA無限ループ』を完封するAt-Most-Once状態機械とPython実装32,625文字本編収蔵章

無料公開プレビュー(第1章): 【Python実装】SQLite WAL無副作用スナップショット読取とflock競合制御:実機計測と検証コード

単一ホスト上で複数のPython自律ワーカー(定期スケジューラ、状態監視デーモン、制作バッチ)を同時に稼働させると、SQLiteまわりの2つの静かな障害に突き当たります。

1つ目は **WALモードDBの「読み取り専用のはずの監視処理」が -shm ファイル生成を試みて失敗する問題** です。監視プロセスやバックアップ機構が読み取り専用権限(たとえば 0o555 ディレクトリ)やロック競合下で sqlite3.connect("file:...?mode=ro", uri=True) を開こうとすると、SQLiteが -shm 共有メモリインデックスを初期化しようとして sqlite3.OperationalError: attempt to write a readonly database で落ちるケースがあります。さらに共有状態ディレクトリ上で不用意にリーダーがファイルを作ると、後続ワーカーとの間で権限・マウント境界の不整合を起こします。

2つ目は 排他制御の非対称性によるスケジュールスキップ暴走 です。バッチ制作ジョブが長時間 flock で排他ロックを握っている間に1分間隔のスケジューラが起動した際、非ブロッキングの LOCK_EX | LOCK_NB を1回だけ試して即座に例外クラッシュさせると、プロセス監視上は「毎時ユニット失敗(EXIT_FAILURE)」が積み上がり、復旧待機中のキューも詰まります。逆に上限なしのブロッキング待ちにすると、多重起動したプロセスがメモリとプロセス枠を食い潰します。

本記事では、Python 3.12 標準ライブラリのみを使ってこの2つの問題を根治する 2層防御パターン を実装・検証コードつきで解説します。

この記事で解決する設計課題と結論

障害パターン従来の落とし穴本設計(検証済み)実機計測値
WAL読取の副作用・権限エラーmode=ro でも -shm 不在時に書込失敗メインDB+-wal を順次読込しRAM上でページ結合、sqlite3.deserialize() へ渡す1,000行WAL復元 p50 6.44 ms(-shm 生成ゼロ)
クラッシュ後の不完全WAL破損テールや未コミットページを読んで不整合salt1/salt2・累積チェックサム・db_size > 0 境界で切り捨て検証破損テール付加後も既コミット2TXのみ厳密復元
ワーカー間の flock 衝突即時クラッシュまたは無限待機でプロセス滞留決定論的ジッタ付き指数バックオフ+タイムアウト時 Fail-Closed 退避無競合獲得 p50 13.65 us / タイムアウト時FD漏れ0

この設計の要点は 「状態判定の純粋ロジック(Functional Core)」と「OSシステムコールの薄いアダプタ(Imperative Shell)」を明確に分離すること にあります。

実機検証の前提と計測環境(本記事で実測した範囲)

本記事の数値はすべて同一のローカル環境(Python 3.12 / SQLite flagship-verification-receipt相当の sqlite3 3.45.1)で test_sqlite_wal_flock_guard.py(全6テスト+ベンチマーク)を実実行して取得した実測値です。架空のハードウェア性能や推定値は含めていません。

  • スナップショット読取対象: journal_mode=WAL、wal_autocheckpoint=0 で1,000行をコミット直後の未チェックポイント状態(本体 4096 bytes / WAL 164832 bytes / コミット済み 40 フレーム)
  • 読取レイテンシ(30回反復): p50 = 6.437 ms、p95 = 7.557 ms、max = 7.735 ms
  • **無競合 flock 取得+解放(50回反復)**: p50 = 13.65 us、p95 = 16.26 us
  • **0o555 読取専用ディレクトリ検査**: 標準 file:...?mode=ro は -shm 不在時に OperationalError を送出することを確認した上で、本スナップショット方式は -shm を一切生成せず全レコードを読み取れることを確認

適用限界(使ってはいけないケース)

本手法は万能ではありません。次のワークロードには不向きです。

  • 数百MB〜数GBの巨大DBに対する毎秒クエリ: インメモリスナップショット生成のため、DB本体+WALサイズと同等のRAMを一時消費します。数MB〜数十MBまでの状態管理DB・ジョブ台帳・テレメトリDBを想定しています。
  • **NFSなど fcntl.flock が共有カーネルで一貫しない分散ストレージ**: 同一カーネル内のプロセス間排他が前提です。複数ホストにまたがる場合は別機構が必要です。

関連する自律ワーカー基盤の設計記録として、以下の実機ベンチマーク記事もあわせて参考になります。

  • 関連実測記録: https://note.com/shiroi1229/n/n9b2f053609f7

1. アーキテクチャ全体像:純粋コアとOSアダプタの分離

WAL無副作用スナップショット読取と有界 flock 制御を運用しやすくする最大のコツは、バイト列解析とバックオフ計算を I/Oを持たない純粋Pythonコア に閉じ込め、ファイル読込・sqlite3.deserialize・fcntl.flock だけを十数行の薄いOSアダプタに隔離することです。これにより、WALのチェックサム検証やクラッシュ復旧のエッジケースを、ファイルシステムやプロセス競合に依存せず決定論的に単体テストできます。

2. WAL バイナリ構造とチェックサム検証(完全実装&単体テスト)

SQLite WAL 先頭32バイトのヘッダには以下の情報が格納されています。

  • [0:4] マジックナンバー(ビッグエンディアン読取): 0x377F0682(32bitワードのチェックサム計算がリトルエンディアン)または 0x377F0683(ビッグエンディアン)
  • [4:8] フォーマット版 3007000、[8:12] ページサイズ(2の冪乗)、[16:24] salt1 / salt2、[24:32] ヘッダチェックサム
  • 各フレームは **24バイトヘッダ+page_sizeバイト本文** で構成され、累積チェックサム (s0, s1) は前フレームからの引き継ぎで frame_header[0:8] と page_data に対して計算されます。db_size > 0 のフレームだけがトランザクションのコミット境界です。

また、インメモリバッファを sqlite3.Connection.deserialize() へ渡す直前、メモリ上のバッファ内に限り SQLite ヘッダの [18:20] バイト目(書込/読取フォーマットバージョン)を 2(WAL)から 1(従来ジャーナル)へ書き換えることで、deserialize() がディスク上の -shm や -wal を参照しようとして失敗する罠を回避します。ディスク上の元ファイルは1ビットも変更しません。

以下のコードは標準ライブラリのみで完結しており、ヘッダ生成・コミット境界解決・破損テール切り捨て・RAMヘッダ正規化の自己検証テストを含みます。

from __future__ import annotations

import dataclasses
from typing import Optional

WAL_MAGIC_LE = 0x377F0682
WAL_MAGIC_BE = 0x377F0683
WAL_FORMAT_VERSION = 3007000
WAL_HEADER_BYTES = 32
WAL_FRAME_HEADER_BYTES = 24
SQLITE_HEADER_MAGIC = b"SQLite format 3\x00"

@dataclasses.dataclass(frozen=True)
class WalHeader:
    magic: int
    big_endian_checksum: bool
    format_version: int
    page_size: int
    checkpoint_seq: int
    salt1: int
    salt2: int
    csum1: int
    csum2: int

@dataclasses.dataclass(frozen=True)
class WalOverlayReport:
    wal_present: bool
    wal_header_valid: bool
    page_size: int
    committed_tx_count: int
    committed_frame_count: int
    uncommitted_tail_frames: int
    stop_reason: str
    committed_db_pages: int
    snapshot_bytes_len: int

def wal_checksum_step(
    chunk: bytes | bytearray,
    s0: int,
    s1: int,
    *,
    big_endian: bool,
) -> tuple[int, int]:
    if len(chunk) % 8 != 0:
        raise ValueError(f"8バイト境界ではないチャンクです: {len(chunk)}")
    byteorder = "big" if big_endian else "little"
    mask = 0xFFFFFFFF
    for off in range(0, len(chunk), 8):
        x0 = int.from_bytes(chunk[off : off + 4], byteorder)
        x1 = int.from_bytes(chunk[off + 4 : off + 8], byteorder)
        s0 = (s0 + x0 + s1) & mask
        s1 = (s1 + x1 + s0) & mask
    return s0, s1

def _u32_be(buf: bytes, offset: int) -> int:
    return int.from_bytes(buf[offset : offset + 4], "big")

def parse_wal_header(wal_bytes: bytes) -> WalHeader:
    if len(wal_bytes) < WAL_HEADER_BYTES:
        raise ValueError(f"WALヘッダ長不足: {len(wal_bytes)}")
    magic = _u32_be(wal_bytes, 0)
    if magic not in (WAL_MAGIC_LE, WAL_MAGIC_BE):
        raise ValueError(f"未知のWALマジック値: 0x{magic:08x}")
    big_endian = magic == WAL_MAGIC_BE
    fmt_ver = _u32_be(wal_bytes, 4)
    if fmt_ver != WAL_FORMAT_VERSION:
        raise ValueError(f"非対応フォーマット版: {fmt_ver}")
    page_size = _u32_be(wal_bytes, 8)
    if page_size < 512 or page_size > 65536 or (page_size & (page_size - 1)) != 0:
        raise ValueError(f"不正なページサイズ: {page_size}")
    ckpt_seq = _u32_be(wal_bytes, 12)
    salt1 = _u32_be(wal_bytes, 16)
    salt2 = _u32_be(wal_bytes, 20)
    csum1 = _u32_be(wal_bytes, 24)
    csum2 = _u32_be(wal_bytes, 28)
    calc0, calc1 = wal_checksum_step(wal_bytes[:24], 0, 0, big_endian=big_endian)
    if (calc0, calc1) != (csum1, csum2):
        raise ValueError("WALヘッダチェックサム不一致")
    return WalHeader(magic, big_endian, fmt_ver, page_size, ckpt_seq, salt1, salt2, csum1, csum2)

def resolve_committed_wal_pages(
    wal_bytes: bytes,
) -> tuple[Optional[WalHeader], dict[int, bytes], int, int, int, int, str]:
    if not wal_bytes:
        return None, {}, 0, 0, 0, 0, "empty_wal"
    if len(wal_bytes) < WAL_HEADER_BYTES:
        return None, {}, 0, 0, 0, 0, "truncated_wal_header"
    try:
        hdr = parse_wal_header(wal_bytes)
    except ValueError as exc:
        return None, {}, 0, 0, 0, 0, f"invalid_wal_header:{exc}"

    frame_size = WAL_FRAME_HEADER_BYTES + hdr.page_size
    s0, s1 = hdr.csum1, hdr.csum2
    committed_pages: dict[int, bytes] = {}
    pending_pages: dict[int, bytes] = {}
    committed_db_pages = 0
    committed_tx_count = 0
    committed_frame_count = 0
    stop_reason = "eof"
    pos = WAL_HEADER_BYTES

    while pos + frame_size <= len(wal_bytes):
        fhdr = wal_bytes[pos : pos + WAL_FRAME_HEADER_BYTES]
        page_data = wal_bytes[pos + WAL_FRAME_HEADER_BYTES : pos + frame_size]
        if (_u32_be(fhdr, 8), _u32_be(fhdr, 12)) != (hdr.salt1, hdr.salt2):
            stop_reason = "salt_mismatch_old_generation"
            break
        s0, s1 = wal_checksum_step(fhdr[:8], s0, s1, big_endian=hdr.big_endian_checksum)
        s0, s1 = wal_checksum_step(page_data, s0, s1, big_endian=hdr.big_endian_checksum)
        if (s0, s1) != (_u32_be(fhdr, 16), _u32_be(fhdr, 20)):
            stop_reason = "frame_checksum_mismatch"
            break
        page_no = _u32_be(fhdr, 0)
        db_size = _u32_be(fhdr, 4)
        if page_no == 0:
            stop_reason = "invalid_page_zero"
            break
        pending_pages[page_no] = page_data
        if db_size > 0:
            committed_pages.update(pending_pages)
            committed_frame_count += len(pending_pages)
            pending_pages.clear()
            committed_db_pages = db_size
            committed_tx_count += 1
        pos += frame_size

    if stop_reason == "eof" and pos < len(wal_bytes):
        stop_reason = "truncated_tail_frame"
    return hdr, committed_pages, committed_db_pages, committed_tx_count, committed_frame_count, len(pending_pages), stop_reason

def assemble_snapshot_bytes(db_bytes: bytes, wal_bytes: bytes = b"") -> tuple[bytes, WalOverlayReport]:
    if len(db_bytes) < 100 or db_bytes[:16] != SQLITE_HEADER_MAGIC:
        raise ValueError("有効なSQLite3ヘッダではありません")
    raw_ps = int.from_bytes(db_bytes[16:18], "big")
    base_ps = 65536 if raw_ps == 1 else raw_ps
    hdr, committed_pages, db_pages, tx_cnt, fr_cnt, uncomm_cnt, reason = resolve_committed_wal_pages(wal_bytes)
    ps = hdr.page_size if hdr is not None else base_ps
    target_len = db_pages * ps if db_pages > 0 else len(db_bytes)
    buf = bytearray(db_bytes[:target_len])
    if len(buf) < target_len:
        buf.extend(b"\x00" * (target_len - len(buf)))
    for page_no, page_data in committed_pages.items():
        start = (page_no - 1) * ps
        if start + ps <= len(buf):
            buf[start : start + ps] = page_data
    if buf[18] == 2:
        buf[18] = 1
    if buf[19] == 2:
        buf[19] = 1
    report = WalOverlayReport(bool(wal_bytes), hdr is not None, ps, tx_cnt, fr_cnt, uncomm_cnt, reason, len(buf) // ps, len(buf))
    return bytes(buf), report

def _build_synthetic_wal(page_size: int, frames: list[tuple[int, int, bytes]]) -> bytes:
    salt1, salt2 = 0x11223344, 0x55667788
    prefix = (
        WAL_MAGIC_LE.to_bytes(4, "big")
        + WAL_FORMAT_VERSION.to_bytes(4, "big")
        + page_size.to_bytes(4, "big")
        + (0).to_bytes(4, "big")
        + salt1.to_bytes(4, "big")
        + salt2.to_bytes(4, "big")
    )
    s0, s1 = wal_checksum_step(prefix, 0, 0, big_endian=False)
    out = bytearray(prefix + s0.to_bytes(4, "big") + s1.to_bytes(4, "big"))
    for page_no, db_size, payload in frames:
        meta8 = page_no.to_bytes(4, "big") + db_size.to_bytes(4, "big")
        s0, s1 = wal_checksum_step(meta8, s0, s1, big_endian=False)
        s0, s1 = wal_checksum_step(payload, s0, s1, big_endian=False)
        out.extend(meta8 + salt1.to_bytes(4, "big") + salt2.to_bytes(4, "big") + s0.to_bytes(4, "big") + s1.to_bytes(4,