Python Field Manual

L1: add_lot(lot_id, capacity)
    park_car(lot_id, car_id)
    remove_car(lot_id, car_id)
    get_available_spots(lot_id)
L2: find_car(car_id) — which lot
    get_fullest_lots(n)
L3: park_car 加 ttl_ms
    get_parking_fee(lot_id, car_id)
L4: backup / restore（remaining_ttl）
    get_car_history(lot_id)
L5: batch — park/remove 單 lock
    transfer car pair-lock
L6: sync_lots(lot_ids, max_concurrent)
    fail-fast

L1: create_channel(channel_id, max_signals)
    inject_signal(channel_id, signal_id, strength)
    drop_signal(channel_id, signal_id)
    read_channel(channel_id)
L2: strongest_channels(n) — by total strength
    find_signal(signal_id) — which channel
L3: inject_signal 加 ttl_ms
    expired signal 唔計
L4: backup / restore（remaining_ttl）
    get_signal_history(channel_id)
L5: batch — inject/drop 單 lock
    transfer signal pair-lock
L6: sync_channels(channel_ids, max_concurrent)
    fail-fast

L1: create_pool(pool_id, max_units)
    claim_unit(pool_id, job_id, unit_count)
    release(pool_id, job_id)
    get_utilization(pool_id)
    get_job_claims(job_id) — for loop all pools
L2: top pools by utilization
L3: claim 加 ttl_ms → expired claim auto-release
L4: backup / restore（remaining_ttl）
    get_claim_history(pool_id)
L5: batch — claim/release 單 lock
    transfer pair-lock
L6: sync_pools(pool_ids, max_concurrent)
    fail-fast

L1: create_zone(zone_id, total_slots)
    reserve(zone_id, tenant_id, slot_count)
    release(zone_id, tenant_id)
    get_remaining(zone_id)
L2: get_tenant_zones(tenant_id) — for loop
    get_busiest_zones(n)
L3: reserve 加 ttl_ms
    extend(zone_id, tenant_id, extra_ms)
L4: backup / restore（remaining_ttl）
    get_reservation_history(zone_id)
    merge_zone(from, to)
L5: batch — reserve/release 單 lock
    transfer pair-lock
L6: sync_zones(zone_ids, max_concurrent)
    fail-fast

L1: create_recipe(recipe_id, chef_id, cook_time)
    add_ingredient(recipe_id, ingredient_name, qty)
    remove_ingredient(recipe_id, ingredient_name)
    get_recipe(recipe_id)
    get_chef_recipes(chef_id) — for loop
L2: search recipes by ingredient
    top recipes by ingredient count
L3: ingredient 加 ttl_ms（expires = 用完）
L4: backup / restore
    get_recipe_history(recipe_id)
L5: batch — add/remove 單 lock
L6: sync_recipes(recipe_ids, max_concurrent)
    fail-fast

L1: register_policy(policy_id, desc, max_violations)
    flag_violation(policy_id, entity_id, violation_id, severity)
    clear_violation(violation_id) ← 只有 v_id！
    get_active_violations(entity_id)
L2: get_worst_entities(n) — for loop violations
    find_violation(violation_id)
L3: flag_violation 加 ttl_ms
    expired violation auto-resolve
L4: backup / restore（remaining_ttl）
    get_violation_history(entity_id) — defaultdict(list)
    merge_entity(from, to)
L5: batch — flag/clear 鎖 locks[v_id]
    transfer_violation pair-lock
L6: report_violations(v_ids, max_concurrent)
    唔存在/已 cleared → fail-fast
    active → sem + sleep + mark REPORTED

L1: create_queue(queue_id, priority_level)
    submit_report(queue_id, report_id, content_id, reason)
    claim_report(report_id, moderator_id) ← 只有 r_id！
    resolve_report(report_id, decision)
    get_pending_count(queue_id)
L2: get_moderator_workload(moderator_id) — for loop
    get_busiest_queues(n)
    find_report(report_id)
L3: submit_report 加 ttl_ms
    get_report_age(report_id)
L4: backup / restore（remaining_ttl）
    get_content_history(content_id) — defaultdict(list)
    escalate(report_id, from_queue, to_queue)
L5: batch — submit/claim/resolve 單 lock
    escalate pair-lock
L6: send_decisions(report_ids, max_concurrent)
    未 resolved → fail-fast
    resolved → sem + sleep + mark NOTIFIED

L1: register_band(band_id, freq_start, freq_end)
    lease(band_id, operator_id, lease_id) ← lease_id 獨立！
    revoke(lease_id) ← 只有 lease_id！
    get_band_status(band_id)
L2: get_operator_bands(operator_id) — for loop
    get_available_bands() — filter unleased
L3: lease 加 ttl_ms
    get_remaining_lease(lease_id)
L4: backup / restore（remaining_ttl）
    get_lease_history(band_id)
    transfer_lease(lease_id, new_operator_id)
L5: batch — lease/revoke 單 lock
    transfer pair-lock
L6: sync_bands(band_ids, max_concurrent)
    band 唔存在 → fail-fast

Family 1 你要記住 4 件事：
1. 只有一個主角 dict：self.items[item_id]
2. L1 係最基本 create / update / get / delete
3. L3 先加 expiry；L4 先加 backups / history / merge
4. L5 單 key 用一把 lock；transfer 呢類雙 key 要 pair-lock

適用題型：
- Bank：account_id -> {balance, outgoing, history}
- Leaderboard：player_id -> {score, history}
- Scheduler：event_id -> {execute_at, status}
- Session：session_id -> {user_id, expiry}

import copy
import asyncio
from collections import defaultdict

class GenericF1:
    def __init__(self):
        self.items = {}                     # L1：主 dict，item_id -> item data
        self.backups = []                   # L4：snapshot list
        self.merged_items = {}              # L4：old_id -> new_id
        self.locks = defaultdict(asyncio.Lock)  # L5：per-item lock

def create(self, timestamp, item_id, field1, field2):      # 開一個新 item；好似喺總名冊度加一張全新卡
    if item_id in self.items:                              # 呢個 id 已經有人霸咗位；即係同一個櫃桶名撞咗
        return False                                       # 已存在就拒絕；唔畀覆蓋舊人
    self.items[item_id] = {                                # 真正落筆開卡；之後所有 level 都圍住呢張卡做加料
        "field1": field1,                                  # 主數值；通常係 balance / score / execute_at 呢類最核心嗰格
        "field2": field2,                                  # 第二格資料；可能係 outgoing / status / owner 呢類副資料
        "expiry": None,                                    # L1 先當永不過期；L3 先開始貼上到期時間
        "history": [(timestamp, field1)],                  # L4 會用到；等於一開卡就順手影第一張相留底
    }
    return True                                            # 成功開卡

def update(self, timestamp, item_id, field1):             # 改 item 嘅主數值；好似拎起張卡改最新餘額
    if item_id not in self.items:                          # 想改嗰張卡根本唔喺名冊入面
        return None                                        # 冇卡可改 → 直接話 caller 今次撲空
    self.items[item_id]["field1"] = field1                # 將主數值改成最新版本；唔係加減，係直接覆蓋
    self.items[item_id]["history"].append((timestamp, field1))  # 每改一次都記低時間同新值；方便之後問「嗰陣時幾多」
    return self.items[item_id]["field1"]                  # 回傳改完之後最新嗰個值

def get(self, timestamp, item_id):                        # 查一張卡而家主數值係幾多
    if item_id not in self.items:                          # 冇呢張卡
        return None                                        # 冇得答，只能回空結果
    return self.items[item_id]["field1"]                  # 直接交返主數值；唔連成張 dict 一齊掟畀外面

def delete(self, timestamp, item_id):                     # 刪走一張卡；等於成個 item 從總名冊除名
    if item_id not in self.items:                          # 本身都唔存在
        return False                                       # 所以刪唔到
    del self.items[item_id]                                # 真正將成張卡由 dict 度抽走
    return True                                            # 刪除成功

def deposit(self, timestamp, item_id, amount):             # 真題常見 variant：加錢 / 加分 / 加資源
    if item_id not in self.items:                          # 主角唔存在就做唔到
        return None
    self.items[item_id]["field1"] += amount               # 將數值直接加上去
    self.items[item_id]["history"].append((timestamp, self.items[item_id]["field1"]))  # 新值一樣要留底
    return self.items[item_id]["field1"]

def transfer(self, timestamp, source_id, target_id, amount):  # pair-op variant：同時改兩張卡，但都仲係 Family 1
    if source_id not in self.items or target_id not in self.items or source_id == target_id:  # 任一張卡唔啱都即走
        return None
    self.items[source_id]["field1"] -= amount             # source 扣走
    self.items[target_id]["field1"] += amount             # target 加返
    self.items[source_id]["history"].append((timestamp, self.items[source_id]["field1"]))  # source 新值留底
    self.items[target_id]["history"].append((timestamp, self.items[target_id]["field1"]))  # target 新值留底
    return self.items[source_id]["field1"]

item = self.items.get(item_id)                             # Step 1：先認主角永遠係一張 flat item 卡
if op == "create": check_duplicate = item_id in self.items  # Step 2：create 先 check duplicate
if op != "create": check_missing = item is None            # Step 3：其餘全部先 check missing
self.items[item_id] = {...}                               # Step 4：create / update 都係直接打 self.items[item_id]
result = self.items[item_id]["field1"]                    # Step 5：回傳 shape 要跟 spec，通常係值 / True / None

def top_n(self, timestamp, n):                           # 揀頭 n 張最勁嘅卡；等於排龍虎榜
    items = []                                           # 先開個臨時排行榜草稿紙
    for item_id, info in self.items.items():             # 逐張卡巡一次；將每個人嘅分數搬去 sorting 用嘅 tuple
        items.append((-info["field1"], item_id))         # 前面落負號 = 想大數排先；後面放 id = 同分時按字母 / id 順
    items.sort()                                         # Python 會先比第一格，再比第二格；即係 score desc + id asc
    result = []                                          # 準備正式榜單
    for value, item_id in items[:n]:                     # 只拎排頭嗰 n 個；後面嗰堆唔使理
        result.append(item_id)                           # generic 版先淨係交 id；真題可以改成 "alice(300)" 呢類 format
    return result                                        # 回傳 top n 名單

def items_above(self, timestamp, min_value):              # filter variant：搵所有高過某條線嘅 item
    result = []                                           # 先開結果 list
    for item_id, info in self.items.items():              # 逐張卡睇一次
        if info["field1"] >= min_value:                   # 達標先收
            result.append(item_id)
    result.sort()                                         # 呢類多數最後字母順交返
    return result

def get_next_item(self, timestamp):                       # next / earliest variant：用 field1 當時間
    best = None                                           # 暫時未揀中
    for item_id, info in self.items.items():              # 巡一次所有 item
        candidate = (info["field1"], item_id)             # 先用 metric，再用 id tie-break
        if best is None or candidate < best:              # 越細越前
            best = candidate
    return None if best is None else best[1]

rows = []                                                 # Step 1：L2 先 collect，唔好一開始就 format
rows.append((-metric, item_id))                          # Step 2：top-N 通常砌 (-metric, id)
rows.sort()                                              # Step 3：先 sort，再 cut 頭 n 個
filtered = [item_id for item_id, info in self.items.items() if keep(info)]  # Step 4：filter 題就直接 for loop
return formatted_result                                  # Step 5：最後先決定回 list / string / count

def _purge(self, timestamp):                              # L3 先引入 helper；因為而家先開始有 expiry 呢個概念
    for item_id in list(self.items.keys()):              # 用 list(...) 包住 keys；即係先抄一份名單，再逐個睇
        exp = self.items[item_id]["expiry"]              # 攞呢張卡嘅到期時間出嚟；None 代表永遠有效
        if exp is not None and timestamp >= exp:         # 而家時間已經踩線 / 過線；等於呢張卡過咗期
            del self.items[item_id]                      # 懶清潔工模式：見到死卡就即場掉落垃圾桶

def create_with_ttl(self, timestamp, item_id, field1, field2, ttl_ms):  # 開卡時順手加有效期
    self._purge(timestamp)                               # 每次做新嘢前先掃一次地；唔好畀死卡留喺場搞亂局
    if item_id in self.items:                            # 掃完地之後如果同名卡仍然存在，即係真係撞名
        return False
    expiry = None                                        # 預設當永久卡；如果 caller 冇畀 ttl，就唔會自己死
    if ttl_ms is not None:                               # 有指定存活時間
        expiry = timestamp + ttl_ms                      # 將「仲有幾耐命」換算成「幾時死」
    self.items[item_id] = {
        "field1": field1,                                # 主資料照存
        "field2": field2,                                # 副資料照存
        "expiry": expiry,                                # 關鍵新增位；之後 helper 就靠佢決定生死
        "history": [(timestamp, field1)],                # 開卡第一刻都一樣留低歷史相片
    }
    return True                                          # TTL 卡開成功

def extend(self, timestamp, item_id, extra_ms):           # extension variant：將壽命向後推
    self._purge(timestamp)                                # 先清場，死咗先唔好再續命
    if item_id not in self.items or self.items[item_id]["expiry"] is None:  # 冇 item 或本身冇 TTL
        return False
    self.items[item_id]["expiry"] += extra_ms            # 直接喺舊 expiry 上加
    return True

def process_due(self, timestamp):                        # due-time variant：到鐘觸發副作用
    for item_id in list(self.items.keys()):              # 逐張卡巡一次
        exp = self.items[item_id]["expiry"]              # 攞到期時間
        if exp is not None and timestamp >= exp:         # 到鐘就做事
            self.items[item_id]["field2"] += 1           # generic 版示範：加一格副作用值
            self.items[item_id]["expiry"] = None         # 做完就熄鐘，避免重覆觸發

expiry = timestamp + ttl_ms                              # Step 1：先計絕對 expiry
self._purge(timestamp)                                   # Step 2：每個 public method 開頭先 call helper
if expired: delete_or_mark_inactive                      # Step 3：決定到鐘係 delete 定 status change
if extend: self.items[item_id]["expiry"] += extra_ms     # Step 4：續命係加喺舊 expiry 上
if due_side_effect: mutate_local_state                   # Step 5：due-time 題記住要做副作用

def backup(self, timestamp):                             # 影一張當下全景相；之後 restore 就靠呢張相倒帶
    self._purge(timestamp)                               # 影相前先掃走死卡；唔好將過期垃圾都影埋入備份
    snapshot = copy.deepcopy(self.items)                 # 冇 TTL 特別玩法時，最穩陣就係成份 dict 深拷貝
    self.backups.append((timestamp, snapshot))           # 連影相時間一齊收埋；之後先知邊張相最近 target_ts

def restore(self, timestamp, target_ts):                # 還原返 target_ts 或之前最近嗰張相
    best = None                                          # 暫時仲未揀到要用邊張備份
    for backup_ts, snapshot in self.backups:             # 逐張舊相行一次
        if backup_ts <= target_ts:                       # 呢張相喺 target_ts 或之前，先有資格做候選
            best = (backup_ts, snapshot)                 # 一路覆蓋到最後，最後留低嘅就係最近嗰張
    if best is None:                                     # 一張合資格嘅都冇
        return False
    self.items = copy.deepcopy(best[1])                  # 成份 state 倒帶返去；等於將成個場景換返舊版本
    return True

def get_value_at(self, timestamp, item_id, time_at):    # 想知某張卡喺某個舊時刻個值係幾多
    self._purge(timestamp)                               # 先保持現場乾淨；雖然查舊值，但系統本身狀態都要先整理
    if item_id not in self.items:                        # 呢張卡而家都唔存在
        return None
    for ts, val in reversed(self.items[item_id]["history"]):  # 由最新歷史倒住行；因為最近嗰筆最有機會啱
        if ts <= time_at:                               # 一見到時間冇超過目標時刻，就代表呢筆係當時有效狀態
            return val
    return None                                          # 連一筆舊紀錄都搵唔到

def merge(self, timestamp, id1, id2):                   # 將第二張卡嘅資產 / 數值合併去第一張卡
    self._purge(timestamp)                               # 合併前先掃走死卡；免得同一張屍體卡融合
    if id1 not in self.items or id2 not in self.items or id1 == id2:  # 任一張唔存在，或者自己吞自己
        return False
    self.items[id1]["field1"] += self.items[id2]["field1"]  # 將 source 嗰份數字倒去 target；好似兩個錢包倒埋一個
    self.items[id1]["history"].append((timestamp, self.items[id1]["field1"]))  # 合併後新總數都要留歷史
    self.merged_items[id2] = id1                         # 記低「舊 id2 去咗 id1」；之後查舊人時可以追蹤去向
    del self.items[id2]                                  # source 張卡完成任務，正式收皮
    return True

def backup_with_ttl(self, timestamp):                     # TTL backup variant：唔存絕對 expiry，要存 remaining_ttl
    snap = {}
    for item_id, info in self.items.items():              # 巡全部活 item
        remaining_ttl = None if info["expiry"] is None else info["expiry"] - timestamp  # 先轉成剩餘壽命
        snap[item_id] = {
            "field1": info["field1"],
            "field2": info["field2"],
            "remaining_ttl": remaining_ttl,
            "history": list(info["history"]),
        }
    self.backups.append((timestamp, snap))                # 一樣用 (timestamp, snapshot)
    return str(len(snap))

def get_history(self, timestamp, item_id):                # history list variant：直接交整條歷史帶
    if item_id not in self.items:                          # 冇卡就冇歷史
        return None
    return list(self.items[item_id]["history"])           # copy 一份出去

snapshot = copy.deepcopy(self.items)                       # Step 1：無 TTL backup 直接 deepcopy
remaining_ttl = expiry - timestamp                        # Step 2：有 TTL 就轉 remaining_ttl
best = latest_snapshot_before(target_ts)                  # Step 3：restore 永遠揀 target_ts 或之前最近嗰張
for ts, val in reversed(history): ...                     # Step 4：value-at-time 用 reversed loop
self.merged_items[source_id] = target_id                  # Step 5：merge 記 mapping，再 del source

async def batch(self, timestamp, operations):            # 將一堆 op 一次過丟出去跑；但同一張卡仍然要守秩序
    self._purge(timestamp)                               # 開波前先清場；唔好畀過期 item 夾雜喺 batch 入面

    async def execute_op(op):                            # 每張單自己各自跑呢個 inner worker
        if op["type"] == "transfer":                     # 呢種係雙 key op；同時掂 source 同 target
            keys = sorted([op["source_id"], op["target_id"]])  # 先排序；全世界都跟同一個上鎖順序，避免 deadlock
            async with self.locks[keys[0]]:              # 先鎖字典序較前嗰張卡
                async with self.locks[keys[1]]:          # 再鎖第二張卡；兩張卡都鎖住先可以安全過數
                    s = self.items.get(op["source_id"])  # 攞 source 卡
                    t = self.items.get(op["target_id"])  # 攞 target 卡
                    if not s or not t:                   # 任一張卡唔存在，今次 transfer 即刻作廢
                        return None
                    amount = op["amount"]                # 今次要搬幾多
                    s["field1"] -= amount                # source 減錢；等於左手銀包拎走一嚿錢
                    t["field1"] += amount                # target 加錢；等於右手銀包收返同一嚿錢
                    return s["field1"]                   # generic 版回 source 最新值

        key = op["item_id"]                              # 其餘大部分 op 都只掂一張卡
        async with self.locks[key]:                      # 鎖住嗰張卡；避免兩條 coroutine 同時改同一格
            if op["type"] == "create":
                return self.create(timestamp, op["item_id"], op["field1"], op.get("field2", 0))
            if op["type"] == "update":
                return self.update(timestamp, op["item_id"], op["field1"])
            if op["type"] == "delete":
                return self.delete(timestamp, op["item_id"])
        return None                                      # 如果 type 唔認得，就交空結果

    tasks = [execute_op(op) for op in operations]        # 將每張單變成 coroutine；等於一次過開晒好多條工作線
    results = await asyncio.gather(*tasks)               # 等全部單一齊跑完先收數
    return list(results)                                 # gather 回 tuple-like 結果；轉 list 比 caller 好用啲

async def batch_get(self, timestamp, item_ids):           # read-only batch variant：每張卡各自上鎖再 get
    async def do_one(item_id):
        async with self.locks[item_id]:                   # 即使係 read，有啲題都照跟 item lock
            return self.get(timestamp, item_id)
    return list(await asyncio.gather(*(do_one(item_id) for item_id in item_ids)))

async def batch_update(self, timestamp, ops):            # update-only batch variant：全部都係單 key
    async def do_one(op):
        async with self.locks[op["item_id"]]:             # 一張單一把 lock
            return self.update(timestamp, op["item_id"], op["field1"])
    return list(await asyncio.gather(*(do_one(op) for op in ops)))

async def execute_op(op): ...                             # Step 1：先寫 inner worker
scope = one_item_or_two_items(op)                        # Step 2：先判斷 shared state scope
lock = self.locks[item_id]                               # Step 3：Pattern A 直接一把 lock
keys = sorted([source_id, target_id])                    # Step 4：Pattern B 先 sorted 再 pair-lock
results = await asyncio.gather(*tasks)                   # Step 5：最後 gather，保持輸入順序

async def sync(self, timestamp, item_ids, max_concurrent):  # 一次過將好多 item 推去外面同步；但同一時間只畀 N 個出門
    self._purge(timestamp)                               # 先清走死卡；唔好浪費外部 quota 喺屍體上面
    sem = asyncio.Semaphore(max_concurrent)              # sem = 閘機；同一時間最多放 max_concurrent 個入去

    async def do_one(item_id):                           # 每個 item 各自排隊過閘
        if item_id not in self.items:                    # 呢張卡根本唔存在
            return False                                 # fail-fast：未去到閘口就即刻遣返，連 sleep 都慳返
        async with sem:                                  # 真正過關先佔用一個外部名額
            await asyncio.sleep(0.01)                    # 模擬打 API / 寫 disk / 出網路；即係真外部成本
        return True                                      # 過關完成

    tasks = [do_one(item_id) for item_id in item_ids]    # 每個 item 一條 async 線；全部先排好
    results = await asyncio.gather(*tasks)               # 一齊等佢哋返嚟
    return list(results)                                 # 逐個 item 對應 success / fail 結果

async def process_external_transfers(self, timestamp, transfers, max_concurrent):  # 進階 L6 variant：本地先扣數，再出面 sleep
    sem = asyncio.Semaphore(max_concurrent)              # 外部 quota 閘口
    async def do_one(transfer):
        source_id = transfer["source_id"]                # 搵 source
        target_id = transfer["target_id"]                # 搵 target
        keys = sorted([source_id, target_id])            # 先統一 pair-lock 順序
        async with self.locks[keys[0]]:                  # 第一把鎖
            async with self.locks[keys[1]]:              # 第二把鎖
                if source_id not in self.items or target_id not in self.items:  # 本地 fail-fast
                    return False
                self.items[source_id]["field1"] -= transfer["amount"]  # 先扣 source
                self.items[target_id]["field1"] += transfer["amount"]  # 再加 target
        async with sem:                                  # 本地成功之後先出外面
            await asyncio.sleep(0.01)                    # 模擬真 external transfer call
        return True
    return list(await asyncio.gather(*(do_one(t) for t in transfers)))

sem = asyncio.Semaphore(max_concurrent)                   # Step 1：function 入面先開 sem
if invalid: return False                                 # Step 2：fail-fast 永遠喺 sem 前做
if need_local_mutation: mutate_under_lock_first          # Step 3：有啲題要先改本地 state
async with sem: await asyncio.sleep(0.01)                # Step 4：過關先做 external work
return list(await asyncio.gather(*tasks))                # Step 5：最後 gather 成批結果

Family 2 你要見字即反應：
outer dict = container
inner dict = sub-item

典型 signature：
- create_container(container_id, capacity)
- add_sub(container_id, sub_id, data)
- remove_sub(container_id, sub_id)
- find_sub(sub_id)

適用題型：
- InMemDB：key 入面有 field
- DNS：domain 入面有 record type
- Parking：lot 入面有 cars
- PubSub：topic 入面有 subscribers / messages

import copy
import asyncio
from collections import defaultdict

class GenericF2:
    def __init__(self):
        self.containers = {}                # container_id -> {capacity, subs, history}
        self.backups = []                   # L4 snapshot list
        self.merged_containers = {}         # L4 merge 記錄（如果題目有）
        self.locks = defaultdict(asyncio.Lock)  # L5 per-container lock

def create_container(self, timestamp, container_id, capacity):  # 先開個大容器；等於先起個櫃桶 / 房 / topic
    if container_id in self.containers:                         # 呢個大容器名已經有人用緊
        return False                                            # 撞名就唔畀重開
    self.containers[container_id] = {
        "capacity": capacity,                                   # 呢個大容器最多裝幾多件 sub-item
        "subs": {},                                             # 內層真正擺貨嘅地方；之後 sub_id 全部塞喺度
        "history": [],                                          # L4 用；等於記住曾經入過邊啲貨
    }
    return True

def add_sub(self, timestamp, container_id, sub_id, data):      # 將一件細 item 放入指定容器
    if container_id not in self.containers:                     # 連大容器都未起好
        return False
    container = self.containers[container_id]                   # 先攞出目標容器；之後所有判斷都圍住佢做
    for cid, c in self.containers.items():                      # 行晒全世界所有容器
        if sub_id in c["subs"]:                                 # 如果其他地方已經收咗同名 sub
            return False                                        # 全局撞名；唔畀一件貨同時喺兩個櫃桶出現
    if len(container["subs"]) >= container["capacity"]:        # 呢個容器已經裝滿
        return False                                            # 再塞落去就爆倉
    container["subs"][sub_id] = {"data": data, "expiry": None}  # 正式將貨放入內層小格；L1 先當永不過期
    container["history"].append(sub_id)                         # 記低「呢件貨曾經入過呢個容器」
    return True

def remove_sub(self, timestamp, container_id, sub_id):         # 將指定細 item 由容器入面拎走
    if container_id not in self.containers:                     # 連個櫃桶都冇
        return False
    if sub_id not in self.containers[container_id]["subs"]:     # 目標櫃桶有，但入面搵唔到呢件貨
        return False
    del self.containers[container_id]["subs"][sub_id]           # 真正將內層細格拆走
    return True

def get_count(self, timestamp, container_id):                  # 查呢個容器而家裝住幾多件貨
    if container_id not in self.containers:                     # 大容器唔存在
        return None
    return len(self.containers[container_id]["subs"])           # 直接數 inner dict 有幾個 key

def get_sub(self, timestamp, container_id, sub_id):            # CRUD variant：直接睇某件 sub-item
    if container_id not in self.containers:                     # outer 都未有
        return None
    info = self.containers[container_id]["subs"].get(sub_id)    # inner lookup
    return None if info is None else dict(info)                 # copy 一份返出去

def set_implicit(self, timestamp, container_id, sub_id, data):  # hidden-create variant：冇 create_container，直接自動開 outer
    if container_id not in self.containers:                     # outer 唔存在就即場補開
        self.containers[container_id] = {"capacity": 999999, "subs": {}, "history": []}
    if sub_id in self.containers[container_id]["subs"]:         # 同一個 outer 入面撞名
        return False
    self.containers[container_id]["subs"][sub_id] = {"data": data, "expiry": None}  # 直接塞入 inner dict
    self.containers[container_id]["history"].append(sub_id)     # 歷史都要記
    return True

container = self.containers.get(container_id)                   # Step 1：先搵 outer container
subs = None if container is None else container["subs"]         # Step 2：再落到 inner subs
if need_implicit_create and container is None: open_outer()     # Step 3：隱藏 create 題就先補 outer
if duplicate_or_full: return False                              # Step 4：duplicate / capacity / missing check
subs[sub_id] = {"data": data}                                   # Step 5：真正 CRUD 都係打 inner dict

def find_sub(self, timestamp, sub_id):                         # 得一件細貨 id，反推佢而家收喺邊個大櫃桶
    for cid, container in self.containers.items():             # 逐個大容器打開睇一次
        if sub_id in container["subs"]:                        # 呢件貨喺呢個容器入面
            return cid                                          # 即刻回報地址；唔使再巡其他倉
    return None                                                 # 行晒全場都冇見過

def top_n(self, timestamp, n):                                 # 排頭 n 個最滿 / 最熱鬧嘅容器
    items = []                                                  # 臨時排行榜
    for cid, container in self.containers.items():              # 巡每個容器
        count = len(container["subs"])                          # 用內層 sub 數量做 metric
        items.append((-count, cid))                             # 負號 = 想最多件排先；同數再按 id
    items.sort()                                                # count desc + cid asc
    result = []                                                 # 正式榜單
    for value, cid in items[:n]:                                # 只拎頭 n 名
        result.append(cid)
    return result

def scan(self, timestamp, container_id):                        # scan variant：列出某個 outer 入面所有 inner key
    if container_id not in self.containers:                     # outer 唔存在
        return ""
    keys = sorted(self.containers[container_id]["subs"].keys()) # inner keys 排序
    return ",".join(keys)                                       # generic 版用逗號串起

def scan_by_prefix(self, timestamp, container_id, prefix):      # prefix variant：只揀某個 prefix 開頭嗰堆 sub
    if container_id not in self.containers:
        return ""
    keys = [sub_id for sub_id in self.containers[container_id]["subs"] if sub_id.startswith(prefix)]  # 先 filter
    keys.sort()                                                 # 再 sort
    return ",".join(keys)

if only_sub_id: for cid, container in self.containers.items(): ...  # Step 1：reverse lookup 題就 for loop outer
if have_container_id: read_inner_dict_directly                  # Step 2：scan 題就直接打該 outer
rows.append((-metric, cid))                                     # Step 3：top-N 題先 collect tuple
rows.sort()                                                     # Step 4：sort 之後先 cut 頭 n 個
return format_after_sort                                        # Step 5：最後先 format output

def _purge(self, timestamp):                                    # L3 先有 helper；因為 inner sub 而家先開始有生死時間
    for cid, container in self.containers.items():              # 逐個大容器巡一次
        for sub_id in list(container["subs"].keys()):           # 將細貨名單先抄出嚟；避免一邊行一邊刪爆 dict
            exp = container["subs"][sub_id]["expiry"]           # 攞呢件貨嘅 expiry
            if exp is not None and timestamp >= exp:            # 到鐘就代表呢件貨已經腐爛 / 過期 / 失效
                del container["subs"][sub_id]                   # 真刪 inner entry；等於將過期貨直接由貨架撤走

def add_sub_with_ttl(self, timestamp, container_id, sub_id, data, ttl_ms):  # 放貨入櫃時順手貼埋到期標籤
    self._purge(timestamp)                                      # 開工前先巡一次，清走舊垃圾
    if container_id not in self.containers:                     # 目標容器都未起好
        return False
    container = self.containers[container_id]
    for cid, c in self.containers.items():                      # 全場再巡一次，睇下有冇同名貨已經擺喺其他櫃
        if sub_id in c["subs"]:
            return False
    if len(container["subs"]) >= container["capacity"]:        # 呢個櫃桶已經滿晒
        return False
    expiry = None                                               # 預設永久貨；冇期限就一直放喺架
    if ttl_ms is not None:                                      # caller 真係有畀保鮮期
        expiry = timestamp + ttl_ms                             # 換算成絕對死亡時間
    container["subs"][sub_id] = {
        "data": data,                                           # 真正貨內容
        "expiry": expiry,                                       # 幾時過期；helper 之後靠呢格清貨
    }
    container["history"].append(sub_id)                         # 即使有 TTL，都記住呢件貨曾經來過
    return True

def extend_sub(self, timestamp, container_id, sub_id, extra_ms):  # TTL variant：延長 inner sub 壽命
    self._purge(timestamp)                                      # 先清走已死貨
    if container_id not in self.containers:                     # outer 唔存在
        return False
    sub = self.containers[container_id]["subs"].get(sub_id)     # inner lookup
    if sub is None or sub["expiry"] is None:                    # 冇呢件貨，或者本身冇 TTL
        return False
    sub["expiry"] += extra_ms                                   # 直接喺舊 expiry 上加
    return True

def get_alive_sub(self, timestamp, container_id, sub_id):       # inline-alive variant：讀嗰陣先 skip 死 record
    if container_id not in self.containers:
        return None
    sub = self.containers[container_id]["subs"].get(sub_id)
    if sub is None or (sub["expiry"] is not None and timestamp >= sub["expiry"]):  # 即場 check 是否已死
        return None
    return dict(sub)

sub["expiry"] = timestamp + ttl_ms                              # Step 1：先將 expiry 放入 inner sub
self._purge(timestamp)                                          # Step 2：lazy purge 題每個 public method 開頭先清
if inline_alive_check: skip_dead_subs                           # Step 3：另一條路係 read path 即場 skip 死 record
if extend: sub["expiry"] += extra_ms                            # Step 4：extend 係加喺舊 expiry
outer_stays_alive = True                                        # Step 5：就算 inner 死晒，outer container 仍然喺度

def backup(self, timestamp):                                   # 幫每個大容器影相；但有 TTL，所以唔可以照抄 expiry
    self._purge(timestamp)                                     # 影相前先清走已死貨；避免相入面夾雜過期垃圾
    snapshot = {}
    for cid, container in self.containers.items():             # 每個大容器都各自影一格
        snapshot[cid] = {
            "capacity": container["capacity"],                 # 容器本身規格照抄
            "history": list(container["history"]),             # 歷史用新 list 抄一份；避免共用 reference
            "subs": {},                                        # 內層貨之後逐件塞入 snapshot
        }
        for sub_id, info in container["subs"].items():         # 巡每件仍然活緊嘅貨
            remaining = None                                   # 預設永久貨冇倒數
            if info["expiry"] is not None:
                remaining = info["expiry"] - timestamp         # 唔存絕對 expiry，只存當下仲有幾耐命
            snapshot[cid]["subs"][sub_id] = {
                "data": info["data"],
                "remaining_ttl": remaining,                    # restore 嗰陣靠呢格重新計時
            }
    self.backups.append((timestamp, snapshot))                 # 將影相時間同相片一齊收起

def restore(self, timestamp, target_ts):                      # 想返到 target_ts 當時個貨架狀態
    best = None
    for backup_ts, snapshot in self.backups:                   # 行晒所有舊相
        if backup_ts <= target_ts:                             # 只揀 target_ts 或之前嘅相
            best = (backup_ts, snapshot)                       # 一路覆蓋到最後，即最近嗰張合資格相
    if best is None:
        return False
    self.containers = {}                                       # 先清空現場；等陣成份場景重建
    for cid, snap in best[1].items():
        self.containers[cid] = {"capacity": snap["capacity"], "history": list(snap["history"]), "subs": {}}
        for sub_id, info in snap["subs"].items():              # 將每件舊貨重新擺返入架
            new_expiry = None
            if info["remaining_ttl"] is not None:
                new_expiry = timestamp + info["remaining_ttl"] # 用「而家」加返剩餘壽命，重新開始倒數
            self.containers[cid]["subs"][sub_id] = {"data": info["data"], "expiry": new_expiry}
    return True

def get_history(self, timestamp, container_id):               # 查呢個容器曾經裝過邊啲貨
    self._purge(timestamp)                                     # 查之前先保持現場乾淨
    if container_id not in self.containers:
        return None
    return list(self.containers[container_id]["history"])      # 回新 list；唔好直接交內部 reference 畀外面亂改

def move_sub(self, timestamp, from_container, to_container, sub_id):  # pair-op variant：搬 inner item 去另一個 outer
    self._purge(timestamp)                                      # 先清場
    source = self.containers.get(from_container)                # source outer
    target = self.containers.get(to_container)                  # target outer
    if not source or not target or sub_id not in source["subs"]:  # 任一 outer 唔啱，或者 source 冇貨
        return False
    if len(target["subs"]) >= target["capacity"]:              # target 滿晒
        return False
    target["subs"][sub_id] = source["subs"][sub_id]             # 整份 data 搬過去
    del source["subs"][sub_id]                                  # source 清空
    target["history"].append(sub_id)                            # target history 記低新來客
    return True

def copy_sub(self, timestamp, source_container, target_container, sub_id):  # copy variant：source 保留，target 新建
    source = self.containers.get(source_container)
    target = self.containers.get(target_container)
    if not source or not target or sub_id not in source["subs"]:
        return False
    target["subs"][sub_id] = copy.deepcopy(source["subs"][sub_id])  # 深拷貝一份過去
    target["history"].append(sub_id)
    return True

snapshot[cid]["subs"][sub_id]["remaining_ttl"] = remaining     # Step 1：backup TTL 轉 remaining_ttl
new_expiry = timestamp + remaining_ttl                         # Step 2：restore 用 restore 時刻重算 expiry
history = self.containers[cid]["history"]                      # Step 3：history 跟 outer container 走
source_pop_then_target_set = move_sub()                        # Step 4：move = target 收、source 清
source_keep_then_target_clone = copy_sub()                     # Step 5：copy = source 保留、target 深拷貝

async def batch(self, timestamp, operations):                  # 一次過處理一堆對容器落手嘅指令
    self._purge(timestamp)                                     # batch 前先清場；唔好拎住死貨去搬倉

    async def execute_op(op):                                  # 每張單各自走呢條 async 線
        if op["type"] == "move":                               # 呢款同時掂兩個大容器
            keys = sorted([op["from_container"], op["to_container"]])  # 鎖順序統一化；避免兩條線互相卡死
            async with self.locks[keys[0]]:                    # 先鎖細嗰個 id
                async with self.locks[keys[1]]:                # 再鎖大嗰個；兩邊都封住先好搬貨
                    from_c = self.containers.get(op["from_container"])  # source 倉
                    to_c = self.containers.get(op["to_container"])      # target 倉
                    if not from_c or not to_c:                 # 任一個倉唔存在
                        return False
                    sub_id = op["sub_id"]
                    if sub_id not in from_c["subs"]:           # source 倉根本冇呢件貨
                        return False
                    if len(to_c["subs"]) >= to_c["capacity"]:  # target 倉滿晒，搬唔入
                        return False
                    to_c["subs"][sub_id] = from_c["subs"][sub_id]  # 將件貨整份搬去新倉
                    del from_c["subs"][sub_id]                 # 舊倉嗰格清空；避免一貨兩地
                    return True

        cid = op["container_id"]                               # 其餘單容器 op 都只掂一個 outer key
        async with self.locks[cid]:                            # 鎖住該容器；避免同時有人加減貨
            if op["type"] == "add":
                return self.add_sub(timestamp, cid, op["sub_id"], op["data"])
            if op["type"] == "remove":
                return self.remove_sub(timestamp, cid, op["sub_id"])
        return None

    tasks = [execute_op(op) for op in operations]              # 開晒工人線
    results = await asyncio.gather(*tasks)                     # 等所有搬貨 / 加貨 / 減貨單做完
    return list(results)

async def batch_scan(self, timestamp, container_ids):          # read-only batch variant：逐個 outer scan
    async def do_one(container_id):
        async with self.locks[container_id]:                   # read 題有時一樣跟 outer lock
            return self.get_count(timestamp, container_id)
    return list(await asyncio.gather(*(do_one(cid) for cid in container_ids)))

async def batch_resolve(self, timestamp, requests):            # update-only variant：全部都係單 container op
    async def do_one(req):
        async with self.locks[req["container_id"]]:            # 一條 request 一把 outer lock
            return self.remove_sub(timestamp, req["container_id"], req["sub_id"])
    return list(await asyncio.gather(*(do_one(req) for req in requests)))

scope = one_container_or_two_containers(op)                    # Step 1：先判斷 shared outer scope
lock = self.locks[container_id]                               # Step 2：Pattern A 跟 outer key lock
keys = sorted([from_container, to_container])                 # Step 3：Pattern B 一律 sorted pair-lock
call_old_sync_logic_inside_lock()                             # Step 4：lock 入面再 call add/remove/move
return list(await asyncio.gather(*tasks))                     # Step 5：最後 gather 成批結果

async def sync(self, timestamp, container_ids, max_concurrent):  # 將多個大容器逐個同步去外部世界
    self._purge(timestamp)                                     # 出發前先清場；唔同步死貨
    sem = asyncio.Semaphore(max_concurrent)                    # 閘機：同一時間最多放 N 個容器出去

    async def do_one(cid):                                     # 每個容器一條排隊線
        if cid not in self.containers:                         # 呢個容器名根本唔存在
            return False                                       # fail-fast：門口即彈走
        async with sem:                                        # 真正輪到佢先佔用外部資源
            await asyncio.sleep(0.01)                          # 模擬出網 / 出 disk / 出 replication call
        return True

    tasks = [do_one(cid) for cid in container_ids]             # 所有容器一齊排隊
    results = await asyncio.gather(*tasks)                     # 等全部同步結果返嚟
    return list(results)

async def batch_scan_all_sleep(self, timestamp, container_ids, max_concurrent):  # all-sleep variant：無論存在與否都照樣 attempt
    sem = asyncio.Semaphore(max_concurrent)                    # 閘口一樣限流
    async def do_one(container_id):
        async with sem:                                        # 先入 sem
            await asyncio.sleep(0.01)                          # 先 sleep，模擬一定要打外部 call
        if container_id not in self.containers:                # sleep 完先知 / 先回失敗
            return False
        return True
    return list(await asyncio.gather(*(do_one(cid) for cid in container_ids)))

async def propagate(self, timestamp, domain_ids, max_concurrent):  # fail-fast variant：domain 唔存在就即走
    sem = asyncio.Semaphore(max_concurrent)
    async def do_one(domain_id):
        if domain_id not in self.containers:                   # generic 版用 containers 代 domain registry
            return False
        async with sem:
            await asyncio.sleep(0.01)
        return True
    return list(await asyncio.gather(*(do_one(did) for did in domain_ids)))

is_all_sleep = read_spec_first()                               # Step 1：先判 fail-fast 定 all-sleep
sem = asyncio.Semaphore(max_concurrent)                       # Step 2：function 入面開 sem
if fail_fast and invalid: return False                        # Step 3：fail-fast 版 check 先
async with sem: await asyncio.sleep(0.01)                     # Step 4：真正 external cost 喺 sem 入面
return gathered_results                                       # Step 5：最後逐條 input 對返逐條 output

Family 3 核心：
self.groups = {}    # A 類嘢 / config
self.items = {}     # B 類嘢 / instance

典型 signature：
- create_group(group_id, config)
- create_item(group_id, item_id, other_id, data)
- clear_item(item_id)
- get_active_count(other_id)

適用題型：
- Workflow：workflow + step status
- PackageMgr：package + installation record
- OrderBook：book side + order

import copy
import asyncio
from collections import defaultdict

class GenericF3:
    def __init__(self):
        self.groups = {}                    # group_id -> config / capacity / meta
        self.items = {}                     # item_id -> {group_id, other_id, data, status, expiry}
        self.backups = []                   # L4 snapshots
        self.merged_groups = {}             # L4 old_group -> new_group
        self.history = defaultdict(list)    # L4 history per group
        self.locks = defaultdict(asyncio.Lock)  # L5 per-item / per-other lock

def create_group(self, timestamp, group_id, config):          # 先開一種「大類別 / policy / workflow 容器」
    if group_id in self.groups:                               # 同名 group 已經存在
        return False
    self.groups[group_id] = {"config": config}               # group 通常只存規格、上限、設定值呢類靜態資料
    return True

def create_item(self, timestamp, group_id, item_id, other_id, data):  # 再喺呢個 group 下面開一個真實 instance
    if group_id not in self.groups:                           # 父 group 都未起好；即係冇 policy / 冇 workflow / 冇 band
        return False
    if item_id in self.items:                                 # 呢個 item 自己個 id 已經撞咗
        return False
    self.items[item_id] = {
        "group_id": group_id,                                 # 呢件 item 屬於邊個 group；之後 merge / history 都靠呢格
        "other_id": other_id,                                 # 第二條關係線；可能係 entity_id / operator_id / user_id
        "data": data,                                         # 真 payload；可能係 severity / amount / step data
        "status": "ACTIVE",                                  # 一出世先當活緊；之後先可能變 CLEARED / EXPIRED / REPORTED
        "expiry": None,                                      # L1 先冇 TTL
    }
    self.history[group_id].append(item_id)                    # 先記住呢個 group 曾經收過呢個 item
    return True

def clear_item(self, timestamp, item_id):                     # 將一件 item 由 active 狀態標記為清除咗
    if item_id not in self.items:                             # 連件貨都冇
        return False
    self.items[item_id]["status"] = "CLEARED"                # 唔 delete；因為之後仲可能要計 history / report / audit
    return True

def get_active_count(self, timestamp, other_id):              # 數某個 other_id 旗下仲有幾多件 ACTIVE item
    count = 0
    for item_id, item in self.items.items():                  # 要行晒 item dict；因為 items 係 flat，唔係按 other_id 分桶
        if item["other_id"] == other_id and item["status"] == "ACTIVE":
            count += 1                                        # 呢件既屬於對方，又仲活緊，先計入總數
    return count

def get_item(self, timestamp, item_id):                       # item-only variant：直接睇一張 B 卡
    item = self.items.get(item_id)                            # flat item lookup
    return None if item is None else dict(item)               # copy 一份返出去

def delete_group(self, timestamp, group_id):                  # group variant：刪 group 前通常要先 check 底下有冇 item
    if group_id not in self.groups:                           # A dict 冇呢個 group
        return False
    for item in self.items.values():                          # 巡全部 item
        if item["group_id"] == group_id and item["status"] == "ACTIVE":  # 仲有 live item 掛住喺度
            return False
    del self.groups[group_id]                                 # 真正刪 group
    return True

group = self.groups.get(group_id)                             # Step 1：先分清 A = groups，B = items
item = self.items.get(item_id)                               # Step 2：item-only method 直接打 self.items[item_id]
self.items[item_id] = {"group_id": group_id, ...}           # Step 3：create_item 時記齊兩條關係線
if item["status"] == "ACTIVE": count += 1                    # Step 4：count 題多數要睇 status
if deleting_group: scan_all_items_first                      # Step 5：group 題成日要先巡 items 睇會唔會撞規則

def find_item(self, timestamp, item_id):                      # 由 item_id 反查佢掛喺邊個 group，同埋同邊個 other_id 有關
    if item_id not in self.items:                             # 目標 item 根本唔喺主表
        return None
    item = self.items[item_id]                                # 攞返成張 item 卡
    return (item["group_id"], item["other_id"])              # generic 版回最重要兩條關係線

def top_n(self, timestamp, n):                                # 排頭 n 個最「多 active item」嘅 other_id
    counts = {}                                               # other_id -> active item count
    for item_id, item in self.items.items():                  # 巡全部 instance
        if item["status"] == "ACTIVE":                       # 死咗 / 清咗嗰啲唔好計
            oid = item["other_id"]
            if oid not in counts:                             # 第一次見到呢個 other_id
                counts[oid] = 0
            counts[oid] += 1                                  # 多一件 active item 就加一
    items = []
    for oid, count in counts.items():                         # 將統計結果變成可排序 tuple
        items.append((-count, oid))                           # 多嘅排先；同數用 other_id 作 tie-break
    items.sort()
    result = []
    for value, oid in items[:n]:                              # 拎榜首 n 個
        result.append(oid)
    return result

def get_group_items(self, timestamp, group_id):               # group lookup variant：列出某個 group 底下所有 item
    result = []                                               # 結果 list
    for item_id, item in self.items.items():                  # 巡 items[B]
        if item["group_id"] == group_id:                      # 屬於呢個 group 就收
            result.append(item_id)
    result.sort()                                             # 排序後交返
    return result

def get_items_for_other(self, timestamp, other_id):           # other lookup variant：列出某個 owner / entity 底下所有 item
    result = []                                               # 結果 list
    for item_id, item in self.items.items():                  # 一樣係巡 items[B]
        if item["other_id"] == other_id and item["status"] == "ACTIVE":  # 只要 live 嗰堆
            result.append(item_id)
    result.sort()
    return result

if by_item_id: read_self_items_directly                        # Step 1：item_id 題直接打 self.items
if by_group_or_other: for item_id, item in self.items.items(): ...  # Step 2：group / other stats 題就巡 B dict
if only_live_items: filter_status_active                      # Step 3：好多題只計 ACTIVE
rows.append((-count, oid))                                    # Step 4：排行題先 collect tuple
return formatted_after_sort                                   # Step 5：最後先 format

def _purge(self, timestamp):                                   # L3 先引入 helper；因為 item 而家先開始會過期
    for item_id in list(self.items.keys()):                   # 巡所有 item
        exp = self.items[item_id]["expiry"]                   # 攞 expiry
        if exp is not None and timestamp >= exp:              # 到期即代表呢件 item 已經死咗
            self.items[item_id]["status"] = "EXPIRED"         # 呢個 family 唔 delete，只改 status；方便之後 history / report 仲查得到

def create_item_with_ttl(self, timestamp, group_id, item_id, other_id, data, ttl_ms):  # 開 item 時順手加壽命
    self._purge(timestamp)                                     # 做新動作前先將應該死嘅 item 先判死
    if group_id not in self.groups or item_id in self.items:   # 父 group 唔存在，或者 item 撞名，都唔畀開
        return False
    expiry = None                                              # 預設永久 item
    if ttl_ms is not None:
        expiry = timestamp + ttl_ms                            # 將 ttl 轉成絕對時間炸彈
    self.items[item_id] = {
        "group_id": group_id,
        "other_id": other_id,
        "data": data,
        "status": "ACTIVE",                                   # 一開先當活緊；helper 到鐘先會改成 EXPIRED
        "expiry": expiry,
    }
    self.history[group_id].append(item_id)                     # 呢個 group 嘅歷史清單都要記埋
    return True

def set_status(self, timestamp, item_id, new_status):         # state-machine variant：手動改狀態
    self._purge(timestamp)                                     # 先跑 helper
    if item_id not in self.items:                              # item 唔存在
        return False
    self.items[item_id]["status"] = new_status                # 直接改 status
    return True

def complete_item(self, timestamp, item_id):                  # workflow-like variant：完成一件 item
    self._purge(timestamp)
    if item_id not in self.items or self.items[item_id]["status"] != "ACTIVE":  # 唔存在或者唔係可完成狀態
        return False
    self.items[item_id]["status"] = "COMPLETED"               # 完成後改新狀態
    self.items[item_id]["expiry"] = None                       # 完成後通常唔再等 TTL
    return True

self.items[item_id]["expiry"] = timestamp + ttl_ms            # Step 1：item 入面加 expiry
self.items[item_id]["status"] = "ACTIVE"                     # Step 2：一開始狀態通常先係 ACTIVE / PENDING
if expired: self.items[item_id]["status"] = "EXPIRED"        # Step 3：F3 常見係 mark status，唔 delete
if state_machine: transition_to_next_status()                 # Step 4：workflow 題照樣係改 status
self._purge(timestamp)                                         # Step 5：每個 public method 開頭先跑 helper

def backup(self, timestamp):                                  # 呢個 family 要影 4 份 state；唔係淨係 items 咁簡單
    self._purge(timestamp)                                    # 影相前先判晒邊啲 item 已過期
    snap_groups = copy.deepcopy(self.groups)                  # groups 係第一層大設定
    snap_items = {}                                           # items 要自己逐件轉成 backup-friendly 形狀
    for item_id, info in self.items.items():
        remaining = None                                      # 預設永久 item 冇 remaining ttl
        if info["expiry"] is not None:
            remaining = info["expiry"] - timestamp            # 有期限就轉成剩餘壽命
        snap_items[item_id] = {
            "group_id": info["group_id"],
            "other_id": info["other_id"],
            "data": info["data"],
            "status": info["status"],                         # status 都要影埋；restore 後先知當時係 ACTIVE 定 CLEARED
            "remaining_ttl": remaining,
        }
    snap_history = copy.deepcopy(dict(self.history))          # history 亦都係系統 state，一樣要凍結落相
    self.backups.append((timestamp, snap_groups, snap_items, snap_history))

def restore(self, timestamp, target_ts):                     # 將 group / item / history 一次過倒帶
    best = None
    for entry in self.backups:
        if entry[0] <= target_ts:                            # 只揀 target_ts 或之前嗰啲舊相
            best = entry
    if best is None:
        return False
    backup_ts, snap_groups, snap_items, snap_history = best
    self.groups = copy.deepcopy(snap_groups)                 # 先還原 groups
    self.items = {}                                          # items 要逐件重建，因為要重算 expiry
    for item_id, info in snap_items.items():
        new_expiry = None
        if info["remaining_ttl"] is not None:
            new_expiry = timestamp + info["remaining_ttl"]   # 由「而家」重新起錶
        self.items[item_id] = {
            "group_id": info["group_id"],
            "other_id": info["other_id"],
            "data": info["data"],
            "status": info["status"],
            "expiry": new_expiry,
        }
    self.history = defaultdict(list)                         # history 先重開一個乾淨 defaultdict
    for k, v in snap_history.items():
        self.history[k] = list(v)                            # 再將每條歷史帶抄返入去
    return True

def get_history(self, timestamp, group_id):                  # 查呢個 group 底下曾經出現過咩 item
    return list(self.history.get(group_id, []))              # 即使冇都回空 list copy；caller 好處理啲

def merge_group(self, timestamp, from_id, to_id):            # 將一堆 item 由舊 group 集體搬倉去新 group
    self._purge(timestamp)                                    # 合併前先判死；免得搬埋過期屍體
    if from_id not in self.groups or to_id not in self.groups or from_id == to_id:
        return False
    for item_id, item in self.items.items():                  # 巡所有 item
        if item["group_id"] == from_id:                       # 凡係舊 group 旗下嘅，都要改戶籍
            item["group_id"] = to_id
    self.merged_groups[from_id] = to_id                       # 記低舊 group 去咗邊
    del self.groups[from_id]                                  # 舊 group 本體正式除名
    return True

def transfer_item(self, timestamp, item_id, new_other_id):    # reassign variant：唔改 group，只改另一條關係線
    if item_id not in self.items:                              # item 唔存在
        return False
    self.items[item_id]["other_id"] = new_other_id            # 直接改 owner / entity / operator
    return True

def rollback_item(self, timestamp, item_id):                  # rollback variant：將 completed / failed 退返去 pending
    if item_id not in self.items:                              # item 唔存在
        return False
    if self.items[item_id]["status"] not in {"COMPLETED", "FAILED"}:  # 唔係可 rollback 狀態
        return False
    self.items[item_id]["status"] = "PENDING"                # 退返去待處理
    return True

snapshot = (groups, items, history)                           # Step 1：先列清楚 L4 要凍結邊幾份 state
remaining_ttl = expiry - timestamp                            # Step 2：item 有 TTL 就轉 remaining_ttl
self.merged_groups[from_id] = to_id                           # Step 3：merge 一定記 mapping
self.items[item_id]["group_id"] = to_id                       # Step 4：merge 改 group_id
self.items[item_id]["other_id"] = new_other_id                # Step 5：transfer/reassign 改 other_id

async def batch(self, timestamp, operations):                 # 一次過處理好多 create / clear / transfer 類指令
    self._purge(timestamp)                                    # batch 前先將到鐘 item 判做 EXPIRED

    async def execute_op(op):                                 # 每張單自己跑一條 async 線
        if op["type"] == "transfer":                          # 呢類係改擁有權 / 關係線；一次掂兩個 other_id
            keys = sorted([op["from_other"], op["to_other"]]) # 一律排好先鎖；避免 A 等 B、B 等 A 卡死
            async with self.locks[keys[0]]:
                async with self.locks[keys[1]]:
                    item = self.items.get(op["item_id"])      # 攞返件真正要搬關係嘅 item
                    if not item:
                        return False
                    item["other_id"] = op["to_other"]         # 將 item 由舊 owner 改掛去新 owner
                    return True

        item_id = op.get("item_id", "")                       # 其餘 op 通常只掂一件 item
        async with self.locks[item_id]:                       # 一件一把鎖；避免同時被 clear / update / create 衝撞
            if op["type"] == "create":
                return self.create_item(timestamp, op["group_id"], op["item_id"], op["other_id"], op["data"])
            if op["type"] == "clear":
                return self.clear_item(timestamp, op["item_id"])
        return None

    tasks = [execute_op(op) for op in operations]             # 將所有單轉成 coroutine
    results = await asyncio.gather(*tasks)                    # 一齊跑，再一齊收單
    return list(results)

async def batch_resolve(self, timestamp, item_ids):           # resolve-only batch variant：全部都係單 item op
    async def do_one(item_id):
        async with self.locks[item_id]:                       # item_id scope
            return self.clear_item(timestamp, item_id)
    return list(await asyncio.gather(*(do_one(item_id) for item_id in item_ids)))

async def batch_transfer(self, timestamp, transfers):         # transfer-only variant：全部都係雙 other_id op
    async def do_one(transfer):
        keys = sorted([transfer["from_other"], transfer["to_other"]])  # pair-lock 順序統一
        async with self.locks[keys[0]]:
            async with self.locks[keys[1]]:
                return self.transfer_item(timestamp, transfer["item_id"], transfer["to_other"])
    return list(await asyncio.gather(*(do_one(t) for t in transfers)))

scope = item_or_other_relation(op)                            # Step 1：先判斷 shared state scope
if single_item_scope: async_with_lock(item_id)               # Step 2：單 item op 用一把 lock
if pair_other_scope: keys = sorted([from_other, to_other])   # Step 3：雙 other relationship 用 sorted pair-lock
reuse_old_sync_method_inside_lock()                          # Step 4：lock 入面盡量 call 舊邏輯
return list(await asyncio.gather(*tasks))                    # Step 5：最後 gather 回結果

async def report(self, timestamp, item_ids, max_concurrent):  # 將一批 still-active item 推出去 report / send / sync
    self._purge(timestamp)                                    # 出發前先將過期嗰堆轉做 EXPIRED
    sem = asyncio.Semaphore(max_concurrent)                   # 外部渠道只容納同時 N 個 request

    async def do_one(item_id):                                # 每件 item 自己一條外發線
        if item_id not in self.items:                         # 連 item 都唔存在
            return False                                      # fail-fast：未出門已經知道失敗
        if self.items[item_id]["status"] != "ACTIVE":        # 已 clear / expired / reported 嘅都唔應再送
            return False
        async with sem:                                       # 真正輪到佢先佔用外部管道
            await asyncio.sleep(0.01)                         # 模擬 external reporting call
            self.items[item_id]["status"] = "REPORTED"       # 成功送出後，喺本地即刻改 status 留底
        return True

    tasks = [do_one(item_id) for item_id in item_ids]         # 每件 item 一齊排隊
    results = await asyncio.gather(*tasks)                    # 等晒全部外發結果
    return list(results)

async def send_decisions(self, timestamp, item_ids, max_concurrent):  # decision variant：只送 RESOLVED 嗰堆
    sem = asyncio.Semaphore(max_concurrent)                   # 外部閘口
    async def do_one(item_id):
        item = self.items.get(item_id)                        # flat item lookup
        if item is None or item["status"] != "RESOLVED":     # fail-fast：未 resolve 唔送得
            return False
        async with sem:
            await asyncio.sleep(0.01)                         # 模擬 send decision
        item["status"] = "SENT"                              # 成功後 mark SENT
        return True
    return list(await asyncio.gather(*(do_one(item_id) for item_id in item_ids)))

async def sync_group_items(self, timestamp, group_id, max_concurrent):  # group-scoped variant：由某個 group 揀出 live items 去 sync
    sem = asyncio.Semaphore(max_concurrent)
    async def do_one(item_id):
        item = self.items[item_id]
        if item["group_id"] != group_id or item["status"] != "ACTIVE":  # 唔屬於該 group 或唔 active
            return False
        async with sem:
            await asyncio.sleep(0.01)
        item["status"] = "SYNCED"
        return True
    ids = sorted(self.items.keys())                           # 先有 deterministic 順序
    return list(await asyncio.gather(*(do_one(item_id) for item_id in ids)))

sem = asyncio.Semaphore(max_concurrent)                       # Step 1：function 入面先開 sem
item = self.items.get(item_id)                               # Step 2：先做 item existence check
if item is None or item["status"] not in allowed_statuses: return False  # Step 3：status fail-fast
async with sem: await asyncio.sleep(0.01)                     # Step 4：過關先做 external work
item["status"] = next_status                                 # Step 5：成功後 mark REPORTED / SENT / SYNCED

import copy
import asyncio
from collections import defaultdict

class SignalProcessingPipeline:
    def __init__(self):
        self.channels = {}
        self.backups = []
        self.locks = defaultdict(asyncio.Lock)

def create_channel(self, timestamp, channel_id, max_signals):
    if channel_id in self.channels:
        return False
    self.channels[channel_id] = {
        "max_signals": max_signals,
        "signals": {},
        "history": [],
    }
    return True

def inject_signal(self, timestamp, channel_id, signal_id, strength):
    if channel_id not in self.channels:
        return False
    channel = self.channels[channel_id]                       # 拎住呢條 channel
    if signal_id in channel["signals"]:
        return False                                          # 同名 signal 唔再插第二次
    if len(channel["signals"]) >= channel["max_signals"]:
        return False                                          # 條 channel 已經滿 signal
    channel["signals"][signal_id] = {
        "strength": strength,
        "created_at": timestamp,
        "expiry": None,
    }
    channel["history"].append(signal_id)                      # 記低曾經入過嚟
    return True

def drop_signal(self, timestamp, channel_id, signal_id):
    if channel_id not in self.channels:
        return False
    channel = self.channels[channel_id]
    if signal_id not in channel["signals"]:
        return False
    del channel["signals"][signal_id]                         # 由 channel 入面拎走呢粒 signal
    return True

def read_channel(self, timestamp, channel_id):
    if channel_id not in self.channels:
        return None
    return {sid: dict(sig) for sid, sig in self.channels[channel_id]["signals"].items()}

def strongest_channels(self, timestamp, n):
    scored = []
    for channel_id, channel in self.channels.items():
        total = sum(sig["strength"] for sig in channel["signals"].values())   # 將成條 channel 嘅 signal 力量加埋
        scored.append((total, channel_id))
    scored.sort(key=lambda x: (-x[0], x[1]))
    return [channel_id for total, channel_id in scored[:n]]

def find_signal(self, timestamp, signal_id):
    for channel_id, channel in self.channels.items():                          # 因為 signal_id 唔係外層 key，要行晒全部 channel 搵
        if signal_id in channel["signals"]:
            return channel_id
    return None

def _purge_expired_signals(self, timestamp):
    for channel in self.channels.values():
        dead = []
        for signal_id, signal in channel["signals"].items():
            if signal["expiry"] is not None and timestamp >= signal["expiry"]:
                dead.append(signal_id)                                         # 到期 signal 先收集，唔好一路 loop 一路 del
        for signal_id in dead:
            del channel["signals"][signal_id]

def inject_signal_with_ttl(self, timestamp, channel_id, signal_id, strength, ttl_ms):
    self._purge_expired_signals(timestamp)                                     # 每個 public method 開頭先掃一次 expiry
    if not self.inject_signal(timestamp, channel_id, signal_id, strength):
        return False
    self.channels[channel_id]["signals"][signal_id]["expiry"] = timestamp + ttl_ms
    return True

def get_signal_age(self, timestamp, channel_id, signal_id):
    self._purge_expired_signals(timestamp)
    if channel_id not in self.channels:
        return None
    signal = self.channels[channel_id]["signals"].get(signal_id)
    if signal is None:
        return None
    return timestamp - signal["created_at"]

def backup(self, timestamp):
    self._purge_expired_signals(timestamp)
    snapshot = {}
    for channel_id, channel in self.channels.items():
        snapshot[channel_id] = {
            "max_signals": channel["max_signals"],
            "signals": {},
            "history": list(channel["history"]),
        }
        for signal_id, signal in channel["signals"].items():
            remaining_ttl = None
            if signal["expiry"] is not None:
                remaining_ttl = signal["expiry"] - timestamp
            snapshot[channel_id]["signals"][signal_id] = {
                "strength": signal["strength"],
                "created_at": signal["created_at"],
                "remaining_ttl": remaining_ttl,
            }
    self.backups.append((timestamp, snapshot))
    return str(len(snapshot))

def restore(self, timestamp, restore_timestamp):
    self._purge_expired_signals(timestamp)
    candidate = None
    for ts, snapshot in self.backups:
        if ts <= restore_timestamp:
            candidate = snapshot
    if candidate is None:
        return False
    self.channels = copy.deepcopy(candidate)
    for channel in self.channels.values():
        for signal in channel["signals"].values():
            remaining_ttl = signal.pop("remaining_ttl")
            signal["expiry"] = None if remaining_ttl is None else timestamp + remaining_ttl
    return True

def get_signal_history(self, timestamp, channel_id):
    self._purge_expired_signals(timestamp)
    if channel_id not in self.channels:
        return None
    return list(self.channels[channel_id]["history"])

async def batch_operations(self, timestamp, ops):
    self._purge_expired_signals(timestamp)
    async def execute_op(op):
        if op["type"] in {"inject", "drop"}:
            channel_id = op["channel_id"]
            async with self.locks[channel_id]:                                  # 單 channel op 鎖一把
                if op["type"] == "inject":
                    return self.inject_signal(timestamp, channel_id, op["signal_id"], op["strength"])
                return self.drop_signal(timestamp, channel_id, op["signal_id"])

        first, second = sorted([op["from_channel_id"], op["to_channel_id"]])   # transfer_signal 會同時郁兩條 channel
        async with self.locks[first]:
            async with self.locks[second]:
                from_channel = self.channels.get(op["from_channel_id"])
                to_channel = self.channels.get(op["to_channel_id"])
                if from_channel is None or to_channel is None:
                    return False
                signal = from_channel["signals"].pop(op["signal_id"], None)
                if signal is None:
                    return False
                to_channel["signals"][op["signal_id"]] = signal
                to_channel["history"].append(op["signal_id"])
                return True

    return list(await asyncio.gather(*(execute_op(op) for op in ops)))

async def sync_channels(self, timestamp, channel_ids, max_concurrent):
    self._purge_expired_signals(timestamp)
    sem = asyncio.Semaphore(max_concurrent)

    async def do_one(channel_id):
        if channel_id not in self.channels:
            return False                                                       # channel 唔存在即刻 fail，唔好入 sem
        async with sem:
            await asyncio.sleep(0.01)                                          # 模擬真 external sync
        self.channels[channel_id]["history"].append(f"sync@{timestamp}")
        return True

    return list(await asyncio.gather(*(do_one(channel_id) for channel_id in channel_ids)))

import copy
import asyncio
from collections import defaultdict

class ResourceAllocationController:
    def __init__(self):
        self.pools = {}
        self.backups = []
        self.locks = defaultdict(asyncio.Lock)

def create_pool(self, timestamp, pool_id, max_units):
    if pool_id in self.pools:
        return False
    self.pools[pool_id] = {"max_units": max_units, "jobs": {}, "history": []}
    return True

def claim_unit(self, timestamp, pool_id, job_id, unit_count):
    if pool_id not in self.pools:
        return False
    pool = self.pools[pool_id]
    if job_id in pool["jobs"]:
        return False
    used = sum(job["units"] for job in pool["jobs"].values())                  # 呢個 pool 已經俾咗幾多單位出去
    if used + unit_count > pool["max_units"]:
        return False
    pool["jobs"][job_id] = {"units": unit_count, "claimed_at": timestamp, "expiry": None}
    pool["history"].append(job_id)
    return True

def release(self, timestamp, pool_id, job_id):
    if pool_id not in self.pools:
        return False
    return self.pools[pool_id]["jobs"].pop(job_id, None) is not None

def get_utilization(self, timestamp, pool_id):
    if pool_id not in self.pools:
        return None
    pool = self.pools[pool_id]
    used = sum(job["units"] for job in pool["jobs"].values())
    return used / pool["max_units"]

def get_job_claims(self, timestamp, job_id):
    result = []
    for pool_id, pool in self.pools.items():                                   # job_id 唔係外層 key，要行晒全部 pool
        if job_id in pool["jobs"]:
            result.append(pool_id)
    return sorted(result)

def top_pools_by_utilization(self, timestamp, n):
    rows = []
    for pool_id in self.pools:
        rows.append((self.get_utilization(timestamp, pool_id), pool_id))
    rows.sort(key=lambda x: (-x[0], x[1]))
    return [pool_id for _, pool_id in rows[:n]]

def _purge_expired_claims(self, timestamp):
    for pool in self.pools.values():
        dead = []
        for job_id, claim in pool["jobs"].items():
            if claim["expiry"] is not None and timestamp >= claim["expiry"]:
                dead.append(job_id)
        for job_id in dead:
            del pool["jobs"][job_id]                                           # claim 到期就自動 release

def claim_unit_with_ttl(self, timestamp, pool_id, job_id, unit_count, ttl_ms):
    self._purge_expired_claims(timestamp)
    if not self.claim_unit(timestamp, pool_id, job_id, unit_count):
        return False
    self.pools[pool_id]["jobs"][job_id]["expiry"] = timestamp + ttl_ms
    return True

def backup(self, timestamp):
    self._purge_expired_claims(timestamp)
    snapshot = {}
    for pool_id, pool in self.pools.items():
        snapshot[pool_id] = {"max_units": pool["max_units"], "jobs": {}, "history": list(pool["history"])}
        for job_id, claim in pool["jobs"].items():
            remaining_ttl = None if claim["expiry"] is None else claim["expiry"] - timestamp
            snapshot[pool_id]["jobs"][job_id] = {
                "units": claim["units"],
                "claimed_at": claim["claimed_at"],
                "remaining_ttl": remaining_ttl,
            }
    self.backups.append((timestamp, snapshot))
    return str(len(snapshot))

def restore(self, timestamp, restore_timestamp):
    self._purge_expired_claims(timestamp)
    candidate = None
    for ts, snapshot in self.backups:
        if ts <= restore_timestamp:
            candidate = snapshot
    if candidate is None:
        return False
    self.pools = copy.deepcopy(candidate)
    for pool in self.pools.values():
        for claim in pool["jobs"].values():
            remaining_ttl = claim.pop("remaining_ttl")
            claim["expiry"] = None if remaining_ttl is None else timestamp + remaining_ttl
    return True

def get_claim_history(self, timestamp, pool_id):
    self._purge_expired_claims(timestamp)
    if pool_id not in self.pools:
        return None
    return list(self.pools[pool_id]["history"])

async def batch_claims(self, timestamp, ops):
    self._purge_expired_claims(timestamp)
    async def execute_op(op):
        if op["type"] in {"claim", "release"}:
            pool_id = op["pool_id"]
            async with self.locks[pool_id]:
                if op["type"] == "claim":
                    return self.claim_unit(timestamp, pool_id, op["job_id"], op["unit_count"])
                return self.release(timestamp, pool_id, op["job_id"])

        first, second = sorted([op["from_pool_id"], op["to_pool_id"]])
        async with self.locks[first]:
            async with self.locks[second]:
                source = self.pools.get(op["from_pool_id"])
                target = self.pools.get(op["to_pool_id"])
                if source is None or target is None:
                    return False
                claim = source["jobs"].pop(op["job_id"], None)
                if claim is None:
                    return False
                target["jobs"][op["job_id"]] = claim
                target["history"].append(op["job_id"])
                return True

    return list(await asyncio.gather(*(execute_op(op) for op in ops)))

async def sync_pools(self, timestamp, pool_ids, max_concurrent):
    self._purge_expired_claims(timestamp)
    sem = asyncio.Semaphore(max_concurrent)

    async def do_one(pool_id):
        if pool_id not in self.pools:
            return False
        async with sem:
            await asyncio.sleep(0.01)
        self.pools[pool_id]["history"].append(f"sync@{timestamp}")
        return True

    return list(await asyncio.gather(*(do_one(pool_id) for pool_id in pool_ids)))

import copy
import asyncio
from collections import defaultdict

class CapacityReservationBroker:
    def __init__(self):
        self.zones = {}
        self.backups = []
        self.merged_zones = {}
        self.locks = defaultdict(asyncio.Lock)

def create_zone(self, timestamp, zone_id, total_slots):
    if zone_id in self.zones:
        return False
    self.zones[zone_id] = {"total_slots": total_slots, "tenants": {}, "history": []}
    return True

def reserve(self, timestamp, zone_id, tenant_id, slot_count):
    if zone_id not in self.zones:
        return False
    zone = self.zones[zone_id]
    if tenant_id in zone["tenants"]:
        return False
    used = sum(item["slots"] for item in zone["tenants"].values())
    if used + slot_count > zone["total_slots"]:
        return False
    zone["tenants"][tenant_id] = {"slots": slot_count, "reserved_at": timestamp, "expiry": None}
    zone["history"].append(tenant_id)
    return True

def release(self, timestamp, zone_id, tenant_id):
    if zone_id not in self.zones:
        return False
    return self.zones[zone_id]["tenants"].pop(tenant_id, None) is not None

def get_remaining(self, timestamp, zone_id):
    if zone_id not in self.zones:
        return None
    zone = self.zones[zone_id]
    used = sum(item["slots"] for item in zone["tenants"].values())
    return zone["total_slots"] - used

def get_tenant_zones(self, timestamp, tenant_id):
    result = []
    for zone_id, zone in self.zones.items():
        if tenant_id in zone["tenants"]:
            result.append(zone_id)
    return sorted(result)

def get_busiest_zones(self, timestamp, n):
    rows = []
    for zone_id, zone in self.zones.items():
        used = sum(item["slots"] for item in zone["tenants"].values())
        rows.append((used, zone_id))
    rows.sort(key=lambda x: (-x[0], x[1]))
    return [zone_id for _, zone_id in rows[:n]]

def _purge_expired_reservations(self, timestamp):
    for zone in self.zones.values():
        dead = []
        for tenant_id, item in zone["tenants"].items():
            if item["expiry"] is not None and timestamp >= item["expiry"]:
                dead.append(tenant_id)
        for tenant_id in dead:
            del zone["tenants"][tenant_id]

def reserve_with_ttl(self, timestamp, zone_id, tenant_id, slot_count, ttl_ms):
    self._purge_expired_reservations(timestamp)
    if not self.reserve(timestamp, zone_id, tenant_id, slot_count):
        return False
    self.zones[zone_id]["tenants"][tenant_id]["expiry"] = timestamp + ttl_ms
    return True

def extend(self, timestamp, zone_id, tenant_id, extra_ms):
    self._purge_expired_reservations(timestamp)
    tenant = self.zones.get(zone_id, {}).get("tenants", {}).get(tenant_id)
    if tenant is None or tenant["expiry"] is None:
        return False
    tenant["expiry"] += extra_ms
    return True

def backup(self, timestamp):
    self._purge_expired_reservations(timestamp)
    snapshot = {}
    for zone_id, zone in self.zones.items():
        snapshot[zone_id] = {"total_slots": zone["total_slots"], "tenants": {}, "history": list(zone["history"])}
        for tenant_id, item in zone["tenants"].items():
            remaining_ttl = None if item["expiry"] is None else item["expiry"] - timestamp
            snapshot[zone_id]["tenants"][tenant_id] = {
                "slots": item["slots"],
                "reserved_at": item["reserved_at"],
                "remaining_ttl": remaining_ttl,
            }
    self.backups.append((timestamp, snapshot))
    return str(len(snapshot))

def restore(self, timestamp, restore_timestamp):
    self._purge_expired_reservations(timestamp)
    candidate = None
    for ts, snapshot in self.backups:
        if ts <= restore_timestamp:
            candidate = snapshot
    if candidate is None:
        return False
    self.zones = copy.deepcopy(candidate)
    for zone in self.zones.values():
        for tenant in zone["tenants"].values():
            remaining_ttl = tenant.pop("remaining_ttl")
            tenant["expiry"] = None if remaining_ttl is None else timestamp + remaining_ttl
    return True

def get_reservation_history(self, timestamp, zone_id):
    self._purge_expired_reservations(timestamp)
    if zone_id not in self.zones:
        return None
    return list(self.zones[zone_id]["history"])

def merge_zone(self, timestamp, from_zone_id, to_zone_id):
    self._purge_expired_reservations(timestamp)
    if from_zone_id not in self.zones or to_zone_id not in self.zones:
        return False
    source = self.zones[from_zone_id]
    target = self.zones[to_zone_id]
    for tenant_id, item in source["tenants"].items():
        target["tenants"][tenant_id] = item
        target["history"].append(tenant_id)
    target["total_slots"] += source["total_slots"]
    del self.zones[from_zone_id]
    self.merged_zones[from_zone_id] = to_zone_id
    return True

async def batch_reservations(self, timestamp, ops):
    self._purge_expired_reservations(timestamp)
    async def execute_op(op):
        if op["type"] in {"reserve", "release"}:
            zone_id = op["zone_id"]
            async with self.locks[zone_id]:
                if op["type"] == "reserve":
                    return self.reserve(timestamp, zone_id, op["tenant_id"], op["slot_count"])
                return self.release(timestamp, zone_id, op["tenant_id"])

        first, second = sorted([op["from_zone_id"], op["to_zone_id"]])
        async with self.locks[first]:
            async with self.locks[second]:
                return self.merge_zone(timestamp, op["from_zone_id"], op["to_zone_id"])

    return list(await asyncio.gather(*(execute_op(op) for op in ops)))

async def sync_zones(self, timestamp, zone_ids, max_concurrent):
    self._purge_expired_reservations(timestamp)
    sem = asyncio.Semaphore(max_concurrent)

    async def do_one(zone_id):
        if zone_id not in self.zones:
            return False
        async with sem:
            await asyncio.sleep(0.01)
        self.zones[zone_id]["history"].append(f"sync@{timestamp}")
        return True

    return list(await asyncio.gather(*(do_one(zone_id) for zone_id in zone_ids)))

import copy
import asyncio
from collections import defaultdict

class RecipeManager:
    def __init__(self):
        self.recipes = {}
        self.backups = []
        self.locks = defaultdict(asyncio.Lock)

def create_recipe(self, timestamp, recipe_id, chef_id, cook_time):
    if recipe_id in self.recipes:
        return False
    self.recipes[recipe_id] = {
        "chef_id": chef_id,
        "cook_time": cook_time,
        "ingredients": {},
        "history": [],
    }
    return True

def add_ingredient(self, timestamp, recipe_id, ingredient_name, qty):
    if recipe_id not in self.recipes:
        return False
    recipe = self.recipes[recipe_id]
    if ingredient_name in recipe["ingredients"]:
        return False
    recipe["ingredients"][ingredient_name] = {"qty": qty, "expiry": None}
    recipe["history"].append(ingredient_name)
    return True

def remove_ingredient(self, timestamp, recipe_id, ingredient_name):
    if recipe_id not in self.recipes:
        return False
    return self.recipes[recipe_id]["ingredients"].pop(ingredient_name, None) is not None

def get_recipe(self, timestamp, recipe_id):
    if recipe_id not in self.recipes:
        return None
    return copy.deepcopy(self.recipes[recipe_id])

def search_recipes_by_ingredient(self, timestamp, ingredient_name):
    result = []
    for recipe_id, recipe in self.recipes.items():
        if ingredient_name in recipe["ingredients"]:
            result.append(recipe_id)
    return sorted(result)

def top_recipes_by_ingredient_count(self, timestamp, n):
    rows = []
    for recipe_id, recipe in self.recipes.items():
        rows.append((len(recipe["ingredients"]), recipe_id))
    rows.sort(key=lambda x: (-x[0], x[1]))
    return [recipe_id for _, recipe_id in rows[:n]]

def get_chef_recipes(self, timestamp, chef_id):
    return sorted([recipe_id for recipe_id, recipe in self.recipes.items() if recipe["chef_id"] == chef_id])

def _purge_expired_ingredients(self, timestamp):
    for recipe in self.recipes.values():
        dead = []
        for ingredient_name, ingredient in recipe["ingredients"].items():
            if ingredient["expiry"] is not None and timestamp >= ingredient["expiry"]:
                dead.append(ingredient_name)
        for ingredient_name in dead:
            del recipe["ingredients"][ingredient_name]                         # 到期即當呢樣材料用晒 / 壞咗

def add_ingredient_with_ttl(self, timestamp, recipe_id, ingredient_name, qty, ttl_ms):
    self._purge_expired_ingredients(timestamp)
    if not self.add_ingredient(timestamp, recipe_id, ingredient_name, qty):
        return False
    self.recipes[recipe_id]["ingredients"][ingredient_name]["expiry"] = timestamp + ttl_ms
    return True

def get_recipe_history(self, timestamp, recipe_id):
    self._purge_expired_ingredients(timestamp)
    if recipe_id not in self.recipes:
        return None
    return list(self.recipes[recipe_id]["history"])

def backup(self, timestamp):
    self._purge_expired_ingredients(timestamp)
    snapshot = {}
    for recipe_id, recipe in self.recipes.items():
        snapshot[recipe_id] = {
            "chef_id": recipe["chef_id"],
            "cook_time": recipe["cook_time"],
            "ingredients": {},
            "history": list(recipe["history"]),
        }
        for ingredient_name, ingredient in recipe["ingredients"].items():
            remaining_ttl = None if ingredient["expiry"] is None else ingredient["expiry"] - timestamp
            snapshot[recipe_id]["ingredients"][ingredient_name] = {
                "qty": ingredient["qty"],
                "remaining_ttl": remaining_ttl,
            }
    self.backups.append((timestamp, snapshot))
    return str(len(snapshot))

def restore(self, timestamp, restore_timestamp):
    self._purge_expired_ingredients(timestamp)
    candidate = None
    for ts, snapshot in self.backups:
        if ts <= restore_timestamp:
            candidate = snapshot
    if candidate is None:
        return False
    self.recipes = copy.deepcopy(candidate)
    for recipe in self.recipes.values():
        for ingredient in recipe["ingredients"].values():
            remaining_ttl = ingredient.pop("remaining_ttl")
            ingredient["expiry"] = None if remaining_ttl is None else timestamp + remaining_ttl
    return True

async def batch_ingredients(self, timestamp, ops):
    self._purge_expired_ingredients(timestamp)
    async def execute_op(op):
        recipe_id = op["recipe_id"]
        async with self.locks[recipe_id]:
            if op["type"] == "add":
                return self.add_ingredient(timestamp, recipe_id, op["ingredient_name"], op["qty"])
            if op["type"] == "remove":
                return self.remove_ingredient(timestamp, recipe_id, op["ingredient_name"])
            return False

    return list(await asyncio.gather(*(execute_op(op) for op in ops)))

async def sync_recipes(self, timestamp, recipe_ids, max_concurrent):
    self._purge_expired_ingredients(timestamp)
    sem = asyncio.Semaphore(max_concurrent)

    async def do_one(recipe_id):
        if recipe_id not in self.recipes:
            return False
        async with sem:
            await asyncio.sleep(0.01)
        self.recipes[recipe_id]["history"].append(f"sync@{timestamp}")
        return True

    return list(await asyncio.gather(*(do_one(recipe_id) for recipe_id in recipe_ids)))

import copy
import asyncio
from collections import defaultdict

class ComplianceAuditEngine:
    def __init__(self):
        self.policies = {}
        self.violations = {}
        self.backups = []
        self.merged_entities = {}
        self.history = defaultdict(list)
        self.locks = defaultdict(asyncio.Lock)

def register_policy(self, timestamp, policy_id, description, max_violations):
    if policy_id in self.policies:
        return False
    self.policies[policy_id] = {
        "description": description,
        "max_violations": max_violations,
    }
    return True

def flag_violation(self, timestamp, policy_id, entity_id, violation_id, severity):
    if policy_id not in self.policies or violation_id in self.violations:
        return False
    self.violations[violation_id] = {
        "policy_id": policy_id,
        "entity_id": entity_id,
        "severity": severity,
        "expiry": None,
        "status": "ACTIVE",
    }
    self.history[entity_id].append(violation_id)                              # 呢個 entity 底下又多咗一單 violation
    return True

def clear_violation(self, timestamp, violation_id):
    violation = self.violations.get(violation_id)
    if violation is None or violation["status"] != "ACTIVE":
        return False
    violation["status"] = "CLEARED"
    return True

def get_active_violations(self, timestamp, entity_id):
    return sorted([
        violation_id
        for violation_id, violation in self.violations.items()
        if violation["entity_id"] == entity_id and violation["status"] == "ACTIVE"
    ])

def find_violation(self, timestamp, violation_id):
    violation = self.violations.get(violation_id)
    if violation is None:
        return None
    return dict(violation)

def get_worst_entities(self, timestamp, n):
    counts = defaultdict(int)
    for violation in self.violations.values():                                # 因為 entity 唔係外層 key，要行 violations 聚合
        if violation["status"] == "ACTIVE":
            counts[violation["entity_id"]] += 1
    rows = [(count, entity_id) for entity_id, count in counts.items()]
    rows.sort(key=lambda x: (-x[0], x[1]))
    return [entity_id for _, entity_id in rows[:n]]

def _purge_expired_violations(self, timestamp):
    for violation in self.violations.values():
        if violation["expiry"] is not None and timestamp >= violation["expiry"] and violation["status"] == "ACTIVE":
            violation["status"] = "EXPIRED"                                   # 呢題唔一定 del；有時只係轉 status 方便留 history

def flag_violation_with_ttl(self, timestamp, policy_id, entity_id, violation_id, severity, ttl_ms):
    self._purge_expired_violations(timestamp)
    if not self.flag_violation(timestamp, policy_id, entity_id, violation_id, severity):
        return False
    self.violations[violation_id]["expiry"] = timestamp + ttl_ms
    return True

def backup(self, timestamp):                                                  # 影低 policies + violations + history + merge map
    snapshot = {                                                              # 開一份完整 snapshot
        "policies": copy.deepcopy(self.policies),                             # A dict 直接 deepcopy
        "violations": {},                                                     # B dict 要逐條轉 TTL
        "history": copy.deepcopy(dict(self.history)),                         # defaultdict 先轉普通 dict 影相
        "merged_entities": copy.deepcopy(self.merged_entities),               # merge 對照表都要跟住 backup
    }
    for violation_id, violation in self.violations.items():                   # 逐條 violation 砌 snapshot 版
        item = dict(violation)                                                # 淺 copy 一份先
        if item["expiry"] is not None:                                        # 有 TTL 先轉 remaining_ttl
            item["remaining_ttl"] = item["expiry"] - timestamp
        else:
            item["remaining_ttl"] = None                                      # 永久單就記 None
        item.pop("expiry", None)                                              # snapshot 唔留絕對時間
        snapshot["violations"][violation_id] = item                           # 放返入 snapshot
    self.backups.append((timestamp, snapshot))                                # (ts, snapshot) 入 backups list
    return str(len(snapshot["violations"]))                                   # 返今次影咗幾多條 violation

def restore(self, timestamp, restore_timestamp):                              # 還原到某個時間點之前最近嗰張相
    candidate = None                                                          # 暫時未揀中 snapshot
    for ts, snapshot in self.backups:                                         # 逐張 backup 睇
        if ts <= restore_timestamp:                                           # 合資格先可做候選
            candidate = snapshot                                              # 越後面越新，所以直接覆蓋
    if candidate is None:
        return False                                                          # 一張都冇 → restore 失敗
    self.policies = copy.deepcopy(candidate["policies"])                      # A dict 直接抄返
    self.violations = {}                                                      # B dict 重新逐條建返
    for violation_id, item in candidate["violations"].items():                # remaining_ttl 要轉返 expiry
        row = dict(item)                                                      # 先 copy 一份 snapshot row
        remaining_ttl = row.pop("remaining_ttl", None)                        # 攞返剩餘 TTL
        row["expiry"] = None if remaining_ttl is None else timestamp + remaining_ttl  # restore 當刻重新計 expiry
        self.violations[violation_id] = row                                   # 寫返 live violations
    self.history = defaultdict(list, copy.deepcopy(candidate["history"]))     # history 都還原返
    self.merged_entities = copy.deepcopy(candidate["merged_entities"])         # merge map 一齊還原
    return True                                                               # restore 成功

def get_violation_history(self, timestamp, entity_id):                        # 睇某個 entity 歷來中過咩 violation
    return list(self.history.get(entity_id, []))                              # copy 一份 list 返出去

def merge_entity(self, timestamp, from_entity_id, to_entity_id):              # 將舊 entity 併入新 entity
    for violation in self.violations.values():                                # 掃 violations，改晒 owner
        if violation["entity_id"] == from_entity_id:
            violation["entity_id"] = to_entity_id
    self.history[to_entity_id].extend(self.history.get(from_entity_id, []))   # 舊歷史搬去新 entity
    self.history.pop(from_entity_id, None)                                    # 舊 entity history 刪走
    self.merged_entities[from_entity_id] = to_entity_id                       # 留底 merge path 方便追查
    return True

async def batch_audit(self, timestamp, ops):
    async def execute_op(op):
        if op["type"] in {"flag", "clear"}:
            key = op["violation_id"]                                          # 單 violation op 鎖 violation_id
            async with self.locks[key]:
                if op["type"] == "flag":
                    return self.flag_violation(timestamp, op["policy_id"], op["entity_id"], op["violation_id"], op["severity"])
                return self.clear_violation(timestamp, op["violation_id"])

        first, second = sorted([op["from_entity_id"], op["to_entity_id"]])    # move / transfer 會同時郁兩個 entity
        async with self.locks[first]:
            async with self.locks[second]:
                violation = self.violations.get(op["violation_id"])
                if violation is None or violation["entity_id"] != op["from_entity_id"]:
                    return False
                violation["entity_id"] = op["to_entity_id"]
                self.history[op["to_entity_id"]].append(op["violation_id"])
                return True

    return list(await asyncio.gather(*(execute_op(op) for op in ops)))

async def report_violations(self, timestamp, violation_ids, max_concurrent):
    sem = asyncio.Semaphore(max_concurrent)

    async def do_one(violation_id):
        violation = self.violations.get(violation_id)
        if violation is None or violation["status"] != "ACTIVE":
            return False
        async with sem:
            await asyncio.sleep(0.01)
        violation["status"] = "REPORTED"
        return True

    return list(await asyncio.gather(*(do_one(violation_id) for violation_id in violation_ids)))

import copy
import asyncio
from collections import defaultdict

class ContentModerationPipeline:
    def __init__(self):
        self.queues = {}
        self.reports = {}
        self.backups = []
        self.history = defaultdict(list)
        self.locks = defaultdict(asyncio.Lock)

def create_queue(self, timestamp, queue_id, priority_level):
    if queue_id in self.queues:
        return False
    self.queues[queue_id] = {"priority_level": priority_level}
    return True

def submit_report(self, timestamp, queue_id, report_id, content_id, reason):
    if queue_id not in self.queues or report_id in self.reports:
        return False
    self.reports[report_id] = {
        "queue_id": queue_id,
        "content_id": content_id,
        "moderator_id": None,
        "reason": reason,
        "decision": None,
        "expiry": None,
        "status": "PENDING",
    }
    self.history[content_id].append(report_id)
    return True

def claim_report(self, timestamp, report_id, moderator_id):
    report = self.reports.get(report_id)
    if report is None or report["status"] != "PENDING":
        return False
    report["moderator_id"] = moderator_id
    report["status"] = "CLAIMED"
    return True

def resolve_report(self, timestamp, report_id, decision):
    report = self.reports.get(report_id)
    if report is None or report["status"] not in {"PENDING", "CLAIMED"}:
        return False
    report["decision"] = decision
    report["status"] = "RESOLVED"
    return True

def find_report(self, timestamp, report_id):
    report = self.reports.get(report_id)
    return None if report is None else dict(report)

def get_moderator_workload(self, timestamp, moderator_id):
    return sum(1 for report in self.reports.values() if report["moderator_id"] == moderator_id and report["status"] == "CLAIMED")

def get_busiest_queues(self, timestamp, n):
    counts = defaultdict(int)
    for report in self.reports.values():
        if report["status"] in {"PENDING", "CLAIMED"}:
            counts[report["queue_id"]] += 1
    rows = [(count, queue_id) for queue_id, count in counts.items()]
    rows.sort(key=lambda x: (-x[0], x[1]))
    return [queue_id for _, queue_id in rows[:n]]

def _purge_expired_reports(self, timestamp):
    for report in self.reports.values():
        if report["expiry"] is not None and timestamp >= report["expiry"] and report["status"] == "PENDING":
            report["status"] = "EXPIRED"

def submit_report_with_ttl(self, timestamp, queue_id, report_id, content_id, reason, ttl_ms):
    self._purge_expired_reports(timestamp)
    if not self.submit_report(timestamp, queue_id, report_id, content_id, reason):
        return False
    self.reports[report_id]["expiry"] = timestamp + ttl_ms
    return True

def get_report_age(self, timestamp, report_id):
    report = self.reports.get(report_id)
    if report is None:
        return None
    return None if report["status"] == "EXPIRED" else timestamp

def get_content_history(self, timestamp, content_id):                          # 睇某份 content 被 report 過幾多次
    return list(self.history.get(content_id, []))                              # copy 一份 history list 返出去

def escalate(self, timestamp, report_id, from_queue_id, to_queue_id):         # 將 report 升級去另一條 queue
    report = self.reports.get(report_id)                                       # 先搵條 report
    if report is None or report["queue_id"] != from_queue_id:
        return False                                                           # 唔存在或者唔喺原 queue → fail
    report["queue_id"] = to_queue_id                                           # 改去新 queue
    report["status"] = "ESCALATED"                                             # 標記已升級
    return True

def backup(self, timestamp):                                                   # 影低 queues + reports + history
    snapshot = {"queues": copy.deepcopy(self.queues), "reports": {}, "history": copy.deepcopy(dict(self.history))}
    for report_id, report in self.reports.items():                             # 逐張 report 轉 TTL
        item = dict(report)
        item["remaining_ttl"] = None if item["expiry"] is None else item["expiry"] - timestamp
        item.pop("expiry", None)
        snapshot["reports"][report_id] = item
    self.backups.append((timestamp, snapshot))                                 # 入 backups list
    return str(len(snapshot["reports"]))                                       # 返 snapshot 入面 report 數量

def restore(self, timestamp, restore_timestamp):                               # 還原到某張 backup
    candidate = None                                                           # 暫時未揀中
    for ts, snapshot in self.backups:
        if ts <= restore_timestamp:
            candidate = snapshot                                               # 揀 restore_ts 之前最近嗰張
    if candidate is None:
        return False
    self.queues = copy.deepcopy(candidate["queues"])                           # A dict 直接抄返
    self.reports = {}                                                          # B dict 逐張重建
    for report_id, item in candidate["reports"].items():
        row = dict(item)
        remaining_ttl = row.pop("remaining_ttl", None)                        # 攞返 snapshot 裏面 TTL
        row["expiry"] = None if remaining_ttl is None else timestamp + remaining_ttl
        self.reports[report_id] = row
    self.history = defaultdict(list, copy.deepcopy(candidate["history"]))      # content history 一齊還原
    return True

async def batch_moderate(self, timestamp, ops):
    async def execute_op(op):
        if op["type"] in {"submit", "claim", "resolve"}:
            key = op["report_id"]
            async with self.locks[key]:
                if op["type"] == "submit":
                    return self.submit_report(timestamp, op["queue_id"], op["report_id"], op["content_id"], op["reason"])
                if op["type"] == "claim":
                    return self.claim_report(timestamp, op["report_id"], op["moderator_id"])
                return self.resolve_report(timestamp, op["report_id"], op["decision"])

        first, second = sorted([op["from_queue_id"], op["to_queue_id"]])
        async with self.locks[first]:
            async with self.locks[second]:
                return self.escalate(timestamp, op["report_id"], op["from_queue_id"], op["to_queue_id"])

    return list(await asyncio.gather(*(execute_op(op) for op in ops)))

async def send_decisions(self, timestamp, report_ids, max_concurrent):
    sem = asyncio.Semaphore(max_concurrent)

    async def do_one(report_id):
        report = self.reports.get(report_id)
        if report is None or report["status"] != "RESOLVED":
            return False
        async with sem:
            await asyncio.sleep(0.01)
        report["status"] = "NOTIFIED"
        return True

    return list(await asyncio.gather(*(do_one(report_id) for report_id in report_ids)))

import copy
import asyncio
from collections import defaultdict

class FrequencySpectrumAllocator:
    def __init__(self):
        self.bands = {}
        self.leases = {}
        self.backups = []
        self.locks = defaultdict(asyncio.Lock)

def register_band(self, timestamp, band_id, freq_start, freq_end):
    if band_id in self.bands:
        return False
    self.bands[band_id] = {"freq_start": freq_start, "freq_end": freq_end, "history": []}
    return True

def lease(self, timestamp, band_id, operator_id, lease_id):
    if band_id not in self.bands or lease_id in self.leases:
        return False
    self.leases[lease_id] = {
        "band_id": band_id,
        "operator_id": operator_id,
        "expiry": None,
        "status": "ACTIVE",
    }
    self.bands[band_id]["history"].append(lease_id)
    return True

def revoke(self, timestamp, lease_id):
    lease = self.leases.get(lease_id)
    if lease is None or lease["status"] != "ACTIVE":
        return False
    lease["status"] = "REVOKED"
    return True

def get_band_status(self, timestamp, band_id):
    return sorted([
        lease_id
        for lease_id, lease in self.leases.items()
        if lease["band_id"] == band_id and lease["status"] == "ACTIVE"
    ])

def get_operator_bands(self, timestamp, operator_id):
    rows = []
    for lease in self.leases.values():
        if lease["operator_id"] == operator_id and lease["status"] == "ACTIVE":
            rows.append(lease["band_id"])
    return sorted(rows)

def get_available_bands(self, timestamp):
    leased = {
        lease["band_id"]
        for lease in self.leases.values()
        if lease["status"] == "ACTIVE"
    }
    return sorted([band_id for band_id in self.bands if band_id not in leased])

def _purge_expired_leases(self, timestamp):
    for lease in self.leases.values():
        if lease["expiry"] is not None and timestamp >= lease["expiry"] and lease["status"] == "ACTIVE":
            lease["status"] = "EXPIRED"

def lease_with_ttl(self, timestamp, band_id, operator_id, lease_id, ttl_ms):
    self._purge_expired_leases(timestamp)
    if not self.lease(timestamp, band_id, operator_id, lease_id):
        return False
    self.leases[lease_id]["expiry"] = timestamp + ttl_ms
    return True

def get_remaining_lease(self, timestamp, lease_id):
    lease = self.leases.get(lease_id)
    if lease is None or lease["expiry"] is None:
        return None
    return max(0, lease["expiry"] - timestamp)

def get_lease_history(self, timestamp, band_id):                               # 睇某條 band 歷來租出去過邊啲 lease
    if band_id not in self.bands:
        return None                                                            # band 都冇就答 None
    return list(self.bands[band_id]["history"])                                # copy 一份 history list

def transfer_lease(self, timestamp, lease_id, new_operator_id):               # 將 lease 轉手畀另一個 operator
    lease = self.leases.get(lease_id)                                          # 先搵 lease
    if lease is None or lease["status"] != "ACTIVE":
        return False                                                           # 唔存在或者已失效 → 唔轉得
    lease["operator_id"] = new_operator_id                                     # 真正轉手只係改 operator_id
    return True

def backup(self, timestamp):                                                   # 影低 bands + leases
    snapshot = {"bands": copy.deepcopy(self.bands), "leases": {}}
    for lease_id, lease in self.leases.items():                                # lease TTL 逐張轉 remaining_ttl
        item = dict(lease)
        item["remaining_ttl"] = None if item["expiry"] is None else item["expiry"] - timestamp
        item.pop("expiry", None)
        snapshot["leases"][lease_id] = item
    self.backups.append((timestamp, snapshot))                                 # 入 backups list
    return str(len(snapshot["leases"]))                                        # 回覆 snapshot 包咗幾張 lease

def restore(self, timestamp, restore_timestamp):                               # 還原到某個 snapshot 時刻
    candidate = None                                                           # 暫時未揀中 backup
    for ts, snapshot in self.backups:
        if ts <= restore_timestamp:
            candidate = snapshot                                               # 揀 restore_ts 之前最近嗰張
    if candidate is None:
        return False
    self.bands = copy.deepcopy(candidate["bands"])                             # A dict 直接還原
    self.leases = {}                                                           # B dict 逐張 rebuild
    for lease_id, item in candidate["leases"].items():
        row = dict(item)
        remaining_ttl = row.pop("remaining_ttl", None)                        # 取出 snapshot TTL
        row["expiry"] = None if remaining_ttl is None else timestamp + remaining_ttl
        self.leases[lease_id] = row
    return True

async def batch_ops(self, timestamp, ops):
    async def execute_op(op):
        if op["type"] in {"lease", "revoke"}:
            key = op["lease_id"]
            async with self.locks[key]:
                if op["type"] == "lease":
                    return self.lease(timestamp, op["band_id"], op["operator_id"], op["lease_id"])
                return self.revoke(timestamp, op["lease_id"])

        first, second = sorted([op["from_band_id"], op["to_band_id"]])
        async with self.locks[first]:
            async with self.locks[second]:
                lease = self.leases.get(op["lease_id"])
                if lease is None or lease["band_id"] != op["from_band_id"]:
                    return False
                lease["band_id"] = op["to_band_id"]
                self.bands[op["to_band_id"]]["history"].append(op["lease_id"])
                return True

    return list(await asyncio.gather(*(execute_op(op) for op in ops)))

async def sync_bands(self, timestamp, band_ids, max_concurrent):
    sem = asyncio.Semaphore(max_concurrent)

    async def do_one(band_id):
        if band_id not in self.bands:
            return False
        async with sem:
            await asyncio.sleep(0.01)
        self.bands[band_id]["history"].append(f"sync@{timestamp}")
        return True

    return list(await asyncio.gather(*(do_one(band_id) for band_id in band_ids)))

import asyncio
from collections import defaultdict

class DocumentApprovalWorkflow:
    def __init__(self):
        self.cases = {}                      # case_id -> {"client_name": str, "history": []}
        self.docs = {}                       # doc_id -> {"case_id", "title", "reviewer_id", "status", "expiry"}
        self.backups = []                    # L4 backup list
        self.locks = defaultdict(asyncio.Lock)  # L5 per-doc lock

def create_case(self, timestamp, case_id, client_name):                     # 開新 case
    self._purge(timestamp)                                                  # 開頭先清過期 doc
    if case_id in self.cases:                                               # case_id 已存在就唔開
        return False
    self.cases[case_id] = {"client_name": client_name, "history": []}       # A dict 起 case
    return True

def add_document(self, timestamp, case_id, doc_id, title, ttl_ms=None):    # 加 doc 入 case
    self._purge(timestamp)
    if case_id not in self.cases or doc_id in self.docs:
        return False                                                         # case 唔存在 / doc 重複都唔得
    expiry = timestamp + ttl_ms if ttl_ms is not None else None             # L3：有 ttl_ms 就即場計 expiry
    self.docs[doc_id] = {                                                   # B dict flat 存 doc
        "case_id": case_id,
        "title": title,
        "reviewer_id": None,
        "status": "DRAFT",
        "expiry": expiry,
    }
    self.cases[case_id]["history"].append(f"{timestamp}: {doc_id} added")   # history 跟 case 走
    return True

def assign_reviewer(self, timestamp, doc_id, reviewer_id):                  # 指派 reviewer
    self._purge(timestamp)
    if doc_id not in self.docs:
        return None
    self.docs[doc_id]["reviewer_id"] = reviewer_id                           # 直接改 B dict
    return True

def submit_for_review(self, timestamp, doc_id):                             # DRAFT -> REVIEW
    self._purge(timestamp)
    if doc_id not in self.docs:
        return None
    if self.docs[doc_id]["status"] != "DRAFT":
        return False
    self._set_status(doc_id, "REVIEW", timestamp)                            # 同步記入 case history
    return True

def approve(self, timestamp, doc_id):                                       # REVIEW -> APPROVED
    self._purge(timestamp)
    if doc_id not in self.docs:
        return None
    if self.docs[doc_id]["status"] != "REVIEW":
        return False
    self._set_status(doc_id, "APPROVED", timestamp)
    return True

def reject(self, timestamp, doc_id):                                        # REVIEW -> REJECTED + rollback
    self._purge(timestamp)
    if doc_id not in self.docs:
        return None
    doc = self.docs[doc_id]
    if doc["status"] != "REVIEW":
        return False
    self._set_status(doc_id, "REJECTED", timestamp)                          # 先 reject 自己
    case_id = doc["case_id"]                                                 # 再搵返同一 case
    for other_id, other in self.docs.items():
        if other["case_id"] == case_id and other["status"] == "APPROVED":
            self._set_status(other_id, "DRAFT", timestamp)                   # rollback：批過嘅通通打返草稿
    return True

def get_case_status(self, timestamp, case_id):                               # 數一個 case 入面各 status 幾多份
    self._purge(timestamp)
    if case_id not in self.cases:
        return None
    counts = {}
    for doc in self.docs.values():                                            # entity 唔喺 cases 入面，要掃 B dict 聚合
        if doc["case_id"] == case_id:
            status = doc["status"]
            counts[status] = counts.get(status, 0) + 1
    return counts

def get_reviewer_workload(self, timestamp, reviewer_id):                     # reviewer 手上幾多份 REVIEW doc
    self._purge(timestamp)
    count = 0
    for doc in self.docs.values():
        if doc["reviewer_id"] == reviewer_id and doc["status"] == "REVIEW":
            count += 1
    return count

def _purge(self, timestamp):                                                  # 清走過期 doc
    expired = [
        doc_id for doc_id, doc in self.docs.items()
        if doc["expiry"] is not None and doc["expiry"] <= timestamp
    ]
    for doc_id in expired:
        del self.docs[doc_id]                                                 # 呢題到期係直接 delete，唔係改 status

def add_document(self, timestamp, case_id, doc_id, title, ttl_ms=None):     # L1 method 到 L3 先加 TTL
    self._purge(timestamp)
    if case_id not in self.cases or doc_id in self.docs:
        return False
    expiry = (timestamp + ttl_ms) if ttl_ms is not None else None            # 只有加 doc 嗰陣先寫 expiry
    self.docs[doc_id] = {
        "case_id": case_id,
        "title": title,
        "reviewer_id": None,
        "status": "DRAFT",
        "expiry": expiry,
    }
    return True

def backup(self, timestamp):                                                  # 影低 cases + docs
    self._purge(timestamp)
    cases_snapshot = {
        cid: {"client_name": c["client_name"], "history": list(c["history"])}
        for cid, c in self.cases.items()
    }
    docs_snapshot = {}
    for did, doc in self.docs.items():
        remaining = (doc["expiry"] - timestamp) if doc["expiry"] is not None else None
        docs_snapshot[did] = {
            "case_id": doc["case_id"],
            "title": doc["title"],
            "reviewer_id": doc["reviewer_id"],
            "status": doc["status"],
            "remaining_ttl": remaining,
        }
    self.backups.append({"timestamp": timestamp, "cases": cases_snapshot, "docs": docs_snapshot})
    return True

def restore(self, timestamp, target_ts):                                     # 還原 target_ts 嗰張相
    snap = None
    for backup in self.backups:
        if backup["timestamp"] == target_ts:
            snap = backup
            break
    if snap is None:
        return False
    self.cases = {
        cid: {"client_name": c["client_name"], "history": list(c["history"])}
        for cid, c in snap["cases"].items()
    }
    self.docs = {}
    for did, doc in snap["docs"].items():
        expiry = timestamp + doc["remaining_ttl"] if doc["remaining_ttl"] is not None else None
        self.docs[did] = {
            "case_id": doc["case_id"],
            "title": doc["title"],
            "reviewer_id": doc["reviewer_id"],
            "status": doc["status"],
            "expiry": expiry,
        }
    return True

def get_case_history(self, timestamp, case_id):                              # history 跟 case 走
    self._purge(timestamp)
    if case_id not in self.cases:
        return None
    return list(self.cases[case_id]["history"])

async def batch_ops(self, timestamp, operations):                             # batch 做 add / submit / approve / reject
    results = []
    for op in operations:                                                     # 保持 input 順序
        op_type = op["type"]
        doc_id = op.get("doc_id")
        lock_key = doc_id if doc_id else op.get("case_id", "global")          # add 未必已有 doc，就退返去鎖 case_id
        async with self.locks[lock_key]:                                       # 同一份 doc / case 嘅 op 排隊
            if op_type == "add":
                res = self.add_document(timestamp, op["case_id"], op["doc_id"], op["title"], ttl_ms=op.get("ttl_ms"))
            elif op_type == "submit":
                res = self.submit_for_review(timestamp, doc_id)
            elif op_type == "approve":
                res = self.approve(timestamp, doc_id)
            elif op_type == "reject":
                res = self.reject(timestamp, doc_id)
            else:
                res = None
            results.append(res)                                                # output 同 input 對位
    return results

async def notify_reviewers(self, timestamp, doc_ids, max_concurrent):         # 通知 reviewer，先 fail-fast 再 sem
    self._purge(timestamp)
    for doc_id in doc_ids:                                                    # Phase 1：同步驗證
        if doc_id not in self.docs:
            raise ValueError(f"doc_id={doc_id} not found")                    # 唔存在即刻炸，唔做後面
        if self.docs[doc_id]["status"] == "DRAFT":
            raise ValueError(f"doc_id={doc_id} is DRAFT, cannot notify")      # DRAFT 未交審，唔應該通知
    sem = asyncio.Semaphore(max_concurrent)                                   # Phase 2：真正 notify 先限流
    notified = []

    async def _notify_one(doc_id):
        async with sem:
            await asyncio.sleep(0.01)                                         # 模擬網絡延遲
            notified.append(doc_id)

    tasks = []
    for doc_id in doc_ids:
        if self.docs[doc_id]["status"] == "REVIEW":                           # 只 notify REVIEW 狀態
            tasks.append(_notify_one(doc_id))
    await asyncio.gather(*tasks)
    return notified

import asyncio
from collections import defaultdict

class SubscriptionBilling:
    def __init__(self):
        self.plans = {}                       # plan_id -> {"price_per_month": N}
        self.subs = {}                        # sub_id -> {"plan_id", "customer_id", "status", "expiry"}
        self.backups = []                     # L4 backup
        self.history = defaultdict(list)      # customer_id -> payment records
        self.migrated_plans = {}              # old_plan -> new_plan
        self.locks = defaultdict(asyncio.Lock)

def create_plan(self, timestamp, plan_id, price_per_month):                   # 開 plan
    self.plans[plan_id] = {"price_per_month": price_per_month}
    return True

def subscribe(self, timestamp, plan_id, subscription_id, customer_id, ttl_ms=None):  # 建 subscription
    resolved = self._resolve_plan(plan_id)                                    # plan 可能已 migrate，要先追鏈
    if resolved not in self.plans or subscription_id in self.subs:
        return False
    expiry = timestamp + ttl_ms if ttl_ms is not None else None
    self.subs[subscription_id] = {
        "plan_id": resolved,
        "customer_id": customer_id,
        "status": "ACTIVE",
        "expiry": expiry,
    }
    return True

def cancel(self, timestamp, subscription_id):                                 # ACTIVE / PAUSED -> CANCELLED
    self._purge_expired(timestamp)
    if subscription_id not in self.subs:
        return False
    sub = self.subs[subscription_id]
    if sub["status"] not in ("ACTIVE", "PAUSED"):
        return False
    sub["status"] = "CANCELLED"
    return True

def pause(self, timestamp, subscription_id):                                  # ACTIVE -> PAUSED
    self._purge_expired(timestamp)
    if subscription_id not in self.subs or self.subs[subscription_id]["status"] != "ACTIVE":
        return False
    self.subs[subscription_id]["status"] = "PAUSED"
    return True

def resume(self, timestamp, subscription_id):                                 # PAUSED -> ACTIVE
    self._purge_expired(timestamp)
    if subscription_id not in self.subs or self.subs[subscription_id]["status"] != "PAUSED":
        return False
    self.subs[subscription_id]["status"] = "ACTIVE"
    return True

def get_plan_subscribers(self, timestamp, plan_id):                           # 數某 plan 有幾多 ACTIVE sub
    self._purge_expired(timestamp)
    resolved = self._resolve_plan(plan_id)
    count = 0
    for sub in self.subs.values():
        if sub["plan_id"] == resolved and sub["status"] == "ACTIVE":
            count += 1
    return count

def get_customer_subscriptions(self, timestamp, customer_id):                # 搵 customer 全部 sub_id
    self._purge_expired(timestamp)
    result = []
    for sub_id, sub in self.subs.items():
        if sub["customer_id"] == customer_id:
            result.append(sub_id)
    return result

def _purge_expired(self, timestamp):                                          # TTL 到期即自動 cancel
    expired = [
        sid for sid, sub in self.subs.items()
        if sub["expiry"] is not None and timestamp >= sub["expiry"] and sub["status"] != "CANCELLED"
    ]
    for sid in expired:
        self.subs[sid]["status"] = "CANCELLED"                                # 呢題過期唔 delete，係改 status

def _resolve_plan(self, plan_id):                                             # 跟 migrated_plans chain 搵最新 plan
    visited = set()
    while plan_id in self.migrated_plans:
        if plan_id in visited:
            break
        visited.add(plan_id)
        plan_id = self.migrated_plans[plan_id]
    return plan_id

def backup(self, timestamp):                                                  # 影低 plans / subs / history / migrated_plans
    self._purge_expired(timestamp)
    subs_snapshot = {}
    for sid, sub in self.subs.items():
        remaining = sub["expiry"] - timestamp if sub["expiry"] is not None else None
        subs_snapshot[sid] = {
            "plan_id": sub["plan_id"],
            "customer_id": sub["customer_id"],
            "status": sub["status"],
            "remaining_ttl": remaining,
        }
    snapshot = {
        "timestamp": timestamp,
        "plans": {pid: dict(plan) for pid, plan in self.plans.items()},
        "subs": subs_snapshot,
        "history": {cid: list(records) for cid, records in self.history.items()},
        "migrated_plans": dict(self.migrated_plans),
    }
    self.backups.append(snapshot)
    return True

def restore(self, timestamp, target_ts):                                     # 找指定 backup timestamp 還原
    snapshot = None
    for backup in self.backups:
        if backup["timestamp"] == target_ts:
            snapshot = backup
            break
    if snapshot is None:
        return False
    self.plans = {pid: dict(plan) for pid, plan in snapshot["plans"].items()}
    self.subs = {}
    for sid, sub in snapshot["subs"].items():
        expiry = timestamp + sub["remaining_ttl"] if sub["remaining_ttl"] is not None else None
        self.subs[sid] = {
            "plan_id": sub["plan_id"],
            "customer_id": sub["customer_id"],
            "status": sub["status"],
            "expiry": expiry,
        }
    self.history = defaultdict(list, {cid: list(records) for cid, records in snapshot["history"].items()})
    self.migrated_plans = dict(snapshot["migrated_plans"])
    return True

def get_payment_history(self, customer_id):                                   # customer history 獨立 tracking
    return list(self.history[customer_id])

def migrate_plan(self, timestamp, from_plan, to_plan):                        # 將舊 plan 用家搬去新 plan
    self._purge_expired(timestamp)
    if to_plan not in self.plans:
        return False
    self.migrated_plans[from_plan] = to_plan
    for sub in self.subs.values():
        if sub["plan_id"] == from_plan:
            sub["plan_id"] = to_plan
    return True

async def batch_ops(self, timestamp, operations):                             # subscribe / cancel / pause / resume 批量處理
    results = [None] * len(operations)

    async def run_op(idx, op):
        op_type = op["type"]
        sub_id = op.get("subscription_id")
        async with self.locks[sub_id]:                                        # 單 sub op 用 sub_id 上鎖
            if op_type == "subscribe":
                results[idx] = self.subscribe(timestamp, op["plan_id"], sub_id, op["customer_id"], ttl_ms=op.get("ttl_ms"))
            elif op_type == "cancel":
                results[idx] = self.cancel(timestamp, sub_id)
            elif op_type == "pause":
                results[idx] = self.pause(timestamp, sub_id)
            elif op_type == "resume":
                results[idx] = self.resume(timestamp, sub_id)
            else:
                results[idx] = False

    await asyncio.gather(*[run_op(i, op) for i, op in enumerate(operations)])
    return results

async def transfer_subscription(self, timestamp, subscription_id, new_plan_id):  # 將一個 sub 轉去另一個 plan
    resolved = self._resolve_plan(new_plan_id)
    if resolved not in self.plans:
        return False
    async with self.locks[subscription_id]:
        self._purge_expired(timestamp)
        if subscription_id not in self.subs:
            return False
        sub = self.subs[subscription_id]
        if sub["status"] == "CANCELLED":
            return False
        sub["plan_id"] = resolved
        return True

async def process_payments(self, timestamp, subscription_ids, max_concurrent):  # fail-fast + sem 收款
    self._purge_expired(timestamp)
    sem = asyncio.Semaphore(max_concurrent)
    results = [None] * len(subscription_ids)

    async def process_one(idx, sub_id):
        if sub_id not in self.subs:                                           # 唔存在即刻 fail
            results[idx] = (sub_id, "PAYMENT_FAILED")
            return
        sub = self.subs[sub_id]
        if sub["status"] == "CANCELLED":                                      # CANCELLED 唔排隊
            results[idx] = (sub_id, "PAYMENT_FAILED")
            return
        if sub["status"] != "ACTIVE":                                         # PAUSED 一樣唔收錢
            results[idx] = (sub_id, "PAYMENT_FAILED")
            return
        async with sem:
            await asyncio.sleep(0.01)                                         # 模擬 network payment
            plan = self.plans.get(sub["plan_id"], {})
            amount = plan.get("price_per_month", 0)
            self.history[sub["customer_id"]].append({                         # 成功後記付款 history
                "subscription_id": sub_id,
                "plan_id": sub["plan_id"],
                "amount": amount,
                "timestamp": timestamp,
            })
            results[idx] = (sub_id, "PAYMENT_SUCCESS")

    await asyncio.gather(*[process_one(i, sid) for i, sid in enumerate(subscription_ids)])
    return results

import asyncio
from collections import defaultdict

class FleetTracker:
    def __init__(self):
        self.fleets = {}                       # fleet_id -> {"region": str, "history": [vehicle_id, ...]}
        self.vehicles = {}                     # vehicle_id -> {"fleet_id", "mileage", "status", "expiry"}
        self.backups = []                      # L4 snapshot list
        self.merged_fleets = {}                # old_fleet -> new_fleet
        self.locks = defaultdict(asyncio.Lock) # L5 per-vehicle lock

def register_fleet(self, timestamp, fleet_id, region):                        # 開一條新 fleet
    if fleet_id in self.fleets:
        return False
    self.fleets[fleet_id] = {"region": region, "history": []}                # A dict 存 fleet metadata
    return True

def add_vehicle(self, timestamp, fleet_id, vehicle_id, mileage, ttl_ms=None):  # 將車加落 fleet
    if fleet_id not in self.fleets or vehicle_id in self.vehicles:
        return False
    expiry = timestamp + ttl_ms if ttl_ms is not None else None
    self.vehicles[vehicle_id] = {                                             # B dict flat 存車
        "fleet_id": fleet_id,
        "mileage": mileage,
        "status": "ACTIVE",
        "expiry": expiry,
    }
    self.fleets[fleet_id]["history"].append(vehicle_id)                       # 記低呢架車曾經屬於過呢條 fleet
    return True

def decommission(self, timestamp, vehicle_id):                                # 只帶 vehicle_id 直接停車
    self._purge_expired(timestamp)
    vehicle = self.vehicles.get(vehicle_id)
    if vehicle is None or vehicle["status"] == "DECOMMISSIONED":
        return False
    vehicle["status"] = "DECOMMISSIONED"
    return True

def get_fleet_size(self, timestamp, fleet_id):                                # 數某條 fleet 幾多架 ACTIVE 車
    self._purge_expired(timestamp)
    if fleet_id not in self.fleets:
        return None
    count = 0
    for vehicle in self.vehicles.values():
        if vehicle["fleet_id"] == fleet_id and vehicle["status"] == "ACTIVE":
            count += 1
    return count

def get_vehicle(self, timestamp, vehicle_id):                                 # 攞一架車資料
    vehicle = self.vehicles.get(vehicle_id)
    if vehicle is None:
        return None
    if vehicle["expiry"] is not None and vehicle["status"] == "ACTIVE" and timestamp >= vehicle["expiry"]:
        vehicle["status"] = "DECOMMISSIONED"                                  # 單點查詢都會順手補做 expiry
    return dict(vehicle)

def get_highest_mileage(self, timestamp, n):                                  # top n mileage，active only
    self._purge_expired(timestamp)
    active = [
        (vehicle_id, vehicle["mileage"])
        for vehicle_id, vehicle in self.vehicles.items()
        if vehicle["status"] == "ACTIVE"
    ]
    active.sort(key=lambda x: (-x[1], x[0]))                                  # mileage desc，tie-break vehicle_id asc
    return active[:n]

def _purge_expired(self, timestamp):                                          # 掃全部車，過期就標 DECOMMISSIONED
    for vehicle in self.vehicles.values():
        if vehicle["expiry"] is not None and vehicle["status"] == "ACTIVE" and timestamp >= vehicle["expiry"]:
            vehicle["status"] = "DECOMMISSIONED"

def _is_active(self, vehicle_id, timestamp):                                  # 查一架車仲 active 唔 active
    vehicle = self.vehicles.get(vehicle_id)
    if vehicle is None:
        return False
    if vehicle["expiry"] is not None and vehicle["status"] == "ACTIVE" and timestamp >= vehicle["expiry"]:
        vehicle["status"] = "DECOMMISSIONED"                                  # 單點 check 都會補做 expiry
    return vehicle["status"] == "ACTIVE"

def backup(self, timestamp):                                                  # 影成個 fleet system snapshot
    self._purge_expired(timestamp)
    fleets_copy = {
        fleet_id: {"region": fleet["region"], "history": list(fleet["history"])}
        for fleet_id, fleet in self.fleets.items()
    }
    vehicles_copy = {}
    for vehicle_id, vehicle in self.vehicles.items():
        remaining = vehicle["expiry"] - timestamp if vehicle["expiry"] is not None and vehicle["status"] == "ACTIVE" else None
        vehicles_copy[vehicle_id] = {
            "fleet_id": vehicle["fleet_id"],
            "mileage": vehicle["mileage"],
            "status": vehicle["status"],
            "remaining_ttl": remaining,
        }
    self.backups.append({
        "timestamp": timestamp,
        "fleets": fleets_copy,
        "vehicles": vehicles_copy,
        "merged_fleets": dict(self.merged_fleets),
    })
    return len(self.backups)

def restore(self, timestamp, target_ts):                                     # 還原指定 backup timestamp
    snapshot = None
    for backup in self.backups:
        if backup["timestamp"] == target_ts:
            snapshot = backup
            break
    if snapshot is None:
        return False
    self.fleets = {fid: {"region": fleet["region"], "history": list(fleet["history"])} for fid, fleet in snapshot["fleets"].items()}
    self.vehicles = {}
    for vehicle_id, vehicle in snapshot["vehicles"].items():
        expiry = timestamp + vehicle["remaining_ttl"] if vehicle["remaining_ttl"] is not None else None
        self.vehicles[vehicle_id] = {
            "fleet_id": vehicle["fleet_id"],
            "mileage": vehicle["mileage"],
            "status": vehicle["status"],
            "expiry": expiry,
        }
    self.merged_fleets = dict(snapshot["merged_fleets"])
    return True

def get_vehicle_history(self, timestamp, fleet_id):                           # 歷史跟 fleet 走，但要先 resolve merge chain
    resolved = self._resolve_fleet(fleet_id)
    if resolved not in self.fleets:
        return None
    return list(self.fleets[resolved]["history"])

def merge_fleet(self, timestamp, from_fleet_id, to_fleet_id):                 # 將 ACTIVE 車搬去另一條 fleet
    self._purge_expired(timestamp)
    if from_fleet_id not in self.fleets or to_fleet_id not in self.fleets:
        return False
    for vehicle_id, vehicle in self.vehicles.items():
        if vehicle["fleet_id"] == from_fleet_id and vehicle["status"] == "ACTIVE":
            vehicle["fleet_id"] = to_fleet_id
            self.fleets[to_fleet_id]["history"].append(vehicle_id)
    self.merged_fleets[from_fleet_id] = to_fleet_id
    return True

async def batch_ops(self, timestamp, operations):                             # add / decommission 批量處理
    results = []
    for op in operations:
        if op["type"] == "add":
            vehicle_id = op["vehicle_id"]
            async with self.locks[vehicle_id]:                                # 單車 op 鎖 vehicle_id
                result = self.add_vehicle(timestamp, op["fleet_id"], vehicle_id, op["mileage"], ttl_ms=op.get("ttl_ms"))
            results.append(result)
        elif op["type"] == "decommission":
            vehicle_id = op["vehicle_id"]
            async with self.locks[vehicle_id]:
                results.append(self.decommission(timestamp, vehicle_id))
        else:
            results.append(False)
    return results

async def transfer_vehicle(self, timestamp, vehicle_id, new_fleet_id):       # 將一架 ACTIVE 車轉去另一條 fleet
    self._purge_expired(timestamp)
    async with self.locks[vehicle_id]:
        vehicle = self.vehicles.get(vehicle_id)
        if vehicle is None or vehicle["status"] != "ACTIVE":
            return False
        if new_fleet_id not in self.fleets or vehicle["fleet_id"] == new_fleet_id:
            return False
        vehicle["fleet_id"] = new_fleet_id
        self.fleets[new_fleet_id]["history"].append(vehicle_id)
        return True

async def inspect_vehicles(self, timestamp, vehicle_ids, max_concurrent):     # fail-fast + semaphore 檢車
    self._purge_expired(timestamp)
    for vehicle_id in vehicle_ids:                                            # Phase 1：先驗證
        vehicle = self.vehicles.get(vehicle_id)
        if vehicle is None:
            return {"error": f"Vehicle {vehicle_id} not found"}               # 唔存在即刻 fail
        if vehicle["status"] == "DECOMMISSIONED":
            return {"error": f"Vehicle {vehicle_id} is DECOMMISSIONED"}       # 已退役一樣唔做
    sem = asyncio.Semaphore(max_concurrent)                                   # Phase 2：過關先限流
    results = {}

    async def _inspect_one(vehicle_id):
        async with sem:
            await asyncio.sleep(0)                                            # 模擬 inspection 工作
            results[vehicle_id] = "INSPECTED"

    tasks = [asyncio.create_task(_inspect_one(vehicle_id)) for vehicle_id in vehicle_ids]
    await asyncio.gather(*tasks)
    return results

import threading
from collections import defaultdict

class CDNEdgeCache:
    def __init__(self):
        self.nodes = {}                        # node_id -> {"storage_limit_mb": N, "history": [...]}
        self.objects = {}                      # object_id -> {"node_id", "size_mb", "access_time", "expiry"}
        self._locks = defaultdict(threading.Lock)  # L5 per-node lock
        self._meta_lock = threading.Lock()     # 保護 _locks dict 建立過程

def register_node(self, timestamp, node_id, storage_limit_mb):                # 開一個新 edge node
    self._purge(timestamp)
    if node_id in self.nodes:
        return {"status": "error", "message": f"Node {node_id} already exists"}
    self.nodes[node_id] = {
        "storage_limit_mb": storage_limit_mb,
        "history": [{"action": "register", "timestamp": timestamp, "storage_limit_mb": storage_limit_mb}],
    }
    return {"status": "ok", "node_id": node_id}

def cache_object(self, timestamp, node_id, object_id, size_mb, ttl_ms=None): # 將 object 放落 node
    self._purge(timestamp)
    if node_id not in self.nodes:
        return {"status": "error", "message": f"Node {node_id} not found"}
    expiry = (timestamp + ttl_ms) if ttl_ms is not None else None
    if object_id in self.objects:
        del self.objects[object_id]                                            # 同 id 重 cache 就先覆蓋舊 object
    self._evict_lru_from(timestamp, node_id, size_mb)                          # L4：容量唔夠就 while 踢 LRU
    usage = self._calc_usage(node_id)
    limit = self.nodes[node_id]["storage_limit_mb"]
    if usage + size_mb > limit:
        return {"status": "error", "message": f"Not enough space on {node_id} even after eviction"}
    self.objects[object_id] = {"node_id": node_id, "size_mb": size_mb, "access_time": timestamp, "expiry": expiry}
    self.nodes[node_id]["history"].append({"action": "cache", "timestamp": timestamp, "object_id": object_id, "size_mb": size_mb, "ttl_ms": ttl_ms})
    return {"status": "ok", "object_id": object_id, "node_id": node_id}

def invalidate(self, timestamp, object_id):                                    # 手動令 object 失效
    self._purge(timestamp)
    if object_id not in self.objects:
        return {"status": "error", "message": f"Object {object_id} not found"}
    node_id = self.objects[object_id]["node_id"]
    del self.objects[object_id]
    return {"status": "ok", "object_id": object_id, "node_id": node_id}

def get_node_usage(self, timestamp, node_id):                                  # 查 node 用量
    self._purge(timestamp)
    if node_id not in self.nodes:
        return {"status": "error", "message": f"Node {node_id} not found"}
    usage = self._calc_usage(node_id)
    limit = self.nodes[node_id]["storage_limit_mb"]
    return {"status": "ok", "node_id": node_id, "used_mb": usage, "limit_mb": limit, "free_mb": limit - usage}

def get_object_location(self, timestamp, object_id):                           # 查 object 而家喺邊個 node
    self._purge(timestamp)
    if object_id not in self.objects:
        return {"status": "error", "message": f"Object {object_id} not found"}
    obj = self.objects[object_id]
    obj["access_time"] = timestamp                                             # 讀取都算 access，會影響 LRU
    return {"status": "ok", "object_id": object_id, "node_id": obj["node_id"], "size_mb": obj["size_mb"], "expiry": obj["expiry"]}

def get_largest_nodes(self, timestamp, n):                                    # top n 用量最大 node
    self._purge(timestamp)
    rows = []
    for node_id in self.nodes:
        rows.append({
            "node_id": node_id,
            "used_mb": self._calc_usage(node_id),                              # usage 要掃 B dict 加總
            "limit_mb": self.nodes[node_id]["storage_limit_mb"],
        })
    rows.sort(key=lambda x: x["used_mb"], reverse=True)
    return {"status": "ok", "nodes": rows[:n]}

def _purge(self, timestamp):                                                  # 掃走所有過期 object
    expired_ids = [
        object_id for object_id, obj in self.objects.items()
        if obj["expiry"] is not None and obj["expiry"] <= timestamp
    ]
    for object_id in expired_ids:
        node_id = self.objects[object_id]["node_id"]
        if node_id in self.nodes:
            self.nodes[node_id]["history"].append({
                "action": "auto_purge",
                "timestamp": timestamp,
                "object_id": object_id,
                "size_mb": self.objects[object_id]["size_mb"],
            })
        del self.objects[object_id]                                           # 呢題過期係直接 delete object

# TTL 寫喺 L1 cache_object 入面：
# expiry = timestamp + ttl_ms if ttl_ms is not None else None

def _evict_lru_from(self, timestamp, node_id, needed_mb):                     # while loop 逐個踢最舊 object
    while True:
        usage = self._calc_usage(node_id)
        limit = self.nodes[node_id]["storage_limit_mb"]
        if usage + needed_mb <= limit:
            break                                                              # 騰夠位就停
        node_objects = [
            (object_id, obj) for object_id, obj in self.objects.items()
            if obj["node_id"] == node_id
        ]
        if not node_objects:
            break
        lru_id, lru_obj = min(node_objects, key=lambda x: x[1]["access_time"])# access_time 最細 = 最舊
        self.nodes[node_id]["history"].append({"action": "evict_lru", "timestamp": timestamp, "object_id": lru_id, "size_mb": lru_obj["size_mb"]})
        del self.objects[lru_id]

def backup(self, timestamp, node_id):                                         # 備份單一 node 所有 object
    self._purge(timestamp)
    if node_id not in self.nodes:
        return {"status": "error", "message": f"Node {node_id} not found"}
    snapshot = []
    for object_id, obj in self.objects.items():
        if obj["node_id"] != node_id:
            continue
        remaining = obj["expiry"] - timestamp if obj["expiry"] is not None else None
        snapshot.append({"object_id": object_id, "size_mb": obj["size_mb"], "access_time": obj["access_time"], "remaining_ttl": remaining})
    return {"status": "ok", "node_id": node_id, "snapshot": snapshot}

def restore(self, timestamp, node_id, snapshot):                              # 根據 remaining_ttl 還原 object
    self._purge(timestamp)
    if node_id not in self.nodes:
        return {"status": "error", "message": f"Node {node_id} not found"}
    restored = 0
    skipped = 0
    for item in snapshot:
        expiry = timestamp + item["remaining_ttl"] if item.get("remaining_ttl") is not None else None
        self._evict_lru_from(timestamp, node_id, item["size_mb"])            # restore 前都可能要先騰位
        if self._calc_usage(node_id) + item["size_mb"] > self.nodes[node_id]["storage_limit_mb"]:
            skipped += 1
            continue
        self.objects[item["object_id"]] = {"node_id": node_id, "size_mb": item["size_mb"], "access_time": item.get("access_time", timestamp), "expiry": expiry}
        restored += 1
    return {"status": "ok", "restored": restored, "skipped": skipped}

def set_storage_limit(self, timestamp, node_id, new_limit_mb):                # 動態縮細容量都要 while loop 踢 LRU
    self._purge(timestamp)
    old_limit = self.nodes[node_id]["storage_limit_mb"]
    self.nodes[node_id]["storage_limit_mb"] = new_limit_mb
    self._evict_lru_from(timestamp, node_id, 0)                               # 唔係加新 object，所以 needed_mb = 0
    return {"status": "ok", "node_id": node_id, "old_limit_mb": old_limit, "new_limit_mb": new_limit_mb}

def batch_ops(self, timestamp, operations):                                   # cache / invalidate 批量做
    self._purge(timestamp)
    involved_nodes = set()
    for op in operations:                                                     # 先收集所有會郁到嘅 node
        if op["op"] == "cache":
            involved_nodes.add(op["node_id"])
        elif op["op"] == "invalidate" and op["object_id"] in self.objects:
            involved_nodes.add(self.objects[op["object_id"]]["node_id"])
    locks = [self._get_lock(node_id) for node_id in sorted(involved_nodes)]   # sorted node lock，避免 deadlock
    for lock in locks:
        lock.acquire()
    try:
        results = []
        for op in operations:
            if op["op"] == "cache":
                results.append(self.cache_object(timestamp, op["node_id"], op["object_id"], op["size_mb"], ttl_ms=op.get("ttl_ms")))
            elif op["op"] == "invalidate":
                results.append(self.invalidate(timestamp, op["object_id"]))
            else:
                results.append({"status": "error", "message": f"Unknown op: {op['op']}"})
        return {"status": "ok", "results": results}
    finally:
        for lock in reversed(locks):
            lock.release()

def replicate(self, timestamp, object_id, from_node, to_node, ttl_ms=None):  # 複製 object 去另一個 node
    self._purge(timestamp)
    sorted_nodes = sorted([from_node, to_node])                               # pair-lock：兩個 node 一定按字母序拎鎖
    locks = [self._get_lock(node_id) for node_id in sorted_nodes]
    for lock in locks:
        lock.acquire()
    try:
        obj = self.objects[object_id]
        replica_id = f"{object_id}@{to_node}"
        expiry = timestamp + ttl_ms if ttl_ms is not None else obj["expiry"]
        self._evict_lru_from(timestamp, to_node, obj["size_mb"])
        self.objects[replica_id] = {"node_id": to_node, "size_mb": obj["size_mb"], "access_time": timestamp, "expiry": expiry}
        return {"status": "ok", "replica_id": replica_id, "from_node": from_node, "to_node": to_node}
    finally:
        for lock in reversed(locks):
            lock.release()

def purge_nodes(self, timestamp, node_ids, max_concurrent):                   # 批量清空多個 node
    self._purge(timestamp)
    for node_id in node_ids:                                                  # Phase 1：fail-fast
        if node_id not in self.nodes:
            return {"status": "error", "message": f"Node {node_id} not found — fail-fast, no nodes purged"}
    semaphore = threading.Semaphore(max_concurrent)                           # Phase 2：thread semaphore
    results = {}
    result_lock = threading.Lock()

    def _purge_single_node(node_id):                                          # 清空單一 node
        with semaphore:
            to_remove = [object_id for object_id, obj in self.objects.items() if obj["node_id"] == node_id]
            removed_count = 0
            freed_mb = 0.0
            for object_id in to_remove:
                if object_id in self.objects:
                    freed_mb += self.objects[object_id]["size_mb"]
                    del self.objects[object_id]
                    removed_count += 1
            self.nodes[node_id]["history"].append({"action": "purge_node", "timestamp": timestamp, "removed_count": removed_count, "freed_mb": freed_mb})
            with result_lock:
                results[node_id] = {"removed_count": removed_count, "freed_mb": freed_mb}

    threads = []
    for node_id in node_ids:
        thread = threading.Thread(target=_purge_single_node, args=(node_id,))
        threads.append(thread)
        thread.start()
    for thread in threads:
        thread.join()
    return {"status": "ok", "purged": results}

import asyncio
import copy
from collections import defaultdict

class ComplianceAuditEngine:
    def __init__(self):
        self.policies = {}                    # policy_id -> {"description": str, "max_violations": int}
        self.violations = {}                  # violation_id -> {"policy_id", "entity_id", "severity", "status", "expiry"}
        self.history = defaultdict(list)      # entity_id -> [violation_id, ...]
        self.merged_entities = {}             # old_entity -> new_entity
        self.backups = []                     # L4 backup list
        self.locks = defaultdict(asyncio.Lock)# L5 per-key lock

def register_policy(self, timestamp, policy_id, description, max_violations): # 開一條 policy
    if policy_id in self.policies:
        return False
    self.policies[policy_id] = {
        "description": description,
        "max_violations": max_violations,
    }
    return True

def flag_violation(self, timestamp, policy_id, entity_id, violation_id, severity, ttl_ms=0):  # 新增 violation
    self._purge(timestamp)
    entity_id = self._resolve_entity(entity_id)                               # merge 過嘅 entity 要先追鏈
    if policy_id not in self.policies or violation_id in self.violations:
        return False
    max_v = self.policies[policy_id]["max_violations"]
    if self._count_active_for_entity_policy(entity_id, policy_id) >= max_v:
        return False                                                          # 已經去到上限唔畀再記
    expiry = (timestamp + ttl_ms) if ttl_ms > 0 else None
    self.violations[violation_id] = {
        "policy_id": policy_id,
        "entity_id": entity_id,
        "severity": severity,
        "status": "ACTIVE",
        "expiry": expiry,
    }
    self.history[entity_id].append(violation_id)                              # independent history 喺呢度記
    return True

def clear_violation(self, timestamp, violation_id):                           # ACTIVE -> CLEARED
    self._purge(timestamp)
    if violation_id not in self.violations:
        return False
    violation = self.violations[violation_id]
    if violation["status"] != "ACTIVE":
        return False
    violation["status"] = "CLEARED"
    return True

def get_active_violations(self, timestamp, entity_id):                        # 數某 entity 跨 policy ACTIVE 幾多單
    self._purge(timestamp)
    entity_id = self._resolve_entity(entity_id)
    count = 0
    for violation in self.violations.values():
        if violation["entity_id"] == entity_id and violation["status"] == "ACTIVE":
            count += 1
    return count

def get_worst_entities(self, timestamp, n):                                   # top n entity by ACTIVE violation count
    self._purge(timestamp)
    entity_counts = defaultdict(int)
    for violation in self.violations.values():
        if violation["status"] == "ACTIVE":
            entity_counts[violation["entity_id"]] += 1
    ranked = sorted(entity_counts.items(), key=lambda x: (-x[1], x[0]))       # count desc，再 entity asc
    return ranked[:n]

def find_violation(self, timestamp, violation_id):                            # direct lookup by violation_id
    self._purge(timestamp)
    if violation_id not in self.violations:
        return None
    violation = self.violations[violation_id]
    return (violation["policy_id"], violation["entity_id"])

def _purge(self, timestamp):                                                  # 掃 violations，過期就改 EXPIRED
    for violation in self.violations.values():
        if violation["status"] == "ACTIVE" and violation["expiry"] is not None and violation["expiry"] <= timestamp:
            violation["status"] = "EXPIRED"                                   # 呢題過期唔 delete，方便審計留痕

# TTL 已經整合喺 flag_violation 入面：
# expiry = (timestamp + ttl_ms) if ttl_ms > 0 else None

def backup(self, timestamp):                                                  # 影低 policies / violations / history / merged_entities
    self._purge(timestamp)
    violations_snap = {}
    for violation_id, violation in self.violations.items():
        row = copy.deepcopy(violation)
        row["remaining_ttl"] = (row["expiry"] - timestamp) if row["expiry"] is not None and row["status"] == "ACTIVE" else None
        del row["expiry"]
        violations_snap[violation_id] = row
    snap = {
        "timestamp": timestamp,
        "policies": copy.deepcopy(self.policies),
        "violations": violations_snap,
        "history": copy.deepcopy(dict(self.history)),
        "merged_entities": copy.deepcopy(self.merged_entities),
    }
    self.backups.append(snap)
    return len(self.backups) - 1

def restore(self, timestamp, backup_idx):                                     # 用 backup index 還原
    if backup_idx < 0 or backup_idx >= len(self.backups):
        return False
    snap = self.backups[backup_idx]
    self.policies = copy.deepcopy(snap["policies"])
    self.merged_entities = copy.deepcopy(snap["merged_entities"])
    self.history = defaultdict(list, copy.deepcopy(snap["history"]))
    self.violations = {}
    for violation_id, row in snap["violations"].items():
        restored = copy.deepcopy(row)
        remaining = restored.pop("remaining_ttl")
        restored["expiry"] = timestamp + remaining if remaining is not None and restored["status"] == "ACTIVE" else None
        self.violations[violation_id] = restored
    return True

def get_violation_history(self, timestamp, entity_id):                        # history 單獨按 entity_id track
    self._purge(timestamp)
    entity_id = self._resolve_entity(entity_id)
    return list(self.history.get(entity_id, []))

def merge_entity(self, timestamp, from_entity, to_entity):                    # 將舊 entity 違規搬去新 entity
    self._purge(timestamp)
    from_entity = self._resolve_entity(from_entity)
    to_entity = self._resolve_entity(to_entity)
    if from_entity == to_entity:
        return False
    for violation in self.violations.values():
        if violation["entity_id"] == from_entity:
            violation["entity_id"] = to_entity
    if from_entity in self.history:
        self.history[to_entity].extend(self.history[from_entity])
        del self.history[from_entity]
    self.merged_entities[from_entity] = to_entity
    return True

async def batch_audit(self, timestamp, operations):                           # flag / clear / transfer 批量處理
    results = []
    for op in operations:
        if op["type"] == "flag":
            violation_id = op["violation_id"]
            async with self.locks[violation_id]:                              # Pattern A：單 violation lock
                results.append(self.flag_violation(timestamp, op["policy_id"], op["entity_id"], violation_id, op["severity"], op.get("ttl_ms", 0)))
        elif op["type"] == "clear":
            violation_id = op["violation_id"]
            async with self.locks[violation_id]:
                results.append(self.clear_violation(timestamp, violation_id))
        elif op["type"] == "transfer":
            violation_id = op["violation_id"]
            to_entity = op["to_entity"]
            keys = sorted([violation_id, to_entity])                          # Pattern B：violation_id + to_entity pair-lock
            async with self.locks[keys[0]]:
                async with self.locks[keys[1]]:
                    results.append(self._transfer_violation(timestamp, violation_id, to_entity))
        else:
            results.append(False)
    return results

def _transfer_violation(self, timestamp, violation_id, to_entity):            # 搬一張 ACTIVE violation 去另一個 entity
    self._purge(timestamp)
    if violation_id not in self.violations:
        return False
    violation = self.violations[violation_id]
    if violation["status"] != "ACTIVE":
        return False
    to_entity = self._resolve_entity(to_entity)
    policy_id = violation["policy_id"]
    max_v = self.policies[policy_id]["max_violations"]
    if self._count_active_for_entity_policy(to_entity, policy_id) >= max_v:
        return False
    violation["entity_id"] = to_entity
    self.history[to_entity].append(violation_id)
    return True

async def report_violations(self, timestamp, violation_ids, max_concurrent):  # fail-fast + sem 匯報 violation
    self._purge(timestamp)
    for violation_id in violation_ids:                                        # Phase 1：同步驗證
        if violation_id not in self.violations:
            raise ValueError(f"Violation {violation_id} does not exist")
        if self.violations[violation_id]["status"] == "CLEARED":
            raise ValueError(f"Violation {violation_id} is CLEARED")          # CLEARED 唔應該再匯報
    sem = asyncio.Semaphore(max_concurrent)                                   # Phase 2：過關先限流
    reported = []

    async def _report_one(violation_id):
        async with sem:
            await asyncio.sleep(0.01)                                         # 模擬 network call
            self.violations[violation_id]["status"] = "REPORTED"
            reported.append(violation_id)

    tasks = [asyncio.create_task(_report_one(violation_id)) for violation_id in violation_ids]
    await asyncio.gather(*tasks)
    return reported

# Bank = 最基本嘅 dict-of-dicts 系統
# 核心 data structure：
self.accounts = {}   # account_id → {balance, outgoing, history}
self.payment = {}    # payment_id → {account_id, cashback_amount, ...}

# 每個 method 第一個 param 都係 timestamp
# L3 開始每個 method 開頭都 call self._process_cashbacks(timestamp)

# Level 進程：
# L1: CRUD（建/存/轉）
# L2: Sort/Filter/Format（排名）
# L3: Timestamp/TTL/Lazy（付款 + cashback）
# L4: Backup/Merge/History（歷史查詢 + 合併）
# L5: Concurrent Batch（async gather + lock）
# L6: Rate Limited External（+ semaphore）

import asyncio                               # L5 async 用
import copy                                   # L4 deepcopy 用
import bisect                                 # 有啲題 binary search 用
from collections import defaultdict           # L5 auto-create lock 用

class BankSystem:
    def __init__(self):
        self.accounts = {}                  # L1 — account_id → {balance, outgoing, history}
        self.payment_counter = 0        # L3 加 — auto-increment payment ID
        self.payment = {}                # L3 加 — payment_id → {account_id, cashback_amount, ...}
        self.merged_accounts = {}        # L4 加 — old_id → new_id（合併記錄）
        self.account_locks = defaultdict(asyncio.Lock) # L5 加 — 每個 account 一把鎖

# Helper: _process_cashbacks — 每個 method 開頭都 call（L3 開始）
# Lazy processing：唔會自動到期，要等有人 call method 帶 timestamp 入嚟先 check
def _process_cashbacks(self, timestamp):    # 行晒所有 payment，到期嘅入賬
    for pid, p in self.payment.items():     # 逐個 payment 睇
        if not p["received"] and timestamp >= p["cashback_time"]:  # 未收過 + 到期
            self.accounts[p["account_id"]]["balance"] += p["cashback_amount"]  # 到鐘就將回贈重新派返入客人戶口；等於商店而家先找數
            p["received"] = True              # 標記已收（下次唔再入）

def create_account(self, timestamp, account_id):  # 開新戶口
    self._process_cashbacks(timestamp)     # L3 加：先處理到期嘅 cashback

    if account_id in self.accounts:  # 呢個戶口存唔存在？
        return False  # 已經有 → 拒絕重複建

    self.accounts[account_id] = {  # 開個新戶口，記低資料
        "balance": 0,                    # L1
        "outgoing": 0,                   # L2 加
        "history": [(timestamp, 0)]      # L4 加
    }

    return True  # 開成功

def deposit(self, timestamp, account_id, amount):  # 存錢入戶口
    self._process_cashbacks(timestamp)     # L3 加：先處理到期嘅 cashback

    if account_id not in self.accounts:  # 戶口唔存在？
        return None  # 搵唔到 → 冇嘢做

    acc = self.accounts[account_id]  # 攞出嚟（pointer，改佢即改原本）
    acc["balance"] += amount  # 加錢入去
    acc["history"].append((timestamp, acc["balance"])) # L4 加

    return acc["balance"]  # 回傳新餘額

def transfer(self, timestamp, source_id, target_id, amount):  # 由一個戶口轉錢去另一個
    self._process_cashbacks(timestamp)     # L3 加：先處理到期嘅 cashback

    if source_id not in self.accounts or target_id not in self.accounts:  # 兩個戶口都存在？
        return None  # 有一個唔喺度 → 唔做
    if source_id == target_id:  # 自己轉畀自己？
        return None  # 唔准

    s_acc = self.accounts[source_id]  # 攞 source 戶口（pointer）
    t_acc = self.accounts[target_id]  # 攞 target 戶口（pointer）
    if s_acc["balance"] < amount:  # source 夠唔夠錢？
        return None  # 唔夠 → 唔做

    s_acc["balance"] -= amount  # source 扣錢
    s_acc["outgoing"] += amount            # L2 加
    s_acc["history"].append((timestamp, s_acc["balance"])) # L4 加

    t_acc["balance"] += amount  # target 收錢
    t_acc["history"].append((timestamp, t_acc["balance"])) # L4 加

    return s_acc["balance"]  # 回傳 source 嘅新餘額

def top_spenders(self, timestamp, n):  # 排頭 N 個花最多錢嘅戶口
    self._process_cashbacks(timestamp)  # 先處理到期 cashback

    sorted_items = dict(sorted(  # 排序：outgoing 大排先，同分按名 asc
        self.accounts.items(),  # 將全部戶口攤平畀 sorted 排榜；之後先可以揀出 top spenders
        key=lambda x: (-x[1]["outgoing"], x[0])  # -值 = desc，名 = asc
    ))

    result = []  # 準備裝 format 完嘅 string
    for account_id, acc in sorted_items.items():  # 逐個戶口行
        result.append(f"{account_id}({acc['outgoing']})")  # 格式化成 "名(值)"

    return result[:n]  # 淨攞頭 N 個

def pay(self, timestamp, account_id, amount):  # 付款（觸發 scheduled cashback）
    self._process_cashbacks(timestamp)  # 先處理到期嘅 cashback

    if account_id not in self.accounts: return None  # 戶口唔存在 → 唔做
    acc = self.accounts[account_id]  # 攞戶口 pointer
    if acc["balance"] < amount: return None  # 唔夠錢 → 唔做

    acc["balance"] -= amount                            # 扣錢
    acc["outgoing"] += amount                           # 記去 outgoing（排名用）
    acc["history"].append((timestamp, acc["balance"]))   # 記歷史

    cashback = amount * 2 // 100                   # 計算 cashback amount（2%，整數除法）
    cashback_time = timestamp + 86400000             # 24 小時後（毫秒）

    self.payment_counter += 1                        # auto-increment ID
    pid = f"payment{self.payment_counter}"            # "payment1", "payment2", ...
    self.payment[pid] = {  # 記低 payment 資料
        "account_id": account_id,  # 邊個 account 嘅
        "cashback_amount": cashback,  # 回贈幾多
        "cashback_time": cashback_time,  # 幾時到期可收
        "received": False  # 未收過
    }

    return pid  # 回傳 payment ID

def get_payment_status(self, timestamp, account_id, payment_id):  # 查付款狀態
    self._process_cashbacks(timestamp)  # 先處理到期嘅 cashback

    if account_id not in self.accounts: return None  # 戶口唔存在
    if payment_id not in self.payment: return None  # payment 唔存在
    if self.payment[payment_id]["account_id"] != account_id: return None  # 唔屬於呢個戶口
    if self.payment[payment_id]["received"]:  # cashback 收咗未？
        return "CASHBACK_RECEIVED"  # 已收
    return "IN_PROGRESS"  # 未到期，仲等緊

def get_balance(self, timestamp, account_id, time_at):  # 查餘額（可以查某個時間點嘅）
    self._process_cashbacks(timestamp)  # 先處理到期嘅 cashback

    if account_id not in self.accounts: return None  # 戶口唔存在

    acc = self.accounts[account_id]  # 攞戶口 pointer
    for ts, val in reversed(acc["history"]):      # 由尾搵返去
        if ts <= time_at:  # 搵到 <= 嗰個時間點嘅 entry
            return val  # 回傳嗰刻嘅 balance

def merge_accounts(self, timestamp, account_id_1, account_id_2):  # 合併兩個戶口
    self._process_cashbacks(timestamp)  # 先處理到期嘅 cashback

    if account_id_1 not in self.accounts or account_id_2 not in self.accounts: return False  # 兩個都要存在
    if account_id_1 == account_id_2: return False  # 唔准自己合自己

    acc_1 = self.accounts[account_id_1]  # 攞主戶口（留低嗰個）
    acc_2 = self.accounts[account_id_2]  # 攞副戶口（被吸收嗰個）

    acc_1["balance"] += acc_2["balance"]              # 合併 balance
    acc_1["outgoing"] += acc_2["outgoing"]            # 合併 outgoing
    acc_1["history"].append((timestamp, acc_1["balance"]))  # 記歷史

    self.merged_accounts[account_id_2] = account_id_1  # 記錄：舊 → 新
    del self.accounts[account_id_2]                     # 刪舊 account

    return True  # 合併成功

# 第一步：先定義點樣處理單一 op
# 第二步：按張單會郁幾多個 account 去攞鎖
# 第三步：收集晒 coroutine，再一次過 gather
async def process_batch(self, timestamp, operations):  # 批量處理一堆銀行動作，好似同時開幾個 clerk 做單
    self._process_cashbacks(timestamp)  # 開工前先補返到期 cashback，避免舊數未入賬就即刻做新單

    async def execute_op(op):                     # 每次只處理一張單，最後會畀 gather 一齊放出去跑
        # 第一步：transfer 會同時郁兩個戶口，所以要先排好鎖嘅次序
        if op["type"] == "transfer":  # 呢種單係由一個戶口搬錢去另一個戶口
            keys = sorted([op["source_id"], op["target_id"]])  # 永遠照同一個次序攞鎖，避免兩張單互相等死
            async with self.account_locks[keys[0]]:  # 先鎖排前面嗰個戶口
                async with self.account_locks[keys[1]]:  # 再鎖第二個戶口，兩邊都安全先真正過數
                    return self.transfer(timestamp, op["source_id"], op["target_id"], op["amount"])  # 借返同步 transfer 真正搬錢，呢度只負責排隊同保護資料

        # 第二步：deposit / pay 只會郁一個戶口，鎖一邊就夠
        aid = op["account_id"]  # 呢張單實際上會改邊個戶口，就用佢做排隊 key
        async with self.account_locks[aid]:  # 同一個戶口一次只畀一張單入去改，避免 balance 互相踩爛
            if op["type"] == "deposit":  # 呢張係入錢單
                return self.deposit(timestamp, op["account_id"], op["amount"])  # 交返畀同步 deposit 真正加錢
            elif op["type"] == "pay":  # 呢張係付款單
                return self.pay(timestamp, op["account_id"], op["amount"])  # 交返畀同步 pay 真正扣錢同記 outgoing

    # 第三步：將所有單包成 coroutine，一次過同時開工
    tasks = []  # 呢個 list 好似待辦單夾，逐張收埋等陣一齊交畀 gather
    for op in operations:  # 行晒你傳入嚟嘅每張單
        tasks.append(execute_op(op))  # 先包成 coroutine，未真跑住
    results = await asyncio.gather(*tasks)  # 一次過放晒出去跑，各自靠 lock 保護同一個戶口
    return list(results)  # caller 會收到每張單各自嘅結果，順序同原本 operations 一致

# 第一步：先喺本地鎖住戶口做 fail-fast 檢查
# 第二步：真係扣到錢先離開 lock
# 第三步：過關嘅單先入 semaphore，模擬外部 API 慢慢處理
async def process_external_transfers(self, timestamp, transfers, max_concurrent):  # 一批外部轉賬同時做，但真外部位會限流
    self._process_cashbacks(timestamp)  # 開工前先補返到期 cashback，避免餘額仲停喺舊數
    sem = asyncio.Semaphore(max_concurrent)      # 好似外部 API 只得 N 個窗口，一次最多放 N 單出去

    async def do_transfer(t):  # 每次處理一張外部轉賬單
        aid = t["account_id"]  # 呢張單實際上要喺邊個戶口扣錢
        lock = self.account_locks[aid]  # 同一個戶口好似同一個櫃位，一次只畀一張單改

        # 第一步：先做本地 fail-fast 檢查，唔合格就即刻踢走
        async with lock:                               # 改餘額同歷史之前，先鎖住個戶口
            if aid not in self.accounts:  # 連戶口都冇，呢張單根本冇得做
                return False                              # 即刻作廢，唔會去搶外部 API 名額
            if self.accounts[aid]["balance"] < t["amount"]:  # 餘額不足，好似客人卡入面唔夠錢
                return False                              # 一樣即場失敗，唔好白白排外面個 API 隊

            # 第二步：本地戶口過到關，就正式扣錢同落簿
            self.accounts[aid]["balance"] -= t["amount"]  # 真正喺戶口扣走呢筆錢
            self.accounts[aid]["outgoing"] += t["amount"]  # 將呢筆支出加落 outgoing，之後計 top spenders 會用到
            self.accounts[aid]["history"].append((timestamp, self.accounts[aid]["balance"]))  # 落簿，等之後查 statement 知道扣完之後仲剩幾多

        # 第三步：只得成功扣到錢嘅單，先入 semaphore 模擬外部過數
        async with sem:                                # 而家先去搶外部 API 窗口，避免無謂阻住其他真單
            await asyncio.sleep(0.01)                  # 模擬真正打去外部支付網關要等一陣

        return True  # 本地扣數同外部 call 都完成，呢張單先算真係做完

    tasks = []  # 收集每張轉賬單嘅 coroutine，等陣一齊放出去跑
    for t in transfers:  # 行晒成批外部轉賬單
        tasks.append(do_transfer(t))  # 先包成 coroutine，未真跑住
    results = await asyncio.gather(*tasks)  # 全部同時跑，各自靠 lock 同 sem 守規矩
    return list(results)  # caller 會收到每張單係成功定失敗，順序同原本 transfers 一樣

Hotel 同 Bank 嘅核心對照：
Bank account  → Hotel room
Bank balance  → Hotel total_revenue
Bank cashback → Hotel late_fee（lazy 收費）
Bank merge    → Hotel upgrade（搬人唔合併房）

Hotel 獨有嘅嘢：
guest_name == "" → available（可 book）
guest_name != "" → occupied（已入住）
checkout 唔刪 room，只係清空 guest_name
booking_id 自動遞增："booking1", "booking2", ...

import asyncio
from collections import defaultdict

class HotelSystem:
    def __init__(self):
        self.rooms = {}                                     # L1 room_id → room info dict
        self.booking_counter = 0                             # L1 自動遞增 booking ID
        self.rooms_locks = defaultdict(asyncio.Lock)         # L5 加：per-room_id 嘅 async lock