3 İşlemeler f406e18d15 ... 835fa2fbd5

Yazar SHA1 Mesaj Tarih
  zhangweijp 835fa2fbd5 refactor(italy): simplify plugin and consolidate tests 2 ay önce
  zhangweijp a22596f1fc refactor(italy): consolidate runtime for single-file hot updates 2 ay önce
  zhangweijp 62c2388999 feat(italy): integrate query-book workflow with automatic OTP and final verification 2 ay önce
59 değiştirilmiş dosya ile 18913 ekleme ve 501 silme
  1. 5 1
      .gitignore
  2. 17 1
      booker.py
  3. 10 2
      config/config_booker.json
  4. 72 1
      config/config_sentinel.json
  5. 5 0
      config/ita_query_account.example.json
  6. 32 8
      config/test_conf.json
  7. 148 0
      docs/italy-refactor/01-technical-design.md
  8. 88 0
      docs/italy-refactor/02-feasibility.md
  9. 89 0
      docs/italy-refactor/03-development-plan.md
  10. 147 0
      docs/italy-refactor/04-test-plan.md
  11. 68 0
      docs/italy-refactor/05-release-criteria.md
  12. 399 0
      docs/italy-refactor/06-execution-records.md
  13. 158 0
      docs/italy-refactor/07-reduction-inventory.md
  14. 79 0
      docs/italy-refactor/README.md
  15. 80 0
      docs/italy-refactor/records/W0-baseline.md
  16. 44 0
      docs/italy-refactor/records/W1-shared-lifecycle.md
  17. 751 0
      docs/italy-refactor/records/W2-login-preparation.md
  18. 572 0
      docs/italy-refactor/records/W3-query-entry.md
  19. 425 0
      docs/italy-refactor/records/W4-selection-readback.md
  20. 262 0
      docs/italy-refactor/records/W5-tools.md
  21. 294 0
      docs/vfs_plugin_deep_dive.md
  22. 1106 487
      plugins/ita_plugin.py
  23. 1 0
      test/ita/__init__.py
  24. 12 0
      test/ita/ita_source_sections.py
  25. 81 0
      test/ita/ita_test_fakes.py
  26. 310 0
      test/ita/test_add_ita_query_account.py
  27. 613 0
      test/ita/test_debug_ita_book.py
  28. 1212 0
      test/ita/test_debug_ita_book_gate.py
  29. 1578 0
      test/ita/test_debug_ita_calendar_gate.py
  30. 370 0
      test/ita/test_debug_ita_monitor.py
  31. 554 0
      test/ita/test_debug_ita_production_query_gate.py
  32. 861 0
      test/ita/test_debug_ita_query_book.py
  33. 26 0
      test/ita/test_debug_ita_reservation.py
  34. 571 0
      test/ita/test_debug_ita_soak.py
  35. 147 0
      test/ita/test_ita_booker_integration.py
  36. 230 0
      test/ita/test_ita_booking_final.py
  37. 614 0
      test/ita/test_ita_calendar_book.py
  38. 949 0
      test/ita/test_ita_calendar_book_flow.py
  39. 271 0
      test/ita/test_ita_calendar_query.py
  40. 446 0
      test/ita/test_ita_calendar_soak.py
  41. 292 0
      test/ita/test_ita_compact.py
  42. 16 0
      test/ita/test_ita_final_attribution.py
  43. 31 0
      test/ita/test_ita_final_evidence.py
  44. 39 0
      test/ita/test_ita_final_read_port.py
  45. 366 0
      test/ita/test_ita_local_handoff.py
  46. 121 0
      test/ita/test_ita_login_flow.py
  47. 165 0
      test/ita/test_ita_otp.py
  48. 1292 0
      test/ita/test_ita_plugin.py
  49. 363 0
      test/ita/test_ita_preflight.py
  50. 491 0
      test/ita/test_ita_protocol.py
  51. 330 0
      test/ita/test_ita_query_recovery.py
  52. 61 0
      test/ita/test_ita_reservation.py
  53. 250 0
      test/ita/test_ita_route_wiring.py
  54. 127 0
      test/ita/test_ita_shared_lifecycle.py
  55. 198 0
      test/ita/test_ita_single_file.py
  56. 689 0
      test/ita/test_ita_workflow.py
  57. 259 0
      test/ita/test_plugin_tester_ita_config.py
  58. 123 0
      utils/local_account.py
  59. 3 1
      vs_types.py

+ 5 - 1
.gitignore

@@ -31,6 +31,7 @@ env/
 !.env.example
 *.local
 secrets.json
+config/ita_query_account.local.json
 
 # —— Node(若子项目使用) ——
 node_modules/
@@ -63,6 +64,9 @@ logs/
 debug_pages/
 temp_browser_data/
 data/temp_browser_data/
+data/ita_query_profiles/
+data/ita_local_handoff/
+data/ita_soak/
 data/reg_session_*/
 data/proxy_states.json
 
@@ -78,4 +82,4 @@ data/**/*.png
 *.tmp
 *.temp
 
-downloads
+downloads

+ 17 - 1
booker.py

@@ -6,7 +6,7 @@ import random
 from datetime import datetime
 from typing import List, Dict, Callable, Optional
 
-from vs_types import GroupConfig, VSPlgConfig, Task, VSQueryResult, AppointmentType, AvailabilityStatus, GroupStatus, PluginStatus, utc_now_str
+from vs_types import GroupConfig, VSPlgConfig, Task, VSQueryResult, AppointmentType, AvailabilityStatus, GroupStatus, PluginStatus, utc_now_str, BookingOutcomeUnknownError
 from vs_plg_factory import VSPlgFactory
 from toolkit.thread_pool import ThreadPool
 from toolkit.vs_cloud_api import VSCloudApi
@@ -493,6 +493,8 @@ class OrderBookerGCO(BaseBookerGCO):
         task_data = None
 
         try:
+            if not task.book_allowed:
+                return
             with self.m_lock:
                 task_data = self.m_task_data_cache.get(str(task_id))
             if not task_data or task_data.get('status') in ['grabbed', 'pause', 'completed', 'cancelled']:
@@ -512,6 +514,20 @@ class OrderBookerGCO(BaseBookerGCO):
             else:
                 self._log(f"❌ BOOK FAILED for Order: {order_id}. Will retry on next signal.")
 
+        except BookingOutcomeUnknownError:
+            # Reuse the existing pause status/API. Never convert an uncertain
+            # website write into the ordinary "retry on next signal" branch.
+            with self.m_lock:
+                task.book_allowed = False
+                if str(task_id) in self.m_task_data_cache:
+                    self.m_task_data_cache[str(task_id)]["status"] = "pause"
+            try:
+                VSCloudApi.Instance().update_vas_task(str(task_id), {"status": "pause"})
+                self.redis_client.zrem(self.m_tracker_key, task_id)
+                self._remove_task(task, "booking outcome requires receipt review")
+                self._log(f"Task={task_id} paused: check its reservation before resuming.")
+            except Exception:
+                self._log(f"Task={task_id} blocked locally; cloud pause failed. Pause it manually before restarting.")
         except Exception as e:
             err_str = str(e)
             self._log(f"Exception during booking: {err_str}")

+ 10 - 2
config/config_booker.json

@@ -1631,7 +1631,7 @@
       "account_cd": 10800,
       "keep_alive": 120,
       "account_source": "order",
-      "booking_cooldown": 10,
+      "booking_cooldown": 45,
       "target_instances": 1,
       "max_bookings_per_account": 1
     },
@@ -1651,6 +1651,14 @@
       }
     ],
     "free_config": {
+      "query_mode": "services_probe",
+      "final_submit_enabled": false,
+      "apt_configs": {
+        "slot.dub.it.tourist": {
+          "service_id": 1321,
+          "capability": "services_probe_only"
+        }
+      },
       "capsolver_key": "03db1d1ff2f4a33e84ef1da99bd83336bed3710153525"
     },
     "version": 2,
@@ -1658,4 +1666,4 @@
     "created_at": "2026-08-23T15:08:14",
     "updated_at": "2026-08-23T16:09:43"
   }
-]
+]

+ 72 - 1
config/config_sentinel.json

@@ -1,4 +1,67 @@
 [
+  {
+    "identifier": "ita.hong_kong",
+    "enable": false,
+    "debug": false,
+    "need_account": true,
+    "need_proxy": true,
+    "proxy_pool": ["proxy-cheap"],
+    "proxy_cd": 300,
+    "session_max_life": 1800,
+    "active_time_start": "00:00",
+    "active_time_end": "23:59",
+    "website": "https://prenotami.esteri.it/",
+    "sentinel": {
+      "account_source": "built-in",
+      "account_pool_id": "hkg.it.sentinel",
+      "account_cd": 1800,
+      "target_instances": 1,
+      "signal_ttl": 30,
+      "query_wait": {
+        "mode": "Random",
+        "fixed_wait": 60,
+        "random_min": 60,
+        "random_max": 300
+      }
+    },
+    "plugin_config": {
+      "lib_path": "plugins",
+      "plugin_bin": "ita_plugin.py",
+      "plugin_name": "ita_plugin",
+      "plugin_proto": "IVSPlg"
+    },
+    "appointment_types": [
+      {
+        "city": "Hong Kong",
+        "country": "Italy",
+        "visa_type": "Tourist",
+        "routing_key": "slot.hkg.it.tourist",
+        "weight": 10
+      }
+    ],
+    "free_config": {
+      "website": "https://prenotami.esteri.it/",
+      "query_mode": "calendar",
+      "otp_mode": "cloud",
+      "final_submit_enabled": false,
+      "apt_configs": {
+        "slot.hkg.it.tourist": {
+          "service_id": 4937,
+          "capability": "single_schengen_tourism",
+          "calendar_scan": {"lookahead_months": 12},
+          "form": {
+            "booking_type_control_id": "typeofbookingddl",
+            "booking_type_value": "1",
+            "booking_type_labels": ["Prenotazione Singola", "Single booking"],
+            "purpose_control_id": "ddls_0",
+            "purpose_value": "42",
+            "purpose_labels": ["Turismo", "Tourism"]
+          },
+          "mail": {"authorization_source": "account"}
+        }
+      }
+    }
+  },
   {
     "id": 27,
     "node_id": "yecaoyun",
@@ -1721,6 +1784,14 @@
       }
     ],
     "free_config": {
+      "query_mode": "services_probe",
+      "final_submit_enabled": false,
+      "apt_configs": {
+        "slot.dub.it.tourist": {
+          "service_id": 1321,
+          "capability": "services_probe_only"
+        }
+      },
       "capsolver_key": "03db1d1ff2f4a33e84ef1da99bd83336bed3710153525"
     },
     "version": 2,
@@ -1728,4 +1799,4 @@
     "created_at": "2026-08-23T15:08:25",
     "updated_at": "2026-08-23T16:13:12"
   }
-]
+]

+ 5 - 0
config/ita_query_account.example.json

@@ -0,0 +1,5 @@
+{
+  "username": "",
+  "password": "",
+  "account_upload_token": ""
+}

+ 32 - 8
config/test_conf.json

@@ -281,28 +281,52 @@
       }
     },
     "ita_plugin": {
-      "group_id": "ita.dublin",
+      "group_id": "ita.hong_kong",
+      "debug": false,
       "account": {
-        "username": "ita_user@example.com",
-        "password": "ItaPassword123!"
+        "username": "johnnyzhang.luck@gmail.com",
+        "password": "Zhangwei123"
       },
       "appointment_types": [
         {
-          "city": "Dublin",
+          "city": "Hong Kong",
           "country": "Italy",
           "visa_type": "Tourist",
-          "routing_key": "slot.dub.it.tourist",
+          "routing_key": "slot.hkg.it.tourist",
           "weight": 10
         }
       ],
       "free_config": {
-        "website": "https://prenotami.esteri.it/Home",
+        "website": "https://prenotami.esteri.it/",
+                "query_mode": "calendar",
+                "otp_mode": "cloud",
+        "final_submit_enabled": false,
+        "apt_configs": {
+                    "slot.hkg.it.tourist": {
+                        "service_id": 4937,
+                        "mail": {
+                            "authorization_source": "account"
+                        },
+            "capability": "single_schengen_tourism",
+            "calendar_scan": {
+              "lookahead_months": 12
+            },
+            "form": {
+              "booking_type_control_id": "typeofbookingddl",
+              "booking_type_value": "1",
+              "booking_type_labels": ["Prenotazione Singola", "Single booking"],
+              "purpose_control_id": "ddls_0",
+              "purpose_value": "42",
+              "purpose_labels": ["Turismo", "Tourism"]
+            }
+          }
+        },
         "capsolver_key": "03db1d1ff2f4a33e84ef1da99bd83336bed3710153525"
       },
       "user_inputs": {
         "first_name": "SAN",
         "last_name": "ZHANG",
-        "email": "ita_user@example.com",
+        "email": "johnnyzhang.luck@gmail.com",
         "citizen": "China",
         "address": "Dublin",
         "expected_start_date": "2026-09-01",
@@ -365,4 +389,4 @@
       }
     }
   }
-}
+}

+ 148 - 0
docs/italy-refactor/01-technical-design.md

@@ -0,0 +1,148 @@
+# Italy 插件约 1000 行技术方案
+
+版本:1.1;日期:2026-09-01;配套:[入口](README.md)、[可行性](02-feasibility.md)、[测试计划](04-test-plan.md)。
+
+> 2026-09-01 用户确认的方案覆盖:Italy 调试阶段允许记录 OTP、Token 与敏感表单,后续再单独删除;最终提交失败、超时或结果未确认时按普通失败交回现有 Booker 重试。本文以下规范已按该决定更新;此前执行记录保留为历史证据,不再代表当前目标语义。
+
+## 1. 总体决策
+
+把 Italy 收敛为现有 Coordinate 框架中的薄网站适配器。采用现有 `IVSPlg` 接口、公共工具和少量网站专属函数;不新建插件内部调度框架、通用预约引擎或传输自动切换框架。
+
+```text
+现有 Sentinel → 池子账号的 ItaPlugin.query → VSQueryResult → 现有 Redis 信号
+现有 Booker   ← 信号 → 用户账号的 ItaPlugin.book → VSBookResult / 现有异常
+```
+
+Query 和 Book 使用独立的实例/会话;信号只携带公共查询结果。网站运行时 ID、Cookie、OTP、选中状态不跨账号传递。
+
+## 2. 必须保留的技术决策
+
+| 编号 | 决策 | 实现边界 |
+| --- | --- | --- |
+| T-01 | 单文件、约 1000 行 | 唯一 Italy 专属生产上传文件是 `plugins/ita_plugin.py`;不新增其运行时辅助模块 |
+| T-02 | 公共能力优先 | 先调用现有函数;确有通用缺口才向后兼容扩展公共模块 |
+| T-03 | Query 只查询 | 逐月扫描,首个正向月份停止,返回其中最早日期;不能把“进入表单”报告为真实有号 |
+| T-04 | Book 只预约 | 不调用公开 `query()` 伪装内部步骤;在用户会话重新检查库存、筛选日期、选择时段、提交和核验 |
+| T-05 | 多领区靠配置 | `apt_configs[routing_key]` 决定服务及表单差异;香港仅作样本,不硬编码服务、邮箱或日期 |
+| T-06 | 按证据选传输方式 | 无浏览器依赖的接口用 HTTP;依赖会话环境的读取可用公共浏览器 fetch;必要交互用浏览器 |
+| T-07 | 自动 OTP 复用云端 | 使用现有邮件 API,绑定当前账号与发送时间;邮件只用于提取预期验证码 |
+| T-08 | 会话准备共用、状态隔离 | Query/Book 可调用相同内部准备函数,但每个实例持有自己的账号、路由和会话状态 |
+| T-09 | 最终提交使用普通重试 | 每次 `book()` 调用在提交前复核选择且最多点击一次;失败、超时或结果未确认统一作为普通失败返回,由现有 Booker 在后续调度中重试,不保留 Italy 专属未知暂停状态机 |
+| T-10 | 诊断不支配生产结构 | 生产保留必要日志;当前调试阶段允许记录 OTP、Token 与敏感表单,不再保留专门的脱敏包装层。后续删除敏感日志是独立工作,不阻塞本轮精简 |
+| T-11 | 配置与公共接口兼容 | 保持 `IVSPlg`、公共返回类型和已部署配置含义;不再发布弱信号有号结果,旧探测入口需明确迁移 |
+| T-12 | 有行为证据才算完成 | 迁移业务测试,不通过删除失败测试、跳过测试或只测新辅助函数证明成功 |
+
+## 3. 文件与函数放在哪里
+
+### 3.1 `plugins/ita_plugin.py`
+
+建议只保留以下结构,名称可微调但职责不能扩散:
+
+- 导入、网站常量、少量解析函数和网站 DOM 脚本。
+- `ItaLoginFlow(BaseFlow)`:Italy 特有的首页、登录表单、验证等待及成功页判断。
+- `ItaPlugin(IVSPlg)`:公开接口和实例会话状态。
+- 私有业务步骤:解析路由、进入服务、准备日历、读取月份、读取时段、选中并核对、提交并核验回执。
+
+不为每个步骤建立一个类。配置可用项目现有 Pydantic 能力或简单结构集中校验;内部日历数据不再层层转换成多套“证明对象”。也不强制把所有逻辑塞进一个超长 `book()`。
+
+### 3.2 公共模块和测试工具
+
+- 已有公共能力继续留在 `utils/plugin_utils.py`、`utils/flow_engine.py`、`toolkit/vs_cloud_api.py`、`vs_types.py` 等现有位置。
+- 不把 Italy 的服务字段、领区配置、页面选择器或回执模板放进公共模块。
+- 测试与诊断可分文件,但运行时禁止依赖 `tools.*`、`test.*` 或另一份 Italy 私有实现。
+- 旧调试入口必须改为调用新公开接口或明确给出替代命令,不能留下导入已删除类型的损坏入口。
+
+## 4. 复用清单
+
+| 能力 | 现成参照 | 动作 | 必须处理的差异 |
+| --- | --- | --- | --- |
+| 浏览器/端口/代理/启动参数 | `plugin_utils.init_chromium_options`;VFS/TLS `create_session` | 直接复用,删除手写初始化 | 持久化目录由调用方提供,不能误删 |
+| 登录调度 | `flow_engine.BaseFlow/on/guard/done`;`TlsLoginFlow` | 复用调度,只写 Italy 页面规则 | 关闭会导致重复登录提交的停滞刷新;当前调试期可保留 OAuth/Token 诊断,后续统一清理 |
+| 鼠标/键盘及验证交互 | 现有 `HumanMouse`、`HumanKeyboard`、验证辅助代码 | 继续复用,去掉额外对象层 | 以页面真实就绪状态为准,不伪造验证成功、不无限重复尝试 |
+| 浏览器内 HTTP | `plugin_utils.perform_browser_fetch` | 对经验证可用的读取接口复用 | 校验状态、返回结构、会话归属;提交超时不走通道切换重发 |
+| 纯 HTTP | BLS 使用的现有 HTTP 库和会话模式 | 仅在 H-04 通过后采用 | 不复制 BLS 的网站字段,不新建统一客户端框架 |
+| 日期筛选 | `plugin_utils.filter_dates_in_range` | 使用 `shuffle=False` | 缺少一端时先补默认边界;最早日期不能依赖随机排序 |
+| 邮件读取 | VFS/BLS 的 `VSCloudApi.fetch_mail_content` | 直接复用 | Italy 仍须使用自己的发件人/模板约束和当前账号绑定 |
+| 返回值/异常 | `VSQueryResult`、`VSBookResult`、现有异常 | 直接使用 | 无号、认证失效和限流仍明确区分;最终提交未确认按宿主可重试的普通失败处理 |
+| 生命周期清理 | `cleanup_browser_workspace` | 复用主要能力 | 现有函数会忽略部分异常,持久化锁需保留失败处理 |
+| 池子/退避/信号/订单 | Sentinel、Booker、现有云端 SDK | 不改调度,不在插件重写 | 不增加第二套账号选择、Redis 协议或订单状态机 |
+
+公共清理函数是本轮唯一预先列出的公共扩展候选:提供可选严格模式或清理结果,默认调用行为不变。实际接口需先完成 H-02;若不需要扩展,优先零公共改动。
+
+新增公共能力必须说明真实消费者。优先有两个以上插件可直接复用;属于现有公共函数的通用结果补全时,也须验证原 VFS/TLS 调用不退化。不得仅把函数改名、移到 `utils` 就认定公共化。
+
+## 5. 6286 行如何减少
+
+下表是分区预算,不是已实现结果。分区允许互相调整,但完整文件预算仍为 1000 行。
+
+| 基线部分 | 基线行数 | 主要减法 | 目标行数 |
+| --- | ---: | --- | ---: |
+| 配置/协议/数据模型/校验 | 1146 | 一次入口校验,保留网站解析,删除重复类型和状态推导 | 140 |
+| Query/Book 日历 | 1348 | 一套月份读取与日期解析,两个明确的业务流程 | 180 |
+| 最终提交/预约记录/回执 | 1189 | 复用宿主普通失败/重试;只保留身份、选择、单次点击和最小成功判定 | 140 |
+| 表单/OTP/验证等待/工作流 | 1063 | 直接的准备函数;移除生产对验收报告的依赖 | 240 |
+| 插件入口/登录/会话/清理 | 1530 | 公共初始化与调度、简洁状态、既有宿主生命周期 | 220 |
+| 文件组织开销 | 10 | 统一导入与必要注释 | 20 |
+| 合计 | 6286 | | 1000 |
+
+统计包含空行、注释和内嵌 JavaScript,文件保留末尾换行。不以分号拼行、巨型字符串外置、动态加载旧代码等手法达标。提交验收时同时报告新增公共生产代码、删除代码和全仓净变化;超过预算必须先记录原因并取得用户对调整的确认,不能自行放宽。
+
+## 6. Query 合同
+
+输入为现有 `AppointmentType`,输出为现有 `VSQueryResult`。
+
+1. 根据 routing key 解析服务配置,确认当前账号/服务会话。
+2. 首次进入日历可完成网站要求的表单和 OTP;有效会话内不重复准备。
+3. 从当前查询起点按月升序扫描,最多扫描配置的月份数,不无限翻页。
+4. 首个正向月份出现后停止;从该月真实正向日期中取最早日期。
+5. 日历日期信号可不携带时段;Book 自己在用户会话重新读取。
+6. 当前月为空不等于所有月份无号;扫描达到约定范围且无正向结果才报告该范围无号。
+7. 查询不会触发 `InsertNewBooking`,也不会把进入 Booking 表单或 HTTP 200 当作有号证据。
+
+`services_probe`/`services_probe_only` 是现有兼容项。实施前逐项登记其消费者:保留作为内部服务入口检查或显式诊断,不再让生产 Query 把弱信号发布成真实档期。不支持的旧路由必须明确报配置能力不足,不能静默变成“无号”。
+
+## 7. Book 合同
+
+输入为 Query 信号和现有订单用户字段,输出为 `VSBookResult` 或现有框架异常。
+
+1. 验证申请人账号与当前 Book 会话一致;不能直接使用池子账号的 Cookie、验证码或时段 ID。
+2. 在申请人会话进入目标服务、完成必要准备,重新读取真实库存。
+3. 使用现有期望起止日期字段筛选;默认按日期、时段升序选择,不引入新的随机策略。
+4. 日期有号但时段已耗尽时,继续检查允许范围内的下一候选,不把旧 Query 信号当库存承诺。
+5. 提交前检查当前服务、日期、时段、容量与选中 DOM 一致;所有运行时 ID 来自当前 Book 会话。
+6. `final_submit_enabled=false` 时只走到选中并核对,不产生最终请求,返回 `success=false` 和明确的预提交标签。
+7. 开启提交且具备当前任务授权时,自动提交,不要求终端输入冗长确认句;一次 `book()` 调用最多点击一次最终按钮。
+8. 网站明确返回成功且能读到与当前申请人、服务、日期及时段相符的结果时返回成功;明确拒绝、超时、断线或证据不足均返回普通失败。
+9. 普通失败交回现有 Booker;后续信号/调度再次调用 `book()` 时必须重新进入服务、准备日历、重查库存并取得新的运行时 ID。仍健康的申请人登录会话可以复用,不强制重复登录;Italy 不维护跨调用的未知暂停状态或持久提交 fence。
+10. 禁止在同一次 `book()` 调用内自旋重提、切换通道重发,或复用上一次调用的运行时 ID;每次重试都从当前申请人会话和当前库存重新开始。
+
+网站回执可能提供分配到的具体时间,而不是选择时段的完整区间;须按已验证语义比较,不能为了简化错误要求两者字符串完全相同。
+
+## 8. OTP、配置和会话
+
+- 继续支持配置邮箱与按当前账号邮箱派生两种已存在的授权来源;不能固定某个测试邮箱。
+- 使用网站已观察的 `noreply-prenotami@esteri.it`、OTP 模板及发送时间窗口。后端 From/To 过滤不是发件人身份认证,不夸大其保证。
+- 邮件正文是数据,只提取预期 ASCII 验证码,不执行内容、不交给大模型。保留前导零;多个冲突验证码应拒绝。
+- 不以 `fetch-top` 作为自动回退读取旧验证码;超时不自动重发 OTP。
+- 保留自动 OTP,手动模式仅作为显式调试能力;不得为精简恢复成强制人工接码。
+- 当前调试阶段允许日志、测试输出和诊断快照包含 OTP、Token 与敏感表单;不再以脱敏包装和“不落日志”测试作为本轮准出条件。账号密码、配置文件和真实秘密仍不得因此写入 Git。
+- 会话状态合并为少量字段,但保留账号、路由、浏览器实例、有效期和准备状态绑定。
+- 生命周期仍由宿主驱动;持久化目录复用、清理失败、跨实例恢复的既有行为必须有迁移清单,不能无声删除。
+- `set_config`、`query_mode`、`otp_mode`、`apt_configs`、提交开关等现有使用方式需做兼容测试;新增必填项须先获得确认。
+
+## 9. 传输方式与禁止事项
+
+优先采用已验证路径。浏览器流程已具备历史证据;日历 API 经 H-04 对照证明等价后,才用公共浏览器 fetch 或纯 HTTP 替换对应步骤。网络错误不代表应在同一次调用中切换账号、IP 或传输方式;最终写操作的普通重试由后续 Booker 调度重新进入完整 Book 准备流程,健康的已认证会话可继续使用。
+
+本轮禁止:新调度器、新 OTP 服务、新通用协议校验框架、新的 Italy 私有辅助运行时、新打包/动态执行方案、为凑行数删除结果核验或必要测试。
+
+## 10. 代码证据导航
+
+以下为基线符号位置,未来行号可变化,以符号名和 Git 提交为准:
+
+- [公共浏览器与工具](../../utils/plugin_utils.py):初始化、fetch、日期、清理。
+- [公共流程调度](../../utils/flow_engine.py):`BaseFlow`;[TLS](../../plugins/tls_plugin.py):`TlsLoginFlow`、`create_session`。
+- [VFS](../../plugins/vfs_plugin.py)、[BLS](../../plugins/bls_plugin.py):公共 API、OTP 与网站特有业务分工。
+- [Italy 基线](../../plugins/ita_plugin.py):协议解析、原生日历和提交、回执核验。
+- [接口](../../vs_plg.py)、[公共类型](../../vs_types.py)、[Sentinel](../../sentinel.py)、[Booker](../../booker.py)。
+- [安装器](../../utils/plugin_updater.py)、[工厂](../../vs_plg_factory.py)、[热更新入口](../../main.py)。

+ 88 - 0
docs/italy-refactor/02-feasibility.md

@@ -0,0 +1,88 @@
+# 可行性分析、假设与风险
+
+版本:1.1;日期:2026-09-01;依据:[技术方案](01-technical-design.md)。
+
+> 方案覆盖 CR-001:用户已明确接受调试阶段记录 OTP、Token 与敏感表单,并接受最终提交按普通失败由 Booker 后续重试。旧的“敏感信息绝不落日志”和“未知结果必须暂停”证据仅描述历史实现,不再是当前架构前提。
+
+## 1. 结论
+
+精简方向具备明确可行性:当前 Italy 大量重复了已有浏览器初始化、流程调度和内部校验;公共接口、网站协议及查询到预提交的历史证据已经存在。
+
+但“可以明显减少代码”不等于“1000 行版本已经可靠”。约 1000 行是本次交付目标,能否在保留全部必要行为的前提下达到,必须由实际重构、行数统计和行为测试证明。不能保证外部网站持续有号或不改变页面,也不使用“100% 信心”替代证据。
+
+约 1000 行的新版本尚未完成。W1、W2 及 W3/W4/W5 局部改动已有证据,见 [执行记录](06-execution-records.md);R5 后当前 2598 行,比 6286 行基线减少 3688 行,仍需净减约 1598 行,不能据此宣称总预算可行性已经证明。R2 已统一 Query/Book 月份表示,R3 已删除 Italy 专属提交状态机,R4 已把表单准备压成五字段合同,R5 已把持久 profile、锁和诊断观察状态移出生产。R5 实际只净减 154 行,说明剩余预算必须从日历捕获、选择和表单脚本的重复协议表示中取得;不能靠继续清理入口或修改其他插件达标。以下所有未执行实验保持待验证,不把离线结果标成现场通过。
+
+## 2. 已有证据及其边界
+
+| 证据 | 已能说明什么 | 不能说明什么 |
+| --- | --- | --- |
+| 代码基线 `a22596f1fcdffb946960724ef299f249e7860891` | Italy 是 6286 行单文件,VFS/TLS 已调用公共工具 | 不能证明压缩后仍正确 |
+| 公共 `init_chromium_options`、`BaseFlow` 等源码 | 可替换一部分重复机制 | 不能直接证明持久化清理、登录刷新语义完全等价 |
+| 用户历史 Query 日志 | 旧版本曾逐月查到最早日期、首个正向月份停止 | 不能证明当前库存、纯 HTTP 可用或新版本已通过 |
+| 用户历史自动 OTP/Book 预提交日志 | 旧版本曾自动读码、进入日历、选中可用时段,最终请求为 0 | 不等于真实预约成功,更不等于重构后的成功 |
+| 现有最终提交、回执解析及测试源码 | 已有可迁移的请求字段和核验逻辑 | 不能替代新版本真实提交与回执验收 |
+| 单文件安装器和工厂 | 现有交付路径只需 Italy 插件文件及已安装宿主公共依赖 | 新公共 API 不会随插件单文件自动安装 |
+
+文档建立时未重新运行原业务测试;其后 [W0](records/W0-baseline.md) 已补齐基线,[W1](records/W1-shared-lifecycle.md) 和 [W2 已实现部分](records/W2-login-preparation.md) 已回归。没有访问真实站点或邮箱,不能据此证明现场登录、API 等价或真实预约成功。
+
+## 3. 假设与验证计划
+
+| 编号 | 假设/问题 | 验证办法 | 通过标准 | 不通过怎么办 |
+| --- | --- | --- | --- | --- |
+| H-01 | 公共初始化和 `BaseFlow` 可替代自建生命周期 | 对照新旧选项、登录页面序列和错误分支;模拟一次提交后长时间停留 | 参数等价,能到认证页,凭据只提交一次,无额外刷新 | 保留必要 Italy 页面规则,不复制整套调度器;记录公共缺口 |
+| H-02 | 公共清理足以兼容持久化目录/锁 | 模拟页面退出失败、隧道失败、目录删除失败及二次清理 | 不删持久化目录,不误判释放完成,不让另一实例接管仍占用目录 | 使用小范围向后兼容扩展,先验证 VFS/TLS 原调用 |
+| H-03 | 一套月份读取可服务 Query 和 Book | 同一组日历夹具驱动两个公开接口;不同账号/服务/日期范围交叉测试 | 共用解析与读取但不共享 Cookie、运行时 ID、选中状态 | 仅保留必要的业务分支,不复制整套扫描流程 |
+| H-04 | 日历接口可替代部分 UI 操作 | 先以脱敏样本确认请求参数,再在获授权会话中比较原生请求与候选读取方式 | 同服务、同月份结构与语义一致,无预约写入,无认证/验证回退 | 保留原生浏览器读取;不阻塞其他精简,也不宣称纯 HTTP 可用 |
+| H-05 | 减少模型层不会削弱协议判断 | 双重 JSON、日期、库存、运行时 ID、未知结构和边界值回归 | 异常仍明确失败,不把错误当无号;正向样本一致 | 修正集中解析边界,不恢复层层重复对象 |
+| H-06 | 表单/OTP 可压缩为一个准备步骤 | 模拟字段延迟、验证码前导零、过期/旧码、验证等待与多次 Query | 有效会话只准备一次;发送/读取有界;账号绑定不变 | 修正准备状态,不增加新的邮件服务或自动重发策略 |
+| H-07 | 薄提交路径可使用宿主普通重试 | 注入成功、拒绝、丢包、超时、错误回执及连续两次独立调用 | 单次调用最多一次最终点击;可确认成功才返回成功;其余返回普通失败;下一次调用重新准备/重查/选择,不复用运行时 ID;健康登录可复用 | 若宿主不能重试普通失败,先修正适配或配置;不在 Italy 内新增重试调度器 |
+| H-08 | 完整实现可收敛到约 1000 行 | 每个工作包统计文件行数和新增公共代码;在 W3/W5 重估剩余预算 | 总预算成立、无隐藏 Italy 运行时文件、主流程可读 | 提交具体超预算原因与替代方案,用户确认前不扩大上限 |
+| H-09 | 领区差异可由现有配置表示 | 至少两个不同服务 ID、路由及表单取值的合成配置;香港现场一次 | 无香港/邮箱/日期硬编码,错误领区不继续提交 | 显式标为配置能力缺口;不谎称所有领区已实测 |
+| H-10 | 工厂热加载及现有宿主不受影响 | 单文件安装、两个版本重载、多实例及真实宿主方法离线测试 | 新实例用新代码,旧实例停止,共享公共类型和暂停语义不丢失 | 修复加载/绑定,不新建打包器或自定义缓存框架 |
+| H-11 | 私有接口精简不会损坏常用工具 | 盘点所有导入 Italy 私有类型的测试/调试工具,逐项迁移并执行 | 现行支持命令可启动且调用新实现;废弃命令有明确替代 | 不发布留有隐蔽 ImportError 的工具集,不用旧实现充当兼容层 |
+
+H-04 为可选优化实验;其他假设关联必需行为或结构验收。未通过 H-04 时,以浏览器路径完成同样的约 1000 行目标,不降低 Query/Book 范围。
+
+## 4. HTTP 可行性实验的具体边界
+
+1. 只选择已有协议证据的日历/时段读取请求。`POST` 不一定是写入,`GET GenerateOTP` 也不是无副作用;按实际业务作用分类。
+2. 当前账号、服务和月份固定;原生浏览器结果与候选结果可保留完整调试摘要,包括本轮用户允许的 Token 或敏感表单。
+3. 至少覆盖无号月、正向月、选中日期时段和认证失效;并发库存变化导致差异时,不能硬判等价,需重新取得可比较样本。
+4. 记录响应状态、路径、字段、月份、正向日期集合和请求副作用;当前阶段允许调试输出包含 Cookie/Token、验证码和敏感表单,但不得因此把真实秘密写入 Git。
+5. 没有授权或真实条件不足时,只报告离线验证,候选传输路径不成为默认实现。
+6. 不通过增加账号/IP轮换、重复登录、无限重试来“证明 API 可用”。
+
+## 5. 主要风险与处理
+
+| 风险 | 影响 | 处理 |
+| --- | --- | --- |
+| 为凑行数删除了关键行为 | 假阳性有号、错号或重复预约 | 行数与行为双验收;RC-01 不能替代其余准出条目 |
+| 用 `utils` 隐藏专属代码 | Italy 看起来短,项目仍然复杂 | 统计新增公共代码与真实消费者;禁止 Italy 专属运行时外移 |
+| 直接复用公共函数改变语义 | 排序随机化、重复登录或持久化目录被删 | H-01/H-02;调用参数和异常语义单独回归 |
+| 网站文案、DOM、库存变化 | 测试环境不稳定 | 结构化字段优先,未知结构明确报错;保留脱敏样本及实测日期 |
+| 邮件服务超时或返回旧内容 | 错码、连续发码、风控 | 保留时间窗和账号绑定,单次发送/读取,不回退 `fetch-top` |
+| 清理失败掩盖已成功预约 | 下一次普通重试可能再次预约 | 单次调用只点击一次并尽量读取结果;失败交回 Booker。此重复风险由用户在 CR-001 中明确接受,不再用 Italy 专属暂停状态机规避 |
+| 旧调试工具紧耦合旧类 | 插件可用但验收命令损坏 | W0 先列消费者清单;W5 统一迁移,不保留第二套生产实现 |
+| 新公共 API 未部署到宿主 | 单文件更新后 ImportError | 优先零新增公共依赖;有扩展则记录最低宿主提交和部署顺序 |
+| 现场没有号/账号不可用 | 无法证明真实提交成功 | 继续离线和预提交验收;不能标记 RC-09 完成,也不能占用无关预约 |
+
+## 6. 可行性判断更新方式
+
+每个工作包结束更新相关 H 编号:待验证、通过、失败或条件成立。必须附代码版本、测试编号/命令和观测结果。
+
+截至最新 [W3](records/W3-query-entry.md) / [W4](records/W4-selection-readback.md) 记录:
+
+- H-01、H-02 已列离线场景有通过证据,现场效果仍待 W6;仅供 soak 的跨实例 checkpoint 已从插件公开入口归位工具,生产 Sentinel/Booker 仍按 `health_check → cleanup → create_session` 重建。H-06 的表单、OTP 绑定及服务入口已收敛为同一五字段合同和线性准备流程,相关离线场景通过;真实网站仍待 W6。
+- H-03 的共用月份捕获已有离线证据:真实公开 Query 与 Book 共用 `_capture_month`,但账号、页面和运行时参数各自持有;申请人侧旧日期已售罄时选择其下一候选。该测试没有替换 `query()`/`book()` 或在测试内重写业务算法。H-04 已有显式、默认关闭的只读对照探针和离线错误/副作用测试;尚未在获授权现场同时取得空月与正向月等价证据,因此生产仍不切换。
+- H-05 的库存模型、统一解析及页面读回已部分收敛。每个 Book 捕获响应只解析一次,候选筛选/DOM 等待已合并;日期和时段脚本现使用同一五字段语义合同,但内部仍逐项检查最后一位库存、冲突计数、服务/日期/ID/时间/容量、CSS、只读不得点击和点击前账号变化。第一轮实际 Node 测试发现并修复点击后日期漂移未绑定选中语义的问题;当前 Italy 385 项、调试 280 项通过,不代表整个协议/模型层已精简完毕。
+- H-06 的当前准备上下文已统一,普通 Query 的读取前后与准备登记中均核对身份;生产不再导出跨实例恢复参考。soak 工具的受控恢复仍只保存 route/账号/profile/URL/服务比较值,并由迁移后的参数化测试覆盖,现有手动诊断和自动 OTP 合同保留;现场仍待验证。
+- H-07 已有当前离线证据:严格匹配的明确成功才返回成功;网站拒绝、监听超时和请求不匹配均在一次点击后返回普通失败并清除日历准备;错误申请人或已清除上下文不会点击;原 `OrderBookerGCO` 在失败后保留任务,并可在下一信号完成新的服务/日历准备后再次调用。真实网站成功与跨进程现场调度仍待 W6,因而 RC-05/09 尚不能整体通过。
+
+表单收拢补充:生产与现有日历调试入口现在使用同一有边界校验的脚本生成器。两套配置、重复业务控件、原生 change 离页和两阶段 OTP 的实际 Node 证据已增加;原账号/发送窗口、单次 OTP、单次提交及回执规则未修改。R4 将约二十字段快照收为五个布尔事实,删除生产阶段枚举、日志门禁及恢复状态类,2823 → 2752、净减 71 行。`utils/network_interceptor.py` 会暂停并修改请求,不能替代被动计数器。该下降不证明 H-08 已通过,也不把公共模块“有类似名字”当作可复用证据。
+- H-08 尚未达标;W3 结束必须用实际剩余结构重估预算,不能把分区目标当作可行性证明。
+- H-10/H-11 已迁移 Book 入口、诊断消费者和旧文档账号池命令:公开 Book 的热加载测试验证自身版本函数绑定;表单结构/日期格式/服务表统计仅在调试工具执行;账号池 Query 共用现有 SDK、分组、邮箱校验和 `PluginTester`,且禁止最终提交。原脱敏、错误路径和只读断言保留。该消费者已通过 27 项离线测试,但其他工具、热更新、两领区和完整预算仍须继续验收。
+- Book 同日排序已改为方案要求的时间升序;新增回归明确验证较晚时段余量更多也不能抢先。修改的是旧实现,不是倒改技术方案。
+
+其他假设不得因旧代码测试通过自动改为“新方案通过”。
+
+如果需要超过行数预算、改变配置含义或放弃已要求的行为,属于方案变更,不是“实现细节”。先按 [执行记录](06-execution-records.md) 提交变更,再由用户决定。

+ 89 - 0
docs/italy-refactor/03-development-plan.md

@@ -0,0 +1,89 @@
+# 开发周期与工作包安排
+
+版本:1.1;日期:2026-09-01;依赖:[技术方案](01-technical-design.md)、[可行性](02-feasibility.md)、[测试计划](04-test-plan.md)。
+
+> CR-001 已获用户确认:W2/W4 不再为敏感日志脱敏和未知提交暂停保留专属结构;W4 改为验证单次调用一次点击、普通失败交回 Booker、后续调用完整重试。
+
+## 1. 周期怎么理解
+
+按一名熟悉项目的工程师、已有本地依赖可用估算,净工程投入约 **6.5–9 个工作日**,包含测试迁移、回归及文档记录,不只是改插件的时间。自动化与代码复用可以缩短实际耗时;不要求等满估算天数才进入下一项。
+
+真实预约验收取决于账号、OTP、网站状态和实际档期,等待窗口单独记录,不承诺日历日期。下表是原始净投入估算,不是从今天重新计算的交付承诺,也不是完成证明;当前 W0 已建基线、W1 已离线回归,W2/W3/W4 仅部分收敛。W5 的旧文档账号池命令已迁移并通过离线回归,但约 1000 行预算及 W5 其余条件仍未完成;实际进度、返工和剩余估算以 [执行记录](06-execution-records.md) 为准。
+
+## 2. 工作包与交付物
+
+| 工作包 | 估算 | 主要工作与代码位置 | 前置条件 | 验证/交付 |
+| --- | --- | --- | --- | --- |
+| W0 行为与消费者基线 | 0.5 天 | 盘点 `plugins/ita_plugin.py`、相关 `tools/`、`test/`;核对用户已有改动 | 用户确认文档及实施范围 | 现有行为测试结果、配置消费者表、私有符号迁移表;T-11/T-12、H-11 |
+| W1 公共能力接入 | 0.5–1 天 | 替换手写初始化/日期筛选/清理;主要改 Italy,公共模块只补必要缺口 | W0 基线明确 | UT-01/02/03;公共消费者回归;H-01/H-02 |
+| W2 登录与会话准备收敛 | 1 天 | 使用 `BaseFlow`,合并表单/验证等待/OTP准备与会话状态 | W1 验证通过 | UT-04/05/06;错误/重复调用测试;H-06 |
+| W3 Query/日历共用 | 1–1.5 天 | 共用读取/解析,逐月最早日期;保留 Book 可调用的内部读取步骤 | W2、H-03/H-05 有证据 | UT-07/08/09、IT-01;扫描与准备次数;可选 H-04 对照 |
+| W4 Book 与最终核验收敛 | 1–1.5 天 | 申请人库存重查、日期/时段选择、单次调用一次点击、最小成功判定和普通失败 | W3 共用日历稳定 | UT-10/11/12/13、IT-02/03;H-07 |
+| W5 工具、热更新和全量回归 | 1–1.5 天 | 迁移旧私有调用、支持命令、单文件加载;公共改动回归 | W1–W4 完成 | UT-14/15、IT-04/05/06;行数及净变化报告 |
+| W6 现场与发布验收 | 1–1.5 天净投入 | 先 Query,再 Book 预提交,再有授权的真实预约;更新执行记录 | 离线通过;用户现场条件/授权具备 | LT-01/02/03;逐项 RC 验收、发布/回退说明 |
+
+W6 的实际等待时间不包含在净投入内。任何任务发现新协议或外部依赖问题,先更新 H 编号、估算和影响,不以“再补几行”无限扩展。
+
+### 2.1 阶段执行对照表
+
+各阶段都以 01 技术方案为约束、02 的假设为待验证问题、04 为测试依据、05 为最终准出标准,并把结果写入 06。下表是执行索引,不另造一套流程或重复生成报告;“阶段完成”只说明本阶段证据齐备,不表示关联 RC 已通过全部离线和现场验收。
+
+| 阶段 | 必须核对的技术/假设 | 必须留下的阶段完成证据 | 关联准出 |
+| --- | --- | --- | --- |
+| W0 | T-01/T-11/T-12;H-08/H-11 | 带版本的行数、旧行为测试结果、配置和工具消费者清单;已有失败与本次回归分开记录 | RC-01/07/10 |
+| W1 | T-02/T-08;H-01/H-02 | UT-01/02/03、IT-06;实际复用函数、删除的重复实现、公共消费者兼容结果及净行数变化 | RC-02/08 |
+| W2 | T-05/T-07/T-08;H-01/H-06 | UT-04/05/06;登录、延迟表单、自动 OTP、重复调用与账号/会话隔离的离线证据 | RC-04/06/07 |
+| W3 | T-03/T-05/T-08;H-03/H-05/H-08 | UT-07/08/09、IT-01;首次正向月停止、最早日期、范围耗尽、无最终请求及剩余行数预算 | RC-01/03/07 |
+| W4 | T-04/T-09;H-03/H-07 | UT-10/11/12/13、IT-02/03;申请人重查、选择一致性、单次调用一次点击、普通失败和下一次独立重试的离线证据 | RC-04/05 |
+| W5 | T-01/T-02/T-11/T-12;H-08/H-09/H-10/H-11 | UT-14/15、IT-04/05/06 及完整相关回归;约 1000 行和净变化、两套领区配置、单文件热更新、可执行的现行命令 | RC-01/02/07/08/10 |
+| W6 | T-03/T-04/T-07/T-09;所有尚需现场验证的假设 | LT-01/02/03;同一待发布版本的真实查询、预提交和受控预约回执,逐项填写最终 RC 记录 | RC-03/04/05/06/09/10 |
+
+H-04 仅在获授权验证并通过后,才允许更换相应的读取通道;没有通过则沿用浏览器路径,不阻止其他工作。开始、执行、结束均使用同一组编号;如果本阶段还有必需证据缺失,标记“部分完成”并列缺口,不自动放宽后续条件。
+
+## 3. 实施顺序
+
+```text
+W0 基线 → W1 公共能力 → W2 登录/准备 → W3 Query → W4 Book → W5 集成 → W6 现场
+```
+
+- 不一口气删掉 5000 行后才测试。
+- 每个工作包保持独立可审查的差异;Git 提交是否执行取决于用户授权。
+- 不依赖后一步的测试可以提前编写,但不能用提前写好的测试代替当前结果。
+- H-04 的 HTTP 对照是可选支线,失败不阻塞浏览器方案的其他工作。
+- W3 和 W5 必须重新核对总行数预算,提前暴露超支,不能直到发布前才发现仍有数千行。
+
+当前优先顺序:R1–R5 已完成,Italy 为 2598 行。R3 已用现有 Booker 的普通失败/后续信号重试替换跨调用 fence、未知暂停和复杂 reconciliation;R2 已合并 Query/Book 的月份与候选表示;R4 已把表单/OTP/Turnstile 约二十字段快照收为五个布尔事实;R5 已将持久 profile、锁和诊断观察状态归位 Italy 工具,并保持公共模块及 VFS/TLS/BLS 零改动。下一结构包重新审计日历捕获、选择及表单脚本的重复表示。不能把消费者修复、夹具或整理导入当作整体完成;W3/W4/W5 的局部产物不代表现场最终提交验收通过。
+
+结构性减量按 [生产代码精简盘点](07-reduction-inventory.md) 的 R1→R3→R2→R4→R5 执行;五包当前均已完成。由于 2598 行仍未满足 RC-01,后续结构包继续使用本文件的记录、测试和准出规则,不修改其他插件换取 Italy 行数。
+
+本次周期复核:R3 为 3532 → 2883、净减 649 行;R2 为 2883 → 2823、净减 60 行;R4 为 2823 → 2752、净减 71 行;R5 为 2752 → 2598、净减 154 行。当前 Italy 384 项、调试 280 项、框架离线 75 项、配置/账号 27 项通过。生产 checkpoint/restore、预约列表/详情读取、跨调用 fence、未知暂停、提示日期优先双扫描、重复月份结果类、二十字段表单快照、生产阶段枚举、持久 profile/锁和诊断观察字段已删除;明确响应判定及底层网站事实仍保留。当前仍需净减约 1598 行;下一包必须以真实剩余结构重新盘点,不重复开发已经统一的协议、选择、OTP 或宿主重试能力,也不自行放宽总预算。
+
+## 4. 每个工作包开始前的检查
+
+1. 引用本包对应 T/H/UT/IT/LT/RC 编号。
+2. 读取将修改的函数及现成参照,列出“复用、保留、删除、合并”清单。
+3. 记录涉及文件、是否影响 VFS/TLS/BLS、配置兼容及热更新依赖。
+4. 记录本包前后的预计行数;确认没有新增 Italy 私有运行时模块。
+5. 确认本次授权范围,不能把开发权限当成真实预约或部署权限。
+
+## 5. 每个工作包结束时的检查
+
+按 [执行记录模板](06-execution-records.md) 填写:
+
+- 实际修改、引用的现成能力和删除的重复结构。
+- 运行过的精确命令、代码版本/工作区指纹、退出码、测试数量及失败明细。
+- 原有业务断言迁移到哪里;哪些仅绑定旧内部结构的测试被替换及原因。
+- Italy 完整行数、新增公共代码行数、全仓生产代码净变化。
+- 未解决问题、相关假设状态和下一步;没有证据的项目仍为待验证。
+
+## 6. 用户需要配合的环节
+
+离线重构不需要用户反复操作。W6 才集中配合:确认测试账号和领区、确认邮箱授权可用、完成网站要求的人工验证,并在真实提交前确认本轮允许预约的用户与日期范围。
+
+已明确授权的真实提交运行无需额外输入完整确认句;但开发脚本不能默认提交,也不能把过去另一轮授权用于新增账户或范围。
+
+## 7. 进度更新规则
+
+进度用“已完成工作包+当前可验证产物+剩余阻碍”表达,不用已删行数代替完成度。
+
+如果公共模块扩展、HTTP 假设或回执核验导致返工,更新文档和剩余估算。不得为了赶周期改成手动 OTP、单账号 Query/Book、香港硬编码或不核验真实预约的缩水版本。

+ 147 - 0
docs/italy-refactor/04-test-plan.md

@@ -0,0 +1,147 @@
+# 测试计划与需求追溯
+
+版本:1.1;日期:2026-09-01;依据:[技术方案](01-technical-design.md)、[可行性](02-feasibility.md)。
+
+> CR-001 覆盖说明:敏感日志脱敏不再是本轮测试目标;提交失败、超时和未确认结果按普通失败进入 Booker 后续重试。下方历史回归叙述中的“未知暂停/脱敏”只说明当时版本,不作为新实现必须保留的行为。
+
+当前状态:以下为实施与验收要求,不是已执行结果。新版本测试证据填写在 [执行记录](06-execution-records.md)。
+
+## 1. 测试策略
+
+1. 先建立旧实现的业务行为基线,再改代码。
+2. 单元测试覆盖协议、表单、会话、查询、选择、提交与回执边界;集成测试调用真正的公开接口和宿主方法。
+3. 离线使用合成账号、脱敏网页/响应夹具、模拟浏览器和外部服务;不得因运行测试意外读取真实邮件或创建预约。
+4. 真实验收依次执行 Query、Book 预提交、获授权的单次真实提交。
+5. 旧版本或前一工作包的历史通过结果不能自动继承;测试数量不是质量指标,但每个业务断言必须有迁移去向。
+
+## 2. 测试代码组织
+
+- 沿用现有 `test/`、unittest 和 `tools/plugin_tester.py`;Italy 专属测试与测试辅助模块统一放在 `test/ita/` 包内,避免继续散落在通用测试根目录。
+- 当前公开合同的精简行为测试位于 `test/ita/test_ita_compact.py`;后续 Italy 新测试继续进入 `test/ita/`,只有被多个插件真实消费的测试辅助能力才考虑放到通用测试目录。
+- 不为维持旧测试导入而保留第二份旧运行时,也不在测试中重新实现业务算法。
+- 只淘汰依赖旧类名、旧文件分区、初次机械搬迁逐字一致的结构断言;核心行为迁移后原断言的去向记入 W0/W5 表。
+- 数据夹具只保留协议相关字段;禁止提交密码、Cookie、Bearer、真实 OTP、邮件授权码和完整个人资料。
+
+## 3. 单元/适配器测试矩阵
+
+每个编号是一组场景,不能只写一个快乐路径用例就标记整组通过。
+
+| 编号 | 场景与注入条件 | 必须观察到的结果 | 决策 |
+| --- | --- | --- | --- |
+| UT-01 | 公共初始化:无代理、直连代理、认证代理、浏览器路径、持久化目录 | 使用公共函数;参数正确;不重复启动浏览器,不另造端口/隧道实现 | T-01/T-02 |
+| UT-02 | 清理:正常、重复调用、页面退出失败、隧道失败、删除失败、仍占用锁 | 只清理实例拥有的资源,不删除持久化目录;失败不伪装成功,不误释放占用 | T-02/T-08 |
+| UT-03 | 日期:两端/单端/无偏好、非法日期、起点晚于终点、跨年 | 默认边界明确;升序、包含边界;非法配置明确失败 | T-02/T-04 |
+| UT-04 | 登录:延迟 DOM、停留登录页、验证页、错误凭据、错误域名、超时 | 到认证 DOM 才成功;凭据至多提交一次;不靠停滞刷新重提;调试日志可包含 Token/敏感表单,不要求专属脱敏器 | T-02/T-08/T-10 |
+| UT-05 | 表单:控件未加载、选项文字/值不匹配、隐藏字段不同步、未知必填项、验证未就绪 | 就绪前不发 OTP/AVANTI;不能跳过新必填项;超时有界;提交后等待真实日历就绪 | T-05/T-07/T-08 |
+| UT-06 | OTP:前导零、重复的相同码、冲突码、过期、旧码、错误邮箱、无权限、504、HTML/指令文本 | 保留前导零;冲突/过期拒绝;绑定本次账号和时间;不执行正文;无自动旧码回退/重发;允许日志记录验证码 | T-07/T-10 |
+| UT-07 | 协议:双重 JSON、空数组、畸形 JSON、HTML 200、缺字段、错误日期/时段、非法/重复 ID | 单一解析边界给出可分类错误;错误不变成无号或成功 | T-03/T-04/T-12 |
+| UT-08 | 库存:`SlotLiberi=1, SlotRimanenti=0`;`0,-1`;冲突、负值、布尔伪整数 | 已验证正向样本可用;零库存不可用;冲突/未知语义拒绝;不能用 `SlotRimanenti>0` 漏掉最后一位 | T-03/T-04 |
+| UT-09 | Query:当前月空、后续月正向、月内无序、跨年、范围耗尽、翻月不前进、服务变化、重复 Query | 返回首个正向月份的最早日期;之后不再翻月;有效会话不再 OTP;最终提交数为 0;配置两领区隔离 | T-03/T-05/T-08 |
+| UT-10 | Book:不同用户、过期/较晚 Query 信号、日期范围、Query 提供的外部时段 ID、同日时段余量不同、售罄、下一候选 | 用申请人自己会话重查;Query 日期只唤醒、不覆盖申请人库存中的更早日期;按方案的日期/时段顺序选择允许范围,不能被余量排序悄悄覆盖;不复用池子运行时 ID;找不到时返回明确无可预约结果 | T-04/T-05/T-08 |
+| UT-11 | 选中:不可用 CSS、日期 DOM 不一致、时段/ID/余量不同、控件缺失;预提交开关关闭 | 选择不一致时不能提交;预提交模式最终请求数 0,结果不是成功 | T-04/T-09 |
+| UT-12 | 提交:成功、明确拒绝、超时、断线、响应结构变化、提交后异常、连续两次独立调用 | 每次调用最多一次最终点击;可确认成功才成功;其余为普通失败;后一次调用从新会话/新库存开始,不复用旧运行时 ID | T-09 |
+| UT-13 | 结果:旧记录、同日他服务、错误日期/时间、数量变化但归属不明、结构冲突 | 当前调用能明确归属才成功;不完整或冲突按普通失败;不要求生产维护复杂历史 reconciliation 或未知暂停状态 | T-04/T-09 |
+| UT-14 | 配置:至少两套服务/表单/路由;现有模式及旧探测配置;动态邮箱 | 无香港或固定邮箱;旧弱探测不发布成真实有号;不支持配置明确诊断,不静默改含义 | T-05/T-11 |
+| UT-15 | 源码结构:行数、导入、公开接口、公共消费者、正常排版、测试迁移清单 | 约定预算满足,无额外 Italy 运行时/旧实现加载,不跳过失败业务测试 | T-01/T-02/T-10/T-12 |
+
+## 4. 集成测试矩阵
+
+| 编号 | 验证范围 | 通过条件 |
+| --- | --- | --- |
+| IT-01 | 真正 `ItaPlugin.query()` → `VSQueryResult` → 现有 Sentinel 信号序列化 | 正确最早日期、routing key、公共状态;信号不含 Cookie/OTP/运行时 ID;过期和无号语义不变 |
+| IT-02 | 现有 Booker 调用 `ItaPlugin.book()` → 成功上报 | 使用用户账号;公共 `VSBookResult` 到既有异步上报字段;不新增订单通道 |
+| IT-03 | `ItaPlugin.book()` 普通失败 → 原 Booker 调度 | 本次调用结束且不在插件内循环提交;后续信号重新进入服务、准备日历、重查库存并再次调用,健康登录可复用;无需 Italy 专属异常分支 |
+| IT-04 | 原安装器、工厂、热更新函数;多实例、前后两个版本 | 只交付 Italy 单文件即可加载;旧实例停止、新实例用新实现;公共类型身份不丢失;不沿用旧模块缓存 |
+| IT-05 | 支持的调试命令、PluginTester、Query+Book 本地串联工具 | 调用新公开接口,默认不提交;配置来源明确;无失效私有类型导入;重复运行的本地提交保护不丢失 |
+| IT-06 | VFS/TLS/BLS 相关共享依赖回归 | 公共函数默认参数/返回/异常不退化;有公共改动则测试原调用者,不操作真实网站 |
+
+集成测试不得把被测 `query()`、`book()`、信号序列化或 Booker 分支替换成总是成功的 Mock。只模拟网络、邮箱、浏览器、Redis/云端等外部边界;共享 Redis 协议与调度行为仍由现有代码执行。
+
+## 5. 现场测试矩阵
+
+### LT-01:真实 Query
+
+前提:用户确认的账号池/路由、邮箱读取已授权、网络可用、已明确本次只查询。
+
+步骤:记录版本与脱敏配置来源 → 登录池子账号 → 首次准备 → Query → 同一有效会话再次 Query → 清理。
+
+通过条件:
+
+- 正向结果与页面/响应日期一致,扫描到首个正向月份即停止;无号必须说明已覆盖月份。
+- 重复 Query 不重复发 OTP/AVANTI;两次调用均没有最终预约请求。
+- 不新增预约或等待名单。网站原生日历可能自动读取第一天时段,不能把该读取误认为 Book。
+- 留存月份摘要、最早日期、请求次数和退出状态;当前调试阶段允许同时留存 OTP、Token 与敏感表单,后续另行清理。
+
+### LT-02:真实 Book 预提交及串联
+
+前提:独立的用户账号、OTP 已授权、允许的日期范围、`final_submit_enabled=false`。
+
+步骤:使用现有本地 Sentinel/Booker 串联入口或 PluginTester 对应场景 → 接收真实 Query 信号 → 用户会话重查 → 选中时段 → 读取预约基线/结束状态。
+
+通过条件:
+
+- 信号确实由 Query 发布并由 Booker 消费;不是手工构造信号替代现场串联。
+- 用户会话自动 OTP,选中日期/时段与当前库存、配置范围一致。
+- 最终请求为 0,`VSBookResult.success=false`,预约/等待名单不增加。
+- 账号隔离和清理通过;敏感日志脱敏不作为本轮阻塞项。
+
+### LT-03:受控单次真实预约
+
+前提:W5 离线通过、LT-01/LT-02 通过;用户明确本轮允许创建真实预约,申请人/服务/日期范围已确认,当前确有符合范围的号。
+
+步骤:记录授权范围与版本 → 核对已有预约/等待名单 → 使用现有提交开关进行一次自动 Book → 读取真实回执和宿主结果 → 清理。
+
+通过条件:本次 `book()` 最终业务请求恰好一次;出现可归属本轮申请人、服务、日期/时段的新成功结果;公共成功结果被原 Booker 正确处理。
+
+如果已尝试提交但结果不明:本次 `book()` 立即结束并返回普通失败,不在同一次调用内重新点击。后续由现有 Booker 按普通调度重试完整流程;该重复预约风险是 CR-001 已确认的取舍。取消预约仍属于额外业务操作,必须另行授权。
+
+没有合适档期或无法确认回执时,LT-03 为未完成;离线模拟成功不能填成真实成功。
+
+## 6. 命令与执行记录
+
+以下是现有入口,执行前必须核对测试副作用和实际依赖;各工作包实际结果保存在 [执行记录](06-execution-records.md)。命令列在这里不表示整套测试已经通过。
+
+```bash
+git diff --check
+wc -l plugins/ita_plugin.py
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test/ita -t . -p 'test_ita*.py'
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test/ita -t . -p 'test_debug_ita*.py'
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.ita.test_plugin_tester_ita_config test.ita.test_add_ita_query_account
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest \
+  test.ita.test_ita_protocol test.ita.test_ita_otp test.ita.test_ita_compact \
+  test.ita.test_ita_login_flow test.ita.test_ita_shared_lifecycle
+```
+
+新增/迁移后必须检查上述 discovery 是否覆盖全部相关用例,不能只跑一个方便通过的文件。若某命令依赖旧结构,先迁移入口,不将其故障默默排除。
+
+2026-09-01 目录整理说明:36 个既有 Italy 测试/辅助文件原样迁入 `test/ita/`,另增加包入口;当前公开薄合同 69 项通过。完整 discovery 同时收集到若干仍依赖已删除历史工具或已移除私有生产符号的旧测试,当前如实失败,后续必须按 W5 迁移到现行公开合同,不能恢复旧运行时壳或把这些文件静默排除。
+
+同日后续清理:本地持久 Query Profile 能力随其最后两个已删除工具一起退休;对应 1 个薄合同用例和 4 个旧插件内部用例移除,`test_debug_ita_query.py`、`test_debug_ita_session.py` 两个纯工具测试文件删除。当前薄合同为 68 项;其他混有现行业务断言的旧文件不能因导入失败直接整批删除。
+
+当前 R4 回归为 Italy 385 项、调试 280 项、框架离线入口 75 项、配置/加账号 27 项通过,全部 0 skip;R4 定向 279 项通过。覆盖两套表单配置、错误来源/path/action/method/enctype、上传字段、错误标签和值、隐藏字段不同步、同行人数、未知 required、重复 OTP/AVANTI/Turnstile、原生 change 离页、两阶段 OTP、一次发送/读取/写入、邮箱和时间窗绑定、Turnstile 三次共享预算及 AVANTI 目标。生产旧阶段枚举、日志门禁和恢复状态类已不存在;调试工具保留自己的阶段名称,仅用于输出诊断。所有外部边界均为模拟,没有访问真实网站、邮箱、账号池、订单或预约;H-06 只有离线证据,RC-06/09 尚未获得当前现场证据。
+
+R4 首轮迁移曾出现一个测试夹具重复关键字错误;修正夹具后通过。进一步删除旧日志门禁时,OTP 输入异常一度直接传播为 `RuntimeError`;实现恢复为 `CalendarGateError` 并保留用户允许的原始诊断信息后通过。没有通过放松表单合同、删除业务场景或恢复旧生产类型解决失败。
+
+以下是 CR-001 前的历史迁移证据,不代表当前仍保留未知暂停、持久 fence 或生产预约列表:Italy 535 项、调试 330 项、框架离线入口 74 项、配置/加账号 27 项曾通过;单文件热加载及当时回执测试包含在完整 Italy 套件内。协议/OTP/配置/日历定向 107 项在协议表示收敛前后通过;首轮暴露 capability 缺失值错误码漂移,修正实现后恢复既有 `string_required` 合同,未修改测试。最终交易的 241 项定向回归曾覆盖一次提交、未知暂停、精确归因、本地持久 fence 与热更新,并从“独立 read-port+状态机”迁移为同一申请人绑定交易对象,见 [W4 第 15–16 节](records/W4-selection-readback.md)。新增 H-04 调试测试覆盖公共 browser-fetch 与原生月份的同解析器比较、库存差异、401/403/429/503、错误 URL/正文、每月恰好两次只读请求以及 OTP/AVANTI/final 零增量;现场空月+正向月样本仍未执行。旧文档命令的失败已通过迁移到受支持 CLI 消除。历史套件之间有交集,不能相加为独立测试总数。
+
+回执单源化补充:生产成功核验只使用严格预约列表、精确原生请求证明和唯一新增活动记录;列表结构/覆盖、活动基线、历史变化、错误服务/日期/时间、拒绝/丢包/未知、清理失败和重启阻断仍在离线测试。详情 DOM、预约类型和状态码保留在 `debug_ita_reservation` 的只读协议测试,不再要求生产按每条历史记录导航详情页。
+
+本批新增/迁移覆盖:Book 表单模式不执行诊断采集也不提交;实际错误页面仍拒绝;表单结构脱敏和错误元数据路径在调试工具验证;日期诊断原只读用例继续执行;热更新不再依赖已删的全局 Book 转发函数,而验证公开 Book 使用上传文件自身的库存重查。等待校验新增“不改写快照、不放松其他字段”和布尔策略类型用例;既有真实扫描顺序、跨年、首月停止与不足范围不得报无号的测试保留。
+
+CR-001 前补充:当时的回执夹具曾改用真实字段及快照级原生请求证明,保留错误归属、历史变化、缺证明和未知暂停;这些生产回执结构已由 R3 删除。解析的内层错误/长度上限、时段分量字段位置以及两种月份日期格式回归仍保留。导入整理前后检查与实际单文件热更新仍是有效证据;不能只以文本行数或 AST 等价替代业务测试。
+
+上下文合并补充:普通 Query 未导出恢复参考时也校验账号/页面/代次/服务/标签页/路由/目录,新增跨实例复制、准备读取中换页面、查询读取中换账号的拒绝回归。原工具使用真实准备登记方法,登录健康状态和 Calendar 延迟就绪夹具按真实生命周期迁移;保留诊断 Book 和自动工作流各自的配置边界,不将真实公开调用替换为总是成功的桩。
+
+日历操作补充:实际 Node 脚本覆盖翻月控件可见/禁用/遮挡/重复/错误来源和路径;时段延迟只筛一次、不额外请求,超时不点击,读回期间账号变化阻止选择。原 2 项服务提示脚本测试迁往调试套件,不删除业务覆盖;新增诊断脱敏、异常不覆盖原错误及 soak 恢复测试。两组新增共 11 项,诊断迁移造成套件计数变化需单独说明。
+
+控件语义合同补充:日期和时段都必须返回精确的上下文、候选数、就绪、选中和点击事实;Python 只接受普通布尔和非负整数。实际 Node 场景继续逐项制造错误来源/服务/日期、不可用标记、错误 ID/时间/容量、重复/隐藏/遮挡元素及点击后漂移;最终脚本必须使用同一读回且不得在不安全状态点击。两个按旧 21 字段分组的 Mock 测试合成一项协议测试,所以 Italy 总数减少 1;具体场景未减少,见 [W3 第 10 节](records/W3-query-entry.md)。
+
+生命周期归位补充:Sentinel 真实 health/cleanup/creator 用例继续证明失效 Query 不发布信号并退役一次;普通 Query 继续覆盖当前实例、页面、tab、账号、代次、route、服务和 profile 漂移。受控跨实例 Calendar 恢复只在 soak 工具测试,必须在导航前拒绝 owner/profile/route/外域/未知参数,在导航后拒绝 form 和错服务,并执行新月份请求而非复用旧 scan。删除生产 checkpoint 方法名不等于删除这些业务断言,见 [W2 第 15 节](records/W2-login-preparation.md)。
+
+表单脚本合并补充:保留原实际 JS、原生隐藏同步、两套配置及前后 OTP 阶段测试;新增 3 项验证调试入口也受同一边界约束、重复业务控件拒绝、原生 change 离页不会被报成就绪。新增重复 token 测试首跑误限定内部错误检查顺序,已改为验证计数和拒绝行为;生产校验没有被放松。旧裸生成器消费者改用唯一的有边界生成器,没有保留旧私有导入或第二份实现。
+
+W0 已验证 discovery 必须带 `-t .`:否则 Python 会将 `test/test.py` 误识别成 `test` 包,导致夹具导入失败;这不是 Italy 缺少 OpenCV,不应通过安装无关依赖解决。
+
+现场命令不在此给一个默认会真实提交的复制块。W6 结合实际配置给出完整命令,明确标注是否会发 OTP、是否会创建预约、账号来源和日期范围;不把密码写进命令行。
+
+每次结果至少包含:代码版本/指纹、命令、退出码、通过/失败/跳过数量、对应测试编号、外部边界是真实还是模拟、请求与回执摘要、遗留问题。任何必需用例被跳过都必须解释,不能计为通过。

+ 68 - 0
docs/italy-refactor/05-release-criteria.md

@@ -0,0 +1,68 @@
+# 准出条件、发布与回退
+
+版本:1.1;日期:2026-09-01;依据:[技术方案](01-technical-design.md)、[测试计划](04-test-plan.md)。
+
+> CR-001 已调整准出边界:敏感调试日志暂时允许;最终提交失败或结果未确认可作为普通失败由 Booker 后续重试。准出仍要求单次 `book()` 最多一次点击、申请人/服务/库存正确及成功不误报。
+
+## 1. 什么叫完成
+
+完成不是“代码少了”“测试全绿”或“看到了 Calendar”。必须同时证明:约 1000 行、公共模块优先、Query/Book 职责清楚、既有框架/配置可接入、单文件热更新成立,以及真实 Book 成功链路经过验收。
+
+当前完成公共复用、Query/Book 入口、共用月份状态、准备上下文、日历操作、协议表示、薄最终提交、表单合同及 R5 生命周期归位的局部精简。生产最终路径不再读取预约列表或维护 Italy 专属未知状态机;它只核对当前申请人/选择、执行一次原生点击,并把明确响应解释为成功或普通失败。本表整体准出尚未通过。完整文件仍为 2598 行,真实网站、邮箱及预约未按本轮实现验收;384/280 项离线回归不能代替剩余条件。H-04 只读对照探针已就绪但现场等价性未通过,生产仍使用原生月份路径。公共模块及 VFS/TLS/BLS 当前零差异,详见 [最新记录](06-execution-records.md)。
+
+## 2. 准出清单
+
+| 编号 | 条件 | 必须提供的证据 | 关联 |
+| --- | --- | --- | --- |
+| RC-01 | 完整 Italy 插件达到约 1000 行预算 | 当前文件行数、正常排版审查、分区预算与实际对照;超预算须有用户确认的方案变更,否则不能默认通过 | T-01、UT-15、H-08 |
+| RC-02 | 真正复用而非搬家 | 复用符号清单、Italy 专属导入审查、新增公共生产代码及真实消费者、全仓净变化;没有隐藏旧实现或 Italy 私有运行时 | T-02/T-10、UT-01/15 |
+| RC-03 | Query 行为完整 | 最早日期/首个正向月份/扫描范围/有效会话重复查询测试;最终预约请求为 0;错误不伪装无号 | T-03、UT-07/08/09、IT-01、LT-01 |
+| RC-04 | Book 使用正确用户与库存 | 独立会话重查、日期范围、运行时 ID 来源、选择一致性;预提交不写入 | T-04/T-08、UT-10/11、LT-02 |
+| RC-05 | 提交与普通重试语义正确 | 成功/拒绝/丢包/超时及连续独立调用测试;单次调用最多一次点击;失败交回 Booker;重试重新准备、重查库存、重选运行时 ID,健康登录可复用 | T-09、UT-12/13、IT-02/03 |
+| RC-06 | 自动 OTP 正确且可调试 | 当前账号/时间窗绑定、前导零/冲突/旧码/超时测试;允许记录 OTP、Token 与敏感表单,不要求本轮完成日志脱敏 | T-07/T-10、UT-05/06、LT-01/02 |
+| RC-07 | 多领区与现有配置兼容 | 两套不同配置离线通过;现有配置消费者迁移清单;无固定香港/邮箱/日期;旧探测不发布假有号 | T-05/T-11、UT-14 |
+| RC-08 | 公共模块和交付机制不退化 | 公共消费者回归、单文件安装/工厂/双版本热更新、多实例、常用命令验证;必要宿主版本注明 | T-01/T-02/T-11、IT-04/05/06 |
+| RC-09 | 新版本真实预约成功 | LT-03 单次调用恰好一次最终请求、真实成功结果、公共结果/Booker处理;绑定本轮代码版本与授权范围 | T-04/T-09、LT-03 |
+| RC-10 | 测试和过程可追溯 | W0–W6 执行记录、T/H/测试映射、精确命令/退出码、失败/跳过说明、方案变更记录 | T-12、全部工作包 |
+
+不因接近 1000 行就容许丢失核心行为;也不以“行为复杂”为由默默放弃 1000 行目标。两者冲突时按变更流程说明事实与可选方案。
+
+## 3. 问题等级
+
+- P0:错误申请人/服务预约、同一次 `book()` 内重复点击、无法控制真实业务写入、把失败误报为成功。必须修复,不能例外发布。跨调用普通重试及当前调试期敏感日志是 CR-001 明确接受的风险,不列为本轮 P0。
+- P1:Query/Book 主路径失败、假阳性或假无号、自动 OTP 退化、单文件更新失败、公共消费者被破坏、行数/复用硬要求未满足。必须修复或先由用户明确批准目标变更;不能直接算完成。
+- P2:不影响核心行为的说明、展示或非关键诊断问题。可记录处置安排,但不能借此归类未通过的必需准出项。
+
+准出要求:未解决 P0/P1 为 0,全部适用 RC 条目有当前证据。P2 是否接受由用户决定并记录。
+
+## 4. 合并、发布与真实成功分开记录
+
+| 状态 | 可以说明什么 | 不能说明什么 |
+| --- | --- | --- |
+| 离线回归通过 | 指定版本的模拟行为、接口和加载符合测试 | 不能说网站上预约成功 |
+| 真实预提交通过 | 登录、OTP、查询、选中可在现场跑通,尚未创建预约 | 不能说 Book 已完成真实验收 |
+| 受控真实提交通过 | 指定版本、账户/服务范围内成功创建并核验预约 | 不能说所有领区或未来网站版本都已实测 |
+| 发布完成 | 已获授权的版本交付/部署动作完成 | 不替代上面的业务证据 |
+
+若用户选择先合并未完成现场验收的代码,必须标明“未完成真实预约准出”,默认提交关闭;这不是完整目标完成。不能把未验收版本无提示替换到生产提交任务。
+
+## 5. 发布前核对
+
+1. 用户已授权本次 Git/上传/部署操作;文档或开发授权本身不够。
+2. 工作区差异精确可审查,用户的配置修改和旧文档删除没有被恢复、覆盖或误带入提交。
+3. 插件版本递增,发布文件和实测文件的哈希一致。
+4. 若使用新公共 API,记录最低宿主提交,先升级宿主后更新插件;未升级的节点不能仅上传 Italy 文件。
+5. 不在真实预约提交进行中热更新;使用现有停止、清理、加载、启动机制。
+6. 保留上一可运行版本的获取方式以及当前配置备份策略,不在文档中保存秘密。
+
+## 6. 回退方案
+
+- 使用既有发布/安装机制回到已确认的前一版本;不新增 Italy 专属部署系统。
+- 回退前停止相关实例,检查是否存在“可能已提交”的任务。业务状态不随代码回退而撤销。
+- 普通失败任务可由 Booker 后续重试;每次重试必须重新进入服务、准备日历、重查库存和重选运行时 ID,不得恢复旧页面状态后直接重放最终请求。仍健康的申请人登录会话可以复用。
+- 公共模块若发生变化,回退须同时核对其他插件兼容性;不能只回退 Italy 文件而保留不兼容宿主。
+- 不自动取消已创建预约,不清空账号池冷却或删除用户数据。此类操作需单独明确授权。
+
+## 7. 完成报告最少内容
+
+最终报告必须列出:基线/最终版本、6286→实际行数、公共复用及新增公共代码、配置与工具迁移、测试结果、现场预约证据范围、遗留问题、发布状态。没有执行的事项明确写“未执行”,不使用模糊的“全部完成”。

+ 399 - 0
docs/italy-refactor/06-execution-records.md

@@ -0,0 +1,399 @@
+# 执行记录、测试迁移与方案变更
+
+版本:1.1;日期:2026-09-01。
+
+本文件是后续工作的记录模板和索引,不要求为每个函数写报告。每个 W 工作包一份记录;过长记录可保存到本目录 `records/` 并在此链接。记录不得包含账号密码、Cookie、Bearer、OTP 或邮件授权码。
+
+## 1. 当前记录
+
+| 工作包/事项 | 状态 | 结果与下一步 |
+| --- | --- | --- |
+| 文档基线建立 | 已建立 | 技术方案、可行性、周期、测试、准出及执行约定已写入本目录;已补阶段执行对照表与仓库入口规则。文档工作不授予代码或业务操作权限 |
+| W0 | 基线已建立 | [行为、测试及消费者台账](records/W0-baseline.md);既有文档依赖失败已定位,不计为通过 |
+| W1 | 公共能力离线验证通过 | [复用与回归记录](records/W1-shared-lifecycle.md);阶段快照为 Italy 6192 行,公共模块净增 8 行;不是整体准出 |
+| W2 | 登录/生命周期及 R4/R5 已离线完成 | [登录、表单、解析、准备上下文及生命周期记录](records/W2-login-preparation.md);第 17 节记录 R4 五字段表单合同,第 19 节记录 R5 2752 → 2598、工具 profile 所有权及其他插件零差异 |
+| W3 | 入口、共用月份状态与 R2 申请人顺序扫描完成;相关回归通过 | [Query 入口及共用日历记录](records/W3-query-entry.md);第 15 节记录 2883 → 2823、单一月份表示及删除提示日期优先双扫描,整体行数预算未达标 |
+| W4 | Book 入口/库存部分完成;R3 薄最终提交已离线通过 | [Book 与最终提交记录](records/W4-selection-readback.md);第 18 节记录 CR-001 后删除生产回执状态机、一次原生点击、明确响应及 Booker 普通重试;真实预约未验收 |
+| W5 | Italy 测试已集中到专属包;孤立 Profile 工具已删除;旧消费者迁移仍进行中 | [工具、协议与完整回归](records/W5-tools.md);`test/ita/` 已集中管理 Italy 测试,无调用者的本地 Profile 工具及两个纯遗留测试已删除,当前薄合同 68 项通过;其余旧消费者未伪装为全绿 |
+| W6 | 未完成 | 未执行新版本现场验收或发布 |
+
+文档建立时的源码核对:`git rev-parse HEAD` 为 `a22596f1fcdffb946960724ef299f249e7860891`;`wc -l` 为 Italy 6286、TLS 852、VFS 1271、BLS 1107。首次建立只做文档;其后 W0/W1/W2 的离线回归分别留档,未运行真实网站、邮箱或预约。
+
+2026-09-01 W2 现场竞态补充:真实失败快照证明 Booking/Purpose 异步选项晚于首次预检;
+等待器已改为有界 pending 轮询,并在表单安全前禁止 Turnstile 交互。当前薄合同 69 项、
+PluginTester 配置 15 项、编译、空白和受保护文件检查通过;Italy 1178 行。精确证据、首次测试
+命令的模块路径问题、SHA-256 及剩余 LT-01 见 [W2 第 23 节](records/W2-login-preparation.md)。
+
+2026-09-01 W5 测试目录整理:36 个 Italy 专属测试/辅助文件迁入 `test/ita/`,新增包入口并
+修正包导入和仓库根路径定位;生产插件、公共模块、其他插件和通用测试零改动。包内 37 个 Python
+文件语法通过,当前薄合同 69 项通过;Italy discovery 的 15 个旧导入错误和 1 个旧结构断言失败、
+调试 discovery 的 10 个旧导入错误,以及配置测试对已删除工具的依赖已如实记录,不恢复旧实现
+也不跳过。详见 [W5 第 9 节](records/W5-tools.md)。
+
+同日 W5 孤立 Profile 清理:删除无生产/工具调用者的 `utils/ita_local_profile.py`,删除只测试
+已删除 `debug_ita_query` / `debug_ita_session` 的两个文件,并从混合测试中移除 5 个专属用例;
+生命周期、登录、协议、OTP、Query/Book 和公共清理断言保留。当前薄合同 68 项通过,完整 Italy
+discovery 的既存 15 errors/1 failure 不变,调试 discovery 从 10 个旧导入错误降为 8 个。详见
+[W5 第 10 节](records/W5-tools.md)。
+
+文档校验(2026-09-01):只读检查了 8 个新增 Markdown 文件、36 个本地链接、全部 T/H/UT/IT/LT/RC 定义与编号引用、代码围栏及末尾换行,结果无错误。对各新增文件执行 `git diff --no-index --check /dev/null <文件>`,并执行 `git diff --check`,均通过。此记录只证明文档结构与引用有效,不是插件行为验收。
+
+W2 登录记录补齐后复核(同日):根 `AGENTS.md` 与本目录共 11 个 Markdown 文件、49 个本地链接,代码围栏/末尾换行及逐文件空白检查均无错误;`git diff --check` exit 0。当前生产文件 SHA-256 与 W2 记录一致,旧配置命令测试失败如实保留,没有据此改写准出要求。
+
+W2 后续改动归档(同日,历史快照):当时 Italy 5863 行;Italy 套件 529 项、调试套件 313 项、框架离线入口 75 项均通过,0 skip;套件有交集,不合并成独立测试总数。配置/加账号套件仍有 1 failure、9 error 记录,均关联已删除的旧验收文档。精确命令、指纹、业务测试迁移和剩余问题见 W2 记录第 5 节;该次文档同步没有继续改动生产实现。
+
+前次归档文档校验:11 个 Markdown 文件、49 个本地链接、57 个 T/H/UT/IT/LT/RC 定义及其引用均一致,代码围栏和末尾换行有效。逐文件空白检查无诊断输出,`git diff --check` exit 0。`git diff --no-index` 的 exit 1 表示文件有差异,不把它单独判为空白错误。生产文件指纹在文档同步前后保持一致。
+
+### 历史快照:5621 行工作区
+
+同日补充核对:Italy 5621 行,公共工具 497 行;相对 W0 两个生产文件合计净减 657 行。本次只做验证与文档同步,没有新增生产代码修改。W2 的 5863 行及“529/313 全部通过”是前一工作区的历史记录,不是当前结果。
+
+当前完整回归:Italy 531 项有 1 failure;调试 313 项有 6 failures;框架离线入口 75 项通过;配置/加账号 26 项有 1 failure、9 error 记录。均为离线、0 skip;精确命令、原因和迁移去向见 [W3](records/W3-query-entry.md)。这是未完成的工作区,不能提交为“重构验收通过”。
+
+该快照文档检查:根 `AGENTS.md` 与本目录共 13 个 Markdown 文件、66 个本地链接、57 个技术/假设/测试/准出编号,全部引用有效,代码围栏及末尾换行正常;逐文件空白检查无错误,`git diff --check` exit 0。文档同步前后 Italy 与公共工具 SHA-256 未变化。
+
+### 历史快照:5334 行工作区
+
+W3/W4 后续已执行协议模型、日期筛选及共用月份捕获收敛,并迁移其真实消费者;从 5621 再减 287 行。当前 Italy 5334 行,公共工具仍为 497 行,相对 W0 两个生产文件合计净减 944 行。本批没有新增公共生产函数或 Italy 专属运行时文件。
+
+完整离线回归:Italy 534 项、调试 313 项、框架入口 75 项通过,均 0 skip;原 7 项迁移失败已修复。配置/加账号 26 项仍有 1 failure、9 error 记录,原因仍是已删除的旧文档命令,不算通过。测试有交集,不能相加。真实 `query()` → `book()` 的新增回归显示:Query 日期在申请人库存中已售罄时,Book 重查其自己的下一日期,最终请求为 0。
+
+精确命令、指纹、剩余分区预算与迁移去向见 [W3 第 6 节](records/W3-query-entry.md),排序/选中业务说明见 [W4 第 4 节](records/W4-selection-readback.md)。约 1000 行目标未完成,W2–W6 不据此标记整体完成。本批未访问真实站点或邮箱,未提交预约、Git 提交/推送或部署。
+
+本次文档同步校验:13 个 Markdown 文件、69 个本地链接、57 个技术/假设/测试/准出编号引用全部有效,围栏、末尾换行及逐文件空白检查无错误;20 个改动/新增 Python 文件 AST 解析通过,`git diff --check` exit 0。文档同步前后生产文件指纹一致。此处仅证明记录可读、引用有效,不改变未完成的业务准出状态。
+
+### 历史快照:5058 行工作区
+
+Book 的三层转发已收进公开接口;仅用于排障的表单结构和日期格式诊断移入现有工具;删除扫描结果重复验证及表单等待克隆快照校验。真实预约所需的页面、账号、字段、库存、一次提交与回执核验仍在生产文件内,没有新增 Italy 私有运行时或公共 API。
+
+本批 Italy 再减 276 行至 5058,公共工具仍 497,两生产文件相对 W0 合计净减 1220 行。最终 Italy 536 项、调试 315 项、框架离线 75 项通过,0 skip;配置/加账号 26 项仍因旧文档命令有 1 failure、9 error 记录。热加载与诊断消费者已迁移,业务断言没有删除。精确命令、源码指纹、分区预算及历史中间结果见 [W4 第 5–6 节](records/W4-selection-readback.md)。
+
+约 1000 行及 W2–W6 仍未整体完成;周期和准出文件已按当前证据更新。未访问真实站点、邮箱或订单,未执行预约、Git 提交/推送、部署或修改用户配置。
+
+本批文档校验:13 个 Markdown 文件、71 个本地链接、57 个技术/假设/测试/准出定义及引用均有效;代码围栏、末尾换行、逐文件空白检查通过。27 个改动/新增 Python 文件 AST 解析通过,`git diff --check` exit 0。生产文件 SHA-256 在文档同步前后保持一致。编号校验脚本已兼容现场测试编号的标题定义格式;不把扫描器自身漏识别标题当作文档缺失。
+
+### 前次文档执行约定复核(2026-09-01)
+
+本轮范围仅为用户要求的文档整理:核对 01–06 与源码复用入口,在 03 第 2.1 节补齐 W0–W6 对应的技术、假设、测试和准出证据,并在 README 与根 AGENTS.md 明确后续开发的读取和记录要求。沿用既有技术方案、范围与预算,不使用用户禁止的 skill,不新增生产实现。
+
+核对时 Italy 为 5058 行、公共工具为 497 行,源码指纹与 W4 最新记录一致。536/315/75 项通过及配置命令既存失败均引用上一批执行记录;本轮没有重跑业务测试,不把历史结果冒充本轮结果。现存用户配置修改及旧文档删除保持原样。
+
+本轮只读校验 exit 0:13 个 Markdown 文件、73 个本地链接、57 个技术/假设/测试/准出定义及引用全部有效,代码围栏、末尾换行和逐文件空白检查通过;27 个已改动/新增 Python 文件 AST 解析通过。`git diff --check` exit 0;Italy 与公共工具 SHA-256 前后相同。文档交付完成,不改变约 1000 行目标、未解决测试项或真实预约准出的状态。
+
+### 历史快照:4572 行工作区
+
+在已获目标续作授权范围内继续 W2/W4:三套回执模型合为真实字段、提交证明放在快照上,重复 JSON/日期/月限与基础校验收敛,机械合并遗留导入统一到文件顶部。5058 → 4974 → 4770 → 4572,三个减行来源分别为回执模型 84、解析/校验及说明 204、文件组织 198;不能把整理导入说成全部是业务复杂度下降。没有将 Italy 专属代码搬入公共模块或增加运行时文件。
+
+最新完整离线回归:Italy 540 项、调试 315 项、框架离线入口 75 项通过,0 skip;协议/OTP/查询/Book/热加载定向 113 项通过。配置/加账号 26 项仍有 1 failure、9 error 记录,原因是已删除的旧文档命令。此失败未删除或跳过;需要在 W5 把命令和原业务断言迁往现有工具。各组存在交集,不累加成独立测试总数。
+
+精确命令、错误修正记录、源码指纹和完整分区预算见 [W2 第 7 节](records/W2-login-preparation.md),回执字段及消费者迁移见 [W4 第 8 节](records/W4-selection-readback.md)。公共工具仍净增 8 行;两个生产文件相对 W0 净减 1706 行。1000 行预算尚差 3572 行,不能用本批通过代替 W2–W6 或整体准出;下一步仍是准备/会话、日历操作和提交读取层的结构精简。
+
+本批只进行本地代码、测试及文档修改。用户配置和旧文档删除保持原样;未读取真实邮箱、访问真实网站/云订单、提交预约,也未 Git 提交、推送或部署。未使用用户禁止的 skill;现有阶段对照表与准出条目继续约束后续工作,未放宽行为或行数要求。
+
+本批文档校验 exit 0:根 AGENTS.md 与本目录共 13 个 Markdown 文件、80 个本地链接、57 个技术/假设/测试/准出定义及引用均有效;围栏、末尾换行和逐文件空白检查通过。30 个已改动/新增 Python 文件 AST 解析通过,`git diff --check` exit 0。Italy 和公共工具 SHA-256 在文档同步前后保持一致。此项仅证明文档与静态结构可核对,不替代尚未完成的运行/现场准出。
+
+### 历史快照:4483 行工作区
+
+本批按 W2 第 8 节既定范围合并 Query/Book 的准备上下文,以及 Query 内部单层转发;未新增运行时文件、公共 API 或配置。普通 Query 和准备登记的身份变化测试新增 4 项,原恢复、角色、一次 OTP/提交、诊断和热更新断言随真实消费者迁移。精确修改、迁移去向、指纹和分区预算见 [W2 第 9 节](records/W2-login-preparation.md)。
+
+Italy 从 4572 减至 4483 行,本批净减 89,低于 100–180 的估计;公共工具仍 497 行,两生产文件相对 W0 净减 1795 行。1000 行预算仍差 3483 行,H-08 未通过,不按减行比例宣布整体进度。下一步集中日历页面操作/选择读回、表单等待和提交读取层;既有工具迁移仍按 W5 台账执行。
+
+本批最终离线回归:Italy 544 项、调试 315 项、框架离线入口 75 项、恢复/Book/回执端口/热更新定向 111 项均 exit 0、0 skip。配置/加账号 26 项仍 exit 1,含 1 failure、9 error 记录,原因仍为已删除的旧验收文档;不得跳过或称全部通过。套件有交集,不累加为独立测试数量。
+
+01 技术决策与阶段对照表未放宽;02 可行性、03 剩余安排、04 测试与 05 准出状态同步引用这批结果。只做本地实施、离线验证和文档记录,用户配置与旧文档删除保持原样;没有真实网站、邮箱、订单、预约操作,也未提交、推送或部署。
+
+本批文档校验 exit 0:根 AGENTS.md 与本目录共 13 个 Markdown 文件、81 个本地链接、57 个技术/假设/测试/准出定义及引用有效,围栏、末尾换行和逐文件空白检查通过;32 个已改动/新增 Python 文件 AST 解析通过。`git diff --check` exit 0;文档同步前后两生产文件 SHA-256 不变。此处不替代尚未完成的运行和现场准出。
+
+### 历史快照:4339 行工作区
+
+按照 W3 第 7 节预先记录的范围,共用日历控件状态脚本、合并重复候选筛选/等待,将服务表统计归位现有调试入口。真实日期/时段选择、账号绑定、最终一次提交及回执业务边界保留。精确修改、消费者迁移、源码指纹和分区预算见 [W3 第 8 节](records/W3-query-entry.md)。
+
+本批 4483 → 4339,净减 144 行,其中 52 为日历结构共用、92 为诊断归位;公共模块仍 497 行,两生产文件相对 W0 净减 1939。工具和测试增量单列,不将诊断搬迁冒称为业务算法删除。离约 1000 行仍差 3339 行,H-08 未通过;下一步继续表单准备/等待、提交读取层和 W5 旧命令消费者迁移。
+
+最终离线回归:Italy 547 项、调试 323 项、框架离线入口 75 项、插件/Query 调试/soak 定向 85 项通过,均 exit 0、0 skip;热更新包含在完整 Italy 套件。配置/加账号 26 项仍 exit 1,含 1 failure、9 error 记录,原因仍是已删除的旧文档命令。测试有交集,不累加。净新增 11 项;另有 2 项实际服务提示脚本测试从生产测试文件迁至调试测试,未删除业务断言。
+
+01 技术方案和准出条目不放宽;02 可行性、03 安排、04 测试及 05 准出状态均同步。未使用用户禁止的 skill。仅有本地代码/离线测试/文档改动,用户配置和旧文档删除保持原样;没有真实网站、邮箱、账号池或预约操作,未 Git 提交、推送、部署。
+
+本批文档校验 exit 0:根 AGENTS.md 与本目录共 13 个 Markdown 文件、81 个本地链接、57 个技术/假设/测试/准出定义及引用全部有效;代码围栏、末尾换行和逐文件空白检查通过。33 个已改动/新增 Python 文件 AST 解析通过,`git diff --check` exit 0;文档同步前后两生产文件指纹不变。此项只证明记录和静态结构可核对,不替代尚未完成的运行或现场准出。
+
+### 最新状态:4289 行工作区
+
+按 W2 第 10 节开始前范围,合并生产与调试两条表单脚本入口、AVANTI 的公共目标校验并移除内部别名;现有控件配置由标准库序列化,未新增 Italy 运行时文件或公共 API。真正的表单/账号/发送窗口、一次 OTP 和一次最终提交边界不变。实际修改、消费者、测试迁移及指纹见 [W2 第 11 节](records/W2-login-preparation.md)。
+
+Italy 4339 → 4289,净减 50;公共工具仍 497,两生产文件相对 W0 净减 1989。分支共用、接线删除和正常格式整理分别说明,不把行数下降全部称为算法优化。约 1000 行仍差 3289 行,H-08 未通过。旧文档命令消费者仍须迁往现有工具,准备/等待、日历操作与提交读取层仍有较大精简空间。
+
+最终离线回归:Italy 550 项、调试 323 项、框架离线入口 75 项、表单/OTP/工作流/日历和 Book 调试定向 231 项通过,均 exit 0、0 skip;完整 Italy 套件包括实际单文件热更新。配置/加账号 26 项仍 exit 1,含 1 failure、9 error 记录,原因仍是已删除的旧文档命令,不标成通过。新增 3 项真实 JS 场景;首次新增测试误限定检查顺序,已修正为验证计数与拒绝行为,生产校验未放宽。套件有交集,不相加为独立测试数。
+
+01 技术决策与准出条件不变;02 可行性、03 排期、04 测试及 05 当前准出同步。没有使用用户禁止的 skill。仅做本地修改与离线测试,用户配置和旧文档删除保持原样;没有真实网站、邮箱、账号池或预约操作,未提交、推送或部署。本批离线通过不等于总体开发或新版本真实预约已完成。
+
+本批文档校验 exit 0:根 AGENTS.md 与本目录共 13 个 Markdown 文件、83 个本地链接、57 个技术/假设/测试/准出编号及引用均有效;围栏、末尾换行及逐文件空白检查通过。33 个已改动/新增 Python 文件 AST 解析通过,`git diff --check` exit 0。文档同步前后 Italy 与公共工具 SHA-256 一致;此项不代替未完成的运行或现场准出。
+
+### 最新补充:W5 账号池 Query 命令迁移
+
+不恢复用户已删除的 `docs/ita_query_book_acceptance.md`,也不保留其中第二套内联账号分配代码。现有 `tools/debug_ita_query_book.py` 增加互斥 `--pool-query`,复用 `tools/ita_query_book_local.py` 的分组/路由/邮箱校验、现有 `VSCloudApi` 和 `PluginTester.run_pipeline(test_book=False)`;`--submit-once` 会在分配账号前拒绝。原 10 个旧文档消费者场景迁移为直接调用支持入口,并新增 Query 不得提交的测试。
+
+最终离线回归:Italy 550 项、调试 323 项、框架离线入口 75 项、配置/加账号 27 项均 exit 0、0 skip;旧 1 failure/9 error 已修复而非跳过。精确命令、指纹、安全边界与支持命令见 [W5 第 2 节](records/W5-tools.md)。测试组有交集,不累加成独立总数。Italy 生产文件未因工具迁移改变,仍为 4289 行、距离约 1000 行差 3289 行,因此 W5、H-08、RC-01 仍未整体通过。
+
+本批仅修改本地工具、测试和文档并执行离线注入测试;没有读取真实账号池、邮箱或网站,没有 Query、OTP、订单或预约动作,也未提交、推送或部署。用户配置和旧文档删除保持原样,没有使用用户禁止的 skill。
+
+### 最新状态:4187 行工作区
+
+按 W4 第 9 节实施前记录,生产回执读取已从预约列表+逐条详情导航收敛为一次严格列表导航;详情页 DOM/状态码/预约类型保留在现有只读调试工具。申请人会话、当前 Book 预提交、精确原生请求、基线无活动预约、完整历史不变、唯一新增确认记录、服务/日期/区间内分配时间以及未知结果暂停均保留。没有新增公共生产 API 或 Italy 私有运行时文件。
+
+Italy 4289 → 4187,净减 102;相对 W0 的 6286 行累计减少 2099 行,距约 1000 行仍差 3187 行。生产回执的浏览器导航复杂度从 O(r) 次降为 O(1) 次,列表解析仍为 O(r)。详情诊断工具增量单列,不把迁移冒充全仓同量删除。
+
+首轮扩大回归因三个旧夹具仍访问已删除的详情存根而出现未知结果;按真实列表事实迁移夹具后,最终离线回归为 Italy 551 项、调试 323 项、框架离线 75 项、配置/账号 27 项通过,全部 0 skip;回执/最终核心定向 190 项、本地最终链路 9 项、原 Booker 集成 8 项及最终门禁用例也通过。精确行为、命令分类和源码指纹见 [W4 第 10 节](records/W4-selection-readback.md)。测试有交集,不累加。
+
+本批没有访问真实网站、邮箱、账号池或订单,没有创建预约,也未提交、推送或部署。用户配置修改和旧文档删除保持原样。H-07/H-11 的本批离线证据通过;RC-01、现场 RC-05、RC-09 和整体 RC-10 仍未完成。下一步按技术方案进入表单准备/等待及日历页面操作的较大结构收敛。
+
+### 最新状态:4031 行工作区
+
+按 T-09/T-10 和 W4 第 11 节的实施前记录,整页 `CalendarRequestAudit` 已从生产插件迁入现有日历调试工具;生产继续通过 `NativeFinalSubmitter` 证明当前标签页、当前预提交选择对应的唯一原生监听请求,并由最终状态机和列表回执完成归属。调试、本地串联及发布门禁继续统计整个页面,重复或迟到最终请求不能通过。
+
+Italy 4187 → 4031,净减 156;相对 W0 累计减少 2255 行,距约 1000 行仍差 3031 行。公共生产模块零新增,调试工具增量单列。旧生产审计所有权测试迁往原生请求证明、被动审计器和最终门禁三类现行测试;没有保留损坏导入或通过删门禁获得通过。
+
+最终离线回归为 Italy 540 项、调试 323 项、框架离线入口 74 项、配置/账号 27 项通过,均 0 skip;迁移中唯一失败为单文件夹具仍传旧 `request_audit` 参数,更新为现行合同后通过。精确职责、消费者映射、源码指纹和风险见 [W4 第 11–12 节](records/W4-selection-readback.md)。测试组有交集,不累加。
+
+本批没有真实外部操作,没有 Git 提交、推送或部署;用户配置修改和旧文档删除保持原样。H-07/H-11 的本批离线证据通过,H-08、RC-01、现场 RC-05、RC-09 和整体 RC-10 仍未完成。下一步仍是表单准备/等待及日历页面操作的较大结构收敛。
+
+### 最新状态:3981 行工作区
+
+按 W2 第 12 节实施前记录,把生产默认预检报告和 Turnstile 交互报告从业务路径移除;现有日历调试 gate 继续显式接收安全诊断回调。表单来源/action/方法、配置控件、隐藏字段、未知必填项、OTP/AVANTI/Turnstile 唯一性、两阶段状态、当前会话、VFS widget helper、有界三次交互和后续真实读回全部保留。
+
+Italy 4031 → 3981,净减 50;相对 W0 累计减少 2305 行,距约 1000 行仍差 2981 行。公共生产模块零新增;生产对工具/测试导入为 0。事前预计 70–130 行,实际较低,因为没有删除真实的表单、OTP、验证及原生请求核验边界。
+
+首次定向回归有 3 个旧生产 JSON 输出断言失败;迁往恢复后真实读回、超时零请求以及 debug gate 超时安全诊断后,最终 Italy 540 项、调试 324 项、框架离线入口 74 项、配置/账号 27 项全部 exit 0、0 skip。精确命令、指纹和断言迁移见 [W2 第 13 节](records/W2-login-preparation.md)。测试组有交集,不累加。
+
+本批只有本地代码、测试和文档修改;没有真实网站、邮箱、账号池、订单或预约操作,没有 Git 提交、推送或部署。用户配置修改和旧文档删除保持原样。H-06/H-11 的本批离线证据通过,H-08、现场 H-04、RC-01/05/09/10 仍未完成;下一步在动代码前记录日历捕获/选择层的具体收敛方案。
+
+### 最新状态:3926 行工作区
+
+按 W3 第 9 节实施前记录,将日期与时段两套快照收敛为同一五字段控件语义合同;底层来源/服务/日期、库存、ID、时间、容量、CSS、唯一性、最终按钮保护和一次点击仍由真实脚本检查。`NATIVE_FINAL_SCRIPT` 复用该合同,Book gate 改用生产 `verify_precommit_selection`,不再手工复验 10 个私有字段。没有新增公共生产函数或 Italy 运行时文件,也没有切换 HTTP 通道。
+
+第一轮 228 项定向回归发现 1 个真实的点击后日期漂移读回缺口,修正选中语义与上下文绑定后,同组 228 项及补充 69 项通过。最终离线回归为 Italy 539 项、调试 324 项、框架离线入口 74 项、配置/账号 27 项,全部 exit 0、0 skip。Italy 数量减少 1 是两组旧原子字段 Mock 测试合并为统一协议测试;实际 Node DOM 的不可用、重复、错误 ID/时间/容量、遮挡、错误来源/日期和点击后漂移场景全部保留。
+
+Italy 3981 → 3926,净减 55;相对 W0 累计减少 2360 行,距约 1000 行仍差 2926 行。公共工具仍 497 行,两生产文件相对 W0 净减 2352 行。精确命令、失败修正、测试迁移和 SHA-256 见 [W3 第 10 节](records/W3-query-entry.md)。生产对 `tools.*`/`test.*` 导入为 0,`py_compile`、AST 和 `git diff --check` 通过。
+
+本批仅有本地代码、测试和文档修改;没有真实网站、邮箱、账号池、订单或预约操作,没有 Git 提交、推送或部署。用户配置修改和旧文档删除保持原样。H-03/H-05/H-10/H-11 增加离线证据;H-04/H-08、RC-01、现场 RC-05/09/10 仍未完成。下一步须审计共用月份捕获/扫描或另一整块生产调用层,不能重复整理已统一的控件合同。
+
+### 最新状态:3795 行工作区
+
+按 W2 第 14 节实施前记录,将只有 soak 工具和测试消费的 `CalendarQueryCheckpoint`、捕获/恢复方法及专属 owner/URL 校验从生产插件移除;生产 Sentinel/Booker 仍按 `health_check → cleanup → create_session` 退役并新建实例,普通 Query 的 `_PreparedCalendar` 身份复核、持久 profile 锁和严格清理均保留。受控同 profile 恢复实验在 `debug_ita_soak` 内保存最小比较值,并继续核对账号、profile、route、URL、服务及 fresh scan。重复浏览器指纹展示脚本也已删除,浏览器初始化继续复用公共工具。
+
+首轮 48 项迁移测试出现 26 errors,定位为工具直接使用调用方 route,而旧 API 会按当前账号重新解析 route;恢复该语义后 48 项通过,补齐迁移后的参数化拒绝场景后为 51 项通过。最终 Italy 535 项、调试 324 项、框架离线入口 74 项、配置/账号 27 项全部 exit 0、0 skip;登录/生命周期/热更新/soak 定向 133 项通过。Italy 计数净减 4 来自 7 个生产内部表示测试合并为 3 个工具语义测试,原场景没有丢失。
+
+Italy 3926 → 3795,净减 131;`ItaPlugin` 类 745 → 629 行;相对 W0 累计减少 2491 行,距约 1000 行仍差 2795 行。公共工具仍 497 行,两生产文件相对 W0 净减 2483 行。生产五个 checkpoint 符号和 `tools.*`/`test.*` 导入均为 0;`py_compile`、AST 与 `git diff --check` 通过。精确职责、测试迁移和 SHA-256 见 [W2 第 14–15 节](records/W2-login-preparation.md)。
+
+本批仅有本地代码、测试和文档修改;没有真实网站、邮箱、账号池、订单或预约操作,没有 Git 提交、推送或部署。用户配置修改和旧文档删除保持原样。H-01/H-10/H-11 增加离线证据;H-04/H-08、RC-01、现场 RC-05/09/10 仍未完成。下一步继续审计月份捕获/扫描、最终提交/回执或另一整块生产调用层。
+
+### H-04 只读传输对照探针就绪:生产仍为 3795 行
+
+月份审计确认 Query 与 Book 已共用 `_capture_month` 和同一库存解析;强行重写该层只能获得很小减量。按 T-06/H-04,现有 `tools/debug_ita_calendar_gate.py` 增加显式 `transport_compare` 模式,复用公共 `perform_browser_fetch` 对同会话、同服务、同月份的原生只读响应做逐项比较。探针默认关闭,严格拒绝库存、路径、状态和结构差异;报告脱敏,并要求对照阶段 OTP/AVANTI/final 零增量。生产插件和公共工具均未修改。
+
+定向 43 项、完整调试 330 项、Italy 535 项、框架离线 74 项、配置/账号 27 项全部 exit 0、0 skip;`py_compile` 与 `git diff --check` 通过。探针尚未获当轮授权运行真实网站,故 H-04 仍为“现场待验证”,不能切换生产 Query。精确范围、指纹和结果见 [W3 第 11 节](records/W3-query-entry.md)。本批没有网站、邮箱、账号池、订单、预约或 Git/部署操作;用户配置与旧文档删除保持原样。
+
+### 最新状态:3776 行工作区
+
+按 W4 第 13 节实施前记录,最终层删除只包装 `FinalTarget` 的证明类型,以及快照内重复的申请人、随机 session key、恒真完整标志和未被最终协议消费的 route service ID。严格原生 POST 匹配后直接传递同一个不可变目标;生产 read-port 和本地提交保护器仍核对当前 route、prepared runtime service、页面服务名、账号、浏览器/标签页、会话代次和 precommit。一次提交、未知暂停、唯一新增回执及归属语义没有改变。
+
+首轮定向回归出现 3 errors、7 failures,均来自旧证明包装和本地保护器的重复 service 字段消费者;迁移到现行单源边界后,同组 241 项通过。最终 Italy 535 项、调试 330 项、框架离线 74 项、配置/账号 27 项全部 exit 0、0 skip;Python 语法、生产导入边界和 `git diff --check` 通过。精确失败、迁移、指纹和测试见 [W4 第 14 节](records/W4-selection-readback.md)。
+
+Italy 3795 → 3776,净减 19 行;相对 W0 累计减少 2510 行,距约 1000 行仍差 2776 行。公共工具仍 497 行且未修改。没有真实外部操作,没有 Git 提交、推送或部署;用户配置修改和旧文档删除保持原样。H-05/H-07/H-10/H-11 增加离线证据,但 H-08、RC-01、现场 RC-05/09 和整体 RC-10 仍未完成。
+
+### 最新状态:3750 行工作区
+
+按 W5 第 3 节实施前记录,协议与配置层只做表示收敛:保留稳定错误码/字段路径、双层 JSON、大小和记录数上限、重复日期/时段/ID 拒绝、库存正负语义、日期时间精度、路由 capability、OTP 来源/模板/有效期和六位唯一性。重复类型/范围校验改为插件内一个原语;没有新增公共 API、Italy 私有运行时模块或网络路径。
+
+首轮 107 项定向回归出现 2 failures,原因是 `ItaProtocolError` 同时属于 `ValueError`,导致缺失/空 capability 被枚举转换捕获并错误归类。实现改回先验证字符串再转换枚举,保留原 `string_required` 错误合同;没有修改测试。最终 Italy 535 项、调试 330 项、框架离线 74 项、配置/账号 27 项均 exit 0、0 skip;正确 discovery 使用 `-s test -t .`。Python 语法、生产导入边界和 `git diff --check` 通过。
+
+Italy 3776 → 3750,净减 26 行;相对 W0 累计减少 2536 行,距约 1000 行仍差 2750 行。公共工具仍 497 行且未修改。小型协议整理的实际收益显著低于预估,下一步转向插件入口/profile/会话生命周期与现有公共实现的整块重复,不继续以微型改名消耗周期。精确范围、命令、失败修正和 SHA-256 见 [W5 第 3–4 节](records/W5-tools.md)。
+
+本批没有真实外部操作,没有 Git 提交、推送或部署;用户配置修改和旧文档删除保持原样。H-05/H-06/H-11 增加离线证据,但 H-04/H-08/H-09、RC-01、现场 RC-05/09 和整体 RC-10 仍未完成。
+
+### 最新状态:3685 行工作区
+
+按 W4 第 15 节实施前记录,独立最终 read-port 与提交状态机已合并为一个申请人绑定交易对象;原生提交器继续只负责同步选择核验、一次网站点击和精确请求证明。基线活动预约阻断、历史不变、唯一新 ACTIVE 回执、服务/日期/区间时间归属、明确拒绝与未知不重试均保留;调试观察、持久 fence 和整页请求计数仍在工具层。
+
+首轮 80 个 import error 来自旧私有类消费者,迁移后发现并修复“未确认所有权的候选标签页也会被关闭”的真实缺陷;另一个旧静态测试被改为区分只读对象构造与真正最终派发,没有放宽运行时门禁。改前与改后最终交易定向集合均为 241 项通过。最终完整回归为 Italy 535 项、调试 330 项、框架离线入口 74 项、配置/账号 27 项,全部 exit 0、0 skip;语法、AST 生产导入边界和 `git diff --check` 通过。
+
+Italy 3750 → 3685,净减 65 行;相对 W0 累计减少 2601 行,距约 1000 行仍差 2685 行。公共工具仍为 497 行且本批未修改。实际减量低于估计,按事实记录,不压缩排版或删除安全断言。精确结构、失败修正、测试迁移、分区预算和指纹见 [W4 第 16 节](records/W4-selection-readback.md)。
+
+本批只有本地实现、离线测试和文档记录;没有访问网站、邮箱、账号池、订单或预约,没有 Git 提交、推送或部署。用户配置与旧文档删除保持原样,没有使用用户禁止的 skill。H-07/H-10/H-11 增加离线证据;H-04/H-08、RC-01、现场 RC-05/09 和整体 RC-10 仍未完成。
+
+### 最新状态:3566 行工作区
+
+按 W3 第 12 节实施前记录,Availability 的运行时服务身份、Query/Book JSON 请求字段、
+日期/时段选择上下文和月份捕获分支已继续单源化;Query 与 Book 的业务循环、原生浏览器传输、
+申请人库存重查、月份连续性、最终按钮保护和一次点击读回保持不变。H-04 未经现场验证,
+生产没有切换到 browser-fetch 或纯 HTTP。
+
+第一轮 Query 定向测试发现空月份可绕过非法 `selectedDay` 的真实缺口并已修复;完整调试首轮
+唯一失败是旧静态消息测试不识别共享 formatter,迁到现行 packet 行为证据后通过。最终 Italy
+535 项、调试 330 项、框架离线入口 74 项、配置/账号 27 项全部 exit 0、0 skip;精确命令、
+断言迁移、分区和源码指纹见 [W3 第 13 节](records/W3-query-entry.md)。
+
+Italy 3685 → 3566,净减 119 行;相对 W0 累计减少 2720 行,距约 1000 行仍差 2566 行。
+公共工具仍为 497 行且未修改。本批没有真实外部操作,没有 Git 提交、推送或部署;用户配置
+修改和旧文档删除保持原样。H-03/H-05/H-10/H-11 增加离线证据,H-04/H-08、RC-01、
+现场 RC-05/09 与整体 RC-10 仍未完成。下一步转向插件入口或最终交易/回执整块调用链。
+
+### CR-001:敏感调试日志与普通提交重试(已确认并完成 R3 离线实施)
+
+日期:2026-09-01。用户明确确认:
+
+1. Italy 当前可以记录 OTP、Token 或敏感表单,后续再删除。
+2. Italy 最终提交可以使用普通重试。
+
+该决定覆盖 T-09/T-10、H-07、UT-04/06/12/13、IT-03、RC-05/06 及 R3 的旧规范。
+落实后的精确语义是:一次 `book()` 调用最多点击一次最终按钮;可确认成功才返回成功;明确
+拒绝、超时、断线或结果未确认均作为普通失败交回现有 Booker。后续调度重新进入服务、准备
+日历、重查库存并取得新的日期/时段及运行时 ID 后再次调用;仍健康的申请人登录会话可以复用。Italy 不再维护跨调用的
+`BookingOutcomeUnknownError` 暂停、持久提交 fence 或复杂 reconciliation。Query 零最终写入、
+Query/Book 账号隔离、申请人当前库存重查和失败不得误报成功仍是硬约束。
+
+敏感日志允许范围只改变当前调试/准出约束,不代表应把账号密码、Cookie、Token、OTP 或个人
+资料提交到 Git;本轮可删除只为脱敏证明存在的生产包装和测试,历史记录中的脱敏结果保持原样。
+
+CR-001 的 R3 生产实现和消费者迁移已完成:Italy **3532 → 2883,净减 649 行**,SHA-256
+`f3d3fbd013e5e311d31162bad86d2d699640f949681dc90aa129b6d5a3d05c11`。生产仅保留当前申请人和
+选择读回、一次网站原生点击及明确响应判定;旧预约列表/详情读取、未知暂停、跨调用 fence、
+复杂 reconciliation 和多层证明对象已删除。`OrderBookerGCO` 未修改,其既有普通失败分支保留
+任务并在下一信号再次调用 Book。
+
+当前验证:最终/Booker/工作流/热更新/重进服务定向 144 项,Italy 389 项,调试 280 项,框架
+离线入口 75 项,配置/账号 27 项,全部 exit 0、0 skip;5 个核心文件 AST 解析、生产禁止导入
+`tools.*`/`test.*` 及 `git diff --check` 通过。框架离线入口首轮因仍点名两个已删除旧测试而有
+2 个加载错误,清单迁到 `test_ita_booking_final`、`BookerReuseTests` 和新 gate 用例后恢复 75 项
+通过,没有恢复旧类壳或删除业务断言。
+
+全部测试均为合成浏览器、请求、账号、Redis/宿主边界;没有访问网站、邮箱、账号池、订单或
+预约,没有 Git 提交、推送或部署。H-07 获得当前离线证据;H-08、RC-01、现场 RC-05/09 及
+整体 RC-10 仍未完成。该历史节点约 1000 行尚差 1883 行;后续 R2 结果如下。
+
+### R2:月份扫描与候选状态收敛
+
+R2 已完成离线实现:Italy **2883 → 2823,净减 60 行**,SHA-256
+`91acff67527b6a4d3c8775ada88b8855f64191f90a11f03142a7544c1eb276ca`。Query 与 Book 现在只使用
+一个不可变月份表示;独立 Query 扫描结果类、Book 捕获包装、初始/下一月二行包装和 Query 提示
+日期优先双扫描均已删除。Query 信号只负责唤醒,Book 在申请人当前库存中按日期/时段升序选择。
+
+第一轮 68 项定向回归只有 1 个旧“双捕获”断言失败,迁移后通过;最终 Italy 385 项、调试
+280 项、框架离线 75 项、配置/账号 27 项全部 exit 0、0 skip,5 个核心文件 AST、生产导入限制
+及 `git diff --check` 通过。测试均模拟外部边界;未访问网站、邮箱、账号池或订单,未发送 OTP、
+AVANTI 或最终预约,未执行 Git/部署。H-03/H-05、RC-03/04 增加证据;当前距约 1000 行仍差
+1823 行,下一结构包为 R4。
+
+### R4:表单、OTP 与 Turnstile 准备链收敛
+
+R4 已完成离线实现:Italy **2823 → 2752,净减 71 行**,SHA-256
+`a2d313755c631b15cbb360fdd1596c8317a40816a9cfb87e5d8513ad442e59e5`。生产表单合同从约二十个
+Python 镜像字段收为 `formReady`、`turnstileReady`、`otpValuePresent`、`otpSendEnabled`、
+`avantiEnabled` 五个普通布尔事实;底层脚本仍逐项校验来源、路径、表单目标、方法、编码、上传、
+配置标签和值、隐藏同步、单人、Privacy、未知必填字段和唯一控件。生产阶段枚举、敏感日志门禁及
+Turnstile 恢复状态类已删除;调试工具只保留自己的阶段名称用于输出。
+
+R4 没有新增公共生产代码或 Italy 运行时文件。Turnstile 继续直接复用 VFS 已采用的
+`CloudflareBypasser.click_verification_button(is_dfs=False)`;OTP 继续复用
+`VSCloudApi.fetch_mail_content`;最终普通重试继续由现有 Booker 承担。公共
+`utils/plugin_utils.py` 仍为 497 行,SHA-256
+`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+当前验证:R4 定向 279 项、Italy 385 项、调试 280 项、框架离线入口 75 项、配置/账号 27 项,
+全部 exit 0、0 skip;10 个编辑过的 Python 文件 AST 解析、生产禁止导入 `tools.*`/`test.*`、
+三个已删生产符号搜索及 `git diff --check` 通过。首轮迁移有一个测试夹具重复关键字错误;进一步
+删除日志门禁时 OTP 输入异常曾绕过业务异常分类。分别修正夹具和恢复 `CalendarGateError`(保留
+CR-001 允许的原始诊断信息)后通过,未放松表单或邮箱合同。
+
+全部边界为模拟;没有访问真实网站、邮箱、账号池、订单或预约,没有发送 OTP、AVANTI 或最终
+预约,也没有 Git 提交、推送或部署。H-06 获得当前离线证据;H-08、RC-01、现场 RC-06/09 和
+整体 RC-10 仍未完成。当前距约 1000 行仍差 1752 行,下一结构包为 R5,不能把本轮 71 行下降
+外推为总预算已经成立。
+
+## 2. 工作包记录模板
+
+```text
+工作包:W__ / 名称
+日期与执行人:
+文档版本:
+当前授权范围:
+代码基线 / 工作区指纹:
+引用技术决策:T-__
+引用假设:H-__
+引用测试与准出:UT/IT/LT-__;RC-__
+
+开始前:
+- 本次具体目标:
+- 修改文件/函数:
+- 已有公共参照与为何适用:
+- 预计删除/保留/合并内容和行数:
+- 配置、公共消费者、热更新影响:
+
+结束后:
+- 实际改动:
+- 复用能力:
+- 是否偏离方案;对应变更编号:
+- 测试迁移去向:
+- Italy 完整文件行数:
+- 新增公共生产代码及消费者:
+- 全仓生产代码净变化:
+- 精确命令、退出码、通过/失败/跳过数量:
+- 外部边界:离线模拟 / 真实网站 / 真实邮箱 / 真实提交
+- H 假设状态与证据:
+- 未解决问题、风险等级:
+- 本包结论:通过 / 未通过 / 部分完成
+- 下一步:
+```
+
+## 3. 业务测试迁移表模板
+
+| 原测试/业务断言 | 对应 T/测试编号 | 新测试位置 | 处置 | 证据 |
+| --- | --- | --- | --- | --- |
+| 待 W0 盘点 | | | 保留/迁移/仅旧结构断言被替换 | |
+
+“删除了对应实现”不是删除业务断言的理由。若测试只验证旧类名、旧分区或初次机械搬迁字节一致,可替换为现行契约检查,但必须说明不再适用的原因。
+
+## 4. 配置/工具消费者表模板
+
+| 消费者 | 当前依赖的公开/私有契约 | 保留或迁移方式 | 支持命令/配置 | 验证结果 |
+| --- | --- | --- | --- | --- |
+| `tools/plugin_tester.py` | 待盘点 | | | 未验证 |
+| `tools/debug_ita_query_book.py` 及本地框架适配 | 待盘点 | | | 未验证 |
+| 其他 `tools/debug_ita*` | 待盘点 | | | 未验证 |
+| 当前 Sentinel/Booker 配置 | 待盘点;不得输出凭据 | | | 未验证 |
+
+对旧命令的移除必须给出替代入口和行为差异,不允许因为私有类被删让用户运行时才遇到 ImportError。
+
+## 5. 方案变更模板
+
+```text
+变更编号:CR-___
+日期:
+涉及文档版本和 T/H/测试/RC 编号:
+新事实与证据:
+原方案为什么不成立:
+选项及利弊(包括继续复用原模块的方案):
+推荐变更:
+对行数、行为、配置、公共消费者、热更新、周期的影响:
+需要补充的测试:
+用户确认记录:待确认 / 已确认(引用日期与范围)
+实施状态:未实施 / 已实施并验证 / 需修正
+```
+
+不能先实现重大偏离再倒填“已确认”。缩小范围、增加人工步骤、放宽行数、改变提交重试策略都属于需明确确认的变更。
+
+## 6. 最终准出记录模板
+
+| RC 编号 | 状态 | 当前证据位置/命令 | 尚缺事项 |
+| --- | --- | --- | --- |
+| RC-01 | 未验证 | | |
+| RC-02 | 未验证 | | |
+| RC-03 | 未验证 | | |
+| RC-04 | 未验证 | | |
+| RC-05 | 未验证 | | |
+| RC-06 | 未验证 | | |
+| RC-07 | 未验证 | | |
+| RC-08 | 未验证 | | |
+| RC-09 | 未验证 | | |
+| RC-10 | 未验证 | | |
+
+最终结论:未完成。只有全部适用条目得到当前证据支持后才能更改。

+ 158 - 0
docs/italy-refactor/07-reduction-inventory.md

@@ -0,0 +1,158 @@
+# Italy 生产代码精简盘点
+
+日期:2026-09-01。原盘点基线为 `plugins/ita_plugin.py` 3566 行;R1/R3/R2/R4/R5 后当前为
+2598 行,SHA-256 `2af5585124d6e73892a0043c24da1a8014f154644906dca356d6df43a9b71569`。
+
+本文件是后续实施的删除清单,不是另一个设计。若与
+[技术方案](01-technical-design.md) 冲突,以技术方案和用户最新指令为准。
+
+CR-001 已确认两项结构性减法:敏感日志脱敏层可在本轮删除;最终提交失败统一交回 Booker
+普通重试,Italy 不再维护跨调用的未知暂停、持久提交 fence 或复杂 reconciliation 状态机。
+
+## 1. 结论
+
+当前问题不是算法慢,而是同一事实被多层对象、快照、验证器和诊断接口重复表示。
+R3 以宿主 Booker 替代 Italy 专属提交状态机后一次净减 649 行,证明整块删除有现成宿主
+归属的职责有效;R4 删除重复表单表示和状态类 71 行,R5 删除生产 profile/锁与诊断状态 154 行。当前仍需从 2598 行净减约 1598 行,
+不能退回逐个包装器微调,也不能把 Italy 专属逻辑搬入公共文件冒充精简。
+
+后续改为整块收敛:以 `ItaPlugin.query()`、`ItaPlugin.book()` 和宿主生命周期为生产
+合同,保留真实网站协议和必要安全边界;删除只为离线取证、私有测试接口或历史迁移
+存在的生产结构。测试迁移到公开行为和少量协议边界,不再以“旧私有符号仍存在”作为
+兼容条件。
+
+## 2. 当前分区与目标
+
+| 分区 | 当前行数 | 目标 | 主要删除对象 |
+| --- | ---: | ---: | --- |
+| 配置、协议和库存模型 | 404 | 140 | 多层字段验证函数、仅用于展示的状态枚举、嵌套配置包装 |
+| Query 日历 | 362 | 120 | 请求监听、月份导航和必要解析;R2 已删除独立扫描结果层 |
+| Book 日历 | 551 | 180 | 日期/时段上下文和读回包装;R2 已删除提示日期优先双扫描 |
+| 最终提交与明确响应判定 | 135 | 200 | R3 已低于预算;不再继续为行数删除一次点击和严格匹配 |
+| 表单、OTP、Turnstile 和准备工作流 | 497 | 220 | R4 已删除多阶段快照模型、日志门禁和恢复状态类;剩余是页面脚本、OTP 与线性准备 |
+| 登录、插件入口和生命周期 | 758 | 120 | 调试专用持久 profile、重复身份字段、私有工具钩子和转发层 |
+| 组织开销 | 45 | 20 | 历史分区说明与不再准确的迁移注释 |
+| **合计(R5 前盘点)** | **2752** | **1000** | R5 后实测 2598;需重新划分剩余结构,不自行扩大总预算 |
+
+目标不是通过压行、分号或外置巨型字符串取得。每批同时记录生产文件行数、公共生产
+代码变化、测试结果和被删除行为的归属。
+
+## 3. 直接复用的公共能力
+
+| 能力 | 现有来源 | Italy 动作 |
+| --- | --- | --- |
+| 插件接口与宿主调度 | `IVSPlg`、Sentinel、Booker | 只实现接口;不实现池子、Redis、退避或订单状态机 |
+| 浏览器、代理、指纹 | `init_chromium_options` | 直接调用;Italy 只提供账号、代理和目录 |
+| 登录流程调度 | `BaseFlow`、`on`、`guard`、`done` | 只保留 Prenot@Mi 页面规则 |
+| 鼠标与键盘 | `HumanMouse`、`HumanKeyboard` | 直接使用,不包装第二层交互框架 |
+| 日期范围 | `filter_dates_in_range(..., shuffle=False)` | Query 取首个正向月最早日;Book 按用户范围重查 |
+| 邮箱 OTP | `VSCloudApi.fetch_mail_content` | 只保留 Italy 发件人、模板、当前账号和发送时间约束 |
+| 公共返回与异常 | `VSQueryResult`、`VSBookResult`、现有异常 | 不再创建平行的业务结果体系 |
+| 清理 | `cleanup_browser_workspace` | 直接复用现有默认合同;不修改公共签名,不复制目录/隧道销毁逻辑 |
+
+`perform_browser_fetch` 只有在 H-04 真实对照通过后才能替换月份原生请求。当前不为了省行
+擅自切换生产传输。
+
+## 4. 不下沉到公共模块的内容
+
+- Prenot@Mi 的双层 JSON、服务 ID、日期/时段字段、DOM 选择器和最终提交参数。
+- Turnstile 页面状态和 Prenot@Mi 的 OTP 表单。
+- Calendar 原生请求监听。它目前只有 Italy 一个生产消费者;移到 `utils` 只是搬家。
+- 预约列表与最终回执语义。VFS/TLS/BLS 的网站结构不同,强行抽象会制造新的框架。
+
+只有出现第二个真实插件消费者,或补全现有公共函数的通用返回能力时,才向后兼容扩展
+公共模块。新增公共基类会使单文件热更新依赖宿主先升级,本轮不采用。
+
+## 5. 五个结构性工作包
+
+### R1:协议与配置
+
+保留一份路由对象、日期对象、时段对象和稳定协议异常。配置在入口一次校验;日历与时段
+共用一个双层 JSON 解码器。删除只为层层转发存在的 `CalendarScanConfig`、`InventoryState` 和
+重复模型校验。`FormControlConfig` 暂保留为两个页面控件共用的三字段命名结构;把它展平成
+route 六个字段或位置元组既不会减行,也会降低表单脚本可读性,后续只随 R4 一起重估。
+
+通过标准:服务/能力/月份、双层 JSON、日期、库存、时段 ID、OTP 六位 ASCII 和账号邮箱
+约束仍失败关闭;不同领区继续只由配置决定。
+
+### R2:Query/Book 日历(已完成离线实现)
+
+保留一个严格、不可变的 `CalendarProbeResult` 作为网站月份边界,以及一个只读逐月扫描和
+“日期→时段→选中并读回”调用链。Query 在首个正向月份停止并返回最早日期;Book 使用申请人
+会话重新扫描并选最早合格时段。`CalendarQueryScanResult`、`_CapturedMonth`、初始/下一月二行
+包装和提示日期优先双扫描已删除;Query 诊断只保存不可变月份元组,不保存第二份候选状态。
+
+当前结果:R2 为 2883 → 2823,净减 60 行;Query 分区 385 → 362,Book 分区 588 → 551。
+Query 信号日期只负责唤醒,不再覆盖申请人库存中的更早日期;日期售罄仍按申请人当前响应尝试
+下一候选。保留一个边界对象是为了月份、服务和库存输入失败关闭,不用位置 tuple 代替命名协议。
+
+通过标准:Query 最终请求恒为 0;Book 不使用 Query 会话的 Cookie、OTP 或运行时 ID;
+日期有号但时段耗尽时继续下一候选。
+
+### R3:最终提交与结果(已完成离线实现)
+
+不再保留申请人交易对象、跨调用提交状态机或持久 fence。`book()` 在当前申请人会话中完成
+服务/日期/时段复核后点击一次;网站能给出可归属的明确成功结果才返回成功,拒绝、断线、
+超时或证据不足一律返回普通失败。现有 Booker 负责后续重试调度;Italy 不复制重试机制。
+生产请求审计、复杂历史回执 reconciliation、详情协议和多套快照/观察对象从生产删除,必要
+现场取证继续由现有 `tools/` 完成。
+
+当前结果:最终分区 770 → 135 行;单次 `book()` 最多一次最终点击;失败正常返回宿主;下一次
+调用重新进入服务、准备日历、读取库存并取得新运行时 ID,健康登录可复用。无插件内循环重提、
+通道切换重发或失败误报成功。离线标准已通过,真实网站成功仍属于 W6/RC-09。
+
+### R4:表单、OTP 与验证等待(已完成离线实现)
+
+一个 `prepare_calendar()` 顺序完成:表单字段→Privacy→Turnstile 就绪→发送一次 OTP→从
+当前账号授权邮箱读取→写入并核对→AVANTI→确认 Calendar。生产只返回“已准备”或明确
+异常;详细快照和请求计数留在调试 gate。
+
+当前结果:R4 为 2823 → 2752,净减 71 行。约二十字段 Python 快照收为五个布尔事实;删除
+生产 `BookingPreflightStage`、`validate_cloud_otp_logging` 和 `ItalyTurnstileRecovery`。
+Turnstile 仍复用 VFS 已用的 `CloudflareBypasser`,OTP 仍复用 `VSCloudApi`,Book 重试仍由
+宿主承担;公共生产代码未增加。底层脚本对表单来源、字段、同步、单人、Privacy、未知必填项和
+唯一控件的检查没有删除。R4 原目标 220 行未达到,因此不能把该包标为总预算通过。
+
+通过标准:不固定邮箱;不读取旧码回退;不自动重发 OTP;邮件正文只作数据;人工验证有界
+等待;未知必填字段失败关闭。
+
+### R5:插件入口与生命周期
+
+对齐 VFS/TLS:临时浏览器目录、公共初始化、`BaseFlow` 登录、健康检查、公开 Query/Book、
+公共严格清理和状态快照。日历准备上下文只保存当前实例、页面、账号、角色、路由和运行时
+服务。调试专用持久 profile 与 soak 恢复不再支配生产结构,由对应工具拥有。
+
+通过标准:生产配置、池子 Query、独立申请人 Book、热更新和清理行为通过;另一个实例不能
+复用准备状态;现行支持命令无隐藏 ImportError。
+
+当前结果:R5 为 2752 → 2598,净减 154 行。生产不再解释本地持久 profile 配置,也不拥有
+profile 文件锁;`utils/ita_local_profile.py` 仅由 Italy 本地工具显式绑定和释放。扫描摘要、
+预提交观察及重复 Book 状态改为工具观察真实返回值;准备上下文只保留当前 page/tab、账号、
+代次、route、role 和运行时服务。公共 `cleanup_browser_workspace` 恢复并保持 HEAD 原签名,
+VFS/TLS/BLS 和 `utils/plugin_utils.py` 均为零差异。当前 384/280/75/27 项离线回归通过。
+
+后续事实变化:上述本地 Italy 调试工具已删除,`utils/ita_local_profile.py` 因而失去最后一个
+运行调用者,现已连同专属测试删除。生产继续使用实例临时工作区,不恢复持久 Profile 配置。
+
+## 6. 测试取舍
+
+保留并优先执行:
+
+1. `query()` 的无号、首个正向月、认证失效、限流和最终请求为 0。
+2. `book()` 的独立账号、自动 OTP、日期范围、库存竞争、预提交和一次最终提交。
+3. 成功、拒绝、超时/断线普通失败、连续独立调用和跨账号结果归属。
+4. 两套不同服务配置、插件测试器、Sentinel→Booker 离线串联和单文件热更新。
+5. 公共 VFS/TLS/BLS 回归,证明公共函数改动没有退化。
+
+迁移或删除:只断言私有类名、私有字段数、诊断 JSON 键全集、历史脚本源码字符串和旧分层
+调用次数的测试。测试数量不是准出条件;公开行为覆盖和零 skip 才是。
+
+## 7. 实施顺序与停止条件
+
+顺序为 R1→R3→R2→R4→R5:五包均已完成,但 2598 行仍未达到 RC-01。下一结构包重新审计日历捕获、选择和表单脚本的重复表示;每包开始前记录基线,结束后记录差异、测试和剩余预算。
+若某包为了保留真实行为不能达到其预算,先在
+[可行性分析](02-feasibility.md) 记录证据并调整下一包结构;不靠删除安全断言补数字。
+
+任何包出现以下情况立即停止并修正:Query 触发最终写入、Book 复用池子会话、OTP 可能读取
+错误账号、同一次 `book()` 出现多次最终点击、重试复用旧运行时 ID、失败被误报成功、单文件
+热更新依赖新增 Italy 运行时文件。

+ 79 - 0
docs/italy-refactor/README.md

@@ -0,0 +1,79 @@
+# Italy 插件精简重构:文档入口与执行约定
+
+版本:1.1;建立日期:2026-09-01。
+
+最新架构决定(CR-001,2026-09-01,用户已确认):Italy 调试期允许记录 OTP、Token 与敏感表单;最终提交失败、超时或结果未确认按普通失败交回 Booker 后续重试。单次 `book()` 仍最多点击一次,Query 仍不得产生最终写入。此决定覆盖旧文档中的脱敏准出和 `BookingOutcomeUnknownError` 暂停策略。
+
+本目录记录用户要求的约 1000 行 Italy 插件技术方案,以及可行性、开发周期、测试和准出要求。后续相关开发必须以本目录为依据,不允许实现过程中另起一套架构。
+
+当前状态:方案文档已建立;[W0 行为基线](records/W0-baseline.md)、[W1 公共能力](records/W1-shared-lifecycle.md) 与 [W2 登录/准备收敛](records/W2-login-preparation.md) 已留档。[W3 查询入口及共用日历](records/W3-query-entry.md)、[W4 Book 与提交职责收敛](records/W4-selection-readback.md) 仍只部分完成。[W5](records/W5-tools.md) 已把失效的旧文档账号池命令迁到现有 Query+Book CLI。R6/R7 及异步表单竞态修复后,Italy 生产运行时为 **1178 行**,SHA-256 `c6566021f997b5b9a1228229bd2f206b33c65a2c573c18acb78b89a960ccef7e`;同仓 VFS 为 1271 行、BLS 1107 行、TLS 852 行,已进入同一量级。当前协议、OTP、Query/Book、登录、公共生命周期与异步表单等待的 69 项精简合同测试及 15 项配置测试通过;旧的实现耦合诊断套件及工具仍在迁移,因此不能沿用旧版“全部测试通过”结论。生产只调用既有公共合同;VFS/TLS/BLS 与 `utils/plugin_utils.py` 均无差异。修复后的真实 Query、现场真实预约、全量消费者迁移与发布尚未完成。未提交、推送或部署。
+
+## 1. 目标不能被替换
+
+- 最大化复用现有公共模块和 VFS/TLS/BLS 做法,将 `plugins/ita_plugin.py` 从 6286 行收敛到约 1000 行。
+- Query 就是查询;Book 就是预约。保留账号池 Query 与用户账号 Book 的职责分离。
+- 不依赖浏览器环境的已验证接口使用 HTTP;依赖浏览器环境的流程使用浏览器或浏览器内请求。不能靠猜测切换通道。
+- 支持通用短期申根旅游签证、单人预约;香港只是现场验收样本,不得硬编码香港。
+- 单文件上传、热更新继续可用;不能把几千行 Italy 私有代码搬到其他文件冒充精简。
+- 不是从零重写协议:保留已验证的网站行为,替换重复能力、合并冗余层次。
+
+质量对齐现有插件的工程方式,而不是照搬其他网站的字段和状态码;提交失败按用户确认的普通重试语义复用现有 Booker。
+
+## 2. 阅读与执行顺序
+
+| 文档 | 回答的问题 | 何时必须查阅 |
+| --- | --- | --- |
+| [01 技术方案](01-technical-design.md) | 代码放哪里、复用谁、哪些删、哪些保留 | 开始任务、设计或代码审查时 |
+| [02 可行性与假设验证](02-feasibility.md) | 哪些已知、哪些待验证、失败后怎么办 | 开始工作包、变更传输方式或发现新事实时 |
+| [03 开发周期与工作包](03-development-plan.md) | 按什么顺序做、预计多久、每步交付什么 | 安排任务、报告进度时 |
+| [04 测试计划](04-test-plan.md) | 用什么证据证明行为没被压缩坏 | 写测试、修改实现、回归和现场验收时 |
+| [05 准出与发布条件](05-release-criteria.md) | 什么叫完成、什么情况不能发布 | 合并、发布、宣称完成前 |
+| [06 执行记录与变更模板](06-execution-records.md) | 如何留下可核对的过程和结果 | 每个工作包开始与结束时 |
+
+当前 W5 工具迁移记录见 [现有工具与完整回归](records/W5-tools.md)。
+
+技术决策使用 `T-xx`,假设使用 `H-xx`,工作包使用 `W0` 至 `W6`,测试使用 `UT/IT/LT-xx`,准出条目使用 `RC-xx`。执行记录必须引用这些编号,使需求、实现、测试能相互追溯。
+
+实际开发时直接使用 [开发计划第 2.1 节的阶段执行对照表](03-development-plan.md):每一阶段都列明必须查阅的约束、需要验证的假设及完成证据。此要求也写入仓库根 [AGENTS.md](../../AGENTS.md),后续任务进入 Italy 工作时必须先读取。文档按技术方案约束实现;不能在实现之后悄悄改文档或测试来迁就代码。
+
+## 3. 当前事实基线
+
+核对日期:2026-09-01;代码提交:`a22596f1fcdffb946960724ef299f249e7860891`。
+
+| 文件 | 基线行数(`wc -l`) | 说明 |
+| --- | ---: | --- |
+| `plugins/ita_plugin.py` | 6286 | 11 个旧运行时文件机械合并后的单文件 |
+| `plugins/tls_plugin.py` | 852 | 已复用浏览器公共工具及 `BaseFlow` |
+| `plugins/vfs_plugin.py` | 1271 | 已复用浏览器公共工具、云端邮件 API 等 |
+| `plugins/bls_plugin.py` | 1107 | HTTP 为主,复用现有云端接口和类型 |
+
+行数包含注释、空行和 JavaScript;其他插件也调用公共模块,因此入口行数不是项目的全部运行时代价。
+
+现场约束:`config/test_conf.json` 有用户改动,多份旧 Italy 文档处于删除状态。本目录是新文档集,不恢复或覆盖这些改动。旧源码和历史提交是参考证据,不是新实现已经通过测试的证明。
+
+## 4. 每个工作包怎么执行
+
+1. 读取对应技术决策、假设、测试及准出条目,检查实际代码是否仍符合记录。
+2. 写明本次范围、文件、复用对象、预期行数变化和验证办法,再开始已获授权的修改。
+3. 优先复用现成函数;需要增加抽象时写清现成实现为什么不能覆盖。
+4. 结束时填写实际改动、精确命令、退出码、测试结果、行数及剩余问题。
+5. 有未通过的前置条件,不把下一步或最终完成标成通过。可以做不依赖该条件的其他工作,但必须如实记录。
+
+文档不是额外的形式主义:一个工作包只需一份简洁记录,不为每个函数生成一份报告。
+
+## 5. 方案变更规则
+
+- 本目录技术约束不得被临时调试代码、旧注释或测试夹具悄悄覆盖。
+- 一般实现细节可在已批准方案内决定,并在执行记录说明。
+- 架构、功能范围、约 1000 行目标、公共 API、配置语义、账号隔离、预约提交与重试策略的改变,必须先给出证据和文档差异,取得用户确认后实施。
+- 不得为已写出的代码倒改测试或准出标准,使其看起来完成。
+- 修改文档时同步更新受影响的测试、工作包和准出引用;旧证据保留并标明失效原因。
+- 实施、Git 提交/推送、部署、真实预约的授权分别核对,不由文档自动授予。
+
+## 6. 当前下一步
+
+生产运行时已从 6286 行收敛到 1178 行,主要通过直接复用 `perform_browser_fetch`、`BaseFlow`、`init_chromium_options`、`cleanup_browser_workspace`、`filter_dates_in_range`、`VSCloudApi.fetch_mail_content` 和宿主公共类型,删除私有请求监听、诊断状态机、回执协调器与重复页面快照。Query 保持逐月扫描并在首个正向月份停止;Book 在申请人会话重新读取库存、选择日期/时段,最终写入每次调用至多一次,普通失败交回现有 Booker。2026-09-01 现场发现并修复 Booking/Purpose 异步选项晚于首次预检的竞态;表单未就绪现在有界轮询,且不会提前触碰 Turnstile 或发送 OTP。
+
+Italy 专属测试与辅助模块现已统一归档到 `test/ita/`;新的 Italy 测试继续放在该包内,通用测试根目录不再散落 Italy 文件。无调用者的 `utils/ita_local_profile.py` 及两个只测试已删除本地调试工具的文件已经移除,混合测试中对应的持久 Profile 用例也已清理。当前公开薄合同 68 项通过;完整 discovery 仍如实暴露其他依赖已删除私有符号或历史工具的旧消费者。
+
+下一步不是继续设计生产架构,而是迁移仍导入已删除私有符号的 Italy 调试工具和旧测试,使它们调用公开 Query/Book 合同;不能把旧私有实现重新塞回生产来换取测试通过。完成迁移后再跑完整 Italy/调试/热更新回归,并在另行授权下执行真实站点 Query、预提交和单次最终验收。实施授权仍不自动包含 Git、推送、部署或真实预约。

+ 80 - 0
docs/italy-refactor/records/W0-baseline.md

@@ -0,0 +1,80 @@
+# W0:行为与消费者基线
+
+日期:2026-09-01;依据:T-01/T-02/T-11/T-12、H-01/H-02/H-11、UT-01/02/03/15、IT-04/05/06、RC-02/08/10。
+
+范围:只读源码/配置结构、离线测试和文档记录;未登录网站、读取邮箱、申请账号或提交预约。配置凭据不进入记录。
+
+## 1. 代码与工作区
+
+- HEAD:`a22596f1fcdffb946960724ef299f249e7860891`。
+- Italy SHA-256:`d2088578c17f0f898a5af307d933b6b55c8e048eecdb9e46b3789acdea98364e`;6286 行。
+- 用户修改 `config/test_conf.json`;删除多份旧 Italy 文档,包括机械迁移 manifest 和旧验收说明。保持不动。
+- 新文档及根 `AGENTS.md` 未提交;本记录不代表 Git 或上线授权。
+
+## 2. 实际测试结果
+
+命令均从仓库根目录运行,前缀为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。
+
+| 命令后缀 | 结果 | 解释 |
+| --- | --- | --- |
+| `-m unittest discover -s test -p 'test_ita*.py'` | exit 1;166 项,13 error | 缺 `-t .`,误导入 `test/test.py`,不是 Italy 需要 OpenCV |
+| `-m unittest discover -s test -p 'test_debug_ita*.py'` | exit 1;141 项,21 error | 同一 discovery 路径问题 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 1;511 项,1 error,0 skip | 唯一 error 是旧机械迁移 manifest 已删除;其余 510 项通过 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;313 项,0 skip | 全部通过;含受限于自有 Unix socket 的一次性本地 Redis 测试,不访问远端 Redis |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录 | 7 个旧文档命令测试及其 subTest 依赖已删除的 `docs/ita_query_book_acceptance.md`;其余 19 项通过 |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip | 使用现有 Sentinel/Booker 方法,网站、云端及邮箱边界模拟;与上述 suites 有重叠,不重复累计 |
+
+已在测试计划修正 discovery 命令。不安装无关依赖、不恢复用户删除的旧文件、不将失败测试跳过。重构期间迁移旧文档/内部结构依赖,保留其业务断言。
+
+## 3. 配置消费者
+
+| 消费者 | 现状 | 迁移要求 |
+| --- | --- | --- |
+| Sentinel 香港配置 | `calendar`、`cloud`、最终提交关闭;`slot.hkg.it.tourist` | 保持字段;调用公共 Query 返回真实最早日期 |
+| Sentinel/Booker Dublin 旧配置 | `services_probe`、未设置 OTP、最终提交关闭;`slot.dub.it.tourist` | 显式报告未配置完整日历能力;不能把旧弱信号发布为有号,不能虚构该领区字段 |
+| 公共 PluginTester Italy 配置 | `calendar`、`cloud`、最终提交关闭;香港路由 | 保留已有配置加载器;不覆盖用户账号变更 |
+| 本地串联 `build_groups` | 从 Query 配置复制;申请人设 `services_probe`、独立账号、显式提交开关 | Book 不再通过公开 Query 进入表单;仍走现有框架、原配置入口 |
+| debug session / soak / book gate | 私有本地账号文件、可选持久化 profile、手动/自动 OTP、扫描选项 | 保留已支持命令或逐一给出替代,不能让私有 import 失效 |
+
+## 4. 工具与私有接口迁移台账
+
+此处的“迁移”是后续动作,当前工具尚未改动。私有符号按职责列出,代码中的 `from plugins.ita_plugin` 及模块别名访问已用 AST 盘点。
+
+| 工具 | 当前依赖 | 迁移目标 |
+| --- | --- | --- |
+| `tools/plugin_tester.py` | `IVSPlg` 公开接口、配置、注册、报告 | 原入口继续使用,不另写测试器 |
+| `debug_ita_session.py` / `debug_ita_monitor.py` | `ItaPlugin`、持久化配置键 | 保留公开会话/健康接口 |
+| `debug_ita_query.py` | 插件及 `BOOKING_FORM_DISCOVERY_SCRIPT` | 真实 Query 走公开接口;弱探测仅明确诊断 |
+| `debug_ita_calendar_gate.py` | 路由/月份 DTO、解析器、监听/翻月/刷新、preflight、OTP、AVANTI、audit | 改为新准备/查询接口;诊断计数留 tools,避免旧运行时影子实现 |
+| `debug_ita_soak.py` | Query 异常、guard、checkpoint/restore 方法 | 保留长会话恢复合同,迁移到新实例状态 |
+| `debug_ita_book.py` | 结果标签、mail 配置/环境校验、audit、service/selection 读取 | 保留公开 Book 调用和预提交/自动 OTP 选项 |
+| `debug_ita_book_gate.py` | 路由/approval、日历就绪、表单校验、日期偏好、receipt port | 迁移预提交诊断,不在工具重写 Book |
+| `debug_ita_reservation.py` | reservation DTO/状态、列表/详情读取、日期诊断 | 调用紧凑回执读取;保留独立只读检查 |
+| `ita_final_evidence.py` | final attempt/submitter/target、signal、receipt port、selection | 保留原本地文件独占创建提交保护;绑定新提交入口 |
+| `ita_query_book_local.py` | route/mail/date helpers、audit、实例 runtime globals、上述最终提交保护 | 保留真实 Sentinel/Booker 调用和账号分离;不新增调度链 |
+| `debug_ita_query_book.py` | 上述本地工具及明确的离线测试集 | 保留 `--offline`、`--local-run`、`--submit-once` 等现行 CLI |
+| `ita_local_handoff.py` / `add_ita_query_account.py` | 本地/云端现有边界,无 Italy 私有运行时直接导入 | 不扩展职责;跑现有离线回归 |
+| `consolidate_ita_plugin.py` | 历史 Git 内容、机械搬迁 manifest | 仅为历史迁移工具;不得用于生成/恢复重构前运行时 |
+
+## 5. 测试迁移分组
+
+| 旧测试文件/断言 | 追溯 | 处理 |
+| --- | --- | --- |
+| `test_ita_plugin` 登录、profile、cleanup | UT-01/02/04 | 只迁移公共工具 mock 边界,保留提交一次、无刷新、会话证明与资源检查 |
+| `test_ita_protocol` / `otp` / `preflight` / `workflow` | UT-05/06/07/08/14 | 保留输入错误、邮箱/时间绑定、验证码和库存边界;不复制旧 DTO 实现 |
+| `test_ita_calendar_query` / `query_recovery` / `calendar_soak` | UT-09、IT-01 | 保留最早日期、首个正向月份、恢复与重复准备次数 |
+| `test_ita_calendar_book` / `calendar_book_flow` | UT-03/10/11 | 保留不同账号、日期偏好、竞态、原生选择和 runtime ID 来源 |
+| `test_ita_booking_final` / `final_attribution` / `reservation` / `final_read_port` | UT-12/13 | 保留至多一次写入、回执归属、列表覆盖和未知结果 |
+| `test_ita_booker_integration` / `test_debug_ita_query_book` | IT-01/02/03/05 | 仍测真正宿主方法,不能 Mock 成总是成功 |
+| `test_ita_single_file` | UT-15、IT-04 | 保留安装/热加载/多实例;替换“重构后必须仍与旧代码逐字/AST 相同”的两项搬迁检查 |
+| `test_plugin_tester_ita_config.ItalyDocumentedPoolCommandTests` | UT-14、IT-05 | 将已删除文档内的可执行命令迁往支持的工具入口,保留动态邮箱/账号池/日志/配置错误断言 |
+| 其余 `test_debug_ita*`、`test_ita_final_evidence`、`test_ita_local_handoff`、`test_add_ita_query_account` | IT-05、UT-12/14 | 随工具改动迁移;默认不提交、失败清理、CLI 错误和本地提交标记仍验收 |
+
+## 6. W1 可直接复用的证据
+
+- `init_chromium_options` 已由 VFS/TLS 使用;Italy 重复了端口、Chrome 路径、代理隧道、指纹及启动参数,且同一次 `create_session` 调用两次 `ChromiumPage`。
+- `filter_dates_in_range` 可用于已规范化日期;须明确 `shuffle=False` 并补齐两端默认值。
+- `cleanup_browser_workspace` 当前吞掉 quit/tunnel 异常;Italy 当前也无条件释放 profile 锁。按 H-02 单独测试,不能把“调用了 cleanup”当作资源已释放。
+- 登录调度、表单/OTP、日历协议、提交与回执尚不在 W0 修改范围。
+
+结论:基线已建立,既有故障已定位。可以开展不依赖缺失旧文档的精简;整体准出仍未通过。下一项是 W1 公共初始化/日期/清理,先补等价行为测试,再替换调用。

+ 44 - 0
docs/italy-refactor/records/W1-shared-lifecycle.md

@@ -0,0 +1,44 @@
+# W1:公共生命周期与日期能力
+
+日期:2026-09-01;依据 T-02/T-08/T-12、H-01/H-02、UT-01/02/03/15、IT-04/06、RC-02/08。
+
+## 范围和复用
+
+- `plugins/ita_plugin.py` 直接调用 VFS/TLS 已用的 `init_chromium_options`,删除手写端口、代理、Chrome 路径、指纹参数组装;同一会话仅构造一次 `ChromiumPage`。
+- 正向日期通过 `filter_dates_in_range(..., shuffle=False)` 筛选,先补齐默认边界并升序排列;协议错误仍由 Italy 原解析边界拒绝。
+- 使用现有 `cleanup_browser_workspace`。按技术方案预列的扩展候选增加关键字参数 `strict=False`:默认四位置参数调用不变;显式 strict 调用在浏览器退出失败时保留目录,继续处理其他资源后报告失败。
+- Italy 严格清理失败时保留页面句柄和 profile 锁;只在确认成功后清空引用、释放锁。不增加自动重试、池子或调度实现。
+- 用户配置、旧文档删除、网站协议、自动 OTP、Query/Book 公共接口及最终提交均未改变。
+
+## 行数和兼容性
+
+| 项目 | W0 | W1 | 净变化 |
+| --- | ---: | ---: | ---: |
+| `plugins/ita_plugin.py` | 6286 | 6192 | -94 |
+| `utils/plugin_utils.py` | 489 | 497 | +8 |
+| 本包生产代码合计 | 6775 | 6689 | -86 |
+
+新公共代码不含 Italy 服务、选择器、邮箱或回执字段。VFS/TLS 继续使用原四参数宽容模式;Italy 是严格模式的消费者。此接口需随宿主发布,只有原始宿主版本的节点不能只上传这版 Italy 文件;最终最低宿主提交号待获授权提交时填写。
+
+这只是第一批公共复用,不是 1000 行目标已经完成。旧模型、日历、表单与提交分层尚待后续大幅收敛。
+
+## 测试和迁移
+
+新增 `test/test_ita_shared_lifecycle.py` 7 项,覆盖真实公共初始化(代理/参数/单浏览器)、日期单边界/顺序、旧 cleanup 调用兼容、严格失败、profile 锁保留和显式清理恢复。
+
+先执行新增测试得到失败,再实现调用与扩展;修正一个缺少真实 profile 目录的测试夹具后全绿。
+
+旧登录测试只将 `ChromiumOptions` mock 移至 `utils.plugin_utils`,原登录断言保留。生命周期夹具补齐构造器本来就持有的字段。旧清理失败测试改为要求保留页面句柄,仍检查脱敏、健康失效及析构不自动重试。
+
+`test_ita_single_file` 两项“与首次机械搬迁源码/manifest 完全一致”已替换为“实现宿主公开接口”和“绑定真正公共工具”;安装器、热更新、多实例、最终未知异常及本地提交保护测试保留。没有恢复已删除的 manifest。
+
+| 实际命令(仓库根目录) | 结果 |
+| --- | --- |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;518 项,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;313 项,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;与前述套件有重叠 |
+| `git diff --check` | exit 0 |
+
+H-01 的公共参数/初始化部分离线通过,登录调度部分转 W2;H-02 当前用例通过。没有真实网站、邮箱或预约操作。W0 留档的旧文档命令测试仍待 W5 迁移,不能宣称整个仓库全绿或可上线。
+
+下一步 W2:在本插件内使用 TLS 同款 `BaseFlow`,保留 Italy 的域名/认证 DOM、一次凭据提交和异常分类;禁用停滞刷新并对框架日志/错误中的 OAuth 地址脱敏。主要文件为插件、登录行为测试,不另建登录调度框架。

+ 751 - 0
docs/italy-refactor/records/W2-login-preparation.md

@@ -0,0 +1,751 @@
+# W2:登录复用与表单/OTP 准备收敛
+
+日期:2026-09-01;状态:部分完成,不是 W2 或整体准出通过。
+
+本页保留各批次历史快照;最新工作区、回归失败及下一步以 [执行记录入口](../06-execution-records.md) 为准,不沿用本页旧指纹下的通过结果。
+
+依据 T-02/T-07/T-08/T-12、H-01/H-06、UT-04/05/06、IT-04/06、RC-02/06/08/10。
+
+## 1. 首批范围:登录复用
+
+文件为 `plugins/ita_plugin.py`、`test/test_ita_login_flow.py`;没有新增 Italy 生产运行时模块。复用 TLS 已使用的 `utils.flow_engine.BaseFlow/on/guard/done`,在同一个 Italy 文件中保留网站专属页面规则。
+
+- 原手写路由轮询改为 `ItaLoginFlow`;认证成功仍同时要求目标域名、`/UserArea`、菜单和 Services 链接。
+- 登录表单可以分次渲染;三个控件到齐才开始输入,首页进入与凭据提交各至多一次。
+- 关闭 BaseFlow 的停滞刷新,登录发起后的服务器错误不刷新重提。配置最多 40 轮、120 秒流程预算;这不是每项浏览器 I/O 的硬墙钟超时保证。
+- 凭据只允许填写到预期 HTTPS 主机,拒绝其他域名、非默认端口和带用户信息的地址。
+- 保留明确封禁及验证等待分支;不再把普通页面中的 `Cloudflare Ray ID` 字样单独当作封禁证据,也没有增加绕过验证能力。
+- 使用原 `_url_for_log` 统一去掉 OAuth 查询参数;额外去掉 URL 中可能出现的用户信息。异常和日志不包含凭据。
+
+以上是已有工作区改动的执行记录。本次文档整理没有新增登录、表单、OTP、日历或提交代码修改,也没有执行 Git 发布或真实业务操作。
+
+## 2. 首批行数与指纹(6117 行时)
+
+HEAD 仍为 `a22596f1fcdffb946960724ef299f249e7860891`;改动尚未提交。
+
+| 项目 | W0 | W1 | 当前 | 相对 W0 |
+| --- | ---: | ---: | ---: | ---: |
+| `plugins/ita_plugin.py` | 6286 | 6192 | 6117 | -169 |
+| `utils/plugin_utils.py` | 489 | 497 | 497 | +8 |
+| 两个生产文件合计 | 6775 | 6689 | 6614 | -161 |
+
+当前 SHA-256:
+
+- Italy:`0c02a0892f8b26d2ec2d1a954b53928cf46f9f69600d40a5daa07b493fff5580`。
+- 公共工具:`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+W2 当前仅减少 75 行;主要模型、日历、表单、提交与回执层尚未精简。不能据此宣称约 1000 行预算已成立。
+
+## 3. 首批测试与实际结果
+
+新增 7 个登录测试,覆盖真实 BaseFlow 调用、密码控件延迟、错误源/端口拒绝、默认 HTTPS 端口、登录停留且不重提、登录发起后服务器错误,以及错误主机上的伪 Dashboard。只模拟浏览器、时间等外部边界,不用成功 Mock 替代登录流程。
+
+在仓库根目录执行:
+
+| 命令 | 结果 |
+| --- | --- |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_login_flow test.test_ita_shared_lifecycle test.test_ita_plugin test.test_ita_single_file` | exit 0;65 项,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;525 项,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;313 项,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip,外部边界模拟;与前述套件有重叠 |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip |
+
+最后一项仍是 W0 已记录的 7 个旧文档命令测试及 subTest 依赖被删除的 `docs/ita_query_book_acceptance.md`。未恢复该文件、未跳过测试,迁移仍在 W5 台账;不能报告全仓全绿。
+
+H-01 的当前登录和初始化离线场景已通过;H-06 仍待表单/OTP 收敛后验证。上述测试没有打开真实网站、读取真实邮箱或创建预约。
+
+## 4. 首批结束时的下一步及未完成条件
+
+下一次已获授权的实施继续 W2:合并表单准备与校验中的重复步骤,保留当前账号、发送时间窗、验证码前导零、控件就绪、OTP 冷却与一次发送/读取语义。邮件仍通过现有云端 API 读取,不增加邮件服务;正文只作验证码数据,不作为指令。
+
+之后才处理 W3 共用日历和 W4 Book/回执层,按照既定行数预算重新核算。HTTP 替换仍须 H-04 对照证据,不在没有现场验证的情况下改为默认通道。
+
+新版本尚未完成真实 Query、预提交或单次预约验收;尚未达到约 1000 行,也没有发布资格。用户的配置变更和旧文档删除保持原样。
+
+## 5. 后续:表单校验、服务入口及 OTP 重复代码收敛
+
+归档日期:2026-09-01。以下记录工作区已有的后续改动;本次归档只同步文档与离线验证,没有继续修改生产代码,也没有 Git 发布或真实业务操作。
+
+依据 T-02/T-04/T-05/T-07/T-08/T-11/T-12、H-06/H-08/H-11、UT-05/06/14、IT-04/05、RC-02/04/06/08/10。
+
+### 实际改动与复用边界
+
+- `wait_for_booking_preflight` 不再对同一份已验证结果重复校验;`validate_booking_preflight` 集中检查预期字段,仍区分发送 OTP 前后以及发送按钮冷却状态。
+- 两个配置下拉框共用页面内的选择步骤,保留值和标签匹配、隐藏字段同步、未知必填项及页面/表单边界。控件数量要求真正的整数,不再接受 `True == 1` 一类伪整数。
+- 服务入口抽为 Italy 内部 `_enter_service`,供准备阶段复用。Book 不再调用公开 `query()`;没有新增网站调度器、返回类型或公共模块。
+- 合并服务页的认证路径、无号/未知提示分支及表单结构摘要处理;摘要只保留白名单元数据,不输出控件值。
+- OTP 继续调用现有云端邮件接口,仅合并重复的邮箱格式校验与异常包装。按 `agent-email-inbox` 的入站邮件约束保留账号、发送窗口、验证码格式和“正文只作数据”的处理;没有接入新邮件服务、LLM 或旧码回退。
+
+`_enter_service` 的成功仅表示进入表单,不是库存证据。遗留的公开 `services_probe` 仍可到达这条弱返回通路,必须在 W3 迁移其消费者;本次拆分尚未完成 T-03,不计为 Query 全面合格。
+
+### 测试迁移
+
+| 测试 | 改动与保留的行为 |
+| --- | --- |
+| `test/test_ita_preflight.py` | 新增 1 项计数类型测试、3 项实际页面脚本测试;以项目现有 Node VM 方式执行真实 preflight 脚本,覆盖两套服务/字段配置、重复读取只变更一次、错误边界、未知控件及冷却状态;本机未跳过 |
+| `test/test_ita_workflow.py` | 夹具区分内部进入服务和公开查询;保留自动 OTP、发送时间、跨账号和重复准备断言,新增 Book 不调用公开 Query 的断言 |
+| `test/test_ita_plugin.py` | 原生服务入口测试保留,Book 探测增加公开 Query 不得被调用的检查 |
+| `test/test_debug_ita_book_gate.py` | 将入口夹具改为内部进入服务;公开 Query 若被 Book 调用即失败,其他预提交/清理断言保留 |
+
+没有删除业务失败断言,没有复制旧运行时来满足测试。页面脚本测试只模拟 DOM 与外部边界,没有操作真实浏览器。
+
+### 当前行数、指纹与命令
+
+| 项目 | W0 | W2 首批 | 当前 | 相对 W0 |
+| --- | ---: | ---: | ---: | ---: |
+| `plugins/ita_plugin.py` | 6286 | 6117 | 5863 | -423 |
+| `utils/plugin_utils.py` | 489 | 497 | 497 | +8 |
+| 两个生产文件合计 | 6775 | 6614 | 6360 | -415 |
+
+本批 Italy 比首批再减少 254 行;公共文件没有进一步变化。仍远未达到约 1000 行,不将该减少量换算为完成百分比。
+
+HEAD 未变。当前 SHA-256:
+
+- Italy:`a15cd3fc5490148d6c7fb5272d163210d89de3bfc3bc2fe2a5e5a09573f5cb51`。
+- 公共工具:`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+命令均从仓库根目录执行,前缀为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`:
+
+| 命令后缀 | 当前结果 |
+| --- | --- |
+| `-m unittest test.test_ita_preflight test.test_ita_otp test.test_ita_workflow test.test_ita_protocol` | exit 0;142 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;529 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;313 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;外部边界模拟 |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip;仍是旧验收文档缺失 |
+| `git diff --check`(无上述 Python 前缀) | exit 0 |
+
+各测试组有重叠,不累加为独立测试总数。旧文档命令测试继续登记 W5,未恢复用户删除的文件或把失败标记为跳过。
+
+### 本批结论与后续
+
+H-06 本批涉及的表单校验、页面脚本及 OTP 场景离线通过;准备工作流和会话状态尚未整体收敛。H-08 仍未达标,H-11 仍有已知迁移失败。W2 保持“部分完成”。
+
+后续按方案处理剩余准备状态,再共用日历读取/解析及迁移弱探测入口;Book 最终提交和回执精简仍属 W4。公共清理接口的宿主部署前置条件保持不变。未发生真实网站、邮箱或预约请求;未提交、推送或部署。
+
+## 6. 后续实施:解析边界与单文件组织
+
+依据 T-01/T-02/T-05/T-07/T-10/T-12、H-05/H-06/H-08/H-10/H-11、UT-03/06/07/08/09/14/15、IT-04/05、RC-01/02/06/08。接续 W4 回执模型合并后的 4974 行工作区;该中间点 Italy 537 项离线测试通过,不代表本节尚未实施的改动已通过。
+
+只在现有单文件内合并重复的双层 JSON 解码、月份/日期解析和配置字段校验;保留错误分类、字段定位、严格库存/时间语义与 OTP 的模板、六位 ASCII、时间窗和账号约束。沿用项目已经使用的标准库和公共日期筛选/云端邮件接口,不新增校验框架。随后统一机械合并遗留的重复导入、删除指向已移除旧模块的独立说明字符串;保留正常排版与真实脚本,不靠分号或压缩字符串凑行数。
+
+修改文件为 `plugins/ita_plugin.py`;按行为需要补充 `test/test_ita_protocol.py`,其余现有测试应继续通过。解析职责合并和文件整理分别记录减行贡献,不能把整理导入声称为业务复杂度降低。执行协议/OTP定向测试、Italy 与调试全量、框架离线入口、单文件热加载以及旧工具消费者检查;不调用真实邮箱或网站。
+
+## 7. 历史组合工作区:4572 行
+
+### 实际修改及减行来源
+
+1. W4 回执模型合并:5058 → 4974,减少 84 行;模型、实际字段及测试迁移见 [W4 第 8 节](W4-selection-readback.md)。
+2. W2 解析边界:4974 → 4770,减少 204 行。双层 JSON 使用一段有界解码,仍严格要求“字符串 → 字符串 → 数组”;库存只在模型边界判定,不再调用另一个未使用其状态返回值的分类器。Query/Book 共用请求日期与月份上限校验;Book 不再构造整段月份列表或空库存过滤结果仅为验证参数。OTP 仍用现成云端读取与模板提取,重复 MIME 验证码只保留一个、冲突拒绝;配置、日期、时段保持字段定位与稳定错误分类。部分减少来自常规单行异常调用和简短说明,不能将 204 行全部理解为算法减少。
+3. 单文件整理:4770 → 4572,减少 198 行。79 个分散导入节点合并为文件顶部唯一导入,删去 10 段指向旧模块的独立说明字符串及遗留过量空行;不修改函数/类的 AST,不改变导入名称集合。使用 AST 做整理前后等价检查,再执行真实安装器与热更新测试。该 198 行是文件组织收益,单独记账。
+
+遵循入站邮件安全约束,仅把邮件正文作为数据,不执行 HTML 或指令;固定发件人/模板、当前账号邮箱与发送时间窗保留。没有增加邮件服务、读取通道回退、运行时辅助文件或公共 API。基础 JSON、时间和正则使用项目已经使用的标准库,不新建协议框架。
+
+新补 3 项业务回归:双层 JSON 内层错误与输入长度上限区分;时段各分量缺失/伪整数仍报告原字段位置;月份请求保留两种已观察日期格式并拒绝非法日期。原 OTP、库存、跨月、未知提交、账号隔离及热更新用例均继续执行。源码组织等价审查不替代这些测试。
+
+### 最终代码上的验证命令
+
+工作目录为仓库根;前缀统一为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_protocol test.test_ita_otp test.test_ita_calendar_query test.test_ita_calendar_book_flow test.test_ita_single_file` | exit 0;113 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;540 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;315 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip;仍依赖用户删除的 `docs/ita_query_book_acceptance.md` |
+| `git diff --check`(无 Python 前缀) | exit 0 |
+
+定向首命令曾误写不存在的 `test.test_ita_cloud_otp`;实际云端 OTP 测试位于 `test.test_ita_otp.CloudOtpTests`。纠正命令后执行了真实测试模块,没有跳过或替换为总是成功的桩。旧文档命令故障与此次误写分开记录;前者仍需 W5 迁移,不能称全仓全绿。各套件有交集,不累加为独立测试总数。
+
+### 行数、指纹及剩余预算
+
+HEAD 仍为 `a22596f1fcdffb946960724ef299f249e7860891`。相对上一批 5058 行,本批共减 486 行;相对 W0 的 6286 行减 1714 行。公共工具仍 497 行、比 W0 净增 8 行;两生产文件合计 5069 行,比 W0 的 6775 行净减 1706 行。
+
+工作区相对 HEAD 的分类统计:两个生产文件新增 682 / 删除 2388 行,净减 1706;调试工具新增 169 / 删除 24,净增 145;已跟踪测试新增 600 / 删除 382,加上两份新增测试 291 行,测试净增 509。文档、用户配置及用户删除的旧文档不混入生产减行数字;这不是“全仓总行数也减少 1714 行”。
+
+| 分区 | 当前行数 | 方案预算 | 剩余工作 |
+| --- | ---: | ---: | --- |
+| 配置/协议/模型 | 464 | 140 | 配置模型和必要的解析边界仍需收敛 |
+| Query/Book 日历 | 1193 | 180 | 已共用捕获、日期与解析;页面操作、等待和读回仍重 |
+| 最终提交/预约记录/回执 | 951 | 200 | 真实字段已合并;提交与读取调用层仍需减少 |
+| 表单/OTP/验证/工作流 | 839 | 240 | 继续合并准备状态与必要等待,不减少 OTP/账号保证 |
+| 插件入口/登录/会话/清理 | 1076 | 220 | 继续复用公共生命周期,减少状态重复表示 |
+| 文件组织 | 49 | 20 | 导入已统一;保持正常排版,不靠压行完成 |
+| 合计 | 4572 | 1000 | 仍差 3572 行,H-08 未通过 |
+
+SHA-256:Italy `e70a4d8aa478c32a88b7577ac78a687b28ded61f74b0cc0600d686e06389289b`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+### 结论与下一步
+
+本批 W2/W4 子项及其实际消费者离线回归通过。H-05/H-06/H-07/H-10 有本批覆盖场景的证据,不代表整组假设、工作包或真实业务通过。H-08、旧工具消费者迁移、H-04 现场 HTTP 等价与新版本真实预约仍未完成;不自行放宽 1000 行预算。
+
+下一步继续准备/会话状态与日历操作层的结构精简,按同一分区表重估;W5 将旧文档内联命令迁往现有工具,保留池子分配、当前账号邮箱、冷却与不泄露错误正文的业务断言,不能只删除失败测试或恢复用户已删除的文件。本批没有修改用户配置,没有访问真实网站/邮箱/云订单,也未执行预约、Git 提交/推送或部署。
+
+## 8. 后续实施:合并日历准备上下文
+
+开始基线为第 7 节的 4572 行及其指纹。引用 T-02/T-03/T-04/T-07/T-08/T-11/T-12,H-03/H-06/H-10/H-11,UT-04/05/06/09/10/12/14、IT-01/03/04/05,RC-03/04/06/07/08。当前授权仅本地实施、离线测试及记录;不执行真实网站/邮件/预约或发布。
+
+核对 VFS/TLS 的实例会话与公共 `BaseFlow`、初始化及清理:继续复用这些能力,账号池和重试仍由宿主承担。公共模块没有可直接复用的 Italy 日历准备凭据;这里不新建公共框架,而在单文件内以一份小型不可变上下文替换 Query 的分散字段及 Book 的七项元组。上下文同时保存角色、账号、实例/页面/代次、领区配置、运行时服务和持久化目录;Query/Book 共用创建和当前身份核对,不能跨角色、账号或实例使用。
+
+`CalendarQueryCheckpoint` 仍是原来的五字段恢复参考,不是登录凭据;恢复前核对账号/目录/配置,恢复后重新观察页面及服务并建立新上下文。它不再重复保存当前页面/代次。准备失败的单次 OTP 标记、最终提交状态和未知暂停不因上下文合并而删除。有效会话重复 Query 不重发 OTP;Book 仍读取申请人库存,原生请求和回执核验不变。
+
+修改 `plugins/ita_plugin.py` 及实际依赖上述私有字段/钩子的现有 `tools/`、`test/`;不新增运行时文件、公共 API 或配置。预计这一结构合并减少约 100–180 行,实际以完成后统计为准,不据此宣称 1000 行预算成立。私有字段断言迁往统一上下文及真实创建钩子,账号/页面/代次/服务/热更新、一次 OTP/提交等业务断言保留,并补普通 Query 未导出恢复参考时的身份变化测试。先执行相关定向回归,再执行第 7 节的完整命令并记录全部失败;不跳过旧命令问题。
+
+同一工作包继续将 `_query_once` 与只被它调用的 `_query_calendar` 合并:公开 Query 保留宿主异常/健康状态边界,内部一次查询直接验证当前上下文、扫描并构造公共结果。共用月份扫描器、首个正向月份和空结果语义不变;不改 HTTP 路径,不在测试内另写扫描算法。
+
+## 9. 历史组合工作区:4483 行
+
+### 实际修改与边界
+
+按第 8 节范围完成两项结构合并:Query 的分散准备字段与 Book 的七项元组合为 `_PreparedCalendar`,由同一组创建、核对和清除方法处理;`_query_calendar` 的单层转发并入 `_query_once`。公开接口、公共返回类型、现有月份扫描及原生网站操作保持不变。本批没有新增公共 API、运行时模块或配置。
+
+当前上下文绑定实例、页面、标签页、会话代次、账号、角色、路由、运行时服务及持久化目录。创建时先捕获页面身份,再读取服务,最后复核,不能把旧页面的观测记到已替换的新页面上。普通 Query 在读取前后都核对身份,不要求先导出恢复参考才生效。恢复参考仍为原五字段,恢复后重读当前页面并重新绑定;Book 的上下文不能被 Query 恢复擦掉。清除日历上下文不会清除单次 OTP 尝试或最终提交结果状态。
+
+继续复用公共初始化、`BaseFlow`、清理、日期筛选及云端邮件接口;Italy 的页面/服务绑定留在单文件内。邮件仍只用于提取绑定当前账号和发送时间窗的验证码,不读取真实邮箱,不新增邮件服务或旧码回退。
+
+### 消费者与业务测试迁移
+
+| 消费者/断言 | 本批处理 |
+| --- | --- |
+| `debug_ita_calendar_gate.py` | 先用现有等待方法确认 Calendar 运行时服务就绪,再登记 Query 上下文;后续仍调用真实公开 Query |
+| `debug_ita_book_gate.py` | 使用统一登记钩子和 Book 角色核对;不复用 Query 凭据或跳过申请人日历准备 |
+| `FinalReceiptReadPort` | 七项元组索引改为同一上下文的命名字段;保持对象身份、当前会话及只读回查检查 |
+| workflow、Book flow、soak、恢复和热更新测试 | 从旧私有字段/钩子迁往真实上下文;账号、角色、服务、页面、恢复、一次 OTP/提交和自身版本绑定断言保留 |
+| 普通 Query 新增业务覆盖 | 未导出 checkpoint 时账号/页面/代次/服务/标签页/路由/目录变化仍拒绝;凭据不能复制到另一实例;准备读取中更换页面拒绝;月份读取中换账号不发布库存 |
+
+新增 4 项测试位于 `test/test_ita_query_recovery.py`。中间回归暴露了旧夹具未设登录健康状态、变更持久化目录后未重新登记、未模拟 Calendar 就绪脚本等问题;按真实生命周期补齐夹具,没有删除业务断言。另纠正一次过严的模式检查:已验证的诊断 Book 仍可使用其申请人上下文,自动 Book 与生产 Query 的原角色/配置约束不变。
+
+### 最终代码上的验证命令
+
+从仓库根执行,Python 命令统一前缀为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。全部网站、邮箱和云端边界为离线模拟;各套件有交集,不相加为独立测试总数。
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_query_recovery test.test_ita_calendar_book_flow test.test_ita_final_read_port test.test_ita_single_file` | exit 0;111 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;544 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;315 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip;仍依赖已删除的旧验收文档命令 |
+| `git diff --check`(无 Python 前缀) | exit 0 |
+
+旧文档命令故障仍按 W5 迁移,不恢复用户删除的文件,不将失败标为通过。`safe_redis_cli.py` 的既有 `setex` 弃用警告未在本批扩展处理。
+
+### 行数、指纹与剩余预算
+
+本批 **4572 → 4483,净减 89 行**,低于开始时估计的 100–180 行。保留五字段恢复合同、诊断入口兼容,并补足普通查询与登记时的身份核对,使实际收益小于估算;不靠删断言或压排版补足数字。相对 W0,Italy 减少 1803 行;公共工具仍为 497 行、净增 8 行。两生产文件合计 4980 行,比 W0 的 6775 行净减 1795 行。
+
+相对 HEAD 的分类差异:两个生产文件新增 808 / 删除 2603 行;调试工具新增 177 / 删除 28 行,净增 149;已跟踪测试新增 774 / 删除 467 行,加上两份新增测试 291 行,测试净增 598。文档、用户配置及旧文档删除不计入生产减行。
+
+| 分区 | 当前行数 | 方案预算 | 剩余工作 |
+| --- | ---: | ---: | --- |
+| 配置/协议/模型 | 464 | 140 | 配置与解析边界继续收敛 |
+| Query/Book 日历 | 1193 | 180 | 页面操作、等待和选择读回仍重 |
+| 最终提交/预约记录/回执 | 951 | 200 | 提交与只读核验调用层仍需减少 |
+| 表单/OTP/验证/工作流 | 836 | 240 | 准备步骤和等待仍需收敛,不降低 OTP 约束 |
+| 插件入口/登录/会话/清理 | 990 | 220 | 当前准备状态已统一,剩余入口及会话代码继续审查 |
+| 文件组织 | 49 | 20 | 保持正常排版 |
+| 合计 | 4483 | 1000 | 仍差 3483 行,H-08 未通过 |
+
+HEAD:`a22596f1fcdffb946960724ef299f249e7860891`。SHA-256:Italy `d9d7041c184551c54173624f8681a73932408237729e44f2e705f8e1dce5233e`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+### 结论与下一步
+
+本批统一上下文和 Query 转发的离线回归通过;H-03/H-06/H-10/H-11 仅获得所列场景证据,不代表工作包整体完成。约 1000 行、新版本真实预约、H-04 的 HTTP 等价及旧文档命令迁移仍未完成。下一步重点为日历页面操作/选择读回、表单等待以及提交读取层;继续按分区预算检验结构减法,不把仅减少 89 行视为总目标可行性已经证明。
+
+本批未修改用户配置、恢复旧文档、访问真实网站/邮箱/云订单、提交预约或执行 Git 提交/推送/部署。
+
+## 10. 表单准备合同收拢(实施范围)
+
+开始基线为 [W3 第 8 节](W3-query-entry.md) 的 4339 行,不是本文件第 9 节的历史 4483 行。当前工作区已有改动继续保留。
+
+- 依据:T-01/T-02/T-05/T-07/T-08/T-10/T-11/T-12;H-06/H-08/H-10/H-11;UT-05/UT-06/UT-14/UT-15、IT-04/IT-05;RC-01/02/04/06/07/08/10。本批不宣告总准出。
+- 现状:生产表单脚本先拼接边界校验,再拼接另一份生成器;日历调试入口直接使用后者。两条入口对同一表单的操作边界不同,表单查找和配置传递也重复。AVANTI 的 302 与跟随重定向 200 分支重复校验相同目标。
+- 改法:合并为一个包含边界校验的表单脚本生成器,生产与原调试入口共同调用;以统一控件配置及读回逻辑替代重复字段接线。AVANTI 保留两种已验证响应表示,只合并相同的目标检查。移除机械合并遗留的内部别名,不增加 Italy 工具层。
+- 复用判断:继续使用现有 `VSCloudApi.fetch_mail_content`、原生浏览器事件和已有验证辅助模块。`utils/network_interceptor.py` 使用 `Fetch.enable` 暂停/修改请求,不是被动观察器,不能为了名义复用替代当前请求计数;本批不改最终请求审计。
+- 不变:配置化服务与控件、原生隐藏字段同步、未知必填项拒绝、单人/旅游约束、两阶段 OTP 按钮状态、账号与发送时间绑定、单次发送及失败后不自动重发、日志脱敏、原生日历准备、单次最终提交和回执要求。
+- 验证:真实 Node 执行生成脚本,覆盖正常与异地配置、错误页面/表单、重复控件、前后两阶段、幂等和隐藏字段同步;调用原生产准备/调试入口,检查业务请求次数不变;重跑 Italy、调试、框架离线及配置/加账号四组命令,单列既有旧文档命令故障。
+- 预计仅减少 30–70 行,是删除重复接线的局部工作,不是已证明能够达到约 1000 行。不得以排版压缩、把 Italy 私有逻辑搬进公共模块或删业务断言补足数字。
+
+本节为开始前的范围记录,尚未填为完成;不访问真实网站、邮箱或云端,也不提交、推送或部署。
+
+## 11. 最新组合结果:4289 行
+
+### 实际改动与消费者
+
+按第 10 节范围,生产文件只保留 `guarded_preflight_script()` 一个生成器:先核对页面、表单和原生 action,再选择配置项、触发原有 change/PrivacyCheck 事件并读回。删除拼接前缀与裸生成器两层结构,复用标准库 `dataclasses.asdict` 传递现有控件配置;没有新增配置结构或公共模块。`tools/debug_ita_calendar_gate.py` 改用同一生成器,不再绕开表单边界。生产与 Book 调试入口沿用这个生成器。
+
+AVANTI 的直接 302 与浏览器跟随重定向 200 仍分别取各自的真实目标,合并相同的同源 Calendar 检查,返回模式字符串不变。删除机械搬迁的内部函数别名;没有切换 HTTP 通道,也没有修改 OTP 发送、读取、窗口、等待、重发或最终提交策略。表单事件后再次读路径,不能把事件触发的离页硬编码为就绪。
+
+邮件相关检查按本轮已读取的 `agent-email-inbox` 约束复核:复用原云端读取接口,保留当前账号、发送窗口、固定发件人过滤、ASCII 验证码和脱敏日志;不把返回正文当指令,不引入 LLM、邮件服务或真实邮箱操作。后端发件人过滤不是邮件认证证明,本批没有扩大这个保证。
+
+| 业务断言 | 位置与处置 | 当前证据 |
+| --- | --- | --- |
+| 两套服务/控件配置、原生隐藏字段同步、前后 OTP 阶段及幂等 | 原 `FormJavaScriptTests` 和 Book gate 实际脚本测试保留 | Node 执行新生成器,不使用模拟就绪结果替代脚本 |
+| 原日历调试入口也必须先检查来源/action/上传项 | `FormJavaScriptTests.test_existing_calendar_debug_entry_uses_the_same_guarded_form` 新增 | 两套配置;错误场景无表单变更 |
+| 重复 OTP 发送、AVANTI、验证 token 控件不能通过 | `test_duplicate_business_controls_cannot_pass_either_otp_stage` 新增 | 实际计数为 2,前后两个阶段均拒绝 |
+| 原生 change 导致离开表单时不能继续 OTP | `test_native_change_navigation_is_not_reported_as_a_ready_form` 新增 | 当前读回 pathMatches=false,后续读回在边界直接返回 |
+| 302/200 三方一致、错域名/路径/方法/状态拒绝 | 原日历 gate 测试保留 | 公共目标校验分支与两个返回模式均通过 |
+| 云端 OTP 的账号/窗口、单次读取、前导零、异常脱敏 | 原 OTP、生产 workflow 测试保留 | 定向与完整套件执行,未删业务断言 |
+
+新增测试首跑有 1 failure:重复 token 场景先被既有 `turnstileTokenPresent` 检查拒绝,而用例误要求必须先报 `turnstileCount`。修正测试为同时核对真实计数为 2 和两阶段均拒绝,不规定内部检查次序;没有放松生产校验。修正后定向及完整回归通过。
+
+### 精确命令与结果
+
+从仓库根执行;Python 统一前缀 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。全部为离线边界,测试套件有交集,不相加成独立总数。
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_preflight test.test_ita_workflow test.test_ita_otp test.test_debug_ita_calendar_gate test.test_debug_ita_book_gate` | 最终 exit 0;231 项,0 skip;首次 1 failure 已按上文修正 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;550 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;323 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip;原因仍为已删除的旧文档命令 |
+| `git diff --check`(无 Python 前缀) | exit 0 |
+
+既有旧文档命令失败不算通过,后续 W5 迁移到现有工具并保留账号池分配、不同账号邮箱、失败不回退和日志脱敏断言;不恢复用户删除的文档。既有 Redis `setex` 弃用警告未在本批扩展处理。
+
+### 行数与剩余预算
+
+本批 **4339 → 4289,净减 50 行**,在开始时 30–70 行估计内。收益来自脚本拼接层和配置接线合并、目标检查合并、内部别名删除以及伴随的正常排版整理,不把 50 行全称为算法复杂度下降。Italy 相对 W0 减少 1997 行;公共工具仍为 497 行、相对 W0 净增 8 行,两生产文件合计 4786 行、净减 1989 行。
+
+相对 HEAD 的分类差异:两生产文件新增 890 / 删除 2879 行;调试工具新增 251 / 删除 48 行、净增 203;已跟踪测试新增 1124 / 删除 552 行,加上两份新增测试 291 行,测试净增 863。文档、用户配置与旧文档删除不计入生产减行;本批没有新增公共生产代码或 Italy 私有运行时。
+
+| 分区 | 当前行数 | 方案预算 | 剩余工作 |
+| --- | ---: | ---: | --- |
+| 配置/协议/模型 | 464 | 140 | 配置解析和模型仍需收敛 |
+| Query/Book 日历 | 1141 | 180 | 页面操作、捕获与选择读回仍重 |
+| 最终提交/预约记录/回执 | 951 | 200 | 提交和读取调用层仍重 |
+| 表单/OTP/验证/工作流 | 786 | 240 | 本批消除两条脚本入口;准备与等待仍需精简 |
+| 插件入口/登录/会话/清理 | 898 | 220 | 入口与会话代码仍需收敛 |
+| 文件组织 | 49 | 20 | 保持正常排版,不靠挤行数完成 |
+| 合计 | 4289 | 1000 | 仍差 3289 行,H-08 未通过 |
+
+HEAD:`a22596f1fcdffb946960724ef299f249e7860891`。SHA-256:Italy `5b40e677a2966081e5bdb437935039d19d75414c6a40cdde3e19fd52900b9d59`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+本批表单收拢的离线验证完成,不代表 W2、W5 或总目标完成。下一步优先消除仍然失效的旧文档命令消费者,并继续较大的准备/提交读取层收敛;不重复计入本次已删除的脚本拼接层。周期预算不因减去 50 行按比例缩短;约 1000 行仍待结构性精简证明。
+
+仅进行本地修改与离线验证;用户配置及旧文档删除保持原样,没有真实站点、邮箱、账号池、云订单或预约操作,未 Git 提交、推送或部署。未使用用户禁止的 skill,技术决策和准出条目没有放宽。
+
+## 12. 表单等待诊断归位与准备流程收敛(实施前)
+
+开始基线为 [执行记录入口](../06-execution-records.md) 的 4031 行工作区。依据 T-01/T-02/T-07/T-08/T-10/T-12,H-01/H-06/H-08/H-11,UT-05/UT-06/UT-14/UT-15、IT-04/IT-05,RC-01/02/04/06/07/08/10。本批只允许本地实现、离线测试和文档记录;不访问真实站点、邮箱、账号池或订单,不提交预约、Git 提交/推送或部署。
+
+### 现状与判断
+
+- 生产 `safe_booking_preflight_diagnostic`/`_print_booking_preflight_diagnostic` 与现有 `tools/debug_ita_calendar_gate.py` 的安全诊断重复;前者不参与表单准入,只生成验收 JSON。按 T-10,完整快照应由工具拥有。
+- 生产表单脚本返回 `turnstileApiPresent`、`turnstileScriptPresent`、`documentVisible` 三个仅供诊断展示的字段;准入、OTP、AVANTI 和 Turnstile 有界交互都不读取它们。
+- `wait_for_booking_preflight` 同时承担业务等待、默认报告器、周期性报告节流及恢复回调。业务只需要当前会话检查、结构校验、就绪判定、明确超时和可选有界交互;报告器应由调试调用方显式传入。
+- `ItalyTurnstileRecovery` 复用 VFS 的 `CloudflareBypasser.click_verification_button` 是正确的公共复用,必须保留;但其生产 JSON 是调试证据,不是成功依据。任何点击结果都不能替代下一次页面快照。
+
+### 本批改法与不变边界
+
+- 把完整预检诊断的所有权收回现有日历调试工具;生产等待器仅在调用方显式传入诊断回调时报告。调试 gate 继续得到 `ready/waiting/rejected/timeout/read_failed` 证据。
+- 删除生产页面脚本中三项纯诊断字段;保留来源、表单 action/method/enctype、无上传项、配置标签和值、隐藏字段、单人、Privacy、未知必填项、OTP/AVANTI/Turnstile 唯一性及两阶段状态的全部校验。
+- 精简等待循环和 Turnstile 包装层;仍只在已验证表单、唯一控件、token 明确缺失时交互,仍共用两阶段总计三次预算、5 秒首次等待和 10 秒间隔,异常不泄露浏览器数据、不刷新、不调用标题式 `bypass()`。
+- 保留自动 OTP、当前账号邮箱、发送时间窗、单次发送/单次读取、DOM 写入读回、AVANTI 原生 POST 监听与 Calendar 目标校验。不得借本批切换 HTTP、放宽验证、增加自动重发或最终提交。
+- 不新增 Italy 私有运行时文件或公共 API。预计生产净减 70–130 行;若明显低于范围,按实际原因记录,不靠压行、删断言或将网站逻辑伪装成公共模块补数字。
+
+### 消费者和测试迁移
+
+- `test/test_ita_preflight.py` 继续验证生产等待、校验、实际 JavaScript、Turnstile 有界交互和不泄密;只把“默认生产必须打印整份诊断”的旧结构断言迁到现有调试 gate。
+- `test/test_debug_ita_calendar_gate.py` 继续证明显式诊断回调的安全白名单、阶段、结果和类型形状;Book gate/本地串联继续调用同一生产表单与等待器。
+- 定向先跑 preflight/workflow/OTP/debug gate;随后运行完整 Italy、完整 debug、离线框架入口、配置/账号四组回归,并执行 AST/热更新、`py_compile`、文档链接和 `git diff --check`。业务断言不得因类名或报告格式变化被删除。
+
+本节只记录实施范围,尚未宣告完成。完成后追加实际行数、源码指纹、精确命令、首次失败及迁移去向;所有未获得现场证据的 RC 保持未通过。
+
+## 13. 表单等待诊断归位结果:3981 行
+
+按第 12 节完成本地实施。生产删除重复的安全诊断构造器和默认报告器;`wait_for_booking_preflight` 只在调试调用方显式传入回调时报告状态,仍在每次 DOM 读取前后核对当前会话、严格校验表单快照,并且只有后续真实快照可以放行。超时异常继续区分 token 缺失、AVANTI 禁用及两者同时等待。
+
+表单脚本删除三个只用于报告展示的字段,所有准入字段保持不变。Turnstile 仍使用 VFS 的 `CloudflareBypasser.click_verification_button(is_dfs=False)`,两阶段合计三次、首次 5 秒、间隔 10 秒;helper 的返回值和异常都不能成为成功证据,仍不刷新、不调用 `bypass()`。生产删除每次交互的 JSON,不影响现有调试 gate 的安全白名单报告。
+
+首次定向回归有 3 个 failure:`test_ita_workflow` 中两个恢复测试和一个超时测试仍要求生产打印 `state/outcome` JSON。它们的业务断言原本已经覆盖真实后续读回、一次 OTP、一次 AVANTI 和超时零请求,因此迁为这些行为断言;新增 debug gate 超时用例继续证明 `timeout` 诊断与私有值隔离。没有修改生产逻辑来迎合旧输出,也没有删除 OTP、恢复或超时业务场景。
+
+### 行数、指纹与验证
+
+- Italy **4031 → 3981,净减 50 行**;低于事前 70–130 行估计。原因是 VFS helper、有界恢复、两阶段表单校验和一次请求核验均为真实业务边界,未为凑数删除。相对 W0 的 6286 行累计减少 2305 行,距约 1000 行仍差 2981 行。
+- 公共生产模块零新增,`utils/plugin_utils.py` 仍为 497 行;两个生产文件相对 W0 合计净减 2297 行。没有新增 Italy 私有运行时文件,生产对 `tools.*`/`test.*` 的导入为 0。
+- SHA-256:Italy `9a5d03724af1769c2127d0d154627f80c082a461b894a80fea3aabb36ddb204c`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`;日历调试工具 `57e15a24ebc20bdc3749ff127453b9cef91f854c98e9a1e1e30860872e5c3271`。
+
+从仓库根执行,Python 命令统一前缀为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`;全部外部边界为模拟,测试组有交集,不相加为独立总数。
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_preflight test.test_ita_workflow test.test_ita_otp test.test_debug_ita_calendar_gate test.test_debug_ita_book_gate -q` | 首次 220 项有 3 个旧输出断言失败;迁移后 exit 0,221 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_ita*.py' -q` | exit 0;540 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py' -q` | exit 0;324 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;74 项,0 skip;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account -q` | exit 0;27 项,0 skip |
+| `-m py_compile plugins/ita_plugin.py test/test_ita_preflight.py test/test_ita_workflow.py test/test_debug_ita_calendar_gate.py` | exit 0 |
+| AST 边界和 `git diff --check` | exit 0;生产工具/测试导入 0,生产重复诊断定义 0 |
+
+H-06/H-11 在本批涉及的离线场景通过;H-08、现场 H-04、真实预约 RC-05/09 及总体 RC-01/10 仍未完成。仅修改本地代码、测试和文档;没有真实网站、邮箱、账号池、订单或预约操作,没有 Git 提交、推送或部署。用户配置与旧文档删除保持原样。下一包进入日历页面捕获/选择层,开始前另写具体范围和风险,不把本批 50 行重复计入。
+
+## 14. Query checkpoint 诊断归位与宿主生命周期复用(实施前)
+
+开始基线为 3926 行,Italy SHA-256 `e482418ba34f43e27f1ef01c8636b8feca15915f76dbdcfa262e55745509fb83`,`tools/debug_ita_soak.py` 为 1156 行、SHA-256 `bda22a979572dc8158c61fe48d800d1efca74fae879c2c4bc06dfd2b82207691`。依据 T-01/T-02/T-08/T-10/T-11/T-12,H-01/H-08/H-10/H-11,UT-01/04/09/14/15、IT-01/04/05/06,RC-01/02/03/07/08/10。本批只做本地代码、测试和文档;不访问真实站点、邮箱、账号池、订单,不执行预约、Git 提交、推送或部署。
+
+### 生产消费者证据与设计判断
+
+- `CalendarQueryCheckpoint`、`capture_calendar_query_checkpoint()`、`restore_calendar_query()` 在生产文件外只有 `tools/debug_ita_soak.py` 和对应测试调用;Sentinel、Booker、插件工厂、主进程及其他生产插件均无消费者。
+- Sentinel 的真实生命周期是 `health_check()` 返回失败后移除并清理旧实例,再由 creator 获取账号、创建新插件、调用 `create_session()`;Booker 使用相同的健康检查、清理和新实例路径。生产 Query 自身从不跨实例传递 checkpoint。
+- checkpoint 的“同 profile 登录后直接导航 Calendar、不再次 OTP”是 soak 的受控恢复实验,不是 `IVSPlg` 合同。把这套实验 API留在 `ItaPlugin`,会让调试需求支配可热更新生产文件,违反 T-10,也与 VFS/TLS/BLS 的薄公开入口不同。
+- 生产仍必须保留 `_PreparedCalendar` 的当前实例、页面、tab、账号、代次、路由、运行时服务、角色及 profile 绑定;普通 Query 发布库存前后的身份复核、失效后健康标记、宿主退役/重建和持久化 profile 排他锁都不是本批删除对象。
+
+### 本批改法与不变边界
+
+1. 从生产插件删除 checkpoint 数据类、导出/恢复方法及只服务该实验的 URL 校验/owner 校验;不增加新的 Italy 运行时模块或公共宿主 API。
+2. soak 工具在 `CalendarSoakContext` 内保存最小的只读比较值,并用现有生产边界 `same_origin_path`、`guard_calendar`、`read_calendar_service`、`_record_calendar_prepared_route` 完成同一受控实验。该工具状态不进入 Sentinel 信号、Booker 订单或插件公开接口。
+3. 账号、显式持久 profile、当前配置路由、Query 模式、禁用最终提交、同源 Calendar URL、唯一允许的 `selectedService` 参数及运行时服务必须全部一致;任一不一致在导航前或查询前拒绝。恢复后仍执行真实新月份读取,不能复用旧 scan、日期或 slot。
+4. 将 checkpoint 专属断言迁到 soak 测试;`test_ita_query_recovery` 继续覆盖生产的认证/限流/权限/断线分类、当前会话身份漂移、宿主退役和清理失败。测试场景不因内部 API 删除而消失。
+5. 删除 `create_session(debug=True)` 中重复的浏览器指纹展示脚本;公共 `init_chromium_options` 已生成并记录必要的指纹种子/平台,生产调试不再维护第二份 WebGL/UA 采集器。此项不改变浏览器参数或页面初始化。
+
+预计 Italy 生产文件净减 130–170 行;诊断工具允许增加少量局部代码,但不能复制整套生产会话状态机。验证先跑 Query recovery、Calendar soak、登录/生命周期/单文件热更新,再跑完整 Italy、完整 debug、离线 Query+Book 和配置回归;同时检查生产对 `tools.*`/`test.*` 零导入、checkpoint 符号零残留及 `git diff --check`。本节只记录实施范围,完成结果、首次失败、精确行数和指纹随后追加。
+
+## 15. Query checkpoint 诊断归位结果:3795 行
+
+### 实际实现与复用
+
+- 生产删除 `CalendarQueryCheckpoint`、owner/URL 校验、checkpoint 捕获和跨实例恢复方法;这些符号在 Sentinel、Booker、工厂及主进程中原本没有消费者。普通 Query 仍通过 `_PreparedCalendar` 在读取前后核对当前插件实例、页面、tab、账号、会话代次、路由、运行时服务、角色和 profile,认证/限流/权限/断线仍标坏实例并交给宿主的 health → cleanup → creator 生命周期。
+- `tools/debug_ita_soak.py` 保留受控“同 profile 重新登录后只读回到 Calendar”实验。最小 checkpoint 仅在工具内存中存在,`repr` 不展开账号;工具在恢复前继续检查当前账号、显式 profile、当前配置 route、Query 模式、关闭最终提交、同源 Calendar URL 和唯一允许的 `selectedService` 参数,恢复后再核对运行时服务并登记新的当前实例证明。旧 scan、日期和 slot 均不进入 checkpoint。
+- 生产 `create_session(debug=True)` 删除第二份 UA/WebGL/时区采集脚本;仍直接复用 `init_chromium_options` 生成浏览器参数和记录指纹种子/平台,浏览器、代理、目录、窗口、登录及 HumanMouse/HumanKeyboard 初始化未变。
+- 没有新增公共 API、Italy 私有运行时文件或 HTTP 通道;持久化 profile 排他锁和严格清理保持原实现。诊断工具依赖现有生产边界,没有复制登录、OTP、扫描或提交状态机。
+
+### 测试迁移与首次失败
+
+原 7 个 checkpoint 私有 API 测试迁到 3 个 soak 语义测试:一个检查最小字段、无凭据/库存;一个参数化检查账号/profile/route 变化在导航前拒绝;一个参数化检查外域和未知 query 参数在导航前拒绝。已有 Calendar soak 继续覆盖新实例真实 fresh scan、form 返回 `ITA-OTP-01`、错运行时服务、受控恢复零 OTP/AVANTI/final,以及断线/过期/清理失败。生产 recovery 套件继续覆盖当前会话身份漂移、查询发布前换账号、跨实例复制证明、认证/限流/权限/断线分类和 Sentinel 真实退役路径。
+
+第一次 48 项定向运行出现 26 errors:迁到工具后直接使用了调用方 route 对象,而旧生产 API 会按当前账号重新解析 route;账号派生邮箱使两个对象不一定完全相等。修正为先调用当前插件 `_resolve_route()`,再绑定准备上下文和 checkpoint。相同 48 项通过后,新增迁移场景组成 51 项也通过。该修复恢复旧语义,没有放宽 route、邮箱或会话检查。
+
+完整 Italy 数量由 539 变为 535:删除的是 7 个生产私有 checkpoint 表示测试,新增 3 个工具所有权语义测试,净减 4;上述所有业务拒绝与恢复场景仍有覆盖,不是通过删掉失败行为得到绿灯。
+
+### 精确验证与结果
+
+从仓库根执行,Python 命令统一前缀 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`;全部外部边界为模拟,0 skip:
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_query_recovery test.test_ita_calendar_soak -q` | 首次 48 项、26 errors;修复 route 重解析后 48 项通过;迁移测试完成后 51 项通过 |
+| `-m unittest test.test_ita_login_flow test.test_ita_shared_lifecycle test.test_ita_plugin test.test_ita_single_file test.test_debug_ita_soak test.test_ita_query_recovery test.test_ita_calendar_soak -q` | exit 0;133 项 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py' -q` | exit 0;535 项 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py' -q` | exit 0;324 项 |
+| `tools/debug_ita_query_book.py --offline` | exit 0;74 项;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account -q` | exit 0;27 项 |
+| `-m py_compile plugins/ita_plugin.py tools/debug_ita_soak.py test/test_ita_query_recovery.py test/test_ita_calendar_soak.py` | exit 0 |
+| AST、checkpoint 搜索及 `git diff --check` | exit 0;生产工具/测试导入 0,五个旧 checkpoint 符号各 0 |
+
+### 行数、指纹与结论
+
+Italy **3926 → 3795,净减 131 行**,在事前 130–170 行估计下沿;`ItaPlugin` 类本体 745 → 629 行。相对 W0 的 6286 行累计减少 2491 行,距约 1000 行仍差 2795 行。公共工具仍为 497 行;Italy+公共工具当前 4292 行,相对 W0 两生产文件 6775 行净减 2483 行。
+
+诊断工具 1156 → 1230,增加 74 行;两个相关测试文件 820 → 789,净减 31 行。该变化把实验所有权从可热更新生产 API 移到调试工具,未把 Italy 业务逻辑搬进另一个运行时文件。SHA-256:Italy `5e67985329620f016708634144682700611ae7824016d0d7f932bd35ebb7e83e`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`;soak 工具 `d0b67935606e97626d1b74ff875574cbb0548862c4f4fc26af9b7251cd630ef7`。
+
+H-01/H-10/H-11 在本批涉及的离线场景通过;H-08、现场 H-04、真实预约 RC-05/09 及总体 RC-01/10 仍未完成。本批没有真实站点、邮箱、账号池、订单或预约操作,没有 Git 提交、推送或部署;用户配置与旧文档删除保持原样。下一包继续审计月份捕获/扫描或最终提交/回执的大块调用层,不能把本次 131 行重复计入。
+
+## 16. R4 表单、OTP 与 Turnstile 准备链(实施前,2823 行)
+
+开始基线:`plugins/ita_plugin.py` 2823 行,SHA-256
+`91acff67527b6a4d3c8775ada88b8855f64191f90a11f03142a7544c1eb276ca`。
+引用 T-05/T-07/T-08/T-10/T-12,H-06/H-08/H-11,UT-05/06/14/15、IT-04/05,
+RC-01/02/04/06/07/08/10。本批只做本地代码、测试、工具消费者与文档;不访问真实网站、
+邮箱、账号池或订单,不发送 OTP、AVANTI 或最终预约,不执行 Git 提交、推送或部署,并保护
+用户配置、旧文档删除和其他工作区改动。
+
+### 16.1 调用图与复用判断
+
+1. 生产准备链当前 566 行,把一张表单拆成 `BookingPreflightStage`、约二十字段快照、
+   `validate_booking_preflight`、通用等待器、41 行恢复对象和 110 行编排。字段中的多数事实只在
+   JavaScript 内组合一次,Python 又逐字段重建同一判断;这与已在日期/时段采用的聚合控件合同
+   不一致。
+2. VFS 已直接复用 `CloudflareBypasser.click_verification_button(is_dfs=False)`,循环读取唯一
+   `cf-turnstile-response` token;Italy 的公共复用方向正确,但阶段枚举、调试状态和恢复对象层
+   不必留在生产。helper 返回值仍不能替代后续页面快照。
+3. `validate_cloud_otp_logging` 只为阻止共享 SDK DEBUG 输出敏感正文。CR-001 已明确允许当前
+   Italy 记录 OTP、Token 或敏感表单,因此这层准出已失效;删除它不代表主动新增日志,也不允许
+   把秘密提交到 Git。
+4. 必须保留:当前账号/标签页/会话代次、配置化表单选项及隐藏字段、单人、Privacy、未知必填项、
+   唯一 OTP/AVANTI/Turnstile 控件、一次 OTP 发送/读取、邮箱与发送时间窗、DOM 写入读回、原生
+   AVANTI 请求及 Calendar 目标、同会话失败不自动重发。
+
+### 16.2 本批改法
+
+- 表单脚本把底层检查聚合为少量精确布尔业务事实;错误来源/action/method/enctype、上传项、
+  配置标签和值、隐藏字段、单人、Privacy、未知 required 和重复控件仍逐项计算。Python 只校验
+  精确字段/普通布尔及 before/after OTP 合同,不复制约二十字段期望字典。
+- 用普通 `after_otp` 布尔代替只含两个值的阶段枚举;等待器继续有界、前后核对当前会话,并只在
+  聚合表单已安全且 token 明确缺失时调用 VFS helper。两阶段共享三次交互预算,不刷新、不调用
+  标题式 `bypass()`。
+- 删除 CR-001 已失效的日志级别门禁;邮箱、收件人、发送时间、固定发件人、主题/正文关键词和
+  ASCII 六位 OTP 继续由现有配置/解析边界校验。邮件仍只作数据,不引入 LLM 或第二读取通道。
+- `prepare_calendar` 保持线性顺序:表单就绪→一次 OTP→一次读取/输入→after 状态→一次 AVANTI→
+  Calendar/服务核对。调试 gate 迁到新聚合合同;不能要求生产恢复旧字段或枚举。
+- 不改变 Query/Book 角色配置、最终提交、重试、HTTP 传输或公共宿主 API;不新增 Italy 运行时文件。
+
+### 16.3 测试与准出
+
+真实 Node 表单 harness 必须继续覆盖两套配置、错误来源/action/method/enctype、上传项、错误标签、
+隐藏字段不同步、同行人数、未知 required、重复 OTP/AVANTI/Turnstile、change 导航和两阶段状态。
+生产流程继续覆盖一次发送/读取/输入、前导零、账号变化、窗口过期、错误 tab、无终端、同会话不重发、
+AVANTI 目标及 Calendar 准备。Turnstile 覆盖首次等待、间隔、总预算、错误表单、会话变化、helper
+异常和“点击成功不等于 token 就绪”。结束时运行定向、完整 Italy、完整调试、离线串联、配置/账号、
+AST/导入、文档链接和 `git diff --check`,记录首轮失败、迁移、行数与指纹。离线通过不等于真实 OTP
+或预约验收。
+
+## 17. R4 表单、OTP 与 Turnstile 准备链(实施结果,2752 行)
+
+### 17.1 实际改动与复用
+
+- 生产表单快照由约二十个 Python 镜像字段收为五个普通布尔事实:`formReady`、
+  `turnstileReady`、`otpValuePresent`、`otpSendEnabled`、`avantiEnabled`。JavaScript 仍逐项
+  校验来源、Booking path、form action/method/enctype、上传字段、配置化 booking/purpose
+  label/value、显隐同步、单人、Privacy、未知 required 以及唯一 OTP/AVANTI/Turnstile 控件。
+- 删除生产 `BookingPreflightStage`,前后阶段改为一个 `after_otp` 布尔;调试工具保留自己的
+  枚举只用于可读输出,不重新进入生产合同。
+- 删除 `validate_cloud_otp_logging`。CR-001 允许当前调试记录 OTP、Token 与敏感表单;邮箱地址、
+  当前账号、发送时间窗、固定发件人、主题/正文关键词及 ASCII 六位验证码约束仍保留。OTP 写入
+  失败继续映射为 `CalendarGateError`,并保留当前允许的原始诊断信息。
+- 删除 `ItalyTurnstileRecovery` 状态类,用局部恢复函数持有两阶段共用的三次预算。仍直接调用
+  VFS 已采用的 `CloudflareBypasser.click_verification_button(is_dfs=False)`,不刷新、不调用
+  `bypass()`,helper 成功后仍以页面 token 读回为准。
+- OTP 继续复用 `VSCloudApi.fetch_mail_content`;最终失败继续由现有 Booker 普通重试;没有新增
+  公共生产代码、Italy 运行时文件、邮箱客户端、验证码服务或重试调度器。
+
+### 17.2 测试迁移与首轮失败
+
+调试入口改为输出五字段的类型/值摘要,并在调用生产等待器时把诊断阶段转换成 `after_otp`。
+测试不再断言已删除的生产枚举、日志级别门禁或约二十字段键全集,但真实 Node harness 仍覆盖
+两套配置、错误来源/path/action/method/enctype、上传、错误标签和值、隐藏不同步、同行人数、
+未知 required、重复控件、change 离页和 OTP 前后阶段。
+
+第一轮定向回归因迁移后的测试夹具同时传入默认值和显式 `turnstileReady`,出现 1 个 Python
+参数错误;这是夹具错误,删除重复参数后通过。进一步删除日志门禁时,OTP 输入桩的
+`RuntimeError` 曾直接传播;实现恢复为 `CalendarGateError` 并保留 CR-001 允许的诊断详情后通过。
+没有放松表单事实、邮箱绑定、发送时间窗、一次发送/读取、DOM 读回或 AVANTI 目标合同。
+
+### 17.3 验证结果
+
+| 验证 | 结果 |
+| --- | --- |
+| R4 定向回归 | exit 0;279 项,0 skip |
+| `discover -p 'test_ita*.py'` | exit 0;385 项,0 skip |
+| `discover -p 'test_debug_ita*.py'` | exit 0;280 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项;`liveAcceptance=false` |
+| 配置/账号测试 | exit 0;27 项,0 skip |
+| 10 个编辑过的 Python 文件 AST 解析 | exit 0 |
+| 生产 `tools.*`/`test.*` 导入、三个已删生产符号搜索 | 均为 0 |
+| `git diff --check` | exit 0 |
+
+### 17.4 行数、指纹与结论
+
+Italy **2823 → 2752,净减 71 行**;SHA-256
+`a2d313755c631b15cbb360fdd1596c8317a40816a9cfb87e5d8513ad442e59e5`。公共
+`utils/plugin_utils.py` 仍为 497 行,SHA-256
+`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`,本批公共生产代码净增
+0 行。
+
+H-06 获得当前离线证据;H-08、RC-01、现场 RC-06/09 与整体 RC-10 仍未完成。R4 行数目标未
+达到,当前距约 1000 行仍差 1752 行,不能把 71 行下降外推为总预算成立。下一包 R5 审计插件
+入口、登录、生命周期和剩余工具钩子;继续最大化复用 `BaseFlow`、公共浏览器初始化、严格清理和
+宿主 Sentinel/Booker,不重写已经统一的表单、OTP、月份、选择或重试能力。
+
+全部测试使用合成浏览器、请求、邮箱和宿主边界;本批未访问真实网站、邮箱、账号池、订单或
+预约,未发送 OTP、AVANTI 或最终提交,未执行 Git 提交、推送或部署。用户配置、旧文档删除和
+其他工作区改动保持原样。
+
+## 18. R5 插件入口、登录与生命周期(实施前,2752 行)
+
+开始基线:`plugins/ita_plugin.py` 2752 行,SHA-256
+`a2d313755c631b15cbb360fdd1596c8317a40816a9cfb87e5d8513ad442e59e5`。引用
+T-01/T-02/T-08/T-10/T-11/T-12,H-01/H-02/H-08/H-10/H-11,UT-01/02/03/04/14/15、
+IT-04/05/06,RC-01/02/07/08/10。本批只做本地代码、工具消费者、测试和文档;不访问真实
+网站、邮箱、账号池、订单或预约,不执行 Git、推送或部署。
+
+### 18.1 当前调用图与复用结论
+
+1. 浏览器参数、代理/隧道、指纹、页面对象和清理已经直接复用
+   `init_chromium_options`、`ChromiumPage` 与 `cleanup_browser_workspace`;不新增
+   基类或第二套浏览器工厂。
+2. 登录已经使用 `BaseFlow/on/guard/done`;R5 只保留 Prenot@Mi 的首页、IAM 表单、验证等待、
+   阻断和 `/UserArea` 成功规则。CR-001 允许当前 Token/URL 诊断,因此 Italy 私有 URL 脱敏转发
+   不再支配生产结构。
+3. 生产 `set_config` 仍包含本地调试持久 profile 的路径、权限、符号链接和文件锁策略,共约百行;
+   TLS/VFS/BLS 没有这套插件私有生命周期,而现有 `utils/ita_local_profile.py` 已负责本地 Query
+   profile 的建立与权限。按既定 R5 方案,持久 profile 的绑定与锁归工具所有,生产插件只接受
+   宿主提供的临时 workspace。
+4. `last_calendar_query_scan`、`last_booking_precommit`、`_query_stop_reason` 和
+   `_calendar_book_attempted` 混合了真实调用状态与调试观察;其中最终提交只需函数参数传递,扫描
+   摘要和预提交观察由工具包装真实函数即可。迁移消费者后从生产删除,不保留影子状态层。
+5. Calendar 准备仍须绑定当前实例的 page/tab、会话代次、账号、route、role 与运行时服务;可用
+   一个实例内元组完成,不需要 owner id、profile path 和重复 route 重新解析。Query/Book 会话隔离、
+   当前库存和运行时 ID 检查不得删除。
+
+### 18.2 本批实施边界
+
+- 对齐 TLS/VFS 的 `__init__`、`set_config`、`health_check`、`create_session`、`cleanup` 和
+  `get_plugin_status` 形态;继续使用当前公共函数,不把 Italy 字段下沉到 `utils`。
+- 本地持久 profile 的创建、权限与排他锁必须由现有调试工具显式持有并在清理后释放;生产配置不再
+  解释 `persistent_browser_profile_path`。工具测试证明 profile 不被临时 workspace 清理删除。
+- 调试扫描/预提交消费者改为观察真实 `scan_until_first_available_month` 与
+  `recheck_calendar_before_final` 返回值;不能要求生产恢复专属诊断字段。
+- 不改表单、OTP、日历协议、日期/时段顺序、一次最终点击、普通重试、领区配置或传输通道;H-04
+  未现场通过前仍不切换生产月份读取。
+
+## 19. R5 插件入口、登录与生命周期(实施结果,2598 行)
+
+### 19.1 实际改动与所有权
+
+- 生产删除本地持久 profile 的路径解释、权限、符号链接和文件锁;Italy 调试工具通过
+  `utils/ita_local_profile.py` 的显式 lease 绑定 profile,并只在浏览器清理成功后释放。生产
+  单文件不依赖该工具模块,单文件热更新边界不变。
+- 删除 `last_calendar_query_scan`、`last_booking_precommit`、`_query_stop_reason`、
+  `_calendar_book_attempted` 及重复 cleanup 状态。Query/Book 工具改为观察真实扫描和库存重查
+  返回值;最终提交把当前 `PrecommitApproval` 作为普通参数传递,不保存第二份插件状态。
+- `_PreparedCalendar` 只保留当前 page/tab、账号、会话代次、route、role 和运行时服务;跨实例
+  仍由页面身份和当前账号/route 拒绝。重复 Book 调用按 CR-001 重新读库存,不复用旧运行时 ID。
+- 登录继续直接使用 `BaseFlow/on/guard/done`;删除只为 URL/Token 脱敏存在的 Italy 转发层,
+  密码仍未主动写日志。生命周期直接调用 HEAD 版本 `cleanup_browser_workspace`,没有改公共签名。
+
+### 19.2 首轮失败与修正
+
+首轮 328 项迁移回归有 1 error、1 failure:Query CLI 测试未隔离工具 profile lease;soak 重启
+错误地从可替换 checkpoint 取得真实 profile 路径,使篡改后的比较值能够自洽。测试补上外部
+lease 边界,soak 改为只从当前已准备实例取得真实路径,checkpoint 继续只作比较证据。之后
+328 项通过。完整回归首轮还暴露旧私有状态、旧脱敏和旧两参数 `submit_final` 断言;均迁到当前
+公开行为/参数合同,没有恢复生产字段、修改公共模块或删除业务场景。
+
+### 19.3 当前验证与边界
+
+| 验证 | 结果 |
+| --- | --- |
+| R5 入口/工具/Book/soak 定向回归 | exit 0;328 项,0 skip |
+| 受影响工具补充回归 | exit 0;74 项,0 skip |
+| `discover -p 'test_ita*.py'` | exit 0;384 项,0 skip |
+| `discover -p 'test_debug_ita*.py'` | exit 0;280 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项;`liveAcceptance=false` |
+| 配置/账号测试 | exit 0;27 项,0 skip |
+| 编辑文件 `py_compile` | exit 0 |
+| VFS/TLS/BLS/`plugin_utils.py` Git 差异 | exit 0;四个文件均无差异 |
+
+全部外部边界为模拟;没有访问真实网站、邮箱、账号池、订单或预约,没有发送 OTP、AVANTI 或
+最终请求,没有 Git 提交、推送或部署。用户配置和旧文档删除保持原样。
+
+### 19.4 行数、指纹与结论
+
+Italy **2752 → 2598,净减 154 行**,SHA-256
+`2af5585124d6e73892a0043c24da1a8014f154644906dca356d6df43a9b71569`。公共
+`utils/plugin_utils.py` 为 HEAD 的 489 行,SHA-256
+`9b521797de461b381cc6b3da7060339110c70c6835d3a04824043c72492c96fa`,本批公共生产代码净增 0。
+
+H-01/H-02/H-10/H-11 在本批离线范围增加证据;H-08、现场 H-04、RC-01、真实预约 RC-09 与
+整体 RC-10 仍未完成。当前距约 1000 行仍差 1598 行;下一结构包必须转向占比最大的日历捕获、
+选择和表单脚本重复表示,不继续从其他插件或公共模块制造改动。
+
+## 20. R6 Italy 内部样板收敛(第一批,2442 行)
+
+本批引用 T-01/T-02/T-03/T-04/T-08/T-12,H-03/H-05/H-08,UT-07/08/09/10/11/15、
+IT-01/02/04/06,RC-01/02/03/04/08/10。硬边界是只改 Italy 生产单文件及其测试/记录;
+`plugins/vfs_plugin.py`、`plugins/tls_plugin.py`、`plugins/bls_plugin.py` 和
+`utils/plugin_utils.py` 必须保持 Git 差异为零。
+
+实际删除了无生产消费者的时间校验辅助、重复月份结果校验、重复配置/OTP/状态包装和入口样板;
+保留双层 JSON、库存冲突、月份边界、表单五事实、自动 OTP、一次 AVANTI、Book 用户会话重查、
+一次最终点击和普通失败交回 Booker。首轮为压缩错误包装导致 2 项调试错误消息断言失败,恢复稳定
+错误分类后通过;没有通过放松请求方法、路径、库存或选择事实解决失败。
+
+验证结果:Italy 384 项、调试 280 项、框架离线入口 77 项、配置/账号 27 项全部 exit 0、0 skip;
+`py_compile`、`git diff --check` 通过;四个受保护文件差异检查 exit 0。全部外部边界为模拟,未访问
+网站、邮箱、账号池、订单或预约,未发送 OTP、AVANTI 或最终请求。
+
+Italy **2598 → 2442,净减 156 行**;SHA-256
+`a24f3a0c53bde36e7f2dc5c4423175567af155e4db4290614deea6fab93fcc73`。本批公共生产代码净增 0。
+RC-01 仍未通过,距约 1000 行仍差 1442 行;不能把本批称为重构完成。
+## 21. R6/R7 公共浏览器请求与薄 Query/Book 适配器(实施结果,1299 行)
+
+日期:2026-09-01。引用 T-01/T-02/T-03/T-04/T-06/T-07/T-09/T-12,H-03/H-04/H-05/H-06/H-07/H-08/H-11,UT-04/06/07/08/09/10/11/12/14/15,IT-01/02/03/04/05/06,RC-01/02/03/04/05/06/07/08/10。本批只有本地实现、测试和文档;没有访问网站、邮箱、账号池、订单或预约,没有 Git 提交、推送或部署。
+
+### 21.1 实际改动与公共复用
+
+- Italy 月份与时段读取直接调用未修改的 `utils.plugin_utils.perform_browser_fetch`,分别 POST 网站的 `RetrieveCalendarAvailability` 和 `RetrieveTimeSlots`;删除生产私有监听器、请求包、头字段包装、捕获超时器和两套 Query/Book 请求表示。
+- Query 与 Book 共用同一双层 JSON 解析和库存模型;Query 在首个正向月份停止,Book 在申请人会话重新读取月份和时段,再以 DOM 核对并选中当前申请人的日期/时段。
+- 表单/Turnstile/OTP 收为线性准备函数,继续直接复用 VFS/BLS 已使用的 `CloudflareBypasser` 与 `VSCloudApi.fetch_mail_content`;固定发件人、收件人、发送时间、模板及唯一六位 ASCII 验证码约束保留。
+- 最终提交在当前已核对选择上调用一次公共 browser fetch POST `InsertNewBooking`;明确成功才返回成功,其余普通失败清空准备状态并交回现有 Booker。未新建重试器、账号池、信号、订单、HTTP 客户端或 Italy 私有运行时文件。
+- 插件入口继续复用 `BaseFlow`、`init_chromium_options`、`cleanup_browser_workspace`、公共返回类型和异常;日期范围继续复用 `filter_dates_in_range`。VFS/TLS/BLS 和 `utils/plugin_utils.py` 的受保护 diff 为 0。
+
+### 21.2 首轮回归与测试迁移
+
+旧 `test_ita*.py` 套件首轮运行出现大量失败和导入错误,原因是测试直接导入已删除的 `NATIVE_FINAL_SCRIPT`、`CalendarNextMonthUnavailableError`、请求监听器及诊断状态对象,并逐字断言旧错误消息。这些结果不是新运行时的业务失败,但也不能标记全量通过;不能恢复旧生产结构迎合旧测试。
+
+新增 `test/ita/test_ita_compact.py`,直接验证配置化领区、公共 browser fetch 请求、首个正向月份停止、申请人库存重查、服务身份、预提交零最终请求、最终单次写入及明确成功判定。协议、OTP、登录和公共生命周期测试迁到当前公开合同;修复了时间字段错误路径、OTP 收件人规范化、配置化过滤器拒绝以及日历服务不匹配被等待循环误吞的问题。
+
+### 21.3 当前验证结果
+
+| 验证 | 结果 |
+| --- | --- |
+| `test_ita_protocol.py` | exit 0;24 项 |
+| `test_ita_otp.py` | exit 0;14 项 |
+| `test_ita_compact.py` | exit 0;13 项 |
+| `test_ita_login_flow.py` | exit 0;7 项 |
+| `test_ita_shared_lifecycle.py` | exit 0;6 项 |
+| `py_compile plugins/ita_plugin.py` | exit 0 |
+| `git diff --check`(当前实现与精简测试) | exit 0 |
+| VFS/TLS/BLS/`utils/plugin_utils.py` 受保护 diff | exit 0;零改动 |
+
+上述共 64 项为当前薄实现的离线业务合同,使用合成页面、响应、邮箱和账号;没有真实外部请求。旧实现耦合测试和三个旧调试入口仍有损坏导入,H-11/RC-07/10 尚未整体通过。
+
+### 21.4 行数、指纹与结论
+
+Italy 从基线 6286 行降为 **1299 行**,相对基线净减 4987 行;相对 Git 当前基线差异为新增 967、删除 5954。SHA-256 为 `c6153deff039bdb09321c5ef1d34b871a82d880a84d9db18634d33152fdd735c`。同仓 VFS 1271 行、BLS 1107 行、TLS 852 行,Italy 已进入同一量级;没有通过压缩排版、外移 Italy 专属逻辑或改其他插件达成。
+
+H-03/H-05/H-06/H-07/H-08 获得当前离线证据;H-04 仅已有历史现场协议证据,新的 browser-fetch 路径尚未用同一待发布版本现场对照。RC-01 的行数量级已满足但必须与测试迁移共同验收;RC-09 真实预约和 RC-10 总体准出仍未完成。下一步只迁移工具/测试消费者并执行全量回归,不恢复已删除的生产私有诊断实现。
+
+## 22. R7 薄适配器后续收敛(1171 行)
+
+日期:2026-09-01。继续引用 T-01/T-02/T-03/T-04/T-08/T-09/T-12 与 RC-01/02/07/10。
+删除无生产价值的日历结果包装、最终审批包装、提交转发方法、重复 prepared-route 入口和登录错误
+影子状态;Query/Book 直接传递 `CalendarDay`、`SlotCandidate` 及公共返回类型。三个大型旧 gate
+改为指向现有 Query+Book CLI 的兼容入口,不再各自复制 Italy 生产协议。
+后续安全精简合并正整数/月份上限校验和两类库存过滤别名,删除失效的机械迁移章节,并把最终提交
+改成明确成功立即返回、其余统一清理后失败;协议边界、提交次数和失败重试语义未改变。
+
+当前 `plugins/ita_plugin.py` 为 **1171 行,其中 1007 个非空行**,SHA-256
+`63235dcd82094eca8bfd006f783fd48af0af6f8c3afc1b901f538ac2d657afd9`;VFS 1271 行、
+BLS 1107 行、TLS 852 行。64 项薄实现离线合同和 15 项 PluginTester 配置测试通过;
+`py_compile`、`git diff --check` 及 VFS/TLS/BLS/`utils/plugin_utils.py` 零差异检查通过。
+旧实现耦合测试仍需迁移,现场 RC-06/09 和整体 RC-10 未完成,故本节不宣称可发布。
+
+本批没有访问网站、邮箱、账号池、订单或预约,没有发送 OTP、AVANTI 或最终请求;没有执行
+Git 提交、推送或部署。用户配置、既有文档删除和其他工作区改动保持原样。
+
+## 23. 现场异步表单竞态修复(1178 行)
+
+日期:2026-09-01。引用 T-03/T-05/T-07/T-08、H-06、UT-05/06、LT-01、RC-03/06。
+用户在真实 `/Services/Booking/4937` 失败现场提供的只读快照显示:页面和表单完整、Privacy 已由
+预检脚本选中,但 `GetBookingTypes` 与 `GetDdlValuesByID` 分别耗时约 962ms/544ms;请求完成后
+目标选项 `1` 与 `42` 已出现,两个控件仍保持空值/`0`。这证明首次脚本运行早于异步选项完成,
+而旧等待器把暂时的 `formReady=false` 当成致命失败。
+
+实施保持原五布尔合同,不增加状态类或公共模块:结构/布尔类型及 OTP 阶段错位仍立即失败;
+表单、OTP 发送按钮、Turnstile token 或 AVANTI 暂未就绪则在原 120 秒边界内重新读取;只有表单
+安全时才允许调用现有 `CloudflareBypasser`,并保持最多三次;OTP 后允许发送按钮进入网站冷却态。
+安全的超时原因随现有业务异常返回,避免再次只看到无上下文的 `Italy Query failed`。账号池、
+邮件读取、日历扫描、最终提交和 VFS/TLS/BLS 均未修改。
+
+新增 5 项当前薄合同回归位于 `test/ita/test_ita_compact.py`:异步表单三次快照后放行、永不就绪时
+不触碰 Turnstile、OTP 按钮未就绪不放行、OTP 后冷却可通过以及 Query 保留安全失败原因。
+
+验证结果:
+
+- 首轮将包名直接交给 `unittest` 时出现 3 个既有测试导入错误,原因是精简测试依赖 `test/`
+  位于模块搜索路径;生产实现没有失败。按真实运行方式加入 `PYTHONPATH=test:.` 后重跑。
+- `PYTHONPATH=test:. PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test_ita_protocol test_ita_otp test_ita_compact test_ita_login_flow test_ita_shared_lifecycle`:exit 0,69 项。
+- `PYTHONPATH=test:. PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test_plugin_tester_ita_config`:exit 0,15 项。
+- `py_compile plugins/ita_plugin.py test/ita/test_ita_compact.py`、`git diff --check`:exit 0。
+- VFS/TLS/BLS/`utils/plugin_utils.py` 受保护差异:0。
+
+Italy 当前 1178 行,SHA-256
+`c6566021f997b5b9a1228229bd2f206b33c65a2c573c18acb78b89a960ccef7e`。本次生产净增 7 行,
+没有新增公共生产代码或 Italy 运行时文件。H-06 的该竞态获得真实现场诊断和离线回归证据;
+修复后的 LT-01 仍须用户用同一待发布工作区复验,因此 RC-03/06 和整体 RC-10 尚未完成。
+本次实现与离线测试没有访问网站、邮箱或预约,没有发送 OTP、AVANTI 或最终请求,也未执行
+Git 提交、推送或部署。

+ 572 - 0
docs/italy-refactor/records/W3-query-entry.md

@@ -0,0 +1,572 @@
+# W3:生产 Query 与弱探测入口分离
+
+日期:2026-09-01;状态:入口、共用月份捕获、库存解析及控件语义合同部分完成;最新 Italy/调试回归通过,整体预算未完成。
+
+依据 T-03/T-04/T-11/T-12、H-03/H-08/H-11、UT-09/14、IT-01/05、RC-03/07/08/10。配套:[技术方案](../01-technical-design.md)、[测试计划](../04-test-plan.md)。
+
+第 1–8 节保留 5621、5334、4339 行等历史快照;第 9–10 节记录控件语义合同收敛时的 3926 行快照。最新工作区为 3795 行,生命周期后续见 [W2 第 14–15 节](W2-login-preparation.md);历史失败和旧指纹不覆盖最新结果。全程未运行真实站点、邮箱或预约,未提交、推送或部署。
+
+## 1. 已有改动及职责边界
+
+- `ItaPlugin.query()` 明确要求 `calendar` 模式和完整路由;旧 `services_probe` 不再经公开查询返回弱信号。
+- `_query_once` 只处理已经准备好且路由连续的日历查询。会话准备继续由既有内部步骤完成,不另建调度器。
+- `_enter_service` 保留为内部/诊断入口;成功仅代表进入表单,不能发布为真实库存。
+- `tools/debug_ita_query.py` 的诊断分支调用内部服务入口,生产工作流分支调用真正 `query()`;`tools/debug_ita_calendar_gate.py` 的初始准备改用内部入口,后续生产查询仍调用公开 Query。
+- `set_config` 对旧诊断配置的接收与 Book 自己的配置语义未删除。旧配置直接调用生产 Query 会明确失败,这是 T-11 已要求的迁移,不默默当成无号。
+
+复用对象仍是现有路由解析、会话准备、日历扫描、公共返回类型及 Sentinel/Booker。没有新增公共 API、Italy 私有运行时或 HTTP 替代通道;H-03 的共用月份读取尚未实现。
+
+## 2. 测试与消费者迁移
+
+| 消费者 | 已处理 | 尚缺 |
+| --- | --- | --- |
+| `test/test_ita_plugin.py` | 服务入口行为测试改用内部入口;新增生产 Query 拒绝旧模式且不操作浏览器的测试;原生产日历测试保留 | 共用日历精简后的完整回归 |
+| `test/test_debug_ita_query.py` | 诊断入口与真实 Query 调用分别计数;诊断误调用公开 Query 即失败 | 无本批局部失败 |
+| `test/test_debug_ita_production_query_gate.py` | 生产工具已改入口 | 共享夹具仍把 `plugin.query` Mock 成准备成功,未提供新的内部入口边界;5 项工作流测试提前失败 |
+| `test/test_ita_calendar_soak.py` | 保留同实例转交、一次准备及清理检查 | 使用上述共享夹具,另有 1 项失败 |
+| `tools/debug_ita_book_gate.py` / 对应测试 | 仍保留诊断白名单 | W4 删除了一个旧错误文案的生产者,但白名单/静态契约尚未同步;1 项失败 |
+
+六项共享夹具失败的直接证据都是 `FakeAuditPage` 缺少 `ele`:真实 `_enter_service` 被意外执行在仅供计数的假页面上。修复应明确迁移准备边界,同时保留真实公开 Query 的专门集成测试;不能把整个查询/预约替换成永远成功的 Mock。
+
+Book 诊断失败对应旧文案 `Book readback unexpectedly clicked`。需要使生产错误、白名单和测试含义一致,同时保留“只读回查不能点击”的业务断言,不是直接删掉失败测试。
+
+## 3. 历史全量验证(5621 行)
+
+仓库根目录执行,Python 命令前缀统一为:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B
+```
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_plugin test.test_debug_ita_query test.test_debug_ita_calendar_gate test.test_ita_workflow` | exit 0;175 项,0 skip |
+| `-m unittest test.test_ita_protocol test.test_ita_calendar_book test.test_ita_calendar_book_flow test.test_ita_booking_final test.test_ita_final_read_port` | exit 0;191 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 1;531 项,1 failure,0 skip;共享准备夹具 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 1;313 项,6 failures,0 skip;5 项共享准备夹具、1 项诊断映射 |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip;既存旧文档依赖 |
+| `git diff --check`(无 Python 前缀) | exit 0 |
+
+各套件有交集,不累加为独立通过数量。既存失败仍依赖用户已删除的 `docs/ita_query_book_acceptance.md`;不恢复该文件或跳过测试,按 W5 迁移其可执行命令消费者。测试中的网络、邮箱、浏览器和云端边界为模拟;框架离线结果不能算真实预约。
+
+## 4. 历史行数与工作区指纹(5621 行)
+
+HEAD:`a22596f1fcdffb946960724ef299f249e7860891`,尚未提交。
+
+| 文件 | W0 | W2 上次记录 | 当前 | 相对 W0 |
+| --- | ---: | ---: | ---: | ---: |
+| `plugins/ita_plugin.py` | 6286 | 5863 | 5621 | -665 |
+| `utils/plugin_utils.py` | 489 | 497 | 497 | +8 |
+| 两个生产文件合计 | 6775 | 6360 | 6118 | -657 |
+
+本批 W3 与 [W4 独立子项](W4-selection-readback.md) 合计再减少 242 行;没有新增公共生产代码。测试、工具、文档单独计,不把它们冒充生产文件的减少量。
+
+SHA-256:
+
+- Italy:`b5451e14f07860adfa93ffd7ffc95189f1681afa6def80d16d1ae3b0cf86320e`。
+- 公共工具:`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+## 5. 当时的结论与下一步
+
+W3 只有入口分离,H-03 共用日历及 H-08 行数目标未完成,H-11 有明确迁移失败。7 项新增失败及既存命令消费者失败均是必须解决的准出阻断,不因定向测试通过降级为可忽略问题。
+
+下一次获准开发首先收尾这些已改结构的消费者,再继续 W2 准备状态、W3 共用读取与 W4 Book 精简。现有宿主公共清理 API 部署前置条件仍适用。未完成真实 Query、预提交或真实提交验收。
+
+## 6. 后续执行:共用捕获与一次解析(5334 行)
+
+本子项依据 T-02/T-03/T-04/T-08/T-11/T-12、H-03/H-05/H-08/H-11、UT-07/08/09/10/11/14、IT-01/04/05、RC-02/03/04/08/10。沿用已授权的 Italy 精简范围,只改 Italy、现有测试/调试消费者及记录;不改配置来源、公共接口或最终提交策略。
+
+### 开始范围与实际改动
+
+预期删除重复准备夹具、重复库存状态和重复解析/捕获路径,而非新建共享框架或下沉 Italy 私有代码。实际从 5621 减到 5334 行:
+
+1. **消费者先恢复**:准备夹具改为明确模拟 `_enter_service`,并断言准备不调用公共 Query;真正公开 Query 的独立集成测试保留。Book 诊断白名单改为现有实际错误;“读回不能点击”由真实 `verify_precommit_selection` 回归覆盖,未丢弃业务断言。
+2. **统一库存模型**:`SlotCandidate` 复用 `CalendarDay` 的日期/计数校验;可用状态由已校验计数推导,不再保存另一份可互相矛盾的 `state` 参数。仍拒绝冲突计数、布尔伪整数、错误日期/时段及非正 runtime ID。
+3. **统一解析边界**:日期和时段的双重 JSON、字段及重复项检查合并为 `_parse_calendar_items`;外部输入在这里解析。Book `_CapturedMonth` 持有解析结果,选择时不再次解析同一原始响应,也不把它作为下一次预约的跨会话缓存。
+4. **直接复用公共日期筛选**:`_available_inventory` 用现有 `filter_dates_in_range(..., shuffle=False)`;日期默认边界及错误输入仍校验。时段按日期、开始/结束时间升序,修复过去按余量排序的方案偏差。
+5. **统一月份捕获**:Query/Book 都调用 `_capture_month`,共用原生动作、请求捕获及库存解析;Query 只主动监听可用日期响应,Book 另核对自己的 tab、服务、自动时段与选中日期。网站自然产生的自动时段读取仍允许存在,不把它当作 Query 主动预约。
+6. **保持两个业务流程**:Query 的单一循环逐月前进、首个正向月即停止;Book 仍在申请人会话重查库存、处理旧日期售罄与选择。没有共享 Cookie、OTP 或运行时 ID,也没有让 Book 调用公开 Query。
+
+所有生产逻辑仍在 `plugins/ita_plugin.py`,没有新增 `utils` 能力或私有运行时。`utils/plugin_utils.py` 本批未变化,仍只有 W1 的可选严格清理扩展(相对基线 +8 行)。原生浏览器路径保留;没有宣称 HTTP 等价已验证。
+
+### 业务测试迁移与新增证据
+
+| 测试位置 | 业务证据 |
+| --- | --- |
+| `test/test_debug_ita_production_query_gate.py`、`test/test_ita_calendar_soak.py` | 原 6 项共享准备夹具错误修复;准备不能误调用公开 Query,真实 Query 集成仍执行 |
+| `tools/debug_ita_book_gate.py`、`test/test_ita_calendar_book.py` | 旧白名单生产者迁移;主动在读回快照注入 `clicked=true` 仍拒绝且实际点击数为 0 |
+| `test/test_ita_protocol.py` | 状态改为派生后仍检验库存冲突/最后一个名额/严格计数/非法 ID;不为旧构造参数保留第二套模型 |
+| `test/test_ita_calendar_book.py`、`test/test_ita_booking_final.py`、`test/test_ita_single_file.py` | 私有选择器改收已解析库存;使用真实解析器迁移夹具;热加载版本使用自身类型,不借旧模块缓存 |
+| `test/test_ita_calendar_book_flow.py` | 每个捕获库存响应只解析一次;较晚时段余量更多也不覆盖时间升序 |
+| `BookEntryTests.test_query_and_book_share_month_reader_but_not_account_inventory` | 真正 `query()` 返回 10 月 13 日;不同申请人的该日已售罄,真正 `book()` 重查并选 14 日;两边都走真实共享捕获,最后请求为 0、选中一次、监听器全部停止 |
+| `CalendarProductionScanTests.test_invalid_scan_interval_never_touches_the_browser` | `bool/None/string/负值/NaN/infinity` 间隔拒绝,页面调用数为 0 |
+
+上述跨角色用例仅模拟浏览器边界,使用两个不同账号和页面;公共 Query/Book、库存解析及选择算法均未 Mock 成成功。Query 信号到 Sentinel/Booker 的框架行为仍由既有离线入口覆盖。
+
+### 5334 行时的运行结果
+
+仓库根目录执行;Python 前缀为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。
+
+| 命令后缀 | 退出码与结果 |
+| --- | --- |
+| `-m unittest test.test_ita_calendar_book_flow.BookEntryTests.test_query_and_book_share_month_reader_but_not_account_inventory test.test_ita_calendar_query` | exit 0;10 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;534 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;313 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip;仍为已删除旧文档命令依赖 |
+| `git diff --check`(无 Python 前缀) | exit 0 |
+
+原 7 项迁移错误均已修复;旧文档依赖不是本批新错误,但仍是未完成的消费者迁移,不能排除在准出之外。套件有交集,不累加为独立测试总数。未运行任何真实站点、邮箱或预约;没有改账号池冷却、提交或推送代码。
+
+### 行数、预算复核与指纹
+
+HEAD 仍为 `a22596f1fcdffb946960724ef299f249e7860891`。当前 Italy 5334、公共工具 497,合计 5831;相对 W0 的 6775 行净减 944。Italy 本身减 952 行,本批比 5621 再减 287 行,离 1000 仍差 4334 行。
+
+按现有机械分区边界核算(包含空行、注释、JS,不移出私有运行时):
+
+| 分区 | 当前行数 | 方案预算 | 状态 |
+| --- | ---: | ---: | --- |
+| 配置/协议/数据模型 | 677 | 140 | 已收敛部分模型与解析,仍超预算 |
+| Query/Book 日历 | 1288 | 180 | 读取已共用,扫描/选择层仍重 |
+| 最终提交/预约记录/回执 | 1189 | 200 | 本批未精简 |
+| 表单/OTP/验证/工作流 | 962 | 240 | 准备状态与报告耦合待继续处理 |
+| 插件入口/登录/会话/清理 | 1208 | 220 | 公共能力已接入,会话表示待收敛 |
+| 文件组织 | 10 | 20 | 不靠改变排版补预算 |
+| 合计 | 5334 | 1000 | 未完成;H-08 未通过 |
+
+SHA-256:
+
+- Italy:`72641546474c971254097955f113187ed27ae49b165a56583bef8c02e5d768e6`。
+- 公共工具:`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+结论:H-03 共用月份读取与 H-05 一次解析有当前离线证据,H-11 本批消费者已迁移但旧文档命令仍失败;H-08 远未完成。下一次优先继续合并准备/扫描结果与提交/回执的重复层,并复核预算;不能把分区目标当成可行性保证,不能只作排版缩行。H-04 和新版本真实预约仍待验证,公共清理 API 的宿主部署前置条件不变。
+
+## 7. 后续实施:日历页面操作与选择收敛
+
+开始基线:4483 行,Italy SHA-256 `d9d7041c184551c54173624f8681a73932408237729e44f2e705f8e1dce5233e`。引用 T-01/T-02/T-03/T-04/T-06/T-08/T-09/T-10/T-11/T-12,H-03/H-05/H-08/H-10/H-11,UT-07/08/09/10/11/12/15、IT-01/03/04/05,RC-01/02/03/04/05/08。上一批有实际代码和回归进展;本批只做本地实施、离线验证及记录,不执行网站、邮箱、账号池或预约操作。
+
+核对 TLS 的原生监听/选中方式、VFS 的日期筛选与公共 `filter_dates_in_range`、`perform_browser_fetch`:日期筛选和公共生命周期继续复用;尚无 H-04 等价证据,本批不更换日历传输通道。公共模块没有可直接复用的 Italy 选中状态读取,因此在同一插件内合并现有网站脚本的公共片段,不向 `utils` 搬迁 Italy 逻辑,也不新建浏览器操作框架。
+
+本批计划合并三种控件重复的样式/可操作性检查,以及日期与时段重复的当前服务、日期、最终按钮保护读取;保留原生日期允许零布局尺寸的已验证差异,不能把鼠标命中要求强加给日期链接。Python 侧合并 `_try_day` 与 `select_slot_before_final` 中重复的候选筛选、就绪等待与读取;仍在申请人会话捕获时段、等待真实 DOM、只选一次,最后只读核对不触发点击。月份/时段包的重复元数据或等待包装在相同行为边界内一并审查,不改错误分类、重试或最终提交策略。
+
+文件范围:`plugins/ita_plugin.py` 及现有日历、Book flow、最终提交、热加载与调试测试;必要时迁移对应 `tools` 私有调用,不新增生产文件。预计本批减少约 100–200 行,实际收益与测试修改分别记账;总目标仍为约 1000 行。验证包括真实 JavaScript 的 Node DOM 夹具、公开 Query/Book、延迟渲染/状态变化、一次点击/提交、热加载、完整 Italy/调试回归和旧命令故障检查;不能只用总是成功的快照桩证明脚本合并正确。
+
+实施前补充 T-10 范围:服务入口缺失时的表格数量/“已预约”提示统计仅用于排障,不参与库存判断,而且提示没有绑定目标服务。将该脚本及脱敏读取放到现有 `tools/debug_ita_query.py`,由该入口和 `tools/debug_ita_soak.py` 的失败诊断调用,删除生产插件的诊断缓存。生产仍抛出同一缺失入口异常,不把页面级提示认作目标服务已预约。同步迁移真实脚本、脱敏、Query/Book 失败和 soak 诊断测试,验证诊断失败不覆盖原业务失败。此项属于诊断归位,不计作删除的重复业务逻辑,也不新增隐藏的生产运行时。
+
+## 8. 日历操作与诊断归位结果:4339 行
+
+### 实际修改
+
+依据第 7 节的技术、假设、测试和准出编号,完成本地结构合并,没有修改公共 API、配置来源、传输通道或提交策略。
+
+1. **日历脚本共用页面事实**:翻月和时段共用样式、视口及遮挡检查;日期与时段共用服务、选中日期、最终按钮保护读取。日期链接仍允许零布局尺寸的原生点击,不套用鼠标命中条件。翻月在实际点击前验证来源和路径,不能在错误页面上先点击后报错。
+2. **时段候选只筛选一次**:将 `_try_day` 与 `select_slot_before_final` 的重复筛选和 DOM 等待合并。DOM 延迟时只继续读取、不重新发库存请求;等待有界,点击前后仍核对快照。新增点击前账号变化检查,防止读取期间换账号后继续选择。
+3. **诊断归位,不是业务外移**:服务表统计脚本原样移至已有 `tools/debug_ita_query.py`,与 soak 共用脱敏输出函数。生产删除 `last_service_list_structure` 和 `_inspect_service_list_structure`,缺失入口仍抛 `ItaTargetServiceLinkMissingError`;统计只由调试失败边界执行。页面级已预约提示不归属于目标服务,诊断读取异常不能掩盖原业务失败。
+
+继续直接复用公共日期筛选、生命周期、`BaseFlow` 和邮件接口;本批未新增公共函数或 Italy 运行时文件。没有通过 HTTP 探测、增加重试或删掉最终核验来缩短代码。
+
+### 测试与消费者迁移
+
+| 位置 | 本批业务证据 |
+| --- | --- |
+| `test/test_ita_calendar_query.py` | 新增 2 项实际 Node 脚本测试,覆盖可用翻月及隐藏、禁用、离屏、遮挡、重复、错误来源/路径等不可点击状态 |
+| `test/test_ita_calendar_book_flow.py` | 新增 3 项:DOM 延迟仍只筛一次/点一次;超时无额外请求和点击;真实公开 Book 在读回期间账号变化时拒绝点击 |
+| `test/test_ita_calendar_book.py`、`test/test_ita_booking_final.py` | 原实际 JavaScript 日期、时段与最终按钮测试继续执行;零布局日期、只读不得点击、原生一次提交边界保留 |
+| `test/test_ita_plugin.py` → `test/test_debug_ita_query.py` | 原 2 项服务提示 JavaScript 测试机械迁移,仍检查可见精确文案及只输出行数;生产保留缺失入口不是无号/成功、其他服务预约不阻断目标入口等断言 |
+| `test/test_debug_ita_query.py`、`test/test_debug_ita_soak.py` | 新增 6 项:统计边界/脱敏/无归属、异常不可用、失败后清理和 soak 恢复;不再依赖生产诊断缓存 |
+
+本批净新增 11 项测试;另有 2 项从 Italy 套件迁往调试套件,因此套件数量变化不等于删除业务覆盖。只模拟外部边界,公开 Query/Book 与真实解析/脚本仍执行;既有单文件上传、版本隔离和热加载测试也包含在完整 Italy 回归内。
+
+### 最终代码验证
+
+仓库根目录执行;Python 前缀均为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。以下均为离线、0 skip,套件有交集,不累加成独立测试总数。
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_plugin test.test_debug_ita_query test.test_debug_ita_soak` | exit 0;85 项 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;547 项 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;323 项 |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录;仍依赖已删除旧文档命令 |
+| `git diff --check`(无 Python 前缀) | exit 0 |
+
+配置/命令失败仍是必需的 W5 消费者迁移,不恢复用户删除的文件、不删除原业务断言或跳过测试。既有 Redis `setex` 弃用警告不在本批扩展处理。未运行真实网站、邮箱、账号池或预约,未 Git 提交、推送、部署;用户配置与旧文档删除保持原样。
+
+### 行数、指纹与剩余安排
+
+实际 **4483 → 4339,净减 144 行**:共用脚本及筛选/等待净减 52,生产诊断归位净减 92。后者是诊断职责迁移,不冒称删除了同等数量的业务算法。没有新增公共生产代码;公共工具仍 497 行,相对 W0 净增 8。Italy 相对 W0 减 1947 行,两生产文件合计 4836,比基线 6775 净减 1939 行。
+
+相对 HEAD 的分类差异:两个生产文件新增 855 / 删除 2794 行;工具新增 249 / 删除 46,净增 203;已跟踪测试新增 1084 / 删除 552,加两份新增测试 291 行,测试净增 823。工具、测试和文档不冒充生产业务代码的消失。
+
+| 分区 | 当前行数 | 方案预算 | 尚需处理 |
+| --- | ---: | ---: | --- |
+| 配置/协议/模型 | 464 | 140 | 保留外部输入校验,减少配置与模型包装 |
+| Query/Book 日历 | 1141 | 180 | 重复控件检查已合并,扫描/捕获/读回层仍重 |
+| 最终提交/预约记录/回执 | 951 | 200 | 合并提交与只读回查调用层,不删未知结果处理 |
+| 表单/OTP/验证/工作流 | 836 | 240 | 合并准备与等待,保留账号/时间窗和一次发送 |
+| 插件入口/登录/会话/清理 | 898 | 220 | 已移出诊断统计,入口与配置绑定仍需收敛 |
+| 文件组织 | 49 | 20 | 正常排版,不以压行代替精简 |
+| 合计 | 4339 | 1000 | 尚差 3339 行,H-08 未通过 |
+
+HEAD 仍为 `a22596f1fcdffb946960724ef299f249e7860891`。SHA-256:Italy `6b12236897f95d2279882eaf1297b9551f0476b569a324a0423580673f8fa207`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+本子项离线回归通过,W2–W6 仍未整体完成。H-03/H-05/H-10/H-11 增加上述场景证据,不能推导 H-04 的 HTTP 等价、约 1000 行可行性或新版本真实 Book 已成功。下一步优先收敛表单准备/等待与提交读取调用层,同时按 W5 迁移旧命令消费者;已完成的控件共享与诊断迁移不重复实施。周期仍按开发计划复核,不能按本批减行比例承诺剩余交付时间。
+
+## 9. 日历日期/时段语义合同收敛(实施前)
+
+开始基线:3981 行,Italy SHA-256 `9a5d03724af1769c2127d0d154627f80c082a461b894a80fea3aabb36ddb204c`。引用 T-01/T-02/T-03/T-04/T-06/T-08/T-09/T-10/T-11/T-12,H-03/H-05/H-08/H-10/H-11,UT-07/08/09/10/11/12/15、IT-01/03/04/05,RC-01/02/03/04/05/08。本批只做本地代码、测试和文档;不访问网站、邮箱、账号池或订单,不执行真实预约、Git 提交、推送或部署。
+
+### 代码事实与判断
+
+- `SLOT_SELECTION_SCRIPT` 已在浏览器内检查来源/路径、当前服务、最终按钮保护、日期双重选中、日期可用性、时段唯一性、运行时 ID、时间、容量、不可用标记、点击命中和选中读回,但又把这些事实拆成 21 个字段交给 `_snapshot`、`_require_ready`、`_approve_selection_snapshot` 重复组合。
+- `DATE_SELECTION_SCRIPT` 表达同一类控件状态,却使用另一套 6 字段结构和另一份校验函数。生产调用者只需要知道:上下文是否安全、候选数量、候选是否就绪、当前是否已选中、本次是否点击。
+- `tools/debug_ita_book_gate.py::_selection_readback` 再次读取生产私有快照并逐字段复验;现有 `verify_precommit_selection` 已是严格、只读、不会点击或提交的生产边界,应直接复用。
+- 公共模块没有网站无关且能直接替代这些 Prenot@Mi DOM 语义的函数;将脚本移到 `utils` 只是搬家。因此本批仍留在单文件插件内,但日期和时段使用同一内部控件合同。
+
+### 本批改法与不变边界
+
+1. 日期和时段脚本都返回精确五字段:`contextReady`、`candidateCount`、`candidateReady`、`selected`、`clicked`;底层 DOM 检查全部留在脚本中,只把重复的原子证明聚合为业务语义。
+2. Python 使用一个严格结构/类型读取器;零候选允许在有界 DOM 等待中继续读取,重复候选、错误页面/服务/日期、未保护最终按钮立即失败。
+3. 时段选择仍按申请人会话的最新 Availability/TimeSlots 选最早正向候选;已有正确选中不重复点击,否则只允许一次原生点击,随后用只读快照验证 ID、日期、时间、容量和 CSS 可用性。
+4. 日期链接继续保留已验证的零布局原生点击差异,不增加鼠标命中要求;读回不得点击,最终 `Prenota` 始终被保护。
+5. 调试 Book gate 改用 `verify_precommit_selection`,不再依赖 `_snapshot`/`_require_ready` 私有实现;错误原因映射随公开生产错误边界迁移。
+6. 不切换到 HTTP。H-04 仍无现场等价证据,月份和时段继续通过当前浏览器原生请求/监听获取;不改变 OTP、重试、未知提交或最终回执策略。
+
+预计生产净减 80–150 行,不新增 Italy 运行时文件或公共生产函数。验证必须包含实际 Node DOM 合同、延迟渲染、上下文/候选/选中漂移、一次点击、只读零点击、公开 Book、最终提交与单文件热更新,再执行完整 Italy、调试、离线串联及配置回归。若第一轮失败来自旧字段结构断言,必须逐项迁到相同业务行为,不能删除场景或放松脚本检查。
+
+## 10. 日历日期/时段语义合同结果:3926 行
+
+### 实际实现与复用
+
+- `DATE_SELECTION_SCRIPT` 与 `SLOT_SELECTION_SCRIPT` 现在使用同一五字段合同:安全上下文、候选数量、候选就绪、当前选中和本次点击。来源/路径、服务、最终按钮保护、日期两处同步、CSS 状态、运行时 ID、时间、容量、唯一性、视口命中等检查仍由真实脚本执行,没有改成 Python 猜测或总是成功的布尔值。
+- Python 统一通过 `_control_snapshot` 做精确结构、普通布尔和非负整数验证。日期仍支持零布局的原生链接;时段允许零候选在有界等待内继续读取,重复候选及错误上下文立即失败;已有选中不会重复点击,未选中只点击一次并只读复核。
+- `NATIVE_FINAL_SCRIPT` 直接复用同一时段合同后才临时解锁唯一最终按钮;原提交消耗标记、`finally` 恢复保护、原生监听和后续逐字段请求/回执核验未变。
+- `tools/debug_ita_book_gate.py` 删除对 `_snapshot`、`_require_ready` 及 10 个原子字段的第二次实现,改为调用 `verify_precommit_selection`。调试错误映射跟随现行生产边界,没有在生产中重新加入诊断快照。
+
+没有新增公共生产函数或 Italy 运行时文件,也没有更改 H-04 的传输选择。公共工具仍为 497 行;这次复用发生在已有单文件内部和现有生产校验入口之间,不把网站专属 DOM 搬进公共模块冒充复用。
+
+### 测试迁移与发现的问题
+
+第一轮 228 项目标回归出现 **1 个真实失败**:点击处理器使日期漂移后,聚合后的 `selected` 一度未绑定同一上下文。修正为 `selected = contextReady && candidateReady && 唯一活动候选` 后,日期漂移和来源漂移都在只读读回中拒绝。第二轮相同 228 项及补充 69 项全部通过。
+
+旧 Mock 中分别改写 21 个内部字段的两组测试合成一组五字段协议/类型测试;不是删除底层场景。实际 Node 脚本仍逐项覆盖不可用/红点、错误时间/容量/ID、额外输入、重复时段、日期/服务/来源漂移、未保护按钮、隐藏/遮挡、禁用日期和错误首选元素;最终提交测试仍验证这些状态不能点击 `Prenota`。因此完整 Italy 数量由 540 变为 539,减少的是一项重复的内部表示测试,不是业务场景。
+
+### 最终验证、行数与结论
+
+仓库根目录执行,Python 命令均使用 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`;全部离线、0 skip:
+
+| 命令 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_calendar_book test.test_ita_calendar_book_flow test.test_ita_booking_final test.test_debug_ita_book_gate -q` | 首轮 exit 1;228 项中 1 个真实漂移失败;修正后 exit 0,228 项通过 |
+| `-m unittest test.test_debug_ita_book test.test_ita_final_attribution test.test_ita_final_evidence test.test_ita_single_file -q` | exit 0;69 项 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py' -q` | exit 0;539 项 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py' -q` | exit 0;324 项 |
+| `tools/debug_ita_query_book.py --offline` | exit 0;74 项;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account -q` | exit 0;27 项 |
+| `py_compile`、生产导入 AST、`git diff --check` | exit 0;生产 `tools.*`/`test.*` 导入为 0;统一控件读取器和时段包装各 1 份 |
+
+实际 **3981 → 3926,净减 55 行**,低于 80–150 行估计;原因是底层 DOM 安全检查和最终同步提交保护均按方案保留。相对 W0 的 Italy 6286 行累计减少 2360 行,距约 1000 行仍差 2926 行;Italy+公共工具为 4423,比 W0 两生产文件 6775 净减 2352 行。Italy SHA-256 为 `e482418ba34f43e27f1ef01c8636b8feca15915f76dbdcfa262e55745509fb83`;公共工具仍为 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`;Book gate 为 `cacecbda506b3f7cebcafaebfc119af1d464c7708e94348b10a1d3020621c15f`。
+
+本子项通过离线行为验收,H-03/H-05/H-10/H-11 增加当前证据;H-04、H-08、RC-01、现场 RC-05/09 仍未通过。没有真实外部操作,没有 Git 提交、推送或部署,用户配置与旧文档删除保持原样。下一步继续审计共用月份捕获/扫描和其他大块生产结构;不能重复精简本批已统一的五字段合同,也不能把 55 行下降当成整体完成。
+
+## 11. Query 传输等价性审计与实施前记录(3795 行)
+
+开始基线:`plugins/ita_plugin.py` 3795 行,SHA-256
+`5e67985329620f016708634144682700611ae7824016d0d7f932bd35ebb7e83e`;
+`utils/plugin_utils.py` 497 行,SHA-256
+`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+引用 T-01/T-02/T-03/T-04/T-06/T-08/T-10/T-11/T-12,
+H-03/H-04/H-05/H-08/H-10/H-11,UT-07/08/09/14/15、IT-01/04/05/06,
+RC-01/02/03/04/07/08/10。本阶段仍只允许本地代码、离线测试和文档;
+没有当轮明确授权时,不访问网站、邮箱、账号池或订单,不发送 OTP、AVANTI 或最终预约,
+也不执行 Git 提交、推送、部署。
+
+### 11.1 审计事实
+
+1. Query 与 Book 已经共用 `_capture_month`、`parse_availability_packet` 和库存模型;
+   `capture_initial_probe` / `capture_next_probe` 只是二行包装。继续在这层重写一套扫描器,
+   预计只能减少几十行,却会扰动已经验证的 Book 新鲜库存、自动时段与月份连续性。
+2. 生产 Query 的 459 行分区包含原生刷新、翻月 DOM、网络监听、响应解析和扫描结果;
+   其中只有“只读月份请求”有可能由现有公共 `perform_browser_fetch` 取代。
+   `utils/network_interceptor.py` 会暂停/修改请求,不是被动读取能力,仍不适用。
+3. 历史证据已经确认网站使用
+   `POST /BookingCalendar/RetrieveCalendarAvailability`,JSON 参数为 `_Servizio` 与
+   `selectedDay`,响应是双重 JSON;但历史原生网络观察不能证明主动 browser-fetch
+   在认证、Cloudflare、月份锚点和返回语义上等价。
+4. Book 仍依赖页面产生的自动时段、日期/时段 DOM 选中以及最终原生点击。
+   即使 H-04 对 Query 通过,也不能据此把 Book 改成跨账号复用 Query 响应,
+   更不能把 `InsertNewBooking` 改为 HTTP 重放。
+
+### 11.2 调整后的方案
+
+- 不为追求数字强拆已经共用的月份读取器;先给现有日历调试入口增加一个**只读对照模式**。
+- 对照必须在同一已认证 Query 会话、同一运行时服务、同一月份内取得:
+  一份由网站原生动作产生,一份由公共 `perform_browser_fetch` 产生。
+- 两份结果都经过同一个 `parse_calendar_availability` 解析,比较月份、完整日期集合、
+  `SlotLiberi` / `SlotRimanenti` 及错误分类;只输出脱敏摘要,不输出 Cookie、验证码、
+  runtime ID 或原始响应正文。
+- 对照入口默认关闭,且必须证明 `otpRequests=0`、`avantiPosts=0`、
+  `finalRequests=0` 的增量;任何认证跳转、403/429、结构差异、月份差异或超时都判失败。
+- 在获得现场授权且至少覆盖一个无号月、一个正向月、认证失效分支之前,
+  H-04 保持“待验证”,生产 Query 继续使用当前浏览器原生路径。
+- H-04 通过后,才单独记录生产改造:Query 用公共 browser-fetch 逐月读;
+  Book 保留申请人会话的原生重查和交互。预计届时可删除 Query 专属翻月监听与相关诊断,
+  实际净减量由实现后统计,不预先冒充完成。
+
+### 11.3 本地开发与测试范围
+
+文件范围限定为已有 `tools/debug_ita_calendar_gate.py`、对应调试测试和本记录;
+若公共 `perform_browser_fetch` 的现有返回合同已经够用,不修改公共模块。
+离线测试至少覆盖:参数严格构造、同一解析器、正向/空月一致、日期或容量不一致、
+认证/限流/权限/临时错误、原始正文不进入日志、零 OTP/AVANTI/final 副作用以及默认不开启。
+本阶段不改变 `plugins/ita_plugin.py` 的生产传输,也不把探针代码搬进插件。
+
+### 11.4 本地实现与结果
+
+已在现有 `tools/debug_ita_calendar_gate.py` 增加显式
+`ITA_QCAL_MODE=transport_compare`,默认模式仍是 `discovery_horizon`。
+探针先捕获网站原生月份响应,再把原请求的两个严格字段交给现有公共
+`perform_browser_fetch`;候选响应复用生产 `parse_calendar_availability`,并逐项比较
+`CalendarDay`。状态 401/403/429/0/408/502/503/504、错误来源/路径、未知正文和库存差异
+均用固定、脱敏错误拒绝。报告只含月份、天数、正向天数和请求计数;不含服务 ID、
+请求/响应正文、Cookie 或 OTP。
+
+`scan_calendar_horizon` 只新增可选只读观察回调;未配置时行为不变。对照报告要求每个月
+恰好一份原生请求和一份 browser-fetch 请求,且对照阶段 OTP/AVANTI/final 增量均为 0。
+只有同时观察到至少一个空月和一个正向月才把现场覆盖标为完整;库存一致但样本不全时
+退出码为 2,不伪装为 H-04 已通过。
+
+本地验证全部 exit 0、0 skip:
+
+| 命令 | 结果 |
+| --- | --- |
+| `-m unittest test.test_debug_ita_calendar_gate -q` | 43 项 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py' -q` | 330 项 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py' -q` | 535 项 |
+| `tools/debug_ita_query_book.py --offline` | 74 项;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account -q` | 27 项 |
+| `py_compile`、`git diff --check` | exit 0 |
+
+本阶段没有改生产插件:Italy 仍为 3795 行、指纹仍为
+`5e67985329620f016708634144682700611ae7824016d0d7f932bd35ebb7e83e`;公共工具仍为
+497 行、指纹仍为
+`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+调试工具为 1706 行,指纹
+`3f6acb43e3f1e4df88917053bbe9c783f8bd5fcff6fddc3931b353a2bb6794f9`;
+对应测试为 1613 行,指纹
+`4da3e3a3905b5b230c083cd134639902030c3f04e83e0c5328728221992602f2`。
+
+H-04 现在是“探针与离线错误边界已就绪,现场等价性待验证”,不是通过;生产 Query
+仍走原生浏览器月份路径。没有访问真实网站、邮箱、账号池或订单,没有发送 OTP/AVANTI/
+最终预约,没有 Git 提交、推送或部署;用户配置修改和旧文档删除保持原样。
+
+## 12. 日历原生适配层结构收敛(实施前,3685 行)
+
+开始基线:`plugins/ita_plugin.py` 3685 行,SHA-256
+`c35317dcaaec63ef18e5bd26a130196cbb106e1b57f954d789313bd310d22009`;
+`utils/plugin_utils.py` 497 行,SHA-256
+`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+引用 T-01/T-02/T-03/T-04/T-06/T-08/T-09/T-10/T-11/T-12,
+H-03/H-04/H-05/H-08/H-10/H-11,UT-07/08/09/10/11/12/14/15、
+IT-01/02/03/04/05/06,RC-01/02/03/04/05/07/08/10。本批只允许本地代码、
+离线测试和文档;不访问真实网站、邮箱、账号池或订单,不发送 OTP、AVANTI 或最终预约,
+不执行 Git 提交、推送或部署,并保留用户现有配置修改和旧文档删除。
+
+### 12.1 调用图与复用结论
+
+1. 复杂度扫描没有在 Italy 业务代码中发现需要优先处理的算法级热点;问题是
+   `CALENDAR_QUERY`、`CALENDAR_BOOK` 两个分区对同一页面事实建立了多套命令、快照、
+   包装和异常翻译。因而本批按调用图和分区体积排序,不优化无关的宿主 Booker 循环。
+2. 浏览器启动、严格清理、日期工具、登录调度和浏览器内 Fetch 已分别复用
+   `init_chromium_options`、`cleanup_browser_workspace`、`filter_dates_in_range`、`BaseFlow`
+   与 `perform_browser_fetch`。后者在 H-04 现场等价性通过前不能接管生产月份读取;
+   不能为了减行把传输方式变化伪装成普通重构。
+3. `CALENDAR_GUARD_SCRIPT`、`NEXT_MONTH_CONTROL_SCRIPT`、`RUNTIME_SERVICE_SCRIPT`、
+   `DATE_SELECTION_SCRIPT`、`SLOT_SELECTION_SCRIPT` 都在重复检查同源 Calendar、唯一控件、
+   可见/禁用状态和最终按钮保护;Python 又分别使用
+   `validate_next_month_snapshot`、`_control_snapshot`、`_date_snapshot`、`_slot_snapshot`
+   解释相近结果。
+4. `parse_availability_packet`、`parse_book_time_slots`、`_post_body`、`_require_packet_tab`
+   重复验证同源、POST、当前标签页、状态码和 JSON body;业务差异仅是 endpoint、字段集合及
+   响应解析函数。
+5. Query 与 Book 已经共用 `_capture_month`,但其内部仍同时承担监听、通用包校验、
+   Book 自动日时段捕获和业务一致性检查。应收敛其底层适配器,保留 Query/Book 两个业务循环,
+   而不是再新建一套通用预约框架或把 Prenot@Mi 选择器搬进公共模块。
+
+### 12.2 本批改法与不变边界
+
+- 在单文件内用一个日历 DOM 命令脚本和一个严格结果读取器承载 `guard/service/next/date/slot`
+  五种网站动作;保留旧常量别名仅用于支持工具迁移时,最终生产调用只能有一个实现来源。
+- 用一个原生 POST 包读取/校验原语统一来源、方法、标签页、HTTP 分类和 JSON body;
+  Availability 与 TimeSlots 继续调用各自已有纯解析函数并核对月份、服务和日期。
+- Query 仍逐月升序、首个正向月份停止并返回最早日期;Book 仍在申请人会话重新扫描、
+  优先尝试 Query 提示日期、失败后从锚点重新捕获并按日期/时段升序选择。
+- 最终按钮在整个扫描和任何异常出口都保持禁用;日期/时段只允许一次原生点击并做只读读回;
+  当前账号、路由、标签页、运行时服务、库存、ID、日期、时间和容量检查不得删除。
+- 不改变 OTP、AVANTI、最终提交、回执归属、未知结果不重试、配置字段或热更新单文件合同;
+  不增加 Italy 私有运行时文件,也不向公共模块放入只有 Italy 一个消费者的网站代码。
+- 预计生产净减 180–320 行。若只能通过压缩排版、放松错误分类或删除业务断言达到估计,
+  本批应如实低于估计,不采用这些手段。
+
+### 12.3 测试与准出
+
+修改前后必须运行日历 Query、Book、最终提交、恢复、单文件热更新和真实 JS harness 的定向集合,
+再运行完整 Italy、完整调试、本地 Query→Book 离线串联与配置/账号套件。旧测试若只绑定被合并的
+私有快照字段,可迁到统一命令合同;月份连续、错误来源/状态、延迟控件、零/重复候选、上下文漂移、
+一次点击、最终零请求、申请人重查和未知提交等业务断言不得删除或跳过。结束记录必须给出精确命令、
+首轮失败、修正、测试数量、行数、生产净变化、源码指纹及 H/RC 状态。H-04 仍保持现场待验证;
+本批离线通过不等于真实预约或整体发布准出。
+
+## 13. 日历原生适配层结果:3566 行
+
+### 13.1 实际实现
+
+- Availability 请求现在把已验证的运行时服务直接绑定到 `CalendarProbeResult`;Book 月份捕获
+  不再第二次解析同一个 POST body,也不再在 `_CapturedMonth` 保存一份重复服务字段。
+- Query/Book 共用 `_json_request_body` 做严格 JSON 与精确字段集合校验;TimeSlots 继续核对
+  endpoint、POST、状态、当前服务、目标日期及响应内每个时段,没有把原始正文写入错误。
+- 日期与时段脚本由一份选择上下文生成,保留两个固定操作入口;服务、日期双选中、唯一候选、
+  CSS 可用性、ID、时间、容量、一次点击和只读读回均未删。next-month 仍是独立脚本,避免其
+  静态包含日期、时段或最终操作。
+- 月份捕获去掉重复 body/状态分支后仍支持 TimeSlots 先于 Availability 返回、空月份不等待
+  不存在的自动时段、正向月份必须同时捕获自动日时段、跨月服务和月份连续性不变。
+- Book 选择和双遍扫描移除嵌套包装,但仍保留 Query 提示日期优先、失败后从原生锚点刷新、
+  全范围升序回退、申请人/标签页/服务复核以及所有出口的最终按钮保护。
+- 公共能力审计没有发现可安全替代上述 Prenot@Mi DOM 语义的现成函数;公共
+  `perform_browser_fetch` 仍只用于默认关闭的 H-04 对照探针,生产传输没有切换。
+
+### 13.2 发现并修正的问题
+
+第一轮 Query/门禁 76 项出现 2 个失败:精简 `CalendarProbeResult` 时,空月份不再主动读取
+`selected_month`,导致非法 `selectedDay` 可在空数组场景绕过。恢复构造时的月份解析后,
+同组 76 项通过。这是测试发现的真实输入边界,未通过修改测试放行。
+
+完整调试首轮 330 项出现 1 个失败:生产已由共享 request formatter 生成
+`Book TimeSlots request fields changed`,旧调试测试却要求该完整字符串必须静态出现在源文件。
+该断言迁到共享 formatter 事实,实际错误字段、额外字段及敏感正文不泄露仍由
+`BookPacketTests` 逐包执行验证;生产消息与调试映射没有改变。修正后完整调试 330 项通过。
+
+### 13.3 验证、行数与结论
+
+仓库根目录执行;Python 命令均使用
+`PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。全部为离线测试、0 skip;测试组有交集,
+不累加为独立总数:
+
+| 命令 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_calendar_query test.test_ita_calendar_book test.test_ita_calendar_book_flow test.test_ita_booking_final test.test_ita_query_recovery test.test_ita_single_file -q` | 修改前 exit 0;189 项 |
+| Query/日历/门禁定向集合 | 首轮 76 项中 2 failures;修正后 76 项通过;扩大后 178 项通过 |
+| Book/最终定向集合 | exit 0;152 项 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py' -q` | exit 0;535 项 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py' -q` | 首轮 330 项中 1 failure;迁移静态断言后 exit 0,330 项通过 |
+| `tools/debug_ita_query_book.py --offline` | exit 0;74 项;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account -q` | exit 0;27 项 |
+| `py_compile`、`git diff --check` | exit 0 |
+
+实际 **3685 → 3566,净减 119 行**,低于 180–320 行估计;`CALENDAR_QUERY`
+456 → 385,`CALENDAR_BOOK` 630 → 588。差值没有用压缩排版补足:最终按钮、DOM 读回、
+月份/服务连续性与申请人会话检查均按方案保留。公共工具仍为 497 行且未修改;相对 W0 的
+Italy 6286 行累计减少 2720 行,距约 1000 行仍差 2566 行。Italy SHA-256 为
+`4dcacf211125145b73916ec7c4922072fec4824c179fb16bd4fcaea9bc61eebf`;公共工具仍为
+`dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+本子项离线通过,H-03/H-05/H-10/H-11 增加证据;H-04/H-08、RC-01、现场 RC-05/09
+和整体 RC-10 仍未通过。没有访问真实网站、邮箱、账号池或订单,没有发送 OTP、AVANTI
+或最终预约,没有 Git 提交、推送或部署;用户配置修改和旧文档删除保持原样。下一步必须
+转向 `PLUGIN` 766 行或最终交易/回执总计 770 行的整块调用链,不再反复整理本批已统一的
+日历请求和选择适配层。
+
+## 14. R2 月份扫描与候选状态收敛(实施前,2883 行)
+
+开始基线:`plugins/ita_plugin.py` 2883 行,SHA-256
+`f3d3fbd013e5e311d31162bad86d2d699640f949681dc90aa129b6d5a3d05c11`。
+引用 T-03/T-04/T-08,H-03/H-05,UT-07/08/09/10/11,IT-01/02/04,
+RC-03/04。本批只做本地代码、测试、工具消费者和文档;不访问真实网站、邮箱、账号池或
+订单,不发送 OTP、AVANTI 或最终预约,不执行 Git 提交、推送或部署,并保护用户现有配置、
+旧文档删除和其他未提交改动。
+
+### 14.1 当前事实与需要纠正的语义
+
+1. Query 和 Book 已共用 `_capture_month` 与同一 Availability 解析边界,但 Query 仍通过
+   `capture_initial_probe`、`capture_next_probe`、`CalendarQueryScanResult` 维护一套月份包装;
+   Book 又通过 `_CapturedMonth`、嵌套 `capture`/`positive_days` 和双遍扫描维护另一套状态。
+   这些对象多数是迁移期诊断表示,不是 Prenot@Mi 必需协议。
+2. 现有 `preferred_day` 分支会先跳到 Query 提示月份,若提示日期仍有号就直接选择,即使申请人
+   会话里存在更早日期。提示日期售罄后还会刷新并从锚点重扫。它既增加重复请求和状态,又与
+   T-04 已确定的“Book 在申请人当前库存内按日期、时段升序选择”冲突。
+3. Query 信号的职责是告诉 Booker 值得唤醒申请人任务,不是替申请人锁定日期、时段或运行时 ID。
+   Book 必须在自己的账号、标签页和服务上下文重新读取库存;因此提示日期只能是诊断信息,不能
+   改变最终选择顺序。
+4. 月份连续性、同源/POST/当前标签页/服务校验、自动 TimeSlots 与 Availability 的一致性、
+   日期售罄回退、原生一次选择和只读读回仍是网站真实边界,不能为了行数删除或搬到公共模块。
+
+### 14.2 本批改法与不变边界
+
+- 删除 Query 两个二行捕获包装和 Book 的提示日期优先双扫描;Query/Book 都直接消费同一月份
+  捕获结果并按连续月份前进。
+- 合并仅用于传递月份探针、自动日和自动时段的中间状态;诊断所需的扫描月数、停止原因和最早
+  日期从一个最小结果中派生,不在插件保存第二份可变候选状态。
+- Query 仍从当前月逐月升序,在首个正向月份停止并发布其中最早日期;完整负向范围才返回无号。
+- Book 忽略 Query 提示日期的选择优先级,在申请人会话按配置日期范围、日期升序、时段升序扫描;
+  某天在 TimeSlots 重查时售罄则尝试下一个日期,不复用 Query 的 Cookie、响应或 runtime ID。
+- 继续保留 `CalendarProbeResult` 作为外部网站响应的严格、不可变边界,除非消费者审计证明可在
+  不重复解析和不放松月份校验的前提下删除;不以 tuple 魔法位置或压缩排版换取表面行数。
+- 不改变表单、OTP、Turnstile、AVANTI、R3 最终一次点击/普通失败合同、公共接口或宿主调度。
+
+### 14.3 测试与准出
+
+必须迁移旧私有包装测试到业务事实:首个正向月停止、完整负向范围、跨年连续、跳月拒绝、
+Book 申请人库存重查、Query 提示不覆盖更早日期、日期售罄回退、错误标签页/服务/状态拒绝、
+最终请求零增量和一次选择。调试/soak 工具只消费新的最小诊断结果,不得反向要求生产恢复旧包装。
+结束时运行日历 Query/Book、公开插件、恢复、单文件、完整 Italy、完整调试、本地离线串联、
+配置/账号套件、AST/导入检查与 `git diff --check`,并记录首轮失败、修正、行数和源码指纹。
+本批离线通过不代表 H-04 传输等价、真实 OTP/预约或整体发布准出。
+
+## 15. R2 月份扫描与候选状态结果:2823 行
+
+### 15.1 实际实现与语义修正
+
+- Query 删除 `capture_initial_probe` / `capture_next_probe`,直接调用 Book 已在使用的
+  `_capture_month`;月份连续、同源 POST、状态、服务和双重 JSON 仍由同一边界检查。
+- `CalendarQueryScanResult` 与 `_CapturedMonth` 删除。一个不可变 `CalendarProbeResult`
+  同时承载月份库存及 Book 当前页面自然产生的自动日/时段;Query 返回不可变月份元组,
+  不再把相同事实包装成三层对象。
+- Book 删除 `preferred_day` 及“跳到 Query 日期→尝试→刷新→从锚点重扫”的双遍逻辑。
+  Query 日期只负责让现有 Booker 唤醒申请人任务;Book 始终从申请人当前 Calendar 锚点
+  按用户日期范围、日期升序、时段升序选择。Query 的 Cookie、响应和运行时 ID 均未复用。
+- 日期在 TimeSlots 重查时售罄仍继续下一个候选;自动时段、手动日期点击、当前标签页、
+  申请人/路由、服务、月份、最终按钮保护及只读读回均保留。生产传输没有切换到 HTTP,
+  表单、OTP、Turnstile、AVANTI 和 R3 最终提交合同未改变。
+
+第一轮 Query/Book 定向 68 项出现 1 个旧断言失败:测试仍要求 Book 对同一个月份捕获两次。
+断言迁为 Query 两个月、Book 一个月后,169 项扩大回归通过。随后删除两个结果层后,日历、
+插件与调试定向 286 项通过。旧的四项提示日期分支测试和一项 fallback-anchor 测试已被一个
+申请人顺序扫描测试及现有公开 `book()` 的“较晚 Query 信号不能覆盖更早申请人库存”集成断言
+取代;Italy 总数 389 → 385 是删除失效私有策略测试,不是删除账号隔离、库存重查或售罄回退。
+
+### 15.2 最终验证、行数与结论
+
+仓库根目录执行;Python 命令均使用 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。
+全部为离线测试、0 skip;套件有交集,不累加成独立总数:
+
+| 命令 | 结果 |
+| --- | --- |
+| 日历 Query/Book 首轮定向 | 首轮 68 项中 1 failure;迁移双捕获旧断言后通过 |
+| 日历、插件、生产 Query gate、soak、串联定向 | exit 0;286 项 |
+| `-m unittest discover -s test -t . -p 'test_ita*.py' -q` | exit 0;385 项 |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py' -q` | exit 0;280 项;仅既有 Redis `setex` 弃用警告 |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account -q` | exit 0;27 项 |
+| 5 个核心文件 AST、生产禁止导入 `tools.*`/`test.*`、`git diff --check` | exit 0 |
+
+实际 **2883 → 2823,净减 60 行**;Query 分区 **385 → 362**,Book 分区
+**588 → 551**。减量低于“大幅压缩”预期,原因是 R2 已有的共用请求解析和 DOM 选择本来就是真实
+网站边界;本批没有删除这些检查或以位置 tuple 取代命名输入。Italy SHA-256 为
+`91acff67527b6a4d3c8775ada88b8855f64191f90a11f03142a7544c1eb276ca`,距约 1000 行仍差
+1823 行。H-03/H-05、UT-09/10/11、IT-01/02、RC-03/04 增加当前离线证据;H-04/H-08、
+RC-01、现场 RC-05/09 和整体 RC-10 仍未通过。
+
+没有访问网站、邮箱、账号池或订单,没有发送 OTP、AVANTI 或最终预约,没有 Git 提交、
+推送或部署;用户配置修改、旧文档删除及其他工作区改动保持原样。R2 完成,下一包按计划进入
+R4 表单/OTP/Turnstile 准备链,不能继续在已统一的月份对象上做低收益微调。

+ 425 - 0
docs/italy-refactor/records/W4-selection-readback.md

@@ -0,0 +1,425 @@
+# W4:Book 入口、选中与诊断收敛
+
+日期:2026-09-01;状态:选中读回、库存复用、Book 入口和 R3 薄最终提交子项离线通过;不代表 W4 整体或现场最终提交验收完成。第 1–16 节为 CR-001 前历史,第 17–18 节为当前提交语义。
+
+依据 T-04/T-09/T-12、H-05/H-07/H-08/H-11、UT-10/11/12、RC-04/05/08/10。配套:[技术方案](../01-technical-design.md)、[测试计划](../04-test-plan.md)。
+
+第 1–6 节保留早期子项记录;第 7–8 节记录回执模型合并。组合工作区的最新命令、指纹和行数见 [W2 第 11 节](W2-login-preparation.md)。早期子项不依赖共用月份读取,因此提前单独处理;W4 其余前置条件没有据此标为通过。未执行真实预约。
+
+## 1. 删除什么、保留什么
+
+- 删除 `DateSelectionState`、`SlotSelectionState`、`approve_precommit` 及其独占的类型辅助函数。
+- 原流程先校验页面快照,再转成两套状态对象,再进行同样检查;现在直接在实际 DOM 读回边界比较业务字段。
+- `_snapshot` 仍验证键、布尔值、真正的整数及日期列表类型;`_require_ready` 仍检查当前服务、日期唯一性、时间线/内容一致性及最终提交保护。
+- `_approve_selection_snapshot` 保留库存为正、日期相同、选中时段唯一、运行时 ID/时间/容量一致、不可用 CSS/红点拒绝以及读回不得点击。
+- `PrecommitApproval` 仍承载当前已核对的日期和时段,不能被解释为锁号或预约成功;最终提交和回执核验没有在本子项中重写或删掉。
+
+相关代码仍全部在 `plugins/ita_plugin.py`。没有把 Italy 状态对象下沉公共模块,也没有复制一套新协议。
+
+## 2. 测试迁移证据
+
+原 `test/test_ita_protocol.py` 中 6 项仅经中间状态对象执行的检查,迁移为 `test/test_ita_calendar_book.py` 的 7 项 `PrecommitReadbackTests`:
+
+- 正向库存与最后一位可用名额;负库存及日期/时段库存不一致。
+- 日期缺失、重复或不一致,日期被标记不可用。
+- 时段数量、ID、时间、余量或 CSS/红点冲突。
+- 布尔伪整数、错误计数类型及日期列表类型。
+- 所有读回成功/失败场景都不产生选择点击;运行时 ID 不进入对象展示。
+
+迁移测试调用真实 `verify_precommit_selection` 和解析函数,只模拟浏览器边界,不重新实现业务校验。相关 191 项定向测试 exit 0、0 skip,命令及当前指纹见 [W3 全量记录](W3-query-entry.md)。
+
+全量调试套件另有 1 项旧诊断白名单测试失败;旧文案生产者已删除但工具映射未同步。因此定向通过不等于消费者迁移完成,H-11/RC-08 仍未通过。
+
+## 3. 当时发现的方案差异与后续
+
+当前 `available_slot_candidates` 排序为 `(日期, -余量, 开始时间, 结束时间)`;[技术方案第 7 节](../01-technical-design.md) 规定默认日期、时段升序。该差异尚未修复,不能写成既有行为完全符合方案。W4 实施前须明确排序迁移,补充“同一天较晚时段余量更多”的用例,保留库存及日期范围约束;不得反过来修改方案掩盖现状。
+
+后续仍须合并重复的日历/时段解析、当前用户库存重查、最终提交和回执层;保留 T-09 的一次提交、未知结果暂停和归属核验。尚无证据证明约 1000 行目标成立,也没有新版本真实 Book 成功证据。
+
+## 4. 后续执行:一次解析、按时间选择及独立会话
+
+依据 T-02/T-04/T-08/T-09/T-12、H-03/H-05/H-08/H-11、UT-07/08/10/11、RC-02/04/05/08/10。生产及测试与 W3 共用一个工作区,精确命令、5334 行分区预算和指纹统一见 [W3 第 6 节](W3-query-entry.md),不重复统计成两份减行成绩。
+
+- **排序差异已修复**:采用现有公共 `filter_dates_in_range(shuffle=False)`,候选按日期/时段升序。同日较晚时段即使余量更多,也不会越过较早时间;协议测试和实际选择器测试均有明确断言。
+- **重复解析已移除**:`_capture_month` 捕获后解析;`_try_day` 和 `select_slot_before_final` 接收同一份已解析库存。新增用例分别覆盖网站自动选中的日期和主动日期点击,解析次数等于捕获请求次数,不在选择阶段重解四遍。
+- **读回仍是业务边界**:当前用户服务、日期、时段 ID、时间、余量、不可用标记及点击次数核对保留;将旧 `clicked` 文案映射迁移到现有错误,不删除只读行为测试。
+- **独立账号仍重查**:Query 与 Book 共用函数而不是共享会话;真实公开接口串联用例验证申请人侧旧日期售罄后的下一候选,并断言没有最终预约请求。
+
+当前 Italy 534 项、调试 313 项、框架离线入口 75 项通过,原 7 项迁移错误已修复;旧文档命令依赖仍失败。预提交结果仍为 `success=false`,未用选中成功代替预约成功。最终提交/回执 1189 行在本批没有缩减或删去业务核验,W4 整体及 RC-09 仍未完成。
+
+## 5. Book 入口与诊断职责收敛
+
+范围:T-02/T-04/T-08/T-09/T-10/T-12,H-03/H-06/H-07/H-08/H-11,UT-10/11/12/13、IT-02/03/05、RC-04/05/08/10。先合并 Book 重复入口,再迁移仅用于排障的采集代码及其工具/测试消费者;不改邮箱服务、账号池、最终提交次数或公共插件接口,不进行真实网站操作。
+
+已将全局 `book`、`_book_discovery_or_prepared`、`_book_prepared_calendar` 三层转发收进公开 `ItaPlugin.book`:路由只解析一次,保留申请人会话绑定、准备、独立库存重查、预提交与最终提交分支。Italy 从 5334 行降至 5290 行。该中间点的插件/工作流/日历 Book/最终提交/回执读取/归属核验 265 项定向测试通过;当时尚未执行全量消费者回归,不作为整体完成证据。
+
+阶段中间点:已将表单字段清单和日期格式诊断原样迁移到现有 `tools/debug_ita_query.py`、`tools/debug_ita_reservation.py`;合并表单诊断重复的脱敏器。生产中保留真实表单边界检查与回执解析,删除 `last_booking_form_structure` 私有诊断缓存,并迁移工具和测试消费者。5113 行时 Italy 534 项、调试 315 项通过。热更新测试不再依赖旧的全局 `book` 转发,而是验证上传文件的公开 Book 调用上传文件自己的库存重查;旧表单诊断脱敏/错误路径测试保留在调试测试中。
+
+接着收敛两处重复职责:扫描终止结果由已验证的有界扫描器生成,取消结果对象内第二套扫描过程校验和可传入的停止原因;表单等待复用同一校验器的显式 `allow_pending` 参数,不再复制并改写快照后校验。等待仅允许验证码控件就绪状态暂时变化,不放松表单、必填项、OTP 是否存在或类型校验。最终代码的完整离线回归见下节。
+
+## 6. 历史验证、预算与未完成事项(5058 行)
+
+### 业务断言及消费者迁移
+
+| 改动 | 保留的行为与测试去向 |
+| --- | --- |
+| Book 入口收敛 | `test_ita_plugin`、`test_ita_workflow`、`test_ita_calendar_book_flow` 继续验证用户库存重查、会话隔离、选中前/后失败、预提交为假、最终开关及未知结果暂停 |
+| 表单诊断迁入 `debug_ita_query` | 复用该工具已有脱敏器;原字段值/额外字段不得泄露和错误元数据路径断言迁入 `test_debug_ita_query`。生产测试改查实际页面路径与零诊断采集;真正的表单边界/必填/字段同步仍由 `test_ita_preflight` 执行真实 JS 验证 |
+| 日期格式诊断迁入 `debug_ita_reservation` | `test_ita_reservation` 与 `test_debug_ita_reservation` 仅改诊断导入来源,隐藏节点、未知文案、截断、上下文、不得初始化 DataTables 或读申请人列的原断言保留;生产回执读取仍在插件内 |
+| 扫描结果由过程生成 | `test_ita_calendar_query` 继续调用真实扫描器,验证初始正向、顺序/跨年、越月拒绝、首正向即停、提前终止不报无号;调试夹具不再传入可伪造的停止原因 |
+| 等待校验合一 | `test_ita_preflight` 新增两项,验证 `allow_pending` 不改写原快照、不放松其他字段,且必须为真正布尔值;原 OTP 冷却、值存在、严格计数等场景保留 |
+| 单文件加载/热更新 | `test_ita_single_file` 改查公开 Book 与上传文件自身的库存重查绑定,并验证热更新替换方法、旧实例保持旧代码、进程 OTP 锁连续;不以旧全局转发函数存在作为成功标准 |
+
+### 最终代码上的命令
+
+工作目录为仓库根目录;Python 前缀统一为 `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B`。
+
+| 命令后缀 | 结果 |
+| --- | --- |
+| `-m unittest test.test_ita_calendar_query test.test_ita_preflight test.test_debug_ita_calendar_gate test.test_debug_ita_production_query_gate test.test_ita_calendar_soak test.test_ita_workflow` | exit 0;199 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_ita*.py'` | exit 0;536 项,0 skip |
+| `-m unittest discover -s test -t . -p 'test_debug_ita*.py'` | exit 0;315 项,0 skip |
+| `tools/debug_ita_query_book.py --offline` | exit 0;75 项,0 skip;`liveAcceptance=false` |
+| `-m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 1;26 项,1 failure、9 error 记录,0 skip;依赖用户已删除的 `docs/ita_query_book_acceptance.md`,仍按 W5 迁移,不恢复旧文件或跳过测试 |
+| `git diff --check`(无 Python 前缀) | exit 0 |
+
+各套件有交集,不累加为独立测试总数。中间热更新测试曾因旧全局 `book` 和不完整会话夹具失败,已迁移到真正公开接口并补齐合成会话身份;最终全量通过。外部网站、邮箱、云端订单、真实预约均未调用。未修改用户配置或已删除文档,没有 Git 提交、推送或部署。
+
+### 行数与指纹
+
+HEAD:`a22596f1fcdffb946960724ef299f249e7860891`。Italy 5334 → 5058,本批净减 276 行;相对 6286 基线减 1228 行。公共模块仍 497 行,相对 W0 的 489 行净增 8 行,本批公共模块零新增改动。两个生产文件合计 5555 行,相对基线 6775 行净减 1220 行;调试代码、测试和文档另计,不能把诊断迁移说成全仓删除同等代码。
+
+按同一机械分区边界统计,包含空行、注释和内嵌 JS:
+
+| 分区 | 当前行数 | 方案预算 | 尚未完成的工作 |
+| --- | ---: | ---: | --- |
+| 配置/协议/模型 | 677 | 140 | 配置入口和基础校验仍有重复 |
+| Query/Book 日历 | 1241 | 180 | 共用捕获已实现;浏览器导航与选择层仍重 |
+| 最终提交/预约记录/回执 | 1111 | 200 | 本批只迁出 78 行日期诊断,核心提交/归属对象尚未精简 |
+| 表单/OTP/验证/工作流 | 921 | 240 | 已合并 Book 转发和等待校验,准备状态仍待收敛 |
+| 插件入口/登录/会话/清理 | 1099 | 220 | 诊断已部分移出,会话表示仍重 |
+| 文件组织 | 9 | 20 | 不以压缩排版达标 |
+| 合计 | 5058 | 1000 | 距预算仍差 4058 行;H-08 未通过 |
+
+SHA-256:Italy `7168b7b62eb6897119684ce8d59c940d7f3d90a38324b80d8465f19bfba903f0`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+结论:本批代码/消费者离线回归通过,W4 整体仍部分完成。下一步优先精简准备/配置和实际提交/回执对象层;旧文档命令消费者继续列入 W5。H-04 HTTP 等价、新实现真实预约与宿主公共 API 部署前置条件均未据此通过,约 1000 行目标没有放宽。
+
+## 7. 回执模型合并:实施范围
+
+依据 T-01/T-04/T-09/T-10/T-12、H-05/H-07、UT-12/13、IT-02/03/04、RC-02/05/08。本轮已获目标续作授权,仅修改本地实现与离线测试,不执行真实网站、邮箱、预约、Git 提交或部署。
+
+开始时 Italy 5058 行。源码显示列表、详情和最终归属层维护三套回执模型;最后一套还兼容网站并不提供的 `service_id`/选中区间字段,并用指纹重新保存被丢弃的详情事实。计划让列表、详情及最终核验共用实际回执字段,保留全部历史事实作直接比较,将本次已观察提交证据放在会话快照上,删除虚构字段的兼容分支与重复转换。原生提交、请求核对、账号绑定、完整覆盖、未知暂停均保留。
+
+修改位置:`plugins/ita_plugin.py` 的回执模型、解析、读取和最终核验;原 `test/test_ita_booking_final.py` 的合成模型夹具迁往真实回执字段,相关 read-port/归属测试及 `tools/ita_final_evidence.py` 同步。沿用现成公共结果/异常和已验证 DOM 读取,不新建公共模块或 Italy 私有运行时。预期此模型合并减少约 100–200 行,再根据实际分区继续精简;不是总预算达标。
+
+改动前命令:`PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_booking_final test.test_ita_final_read_port test.test_ita_final_attribution test.test_ita_reservation`,exit 0,131 项通过、0 skip。实际改动后的结果另行补充,不能继承此基线。
+
+## 8. 回执模型合并结果
+
+已合并列表、详情与最终核验使用的回执模型为 `ReservationRecord`,只保留真实观察字段:预约号、领馆、服务名、日期、分配时间、状态、详情路径及详情中的预约类型/状态码。历史记录直接比较这些事实,不再先丢弃字段又计算指纹;本次原生提交证据只在 `ReservationSnapshot` 保存一份。
+
+`FinalReceiptReadPort` 继续核对列表与详情、完整覆盖、用户/会话/标签页、目标服务与日期;最终核验继续接受选定区间内的真实分配时间。该历史中间点的 `VerifiedSubmission` 来自严格核对过的原生请求,并另外依赖生产内的恰好一次请求审计;后续第 11–12 节已按 T-10 把整页计数迁到调试/发布门禁,原生请求证明本身仍保留。拒绝、丢包、未知响应、历史变化和重复调用始终不能触发第二次提交。
+
+| 原业务断言/消费者 | 迁移方式 |
+| --- | --- |
+| `test_ita_booking_final` 的合成回执 | 使用实际详情字段和快照级原生提交证明;缺字段、错误服务/日期/时间、无请求证明、历史变化、未知暂停和至多一次断言保留 |
+| 旧合成模型的“其他服务活动记录不算目标预约” | 保留“新记录属于其他服务不能报告目标成功”;另补已有其他服务活动预约必须在提交前停止。真实 read-port 原本已拒绝所有活动基线,原合成对象不能代表网站层会放行 |
+| `test_ita_final_read_port` / `test_ita_final_attribution` | 验证真实字段不被丢弃、虚构 service ID/区间/指纹字段消失、本轮证明绑定快照;错误归属及历史完整性仍验证实际解析与读取 |
+| `tools/ita_final_evidence.py` | 使用同一列表/详情一致性检查,直接比较完整历史记录;不再依赖已删除的指纹转换函数 |
+
+此模型合并实际为 **5058 → 4974,净减 84 行**,小于开始时估计的 100–200 行,按实际结果记账。没有新增公共或 Italy 私有运行时模块。该中间点相同定向命令为 132 项通过,新增 1 项;完整 Italy 537 项通过,均 exit 0、0 skip。随后继续了 W2 的解析/文件组织,不能用中间点测试替代最后一次回归;4572 行及 4483 行历史工作区分别见 W2 第 7/9 节,4339 行历史快照见 W3 第 8 节,当前 4289 行工作区及最新回归见 W2 第 11 节。
+
+H-07 的此次对象合并离线场景有证据,W4 整体仍部分完成;真实预约成功与约 1000 行目标均未完成。没有真实请求、Git 提交/推送或部署。
+
+## 9. 回执单源化:实施前记录
+
+依据 T-01/T-04/T-09/T-10/T-12、H-05/H-07/H-08/H-11、UT-12/13、IT-02/03/04、RC-01/02/05/08/10。当前 Italy 4289 行;最终提交、预约记录和回执分区仍约 951 行。用户要求质量对齐 VFS/TLS/BLS,而不是在生产插件保留一套只为协议发掘服务的详情页审计系统。
+
+### 代码事实与取舍
+
+现有生产成功判断同时依赖:原生最终 POST 的精确请求匹配、预约列表稳定读取、逐条打开详情页、列表/详情交叉匹配、再回到列表复读。详情页只额外提供预约类型和状态码;单人类型已在 AVANTI 前由当前表单配置/DOM 校验,预约列表本身已经在当前申请人会话内提供预约号、领馆、服务、日期、时间和状态。技术方案第 7 节要求核验的申请人会话、服务、日期、时间与预约号均可由“当前会话+严格列表结构+匹配过的唯一原生请求+唯一新增确认记录”覆盖,不要求生产逐条打开详情页。
+
+本批采用一个生产事实源:
+
+1. 提交前与提交后都用现有只读 `read_reservation_listing()` 做两次稳定 DOM 读取;它仍验证认证页面、DataTables 完整覆盖、无搜索/分页遗漏、字段长度、唯一预约号/详情路径、日期/时间/状态和上下文不变。
+2. `FinalReceiptReadPort` 仍创建并只关闭自己拥有的同浏览器标签页,绑定申请人、会话、路由、日历预提交和原生请求证明;但每次只进入 `/Reservation` 一次,不再逐条进入详情页或再实现一套历史稳定检查。
+3. 成功仍要求:基线没有活动预约/候补;最终请求恰好一次且请求字段匹配;历史记录未缺失/未变化;恰好新增一条 `Confermata`;服务、日期和分配时间落在选择区间;响应不能明确拒绝。否则进入既有未知结果暂停,不自动重试。
+4. 详情页 DOM/状态码/预约类型采集不是生产 Book 必需条件,迁至现有 `tools/debug_ita_reservation.py` / `tools/ita_final_evidence.py` 的人工诊断边界。调试工具可以保留更深协议观测,但不得参与 `ItaPlugin.book()` 成功判断或成为单文件热更新依赖。
+
+### 预计变化与验证
+
+- 删除插件内 `DETAIL_READ_SCRIPT`、详情解析/读取、`ReceiptObservation` 及 read-port 的逐详情导航;预约记录移除只由详情提供的 `booking_type/status_code`。
+- 保留 `detail_url`,用于列表结构唯一性、人工诊断和真实记录身份;不读取申请人栏、不输出预约号或页面正文。
+- 预计净减 180–300 行;不新增公共模块或 Italy 私有运行时文件。工具代码单独记账,不能冒充生产算法删除。
+- 原生产业务测试迁往列表事实:提交一次、申请人/会话/路由变化、活动基线、历史变化、错误服务/日期/时间、未知状态、明确拒绝、丢包、清理失败及未知不重试必须保留。仅详情 DOM 结构测试迁入调试测试。
+- 定向执行预约解析、最终提交/read-port/归属、工作流、调试证据和热更新;随后执行 Italy 550 项基线、调试 323 项、框架 75 项与配置/账号 27 项完整回归。
+
+本节授权范围仍仅是本地实现、离线测试和文档;不访问真实网站、邮箱、账号池或预约,不提交、推送或部署。若列表事实不能维持 T-09/H-07 的唯一归属与未知暂停,立即回退本批结构,不通过弱化成功条件凑行数。
+
+## 10. 回执单源化结果
+
+### 实际实现与复杂度
+
+- 生产 `ReservationRecord` 现在只表示预约列表能观察到的事实;详情页专属的预约类型和状态码不再进入 `ItaPlugin.book()` 的成功条件。
+- `FinalReceiptReadPort` 每次只创建一个自有标签页、进入一次 `/Reservation`,复用原有稳定双读和严格列表解析。提交前仍拒绝任何活动预约;提交后仍要求精确原生请求证明、原历史不变、恰好一条新活动记录,并核对服务、日期及选中区间内的分配时间。
+- 生产读取从“列表导航+按历史记录逐条详情导航+再次列表读取”的 **O(r) 次浏览器导航**,收敛为 **O(1) 次导航+O(r) 列表解析**;`r` 为当前预约记录数。没有引入缓存或放松分页、等待名单、状态、账号、会话和标签页边界。
+- 详情页脚本、解析器和人工核对留在既有 `tools/debug_ita_reservation.py`;这是协议发掘/诊断能力迁移,不是隐藏 Italy 运行时代码。`tools/ita_final_evidence.py` 改用同一列表事实,不再维护第二套生产匹配器。
+
+实际 **4289 → 4187,净减 102 行**,低于预计的 180–300 行。原因是保留了稳定双读、标签页所有权、清理异常优先级、完整历史对比和未知结果不重试;不通过压排版或删除安全断言补足估算。公共生产工具仍为 497 行,本批没有新增公共 API 或 Italy 私有运行时文件。Italy 相对 W0 的 6286 行基线累计减少 2099 行,距离约 1000 行仍差 3187 行。
+
+### 消费者迁移与失败修正
+
+首轮扩大回归暴露三个旧夹具仍在写入已删除的 `browser.receipts` 详情存根。异常发生在模拟最终请求之后,真实最终核心按设计将其归类为 `unknown_do_not_retry`;没有通过恢复详情读取或把未知改成成功来处理。夹具改为只生成真实预约列表的新确认行后,本地 Query→Book、原 Booker 异步成功上报和最终门禁恢复通过。
+
+| 业务边界 | 当前证据 |
+| --- | --- |
+| 回执解析、最终状态机、read-port、归属与证据工具 | 190 项通过;0 skip |
+| 本地 Query→Book→最终核心 | `LocalFinalTests` 9 项通过;包含确认、拒绝、丢回执、未知响应、清理失败和重启阻断 |
+| 原 Booker 异步成功/暂停/上报失败 | `BookerIntegrationTests` 8 项通过 |
+| 最终门禁及迟到重复请求 | `BookGateFlowTests.test_final_gate_exports_verified_success_and_late_failures_cannot_pass` 通过 |
+| Italy discovery | 551 项通过;0 skip |
+| 调试 discovery | 323 项通过;0 skip |
+| 现有框架离线入口 | 75 项通过;0 skip;`liveAcceptance=false` |
+| 配置/账号 | 27 项通过;0 skip |
+| 静态检查 | 修改文件语法检查及 `git diff --check` 通过 |
+
+测试均使用合成页面、请求、账号和外部边界;没有访问网站、邮箱、云账号池或创建预约。四个完整套件存在交集,不能相加为独立测试总数。
+
+### 指纹、结论与剩余风险
+
+- Italy:4187 行,SHA-256 `aab87b4e4bb7996e9c94833a64c7102e9e90dff4bd4d74ec545921fe7e92a14e`。
+- 公共工具:497 行,SHA-256 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+- 详情诊断工具:505 行,SHA-256 `3fb74f5cd53312381ca566e564fce34798069f40b1bc48f1d1b9a68472819c93`。
+- 最终证据工具:177 行,SHA-256 `92259d2e58c8712a836e568aaaa6091fea1d59411ce520a0c8cf0faf707f6152`。
+
+H-07 的离线单源归属和未知暂停证据通过,H-11 的本批消费者迁移通过;真实网站列表状态文案、现场完整覆盖及新版本真实预约仍属 W6/LT-03,不能由离线测试替代。W4 继续为部分完成,RC-01/05/09/10 仍未整体通过。下一生产工作包回到表单准备/日历操作的较大重复结构,不在已经单源化的回执层继续为行数强删。
+
+## 11. 最终请求审计职责迁移:实施前记录
+
+依据 T-01/T-02/T-09/T-10/T-12、H-07/H-08/H-11、UT-12/13、IT-02/03/04、RC-01/02/05/08/10。当前 Italy 4187 行;本工作包只调整“生产提交证明”和“验收请求计数”的职责边界,不改变最终按钮、请求字段、回执归属、未知结果或自动重试语义。
+
+### 代码事实与取舍
+
+生产 `NativeFinalSubmitter` 已经在同一次同步浏览器操作中完成:复核当前用户会话和预提交选择、只允许唯一按钮执行一次、用 DOM 消耗标记阻止同一按钮再次点击、围绕原生点击监听唯一目标 POST,并逐字段核对标签页、日历运行时 ID、日期、时间和容量。`FinalBookingAttempt` 还是单次状态机;写入后的任何监听、响应或回执不确定都会进入 `BookingOutcomeUnknownError`,不会作为普通失败自动重试。
+
+现有 `CalendarRequestAudit` 另外注册整页 CDP 回调,统计 OTP、AVANTI、月份读取、时段读取和最终请求。它的大部分消费者位于 `tools/debug_ita_*`、本地 Query→Book 验收和调试测试;生产最终流程只用其中一个差值判断。技术方案 T-10 已规定请求计数、快照和取证报告属于调试工具,VFS/TLS/BLS 的生产提交也采用原生监听而不是第二套常驻审计器。
+
+本批计划:
+
+1. 把 `CalendarRequestAudit` 原样迁入现有 `tools/debug_ita_calendar_gate.py`;调试、soak、本地串联和最终门禁继续使用完整计数,不新建 Italy 运行时模块。
+2. 生产 `submit_final` 直接复用 `NativeFinalSubmitter` 的精确请求证明;只有获得与当前 `FinalTarget` 完全一致的 `VerifiedSubmission` 才调用 `FinalReceiptReadPort.record_submission()`。没有证明仍走未知结果,不恢复第二次提交。
+3. 删除 `submit_final(..., request_audit=...)` 的调试注入参数和生产对 CDP 回调的所有权;工具在生产调用外持续观察整个页面,并继续以 `finalRequests == 1` 作为验收条件。
+4. 热更新/单文件测试不再把调试计数器列为上传插件的生产符号;改为继续验证原生提交器、最终状态机、回执读端和共享 OTP 锁都来自同一上传文件。
+
+### 风险、预算与验收
+
+- 生产能够保证的是 Coordinate 只执行一次原生点击、观察并核对该点击对应的目标请求、随后以唯一新增回执归属结果;整页是否还出现额外业务请求由调试/发布门禁计数。若现场或离线门禁观察到两个最终请求,仍不得发布。
+- 这不把 HTTP 200 当成功,也不删除基线活动预约阻断、申请人/会话/路由绑定、选择读回、回执稳定读取、明确拒绝或未知不重试。任何这些测试失败都必须修复实现,不能放宽断言。
+- 预计生产净减约 130–170 行;工具会增加同量左右的诊断代码,必须分别记账,不能把迁移说成全仓算法删除。公共模块零新增,VFS/TLS/BLS 零修改。
+- 先执行最终组合、真实 read-port、Booker 集成、单文件热更新及请求审计工具定向测试;再执行 Italy、调试、框架离线入口及配置/账号四套完整回归。全程不访问真实网站、邮箱、账号池或预约,不提交、推送或部署。
+
+如果生产原生监听不能维持“当前点击对应的精确请求证明”,或工具迁移破坏发布前恰好一次请求门禁,本工作包不得完成,也不得以删除测试达到减行目标。
+
+## 12. 最终请求审计职责迁移结果
+
+### 实际实现与边界
+
+- `CalendarRequestAudit` 已从 `plugins/ita_plugin.py` 原样迁入现有 `tools/debug_ita_calendar_gate.py`;soak、Book 门禁、预约诊断、本地 Query→Book 和调试测试继续使用同一被动 CDP 计数器。没有新建 Italy 运行时模块,也没有修改 VFS/TLS/BLS 或公共生产模块。
+- 生产 `submit_final(plugin, route)` 不再接收调试注入参数,也不注册/清理整页 CDP 回调。它直接调用现有 `NativeFinalSubmitter`;只有监听到当前标签页的原生最终 POST,并且运行时 ID、日期、时间和容量全部与当前 `FinalTarget` 一致,才把 `VerifiedSubmission` 绑定给回执读端。
+- `NativeFinalSubmitter` 的单次锁、DOM 消耗标记、唯一按钮检查、提交前选择读回和原生 `listen_once` 均保留;`FinalBookingAttempt` 的单次状态机、活动预约基线阻断、未知结果暂停和只读 reconciliation 均未改变。
+- 发布前整页副作用仍由工具证明:本地串联先确认最终请求计数为零再触发,触发后要求 `finalRequests == 1`;Book 最终门禁继续覆盖重复请求、迟到请求、审计回调丢失和清理失败,任一情况均不能发布成功。
+
+### 测试消费者迁移
+
+旧 `RealFinalAuditTests` 绑定“生产借用/拥有调试审计器”这一已删除内部结构,未作为旧接口保留。其业务风险按以下现行边界继续验证:
+
+| 旧风险 | 现行测试去向 |
+| --- | --- |
+| 没有匹配原生请求却出现新回执 | `FinalCompositionTests`:缺 `VerifiedSubmission` 必须进入未知,不返回普通失败或成功 |
+| 被动审计回调冲突、断线、无效事件、启动/停止失败 | `PassiveRequestAuditTests` 与预约/Book 门禁调试测试 |
+| 零次、重复、混合或迟到最终请求 | `BookGateFlowTests` 的真实最终核心与最终门禁用例;重复/迟到均令 `requestAuditVerified=false` 或整体失败 |
+| 已有活动预约、申请人/会话变化、写后未知不重试 | 最终 read-port/归属测试、`LocalFinalTests` 和原 `BookerIntegrationTests` |
+| 单文件热更新仍绑定上传版本 | `SingleFileInstallationTests` 改查 `NativeFinalSubmitter`、最终状态机、read-port 和共享 OTP 锁,不再要求生产上传调试计数器 |
+
+首次定向回归唯一失败是单文件本地验收夹具仍要求 `production(..., request_audit=...)`;夹具迁至现行两参数合同后通过,生产没有增加兼容参数。框架离线入口也仍点名已删除的旧测试类;已替换为上表三类现行测试,而不是删除最终请求门禁。
+
+### 行数、验证与结论
+
+- Italy **4187 → 4031,净减 156 行**,符合事前 130–170 行估算;相对 W0 的 6286 行累计减少 2255 行,距约 1000 行仍差 3031 行。
+- `tools/debug_ita_calendar_gate.py` 为 1491 行;迁入诊断代码单独记账,不能描述为全仓净删 156 行。公共 `utils/plugin_utils.py` 仍为 497 行,本批公共生产代码零新增。
+- 定向六组 194 项通过;完整 Italy 540 项、调试 323 项、框架离线入口 74 项、配置/账号 27 项均 exit 0、0 skip。测试组有交集,不累加为独立总数。
+- SHA-256:Italy `cf2b542cd0dfef08611818d2e5eb9676b8e49b4e4b9b033fbe7ddb5bbd575345`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`;日历调试工具 `57e15a24ebc20bdc3749ff127453b9cef91f854c98e9a1e1e30860872e5c3271`;框架入口 `55ee8bcd2ae62ec7e0fb7a49367c7dd1ba78d54d5bd1cf8c0e780aa7f40fe72d`。
+- Python 语法检查、`git diff --check` 均通过。所有测试使用合成浏览器、请求、账号和外部边界;没有访问真实网站、邮箱、账号池或订单,没有创建预约,也未提交、推送或部署。
+
+本子项符合 T-09/T-10:生产必须持有精确原生请求证明,发布门禁必须持有整页恰好一次计数;两者不能互相冒充。H-07/H-11 的本批离线证据通过,H-08 和 RC-01/05/09/10 仍未整体通过。下一工作包继续处理表单准备/等待与日历页面操作的较大重复结构。
+
+## 13. 最终提交证明模型收敛:实施前记录
+
+依据 T-01/T-02/T-04/T-08/T-09/T-10/T-11/T-12、H-05/H-07/H-08/H-10/H-11、UT-10/11/12/13/15、IT-02/03/04/05/06、RC-01/02/04/05/08/10。当前 Italy 为 **3795 行**,SHA-256 `5e67985329620f016708634144682700611ae7824016d0d7f932bd35ebb7e83e`;公共工具为 497 行,SHA-256 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+### 代码事实与本次边界
+
+最终提交层目前把同一份不可变 `FinalTarget` 重复包装为 `VerifiedSubmission`,又把申请人和一次性随机 `session_key` 复制进 `ReservationSnapshot`。实际生产上下文仍由 `FinalReceiptReadPort.session_is_current()` 在每次读取前后核对页面、浏览器、标签页、会话代次、账号、路由、prepared calendar 与 precommit;`service_id` 也只在构造 `FinalTarget` 时复制,最终请求匹配和回执归因没有读取它。这些重复字段没有增加独立事实源,反而形成三套必须同步的身份表示。
+
+本批只收敛证明表示,不改变网站行为或状态机:
+
+1. 严格匹配原生最终请求后,直接返回当前不可变 `FinalTarget` 作为本次请求证明;删除只含一个 `target` 字段的 `VerifiedSubmission` 包装。
+2. `ReservationSnapshot` 直接绑定同一 `FinalTarget`,不再复制申请人、随机 session key 和恒为真的 `complete`。最终状态机仍要求快照目标与本次目标完全相等、时间戳位于当前读取窗口、记录结构完整。
+3. 删除 `FinalTarget` 中最终层从未消费的 `service_id` 和一次性 `session_key`。网站服务仍由当前 route、prepared runtime service、页面 selectedService、当前会话检查及请求字段共同核对;多领区配置语义不变。
+4. 保留原生按钮一次性消费、`listen_once`、目标 POST 三字段匹配、提交后的 accepted/rejected/unknown 解释、活动预约基线阻断、历史不变、唯一新增确认回执、服务/日期/时间归属和 `BookingOutcomeUnknownError`。结果不明仍不得自动重试。
+
+修改范围仅为 `plugins/ita_plugin.py`、直接消费这些私有证明类型的现有测试和 `tools/ita_final_evidence.py`;不修改公共接口、配置、VFS/TLS/BLS、HTTP/OTP/DOM/最终提交策略,不新增公共模块或 Italy 私有运行时文件。预计生产净减 **20–50 行**;数值小于一个完整分区,重点是把三份身份表示压成一个事实源,不能用本批代替约 1000 行总体目标。
+
+改前定向命令:`PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_ita_booking_final test.test_ita_final_read_port test.test_ita_final_attribution test.test_ita_final_evidence test.test_ita_workflow test.test_debug_ita_query_book test.test_ita_single_file`,exit 0,**241 项通过、0 skip**。改后必须先迁移相同业务断言,再执行完整 Italy、调试、框架离线入口、配置/账号、语法及工作区检查;不能通过删除未知暂停或精确归因测试获得通过。
+
+本次授权只覆盖既定方案内的本地实现、离线测试和记录;不访问真实网站、邮箱、账号池、订单或预约,不提交、推送或部署。用户的 `config/test_conf.json` 修改和旧文档删除保持原样。
+
+## 14. 最终提交证明模型收敛结果
+
+### 实际实现与安全边界
+
+- 删除只包装一个字段的 `VerifiedSubmission`。`inspect_final_packet()` 只有在当前标签页、同源最终路径、POST 方法及三个原生表单字段全部匹配时,才直接返回同一个不可变 `FinalTarget`;响应状态或结构未知时仍保留“请求可能已经写入”的证明并进入只读 reconciliation。
+- `ReservationSnapshot` 现在只保存同一个 `FinalTarget`、当前读取时间、严格预约记录和可选的同目标提交证明,不再复制申请人、随机 `session_key` 和恒为真的 `complete`。`FinalBookingAttempt` 继续检查目标完全相等、时间戳位于本次调用窗口、记录上限/唯一性/状态/日期/时间/详情路径以及写后证明阶段。
+- `FinalTarget` 删除最终层没有消费的 route `service_id` 和随机 `session_key`。这没有删除服务核验:生产 read-port 每次仍通过当前 route、prepared calendar、runtime service、页面 `selectedService`、账号、浏览器、标签页、会话代次和 precommit 检查上下文;本地真实提交保护器也从复制的 `target.service_id` 改为分别核对 route/routing key、prepared runtime service 和同一 approval。
+- 原生按钮一次性消费、同步选择读回、`listen_once`、最终 POST 字段匹配、活动基线阻断、历史不变、唯一新增确认回执、服务/日期/区间时间归属及 `BookingOutcomeUnknownError` 均未改变。未知、丢包、清理失败或重复调用仍不能触发第二次写入。
+
+首轮 241 项回归出现 3 errors、7 failures:两项测试仍访问旧证明包装的 `.target`;单文件/本地串联保护器仍访问已删的重复 `target.service_id`,因此在原生派发前按设计失败,连带 7 个最终串联场景没有进入提交。消费者迁移后,保护器改查 route 和当前 prepared runtime service,而不是跳过服务检查;同一 241 项恢复为全部通过。
+
+### 行数、消费者与验证
+
+- Italy **3795 → 3776,净减 19 行**,略低于 20–50 行估计;按实际记账,不通过压排版补足。相对 W0 的 6286 行累计减少 2510 行,距约 1000 行仍差 2776 行。
+- 公共 `utils/plugin_utils.py` 仍为 497 行且未修改。`tools/ita_final_evidence.py` 为 178 行;`tools/ita_query_book_local.py` 为 729 行。工具只迁移证明消费者和本地保护器,不成为插件运行时依赖。
+- 定向 241 项、完整 Italy 535 项、调试 330 项、框架离线入口 74 项、配置/账号 27 项均 exit 0、0 skip;测试组有交集,不能相加为独立测试总数。
+- Python 语法检查、生产 AST 禁止导入 `tools.*`/`test.*`、旧证明/随机 session/重复 service 字段扫描和 `git diff --check` 均通过。
+- SHA-256:Italy `55152b06d32d0567e41d48d42aa04afdb7449a80234f5f812e23fea8a819f8ee`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`;最终证据工具 `5e2b587d3ee193405a0926261c4ad15c25741d57419689e0ab9a54dce4e49fba`;本地串联工具 `26f87db2bdcdc56a8664c79001b081a9eb2505e2e38b41ab0abb6e65e7f6987a`。
+
+所有验证均使用合成浏览器、请求、回执、账号和外部边界;没有访问真实网站、邮箱、账号池、订单或预约,没有提交、推送或部署。用户配置修改和旧文档删除保持原样。本子项为 H-05/H-07/H-10/H-11 增加离线证据,但 W4、H-08、RC-01、现场 RC-05/09 和整体 RC-10 仍未完成。下一步须继续审计最终读端/状态机或另一整块生产结构,不能因本批只有 19 行减量而放宽总预算。
+
+## 15. 最终交易单流程收敛:实施前记录
+
+日期:2026-09-01;依据 T-01/T-02/T-04/T-08/T-09/T-10/T-11/T-12、H-05/H-07/H-08/H-10/H-11、UT-10/11/12/13/15、IT-02/03/04/05/06、RC-01/02/04/05/08/10。当前 Italy 为 **3750 行**,SHA-256 `7c28d0f6a361f2b243c333d0fa1b463e01ee7c9f3d578a9758e35a48e4e0fbc3`。
+
+### 代码事实与目标结构
+
+生产最终路径只有一条:`submit_final → FinalReceiptReadPort → NativeFinalSubmitter → FinalBookingAttempt → FinalReceiptReadPort`。三层对象分别保存同一个 target、session/current 回调、锁、提交证明和前后快照;`FinalBookingAttempt.reconcile()` 在生产重复调用中并不会自动执行,`observe_receipts()` 则只由调试/验收工具消费。当前 `NativeFinalSubmitter`、`FinalBookingAttempt`、`FinalReceiptReadPort` 合计约 336 行,连同快照/观察包装和转发约 370 行。
+
+本批不是重写网站协议,而是把现有代码按原顺序整合为一个最终交易边界:
+
+1. 保留 `FinalTarget`、原生同步选择读回、唯一按钮 DOM 消耗标记、`listen_once` 和最终 POST 三字段逐项匹配;网站 handler 继续拥有请求构造,不增加 HTTP 重放。
+2. 由一个对象捕获 applicant/page/browser/tab/session/prepared/precommit/route,串行完成只读基线、一次原生派发和一次只读结果核验;不再让三层对象复制同一状态。
+3. 保留基线活动预约/候补阻断、历史记录不可变化、唯一新增 ACTIVE 回执、服务/日期/分配时间归属、明确拒绝返回 false,以及任何不完整证据进入 `BookingOutcomeUnknownError`。派发后中断、监听失败、回执读取或标签页清理失败仍不得自动重试。
+4. 只读观察从生产交易状态中分离:现有调试工具调用同一个受绑定的预约列表读取入口,但观察结果不能晋升为生产成功。工具的持久一次性 fence 和整页恰好一次请求审计继续保留。
+5. 删除只验证旧三层对象形状的测试;所有业务断言迁到单交易对象、公开 `submit_final()`、现有本地 fence 和单文件热更新。不会用减少测试数量替代拒绝/未知/归属场景。
+
+不修改 Query、Book 日期/时段选择、OTP、Turnstile、日历传输、配置或公共模块,不新增 Italy 运行时文件。VFS/TLS/BLS 零修改。预计生产净减 **140–240 行**;若需要删除一次提交、精确请求证明、回执归属或未知暂停才能达到下限,本包停止并按实际记录。
+
+### 改前证据与验收
+
+改前执行:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest \
+  test.test_ita_booking_final test.test_ita_final_read_port \
+  test.test_ita_final_attribution test.test_ita_final_evidence \
+  test.test_ita_workflow test.test_debug_ita_query_book \
+  test.test_ita_single_file
+```
+
+结果:exit 0,**241 项通过、0 skip**。改后先执行同一业务集合并逐项登记结构测试迁移,再执行完整 Italy、调试、框架离线入口、配置/账号、语法、单文件导入边界和 `git diff --check`。
+
+本批授权仍只覆盖既定方案内的本地实现、离线测试和记录;不访问真实网站、邮箱、账号池、订单或预约,不提交、推送或部署。用户配置修改和旧文档删除保持原样;不使用用户禁止的 phase-gated skill。
+
+## 16. 最终交易单流程收敛结果
+
+### 实际结构与保留边界
+
+- 删除独立 `FinalReceiptReadPort` 运行时对象;`FinalBookingAttempt` 现在一次捕获申请人、页面、浏览器、标签页、会话代次、route、prepared calendar 与 precommit,并串行持有基线、原生请求证明和回执状态。生产 `submit_final()` 只创建这一个交易对象。
+- `NativeFinalSubmitter` 保留为网站边界适配器:它继续同步复核当前选中时段、消费唯一按钮、使用既有 `listen_once` 监听一次原生 POST,并逐字段核对日历 ID、日期、时间和容量。没有改为 HTTP 重放,也没有把 200 当预约成功。
+- 预约列表读取继续只创建并关闭自己确认拥有的同浏览器后台标签页;读取前后核对当前申请人会话,使用同一严格列表解析和稳定双读。基线只允许取消历史;任何活动、候补、未知状态、结构不完整或上下文变化都在提交前停止。
+- 写后仍要求旧历史逐条不变、恰好一条新 ACTIVE 记录、服务/日期/选中区间内分配时间一致,并且存在同一 `FinalTarget` 的原生请求证明。明确拒绝且没有新活动记录才返回 false;其余冲突、超时、断线、清理失败或证据不足均为 `FinalOutcomeUnknown`,不得自动重试。
+- 调试/验收工具改用同一个交易对象的只读调用和 `observe_receipts()`;本地一次性文件 fence、整页最终请求计数及人工授权边界保持在工具层。没有增加兼容类或第二套旧状态机。
+
+### 首轮失败与修正
+
+合并后的首轮定向回归出现 80 个 import error,原因是现有工具和测试仍导入已删除的旧私有类名;这些消费者迁到单交易对象,没有恢复旧类壳。迁移后还有两项失败:
+
+1. 新读取逻辑在确认标签页所有权前就把候选页加入清理列表,可能关闭主日历页或外部页。实现改为先验证“新页、同一浏览器、不同且有效 tab id”,通过后才取得关闭所有权;相应安全测试恢复通过。
+2. 旧静态边界把“构造可只读调用的交易对象”当作“执行最终提交”。测试改为继续禁止 `submit_final` 和 `NativeFinalSubmitter` 直接出现在 Query/预提交入口;是否发生写入仍由默认开关、运行时最终请求零计数和单次提交测试证明,没有放松生产提交条件。
+
+状态机离线夹具改为测试专用适配器子类,只替换浏览器/回执外部边界,继续执行生产 `FinalBookingAttempt.execute()` 与 `reconcile()`;没有在测试中复制成功判定算法。真实工具仍走标准构造器。
+
+### 行数、验证与结论
+
+- Italy **3750 → 3685,净减 65 行**,低于事前 140–240 行估计。原因是合并后仍保留快照结构验证、独占锁、标签页所有权、清理异常、中断后的只读 reconciliation 和调试观察入口;不通过压排版或删除安全语义补足估算。
+- 相对 W0 的 6286 行累计减少 2601 行,距约 1000 行仍差 2685 行。当前大分区为 `PLUGIN` 766 行、`CALENDAR_BOOK` 630 行、`CALENDAR_QUERY` 456 行、`PROTOCOL` 435 行;下一工作包必须从这些真实调用图寻找结构性复用,不能继续靠微型包装合并宣称预算可达。
+- 改前、改后同一最终交易集合均为 **241 项通过、0 skip**。扩大回归:Italy 535 项、调试 330 项、框架离线入口 74 项、配置/账号 27 项,全部 exit 0、0 skip;测试组有交集,不能相加为独立总数。
+- `py_compile`、4 个核心修改文件 AST 解析、生产对 `tools.*`/`test.*` 导入为 0、旧 `FinalReceiptReadPort` 运行时代码/消费者扫描和 `git diff --check` 均通过。历史记录中的旧类名保留为当时结构事实,不是当前导入。
+- SHA-256:Italy `c35317dcaaec63ef18e5bd26a130196cbb106e1b57f954d789313bd310d22009`;公共工具 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`;最终证据工具 `a0a8f93fba52560f6dbfb405664829273f392e8e17476fefae15fd033c086f2`;Book gate `242e087b5b98780d7e4c9eb197fe65351b2f80f54b3012bccabe5ca3696af9b7`。
+
+所有验证均使用合成浏览器、请求、回执、账号、Redis 或其他模拟外部边界;没有访问真实网站、邮箱、账号池或订单,没有创建预约,也未提交、推送或部署。用户的 `config/test_conf.json` 修改和旧文档删除保持原样。本批增加 H-07/H-10/H-11 的离线证据,但 H-04/H-08、RC-01、现场 RC-05/09 及整体 RC-10 仍未完成,W4 仍是“部分完成”。
+
+## 17. CR-001 后的最终提交精简:实施前记录
+
+日期:2026-09-01。依据 T-01/T-02/T-04/T-08/T-09/T-10/T-12、H-03/H-07/H-08/H-10/H-11、
+UT-10/11/12/13/15、IT-02/03/04/05、RC-01/02/04/05/08/10。用户明确允许 Italy 调试期记录
+OTP、Token 和敏感表单,并允许最终提交使用普通重试;这是对本文件第 1–16 节旧“未知暂停、
+跨调用不重提、脱敏诊断”目标的正式覆盖,旧章节仍作为当时实现与测试的历史证据。
+
+### 目标结构
+
+1. 保留申请人账号/会话、route、当前库存、日期/时段、DOM 选中状态和最终按钮的提交前核对。
+2. 每次 `book()` 最多执行一次网站最终点击;不在插件内循环、不切换传输通道重放。
+3. 网站给出可归属的明确成功结果才返回 `VSBookResult.success=true`;拒绝、超时、断线或证据不足均返回普通失败。
+4. 普通失败交回既有 Booker;下一次调度重新进入服务、准备日历、重查库存和重选运行时 ID 后再调用,健康登录可复用。删除 Italy 专属 `BookingOutcomeUnknownError` 暂停、跨调用持久 fence、复杂历史 reconciliation 和多层提交/回执证明对象。
+5. 删除只证明 OTP/Token/敏感表单没有出现在日志中的包装和测试;允许现有调试输出直接记录这些值。真实秘密仍不得提交进 Git。
+6. Query 的零最终写入、池子 Query/申请人 Book 隔离、预提交开关和单文件热更新不变。
+
+现成替代证据:`OrderBookerGCO._execute_book_job()` 已对 `VSBookResult.success=false` 明确记录
+“Will retry on next signal”,而 `BookingOutcomeUnknownError` 才进入专属 pause 分支;删除 Italy
+未知异常后会自然复用普通分支,不需要修改 Booker。VFS/TLS/BLS 的 `book()` 也直接返回
+`VSBookResult` 或普通业务异常,没有 Italy 这套预约历史状态机。
+
+本工作包不修改 Sentinel/Booker 调度协议,不新建 Italy 私有运行时或通用提交框架。当前先完成
+进行中的 R1,R3 实施时再迁移上述代码和业务测试。实施前基线为当前中间工作区 3532 行,
+SHA-256 `245fc806cb0834d6d39bfc1601fc3287809e34f834d3c7e6c6723a7928f0be73`;完整回归尚未重跑。
+本记录与方案同步不授权真实网站、邮箱、账号池、订单、最终预约、Git 提交/推送或部署。
+
+## 18. CR-001 后的最终提交精简:结果
+
+### 实际结构
+
+- Italy 最终生产路径收敛为 `_submit_final_once()`:先核对当前 Book 准备上下文和申请人,复用
+  `verify_precommit_selection()` 读回当前日期/时段/运行时 ID,再通过网站原生按钮执行一次点击。
+- `_final_packet_accepted()` 只接受当前标签页、同源精确路径、POST、恰好三个唯一表单字段、
+  当前日期/时段/日历 ID、HTTP 200、大小有界 JSON、空 `errorMessage` 和同源目标 URL。只有这些
+  条件全部成立才返回标准 `VSBookResult.success=true`。
+- 拒绝、监听超时、错误字段、上下文变化或解析失败均返回标准 `success=false`,并清除 Calendar
+  准备与 precommit;同一次调用不再点击。下一共享信号重新进入服务、准备日历、读取库存和
+  运行时 ID,健康登录可复用。
+- 删除生产预约列表/详情读取、活动基线、历史差异、`FinalBookingAttempt`、
+  `NativeFinalSubmitter`、`FinalOutcomeUnknown`、`SubmissionSignal`、持久 fence 与
+  `BookingOutcomeUnknownError` 分支。现有 Booker 的普通失败重试是唯一调度器,没有在 Italy
+  复制第二套重试系统。
+- Query、预提交开关、账号隔离、自动 OTP、日期范围、时段选择和单文件热加载保持;公共模块、
+  VFS/TLS/BLS、Sentinel/Booker 均未修改。
+
+### 测试迁移、失败修正和证据
+
+- `test_ita_booking_final` 改为明确成功、网站拒绝、超时/错请求、错误申请人、一次调用第二次派发
+  阻断和旧生产类型不存在的合同测试。
+- `test_ita_booker_integration` 使用真实 `OrderBookerGCO._execute_book_job()` 证明:成功仍走现有
+  上报/清理;普通失败保留任务和 `book_allowed`;下一信号重新准备后可再次调用。
+- 最终证据、reservation、read-port、workflow、single-file、debug gate 和本地 Query→Book
+  消费者均迁到新公开结果;只验证旧私有类形状的断言被替换,没有保留兼容类或第二套实现。
+- 框架离线入口首轮仍点名两个已删除的旧测试,出现 2 个加载错误;迁到新最终合同后 75 项通过。
+  这是消费者清单遗漏,不是生产行为失败。
+
+精确验证结果:定向 144 项、完整 Italy 389 项、调试 280 项、框架离线入口 75 项、配置/账号
+27 项均 exit 0、0 skip;5 个核心文件 AST 解析、生产导入边界与 `git diff --check` 通过。
+
+Italy **3532 → 2883,净减 649 行**;最终分区约 **770 → 135 行**,公共工具仍为 497 行且本批
+未修改。当前 Italy SHA-256 为
+`f3d3fbd013e5e311d31162bad86d2d699640f949681dc90aa129b6d5a3d05c11`。所有验证均为离线模拟,
+没有网站、邮箱、池子、订单、预约、Git 或部署动作。R3/H-07 当前离线条件通过;W4 整体、
+H-08、RC-01、现场 RC-05/09 与整体 RC-10 仍未完成。下一步执行 R2。

+ 262 - 0
docs/italy-refactor/records/W5-tools.md

@@ -0,0 +1,262 @@
+# W5:现有工具、热更新与完整回归
+
+日期:2026-09-01;状态:账号池 Query 命令迁移完成,W5 整体仍进行中。
+
+依据 T-01/T-02/T-07/T-11/T-12、H-08/H-09/H-10/H-11、UT-06/14/15、IT-04/05/06、RC-01/02/06/07/08/10。配套:[技术方案](../01-technical-design.md)、[开发计划](../03-development-plan.md)、[测试计划](../04-test-plan.md)、[准出条件](../05-release-criteria.md)。
+
+## 1. 账号池 Query 命令迁移(开始前)
+
+### 现状与问题
+
+`test/test_plugin_tester_ita_config.py` 的 10 个场景不调用任何现行工具,而是从用户已删除的 `docs/ita_query_book_acceptance.md` 截取一段 shell 内联 Python,再 `exec`。因此 26 项配置/账号测试固定出现 1 failure、9 error;恢复旧文档会重新引入第二套账号分配实现,也违背用户已有删除。
+
+项目已有:
+
+- `tools/debug_ita_query_book.py`:Italy Query+Book 的现行公开调试入口;已支持离线、本地预检和真实本地串联。
+- `tools/ita_query_book_local.py`:读取唯一 Sentinel 分组、验证路由/OTP/代理、调用现有 `VSCloudApi.get_next_account()`,再交给真正 Sentinel/Booker。
+- `tools/plugin_tester.py`:公开插件 Query 流水线;不应理解 Italy Sentinel 配置或再实现账号池。
+
+### 本批改法
+
+1. 在现有 Query+Book CLI 增加互斥的 `--pool-query` 模式,不在 `plugin_tester.py` 增加 Italy 分支。
+2. 从现有本地串联适配器提取一个“分配并验证 Query 账号”函数;原串联和新模式共用,仍只调用一次 SDK。
+3. 新模式读取原 `config/config_sentinel.json` 分组,构造标准 `VSPlgConfig` 后交给 `PluginTester.run_pipeline(test_book=False)`;不重写 Query、浏览器、OTP 或调度逻辑。
+4. 将旧文档执行测试迁到 CLI `main(argv)`,保留:DEBUG 日志/TEST_ACCOUNT 在分配前拒绝、不同合法邮箱动态解析自己的 OTP 邮箱、错误池/空密码/禁用/坏邮箱在浏览器前拒绝、上游失败不本地回退且不输出响应正文。
+
+### 不变边界与验证
+
+- `--pool-query` 只 Query,不 Book、不创建订单;账号池和冷却来自唯一分组配置。
+- 不打印用户名、密码、邮箱正文或 OTP;错误输出只含固定分类或异常类型。
+- 不读取真实账号池进行离线测试;云端、浏览器和 subprocess 均注入合成边界。
+- 预计工具与测试净增少量代码,Italy 生产文件行数不因此下降;这是消除无效消费者、恢复完整准出测试,不冒充 RC-01 进展。
+- 定向执行配置/加账号测试,再执行 Italy、调试、框架离线和单文件热更新回归。结束结果、命令和未完成预算在本文件续记。
+
+本节只授权本地工具、测试和记录范围;不访问真实网站、邮箱、账号池或预约,不提交、推送、部署,也不恢复用户删除的文档。
+
+## 2. 账号池 Query 命令迁移(完成结果)
+
+### 实际实现与复用
+
+- `tools/debug_ita_query_book.py` 在原有互斥运行模式中增加 `--pool-query`;它不是第二个测试器,也没有复制 Italy Query。`--submit-once` 仍只允许与 `--local-run` 同用,因此 Query 模式在账号分配前就拒绝最终提交。
+- `tools/ita_query_book_local.py` 从既有本地串联边界提取 `allocate_query_account()`。原 `LocalCloudBoundary` 和新 Query 命令共同调用它,继续使用同一个 `VSCloudApi.get_next_account(pool, cooldown)`、`VSAccount`、分组配置、路由解析及邮箱绑定校验。
+- 新入口将标准 `VSPlgConfig` 交给既有 `PluginTester.run_pipeline(test_book=False)`;浏览器、登录、OTP、Query 及清理仍由公开测试器和插件实现,工具没有重写这些行为。
+- `test/test_plugin_tester_ita_config.py` 不再读取或 `exec` 已删除文档中的 shell 代码,而是直接调用受支持 CLI 的 `main(argv)`。旧业务断言全部迁移,并增加“账号池 Query 不能与最终提交同时启用”的前置拒绝测试。
+
+支持命令如下;这是会分配真实池账号并执行真实 Query 的人工命令,本批没有运行:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B tools/debug_ita_query_book.py \
+  --pool-query \
+  --group ita.hong_kong \
+  --config config/config_sentinel.json \
+  --proxy http://127.0.0.1:6268
+```
+
+### 离线验证结果
+
+| 命令 | 结果 |
+| --- | --- |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_plugin_tester_ita_config test.test_add_ita_query_account` | exit 0;27 项通过,0 skip;旧 1 failure/9 error 已由真实迁移消除 |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest test.test_debug_ita_query_book` | exit 0;60 项通过,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test -p 'test_ita*.py'` | exit 0;550 项通过,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest discover -s test -p 'test_debug_ita*.py'` | exit 0;323 项通过,0 skip |
+| `PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B tools/debug_ita_query_book.py --offline` | exit 0;75 项通过,0 skip |
+| `git diff --check` | exit 0 |
+
+测试使用合成账号和注入边界;socket、HTTP、subprocess、真实账号池与本地账号回退均被禁止。验证了只分配一次、配置冷却、动态邮箱绑定、Query-only、禁用/错池/空密码/坏邮箱前置拒绝、DEBUG/TEST_ACCOUNT 前置拒绝、上游错误正文不进入输出,以及不能借 `--submit-once` 越过 Query 边界。测试组有交集,不把 27/60/550/323/75 相加为独立总数。
+
+### 指纹、预算与未完成项
+
+- `tools/debug_ita_query_book.py`:81 行,SHA-256 `a487b71484e864450cecbe28d279f7056b5ba2f7f43db7baaeafa43ca41f3997`。
+- `tools/ita_query_book_local.py`:727 行,SHA-256 `62f3c728aa09932e26f70f3b72fb3e878f04e505244788050a73d3e76a0e73fd`。
+- `test/test_plugin_tester_ita_config.py`:259 行,SHA-256 `9b47fe909a89321efe825ca473f12b75c1a1eae6bec32d20043a72ca34b27b64`。
+- Italy 生产文件在本批保持 4289 行,SHA-256 `5b40e677a2966081e5bdb437935039d19d75414c6a40cdde3e19fd52900b9d59`;公共工具保持 497 行,SHA-256 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+
+因此 H-11 的这一个失效消费者已修复,UT-14/IT-04/IT-05 对应证据恢复;这不使 W5 或 RC-01 整体通过。插件仍比约 1000 行目标多 3289 行,生产结构精简、两领区配置证据、现场验收和发布均未完成。本批没有访问真实网站、邮箱、云账号池或预约,也没有提交、推送或部署;用户配置和旧文档删除保持原样,且没有使用用户禁止的 skill。
+
+## 3. 协议与配置校验收敛(开始前)
+
+日期:2026-09-01;依据 T-01/T-02/T-03/T-04/T-05/T-07/T-11/T-12、H-05/H-06/H-08/H-09/H-11、UT-05/06/07/08/10/14/15、IT-01/02/04/05/06、RC-01/02/03/04/06/07/08/10。
+
+### 代码事实与取舍
+
+当前 `plugins/ita_plugin.py` 为 **3776 行**。文件开头约 460 行的协议层已经是 Query 与 Book 共用的唯一解析入口,但同一类“类型、范围、字段路径、错误码”校验仍以大量重复的 `raise` 文案和薄包装函数展开。该层没有可直接替换它的 VFS/TLS/BLS 或公共模块:日期范围继续复用 `filter_dates_in_range`,公共返回类型继续复用 `VSQueryResult`/`VSBookResult`;Prenot@Mi 的双层 JSON、库存计数、动态日历 ID、路由表单字段和 OTP 模板属于网站协议,不能下沉到 `utils` 冒充通用能力。
+
+本子项只做表示收敛,不改变协议合同:
+
+1. `ItaProtocolError` 继续暴露稳定 `code` 和 `path`,但错误文本由稳定错误码生成,删除每个调用点重复且无人消费的解释句;异常仍不得包含服务器正文、邮箱正文、账号或运行时 ID。
+2. 合并协议内部的重复类型/范围校验模板;保留 `ItaCapability`、`InventoryState`、`ItaRouteConfig`、`OtpMailConfig`、`CalendarDay`、`SlotCandidate`、`PrecommitApproval` 及现有解析函数名称,避免热更新和受支持工具出现隐式断裂。
+3. 保留双层 JSON 严格层数、1 MB/512 项边界、重复日期/时段/日历 ID 拒绝、库存正负计数语义、日期/时间精度、路由能力、表单标签、邮箱来源/发件人/模板/有效期和六位 OTP 唯一性。
+4. 不改 `query()`、`book()`、登录、OTP 请求、日历读取、最终提交、回执、网络通道或重试行为;H-04 仍未现场通过,生产继续使用当前原生浏览器月份路径。
+
+这不是把 Italy 协议搬到新文件,也不新增公共 API、私有运行时模块或构建步骤。预计生产净减 **80–160 行**;如果只能通过删除错误码、字段路径、边界检查或业务测试才能达到预计值,本子项停止并按实际减量记录。
+
+### 改前证据与验证计划
+
+改前命令:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 .venv/bin/python -B -m unittest \
+  test.test_ita_protocol test.test_ita_otp test.test_plugin_tester_ita_config \
+  test.test_ita_calendar_query test.test_ita_calendar_book
+```
+
+结果:exit 0,**107 项通过、0 skip**。改后先执行同一命令;再执行完整 Italy、调试、框架离线入口和配置/账号回归,并检查 Python 语法、生产 AST 不依赖 `tools.*`/`test.*`、单文件热加载和 `git diff --check`。失败必须定位为实现或旧内部结构消费者;不能删除 Query 最早日期、Book 当前用户重查、自动 OTP、一次提交/未知暂停或多领区配置断言换取通过。
+
+本子项授权范围仍仅为既定方案内的本地代码、离线测试和记录;不访问真实网站、邮箱、账号池、订单或预约,不提交、推送或部署。`config/test_conf.json` 及用户删除的旧文档保持原样;不使用用户禁止的 phase-gated skill。
+
+## 4. 协议与配置校验收敛(完成结果)
+
+### 实际修改与边界
+
+- `ItaProtocolError` 继续保留 `code`、`path` 和不含外部正文的固定文本;内部调用点不再重复维护无人消费的解释句。
+- OTP 邮箱来源、固定模板/发件人、有效期、库存计数、时段 ID、路由 capability、双层 JSON、日期/时间精度和重复记录错误分类全部保留。常用的整数、日期、时间、映射和字符串校验改为一个插件内 `_checked` 原语;没有建立新的通用协议框架。
+- 月份起点由等价的年月偏移计算生成,继续验证 1–120 月边界并保持跨年升序;Query/Book、网络通道、最终提交、回执和重试代码未改。
+- 未新增公共 API 或 Italy 私有运行时文件。公共 `filter_dates_in_range`、框架类型和单文件热加载合同继续复用;网站专属协议仍留在上传文件中。
+
+首轮 107 项回归出现 2 failures:把非空 capability 校验放进枚举转换的同一个 `try` 后,缺失/空值被错误归为 `capability_unsupported`,而不是既有 `string_required`。实现改回“先验证字符串、再转换枚举”,保持原错误码;没有修改测试或放宽配置。
+
+### 行数、回归与结论
+
+- Italy **3776 → 3750,净减 26 行**,显著低于 80–160 行估算。原因是错误码、字段路径、模型符号和所有业务边界均被保留;不通过压缩 JavaScript、合并物理行或删除边界测试补足估算。相对 W0 的 6286 行累计减少 2536 行,距约 1000 行仍差 2750 行。
+- 改前定向 107 项通过;首轮 2 项失败修复后,同一 107 项通过、0 skip。
+- 完整 Italy **535 项**、调试 **330 项**、框架离线入口 **74 项**、配置/账号 **27 项**均 exit 0、0 skip。第一次 discovery 命令遗漏 `-t .`,仓库的 `test/test.py` 因顶层模块解析被误导入并报缺少无关 `cv2`;用正确的项目包参数 `discover -s test -t .` 重跑后两套完整通过,未安装依赖或改生产代码掩盖命令问题。
+- Python 语法检查、生产 AST 禁止 `tools.*`/`test.*` 依赖和 `git diff --check` 均通过。Italy SHA-256 为 `7c28d0f6a361f2b243c333d0fa1b463e01ee7c9f3d578a9758e35a48e4e0fbc3`;公共工具仍为 497 行,本子项未修改。
+
+所有测试使用合成协议、浏览器、账号和外部边界;没有访问网站、邮箱、账号池、订单或预约,没有提交、推送或部署。H-05/H-06/H-11 获得本子项离线证据,但 H-08、H-09 的第二领区证据、现场 H-04、RC-01/05/09/10 仍未完成。26 行结果进一步证明小型校验整理不是主要减量路径;下一子项必须优先审计插件入口中与现有公共 profile/生命周期能力重复的整块实现,或通过 H-04 后替换月份传输层,不能继续用微型模型改名消耗周期。
+
+## 5. 入口/profile 公共化审计结论
+
+按 T-01/T-02/T-11、H-01/H-02/H-08/H-10 审计后,本轮不把 Italy 的持久 profile 校验搬到 `utils`:
+
+- `init_chromium_options`、`cleanup_browser_workspace` 和 `BaseFlow` 已真实复用;R5 最终保持公共清理函数 HEAD 原签名,没有影响 VFS/TLS/BLS。
+- `utils/ita_local_profile.py` 只服务本地工具,负责创建账号哈希目录;生产插件负责验证调用方显式提供、已存在且位于临时目录之外的目录,并持有跨进程排他锁。两者名字接近但所有权和副作用不同,不能直接互换。
+- 把生产校验移入该 Italy 私有工具会让单文件上传依赖另一个 Italy 运行时文件,违反 T-01;在 `plugin_utils` 新增只由 Italy 使用的薄包装也不满足“两类真实消费者”要求,还给旧宿主热更新增加版本前置条件。
+- 该块即使安全抽取,预计只能减少约 40–80 行,无法解决 2750 行差距。现阶段保留 profile 安全语义和单文件自包含,转向生产仅有一条调用链的最终交易对象层;若未来 VFS/TLS 也采用持久 profile,再以至少两个真实插件消费者设计公共 API。
+
+这是一项“不改代码”的复用决定,不算 H-08 进展;避免了为表面复用制造新的公共层和部署耦合。
+后续本地 Italy 调试工具被删除后,该文件失去最后一个运行调用者;最终处置见第 10 节。
+
+## 6. R1 协议与配置结构性收敛(开始前)
+
+日期:2026-09-01;基线为 Italy **3566 行**、SHA-256
+`4dcacf211125145b73916ec7c4922072fec4824c179fb16bd4fcaea9bc61eebf`。依据
+[生产代码精简盘点](../07-reduction-inventory.md) R1、T-01/T-02/T-03/T-04/T-05/T-07/T-11/T-12、
+H-05/H-06/H-08/H-09/H-11、UT-03/05/06/07/08/10/14/15、RC-01/02/03/04/06/07/08/10。
+
+第 3–5 节采用“保留所有私有符号”的保守范围,实际只净减 26 行;其后日历和最终交易小包也
+分别只减 119/65 行。按用户最新明确要求,后续质量对齐 VFS/TLS/BLS,而不是继续兼容 Italy
+重构过程中的每一个私有对象。公开 `query()`/`book()`、现行配置含义、工具命令和关键协议
+失败关闭仍是合同;只被测试用于观察内部结构的枚举、嵌套包装和小校验转发不再是合同。
+
+本批计划:
+
+1. 路由保持一个不可变对象,但把只包一个整数的月份配置展平;表单控件仍保持命名字段,避免
+   页面脚本改回位置索引。
+2. 日历日、时段、OTP、双层 JSON 与路由在唯一入口校验;删除同一值在模型构造和解析器中的
+   重复验证,以及只用于断言展示状态的 `InventoryState`。
+3. 保留稳定 `ItaProtocolError.code/path`、最大载荷/项目数、重复日期/时段/日历 ID、库存冲突、
+   日期/时间精度、当前账号邮箱、固定发件人/模板、OTP 有效期和六位 ASCII 唯一性。
+4. 迁移实际工具和公开行为测试到新的扁平字段;只断言旧私有表示的测试改为断言可用/不可用
+   业务语义。不得修改 Query、Book、浏览器、网络通道、提交或回执行为。
+
+本批不向 `utils` 下沉 Prenot@Mi 协议;公共日期筛选、公共返回类型和云端邮箱接口继续直接复用。
+预计协议分区从 438 行降至 180–240 行;若实际边界要求更高,按事实记录,不压物理行或删除关键
+失败关闭。授权范围仅为本地代码、离线测试和记录;不访问网站、邮箱、池子、订单或预约,不做
+Git 提交、推送或部署,也不使用用户禁止的 phase-gated skill。
+
+## 7. R1 协议与配置结构性收敛(结果)
+
+### 实际改动
+
+- 删除 `CalendarScanConfig`,把唯一的 `lookahead_months` 直接放入 `ItaRouteConfig`;生产 Query、
+  Book、调试工具和测试均读取同一字段。
+- 删除只用于展示同一库存事实的 `InventoryState`;公开行为直接使用 `CalendarDay.is_available`,
+  仍以 `SlotLiberi > 0` 表示可用,并保留 `1/0` 最后一位样本和冲突/非法计数拒绝。
+- `CalendarDay`/`SlotCandidate` 不再在 dataclass 构造后重复执行解析器已经完成的字段验证;所有
+  外部数据仍只能经过唯一协议解析入口。
+- `OtpMailConfig` 合并邮箱规范化和动态邮箱解析,删除重复缓存字段;配置邮箱和当前账号邮箱
+  两种来源、固定发件人/模板、有效期、六位 ASCII 唯一性及账号绑定不变。
+- `FormControlConfig` 暂保留。它只有两个真实实例,直接服务同一表单脚本的 `control_id/value/labels`
+  命名字段;展平成 route 六字段或位置元组不会减行且会降低可读性,随 R4 表单整块再评估。
+- 只断言旧 `InventoryState`、嵌套月份包装和 dataclass 私有重复校验的测试迁到库存业务语义、
+  route 扁平字段和解析入口;没有删除 Query 最早日期、Book 申请人重查、自动 OTP 或多领区合同。
+
+CR-001 在本批完成后获用户确认。它改变后续 R3 的提交/日志语义,但不影响上述 R1 协议、
+配置和库存结果;对应方案及 W4 实施前记录已同步。
+
+### 行数与验证
+
+- Italy **3566 → 3532,净减 34 行**,低于 180–240 行协议分区目标。事实说明剩余 `_require_*`
+  多数承载稳定错误码/字段路径,继续微调收益低;下一步按计划进入 R2/R4/R3 的完整调用链。
+- 当前 Italy SHA-256:`245fc806cb0834d6d39bfc1601fc3287809e34f834d3c7e6c6723a7928f0be73`;
+  公共工具仍为 497 行,SHA-256 `dcead8ae1957044ec3e2092f192f68512f5a10c7d15197e6463c4fec26b6ebe4`。
+- 协议/OTP/配置/Query/Book 日历定向:107 项,exit 0,0 skip。
+- 完整 Italy:535 项,exit 0,0 skip;完整调试:330 项,exit 0,0 skip。
+- 框架离线入口:74 项,exit 0,0 skip;配置/账号:27 项,exit 0,0 skip。
+- Python AST、生产禁止导入 `tools.*`/`test.*`、`git diff --check` 和文档尾随空白检查通过。
+
+全部测试使用合成协议、浏览器、账号和外部边界;没有访问真实网站、邮箱、账号池、订单或
+预约,没有 Git 提交、推送或部署。用户的 `config/test_conf.json` 修改和旧文档删除保持原样。
+R1 完成;H-05/H-06/H-11 获得当前离线证据,H-08/RC-01 和现场准出仍未完成。
+
+## 8. R3 工具与离线入口迁移
+
+CR-001 删除生产最终回执状态机后,现有工具不再导入旧私有提交/预约类型:
+
+- `tools/ita_final_evidence.py` 只调用热加载插件自身的 `submit_final()` 并格式化标准成功/失败;
+  不维护持久 fence、未知暂停或另一套成功判定。
+- `tools/ita_query_book_local.py` 保留一次本地派发观察和副作用计数,但普通失败标为可由共享 Booker
+  后续重试;不创建 Italy 私有调度器。
+- `tools/debug_ita_book_gate.py` 的旧 receipt baseline 入口明确退休;一次真实提交仍必须显式传参,
+  工具不改变生产 `book()` 合同。
+- `tools/debug_ita_query_book.py --offline` 首轮因点名两个已删除的旧测试产生 2 个加载错误;清单改为
+  新最终适配器、`BookerReuseTests` 和新 gate 用例后,75 项通过。
+
+完整当前回归为 Italy 389 项、调试 280 项、框架离线 75 项、配置/账号 27 项,全部 0 skip;
+定向 144 项通过,AST/生产导入边界和 `git diff --check` 通过。工具不是插件运行时依赖,也没有
+恢复旧实现。未执行真实外部操作、Git 或部署。W5 仍需随 R2/R4/R5 的私有消费者继续迁移。
+
+## 9. Italy 专属测试目录整理
+
+用户要求把 Italy 相关测试集中管理。本批只整理测试消费者,不修改生产插件、公共模块、
+VFS/TLS/BLS、配置或真实业务入口:
+
+- 将 34 个 `test_ita*` / `test_debug_ita*` / Italy 配置测试,以及 `ita_source_sections.py`、
+  `ita_test_fakes.py` 两个测试辅助模块,共 36 个既有文件原样迁到 `test/ita/`。
+- 新增 `test/ita/__init__.py`;包内跨测试导入统一改为 `test.ita.*`。
+- 因文件深度增加一层,测试中用于定位仓库根目录的 `Path(__file__).resolve().parents[1]`
+  统一改为 `parents[2]`;这只是路径适配,不改变业务断言。
+- 顶层 `test/` 不再保留 Italy 专属 `.py` 文件;其他插件及通用测试均未移动。
+
+验证结果:37 个包内 Python 文件(含 `__init__.py`)全部通过语法编译;当前公开薄合同
+69 项通过、0 skip。完整 `test_ita*.py` discovery 能从新目录正确收集模块,但当前有 15 个
+导入错误和 1 个旧结构断言失败;`test_debug_ita*.py` discovery 有 10 个导入错误:它们依赖
+工作区中已删除的历史 Italy 工具或生产重构已删除的私有脚本/类型。
+`test_plugin_tester_ita_config` 同样仍导入已删除的
+`tools.debug_ita_query_book`。这些是整理前已经存在的旧消费者债务,本批没有恢复旧工具、旧
+运行时符号、跳过测试或伪造通过;后续仍按 W5 将业务断言迁往现行公开合同。
+
+外部边界全部为离线;没有访问网站、邮箱、账号池、订单或预约,没有 Git 提交、推送或部署。
+
+## 10. 删除孤立本地 Profile 能力及纯遗留测试
+
+调用图确认 `utils/ita_local_profile.py` 已没有生产或工具调用者:当前 Italy 插件使用实例临时
+工作区,VFS/TLS/BLS 从未引用该模块;原 `debug_ita_query`、`debug_ita_session` 等本地工具已经
+从工作区删除。继续保留该文件只会让 `utils` 看起来存在一个并不通用、也不会运行的公共能力。
+
+本批删除:
+
+- `utils/ita_local_profile.py`;
+- 只测试已删除工具的 `test/ita/test_debug_ita_query.py`、
+  `test/ita/test_debug_ita_session.py`;
+- `test_ita_shared_lifecycle.py` 中 1 个工具 Profile 锁用例;
+- `test_ita_plugin.py` 中 4 个持久 Profile 内部用例及其导入。
+
+保留:公共浏览器初始化、严格清理、临时工作区删除、登录、协议、OTP、Query/Book、最终一次
+提交和当前表单竞态测试。其他仍导入旧工具的测试文件混有现行业务断言,本批不直接整文件删除;
+应先迁移断言或证明已由当前合同覆盖。
+
+当前薄合同 68 项通过、0 skip;完整 Italy discovery 的既存 15 errors/1 failure 不变,说明本次
+没有新增业务回归;调试 discovery 因删除两个无被测对象的文件由 10 个旧导入错误降为 8 个。
+没有修改生产插件、公共浏览器模块或其他插件,也没有外部请求、Git、部署或真实预约。

+ 294 - 0
docs/vfs_plugin_deep_dive.md

@@ -0,0 +1,294 @@
+# 插件系统深度走读:以 vfs_plugin 为例
+
+> 配套文档:`docs/HANDOVER.md`(系统全景)。本文聚焦"插件系统是怎么设计出来的",用 vfs 插件作为解剖样本。
+> 行号引用:`plugins/vfs_plugin.py`(1466 行),框架侧引用 `vs_plg.py` / `vs_plg_factory.py` / `sentinel.py` / `booker.py` / `standalone.py`。
+
+---
+
+## 第一部分:插件系统是什么——三个文件、三个概念
+
+整个插件系统只有三个核心文件,对应三个概念:**契约(Interface)、工厂(Factory)、宿主(Host)**。
+
+```
+vs_plg.py           契约:IVSPlg 抽象基类 —— 定义"一个签证插件长什么样"
+vs_plg_factory.py   工厂:VSPlgFactory —— 定义"怎么把一个 .py 文件变成插件实例"
+sentinel/booker/standalone.py   宿主:GCO —— 定义"什么时候调用插件的哪个方法"
+```
+
+### 1.1 契约:IVSPlg(vs_plg.py,94 行)
+
+插件必须实现 8 个抽象方法,不多不少:
+
+| 方法 | 语义 | 宿主什么时候调用 |
+|---|---|---|
+| `set_config(cfg)` | 注入配置(账号/代理/业务参数) | 创建后立即 |
+| `set_log(logger)` | 注入日志函数 | 创建后立即 |
+| `create_session()` | 登录建会话;抛异常=失败 | 实例化时一次 |
+| `query(apt_type)` | 查档期,返回 `VSQueryResult` | 宿主循环反复调用 |
+| `book(slot_info, user_inputs)` | 抢号,返回 `VSBookResult` | 收到信号/命中档期时 |
+| `keep_alive()` | 保活;**不允许抛异常** | 周期调用 |
+| `health_check()` | 健康探活,返回 bool;**不允许抛异常** | 周期调用 |
+| `cleanup()` | 释放资源(关浏览器/删文件) | 任务销毁/组停止时 |
+
+外加两个约定:
+- 类属性 `name / version / description` —— 这是插件的"身份证",`utils/plugin_updater.py` 用 **AST 静态扫描**(不 import、不执行代码)就能读到版本号做升级判断(`plugin_updater.py:30-65`)。
+- 可选方法 `get_plugin_status()` —— 返回运行状态快照,供状态上报。
+
+**为什么是这 8 个方法?** 这是把"成千上万个具体签证网站"抽象成通用模式后的最小集合。观察所有签证预约网站:都要登录(会话)、都要查日期(查询)、都要填表提交(预订)、都要防掉线(保活)、都要判断登录是否过期(健康)、都要关浏览器(清理)。**变化的(每个网站的协议细节)留给插件,不变的(生命周期节奏、配额、退避、信号、订单流转)留在宿主。** 这就是框架开发的"抽象能力"——区分什么是变的、什么是不变的。
+
+### 1.2 工厂:VSPlgFactory(vs_plg_factory.py,63 行)
+
+```python
+register_plugin(plugin_name, module_path, class_name)  # 注册:名字 → 文件路径 + 类名
+create(group_id, plugin_name) -> IVSPlg               # 动态加载并实例化
+```
+
+关键实现:`importlib.util.spec_from_file_location` 按**文件路径**加载,而不是普通 `import`(`vs_plg_factory.py:41-48`)。
+
+**为什么按路径加载而不是 import?** 因为插件要支持**热升级**:
+1. 云端下发新版本 → 下载到 `plugins/xxx.py`(SHA256 校验 + `py_compile` 语法预检 + 原子替换,`plugin_updater.py:117-170`)
+2. 宿主把正在用旧代码的实例停掉,`sys.modules.pop(plugin_name)` 清掉模块缓存(`main.py:90`)
+3. 下次 `create()` 再加载时,读到的是磁盘上的新文件
+
+如果插件是普通 import 的模块,`sys.modules` 缓存会让"升级"永远加载旧代码。按路径加载 + 显式清缓存,是热升级闭环的地基。
+
+`create()` 里还有一个防御:实例化后强制 `isinstance(instance, IVSPlg)` 校验(`vs_plg_factory.py:54-56`),防止有人写了个"长得像插件但不是插件"的文件。
+
+### 1.3 宿主:GCO 怎么驱动插件
+
+以 Sentinel 为例,创建实例的完整链路(`sentinel.py:246-298`):
+
+```python
+plg_cfg = VSPlgConfig()                    # 组装插件配置
+plg_cfg.account = ...(从云端账号池取,带冷却)   # sentinel.py:261-262
+plg_cfg.proxy = ...(从云端代理池取,带冷却)     # sentinel.py:264-266
+instance = self.m_factory.create(group_id, plugin_name)  # 动态加载
+instance.set_log(logger)
+instance.set_config(plg_cfg)
+instance.create_session()                  # 登录
+task = Task(instance=instance, ...)        # 包进任务对象
+```
+
+之后 monitor 循环只做一件事:`task.instance.query(apt_type)`(`sentinel.py:202`)。发现档期 → 写 Redis 信号,**插件对"信号/Redis/云端"一无所知**。
+
+Booker 侧多了 `book()`:收到信号 → `task.instance.book(query_result, user_inputs)`(`booker.py:388`)。
+
+**设计亮点:宿主把插件当"黑盒工人",插件把宿主当"调度器"。** 插件代码里你找不到任何 Redis 操作、找不到订单队列逻辑——这些全是宿主的事。职责边界清晰到可以各自独立演进:新增一种签证网站 = 新增一个插件文件,框架一行不改;宿主加新能力(比如心跳) = 所有插件自动受益。
+
+---
+
+## 第二部分:vfs_plugin 解剖——一个真实插件做了什么
+
+VFS Global 是全球最大的签证外包商,它的预约系统是典型的 SPA(Angular 前端)+ 独立 API 域(`lift-api.vfsglobal.com`)+ Cloudflare 防护。这个插件就是和这套系统对抗的完整产物。
+
+### 2.0 模块级工具(vfs_plugin.py:1-114)
+
+| 工具 | 作用 | 为什么需要 |
+|---|---|---|
+| `VFS_PUBLIC_KEY_PEM` | VFS 的公钥(RSA) | VFS 登录密码必须 RSA-OAEP 加密后传输(2.3 详述) |
+| `COUNTRY_MAP` | 国家名 → ISO3 代码 | 申请人 payload 里 `nationalityCode` 要 ISO3,用户输入的是英文名 |
+| `get_alias_email()` | `xxx@gmail.com` → `xxx@text.skin` | VFS 邮箱字段校验域名(防虚假邮箱),用别名规避 |
+| `to_yyyymmdd()` | 日期格式转换 | VFS 不同接口返回 `MM/DD/YYYY` / `%m/%d/%Y %H:%M:%S` 等多种格式,统一成 `YYYY-MM-DD` |
+| `BrowserResponse` | 模拟 `requests.Response` | JS fetch 结果是个 dict,包装成类 Response 让上层代码像写普通 HTTP 客户端 |
+
+### 2.1 __init__:每实例完全隔离
+
+```python
+self.instance_id = uuid.uuid4().hex[:8]
+self.root_workspace = "data/temp_browser_data/{group_id}.{instance_id}"
+self.user_data_path = .../user_data
+```
+
+**每个实例有独立的浏览器用户数据目录 + 独立 instance_id。** 这是多实例并发的安全地基:Sentinel 一个组可以 spawn 多个 worker(`target_instances`),Booker 可能同时有 5 个实例,如果共享浏览器目录会互相踩 Cookie/锁文件。
+
+`set_config` 里有个细节(`vfs_plugin.py:155-159`):`free_config.country_code == 'chn'` 时把 API 域名切到 `lift-apicn.vfsglobal.com`——中国区有独立 API 域名。**业务配置(free_config)驱动行为差异,而不是写死在代码里**,这是插件"一文件多场景"的关键。
+
+### 2.2 create_session:四步建会话(vfs_plugin.py:201-373)
+
+#### 第 1 步:拉起浏览器(201-265)
+
+- **随机空闲 debug port**(`get_free_port()`):DrissionPage 走 CDP(Chrome DevTools Protocol),多实例必须端口隔离。
+- **代理接入两种模式**:
+  - 账号密码代理 → 起 **mihomo 隧道**(`MihomoTunnel`):本地起一个 Clash Meta 实例,配置 exit_node=目标代理、可选随机 relay_node=中继节点(`configure.MIHOMO_RELAY_NODES` 随机选),浏览器只连本地 `--proxy-server=127.0.0.1:随机端口`。**为什么这么绕?** 直连代理容易被检测,mihomo 可以做链式路由(出口伪装 + 中继混淆),且每个实例独立隧道进程、独立端口,互不干扰(`toolkit/mihomo_tunnel.py`)。
+  - 无密码代理 → 直接 `--proxy-server={proto}://{ip}:{port}`。
+- 反自动化参数:`--disable-blink-features=AutomationControlled`(去掉 `navigator.webdriver` 标志)、`--no-sandbox`、`--disable-dev-shm-usage`(容器内 /dev/shm 太小)、固定 1920x1080 视口。
+
+#### 第 2 步:过 Cloudflare 盾(278-325)
+
+这是全插件最"硬核"的部分。VFS 登录页挂了 Cloudflare Turnstile(无感验证码),拿不到它的 token 就登录不了。
+
+```python
+for i in range(40):                     # 最多等 40 秒
+    time.sleep(1)
+    ele = self.page.ele('@name=cf-turnstile-response', timeout=1)
+    if ele and ele.value:               # 隐藏 input 里出现 token = 过盾成功
+        cf_token = ele.value
+        break
+    if i > 2:
+        cf_bypasser.click_verification_button(False)  # 主动点验证按钮
+```
+
+配套 `CloudflareBypasser`(`utils/cloudflare_bypass_for_scraping.py`)做两件事:
+- **递归钻 shadow DOM + iframe**(`search_recursively_shadow_root_with_iframe`):Turnstile 组件是"shadow root 套 iframe 再套 shadow root"的俄罗斯套娃,必须一层层钻进去才能找到真正的验证按钮/输入框。
+- **handle_waiting_room**:VFS 高峰有"waiting room"排队页,检测到 `file d'attente` / `waitting room` 就每 10s 轮询,最多等 1 小时。
+
+过盾后从隐藏 input 的 value 里提取 cf_token——**Turnstile token 是登录请求的必填参数**(`captcha_api_key`)。
+
+#### 第 3 步:JS fetch 登录(327-367)——本插件最核心的逆向成果
+
+```python
+enc_password = self._encrypt_password(password)   # RSA-OAEP(SHA256) 加密
+client_src = self._get_client_source()            # RSA("GA;{UTC时间戳}Z")
+orange_src = self._get_orange_source(email)       # RSA("{email};{UTC时间戳}")
+data = {
+    "username": email,
+    "password": enc_password,
+    "captcha_version": "cloudflare-v1",
+    "captcha_api_key": cf_token,                  # Turnstile token
+    ...
+}
+resp = self._perform_request("POST", url, headers=headers, json_data=data)
+```
+
+三个逆向点:
+1. **密码 RSA-OAEP 加密**(`_encrypt_password`,604-613):VFS 前端用公钥加密密码再 POST,`cryptography` 库复刻。
+2. **请求签名**:`clientsource` = RSA 加密 `"GA;{时间戳}Z"`,`orangex` = RSA 加密 `"{email};{时间戳}"`——这是 VFS 的反爬签名(防脚本调用 API),插件把签名算法逆向出来了。
+3. **登录走浏览器内 fetch 而非 requests**(`_perform_request`,2.4 详述)——复用浏览器的 Cookie、TLS 指纹、UA、Origin。
+
+**OTP 分支**(361-364 + 705-781):若账号开了二次验证,登录响应返回 `enableOTPAuthentication`:
+- 用**云端邮件抓取 API**(`VSCloudApi.fetch_mail_content`)读 VFS 发来的 OTP 邮件——不依赖本地邮箱客户端;
+- 先正则找 6 位数字;找不到(VFS 有时把 OTP 做成图片)→ base64 图片丢给 **Qwen-VL 多模态大模型**识别(`toolkit/captcha_breaker.py:46-77`,prompt 甚至知道"OTP 箭头指向的才是真验证码");
+- 重新过盾拿新 Turnstile token(`_refresh_turnstile_token`,783-822:清空 input → `window.turnstile.reset()` → 轮询新 token),带 `otp` 字段重新提交登录。
+
+#### 第 4 步:会话建立后(369-373)
+
+- 记录 `session_create_time`(供 health_check 判定会话寿命);
+- 开**新标签页**查 `api.ipify.org` 拿出口 IP(`_get_realnetwork_ip`,555-583)。**为什么开新标签页而不是 fetch?** 注释写得很清楚:Top-Level Navigation 不带 `Origin` 头也不带 credentials,符合 ipify 的 CORS 规则。这个 IP 后面会作为申请人 payload 的 `ipAddress` 字段——VFS 的风控会校验"填表 IP"和"实际 IP"是否一致,提前拿到可以防误杀。
+
+### 2.3 _perform_request:插件的灵魂(397-526)
+
+**所有 API 调用(登录/查询/预订/保活)都走这一个方法**,它干的事是:把 HTTP 请求翻译成一段 JS,注入浏览器执行 `fetch`,再把结果翻译回 `BrowserResponse`。
+
+```js
+return fetch(url, options)          // credentials: "include" —— 自动带浏览器 Cookie
+    .then(async response => { ... 把 status/body/headers 打包返回 ... })
+```
+
+**为什么坚持用浏览器 fetch 而不是 requests?** 三层原因:
+1. **Cookie 自动携带**:`credentials: include`,浏览器自动带上登录后的会话 Cookie/JWT 相关状态;
+2. **环境指纹一致**:TLS 指纹、UA、`Sec-CH-UA`、`Origin` 全部是真实浏览器值——requests 的 TLS 指纹一眼假;
+3. **CF 盾的延续**:`lift-api` 域也受 Cloudflare 保护,用浏览器上下文发请求天然"过盾"。
+
+代价是性能(每次请求一次 JS 注入 + 网络往返),但正确性优先。
+
+**错误处理是这套系统的精华**——它把"反爬对抗"抽象成了标准 HTTP 语义:
+
+| 状态码 | 插件动作 | 宿主动作(框架层) |
+|---|---|---|
+| 401 | `is_healthy=False` + 抛 `SessionExpiredOrInvalidError` | 宿主销毁实例、重新 spawn(booker.py:498-502) |
+| 403 | 检测到 `"Just a moment"`(CF 盾)→ **自动重新过盾拿新 token → 递归重试**(最多 3 次);否则抛 `PermissionDeniedError` | 宿主退避 |
+| 429 | `is_healthy=False` + 抛 `RateLimiteddError` | 宿主 30s 退避 + 云端锁账号(sentinel.py:281-289) |
+| 0(fetch 网络错误) | 抛 `BizLogicError` | 宿主重试 |
+
+**亮点:403 自动过盾重试**(498-511)。请求打到一半被 CF 拦了,插件不慌:重置 Turnstile → 等新 token → 更新请求里的 `captcha_api_key` → 递归重发。这在抢号场景是生死攸关的——CF 盾可能随时插入,能自动恢复的抢号机才能活下来。
+
+另外注意 `debug` 模式(435-489):完整打印每个请求的 Headers/Body 和响应,这是"逆向调参"时期的可观测性设计,生产关掉避免刷屏(这也是最近 commit 在清理的"verbose logs")。
+
+### 2.4 query:查询链路(375-395 + 625-703)
+
+```python
+apt_config = self.free_config["apt_configs"][routing_key]  # 业务配置:这个 routing_key 对应哪个中心/类别
+self._fetch_configurations(apt_config)                     # 懒加载 master 数据
+result = self._query_earliest_slot(apt_config)             # 查最早档期
+```
+
+- `_query_earliest_slot`(625-646):POST `CheckIsSlotAvailable` → 响应含 `"WaitList"` 或 `earliestSlotLists[0].date`;
+- 结果归一化成 `VSQueryResult`(`availability_status` = Available / Waitlist / NoneAvailable 三态)——**插件内部千奇百怪的响应,出插件必须是统一三态**,这样宿主/信号/云端才能无脑消费。
+
+`_fetch_configurations`(648-703)是性能设计:VFS 的 master 数据(中心列表 → 签证类别 → 子类别)要三级 API 才能拿到,但一个会话内基本不变,所以**惰性加载 + 内存缓存**(`center_conf` / `category_conf` / `subcategory_conf`),只查一次。`_query_center` 用的是 GET 无鉴权接口(678-684),连登录都不需要。
+
+### 2.5 book:预订链路(824-992)——全插件最长的单方法
+
+11 个步骤,按业务顺序:
+
+1. **日期偏好预检**(837-842):`expected_start/end` 是订单用户填的期望区间,`earliest_date` 不在区间内直接放弃——**避免无谓地消耗账号和触发风控**。
+2. **master 配置懒加载**(849)。
+3. **OCR 分支**(854-860):如果该子类别 `isOCREnable`,先把护照照片上传(`_upload_applicant_documents`,1006-1044:支持 URL 下载或本地文件,base64 上传),拿到 `GUID` 等凭证,后面 payload 要用。
+4. **20 秒"冷静期"**(867-870):`booking_wait_applied` 标志位保证**每个插件实例只等一次**——VFS 风控会抓"刚登录就抢号"的行为,先装一会儿人。硬编码 20s,见"风险"。
+5. **提交主申请人**(875,`_add_primary_applicant`,1046-1165):构造一个 **60+ 字段的 applicant payload**——姓名全大写、生日转 `DD/MM/YYYY`、国家名转 ISO3、`ipAddress` 用真实出口 IP、`referenceNumber` 按子类别开关……全是逆向出来的"VFS 想要的格式"。成功后拿到 **URN**(预约单号)。失败重试 2 次,但 `"Capping has exceeded"`(当日预约上限)**不重试**(880-881)——识别"不可恢复错误"并立刻止损。
+6. **申请人 OTP**(889-899):`isApplicantOTPEnabled` 子类别 → 发 OTP → 云邮件读 → 验证。注意 `_applicant_otp_verify` 给 header 加了 `datacenter: GERMANY`(1187)——逆向出的又一个隐藏要求。
+7. **Waitlist 分流**(901-908):如果查到的档期是 Waitlist,走 `ConfirmWaitlist` 接口直接确认,流程结束——**不用选日期,因为日期不可选**。
+8. **按月扫日历选日期**(910-958):从 `expected_start` 到 `expected_end` 生成月份列表(`_get_filtered_covered_months`)→ 逐月 `_query_slot_calendar` 拿可预约日期 → 累积去重 → `_filter_dates` 过滤出区间内日期并 **random.shuffle 打乱**(防"每次都选同一天"的机器人特征)→ 对每个候选日期先 `_saveuseractionaudit`(**VFS 要求的"用户操作审计"步骤,不调这个接口就选不了时间**)→ `_query_slot_time` 拿时间段 → `random.choice` 随机选一个。
+9. **跳过增值服务 + 查费用**(967-968):`_submit_no_addition_service`(`/vas/mapvas`,不选任何 VAS)→ `_query_fee` 拿金额和币种。
+10. **提交预订**(971-976):`/appointment/schedule`,带 `allocationId`(选中时间段的 ID)和支付信息 → `IsAppointmentBooked` 判定成败。
+11. **支付链接解析**(984-991):如需在线支付,`_pay_request`(1324-1348)开新标签页访问 VFS 支付组件,等 URL 跳转后把最终支付链接抓回来——**返回给订单用户去付款**,机器人不替用户付钱。
+
+### 2.6 keep_alive / health_check(170-199)
+
+```python
+def keep_alive(self):
+    keep_alive_funcs = [self._get_application, self._query_center]
+    random.choice(keep_alive_funcs)()   # 随机挑一个真实 API 打一下
+```
+
+**亮点:保活不是发心跳包,而是随机执行一个真实业务 API。** 既维持了会话活性,又模拟了真实用户行为(对风控更友好)。失败则 `is_healthy=False`。
+
+`health_check` 三重判定:`is_healthy` 标志 + 页面 `run_js("return 1;")` 探活 + `session_max_life` 超时(超时返回 False,宿主重建会话)。两个方法都"不允许抛异常"——契约里写死的,因为宿主循环里任何异常都会打乱调度节奏。
+
+### 2.7 cleanup / get_plugin_status(1407-1460)
+
+- `cleanup`:关浏览器 → **删临时目录(3 次重试)** → 停 mihomo 隧道。抢号机跑久了会产生大量浏览器 profile(每个实例几十 MB),不删干净磁盘会爆;
+- `get_plugin_status`:把内部状态翻译成 `PluginStatus`(instance_id / account / proxy / current_url / session_age / state:`running` / `logging_in` / `unhealthy`)——宿主聚合后上报云端做监控大屏;
+- `__del__` 兜底:对象被 GC 时也尝试清理(防异常路径泄漏)。
+
+---
+
+## 第三部分:为什么这么设计——设计哲学总结
+
+1. **契约是"最小共识"**:8 个方法恰好覆盖"任何签证网站都要做的事",多一个侵入、少一个残缺。插件作者只需要看 `vs_plg.py` 一个文件就能写插件——低门槛;而宿主通过异常体系(401/403/429)获得"通用决策能力"——高天花板。这就是"Low Floor, High Ceiling"。
+
+2. **控制反转**:不是插件调用框架("我要查档期了"),而是框架调用插件("该你查了")。插件不知道 Redis、不知道订单队列、不知道信号,它只对 `query/book` 的入参出参负责。**替换插件 = 替换工人,不换工厂。**
+
+3. **对抗性设计内聚在插件里**:反爬对抗(CF 过盾、RSA 签名、浏览器 fetch、拟人化等待)全部在插件内部消化,框架层的调度逻辑保持纯净、可测试。框架只依赖"插件会按契约工作"这个信念。
+
+4. **归一化接口**:VFS 的三种档期状态(有/无/waitlist)→ 统一 `AvailabilityStatus`;千奇百怪的日期格式 → 统一 `YYYY-MM-DD`;浏览器 fetch 结果 → 统一 `BrowserResponse`。**接口的稳定性就是插件的可替换性。**
+
+5. **生产级资源管理**:实例隔离(独立端口/独立目录)、原子清理、`__del__` 兜底、内存缓存、失败重试带"不可恢复错误识别"——这些是"能长期跑"和"演示能跑"的分界线。
+
+---
+
+## 第四部分:亮点清单(vfs 插件值得抄作业的地方)
+
+| # | 亮点 | 位置 |
+|---|---|---|
+| 1 | **403 自动过盾重试**:请求被 CF 拦截后自动重置 Turnstile、换 token、递归重发,抢号机在盾前能自愈 | 498-511 |
+| 2 | **逆向 VFS 请求签名**:RSA-OAEP 加密的 `clientsource`/`orangex` 头 + 密码加密 | 604-623 |
+| 3 | **保活 = 随机真实业务 API**:既是心跳又是行为仿真 | 170-180 |
+| 4 | **OTP 双通道读取**:云邮件正文正则 → 失败再上 Qwen-VL 识图 | 705-737 |
+| 5 | **master 配置惰性缓存**:三级元数据只拉一次,会话内复用 | 648-703 |
+| 6 | **风控前置**:20s 冷静期(仅一次)、日期随机化、真实 IP 预取、审计步骤补齐 | 867/1376/555/1249 |
+| 7 | **不可恢复错误识别**:`Capping has exceeded` 不重试,止损 | 880-881 |
+| 8 | **可观测性**:debug 模式完整 TRAFFIC 日志 | 435-489 |
+| 9 | **多态适配**:Waitlist / OTP / OCR / 参考号,全部由子类别配置开关驱动,一个插件覆盖全球几十个中心 | 854/889/1136 |
+| 10 | **实例级隔离 + 彻底清理**:独立 profile、独立隧道、删除重试 | 144-150 / 1407-1434 |
+
+---
+
+## 第五部分:客观风险与可改进点(不做改动,仅记录)
+
+1. **`time.sleep(20)` 硬编码**(869):冷静期不可配置,改时长要改代码。建议进 `free_config`。
+2. **`master_email = "hujiarui8@gmail.com"` 硬编码**(707):读 OTP 邮件的"主邮箱"写死在代码里,换运营人就要改代码。建议进配置。
+3. **保活调用随机二选一**(172-175):`_query_center` 是 GET 全量中心列表(较重的响应),高频随机到它浪费带宽。可换成更轻的接口。
+4. **`real_ip` 获取失败 fallback 到代理 IP**(373):代理 IP 与风控记录可能不符,极端情况会误伤账号。值得观察线上日志。
+5. **OTP 图片识别依赖具体邮件模板**:prompt 里写死"OTP 箭头指向的验证码"(captcha_breaker.py:53),VFS 改模板就失效——属"对抗的宿命",但要知道这个脆弱点。
+6. **`_perform_request` 每次全量打印响应体**(debug 模式):响应 1KB 截断打印,已比早期好,仍建议加开关。
+
+---
+
+## 附:如果你要新写一个插件(比如接一个新签证网站)
+
+1. 复制 `prt_plugin.py`(最小骨架)或参考 `vfs_plugin.py` 结构;
+2. 只实现 8 个契约方法,遵守两条铁律:`keep_alive`/`health_check` 不抛异常;`create_session` 失败抛异常;
+3. 业务差异全放 `free_config`(用 `apt_configs` 按 routing_key 给配置),**不要写死任何中心/类别代码**;
+4. 所有 HTTP 走 `_perform_request` 式浏览器 fetch(如果网站有反爬)或 requests(如果网站裸奔),但**响应必须归一化成 `VSQueryResult` 三态**;
+5. 上传到云端插件仓库 → 下发 → 节点秒级热升级,框架零改动。

+ 1106 - 487
plugins/ita_plugin.py

@@ -1,559 +1,1178 @@
-import time
+"""Prenot@Mi Query/Book adapter; Italy-specific production code stays here."""
+from __future__ import annotations
+
+import html
 import json
+import os
 import random
 import re
-import os
+import sys
+import time
 import uuid
-import base64
-from datetime import datetime
-from typing import List, Dict, Optional, Any, Callable
-from DrissionPage import ChromiumPage
+from dataclasses import asdict, dataclass, field
+from datetime import date, datetime, time as datetime_time, timezone
+from enum import Enum
+from threading import Lock
+from typing import Any, Mapping, Sequence
+from urllib.parse import urljoin, urlparse
 
+from DrissionPage import ChromiumPage
+import vs_plg as _ita_host
 from vs_plg import IVSPlg
 from vs_types import (
-    VSPlgConfig, 
-    AppointmentType, 
-    VSQueryResult, 
-    VSBookResult, 
-    AvailabilityStatus, 
-    TimeSlot, 
-    DateAvailability, 
-    NotFoundError, 
-    PermissionDeniedError, 
-    RateLimiteddError, 
-    SessionExpiredOrInvalidError, 
-    BizLogicError, 
-    PluginStatus, 
-    utc_now_str
+    AvailabilityStatus, BizLogicError,
+    DateAvailability, PermissionDeniedError, PluginStatus, RateLimiteddError,
+    SessionExpiredOrInvalidError, VSBookResult, VSQueryResult, utc_now_str,
 )
 from toolkit.vs_cloud_api import VSCloudApi
 from utils.cloudflare_bypass_for_scraping import CloudflareBypasser
-from utils.mouse import HumanMouse
+from utils.flow_engine import BaseFlow, done, guard, on
 from utils.keyboard import HumanKeyboard
-from utils.flow_engine import BaseFlow, on, guard, done, fatal
+from utils.mouse import HumanMouse
 from utils.plugin_utils import (
-    BrowserResponse,
-    init_chromium_options,
+    cleanup_browser_workspace, filter_dates_in_range, init_chromium_options,
     perform_browser_fetch,
-    filter_dates_in_range,
-    cleanup_browser_workspace
 )
 
 
-class ItaLoginFlow(BaseFlow):
-    """
-    基于 BaseFlow 注解状态机驱动的意大利 Prenot@Mi 会话创建与自动导航流
-    """
-    def __init__(self, page, plugin: 'ItaPlugin', interval: float = 1.0):
-        super().__init__(
-            page=page, 
-            config=plugin.config, 
-            context={"plugin": plugin}, 
-            interval=interval, 
-            logger=plugin._log, 
-            cf_bypasser=CloudflareBypasser(page, log=plugin.config.debug if plugin.config else False)
+MAX_PROTOCOL_ITEMS = 512
+MAX_PROTOCOL_PAYLOAD_CHARS = 1_000_000
+MAX_LOOKAHEAD_MONTHS = 120
+PRENOTAMI_OTP_SENDER = "noreply-prenotami@esteri.it"
+_EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+_OTP_PATTERN = re.compile(r"(?<!\w)OTP\s+Code\s*:\s*([0-9]{6})(?!\w)", re.I)
+
+
+class ItaProtocolError(ValueError):
+    def __init__(self, code: str, message: str = "rejected", *, path: str = ""):
+        self.code, self.path = code, path
+        super().__init__(f"Italy protocol error [{code}]" + (f" at {path}" if path else "") + f": {message}")
+
+
+class ItaCapability(str, Enum):
+    SERVICES_PROBE_ONLY = "services_probe_only"
+    SINGLE_SCHENGEN_TOURISM = "single_schengen_tourism"
+
+
+@dataclass(frozen=True, slots=True)
+class FormControlConfig:
+    control_id: str
+    value: str
+    labels: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class OtpMailConfig:
+    authorization_email: str | None = field(default=None, repr=False)
+    subject_keywords: str = "OTP Code"
+    body_keywords: str = "OTP Code:"
+    expiry_seconds: int = 300
+    authorization_source: str = "configured"
+
+    def __post_init__(self):
+        if self.authorization_source not in {"account", "configured"}:
+            raise ItaProtocolError("otp_authorization_source_invalid")
+        if self.authorization_source == "account" and self.authorization_email is not None:
+            raise ItaProtocolError("otp_authorization_source_conflict")
+        if self.authorization_source == "configured":
+            self.mailbox_for("")
+        if type(self.expiry_seconds) is not int or not 1 <= self.expiry_seconds <= 300:
+            raise ItaProtocolError("otp_expiry_invalid")
+        if (self.subject_keywords, self.body_keywords) != ("OTP Code", "OTP Code:"):
+            raise ItaProtocolError("otp_filter_invalid")
+
+    def mailbox_for(self, account_email: str) -> str:
+        value = account_email if self.authorization_source == "account" else self.authorization_email
+        if not isinstance(value, str) or not _EMAIL_PATTERN.fullmatch(value.strip()):
+            raise ItaProtocolError("otp_authorization_email_invalid", path="mail.authorization_email")
+        return value.strip()
+
+
+@dataclass(frozen=True, slots=True)
+class ItaRouteConfig:
+    routing_key: str
+    service_id: int
+    capability: ItaCapability
+    lookahead_months: int = 0
+    booking_type: FormControlConfig | None = None
+    purpose: FormControlConfig | None = None
+    mail: OtpMailConfig | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CalendarDay:
+    day: date
+    slots_free: int
+    slots_remaining: int
+
+    @property
+    def is_available(self):
+        return self.slots_free > 0
+
+
+@dataclass(frozen=True, slots=True)
+class SlotCandidate(CalendarDay):
+    start_time: datetime_time
+    end_time: datetime_time
+    daily_calendar_id: str = field(repr=False)
+
+    @property
+    def time_label(self):
+        return f"{self.start_time:%H:%M} - {self.end_time:%H:%M}"
+
+
+def _positive_int(value, path, maximum=None):
+    if type(value) is not int or value <= 0:
+        raise ItaProtocolError("positive_integer_required", path=path)
+    if maximum is not None and value > maximum:
+        raise ItaProtocolError("lookahead_too_large", path=path)
+    return value
+
+
+def _mapping(value, path):
+    if not isinstance(value, Mapping):
+        raise ItaProtocolError("mapping_required", path=path)
+    return value
+
+
+def _text(value, path):
+    if not isinstance(value, str) or not value.strip():
+        raise ItaProtocolError("string_required", path=path)
+    return value.strip()
+
+
+def _control(form, prefix, path):
+    labels = form.get(f"{prefix}_labels")
+    if isinstance(labels, (str, bytes)) or not isinstance(labels, Sequence) or not labels:
+        raise ItaProtocolError("labels_required", path=path)
+    labels = tuple(_text(value, path) for value in labels)
+    if len(set(labels)) != len(labels):
+        raise ItaProtocolError("labels_duplicate", path=path)
+    return FormControlConfig(
+        _text(form.get(f"{prefix}_control_id"), path),
+        _text(form.get(f"{prefix}_value"), path),
+        labels,
+    )
+
+
+def resolve_route_config(configs: Mapping[str, Any], routing_key: str) -> ItaRouteConfig:
+    configs, key = _mapping(configs, "apt_configs"), _text(routing_key, "routing_key")
+    if key not in configs:
+        raise ItaProtocolError("route_missing", path="apt_configs")
+    raw = _mapping(configs[key], key)
+    capability_name = _text(raw.get("capability"), f"{key}.capability")
+    try:
+        capability = ItaCapability(capability_name)
+    except ValueError:
+        raise ItaProtocolError("capability_unsupported", path=f"{key}.capability") from None
+    service = _positive_int(raw.get("service_id"), f"{key}.service_id")
+    if capability is ItaCapability.SERVICES_PROBE_ONLY:
+        return ItaRouteConfig(key, service, capability)
+    form = _mapping(raw.get("form"), f"{key}.form")
+    scan = _mapping(raw.get("calendar_scan"), f"{key}.calendar_scan")
+    mail_raw = raw.get("mail")
+    mail = None
+    if mail_raw is not None:
+        mail_raw = _mapping(mail_raw, f"{key}.mail")
+        if str(mail_raw.get("sender", PRENOTAMI_OTP_SENDER)).strip().casefold() != PRENOTAMI_OTP_SENDER:
+            raise ItaProtocolError("otp_sender_not_allowlisted", path=f"{key}.mail.sender")
+        source = mail_raw.get("authorization_source", "configured")
+        mail = OtpMailConfig(
+            mail_raw.get("authorization_email"),
+            mail_raw.get("subject_keywords", "OTP Code"),
+            mail_raw.get("body_keywords", "OTP Code:"),
+            mail_raw.get("expiry_seconds", 300), source,
         )
-        self.plugin = plugin
-        self.has_submitted_login = False
-
-    # --- 异常守卫与自愈 (Priority 5~7) ---
-    @guard(text="502 Bad Gateway", priority=5)
-    @guard(text="503 Service Temporarily Unavailable", priority=5)
-    @guard(text="error 1020", priority=5)
-    def on_server_network_error(self):
-        self.log("[WARN] 检测到服务器网络错误 (502/503/1020),等待并刷新自愈...", level="warning")
-        self.plugin._random_sleep(10, 15)
-        self.page.refresh()
+    return ItaRouteConfig(
+        key, service, capability,
+        _positive_int(scan.get("lookahead_months"), f"{key}.calendar_scan", MAX_LOOKAHEAD_MONTHS),
+        _control(form, "booking_type", f"{key}.form"),
+        _control(form, "purpose", f"{key}.form"),
+        mail,
+    )
+
+
+def decode_double_json_array(payload: str, *, max_items: int = MAX_PROTOCOL_ITEMS):
+    if not isinstance(payload, str) or not payload:
+        raise ItaProtocolError("payload_type")
+    if len(payload) > MAX_PROTOCOL_PAYLOAD_CHARS:
+        raise ItaProtocolError("payload_too_large")
+    if type(max_items) is not int or max_items <= 0:
+        raise ItaProtocolError("max_items_invalid")
+    try:
+        inner = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise ItaProtocolError("outer_json_invalid") from exc
+    if not isinstance(inner, str):
+        raise ItaProtocolError("payload_layer_count")
+    try:
+        records = json.loads(inner)
+    except json.JSONDecodeError as exc:
+        raise ItaProtocolError("inner_json_invalid") from exc
+    if not isinstance(records, list):
+        raise ItaProtocolError("payload_layer_count")
+    if len(records) > max_items:
+        raise ItaProtocolError("item_limit_exceeded")
+    if not all(isinstance(item, Mapping) for item in records):
+        raise ItaProtocolError("item_type")
+    return tuple(records)
+
+
+def _site_date(value, path):
+    if not isinstance(value, str) or not re.fullmatch(r"\d{2}/\d{2}/\d{4} 00:00:00", value):
+        raise ItaProtocolError("date_format", path=path)
+    try:
+        return datetime.strptime(value, "%d/%m/%Y %H:%M:%S").date()
+    except ValueError as exc:
+        raise ItaProtocolError("date_invalid", path=path) from exc
+
+
+def _integer(item, key, path):
+    if key not in item:
+        raise ItaProtocolError("field_missing", path=f"{path}.{key}")
+    if type(item[key]) is not int:
+        raise ItaProtocolError("integer_required", path=f"{path}.{key}")
+    return item[key]
+
+
+def _clock(value, path):
+    value = _mapping(value, path)
+    parts = [_integer(value, key, path) for key in (
+        "Hours", "Minutes", "Seconds", "Milliseconds")]
+    if parts[2] or parts[3]:
+        raise ItaProtocolError("time_precision", path=path)
+    try:
+        return datetime_time(parts[0], parts[1])
+    except ValueError as exc:
+        raise ItaProtocolError("time_invalid", path=path) from exc
+
+
+def _parse_calendar_items(payload, time_slots=False, max_items=MAX_PROTOCOL_ITEMS):
+    records, identities, daily_ids = [], set(), set()
+    for index, item in enumerate(decode_double_json_array(payload, max_items=max_items)):
+        path = f"{'time_slots' if time_slots else 'availability'}[{index}]"
+        free, remaining = _integer(item, "SlotLiberi", path), _integer(item, "SlotRimanenti", path)
+        if not ((free > 0 and remaining >= 0) or (free == 0 and remaining < 0)):
+            raise ItaProtocolError("inventory_conflict", path=path)
+        day = _site_date(item.get("Data" if time_slots else "DateLibere"), path)
+        if time_slots:
+            start = _clock(item.get("OrarioInizioFascia"), f"{path}.OrarioInizioFascia")
+            end = _clock(item.get("OrarioFineFascia"), f"{path}.OrarioFineFascia")
+            if start >= end:
+                raise ItaProtocolError("time_range_invalid", path=path)
+            daily_id = _integer(item, "IDCalendarioServizioGiornaliero", path)
+            if daily_id <= 0:
+                raise ItaProtocolError("positive_integer_required", path=path)
+            if daily_id in daily_ids:
+                raise ItaProtocolError("duplicate_daily_id", path=path)
+            daily_ids.add(daily_id)
+            record = SlotCandidate(day, free, remaining, start, end, str(daily_id))
+            identity = day, start, end
+        else:
+            record, identity = CalendarDay(day, free, remaining), day
+        if identity in identities:
+            raise ItaProtocolError("duplicate_time_range" if time_slots else "duplicate_calendar_day")
+        identities.add(identity)
+        records.append(record)
+    return tuple(sorted(records, key=lambda item: (item.day, getattr(item, "start_time", datetime_time.min))))
+
+
+def parse_calendar_availability(payload: str, *, max_items: int = MAX_PROTOCOL_ITEMS):
+    return _parse_calendar_items(payload, max_items=max_items)
+
+
+def parse_time_slots(payload: str, *, max_items: int = MAX_PROTOCOL_ITEMS):
+    return _parse_calendar_items(payload, time_slots=True, max_items=max_items)
+
+
+def _available_inventory(items, *, start_day=None, end_day=None):
+    if start_day and end_day and start_day > end_day:
+        raise ItaProtocolError("date_range_invalid")
+    allowed = set(filter_dates_in_range(
+        [item.day.isoformat() for item in items],
+        (start_day or date.min).isoformat(), (end_day or date.max).isoformat(),
+        shuffle=False,
+    ))
+    return tuple(item for item in sorted(
+        (item for item in items if item.is_available and item.day.isoformat() in allowed),
+        key=lambda item: (item.day, getattr(item, "start_time", datetime_time.min)),
+    ))
+
+
+available_calendar_days = available_slot_candidates = _available_inventory
+
+
+def parse_otp_body(body: str, *, max_chars: int = MAX_PROTOCOL_PAYLOAD_CHARS):
+    if not isinstance(body, str) or not body.strip():
+        raise ItaProtocolError("otp_body_invalid")
+    if len(body) > max_chars:
+        raise ItaProtocolError("otp_body_too_large")
+    values = set(_OTP_PATTERN.findall(html.unescape(re.sub(r"<[^>]*>", " ", body))))
+    if len(values) != 1:
+        raise ItaProtocolError("otp_not_found" if not values else "otp_ambiguous")
+    return values.pop()
+
+
+def month_starts(anchor_day: date, lookahead_months: int):
+    months = _positive_int(lookahead_months, "lookahead_months", MAX_LOOKAHEAD_MONTHS)
+    return tuple(date(anchor_day.year + (anchor_day.month - 1 + i) // 12,
+                      (anchor_day.month - 1 + i) % 12 + 1, 1) for i in range(months))
+
+
+CALENDAR_PATH = "/BookingCalendar"
+AVAILABILITY_PATH = "/BookingCalendar/RetrieveCalendarAvailability"
+TIME_SLOTS_PATH = "/BookingCalendar/RetrieveTimeSlots"
+DEFAULT_MONTH_CLICK_INTERVAL_SECONDS = 1.5
+
+
+class CalendarGateError(RuntimeError): pass
+class CalendarAuthenticationExpiredError(CalendarGateError): pass
+class CalendarRateLimitedError(CalendarGateError): pass
+class CalendarAccessDeniedError(CalendarGateError): pass
+class CalendarTransientError(CalendarGateError): pass
+class CalendarBookError(CalendarGateError): pass
+
+
+def same_origin_path(raw_url):
+    parsed = urlparse(str(raw_url or ""))
+    if parsed.scheme != "https" or parsed.hostname != "prenotami.esteri.it":
+        raise CalendarGateError("Italy request left the expected origin")
+    return parsed.path
+
+
+CALENDAR_DOM_SCRIPT = r"""
+const [mode, serviceId, day, dailyId, timeLabel, capacity, shouldClick] = arguments;
+const all = (selector, root = document) => Array.from(root.querySelectorAll(selector));
+const services = all('#idServizio'), timeline = all('.events a.selected[data-date]');
+const service = services.length === 1 ? services[0].value : '';
+const selectedDay = timeline.length === 1 ? timeline[0].dataset.date : '';
+if (mode === 'context') return {path: location.pathname, service, day: selectedDay};
+const contextReady = location.pathname === '/BookingCalendar' && service === serviceId;
+const links = all('.events a[data-date]').filter(item => item.dataset.date === day);
+const link = links.length === 1 ? links[0] : null;
+if (mode === 'date') {
+  const candidateReady = Boolean(contextReady && link &&
+    !link.classList.contains('notAvailableDay') && !link.classList.contains('disabled'));
+  let selected = Boolean(candidateReady && link.classList.contains('selected')), clicked = false;
+  if (shouldClick && candidateReady && !selected) { link.click(); clicked = true; }
+  selected = Boolean(candidateReady && link.classList.contains('selected'));
+  return {contextReady, candidateCount: links.length, candidateReady, selected, clicked};
+}
+const content = all('.events-content li.selected').find(item => item.dataset.date === day);
+const matches = content ? all('.fascia', content).filter(slot => {
+  const input = slot.querySelector('#idHiddenFasciaServizio');
+  return input && input.value === dailyId;
+}) : [];
+const slot = matches.length === 1 ? matches[0] : null, spans = slot ? slot.querySelectorAll('span') : [];
+const clean = value => String(value || '').replace(/\s+/g, ' ').trim();
+const candidateReady = Boolean(contextReady && slot && !slot.classList.contains('notAvailableFascia') &&
+  spans.length === 2 && clean(spans[0].textContent) === timeLabel &&
+  clean(spans[1].textContent) === `(${capacity})`);
+let selected = Boolean(candidateReady && slot.classList.contains('act')), clicked = false;
+if (shouldClick && candidateReady && !selected) { slot.click(); clicked = true; }
+selected = Boolean(candidateReady && slot.classList.contains('act'));
+return {contextReady, candidateCount: matches.length, candidateReady, selected, clicked};
+"""
+def _runtime_id(value):
+    value = str(value).strip()
+    if not value or len(value) > 128:
+        raise CalendarBookError("Italy Calendar service id is invalid")
+    return value
+
+
+def _request_day(value):
+    try:
+        return date.fromisoformat(str(value))
+    except ValueError:
+        raise CalendarBookError("Italy Calendar date format changed") from None
+
+
+def read_calendar_context(page):
+    if same_origin_path(page.url) != CALENDAR_PATH:
+        raise CalendarBookError("Italy Calendar page is not current")
+    raw = page.run_js(CALENDAR_DOM_SCRIPT, "context", "", "", "", "", 0, False)
+    if not isinstance(raw, dict) or raw.get("path") != CALENDAR_PATH:
+        raise CalendarBookError("Italy Calendar context is not ready")
+    return _runtime_id(raw.get("service")), _request_day(raw.get("day"))
+
+
+def read_calendar_service(page):
+    return read_calendar_context(page)[0]
+
+
+def wait_for_calendar_service(page, *, session_is_current, expected_service=None, timeout=5):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if session_is_current() is not True:
+            raise CalendarBookError("Italy applicant Session changed")
         try:
-            self.page.wait.doc_loaded()
-        except Exception:
-            pass
+            service = read_calendar_service(page)
+        except CalendarBookError:
+            time.sleep(0.1)
+            continue
+        if expected_service and service != _runtime_id(expected_service):
+            raise CalendarBookError("Italy Calendar service changed")
+        return service
+    raise CalendarBookError("Italy Calendar service did not initialize")
 
-    @guard(text="Sorry, you have been blocked", priority=6)
-    @guard(text="You are being rate limited", priority=6)
-    @guard(text="Cloudflare Ray ID", priority=6)
-    @fatal("Blocked by Cloudflare WAF. Need to change IP or browser fingerprint.")
-    def on_cloudflare_blocked(self):
-        pass
 
-    @guard(title="just a moment", priority=7)
-    def on_cloudflare_turnstile_challenge(self):
-        self.log("🛡️ 检测到 Cloudflare 5秒盾挑战,正在尝试穿透...")
-        if self.cf_bypasser.bypass(max_retry=3):
-            self.plugin._random_sleep(3, 5)
-            self.cf_bypasser.handle_waiting_room()
-
-    @guard(title="waitting room", priority=7)
-    def on_cloudflare_waiting_room(self):
-        self.log("🛡️ 检测到 Cloudflare 等候室,正在等待自动排队刷新...")
-        self.cf_bypasser.handle_waiting_room()
-        time.sleep(2)
-
-    # --- 状态流转与表单处理 (Priority 35~45) ---
-    @on(ele="#pingid-button", priority=45)
-    def handle_initial_landing_page(self):
-        self.log("[State] Initial Landing Page detected. Clicking login button...")
-        login_btn = self.page.ele('#pingid-button')
-        if login_btn:
-            self.plugin.mouse.human_click_ele(login_btn)
-        self.log("Redirecting to PingID...")
-        self.plugin._random_sleep(3, 5)
+def _calendar_post(page, path, payload, parser):
+    response = perform_browser_fetch(page, "POST", path, json_data=payload, timeout=30)
+    status, host = response.status_code, urlparse(str(response.url or "")).hostname
+    if host == "iam.esteri.it" or status == 401:
+        raise CalendarAuthenticationExpiredError("Italy Calendar authentication expired")
+    if status == 403:
+        raise CalendarAccessDeniedError("Italy Calendar access denied")
+    if status == 429:
+        raise CalendarRateLimitedError("Italy Calendar rate limited")
+    if status in {0, 408, 502, 503, 504}:
+        raise CalendarTransientError("Italy Calendar temporarily unavailable")
+    if status != 200 or same_origin_path(response.url) != path:
+        raise CalendarGateError("Italy Calendar returned an unexpected response")
+    try:
+        return parser(response.text)
+    except ItaProtocolError as exc:
+        raise CalendarGateError(f"Italy Calendar response rejected ({exc.code})") from exc
 
-    @on(ele="@name=callback_1", priority=40)
-    def handle_pingid_login_form(self):
-        if self.has_submitted_login:
-            return
-        self.log("[State] PingID Login Form detected. Submitting credentials...")
-        username = self.plugin.config.account.username
-        password = self.plugin.config.account.password
-
-        self.log("Entering username...")
-        user_input = self.page.ele('@name=callback_1')
-        self.plugin.mouse.human_click_ele(user_input)
-        user_input.input(username, clear=True)
-        time.sleep(1)
 
-        self.log("Entering password...")
-        pwd_input = self.page.ele('@type=password')
-        self.plugin.mouse.human_click_ele(pwd_input)
-        pwd_input.input(password, clear=True)
+def fetch_calendar_month(page, service, selected_day):
+    selected = selected_day.strftime("%d/%m/%Y")
+    return _calendar_post(
+        page, AVAILABILITY_PATH,
+        {"_Servizio": _runtime_id(service), "selectedDay": selected},
+        parse_calendar_availability,
+    )
+
+
+def fetch_calendar_slots(page, service, selected_day):
+    slots = _calendar_post(
+        page, TIME_SLOTS_PATH,
+        {"selectedDay": selected_day.isoformat(), "idService": _runtime_id(service)},
+        parse_time_slots,
+    )
+    if any(slot.day != selected_day for slot in slots):
+        raise CalendarBookError("Italy Calendar returned slots for another day")
+    return slots
+
+
+def scan_until_first_available_month(
+    page, *, lookahead_months, log=None,
+    month_click_interval_seconds=DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
+):
+    service, anchor = read_calendar_context(page)
+    scans = []
+    for index, month in enumerate(month_starts(anchor, lookahead_months)):
+        if index and month_click_interval_seconds:
+            time.sleep(month_click_interval_seconds)
+        days = fetch_calendar_month(page, service, month)
+        scans.append(days)
+        available = available_calendar_days(days)
+        if log:
+            log(f"Italy Calendar probe index={index} available={len(available)}")
+        if available:
+            break
+    return tuple(scans)
+
+
+def click_next_month(page, *, timeout=10, diagnostic=None):
+    control = page.ele("css:#datetimepicker th.dtpicker-next", timeout=timeout)
+    if not control:
+        raise CalendarBookError("Italy Calendar next-month control is unavailable")
+    control.click(by_js=True)
+
+
+def _snapshot(page, mode, service, day, candidate=None, click=False):
+    candidate = candidate or SlotCandidate(day, 0, -1, datetime_time.min, datetime_time.min, "")
+    raw = page.run_js(
+        CALENDAR_DOM_SCRIPT, mode, service, day.isoformat(), candidate.daily_calendar_id,
+        candidate.time_label, candidate.slots_free, click,
+    )
+    if not isinstance(raw, dict) or not raw.get("contextReady") or raw.get("candidateCount") != 1:
+        raise CalendarBookError("Italy Calendar selection context changed")
+    return raw
+
+
+def verify_precommit_selection(page, *, runtime_service, candidate):
+    raw = _snapshot(
+        page, "slot", runtime_service, candidate.day, candidate, False)
+    if not raw.get("candidateReady") or not raw.get("selected"):
+        raise CalendarBookError("Italy Calendar selected slot changed")
+    return candidate
+
+
+def select_slot_before_final(
+    page, *, target_day, days, slots, runtime_service,
+    dom_timeout=5, session_is_current=None,
+):
+    inventory = [item for item in days if item.day == target_day and item.is_available]
+    candidates = available_slot_candidates(slots, start_day=target_day, end_day=target_day)
+    if not inventory or not candidates:
+        return None
+    candidate, deadline = candidates[0], time.monotonic() + dom_timeout
+    _snapshot(page, "date", runtime_service, target_day, click=True)
+    while time.monotonic() < deadline:
+        if session_is_current and session_is_current() is not True:
+            raise CalendarBookError("Italy applicant Session changed")
+        date_state = _snapshot(page, "date", runtime_service, target_day)
+        slot_state = _snapshot(page, "slot", runtime_service, target_day, candidate)
+        if date_state.get("selected") and slot_state.get("candidateReady"):
+            if not slot_state.get("selected"):
+                _snapshot(page, "slot", runtime_service, target_day, candidate, True)
+            return verify_precommit_selection(
+                page, runtime_service=runtime_service, candidate=candidate)
+        time.sleep(0.1)
+    raise CalendarBookError("Italy Calendar slot did not finish loading")
+
+
+def book_date_preferences(user_inputs):
+    values = []
+    for key, default in (("expected_start_date", "2000-01-01"),
+                         ("expected_end_date", "2100-01-01")):
+        try:
+            values.append(date.fromisoformat(user_inputs.get(key, default)))
+        except (AttributeError, TypeError, ValueError):
+            raise CalendarBookError(f"Italy {key} must use YYYY-MM-DD") from None
+    if values[0] > values[1]:
+        raise CalendarBookError("Italy date preference is inverted")
+    return tuple(values)
+
+
+def _move_to_month(page, service, target, timeout):
+    current = read_calendar_context(page)[1]
+    while (current.year, current.month) < target:
+        expected = (current.year + 1, 1) if current.month == 12 else (current.year, current.month + 1)
+        click_next_month(page, timeout=timeout)
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            actual_service, current = read_calendar_context(page)
+            if actual_service != service:
+                raise CalendarBookError("Italy Calendar service changed")
+            if (current.year, current.month) == expected:
+                break
+            time.sleep(0.1)
+        else:
+            raise CalendarBookError("Italy Calendar month did not load")
+    if (current.year, current.month) != target:
+        raise CalendarBookError("Italy Calendar cannot navigate backwards")
+
+
+def recheck_calendar_before_final(
+    page, *, lookahead_months, start_day, end_day, session_is_current,
+    month_click_interval_seconds=DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
+    timeout=30, dom_timeout=5, log=None,
+):
+    service, anchor = read_calendar_context(page)
+    for index, month_start in enumerate(month_starts(anchor, lookahead_months)):
+        if session_is_current() is not True:
+            raise CalendarBookError("Italy applicant Session changed")
+        if index and month_click_interval_seconds:
+            time.sleep(month_click_interval_seconds)
+        inventory = fetch_calendar_month(page, service, month_start)
+        days = available_calendar_days(inventory, start_day=start_day, end_day=end_day)
+        selected_month = month_start.year, month_start.month
+        if log:
+            log(f"Italy Book Calendar month={month_start:%Y-%m} candidates={len(days)}")
+        if days:
+            _move_to_month(page, service, selected_month, timeout)
+        for item in days:
+            slots = fetch_calendar_slots(page, service, item.day)
+            candidate = select_slot_before_final(
+                page, target_day=item.day, days=inventory, slots=slots,
+                runtime_service=service, dom_timeout=dom_timeout,
+                session_is_current=session_is_current,
+            )
+            if candidate:
+                return candidate
+        if selected_month >= (end_day.year, end_day.month):
+            break
+    return None
+
+
+FINAL_PATH = "/BookingCalendar/InsertNewBooking"
+FINAL_FAILED_LABEL = "italy-final-failed"
+FINAL_ACCEPTED_LABEL = "italy-final-accepted"
+
+
+def _submit_final_once(plugin, route: ItaRouteConfig, slot: SlotCandidate) -> VSBookResult:
+    try:
+        page = plugin.page
+        username = plugin.config.account.username.strip().casefold()
+        prepared = plugin._require_calendar_context(route, role="book", username=username)
+        if (not username or not isinstance(slot, SlotCandidate)
+                or page.tab_id != prepared.tab_id or same_origin_path(page.url) != CALENDAR_PATH):
+            raise CalendarBookError("Italy final context is not current")
+        verify_precommit_selection(page, runtime_service=prepared.runtime_service, candidate=slot)
+        response = perform_browser_fetch(page, "POST", FINAL_PATH, data={
+            "idCalendarioGiornaliero": slot.daily_calendar_id,
+            "selectedDay": slot.day.isoformat(),
+            "selectedHour": f"{slot.time_label}\n({slot.slots_free})",
+        })
+        data = response.json()
+        if (response.status_code == 200 and same_origin_path(response.url) == FINAL_PATH
+                and isinstance(data, dict) and not str(data.get("errorMessage", "")).strip()
+                and isinstance(data.get("url"), str) and data["url"].strip()):
+            same_origin_path(urljoin("https://prenotami.esteri.it", data["url"]))
+            return VSBookResult(
+                success=True,
+                account=username,
+                label=FINAL_ACCEPTED_LABEL,
+                book_date=slot.day.isoformat(),
+                book_time=slot.time_label,
+            )
+    except Exception as exc:
+        plugin._log(f"Italy final submission failed: {type(exc).__name__}")
+    # The next Booker signal must re-enter the form and obtain fresh IDs.
+    plugin._reset_calendar_state()
+    return VSBookResult(success=False, label=FINAL_FAILED_LABEL)
+
+
+_SENT_AT_FORMAT = "%Y-%m-%d %H:%M:%S"
+_OTP_INPUT_LOCK = vars(_ita_host).setdefault("_coordinate_ita_otp_input_lock", Lock())
+
+
+def guarded_preflight_script(route: ItaRouteConfig, booking_path: str) -> str:
+    if not route.booking_type or not route.purpose:
+        raise CalendarGateError("Italy route is missing form controls")
+    config = {"path": booking_path, "booking": asdict(route.booking_type),
+              "purpose": asdict(route.purpose)}
+    return f"""
+const cfg = {json.dumps(config, ensure_ascii=False)};
+const form = document.querySelector('#bookingForm');
+const norm = value => String(value || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+function choose(item) {{
+  const control = document.getElementById(item.control_id);
+  const option = control && Array.from(control.options).find(value => value.value === item.value);
+  if (!option || !item.labels.map(norm).includes(norm(option.textContent))) return false;
+  if (control.value !== item.value) {{
+    control.value = item.value;
+    control.dispatchEvent(new Event('change', {{bubbles: true}}));
+  }}
+  return control.value === item.value;
+}}
+const booking = choose(cfg.booking), purpose = choose(cfg.purpose);
+const privacy = document.querySelector('#PrivacyCheck');
+if (privacy && !privacy.checked) privacy.click();
+const otp = document.querySelector('#otp-input'), send = document.querySelector('#otp-send');
+const avanti = document.querySelector('#btnAvanti');
+const token = document.querySelector('input[name="cf-turnstile-response"]');
+return {{
+  formReady: Boolean(location.pathname === cfg.path && form && booking && purpose && privacy && privacy.checked),
+  turnstileReady: Boolean(token && token.value),
+  otpValuePresent: Boolean(otp && otp.value.trim()),
+  otpSendEnabled: Boolean(send && !send.disabled),
+  avantiEnabled: Boolean(avanti && !avanti.disabled),
+}};
+"""
+
+
+def validate_booking_preflight(raw, *, after_otp=False, allow_pending=False):
+    if type(after_otp) is not bool or type(allow_pending) is not bool:
+        raise CalendarGateError("Italy booking preflight policy is invalid")
+    if not isinstance(raw, dict) or any(type(raw.get(key)) is not bool for key in (
+            "formReady", "turnstileReady", "otpValuePresent", "otpSendEnabled", "avantiEnabled")):
+        raise CalendarGateError("Italy booking form structure changed")
+    if raw["otpValuePresent"] is not after_otp:
+        raise CalendarGateError("Italy booking OTP stage changed")
+    ready = (raw["formReady"] and (after_otp or raw["otpSendEnabled"]) and
+             raw["turnstileReady"] and raw["avantiEnabled"])
+    if not allow_pending and not ready:
+        raise CalendarGateError("Italy booking verification is not ready")
+
+
+def wait_for_booking_preflight(page, *, script, after_otp=False, timeout=120,
+                               diagnostic=None, wait_action=None, check_current=None):
+    deadline, bypasser, attempts, raw = time.monotonic() + timeout, None, 0, None
+    while time.monotonic() < deadline:
+        if check_current:
+            check_current()
+        raw = page.run_js(script)
+        validate_booking_preflight(raw, after_otp=after_otp, allow_pending=True)
+        form_ready = raw["formReady"] and (after_otp or raw["otpSendEnabled"])
+        if form_ready and raw["turnstileReady"] and raw["avantiEnabled"]:
+            return raw
+        if form_ready and not raw["turnstileReady"] and attempts < 3:
+            bypasser = bypasser or CloudflareBypasser(page, log=False)
+            try:
+                bypasser.click_verification_button(is_dfs=False)
+            except Exception:
+                pass
+            attempts += 1
         time.sleep(1)
+    reason = ("form_pending" if not raw or not raw["formReady"] else
+              "otp_send_disabled" if not after_otp and not raw["otpSendEnabled"] else
+              "turnstile_token_pending" if not raw["turnstileReady"] else "avanti_disabled")
+    raise CalendarGateError(f"Italy booking verification timed out: {reason}")
 
-        self.log("Clicking submit login button...")
-        submit_btn = self.page.ele('tag:button@type=submit') 
-        if submit_btn:
-            self.plugin.mouse.human_click_ele(submit_btn)
-        
-        self.has_submitted_login = True
-        self.log("Login form submitted. Waiting for dashboard to load...")
-        self.plugin._random_sleep(5, 7)
 
-    @on(ele=".app-menu", priority=35)
-    def handle_dashboard_menu(self):
-        self.log("[State] Dashboard Menu detected.")
-        switch_en_btn = self.page.ele('tag:a@@href=/Language/ChangeLanguage?lang=2', timeout=0.5)
-        if switch_en_btn:
-            self.log("Found 'English' language switch button. Clicking to change language...")
-            self.plugin.mouse.human_click_ele(switch_en_btn)
-            self.plugin._random_sleep(4, 6)
-            return
+def _element_or_fail(page, selector):
+    element = page.ele(selector, timeout=5)
+    if not element:
+        raise CalendarGateError(f"Italy booking element is missing: {selector}")
+    return element
 
-        book_btn = self.page.ele('@href=/Services', timeout=0.5)
-        if book_btn:
-            self.log("Found 'Book' menu element. Clicking to proceed to reservation...")
-            self.plugin.mouse.human_click_ele(book_btn)
-            self.plugin._random_sleep(4, 6)
+
+def _read_manual_otp():
+    value = input("Italy booking OTP: ").strip()
+    if not re.fullmatch(r"[0-9]{4,12}", value):
+        raise CalendarGateError("Italy OTP format rejected")
+    return value
+
+
+def _enter_otp(plugin, otp):
+    field = _element_or_fail(plugin.page, "#otp-input")
+    plugin.mouse.human_click_ele(field)
+    field.input(otp, clear=True)
+    if field.run_js("return this.value === arguments[0];", otp) is not True:
+        raise CalendarGateError("Italy OTP write failed")
+
+
+def validate_cloud_otp_environment(mail_config, recipient):
+    if not isinstance(mail_config, OtpMailConfig):
+        raise CalendarGateError("Italy OTP mail configuration is missing")
+    if not isinstance(recipient, str) or not _EMAIL_PATTERN.fullmatch(recipient.strip()):
+        raise CalendarGateError("Italy OTP recipient is invalid")
+    mail_config.mailbox_for(recipient)
+    return recipient.strip()
+
+
+def fetch_otp_from_cloud(mail_config, *, recipient, sent_at, api=None):
+    validate_cloud_otp_environment(mail_config, recipient)
+    try:
+        datetime.strptime(sent_at, _SENT_AT_FORMAT)
+    except (TypeError, ValueError):
+        raise CalendarGateError("Italy OTP sent time is invalid") from None
+    try:
+        body = (api or VSCloudApi.Instance()).fetch_mail_content(
+            email=mail_config.mailbox_for(recipient), sender=PRENOTAMI_OTP_SENDER, recipient=recipient,
+            subject_keywords="OTP Code", body_keywords="OTP Code:",
+            sent_date=sent_at, expiry=mail_config.expiry_seconds, only_text=True,
+        )
+        return parse_otp_body(body)
+    except Exception as exc:
+        message = "not permitted" if isinstance(exc, PermissionDeniedError) else "read failed"
+        raise CalendarGateError(f"Italy OTP mailbox {message}") from None
+
+
+def _wait_for_calendar(page, timeout=30):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if urlparse(str(page.url or "")).path.rstrip("/") == CALENDAR_PATH:
+            page.wait.doc_loaded()
             return
+        time.sleep(0.25)
+    raise CalendarGateError("Italy AVANTI did not reach Calendar")
+
+
+def prepare_calendar(plugin, route, *, role):
+    if role not in {"query", "book"} or route.capability is not ItaCapability.SINGLE_SCHENGEN_TOURISM:
+        raise BizLogicError("Italy Calendar preparation requires a tourism route")
+    cloud = plugin.free_config.get("otp_mode") == "cloud"
+    if not cloud and (plugin.free_config.get("otp_mode") != "manual" or not sys.stdin.isatty()):
+        raise PermissionDeniedError("Italy Calendar requires automatic OTP or an attached terminal")
+    username, page, booking_path = (
+        plugin.config.account.username.strip().casefold(), plugin.page, plugin._booking_path(route))
+    if cloud:
+        validate_cloud_otp_environment(route.mail, username)
+
+    def current(path):
+        if plugin.page is not page or same_origin_path(page.url) != path:
+            raise CalendarGateError("Italy preparation page changed")
 
-        self.log("[WARN] On Dashboard, but neither 'English' nor 'Book' button was found. Waiting...")
-        time.sleep(2)
+    def click(selector):
+        current(booking_path)
+        plugin.mouse.human_click_ele(_element_or_fail(page, selector))
 
-    # --- 成功终态到达 (Priority 10) ---
-    @on(url="/Services", ele=".app-menu", priority=10)
+    with _OTP_INPUT_LOCK:
+        script = guarded_preflight_script(route, booking_path)
+        wait_for_booking_preflight(page, script=script, check_current=lambda: current(booking_path))
+        sent_at = datetime.now(timezone.utc).strftime(_SENT_AT_FORMAT)
+        click("#otp-send")
+        plugin._log(f"Italy {role} OTP sent.")
+        otp = (fetch_otp_from_cloud(route.mail, recipient=username, sent_at=sent_at)
+               if cloud else _read_manual_otp())
+        _enter_otp(plugin, otp)
+        wait_for_booking_preflight(
+            page, script=script, after_otp=True, check_current=lambda: current(booking_path))
+        page.set.auto_handle_alert(accept=True)
+        try:
+            click("#btnAvanti")
+            _wait_for_calendar(page)
+        finally:
+            page.set.auto_handle_alert(on_off=False)
+        wait_for_calendar_service(
+            page, session_is_current=lambda: plugin.page is page,
+            expected_service=route.service_id,
+        )
+        plugin._record_calendar_prepared_route(route, role=role)
+
+
+BOOKING_RECHECK_NONE_AVAILABLE_LABEL = "no-availability-after-user-recheck"
+BOOKING_CALENDAR_PREFINAL_STOP_LABEL = "calendar-ready-before-final"
+RADWARE_VALIDATION_HOSTS = frozenset({"validate.perfdrive.com"})
+SERVICE_LINK_WAIT_SECONDS = 15
+SERVICES_PROBE_QUERY_MODE = "services_probe"
+CALENDAR_QUERY_MODE = "calendar"
+
+
+class ItaAuthenticationChallengeError(BizLogicError): pass
+class ItaTargetServiceLinkMissingError(BizLogicError): pass
+class ItaCalendarTransientError(BizLogicError): pass
+
+
+@dataclass(frozen=True, repr=False, eq=False)
+class _PreparedCalendar:
+    username: str
+    routing_key: str
+    runtime_service: str
+    tab_id: str
+    role: str
+
+
+class ItaLoginFlow(BaseFlow):
+    """Italy page rules on the host flow engine; never resubmit credentials."""
+
+    def __init__(self, plugin):
+        self.plugin = plugin
+        self.entered = self.submitted = False
+        super().__init__(plugin.page, interval=3, logger=plugin._log, max_stuck_cycles=None)
+
+    def at(self, host, path):
+        url = urlparse(self.page.url)
+        return url.hostname == host and (url.path.rstrip("/") or "/") == path
+
+    @guard(predicate=lambda f: urlparse(f.page.url).hostname in RADWARE_VALIDATION_HOSTS, priority=1)
+    def radware(self):
+        raise ItaAuthenticationChallengeError(
+            "Italy authentication requires Radware browser validation; automatic retry is disabled")
+
+    @guard(predicate=lambda f: urlparse(f.page.url).scheme != "https" or
+           urlparse(f.page.url).netloc.lower() not in {
+               "prenotami.esteri.it", "iam.esteri.it", "prenotami.esteri.it:443", "iam.esteri.it:443"}, priority=2)
+    def foreign_origin(self):
+        raise BizLogicError("Italy authentication left the expected website")
+
+    @guard(predicate=lambda f: any(value in f.page.html for value in (
+        "Sorry, you have been blocked", "You are being rate limited", "error 1020")), priority=3)
+    def blocked(self):
+        raise ItaAuthenticationChallengeError("Italy authentication was blocked; automatic retry is disabled")
+
+    @guard(predicate=lambda f: any(value in f.page.html for value in (
+        "502 Bad Gateway", "503 Service Temporarily Unavailable")), priority=4)
+    def server_error(self):
+        if self.entered or self.submitted:
+            raise BizLogicError("Italy authentication failed after login started; no resubmission")
+        self.page.refresh()
+        self.plugin._random_sleep(10, 15)
+
+    @guard(title="just a moment", priority=5)
+    @guard(title="cloudflare", priority=5)
+    def verification_pending(self):
+        self.log("Waiting for the website's human verification")
+        time.sleep(5)
+
+    @on(ele=".app-menu", predicate=lambda f: f.at("prenotami.esteri.it", "/UserArea") and
+        bool(f.page.ele("@href=/Services", timeout=0.2)), priority=20)
     @done
-    def on_reached_services_page(self):
+    def authenticated(self):
+        self.plugin._log("Successfully reached authenticated /UserArea.")
         self.plugin.session_create_time = time.time()
-        self.log("🎉 Successfully reached the Booking Services page! Session created successfully!")
+        self.plugin.is_healthy = True
+
+    @on(ele="#pingid-button", predicate=lambda f: f.at("prenotami.esteri.it", "/") and not f.entered, priority=30)
+    def enter(self):
+        self.entered = True
+        self.plugin.mouse.human_click_ele(self.page.ele("#pingid-button"))
+        self.plugin._log("Redirecting to PingID...")
+        self.plugin._random_sleep(3, 5)
+
+    @on(ele="@name=callback_1", predicate=lambda f: f.at("iam.esteri.it", "/signin") and not f.submitted, priority=40)
+    def credentials(self):
+        username, password, submit = [self.page.ele(selector, timeout=0.2) for selector in
+                                      ("@name=callback_1", "@name=callback_2", "tag:button@type=submit")]
+        if not all((username, password, submit)):
+            return  # IAM can render its controls in separate updates.
+        for label, element, value in (("username", username, self.plugin.config.account.username),
+                                      ("password", password, self.plugin.config.account.password)):
+            self.plugin._log(f"Entering {label}...")
+            self.plugin.mouse.human_click_ele(element)
+            element.input(value, clear=True)
+            time.sleep(1)
+        self.submitted = True
+        self.plugin.mouse.human_click_ele(submit)
+        self.plugin._log("Login form submitted. Waiting for dashboard to load...")
+        self.plugin._random_sleep(5, 7)
 
 
 class ItaPlugin(IVSPlg):
     name = "ita_plugin"
-    version = "1.0.0"
-    description = "意大利Prenot@Mi领事预约插件 (支持拟人化交互与多领区调度)"
+    version = "1.0.2"
+    description = "意大利 Prenot@Mi 查询与预约插件"
 
-    def __init__(self, group_id: str):
+    def __init__(self, group_id):
         self.group_id = group_id
-        self.config: Optional[VSPlgConfig] = None
-        self.free_config: Dict[str, Any] = {}
+        self.config = None
+        self.free_config = {}
         self.is_healthy = True
-        self.logger = None
-        self.page: Optional[ChromiumPage] = None
-        
-        # Prenotami 特有配置
-        self._service_id = 0 
-        self.ita_url = 'https://prenotami.esteri.it'
-        self._host = self.ita_url
-        
+        self.logger = self.page = self.tunnel = None
+        self.ita_url = "https://prenotami.esteri.it"
         self.instance_id = uuid.uuid4().hex[:8]
-        self.root_workspace = os.path.abspath(os.path.join("data/temp_browser_data", f"{self.group_id}.{self.instance_id}"))
+        self.root_workspace = os.path.abspath(
+            os.path.join("data/temp_browser_data", f"{group_id}.{self.instance_id}"))
         self.user_data_path = os.path.join(self.root_workspace, "user_data")
-        
-        if not os.path.exists(self.root_workspace):
-            os.makedirs(self.root_workspace)
-        self.tunnel = None
-        self.session_create_time: float = 0
-    
-    def set_log(self, logger: Callable[[str], None]) -> None:
+        os.makedirs(self.root_workspace, exist_ok=True)
+        self.session_create_time = 0
+        self._prepared_calendar = None
+
+    def set_log(self, logger):
         self.logger = logger
-        
-    def _log(self, message): 
-        if self.logger:
-            self.logger(f'[ItaPlugin] [{self.group_id}] [{self.instance_id}] {message}')
-        else:
-            print(f'[ItaPlugin] [{self.group_id}] [{self.instance_id}] {message}')
-
-    def _random_sleep(self, min_sec=3, max_sec=5):
-        sleep_time = random.uniform(min_sec, max_sec)
-        time.sleep(sleep_time)
-        
-    def set_config(self, config: VSPlgConfig): 
-        self.config = config
-        self.free_config = config.free_config or {}
-        # Service ID (e.g., 1321 for Ireland, 5059 for Guangzhou)
-        self._service_id = self.free_config.get('service_id', 0)
-        
+
+    def _log(self, message):
+        (self.logger or print)(f"[ItaPlugin] [{self.group_id}] {message}")
+
+    def _random_sleep(self, minimum=30, maximum=60):
+        seconds = random.uniform(minimum, maximum)
+        self._log(f"Anti-Rate-Limit: Sleeping for {seconds:.2f} seconds...")
+        time.sleep(seconds)
+
+    def set_config(self, config):
+        self.config, self.free_config = config, config.free_config or {}
+        query_mode = self.free_config.get("query_mode", SERVICES_PROBE_QUERY_MODE)
+        otp_mode = self.free_config.get("otp_mode")
+        final = self.free_config.get("final_submit_enabled", False)
+        if query_mode not in {SERVICES_PROBE_QUERY_MODE, CALENDAR_QUERY_MODE}:
+            raise BizLogicError("Italy query_mode is invalid")
+        if otp_mode not in {None, "manual", "cloud"}:
+            raise BizLogicError("Italy otp_mode is invalid")
+        if final is not False and not (
+                final is True and otp_mode in {"manual", "cloud"}
+                and query_mode == SERVICES_PROBE_QUERY_MODE):
+            raise BizLogicError("Italy final submission configuration is invalid")
+        self._prepared_calendar = None
+
+    def _resolve_route(self, apt_type):
+        try:
+            return resolve_route_config(
+                self.free_config.get("apt_configs", {}), apt_type.routing_key)
+        except (AttributeError, ItaProtocolError) as exc:
+            detail = getattr(exc, "code", type(exc).__name__)
+            raise BizLogicError(f"Italy route configuration rejected: {detail}") from exc
+
+    @staticmethod
+    def _booking_path(route):
+        return f"/Services/Booking/{route.service_id}"
+
+    def _authenticated_path(self):
+        host = urlparse(str(self.page.url or "")).hostname
+        if host == "iam.esteri.it" or self.page.ele("#pingid-button", timeout=0.2):
+            raise SessionExpiredOrInvalidError("Italy Session expired")
+        return same_origin_path(self.page.url)
+
+    def _reset_calendar_state(self):
+        self._prepared_calendar = None
+
+    def _calendar_context_matches(self, route, *, role, username=None):
+        state = self._prepared_calendar
+        try:
+            account = self.config.account.username.strip().casefold()
+            return (
+                isinstance(state, _PreparedCalendar) and self.is_healthy and
+                state.tab_id == self.page.tab_id and state.username == account and
+                state.routing_key == route.routing_key and state.role == role and
+                (username is None or username == account)
+            )
+        except Exception:
+            return False
+
+    def _record_calendar_prepared_route(self, route, *, role):
+        try:
+            self._prepared_calendar = _PreparedCalendar(
+                self.config.account.username.strip().casefold(), route.routing_key,
+                read_calendar_service(self.page), self.page.tab_id, role)
+        except Exception:
+            self._prepared_calendar = None
+            raise BizLogicError("Italy Calendar identity is unavailable") from None
+
+    def _require_calendar_context(self, route, *, role, username=None):
+        if not self._calendar_context_matches(route, role=role, username=username):
+            raise BizLogicError("Italy Calendar Session changed")
+        if read_calendar_service(self.page) != self._prepared_calendar.runtime_service:
+            raise BizLogicError("Italy Calendar service changed")
+        return self._prepared_calendar
+
+    def _invalidate_query_session(self):
+        self.is_healthy = False
+        self._prepared_calendar = None
+
+    def _calendar_failure(self, exc, role):
+        self._prepared_calendar = None
+        kinds = (
+            (CalendarAuthenticationExpiredError, SessionExpiredOrInvalidError, "Session expired"),
+            (CalendarRateLimitedError, RateLimiteddError, "rate limited"),
+            (CalendarAccessDeniedError, PermissionDeniedError, "access denied"),
+            (CalendarTransientError, ItaCalendarTransientError, "temporarily unavailable"),
+        )
+        for source, target, message in kinds:
+            if isinstance(exc, source):
+                if role == "Query" or source is CalendarAuthenticationExpiredError:
+                    self.is_healthy = False
+                return target(f"Italy {role} {message}")
+        return BizLogicError(f"Italy {role} failed: {exc}")
+
     def keep_alive(self):
         pass
 
-    def health_check(self) -> bool:
+    def health_check(self):
         if not self.is_healthy or not self.page:
             return False
         try:
-            if not self.page.run_js("return 1;"):
-                return False
+            alive = self.page.run_js("return 1;") == 1
         except Exception:
+            alive = False
+        expired = self.config.session_max_life > 0 and (
+            time.time() - self.session_create_time > self.config.session_max_life)
+        if not alive or expired:
+            self._invalidate_query_session()
             return False
-        if self.config.session_max_life > 0:
-            if time.time() - self.session_create_time > self.config.session_max_life:
-                self._log("Session expired.")
-                return False
         return True
 
     def create_session(self):
-        """
-        全浏览器会话创建:过盾 -> JS注入登录 -> 状态机自动路由导航 -> 到达目标页
-        """
         self._log(f"Initializing Session (ID: {self.instance_id})...")
-        self._log(f"Account id={self.config.account.id}, proxy id={self.config.proxy.id if self.config and self.config.proxy else 'None'}")
-
-        co, self.tunnel = init_chromium_options(
+        self._invalidate_query_session()
+        options, self.tunnel = init_chromium_options(
             user_data_path=self.user_data_path,
-            username_seed=self.config.account.username if self.config and self.config.account else None,
-            proxy=self.config.proxy if self.config else None,
+            username_seed=self.config.account.username,
+            proxy=self.config.proxy,
             headless=False,
             window_size="1920,1080",
-            logger=self._log
-        )
-        
-        self.page = ChromiumPage(co)
-        ita_url = self.ita_url
-        self._log(f"Navigating to {ita_url}")
-        self.page.get(ita_url)
-        
-        self._log("Init humanize tools...")
-        self.mouse = HumanMouse(self.page, debug=False)
-        self.keyboard = HumanKeyboard(self.page)
-        
-        viewport_width = self.page.rect.viewport_size[0]
-        viewport_height = self.page.rect.viewport_size[1]
-        init_x = random.randint(10, viewport_width - 10)
-        init_y = random.randint(10, viewport_height - 10)
-        self.mouse.move(init_x, init_y) 
-
-        # 启动 ItaLoginFlow 注解流状态机
-        login_flow = ItaLoginFlow(
-            self.page, 
-            plugin=self, 
-            interval=1.0
+            logger=self._log,
         )
-        login_flow.run(max_steps=20)
-        self.session_create_time = time.time()
-        self._log("🎉 ItaLoginFlow completed successfully. Session created.")
-
-    def query(self, apt_type: AppointmentType) -> VSQueryResult:
-        res = VSQueryResult()
-        res.success = False
-        res.availability_status = AvailabilityStatus.NoneAvailable
-        
-        TARGET_SERVICE = self.free_config.get('target_service', "National and Schengen Visas")
-        REASON_FOR_VISIT = self.free_config.get('reason_for_visit', "Tourism")
-
-        # 步骤 1:在服务列表中寻找并点击目标服务的 Book
-        self._log("Waiting for service list to load...")
-        self.page.wait.eles_loaded('@aria-controls=dataTableServices', timeout=10)
-
-        self._log(f"Searching for [{TARGET_SERVICE}] Book button...")
-        target_book_btn_xpath = f'xpath://tr[contains(., "{TARGET_SERVICE}")]//a[contains(text(), "Book")]'
-        book_btn = self.page.ele(target_book_btn_xpath)
-
-        if not book_btn:
-            self._log(f"Target [{TARGET_SERVICE}] Book button not found, currently no slots available.")
-            return res
-
-        self.mouse.human_click_ele(book_btn)
-        self.page.wait.load_start()
-        time.sleep(3)
-
-        # 步骤 2:填写预约表单
-        self._log("Waiting for booking form to load...")
-        self.page.wait.eles_loaded('#bookingForm', timeout=10)
-
-        self._log("Selecting booking type & reason...")
-        typeofbooking_ddl = self.page.ele('#typeofbookingddl')
-        if typeofbooking_ddl:
-            typeofbooking_ddl.select('Individual booking')
-            time.sleep(1)
-
-        reason_ddl = self.page.ele('#ddls_0')
-        if reason_ddl:
-            reason_ddl.select(REASON_FOR_VISIT)
-            time.sleep(1)
-
-        notes_input = self.page.ele('#BookingNotes')
-        if notes_input:
-            notes_input.clear()
-            notes_input.input('N/A')
-            time.sleep(1)
-
-        # 步骤 3:处理 OTP 验证码
-        self._log("Sending OTP code...")
-        otp_send_btn = self.page.ele('#otp-send')
-        if otp_send_btn:
-            self.mouse.human_click_ele(otp_send_btn)
-            self.page.wait.ele_displayed('#IdOtpSent', timeout=15)
-            self._log("OTP code sent successfully.")
-
-        otp_input = self.page.ele('#otp-input')
-        if otp_input:
-            self.mouse.human_click_ele(otp_input)
-            otp_input.input('123456')
-            time.sleep(1)
-
-        # 步骤 4:勾选隐私政策并提交
-        privacy_checkbox = self.page.ele('#PrivacyCheck')
-        if privacy_checkbox and not privacy_checkbox.states.is_checked:
-            self.mouse.human_click_ele(privacy_checkbox)
-        time.sleep(1)
+        self.page = ChromiumPage(options)
+        self.page.get(self.ita_url)
+        self.mouse, self.keyboard = HumanMouse(self.page, debug=True), HumanKeyboard(self.page)
+        width, height = self.page.rect.viewport_size
+        self.mouse.move(random.randint(10, width - 10), random.randint(10, height - 10))
+        flow = ItaLoginFlow(self)
+        try:
+            flow.run(max_steps=40, timeout=120)
+        except BizLogicError:
+            raise
+        except Exception as exc:
+            raise BizLogicError(f"Italy login failed: {type(exc).__name__}; url={self.page.url}") from None
 
-        self._log("Submitting forward form...")
-        forward_btn = self.page.ele('#btnAvanti')
-        if forward_btn:
-            self.mouse.human_click_ele(forward_btn)
+    def query(self, apt_type):
+        if not self.health_check() or self.free_config.get("query_mode") != CALENDAR_QUERY_MODE:
+            raise SessionExpiredOrInvalidError("Italy Query Session is unavailable")
+        route = self._resolve_route(apt_type)
+        try:
+            if same_origin_path(self.page.url) != CALENDAR_PATH:
+                entry = self._enter_service(apt_type, route=route)
+                if not entry.success:
+                    return entry
+                self._reset_calendar_state()
+                prepare_calendar(self, route, role="query")
+            self._require_calendar_context(route, role="query")
+            probes = scan_until_first_available_month(
+                self.page, lookahead_months=route.lookahead_months, log=self._log)
+        except CalendarGateError as exc:
+            raise self._calendar_failure(exc, "Query") from None
+        available = available_calendar_days(probes[-1])
+        if not available:
+            return VSQueryResult(
+                success=False, apt_type=apt_type,
+                availability_status=AvailabilityStatus.NoneAvailable)
+        earliest = datetime.combine(available[0].day, datetime.min.time())
+        self._log(f"Italy Calendar earliest_date={earliest.date().isoformat()}")
+        return VSQueryResult(
+            success=True, apt_type=apt_type,
+            availability_status=AvailabilityStatus.Available,
+            earliest_date=earliest,
+            availability=[DateAvailability(date=earliest, times=[])])
 
+    def _enter_service(self, apt_type, *, route=None):
+        route, path = route or self._resolve_route(apt_type), None
+        booking_path = self._booking_path(route)
+        self.page.get(f"{self.ita_url}/Services")
+        self.page.wait.doc_loaded()
+        if self._authenticated_path() != "/Services":
+            raise BizLogicError("Italy service list is unavailable")
+        link = self.page.ele(f"tag:a@@href={booking_path}", timeout=SERVICE_LINK_WAIT_SECONDS)
+        if not link:
+            raise ItaTargetServiceLinkMissingError(f"Italy service link is missing: {booking_path}")
+        self.mouse.human_click_ele(link)
         self.page.wait.load_start()
-        self._log(f"Form submitted. Current page: {self.page.url}")
-        time.sleep(3)
-
-        return res
-
-    def book(self, slot_info: VSQueryResult, user_inputs: Dict = None) -> VSBookResult:
-        res = VSBookResult()
-        res.success = False
-        user_inputs = user_inputs or {}
-        
-        if not slot_info.availability:
-            raise NotFoundError("No slots to book")
-            
-        target_dt = slot_info.availability[0].date
-        target_date = target_dt.strftime("%Y-%m-%d") if target_dt else ""
-        target_slot = slot_info.availability[0].times[0] if slot_info.availability[0].times else None
-        slot_id = target_slot.label if target_slot else ""
-        slot_text = target_slot.time if target_slot else ""
-        
-        # 1. 获取 OTP (GenerateOTP)
-        self._log("Requesting OTP...")
-        otp_url = f"{self._host}/BookingCalendar/GenerateOTP?ServiceID={self._service_id}"
-        self._perform_request("POST", otp_url)
-        
-        # 2. 等待并读取邮件
-        self._log("Waiting for email code...")
-        time.sleep(10)
-        email_account = self.config.account.username if self.config and self.config.account else ""
-        otp_code = VSCloudApi.Instance().get_email_verify_code(email_account)
-        
-        if not otp_code:
-            raise BizLogicError("Failed to retrieve OTP code")
-        self._log(f"Got OTP: {otp_code}")
-
-        # 3. 提交详细信息 (Fill User Info)
-        self._log("Submitting User Details & Files...")
-        passport_pdf_path = user_inputs.get('passport_pdf_path')
-        irp_pdf_path = user_inputs.get('irp_pdf_path')
-        
-        def file_to_b64(path):
-            if not path or not os.path.exists(path):
-                return ""
-            with open(path, "rb") as f:
-                return base64.b64encode(f.read()).decode('utf-8')
-
-        ppt_b64 = file_to_b64(passport_pdf_path)
-        irp_b64 = file_to_b64(irp_pdf_path)
-        
-        submit_url = f"{self._host}/Services/Booking/{self._service_id}"
-        
-        js_submit = f"""
-        const url = "{submit_url}";
-        const fd = new FormData();
-        
-        fd.append('ServizioDescrizione', 'D Visa Application');
-        fd.append('MessaggioRassicuranteWaitingList', 'True');
-        fd.append('isWaitingListEnabled', 'False');
-        fd.append('IDServizioConsolare', '35');
-        fd.append('IDServizioErogato', '{self._service_id}');
-        fd.append('IdTipoPrenotazione', '1');
-        fd.append('NumMaxAccompagnatori', '3');
-        fd.append('NumAccompagnatoriSelected', '0');
-        
-        fd.append('DatiAddizionaliPrenotante[0]._Descrizione', 'Other citizenship/s');
-        fd.append('DatiAddizionaliPrenotante[0]._testo', '{user_inputs.get("citizen", "China")}');
-        fd.append('DatiAddizionaliPrenotante[0]._Obbligatorio', 'False');
-        fd.append('DatiAddizionaliPrenotante[0]._Id', '61738');
-        fd.append('DatiAddizionaliPrenotante[0]._TipoDatoAddizionale.IDTipoDatoAddizionale', '26');
-        fd.append('DatiAddizionaliPrenotante[0]._TipoDatoAddizionale.IDTipoControllo', '2');
-        
-        fd.append('DatiAddizionaliPrenotante[1]._Descrizione', 'Full residence address');
-        fd.append('DatiAddizionaliPrenotante[1]._testo', '{user_inputs.get("address", "")}');
-        fd.append('DatiAddizionaliPrenotante[1]._Obbligatorio', 'True');
-        fd.append('DatiAddizionaliPrenotante[1]._Id', '61739');
-        fd.append('DatiAddizionaliPrenotante[1]._TipoDatoAddizionale.IDTipoDatoAddizionale', '25');
-        fd.append('DatiAddizionaliPrenotante[1]._TipoDatoAddizionale.IDTipoControllo', '2');
-
-        fd.append('DatiAddizionaliPrenotante[2]._Descrizione', 'Passport number');
-        fd.append('DatiAddizionaliPrenotante[2]._testo', '{user_inputs.get("passport", "")}');
-        fd.append('DatiAddizionaliPrenotante[2]._Obbligatorio', 'True');
-        fd.append('DatiAddizionaliPrenotante[2]._Id', '61740');
-        fd.append('DatiAddizionaliPrenotante[2]._TipoDatoAddizionale.IDTipoDatoAddizionale', '2');
-        fd.append('DatiAddizionaliPrenotante[2]._TipoDatoAddizionale.IDTipoControllo', '2');
-
-        fd.append('DatiAddizionaliPrenotante[3]._Descrizione', 'Reason for visit');
-        fd.append('DatiAddizionaliPrenotante[3]._Obbligatorio', 'True');
-        fd.append('DatiAddizionaliPrenotante[3]._Id', '61741');
-        fd.append('DatiAddizionaliPrenotante[3]._TipoDatoAddizionale.IDTipoDatoAddizionale', '34');
-        fd.append('DatiAddizionaliPrenotante[3]._TipoDatoAddizionale.IDTipoControllo', '3');
-        fd.append('DatiAddizionaliPrenotante[3]._idSelezionato', '42');
-
-        fd.append('otp-input', '{otp_code}');
-        fd.append('PrivacyCheck', 'true');
-        
-        async function addFile(b64, name, filename) {{
-            if(!b64) return;
-            const res = await fetch(`data:application/pdf;base64,${{b64}}`);
-            const blob = await res.blob();
-            fd.append(name, blob, filename);
-        }}
-        
-        await Promise.all([
-            addFile('{ppt_b64}', 'File_0', 'passport.pdf'),
-            addFile('{irp_b64}', 'File_1', 'irp.pdf')
-        ]);
-
-        return fetch(url, {{
-            method: 'POST',
-            body: fd
-        }}).then(async r => {{
-            return {{ status: r.status, url: r.url, text: await r.text() }};
-        }}).catch(e => {{ return {{ status: 0, text: e.toString() }}; }});
-        """
-        
-        result_dict = self.page.run_js(js_submit)
-        resp = BrowserResponse(result_dict)
-        
-        if resp.status_code == 302 or "BookingCalendar" in resp.url:
-            self._log("User Info Submitted Successfully.")
-        else:
-            self._log(f"User Info Submit Failed: {resp.text[:100]}")
-            if "Codice errato" in resp.text:
-                raise BizLogicError("Invalid OTP Code")
-            return res
-
-        # 4. 最终确认预约 (InsertNewBooking)
-        self._log("Finalizing Booking...")
-        final_url = f"{self._host}/BookingCalendar/InsertNewBooking"
-        final_payload = {
-            "idCalendarioGiornaliero": slot_id,
-            "selectedDay": target_date,
-            "selectedHour": slot_text
-        }
-        resp_final = self._perform_request("POST", final_url, data=final_payload)
-        
-        if resp_final.status_code == 200:
-            self._log("Booking Confirmed!")
-            res.success = True
-            res.book_date = target_date
-            res.book_time = slot_text
-        else:
-            self._log(f"Final Booking Failed: {resp_final.status_code}")
-            
-        return res
-    
-    def _perform_request(self, method, url, headers=None, data=None, json_data=None):
-        """在浏览器上下文中注入执行 Fetch"""
-        if not self.page:
-            raise BizLogicError("Browser not initialized")
-        return perform_browser_fetch(
-            self.page, 
-            method=method, 
-            url=url, 
-            headers=headers, 
-            data=data, 
-            json_data=json_data
-        )
+        self.page.wait.doc_loaded()
+        path = self._authenticated_path()
+        empty = VSQueryResult(
+            success=False, apt_type=apt_type,
+            availability_status=AvailabilityStatus.NoneAvailable)
+        if path == "/Services":
+            marker = self.page.ele("#WNotAvailable", timeout=1)
+            notice = self.page.ele(".jconfirm-content", timeout=1)
+            text = ((marker.attr("value") if marker else "") or
+                    (notice.text if notice else "") or "").strip().casefold()
+            if text and ("posti disponibili" in text or marker):
+                return empty
+            raise BizLogicError("Italy service returned an unknown response")
+        if path != booking_path or not self.page.ele("#bookingForm", timeout=2):
+            raise BizLogicError("Italy booking form is unavailable")
+        return VSQueryResult(
+            success=True, apt_type=apt_type,
+            availability_status=AvailabilityStatus.NoneAvailable)
 
-    def _parse_valid_days(self, text: str) -> List[str]:
-        days = []
+    def book(self, slot_info, user_inputs=None):
+        if not self.page or not isinstance(slot_info, VSQueryResult):
+            raise BizLogicError("Italy Book requires a Query signal")
+        route = self._resolve_route(slot_info.apt_type)
+        inputs = user_inputs if isinstance(user_inputs, Mapping) else {}
+        username = str(inputs.get("username", "")).strip().casefold()
+        if not username or username != self.config.account.username.strip().casefold():
+            raise BizLogicError("Italy Book requires the applicant account")
+        if self._prepared_calendar is None:
+            entry = self._enter_service(slot_info.apt_type, route=route)
+            if not entry.success:
+                return VSBookResult(success=False, label=BOOKING_RECHECK_NONE_AVAILABLE_LABEL)
+            prepare_calendar(self, route, role="book")
         try:
-            matches = re.findall(r'{"DateLibere":"(.*?)".*?"SlotRimanenti":(-?\d+)}', text)
-            for d_str, rem in matches:
-                if int(rem) != -1:
-                    dt = datetime.strptime(d_str[:10], "%d/%m/%Y")
-                    days.append(dt.strftime("%Y-%m-%d"))
-        except Exception:
-            pass
-        return days
-
-    def _parse_time_slots(self, text: str) -> List[Dict[str, Any]]:
-        slots = []
-        try:
-            raw_list = json.loads(text)
-            for item in raw_list:
-                remain = item.get('SlotRimanenti', -1)
-                if remain > 0:
-                    start = item['OrarioInizioFascia']
-                    end = item['OrarioFineFascia']
-                    s_time = f"{start['Hours']:02d}:{start['Minutes']:02d}"
-                    e_time = f"{end['Hours']:02d}:{end['Minutes']:02d}"
-                    slots.append({
-                        'id': item['IDCalendarioServizioGiornaliero'],
-                        'start': s_time,
-                        'end': e_time,
-                        'remain': remain
-                    })
-        except Exception:
-            pass
-        return slots
+            start, end = book_date_preferences(inputs)
+            slot = recheck_calendar_before_final(
+                self.page,
+                lookahead_months=route.lookahead_months,
+                start_day=start,
+                end_day=end,
+                session_is_current=lambda: self._calendar_context_matches(
+                    route, role="book", username=username),
+                log=self._log,
+            )
+        except CalendarGateError as exc:
+            raise self._calendar_failure(exc, "Book") from None
+        if not slot:
+            return VSBookResult(success=False, label=BOOKING_RECHECK_NONE_AVAILABLE_LABEL)
+        self._log(f"Italy Book selected {slot.day} {slot.time_label}")
+        if self.free_config.get("final_submit_enabled") is True:
+            return _submit_final_once(self, route, slot)
+        return VSBookResult(success=False, label=BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
 
     def cleanup(self):
-        """销毁浏览器并彻底删除临时文件"""
-        cleanup_browser_workspace(self.page, self.root_workspace, self.tunnel, self._log)
-        self.page = None
-        self.tunnel = None
-                 
-    def get_plugin_status(self) -> PluginStatus:
-        account_name = self.config.account.username if self.config and self.config.account else ""
-        proxy_info = f"{self.config.proxy.ip}:{self.config.proxy.port}" if self.config and self.config.proxy and self.config.proxy.ip else ""
-        current_url = ""
-        if self.page:
-            try:
-                current_url = self.page.url
-            except Exception:
-                pass
-
-        session_age = int(time.time() - self.session_create_time) if self.session_create_time > 0 else 0
-        state = "running" if self.is_healthy else "unhealthy"
+        self._invalidate_query_session()
+        cleanup_browser_workspace(
+            self.page, self.root_workspace, self.tunnel, self._log)
+        self.page = self.tunnel = None
 
+    def get_plugin_status(self):
+        proxy = self.config.proxy if self.config else None
         return PluginStatus(
             instance_id=self.instance_id,
             is_healthy=self.is_healthy,
-            state=state,
-            current_url=current_url,
-            account=account_name,
-            proxy=proxy_info,
-            session_age_sec=session_age,
+            state="running" if self.is_healthy else "unhealthy",
+            current_url=str(self.page.url if self.page else ""),
+            account=self.config.account.username if self.config else "",
+            proxy=f"{proxy.ip}:{proxy.port}" if proxy and proxy.ip else "",
+            session_age_sec=0,
             last_active_at=utc_now_str(),
         )
 
     def __del__(self):
-        """
-        析构函数:当对象被垃圾回收时自动调用
-        """
-        self.cleanup()
+        try:
+            self.cleanup()
+        except Exception:
+            pass

+ 1 - 0
test/ita/__init__.py

@@ -0,0 +1 @@
+"""Italy plugin tests and test-only helpers."""

+ 12 - 0
test/ita/ita_source_sections.py

@@ -0,0 +1,12 @@
+"""Read one mechanically relocated section for existing boundary assertions."""
+from pathlib import Path
+import re
+
+
+def section(name):
+    source = (Path(__file__).resolve().parents[2] / "plugins/ita_plugin.py").read_text()
+    sections = re.split(r"\n# ={76}\n# (\w+) \(from plugins/ita_\w+\.py\)\n# ={76}\n", source)
+    matches = [sections[i + 1] for i in range(1, len(sections), 2) if sections[i] == name.upper()]
+    if len(matches) != 1:
+        raise AssertionError(f"Missing/duplicate Italy section: {name}")
+    return matches[0]

+ 81 - 0
test/ita/ita_test_fakes.py

@@ -0,0 +1,81 @@
+class FakeChromiumOptions:
+    def set_local_port(self, _port): return self
+    def set_user_data_path(self, _path): return self
+    def set_paths(self, **_kwargs): return self
+    def set_argument(self, _argument): return self
+    def headless(self, _enabled): return self
+
+
+class FakeWait:
+    def doc_loaded(self): pass
+    def load_start(self): pass
+
+
+class FakeElement:
+    def __init__(self, page, name):
+        self.page, self.name = page, name
+
+    def input(self, value, clear=False):
+        self.page.input_values[self.name] = {"value": value, "clear": clear}
+
+
+class FakePage:
+    URLS = {
+        "landing": "https://prenotami.esteri.it/",
+        "pingid": "https://iam.esteri.it/signin/?realm=/external&state=fixture#/",
+        "dashboard": "https://prenotami.esteri.it/UserArea",
+        "services": "https://prenotami.esteri.it/Services",
+        "radware": "https://validate.perfdrive.com/fixture/",
+    }
+
+    def __init__(self, *, submit_succeeds=True, has_services_link=True, login_target="pingid"):
+        self.state, self.submit_succeeds = "landing", submit_succeeds
+        self.has_services_link, self.login_target = has_services_link, login_target
+        self.wait, self.rect = FakeWait(), type("Rect", (), {"viewport_size": (1920, 1080)})()
+        self.clicked, self.input_values, self.refresh_calls = [], {}, 0
+
+    @property
+    def url(self): return self.URLS[self.state]
+
+    @property
+    def title(self):
+        return {"landing": "Login", "pingid": "Sign in", "dashboard": "Home",
+                "services": "Services", "radware": "Access Denied"}[self.state]
+
+    @property
+    def html(self): return ""
+
+    def get(self, _url): self.state = "landing"
+    def refresh(self): self.refresh_calls += 1
+    def quit(self, force=False): self.quit_force = force
+
+    def ele(self, selector, timeout=None):
+        del timeout
+        controls = {
+            ("landing", "#pingid-button"): "login",
+            ("pingid", "@name=callback_1"): "username",
+            ("pingid", "@name=callback_2"): "password",
+            ("pingid", "tag:button@type=submit"): "submit",
+            ("dashboard", ".app-menu"): "app-menu",
+        }
+        name = controls.get((self.state, selector))
+        if selector == "@href=/Services" and self.state == "dashboard" and self.has_services_link:
+            name = "book"
+        return FakeElement(self, name) if name else None
+
+
+class FakeMouse:
+    def __init__(self, page, debug=False): self.page, self.debug = page, debug
+    def move(self, _x, _y): pass
+
+    def human_click_ele(self, element):
+        if element is None:
+            raise AssertionError("attempted to click a missing element")
+        self.page.clicked.append(element.name)
+        if element.name == "login": self.page.state = self.page.login_target
+        elif element.name == "submit" and self.page.submit_succeeds: self.page.state = "dashboard"
+        elif element.name == "book": self.page.state = "services"
+
+
+class FakeKeyboard:
+    def __init__(self, page): self.page = page

+ 310 - 0
test/ita/test_add_ita_query_account.py

@@ -0,0 +1,310 @@
+import ast
+import io
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+
+import requests
+
+from tools.add_ita_query_account import (
+    ACCOUNT_POOL,
+    ACCOUNT_UPLOAD_URL,
+    SERVICE_ID,
+    run_account_upload,
+)
+
+
+class FakeResponse:
+    def __init__(self, *, status_code=200, body=None, json_error=None):
+        self.status_code = status_code
+        self.body = body if body is not None else {"code": 0, "data": {"id": 42}}
+        self.json_error = json_error
+
+    def json(self):
+        if self.json_error is not None:
+            raise self.json_error
+        return self.body
+
+
+class FakeSession:
+    def __init__(self, *, response=None, error=None):
+        self.response = response or FakeResponse()
+        self.error = error
+        self.calls = []
+        self.trust_env = True
+
+    def post(self, url, **kwargs):
+        self.calls.append((url, kwargs))
+        if self.error is not None:
+            raise self.error
+        return self.response
+
+
+class AddItaQueryAccountTests(unittest.TestCase):
+    ENV = {
+        "ITA_QUERY_USERNAME": "authorized-query@example.test",
+        "ITA_QUERY_PASSWORD": "offline-password",
+        "VS_ACCOUNT_UPLOAD_TOKEN": "offline-api-token",
+    }
+
+    @staticmethod
+    def _run(*, env=None, apply=False, config_path=None, session=None):
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        with redirect_stdout(stdout), redirect_stderr(stderr):
+            exit_code = run_account_upload(
+                env or {},
+                apply=apply,
+                non_interactive=True,
+                config_path=config_path,
+                session=session,
+            )
+        return exit_code, stdout.getvalue(), stderr.getvalue()
+
+    def test_default_preflight_sends_no_request_and_needs_no_credentials(self):
+        session = FakeSession(error=AssertionError("post must not be called"))
+
+        exit_code, stdout, stderr = self._run(session=session)
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(session.calls, [])
+        self.assertIn(
+            "ITA_ACCOUNT_UPLOAD_PREFLIGHT_OK "
+            f"pool={ACCOUNT_POOL} service_id={SERVICE_ID} request_sent=false",
+            stdout,
+        )
+        self.assertEqual(stderr, "")
+
+    def test_cli_default_dry_run_starts_from_the_repository_root(self):
+        repo_root = Path(__file__).resolve().parents[2]
+        completed = subprocess.run(
+            [sys.executable, str(repo_root / "tools" / "add_ita_query_account.py")],
+            cwd=repo_root,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+        self.assertEqual(completed.returncode, 0)
+        self.assertIn("request_sent=false", completed.stdout)
+        self.assertEqual(completed.stderr, "")
+
+    def test_apply_sends_exactly_one_locked_pool_request_without_logging_secrets(self):
+        session = FakeSession()
+
+        exit_code, stdout, stderr = self._run(
+            env=self.ENV,
+            apply=True,
+            session=session,
+        )
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(len(session.calls), 1)
+        url, kwargs = session.calls[0]
+        self.assertEqual(url, ACCOUNT_UPLOAD_URL)
+        self.assertEqual(kwargs["json"]["pool_name"], ACCOUNT_POOL)
+        self.assertEqual(kwargs["json"]["username"], self.ENV["ITA_QUERY_USERNAME"])
+        self.assertEqual(kwargs["json"]["password"], self.ENV["ITA_QUERY_PASSWORD"])
+        self.assertEqual(kwargs["json"]["extra_data"]["service_id"], SERVICE_ID)
+        self.assertEqual(kwargs["timeout"], 10)
+        self.assertFalse(session.trust_env)
+        self.assertIn("account_id=42 request_count=1", stdout)
+        combined_output = stdout + stderr
+        for secret in self.ENV.values():
+            self.assertNotIn(secret, combined_output)
+
+    def test_apply_reads_ignored_local_config_and_logs_no_secret(self):
+        local_values = {
+            "username": "local-authorized@example.test",
+            "password": "local-password",
+            "account_upload_token": "local-api-token",
+        }
+        session = FakeSession()
+        with tempfile.TemporaryDirectory() as temp_dir:
+            config_path = Path(temp_dir) / "ita_query_account.local.json"
+            config_path.write_text(json.dumps(local_values), encoding="utf-8")
+            config_path.chmod(0o600)
+
+            exit_code, stdout, stderr = self._run(
+                apply=True,
+                config_path=config_path,
+                session=session,
+            )
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(len(session.calls), 1)
+        _, kwargs = session.calls[0]
+        self.assertEqual(kwargs["json"]["username"], local_values["username"])
+        self.assertEqual(kwargs["json"]["password"], local_values["password"])
+        combined_output = stdout + stderr
+        for secret in local_values.values():
+            self.assertNotIn(secret, combined_output)
+
+    def test_invalid_local_config_fails_before_request_without_content_leak(self):
+        session = FakeSession(error=AssertionError("post must not be called"))
+        with tempfile.TemporaryDirectory() as temp_dir:
+            config_path = Path(temp_dir) / "ita_query_account.local.json"
+            config_path.write_text('{"password": "private-value",', encoding="utf-8")
+            config_path.chmod(0o600)
+
+            exit_code, stdout, stderr = self._run(
+                apply=True,
+                config_path=config_path,
+                session=session,
+            )
+
+        self.assertEqual(exit_code, 2)
+        self.assertEqual(session.calls, [])
+        self.assertEqual(stdout, "")
+        self.assertIn("local config is invalid JSON", stderr)
+        self.assertNotIn("private-value", stderr)
+
+    def test_environment_values_override_local_config(self):
+        local_values = {
+            "username": "stale@example.test",
+            "password": "stale-password",
+            "account_upload_token": "stale-token",
+        }
+        session = FakeSession()
+        with tempfile.TemporaryDirectory() as temp_dir:
+            config_path = Path(temp_dir) / "ita_query_account.local.json"
+            config_path.write_text(json.dumps(local_values), encoding="utf-8")
+            config_path.chmod(0o600)
+
+            exit_code, _, _ = self._run(
+                env=self.ENV,
+                apply=True,
+                config_path=config_path,
+                session=session,
+            )
+
+        self.assertEqual(exit_code, 0)
+        _, kwargs = session.calls[0]
+        self.assertEqual(kwargs["json"]["username"], self.ENV["ITA_QUERY_USERNAME"])
+        self.assertEqual(kwargs["json"]["password"], self.ENV["ITA_QUERY_PASSWORD"])
+
+    def test_missing_non_interactive_credentials_fails_before_request(self):
+        session = FakeSession(error=AssertionError("post must not be called"))
+
+        exit_code, stdout, stderr = self._run(
+            apply=True,
+            session=session,
+        )
+
+        self.assertEqual(exit_code, 2)
+        self.assertEqual(session.calls, [])
+        self.assertEqual(stdout, "")
+        self.assertIn("ITA_ACCOUNT_UPLOAD_CONFIG_ERROR", stderr)
+
+    def test_http_rejection_does_not_print_response_body_or_retry(self):
+        response = FakeResponse(
+            status_code=409,
+            body={"message": "authorized-query@example.test already exists"},
+        )
+        session = FakeSession(response=response)
+
+        exit_code, stdout, stderr = self._run(
+            env=self.ENV,
+            apply=True,
+            session=session,
+        )
+
+        self.assertEqual(exit_code, 4)
+        self.assertEqual(len(session.calls), 1)
+        self.assertEqual(stdout, "")
+        self.assertIn("status=409 request_count=1", stderr)
+        self.assertNotIn("already exists", stderr)
+        self.assertNotIn(self.ENV["ITA_QUERY_USERNAME"], stderr)
+
+    def test_transport_error_is_uncertain_and_explicitly_forbids_blind_retry(self):
+        session = FakeSession(error=requests.Timeout("sensitive request details"))
+
+        exit_code, stdout, stderr = self._run(
+            env=self.ENV,
+            apply=True,
+            session=session,
+        )
+
+        self.assertEqual(exit_code, 5)
+        self.assertEqual(len(session.calls), 1)
+        self.assertEqual(stdout, "")
+        self.assertIn("ITA_ACCOUNT_UPLOAD_UNCERTAIN", stderr)
+        self.assertIn("action=verify-admin-before-retry", stderr)
+        self.assertNotIn("sensitive request details", stderr)
+
+    def test_invalid_success_json_is_uncertain_not_success(self):
+        session = FakeSession(
+            response=FakeResponse(json_error=ValueError("secret response"))
+        )
+
+        exit_code, stdout, stderr = self._run(
+            env=self.ENV,
+            apply=True,
+            session=session,
+        )
+
+        self.assertEqual(exit_code, 5)
+        self.assertEqual(len(session.calls), 1)
+        self.assertEqual(stdout, "")
+        self.assertIn("type=InvalidJson", stderr)
+        self.assertNotIn("secret response", stderr)
+
+    def test_business_error_is_rejected_without_message_leak(self):
+        session = FakeSession(
+            response=FakeResponse(
+                body={"code": 40001, "message": "private server detail"}
+            )
+        )
+
+        exit_code, stdout, stderr = self._run(
+            env=self.ENV,
+            apply=True,
+            session=session,
+        )
+
+        self.assertEqual(exit_code, 4)
+        self.assertEqual(len(session.calls), 1)
+        self.assertEqual(stdout, "")
+        self.assertIn("status=business-error", stderr)
+        self.assertNotIn("private server detail", stderr)
+
+    def test_source_has_one_post_call_no_retry_loop_and_no_secret_cli_flags(self):
+        source_path = (
+            Path(__file__).resolve().parents[2]
+            / "tools"
+            / "add_ita_query_account.py"
+        )
+        source = source_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+        upload_function = next(
+            node
+            for node in tree.body
+            if isinstance(node, ast.FunctionDef)
+            and node.name == "run_account_upload"
+        )
+        post_calls = [
+            node
+            for node in ast.walk(upload_function)
+            if isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "post"
+        ]
+        retry_loops = [
+            node
+            for node in ast.walk(upload_function)
+            if isinstance(node, (ast.For, ast.While))
+        ]
+
+        self.assertEqual(len(post_calls), 1)
+        self.assertEqual(retry_loops, [])
+        self.assertNotIn("--username", source)
+        self.assertNotIn("--password", source)
+        self.assertNotIn("--token", source)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 613 - 0
test/ita/test_debug_ita_book.py

@@ -0,0 +1,613 @@
+import ast
+import io
+import tempfile
+import unittest
+from contextlib import ExitStack, redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from plugins.ita_plugin import (
+    BOOKING_CALENDAR_PREFINAL_STOP_LABEL,
+    BOOKING_FORM_DISCOVERY_STOP_LABEL,
+    BOOKING_RECHECK_NONE_AVAILABLE_LABEL,
+)
+from tools.debug_ita_book import (
+    _assert_distinct_local_accounts,
+    run_book_recheck_once,
+)
+from tools.debug_ita_session import DebugConfigurationError
+from vs_types import AvailabilityStatus, BizLogicError, VSAccount, VSBookResult
+
+
+class FakeBookDebugElement:
+    def __init__(self, text):
+        self.text = text
+
+
+class FakeBookDebugPage:
+    def __init__(self):
+        self.url = "https://prenotami.esteri.it/UserArea?state=sensitive-state"
+        self.popup_text = ""
+        self.form_structure = None
+
+    def run_js(self, script):
+        return self.form_structure
+
+    def ele(self, selector, timeout=None):
+        del timeout
+        if selector == ".jconfirm-content" and self.popup_text:
+            return FakeBookDebugElement(self.popup_text)
+        return None
+
+
+class FakeBookDebugPlugin:
+    behavior = "none-available"
+    last_instance = None
+
+    def __init__(self, group_id):
+        self.group_id = group_id
+        self.page = FakeBookDebugPage()
+        self.create_session_calls = 0
+        self.book_calls = 0
+        self.cleanup_called = False
+        self.last_trigger = None
+        self.events = []
+        FakeBookDebugPlugin.last_instance = self
+
+    def set_log(self, logger):
+        self.logger = logger
+
+    def set_config(self, config):
+        self.config = config
+
+    def create_session(self):
+        self.create_session_calls += 1
+        self.events.append("create-session")
+
+    def book(self, trigger, user_inputs=None):
+        del user_inputs
+        self.last_trigger = trigger
+        self.book_calls += 1
+        self.events.append("book")
+        if self.behavior == "booking-form":
+            self.page.form_structure = {
+                "path": "/Services/Booking/1321",
+                "form": {
+                    "method": "POST",
+                    "action_path": "/Services/Booking/1321",
+                    "secret": "must-not-appear",
+                },
+                "field_count": 1,
+                "fields": [
+                    {
+                        "tag": "input",
+                        "type": "hidden",
+                        "id": "RequestToken",
+                        "name": "__RequestVerificationToken",
+                        "required": False,
+                        "value": "private@example.test",
+                    }
+                ],
+                "button_count": 1,
+                "buttons": [
+                    {
+                        "tag": "button",
+                        "type": "submit",
+                        "id": "btnAvanti",
+                        "name": None,
+                        "text": "Avanti",
+                        "value": "server-secret",
+                    }
+                ],
+            }
+            return VSBookResult(
+                success=False,
+                label=BOOKING_FORM_DISCOVERY_STOP_LABEL,
+            )
+        if self.behavior == "unexpected-success":
+            return VSBookResult(success=True)
+        if self.behavior == "unexpected-error":
+            self.page.popup_text = "Account private@example.test ref 12345678"
+            raise RuntimeError(
+                "failed at https://iam.esteri.it/signin/"
+                "?state=sensitive-state&code_challenge=sensitive-challenge"
+            )
+        return VSBookResult(
+            success=False,
+            label=BOOKING_RECHECK_NONE_AVAILABLE_LABEL,
+        )
+
+    def cleanup(self):
+        self.cleanup_called = True
+        self.events.append("cleanup")
+
+
+class DebugItaBookSafetyTests(unittest.TestCase):
+    def setUp(self):
+        FakeBookDebugPlugin.behavior = "none-available"
+        FakeBookDebugPlugin.last_instance = None
+
+    @staticmethod
+    def _run(*, arm=False, input_side_effect=None):
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        env = {
+            "ITA_USERNAME": "offline-test@example.test",
+            "ITA_PASSWORD": "offline-password",
+        }
+        if input_side_effect is None:
+            input_side_effect = lambda _prompt: (
+                FakeBookDebugPlugin.last_instance.events.append("release")
+            )
+        with (
+            patch(
+                "tools.debug_ita_book.resolve_chrome_path",
+                return_value=Path("/test/chrome"),
+            ),
+            patch("tools.debug_ita_book.ItaPlugin", FakeBookDebugPlugin),
+            patch.dict("tools.debug_ita_book.os.environ", {}, clear=False),
+            patch(
+                "builtins.input",
+                side_effect=input_side_effect,
+            ) as input_mock,
+            redirect_stdout(stdout),
+            redirect_stderr(stderr),
+        ):
+            exit_code = run_book_recheck_once(
+                env,
+                non_interactive=True,
+                arm=arm,
+            )
+        return exit_code, stdout.getvalue(), stderr.getvalue(), input_mock
+
+    def test_no_slot_recheck_calls_book_once_and_cleans_up(self):
+        exit_code, stdout, stderr, _input_mock = self._run()
+        plugin = FakeBookDebugPlugin.last_instance
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(plugin.create_session_calls, 1)
+        self.assertEqual(plugin.book_calls, 1)
+        self.assertTrue(plugin.last_trigger.success)
+        self.assertEqual(
+            plugin.last_trigger.availability_status,
+            AvailabilityStatus.NoneAvailable,
+        )
+        self.assertTrue(plugin.cleanup_called)
+        self.assertIn("book_attempt=1", stdout)
+        self.assertIn("ITA_BOOK_RECHECK_NONE_AVAILABLE service_id=1321", stdout)
+        self.assertIn("ITA_BOOK_CLEANUP_OK", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_booking_form_is_reported_without_values_or_submission(self):
+        FakeBookDebugPlugin.behavior = "booking-form"
+
+        exit_code, stdout, stderr, _input_mock = self._run()
+        plugin = FakeBookDebugPlugin.last_instance
+
+        self.assertEqual(exit_code, 4)
+        self.assertEqual(plugin.book_calls, 1)
+        self.assertTrue(plugin.cleanup_called)
+        self.assertIn("ITA_BOOKING_FORM_STRUCTURE=", stdout)
+        self.assertIn('"action_path": "/Services/Booking/1321"', stdout)
+        self.assertIn("stage=before-avanti submit_attempts=0", stdout)
+        self.assertNotIn("private@example.test", stdout)
+        self.assertNotIn("server-secret", stdout)
+        self.assertNotIn("must-not-appear", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_unexpected_success_stops_safely(self):
+        FakeBookDebugPlugin.behavior = "unexpected-success"
+
+        exit_code, stdout, _stderr, _input_mock = self._run()
+
+        self.assertEqual(exit_code, 4)
+        self.assertIn("reason=unexpected-success-before-avanti", stdout)
+
+    def test_unexpected_error_is_sanitized_and_not_retried(self):
+        FakeBookDebugPlugin.behavior = "unexpected-error"
+
+        exit_code, stdout, stderr, _input_mock = self._run()
+        plugin = FakeBookDebugPlugin.last_instance
+
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(plugin.book_calls, 1)
+        self.assertTrue(plugin.cleanup_called)
+        self.assertNotIn("sensitive-state", stdout)
+        self.assertNotIn("sensitive-challenge", stdout)
+        self.assertNotIn("private@example.test", stdout)
+        self.assertNotIn("12345678", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_arm_waits_after_login_and_before_the_single_book_call(self):
+        exit_code, stdout, stderr, input_mock = self._run(arm=True)
+        plugin = FakeBookDebugPlugin.last_instance
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(
+            plugin.events,
+            ["create-session", "release", "book", "cleanup"],
+        )
+        input_mock.assert_called_once()
+        self.assertIn(
+            "ITA_BOOK_ARMED service_id=1321 "
+            "routing_key=slot.dub.it.tourist stage=user-area",
+            stdout,
+        )
+        self.assertEqual(stderr, "")
+
+    def test_ctrl_c_cancels_armed_mode_without_book_or_traceback(self):
+        exit_code, stdout, stderr, input_mock = self._run(
+            arm=True,
+            input_side_effect=KeyboardInterrupt,
+        )
+        plugin = FakeBookDebugPlugin.last_instance
+
+        self.assertEqual(exit_code, 130)
+        self.assertEqual(plugin.book_calls, 0)
+        self.assertEqual(plugin.events, ["create-session", "cleanup"])
+        input_mock.assert_called_once()
+        self.assertIn(
+            "ITA_BOOK_ARM_CANCELLED service_id=1321 "
+            "routing_key=slot.dub.it.tourist book_attempts=0",
+            stdout,
+        )
+        self.assertIn("ITA_BOOK_CLEANUP_OK", stdout)
+        self.assertNotIn("Traceback", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_local_signal_wait_claims_once_before_the_single_book_call(self):
+        claimed = []
+
+        def claim():
+            claimed.append("claim")
+            return object()
+
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        env = {
+            "ITA_USERNAME": "book-user@example.test",
+            "ITA_PASSWORD": "offline-password",
+        }
+        with (
+            patch(
+                "tools.debug_ita_book.resolve_chrome_path",
+                return_value=Path("/test/chrome"),
+            ),
+            patch("tools.debug_ita_book._assert_distinct_local_accounts"),
+            patch("tools.debug_ita_book.ItaPlugin", FakeBookDebugPlugin),
+            patch.dict("tools.debug_ita_book.os.environ", {}, clear=False),
+            redirect_stdout(stdout),
+            redirect_stderr(stderr),
+        ):
+            exit_code = run_book_recheck_once(
+                env,
+                non_interactive=True,
+                wait_for_local_signal=True,
+                signal_timeout=1,
+                signal_claimer=claim,
+                monotonic=lambda: 0.0,
+                sleep=lambda _seconds: None,
+            )
+
+        plugin = FakeBookDebugPlugin.last_instance
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(claimed, ["claim"])
+        self.assertEqual(plugin.events, ["create-session", "book", "cleanup"])
+        self.assertEqual(plugin.book_calls, 1)
+        self.assertEqual(plugin.config.account.username, "book-user@example.test")
+        self.assertEqual(plugin.config.account.password, "offline-password")
+        self.assertNotIn(
+            "persistent_browser_profile_path",
+            plugin.config.free_config,
+        )
+        self.assertIn("ITA_BOOK_SIGNAL_CLAIMED", stdout.getvalue())
+        self.assertEqual(stderr.getvalue(), "")
+
+    def test_local_signal_timeout_never_calls_book(self):
+        clock = iter([0.0, 0.0, 2.0])
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        env = {
+            "ITA_USERNAME": "book-user@example.test",
+            "ITA_PASSWORD": "offline-password",
+        }
+        with (
+            patch(
+                "tools.debug_ita_book.resolve_chrome_path",
+                return_value=Path("/test/chrome"),
+            ),
+            patch("tools.debug_ita_book._assert_distinct_local_accounts"),
+            patch("tools.debug_ita_book.ItaPlugin", FakeBookDebugPlugin),
+            patch.dict("tools.debug_ita_book.os.environ", {}, clear=False),
+            redirect_stdout(stdout),
+            redirect_stderr(stderr),
+        ):
+            exit_code = run_book_recheck_once(
+                env,
+                non_interactive=True,
+                wait_for_local_signal=True,
+                signal_timeout=1,
+                signal_claimer=lambda: None,
+                monotonic=lambda: next(clock),
+                sleep=lambda _seconds: None,
+            )
+
+        plugin = FakeBookDebugPlugin.last_instance
+        self.assertEqual(exit_code, 5)
+        self.assertEqual(plugin.book_calls, 0)
+        self.assertIn("ITA_BOOK_SIGNAL_WAIT_TIMEOUT", stdout.getvalue())
+        self.assertIn("book_attempts=0", stdout.getvalue())
+        self.assertEqual(stderr.getvalue(), "")
+
+    def test_automatic_handoff_rejects_the_same_query_and_book_account(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            account_path = Path(temp_dir) / "query-account.json"
+            account_path.touch()
+            with (
+                patch("tools.debug_ita_book.ITA_QUERY_ACCOUNT_FILE", account_path),
+                patch(
+                    "tools.debug_ita_book.load_local_account",
+                    return_value=VSAccount(
+                        username="same@example.test",
+                        password="query-secret",
+                    ),
+                ),
+                self.assertRaisesRegex(
+                    DebugConfigurationError,
+                    "different Query and Book accounts",
+                ),
+            ):
+                _assert_distinct_local_accounts("SAME@example.test")
+
+    def test_role_check_accepts_different_query_and_book_accounts(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            account_path = Path(temp_dir) / "query-account.json"
+            account_path.touch()
+            with (
+                patch("tools.debug_ita_book.ITA_QUERY_ACCOUNT_FILE", account_path),
+                patch(
+                    "tools.debug_ita_book.load_local_account",
+                    return_value=VSAccount(
+                        username="query@example.test",
+                        password="query-secret",
+                    ),
+                ) as query_loader,
+            ):
+                _assert_distinct_local_accounts("book@example.test")
+
+            query_loader.assert_called_once_with(account_path)
+
+    def test_entrypoint_has_one_book_call_and_no_query_call(self):
+        source_path = (
+            Path(__file__).resolve().parents[2] / "tools" / "debug_ita_book.py"
+        )
+        tree = ast.parse(source_path.read_text(encoding="utf-8"))
+        book_calls = []
+        query_calls = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            if not isinstance(node.func, ast.Attribute):
+                continue
+            if node.func.attr == "book":
+                book_calls.append(node)
+            if node.func.attr == "query":
+                query_calls.append(node)
+
+        self.assertEqual(len(book_calls), 1)
+        self.assertEqual(query_calls, [])
+
+
+class DebugItaBookWorkflowTests(unittest.TestCase):
+    """Exercise the CLI contract with synthetic adapters, never a real browser."""
+
+    def setUp(self):
+        from tools import debug_ita_book as cli
+        from tools import debug_ita_calendar_gate as audit_module
+        from tools import debug_ita_book_gate as book_gate
+        from plugins import ita_plugin as calendar
+        from test.ita.test_debug_ita_calendar_gate import gate_env
+        from test.ita.test_ita_booking_final import target
+        self.cli = cli
+        self.env = {**gate_env(), "ITA_USERNAME": "query@example.test", "ITA_PASSWORD": "query-secret"}
+        self.plugin = Mock()
+        self.approval = target().approval
+        self.plugin.book.return_value = VSBookResult(success=False, label=BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        self.counts = {"otpRequests": 1, "avantiPosts": 1, "availabilityRequests": 3,
+                       "timeSlotRequests": 3, "finalRequests": 0}
+        self.audit = Mock()
+        self.audit.settled_snapshot.side_effect = lambda: dict(self.counts)
+        self.stack = ExitStack()
+        self.addCleanup(self.stack.close)
+        self.stack.enter_context(patch.object(cli, "ItaPlugin", return_value=self.plugin))
+        self.stack.enter_context(patch.object(cli, "resolve_chrome_path", return_value=Path("/offline/chrome")))
+        self.credentials = self.stack.enter_context(patch.object(cli, "_get_credentials",
+            return_value=("applicant@example.test", "applicant-secret")))
+        self.stack.enter_context(patch.object(audit_module, "CalendarRequestAudit", return_value=self.audit))
+        self.stack.enter_context(patch.object(
+            book_gate,
+            "book_with_approval",
+            side_effect=lambda plugin, trigger, user_inputs: (
+                plugin.book(trigger, user_inputs=user_inputs), self.approval
+            ),
+        ))
+        self.stack.enter_context(patch.object(calendar, "read_calendar_service", return_value="9001"))
+        self.readback = self.stack.enter_context(patch.object(calendar, "verify_precommit_selection"))
+
+    def run_workflow(self, **kwargs):
+        output = io.StringIO()
+        with redirect_stdout(output):
+            code = self.cli.run_book_recheck_once(self.env, non_interactive=False,
+                                                 production_workflow=True, **kwargs)
+        return code, output.getvalue()
+
+    def test_auto_otp_reuses_one_public_book_call_and_keeps_final_disabled(self):
+        self.env["ITA_OTP_AUTHORIZATION_EMAIL"] = "mailbox@example.test"
+        code, output = self.run_workflow(auto_otp=True)
+        self.assertEqual(code, 0)
+        config = self.plugin.set_config.call_args.args[0]
+        self.assertEqual(config.free_config["otp_mode"], "cloud")
+        self.assertIs(config.free_config["final_submit_enabled"], False)
+        route_config = next(iter(config.free_config["apt_configs"].values()))
+        self.assertEqual(route_config["mail"], {"authorization_email": "mailbox@example.test"})
+        self.plugin.book.assert_called_once()
+        self.assertNotIn("mailbox@example.test", output)
+        self.assertIn("mode=cloud", output)
+
+    def test_auto_otp_requires_explicit_mailbox_before_session(self):
+        with self.assertRaises(self.cli.DebugConfigurationError):
+            self.run_workflow(auto_otp=True)
+        self.plugin.create_session.assert_not_called()
+
+    def test_verify_receipts_reuses_existing_gate_after_selection_without_final(self):
+        baseline = {"verified": True, "recordCount": 0, "calendarSelectionPreserved": True,
+                    "businessRequests": {k: 0 for k in self.counts}, "finalSubmissionEnabled": False}
+        self.env["ITA_OTP_AUTHORIZATION_EMAIL"] = "mailbox@example.test"
+        with patch("tools.debug_ita_book_gate._verify_receipt_baseline", return_value=baseline) as verify:
+            code, output = self.run_workflow(auto_otp=True, verify_receipts=True)
+        self.assertEqual(code, 0)
+        verify.assert_called_once_with(self.plugin, self.plugin._resolve_route.return_value)
+        self.plugin.book.assert_called_once()
+        self.assertIs(self.plugin.set_config.call_args.args[0].free_config["final_submit_enabled"], False)
+        self.assertIn("ITA_BOOK_WORKFLOW_RECEIPT_BASELINE=", output)
+        self.assertIn('"calendarSelectionPreserved": true', output)
+        self.assertIn('"finalRequests": 0', output)
+
+    def test_receipt_failure_is_not_passed_or_retried(self):
+        from plugins.ita_plugin import FinalBookingError
+        self.stack.enter_context(patch.object(self.cli, "_print_failure_context"))
+        with patch("tools.debug_ita_book_gate._verify_receipt_baseline",
+                   side_effect=FinalBookingError("Italy receipt baseline rejected")) as verify:
+            code, output = self.run_workflow(verify_receipts=True)
+        self.assertEqual(code, 1)
+        verify.assert_called_once()
+        self.plugin.book.assert_called_once()
+        self.assertNotIn("ITA_BOOK_WORKFLOW_RESULT=", output)
+        self.plugin.cleanup.assert_called_once()
+
+    def test_receipt_read_business_request_change_fails(self):
+        def unexpected(*args):
+            self.counts["otpRequests"] += 1
+            return {}
+        self.stack.enter_context(patch.object(self.cli, "_print_failure_context"))
+        with patch("tools.debug_ita_book_gate._verify_receipt_baseline", side_effect=unexpected):
+            code, output = self.run_workflow(verify_receipts=True)
+        self.assertEqual(code, 1)
+        self.assertNotIn("ITA_BOOK_WORKFLOW_RECEIPT_BASELINE=", output)
+        self.plugin.book.assert_called_once()
+
+    def test_no_candidate_skips_receipt_read_and_does_not_claim_pass(self):
+        self.plugin.book.return_value = VSBookResult(success=False, label=BOOKING_RECHECK_NONE_AVAILABLE_LABEL)
+        with patch("tools.debug_ita_book_gate._verify_receipt_baseline") as verify:
+            code, output = self.run_workflow(verify_receipts=True)
+        self.assertEqual(code, 2)
+        verify.assert_not_called()
+        self.assertNotIn("ITA_BOOK_WORKFLOW_RECEIPT_BASELINE=", output)
+
+    def test_receipt_flag_requires_workflow_and_defaults_off(self):
+        self.assertFalse(self.cli.parse_args([]).verify_receipts)
+        self.assertTrue(self.cli.parse_args(["--production-workflow", "--verify-receipts"]).verify_receipts)
+        with self.assertRaises(self.cli.DebugConfigurationError):
+            self.cli.run_book_recheck_once(self.env, non_interactive=False, verify_receipts=True)
+        self.credentials.assert_not_called()
+        self.plugin.create_session.assert_not_called()
+
+    def test_main_routes_both_opt_in_flags_and_rejects_receipts_alone(self):
+        with patch.object(self.cli, "run_book_recheck_once", return_value=0) as run:
+            self.assertEqual(self.cli.main(["--production-workflow", "--auto-otp", "--verify-receipts"]), 0)
+        self.assertIs(run.call_args.kwargs["verify_receipts"], True)
+        self.assertIs(run.call_args.kwargs["auto_otp"], True)
+        with patch.object(self.cli, "run_book_recheck_once") as run, redirect_stderr(io.StringIO()):
+            self.assertEqual(self.cli.main(["--verify-receipts"]), 2)
+        run.assert_not_called()
+
+    def test_auto_flag_without_workflow_rejected_before_login(self):
+        with self.assertRaises(self.cli.DebugConfigurationError):
+            self.cli.run_book_recheck_once(self.env, non_interactive=False, auto_otp=True)
+        self.credentials.assert_not_called()
+        self.plugin.create_session.assert_not_called()
+        self.assertTrue(self.cli.parse_args(["--production-workflow", "--auto-otp"]).auto_otp)
+
+    def test_one_public_book_call_with_applicant_identity_and_final_disabled(self):
+        code, output = self.run_workflow()
+        self.assertEqual(code, 0)
+        config = self.plugin.set_config.call_args.args[0]
+        self.assertEqual(config.account.username, "applicant@example.test")
+        self.assertEqual(config.free_config["otp_mode"], "manual")
+        self.assertEqual(config.free_config["query_mode"], "services_probe")
+        self.assertIs(config.free_config["final_submit_enabled"], False)
+        self.assertNotIn("persistent_browser_profile_path", config.free_config)
+        self.credentials.assert_called_once_with({"ITA_USERNAME": "", "ITA_PASSWORD": ""}, non_interactive=False)
+        self.plugin.book.assert_called_once()
+        self.assertEqual(self.plugin.book.call_args.kwargs["user_inputs"], {"username": "applicant@example.test"})
+        self.plugin.query.assert_not_called()
+        self.readback.assert_called_once()
+        self.audit.start.assert_called_once()
+        self.audit.stop.assert_called_once()
+        self.plugin.cleanup.assert_called_once()
+        self.assertIn('"selectionVerified": true', output)
+        self.assertIn('"finalRequests": 0', output)
+        self.assertIn("ITA_BOOK_CLEANUP_OK", output)
+        self.assertNotIn("applicant-secret", output)
+        self.assertNotIn("query-secret", output)
+
+    def test_book_specific_environment_is_used_not_general_query_credentials(self):
+        self.env.update(ITA_BOOK_USERNAME="book@example.test", ITA_BOOK_PASSWORD="book-secret")
+        self.run_workflow()
+        self.credentials.assert_called_once_with(
+            {"ITA_USERNAME": "book@example.test", "ITA_PASSWORD": "book-secret"}, non_interactive=False)
+
+    def test_no_candidate_does_not_claim_positive_acceptance(self):
+        self.plugin.book.return_value = VSBookResult(success=False, label=BOOKING_RECHECK_NONE_AVAILABLE_LABEL)
+        code, output = self.run_workflow()
+        self.assertEqual(code, 2)
+        self.assertIn('"selectionVerified": false', output)
+        self.readback.assert_not_called()
+        self.plugin.cleanup.assert_called_once()
+
+    def test_selection_readback_failure_is_not_a_pass(self):
+        self.readback.side_effect = BizLogicError("synthetic readback mismatch")
+        self.stack.enter_context(patch.object(self.cli, "_print_failure_context"))
+        code, output = self.run_workflow()
+        self.assertEqual(code, 1)
+        self.assertNotIn("ITA_BOOK_WORKFLOW_RESULT=", output)
+        self.plugin.cleanup.assert_called_once()
+
+    def test_unexpected_final_request_fails_and_never_retries(self):
+        self.counts["finalRequests"] = 1
+        self.stack.enter_context(patch.object(self.cli, "_print_failure_context"))
+        code, output = self.run_workflow()
+        self.assertEqual(code, 1)
+        self.assertNotIn("ITA_BOOK_WORKFLOW_RESULT=", output)
+        self.plugin.book.assert_called_once()
+        self.plugin.cleanup.assert_called_once()
+
+    def test_late_audit_failure_invalidates_exit_code(self):
+        self.audit.settled_snapshot.side_effect = [self.counts, RuntimeError("audit lost")]
+        code, output = self.run_workflow()
+        self.assertEqual(code, 1)
+        self.assertIn("ITA_BOOK_WORKFLOW_AUDIT_FAILED", output)
+        self.audit.stop.assert_called_once()
+        self.plugin.cleanup.assert_called_once()
+
+    def test_cleanup_failure_invalidates_exit_code(self):
+        self.plugin.cleanup.side_effect = RuntimeError("cleanup failed")
+        with redirect_stderr(io.StringIO()):
+            code, _ = self.run_workflow()
+        self.assertEqual(code, 3)
+
+    def test_legacy_flags_rejected_before_credentials(self):
+        for kwargs in ({"non_interactive": True}, {"arm": True}, {"wait_for_local_signal": True}):
+            with self.subTest(kwargs=kwargs), self.assertRaises(DebugConfigurationError):
+                self.cli.run_book_recheck_once(self.env, production_workflow=True,
+                                              **{"non_interactive": False, **kwargs})
+        self.credentials.assert_not_called()
+        self.plugin.create_session.assert_not_called()
+
+    def test_cli_flag_defaults_off(self):
+        self.assertFalse(self.cli.parse_args([]).production_workflow)
+        self.assertTrue(self.cli.parse_args(["--production-workflow"]).production_workflow)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 1212 - 0
test/ita/test_debug_ita_book_gate.py

@@ -0,0 +1,1212 @@
+import copy
+import ast
+import json
+import shutil
+import subprocess
+import tempfile
+import unittest
+from contextlib import ExitStack, redirect_stdout
+from io import StringIO
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin as calendar_book
+from plugins.ita_plugin import AVAILABILITY_PATH, CALENDAR_PATH
+from plugins.ita_plugin import ItaPlugin
+from test.ita import test_debug_ita_calendar_gate as prep_fixtures
+from test.ita import test_debug_ita_production_query_gate as audit_fixtures
+from test.ita import test_ita_calendar_book_flow as flow_fixtures
+from tools import debug_ita_book_gate as gate
+from tools import debug_ita_calendar_gate as preparation
+from vs_types import AvailabilityStatus, VSBookResult, VSQueryResult
+
+
+ORIGIN = "https://prenotami.esteri.it"
+USERNAME = "applicant@example.test"
+PASSWORD = "private-test-pass"
+OTP = "012345"
+
+
+def gate_env():
+    env = prep_fixtures.gate_env()
+    env.update(ITA_BOOK_USERNAME=USERNAME, ITA_BOOK_PASSWORD=PASSWORD)
+    return env
+
+
+class GateListener(flow_fixtures.FakeListener):
+    def stop(self):
+        # Installed DrissionPage stop() dereferences None on a repeated stop.
+        if not self.listening:
+            raise AttributeError("Fixture listener already stopped")
+        super().stop()
+
+    def start(self, targets, method):
+        # The same listener is used for preparation and the real Book scanner.
+        if targets in (preparation.OTP_PATH, self.page.booking_path):
+            self.starts += 1
+            self.target = targets
+            self.queue.clear()
+            self.listening = True
+            self.page.events.append("listen-start")
+        else:
+            super().start(targets, method)
+
+
+class GateElement:
+    def __init__(self, page, selector):
+        self.page, self.selector = page, selector
+
+    def input(self, value, *, clear):
+        if self.selector != "#otp-input" or clear is not True:
+            raise AssertionError("Unexpected input")
+        self.page.otp_value = value if self.page.otp_write_matches else ""
+
+    def run_js(self, script, value):
+        if script != "return this.value === arguments[0];":
+            raise AssertionError("Unexpected OTP readback")
+        return self.page.otp_value == value
+
+    def click(self):
+        if self.selector == "#otp-input":
+            return
+        if self.selector == "#otp-send":
+            self.page.otp_clicks += 1
+            packet = self.page.preparation_packet(preparation.OTP_PATH, "GET")
+            packet.url += "?ServiceID=" + str(self.page.service_id)
+            packet.response.raw_body = json.dumps("SENT")
+            self.page.emit(preparation.OTP_PATH, "GET")
+            if self.page.duplicate_otp:
+                self.page.emit(preparation.OTP_PATH, "GET")
+        elif self.selector == "#btnAvanti":
+            self.page.avanti_clicks += 1
+            if self.page.auto_accept is not True:
+                raise AssertionError("AVANTI confirmation was not enabled")
+            packet = self.page.preparation_packet(self.page.booking_path, "POST")
+            packet.response.status = self.page.avanti_status
+            packet.response.url = ORIGIN + CALENDAR_PATH
+            packet.response.headers = {"Location": CALENDAR_PATH + "?selectedService=fixture"}
+            self.page.url = ORIGIN + CALENDAR_PATH
+            self.page.emit(self.page.booking_path, "POST")
+            if self.page.duplicate_avanti:
+                self.page.emit(self.page.booking_path, "POST")
+            # The original page's Calendar bootstrap is not Book's fresh scan.
+            self.page.emit(AVAILABILITY_PATH, "POST")
+        else:
+            raise AssertionError("The gate must not click any other control")
+        if self.page.preparation_mutator:
+            self.page.preparation_mutator(packet, self.selector)
+        self.page.listen.queue.append(packet)
+
+
+class GatePage(flow_fixtures.FlowPage):
+    def __init__(self, months=None):
+        super().__init__(months)
+        self.url = ORIGIN + "/UserArea"
+        self.service_id = 4937
+        self.booking_path = "/Services/Booking/4937"
+        self.driver = audit_fixtures.FakeDriver()
+        self.listen = GateListener(self)
+        self.set = SimpleNamespace(auto_handle_alert=self.auto_handle_alert)
+        self.auto_accept = False
+        self.alert_settings = []
+        self.otp_value = ""
+        self.otp_write_matches = True
+        self.otp_clicks = self.avanti_clicks = 0
+        self.duplicate_otp = self.duplicate_avanti = False
+        self.avanti_status = 302
+        self.preparation_mutator = None
+        self.preflight_changes = {}
+        self.preflight_hook = None
+        self.commands = []
+
+    def auto_handle_alert(self, on_off=True, accept=True):
+        self.auto_accept = accept if on_off else False
+        self.alert_settings.append(self.auto_accept)
+
+    def run_cdp(self, name):
+        self.commands.append(name)
+        return {}
+
+    def emit(self, path, method="POST"):
+        if path.endswith("InsertNewBooking"):
+            self.guard_final_count += 1
+        callback = self.driver.immediate_event_handlers.get(preparation.CalendarRequestAudit.EVENT)
+        if callback:
+            callback(request={"url": ORIGIN + path, "method": method})
+
+    def preparation_packet(self, path, method):
+        return SimpleNamespace(
+            tab_id=self.tab_id, is_failed=False, url=ORIGIN + path, method=method,
+            response=SimpleNamespace(status=200, raw_body="", url=ORIGIN + path, headers={}),
+        )
+
+    def response_packet(self, path, body, items, day=None):
+        self.emit(path)
+        return super().response_packet(path, body, items, day)
+
+    def ele(self, selector, timeout=None):
+        if selector in ("#otp-send", "#otp-input", "#btnAvanti"):
+            return GateElement(self, selector)
+        return None
+
+    def run_js(self, script, *args):
+        if "coordinate:ita-book-gate-form-boundary" in script:
+            if self.preflight_hook:
+                self.preflight_hook()
+            return prep_fixtures.booking_preflight_snapshot(
+                formReady=self.url == ORIGIN + self.booking_path,
+                otpValuePresent=bool(self.otp_value), otpSendEnabled=self.otp_clicks == 0,
+                **self.preflight_changes,
+            )
+        if script == preparation.AVANTI_FAILURE_DIAGNOSTIC_SCRIPT:
+            return {"path": self.url.removeprefix(ORIGIN), "otpValuePresent": bool(self.otp_value),
+                    "bookingFormPresent": self.url == ORIGIN + self.booking_path}
+        return super().run_js(script, *args)
+
+
+def make_plugin(page):
+    # No constructor, files, browser, real credentials, mail or external service.
+    plugin = ItaPlugin.__new__(ItaPlugin)
+    plugin.group_id = "offline-book-gate"
+    plugin.logger = None
+    plugin.page = page
+    plugin._transient_user_data_path = "/unused/ita-book-gate-test"
+    plugin.mouse = SimpleNamespace(human_click_ele=lambda element: element.click())
+    plugin.session_create_time = 0
+    plugin.is_healthy = False
+    def create():
+        plugin.session_create_time = 123.0
+        plugin.is_healthy = True
+    plugin.create_session = Mock(side_effect=create)
+    plugin.cleanup = Mock()
+
+    def enter(apt_type, **kwargs):
+        page.url = ORIGIN + page.booking_path
+        return VSQueryResult(success=True, apt_type=apt_type, availability_status=AvailabilityStatus.NoneAvailable)
+
+    plugin._enter_service = Mock(side_effect=enter)
+    plugin.query = Mock(side_effect=AssertionError("Book must not call public Query"))
+    plugin.book = Mock(wraps=plugin.book)
+    plugin._record_calendar_prepared_route = Mock(wraps=plugin._record_calendar_prepared_route)
+    return plugin
+
+
+class BookGateFlowTests(unittest.TestCase):
+    def run_gate(self, page=None, *, env=None, execute=True, inputs=None, configure=None,
+                 otp_reader=None, before=None, after=None, reservation_hook=None,
+                 use_local_query_account=False, verify_receipts=False, submit_once=False,
+                 final_confirm=lambda _: "no", review_reader=lambda _: ""):
+        page = page or GatePage()
+        plugin = make_plugin(page)
+        # __del__ invokes cleanup again. Keep a fault-injection mock from raising
+        # an unraisable exception after this test has already asserted its result.
+        self.addCleanup(lambda: setattr(plugin.cleanup, "side_effect", None))
+        if configure:
+            configure(plugin, page)
+        captured = StringIO()
+        reservation_calls = []
+
+        def reservations(_page):
+            self.assertIs(_page, page)
+            reservation_calls.append(True)
+            if reservation_hook:
+                reservation_hook(plugin, page, len(reservation_calls))
+            return (before if len(reservation_calls) == 1 else after) or preparation.ReservationSnapshot(0, 0)
+
+        with ExitStack() as stack:
+            factory = stack.enter_context(patch.object(gate, "ItaPlugin", return_value=plugin))
+            stack.enter_context(patch.object(gate, "resolve_chrome_path", return_value=Path("/fixture/Chrome")))
+            stack.enter_context(patch.object(preparation, "read_reservation_snapshot", side_effect=reservations))
+            stack.enter_context(patch.object(preparation.CalendarRequestAudit, "settled_snapshot", lambda audit: audit.snapshot()))
+            stack.enter_context(patch.object(calendar_book, "click_next_month", side_effect=lambda _page: page.next_month()))
+            stack.enter_context(patch.object(calendar_book.time, "sleep"))
+            stack.enter_context(patch.dict(gate.os.environ, {}, clear=True))
+            stack.enter_context(redirect_stdout(captured))
+            code = gate.run_book_gate(env or gate_env(), execute=execute, user_inputs=inputs,
+                                      otp_reader=otp_reader or (lambda: OTP),
+                                      use_local_query_account=use_local_query_account,
+                                      verify_receipts=verify_receipts, submit_once=submit_once,
+                                      final_confirm=final_confirm, review_reader=review_reader)
+        output = captured.getvalue()
+        lines = [line for line in output.splitlines() if line.startswith("ITA_BOOK_GATE_RESULT=")]
+        report = json.loads(lines[-1].split("=", 1)[1]) if lines else None
+        return SimpleNamespace(code=code, report=report, output=output, plugin=plugin,
+                               page=page, factory=factory, reservation_calls=reservation_calls)
+
+    def assert_clean(self, result):
+        result.plugin.cleanup.assert_called_once()
+        self.assertFalse(result.page.listen.listening)
+        self.assertNotIn(preparation.CalendarRequestAudit.EVENT, result.page.driver.immediate_event_handlers)
+        self.assertFalse(result.page.auto_accept)
+        self.assertEqual(result.page.guard_final_count, 0)
+
+    def test_production_failures_are_distinct_and_diagnostic_precedes_reconciliation(self):
+        cases = (
+            ("Book date control was not ready before timeout", "date_control_timeout"),
+            ("Book TimeSlots request does not match the current service", "timeslot_service_mismatch"),
+            ("Book slot DOM did not match the response before timeout", "slot_dom_timeout"),
+            ("Book precommit rejected (precommit_rejected)", "precommit_readback_rejected"),
+        )
+        for message, reason in cases:
+            with self.subTest(reason=reason):
+                page = GatePage()
+                seen = []
+                original = page.run_js
+
+                def read(script, *args):
+                    if script == gate.BOOK_FAILURE_STATE_SCRIPT:
+                        seen.append(True)
+                        return book_failure_state()
+                    return original(script, *args)
+
+                def reconcile(plugin, page, count):
+                    if count == 2:
+                        self.assertEqual(seen, [True])
+
+                page.run_js = read
+                with patch.object(calendar_book, "_try_day", side_effect=calendar_book.CalendarBookError(message)):
+                    result = self.run_gate(page, reservation_hook=reconcile)
+                self.assertEqual(result.code, 1, result.output)
+                self.assertIn(f'"reason": "{reason}"', result.output)
+                self.assertIn('"readSucceeded": true', result.output)
+                self.assertEqual(result.report["calendarBookCalls"], 1)
+                self.assertEqual(result.report["requests"]["finalRequests"], 0)
+                self.assertEqual(result.report["requests"]["otpRequests"], 1)
+                self.assertEqual(result.report["requests"]["avantiPosts"], 1)
+                self.assertEqual(page.clicks, 0)
+                self.assert_clean(result)
+
+    def test_production_diagnostic_failure_does_not_replace_original_reason(self):
+        # GatePage deliberately has no implementation of this diagnostic script.
+        with patch.object(calendar_book, "_try_day", side_effect=calendar_book.CalendarBookError(
+            "Book slot click was not acknowledged",
+        )):
+            result = self.run_gate()
+        self.assertEqual(result.code, 1)
+        self.assertIn('"reason": "slot_click_not_acknowledged"', result.output)
+        self.assertIn('"readSucceeded": false', result.output)
+        self.assert_clean(result)
+
+    def test_full_gate_uses_real_book_and_stops_before_final(self):
+        result = self.run_gate()
+        self.assertEqual(result.code, 0, result.output)
+        report = result.report
+        self.assertIs(report["passed"], True)
+        self.assertEqual(report["outcome"], "pre_final")
+        self.assertEqual((report["entryBookCalls"], report["calendarBookCalls"]), (1, 1))
+        self.assertEqual(report["requests"], {"otpRequests": 1, "avantiPosts": 1,
+                                            "availabilityRequests": 2, "finalRequests": 0})
+        self.assertEqual(report["bookRequestDelta"], {"otpRequests": 0, "avantiPosts": 0,
+                                                    "availabilityRequests": 1, "finalRequests": 0})
+        self.assertEqual(report["selectedDate"], "2026-10-13")
+        self.assertEqual(report["selectedTime"], "10:05 - 11:05")
+        self.assertIs(report["bookResultSuccess"], False)
+        self.assertEqual(result.plugin.book.call_count, 2)
+        result.plugin._enter_service.assert_called_once()
+        result.plugin.query.assert_not_called()
+        self.assertEqual(result.page.clicks, 1)
+        self.assertEqual(result.page.otp_value, OTP)
+        self.assertEqual(result.page.alert_settings, [True, False])
+        self.assertEqual(result.plugin._prepared_calendar.role, "book")
+        self.assertEqual(result.plugin._record_calendar_prepared_route.call_count, 1)
+        self.assertEqual(len(result.reservation_calls), 2)
+        self.assert_clean(result)
+        for secret in (USERNAME, PASSWORD, OTP, "80000113"):
+            self.assertNotIn(secret, result.output)
+
+    def test_receipt_baseline_mode_is_retired_before_browser_creation(self):
+        with patch.object(gate, "_book_credentials") as credentials:
+            result = self.run_gate(execute=False, verify_receipts=True)
+        self.assertEqual(result.code, 1)
+        self.assertIn("Receipt-baseline mode is no longer", result.output)
+        credentials.assert_not_called()
+        result.factory.assert_not_called()
+
+    def test_submit_once_preflight_is_local_and_needs_no_persistent_fence(self):
+        with patch.object(gate, "_book_credentials") as credentials:
+            result = self.run_gate(execute=False, submit_once=True)
+        self.assertEqual(result.code, 0, result.output)
+        credentials.assert_not_called()
+        result.factory.assert_not_called()
+
+    def test_submit_once_delegates_to_one_production_result(self):
+        page = GatePage()
+
+        class FinalRun:
+            def __init__(self, plugin, route, **_kwargs):
+                self.plugin, self.route = plugin, route
+                self.possibly_submitted = False
+                self.result = None
+                self.report = {
+                    "attempted": False, "automaticRetry": True,
+                    "bookingConfirmed": False, "outcome": "not_submitted",
+                }
+
+            def execute(self, **_kwargs):
+                self.possibly_submitted = True
+                page.emit("/BookingCalendar/InsertNewBooking", "POST")
+                self.result = VSBookResult(
+                    success=True, account=USERNAME, book_date="2026-10-13",
+                    book_time="10:05 - 11:05",
+                )
+                self.report.update(
+                    attempted=True, bookingConfirmed=True, outcome="confirmed",
+                    confirmedDate=self.result.book_date, confirmedTime=self.result.book_time,
+                )
+                return self.report
+
+        with patch.object(gate.final_evidence, "FinalEvidenceRun", FinalRun):
+            result = self.run_gate(
+                page, submit_once=True,
+                before=preparation.ReservationSnapshot(1, 0),
+                after=preparation.ReservationSnapshot(1, 0),
+            )
+        self.assertEqual(result.code, 0, result.output)
+        self.assertTrue(result.report["passed"])
+        self.assertTrue(result.report["bookResultSuccess"])
+        self.assertEqual(result.report["requests"]["finalRequests"], 1)
+        self.assertTrue(result.report["finalEvidence"]["automaticRetry"])
+        result.plugin.cleanup.assert_called_once()
+        self.assertFalse(result.page.listen.listening)
+        self.assertFalse(result.page.driver.immediate_event_handlers)
+        self.assertEqual(result.page.guard_final_count, 1)
+
+    def test_final_cli_flag_is_forwarded_without_receipt_requirement(self):
+        with patch.object(gate, "run_book_gate", return_value=0) as runner:
+            self.assertEqual(gate.main(["--preflight", "--submit-once"]), 0)
+        self.assertIs(runner.call_args.kwargs["submit_once"], True)
+        self.assertIs(runner.call_args.kwargs["verify_receipts"], False)
+        self.assertIs(runner.call_args.kwargs["execute"], False)
+    def test_followed_redirect_200_is_accepted(self):
+        page = GatePage()
+        page.avanti_status = 200
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 0, result.output)
+        self.assertIn("followed_redirect_200", result.output)
+        self.assert_clean(result)
+
+    def test_config_not_geography_controls_route(self):
+        env = gate_env()
+        env.update(ITA_ROUTING_KEY="slot.other.it.tourist", ITA_CITY="Another City", ITA_SERVICE_ID="9001")
+        page = GatePage()
+        page.service_id, page.booking_path = 9001, "/Services/Booking/9001"
+        result = self.run_gate(page, env=env)
+        self.assertEqual(result.code, 0, result.output)
+        self.assertEqual(result.plugin._prepared_calendar.route.service_id, 9001)
+
+    def test_default_preflight_does_not_load_credentials_or_create_browser(self):
+        for reuse in (False, True):
+            with self.subTest(reuse=reuse), patch.object(
+                gate, "_book_credentials", side_effect=AssertionError("No credential access")
+            ), patch.object(gate, "load_local_account") as loader:
+                result = self.run_gate(execute=False, use_local_query_account=reuse)
+            self.assertEqual(result.code, 0, result.output)
+            loader.assert_not_called()
+            result.factory.assert_not_called()
+            result.plugin.create_session.assert_not_called()
+            self.assertEqual(result.reservation_calls, [])
+
+    def test_local_account_reuse_still_uses_independent_prefinal_book_flow(self):
+        with patch.object(gate, "load_local_account", return_value=SimpleNamespace(
+            username=USERNAME, password=PASSWORD,
+        )) as loader, patch.object(gate, "_get_credentials") as prompt:
+            result = self.run_gate(use_local_query_account=True)
+        loader.assert_called_once_with(gate.ITA_QUERY_ACCOUNT_FILE)
+        prompt.assert_not_called()
+        self.assertEqual(result.code, 0, result.output)
+        self.assertTrue(result.report["passed"])
+        self.assertFalse(result.report["bookResultSuccess"])
+        self.assertEqual(result.report["requests"]["finalRequests"], 0)
+        self.assertEqual(result.plugin.config.account.username, USERNAME)
+        self.assertEqual(result.plugin._prepared_calendar.role, "book")
+        self.assertIsNone(result.plugin.free_config.get(gate.PERSISTENT_BROWSER_PROFILE_KEY))
+        self.assertEqual(result.plugin.book.call_count, 2)
+        self.assertIn("source=local_query_file", result.output)
+        for secret in (USERNAME, PASSWORD, OTP):
+            self.assertNotIn(secret, result.output)
+        self.assert_clean(result)
+
+    def test_invalid_local_account_stops_before_browser_without_fallback(self):
+        with patch.object(gate, "load_local_account", side_effect=gate.LocalAccountConfigurationError(
+            f"untrusted loader detail {USERNAME} {PASSWORD}",
+        )), patch.object(gate, "_get_credentials") as prompt:
+            result = self.run_gate(use_local_query_account=True)
+        self.assertEqual(result.code, 1)
+        self.assertFalse(result.report["passed"])
+        result.factory.assert_not_called()
+        result.plugin.create_session.assert_not_called()
+        prompt.assert_not_called()
+        self.assertEqual(result.page.otp_clicks, 0)
+        self.assertEqual(result.page.avanti_clicks, 0)
+        self.assertEqual(result.reservation_calls, [])
+        self.assertIn("applicant_credentials", result.output)
+        for secret in (USERNAME, PASSWORD, "untrusted loader detail"):
+            self.assertNotIn(secret, result.output)
+
+    def test_calendar_service_failure_retains_business_exit_and_safe_diagnostic(self):
+        page = GatePage()
+        page.context_count = 0
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1, result.output)
+        self.assertFalse(result.report["passed"])
+        self.assertEqual(result.report["calendarBookCalls"], 0)
+        self.assertEqual(result.report["requests"], {
+            "otpRequests": 1, "avantiPosts": 1, "availabilityRequests": 1, "finalRequests": 0,
+        })
+        diagnostic = json.loads(next(line.split("=", 1)[1] for line in result.output.splitlines()
+                                     if line.startswith("ITA_BOOK_GATE_CALENDAR_DIAGNOSTIC=")))
+        self.assertEqual(diagnostic["controlCount"], 0)
+        self.assertTrue(diagnostic["readSucceeded"])
+        self.assertTrue(diagnostic["afterFailure"])
+        self.assertIn('"reason": "calendar_service_unidentified"', result.output)
+        self.assertNotIn("cleanup_listener", result.output)
+        self.assertEqual(page.listen.stops, 2)  # OTP and AVANTI; no third stop.
+        self.assert_clean(result)
+
+    def test_calendar_identifier_shapes_stay_rejected_without_logging_values(self):
+        for value in ("", " ", "x" * 129, 7002, None):
+            with self.subTest(value_type=type(value).__name__), patch.object(
+                gate, "CALENDAR_READY_TIMEOUT_SECONDS", 0,
+            ):
+                page = GatePage()
+                page.service = value
+                result = self.run_gate(page)
+                self.assertEqual(result.code, 1, result.output)
+                self.assertEqual(result.report["calendarBookCalls"], 0)
+                reason = "calendar_service_not_ready" if value == "" else "calendar_service_unidentified"
+                self.assertIn(f'"reason": "{reason}"', result.output)
+                diagnostic = json.loads(next(line.split("=", 1)[1] for line in result.output.splitlines()
+                                             if line.startswith("ITA_BOOK_GATE_CALENDAR_DIAGNOSTIC=")))
+                self.assertEqual(diagnostic["valueType"], type(value).__name__)
+                self.assertEqual(diagnostic["valueLength"], len(value) if isinstance(value, str) else None)
+                self.assertFalse(diagnostic["valueAccepted"])
+                self.assertNotIn("value", diagnostic)
+                self.assertNotIn("x" * 129, result.output)
+                self.assert_clean(result)
+
+    def test_calendar_initialization_can_finish_after_document_loaded(self):
+        page = GatePage()
+        original_run_js = page.run_js
+        reads = []
+
+        def delayed(script, *args):
+            result = original_run_js(script, *args)
+            if script == calendar_book.RUNTIME_SERVICE_SCRIPT:
+                reads.append(True)
+                if len(reads) == 1:
+                    return {**result, "value": ""}
+            return result
+
+        page.run_js = delayed
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 0, result.output)
+        self.assertGreater(len(reads), 1)
+        self.assertEqual(result.report["calendarBookCalls"], 1)
+        self.assertEqual(result.report["requests"]["otpRequests"], 1)
+        self.assertEqual(result.report["requests"]["avantiPosts"], 1)
+        self.assertEqual(result.report["requests"]["finalRequests"], 0)
+        self.assert_clean(result)
+
+    def test_diagnostic_read_failure_does_not_replace_the_primary_error(self):
+        page = GatePage()
+        original_run_js = page.run_js
+
+        def run_js(script, *args):
+            if script == calendar_book.RUNTIME_SERVICE_SCRIPT:
+                raise RuntimeError(f"{USERNAME} {PASSWORD} private-response")
+            return original_run_js(script, *args)
+
+        page.run_js = run_js
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1, result.output)
+        self.assertIn('"readSucceeded": false', result.output)
+        self.assertIn('"reason": "calendar_service_unidentified"', result.output)
+        for secret in (USERNAME, PASSWORD, "private-response"):
+            self.assertNotIn(secret, result.output)
+        self.assert_clean(result)
+
+    def test_active_listener_cleanup_failure_is_not_silenced(self):
+        def reservation_hook(plugin, page, count):
+            if count == 2:
+                page.listen.listening = True
+                page.listen.stop = Mock(side_effect=AttributeError("active listener failed"))
+
+        result = self.run_gate(reservation_hook=reservation_hook)
+        self.assertEqual(result.code, 3)
+        self.assertFalse(result.report["passed"])
+        self.assertIn("cleanup_listener", result.output)
+        result.page.listen.stop.assert_called_once()
+        result.plugin.cleanup.assert_called_once()
+        self.assertNotIn(preparation.CalendarRequestAudit.EVENT,
+                         result.page.driver.immediate_event_handlers)
+        self.assertEqual(result.page.guard_final_count, 0)
+
+    def test_no_route_fallback_is_allowed(self):
+        for name in prep_fixtures.gate_env():
+            with self.subTest(missing=name):
+                env = gate_env()
+                del env[name]
+                result = self.run_gate(env=env)
+                self.assertEqual(result.code, 1)
+                result.factory.assert_not_called()
+
+    def test_bad_preferences_fail_before_credentials(self):
+        for inputs in ({"expected_start_date": "20260230"}, {"username": "query@example.test"},
+                       {"expected_start_date": "2026-11-01", "expected_end_date": "2026-10-01"}):
+            with self.subTest(inputs=inputs), patch.object(gate, "_book_credentials") as credentials:
+                result = self.run_gate(inputs=inputs)
+                self.assertEqual(result.code, 1)
+                credentials.assert_not_called()
+                result.factory.assert_not_called()
+
+    def test_preferences_reach_real_book_without_changing_input(self):
+        page = GatePage([flow_fixtures.month("2026-10", {13: 1, 14: 1})])
+        inputs = {"expected_start_date": "2026-10-14", "expected_end_date": "2026-10-14"}
+        original = copy.deepcopy(inputs)
+        result = self.run_gate(page, inputs=inputs)
+        self.assertEqual(result.code, 0, result.output)
+        self.assertEqual(result.report["selectedDate"], "2026-10-14")
+        self.assertEqual(page.date_clicks, ["2026-10-14"])
+        self.assertEqual(inputs, original)
+
+    def test_entry_unavailable_does_not_send_otp(self):
+        def configure(plugin, page):
+            plugin._enter_service = Mock(return_value=VSQueryResult(success=False))
+        result = self.run_gate(configure=configure)
+        self.assertEqual(result.code, 2, result.output)
+        self.assertFalse(result.report["passed"])
+        self.assertEqual(result.report["calendarBookCalls"], 0)
+        self.assertEqual(result.page.otp_clicks, 0)
+        self.assert_clean(result)
+
+    def test_calendar_no_inventory_is_not_a_positive_gate(self):
+        page = GatePage([flow_fixtures.month("2026-10", {13: 0})])
+        result = self.run_gate(page, inputs={"expected_end_date": "2026-10-31"})
+        self.assertEqual(result.code, 2, result.output)
+        self.assertFalse(result.report["selectionVerified"])
+        self.assertFalse(result.report["passed"])
+        self.assertEqual(page.clicks, 0)
+        self.assert_clean(result)
+
+    def test_form_preflight_failure_does_not_send_otp(self):
+        page = GatePage()
+        page.preflight_changes = {"formReady": False}
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1)
+        self.assertEqual(page.otp_clicks, 0)
+        self.assert_clean(result)
+
+    def test_otp_must_really_be_written_before_avanti(self):
+        page = GatePage()
+        page.otp_write_matches = False
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1)
+        self.assertEqual((page.otp_clicks, page.avanti_clicks), (1, 0))
+        self.assert_clean(result)
+
+    def test_bad_manual_code_never_retries_or_reaches_avanti(self):
+        for value in ("", "123456", "123 abc", None):
+            with self.subTest(value=value):
+                result = self.run_gate(otp_reader=lambda: value)
+                self.assertEqual(result.code, 1)
+                self.assertEqual((result.page.otp_clicks, result.page.avanti_clicks), (1, 0))
+                self.assert_clean(result)
+
+    def test_cancel_at_manual_otp_reconciles_and_cleans_without_retry(self):
+        reader = Mock(side_effect=KeyboardInterrupt)
+        result = self.run_gate(otp_reader=reader)
+        self.assertEqual(result.code, 130)
+        self.assertEqual((result.page.otp_clicks, result.page.avanti_clicks), (1, 0))
+        self.assertEqual(len(result.reservation_calls), 2)
+        self.assert_clean(result)
+
+    def test_eof_at_manual_otp_is_safe_cancellation(self):
+        result = self.run_gate(otp_reader=Mock(side_effect=EOFError))
+        self.assertEqual(result.code, 130)
+        self.assert_clean(result)
+
+    def test_duplicate_otp_is_detected_before_reading_code(self):
+        page = GatePage()
+        page.duplicate_otp = True
+        reader = Mock(return_value=OTP)
+        result = self.run_gate(page, otp_reader=reader)
+        self.assertEqual(result.code, 1)
+        reader.assert_not_called()
+        self.assertEqual(page.avanti_clicks, 0)
+        self.assertEqual(result.report["requests"]["otpRequests"], 2)
+        self.assert_clean(result)
+
+    def test_duplicate_avanti_never_records_prepared_context(self):
+        page = GatePage()
+        page.duplicate_avanti = True
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1)
+        result.plugin._record_calendar_prepared_route.assert_not_called()
+        self.assertEqual(page.refreshes, 0)
+        self.assert_clean(result)
+
+    def test_preparation_packets_are_bound_to_tab_service_and_response(self):
+        changes = (
+            lambda packet: setattr(packet, "tab_id", "old-query-tab"),
+            lambda packet: setattr(packet, "is_failed", True),
+            lambda packet: setattr(packet.response, "status", True),
+            lambda packet: setattr(packet, "url", ORIGIN + preparation.OTP_PATH + "?ServiceID=9001"),
+            lambda packet: setattr(packet.response, "raw_body", json.dumps("NOT_SENT")),
+        )
+        for index, mutate in enumerate(changes):
+            with self.subTest(index=index):
+                page = GatePage()
+                page.preparation_mutator = lambda packet, selector: mutate(packet) if selector == "#otp-send" else None
+                result = self.run_gate(page)
+                self.assertEqual(result.code, 1)
+                self.assertEqual(page.avanti_clicks, 0)
+                self.assert_clean(result)
+
+    def test_avanti_wrong_tab_or_transition_does_not_attest_calendar(self):
+        for variant in ("wrong-tab", "wrong-target", "bad-status", "response-form"):
+            with self.subTest(variant=variant):
+                page = GatePage()
+
+                def mutate(packet, selector):
+                    if selector != "#btnAvanti":
+                        return
+                    if variant == "wrong-tab":
+                        packet.tab_id = "another-tab"
+                    elif variant == "wrong-target":
+                        packet.response.headers["Location"] = "https://other.example/BookingCalendar"
+                    elif variant == "bad-status":
+                        packet.response.status = 500
+                    else:
+                        packet.response.status = 200
+                        packet.response.url = ORIGIN + page.booking_path
+
+                page.preparation_mutator = mutate
+                result = self.run_gate(page)
+                self.assertEqual(result.code, 1)
+                result.plugin._record_calendar_prepared_route.assert_not_called()
+                self.assertEqual(page.refreshes, 0)
+                self.assert_clean(result)
+
+    def test_avanti_timeout_does_not_repeat_and_disables_auto_accept(self):
+        with patch.object(preparation, "_wait_for_calendar", side_effect=preparation.CalendarGateError("timeout")):
+            result = self.run_gate()
+        self.assertEqual(result.code, 1)
+        self.assertEqual(result.page.avanti_clicks, 1)
+        self.assertEqual(result.page.alert_settings, [True, False])
+        self.assert_clean(result)
+
+    def test_account_route_tab_and_login_drift_stop_before_otp(self):
+        mutations = (
+            lambda plugin, page: setattr(plugin.config.account, "username", "other@example.test"),
+            lambda plugin, page: setattr(page, "tab_id", "other-tab"),
+            lambda plugin, page: setattr(plugin, "session_create_time", 124.0),
+            lambda plugin, page: plugin.free_config.update(final_submit_enabled=True),
+            lambda plugin, page: setattr(plugin, "_prepared_calendar", SimpleNamespace(role="query")),
+            lambda plugin, page: plugin.free_config["apt_configs"]["slot.hkg.it.tourist"].update(service_id=9001),
+        )
+        for index, mutate in enumerate(mutations):
+            with self.subTest(index=index):
+                def configure(plugin, page):
+                    page.preflight_hook = lambda: mutate(plugin, page)
+                result = self.run_gate(configure=configure)
+                self.assertEqual(result.code, 1)
+                self.assertEqual(result.page.otp_clicks, 0)
+                self.assert_clean(result)
+
+    def test_account_change_while_reading_otp_does_not_write_code(self):
+        state = {}
+        def configure(plugin, page):
+            state["plugin"] = plugin
+        def reader():
+            state["plugin"].config.account.username = "another@example.test"
+            return OTP
+        result = self.run_gate(configure=configure, otp_reader=reader)
+        self.assertEqual(result.code, 1)
+        self.assertEqual(result.page.otp_value, "")
+        self.assertEqual(result.page.avanti_clicks, 0)
+        self.assert_clean(result)
+
+    def test_existing_calendar_is_not_accepted_as_a_fresh_login(self):
+        page = GatePage()
+        page.url = ORIGIN + CALENDAR_PATH
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1)
+        result.plugin.book.assert_not_called()
+        self.assertEqual(page.otp_clicks, 0)
+
+    def test_unexpected_book_success_is_never_reported_as_gate_success(self):
+        def configure(plugin, page):
+            plugin.book = Mock(return_value=VSBookResult(success=True, urn="private-reservation"))
+        result = self.run_gate(configure=configure)
+        self.assertEqual(result.code, 1)
+        self.assertEqual(result.page.otp_clicks, 0)
+        self.assertNotIn("private-reservation", result.output)
+        self.assert_clean(result)
+
+    def test_lost_selection_after_book_is_not_clicked_again(self):
+        def configure(plugin, page):
+            original = plugin.book
+            def call(*args, **kwargs):
+                result = original(*args, **kwargs)
+                if page.url.endswith(CALENDAR_PATH):
+                    page.active = False
+                return result
+            plugin.book = Mock(side_effect=call)
+        result = self.run_gate(configure=configure)
+        self.assertEqual(result.code, 1)
+        self.assertEqual(result.page.clicks, 1)
+        self.assert_clean(result)
+
+    def test_otp_during_book_fails_audit_without_repeating_preparation(self):
+        page = GatePage()
+        original = page.refresh
+        def refresh():
+            original()
+            page.emit(preparation.OTP_PATH, "GET")
+        page.refresh = refresh
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1)
+        self.assertEqual((page.otp_clicks, page.avanti_clicks), (1, 1))
+        self.assertFalse(result.report["passed"])
+        self.assert_clean(result)
+
+    def test_final_request_after_avanti_is_detected_before_book(self):
+        page = GatePage()
+        page.preparation_mutator = lambda packet, selector: (
+            page.emit("/BookingCalendar/InsertNewBooking") if selector == "#btnAvanti" else None
+        )
+        result = self.run_gate(page)
+        self.assertEqual(result.code, 1)
+        result.plugin._record_calendar_prepared_route.assert_not_called()
+        self.assertEqual(page.refreshes, 0)
+        self.assertEqual(result.report["requests"]["finalRequests"], 1)
+        self.assertFalse(page.auto_accept)
+
+    def test_reservation_change_prevents_positive_gate(self):
+        result = self.run_gate(after=preparation.ReservationSnapshot(1, 0))
+        self.assertEqual(result.code, 1)
+        self.assertFalse(result.report["passed"])
+        self.assert_clean(result)
+
+    def test_waitlist_change_prevents_positive_gate(self):
+        result = self.run_gate(after=preparation.ReservationSnapshot(0, 1))
+        self.assertEqual(result.code, 1)
+        self.assertFalse(result.report["passed"])
+
+    def test_late_business_request_during_reconciliation_is_detected(self):
+        def hook(plugin, page, count):
+            if count == 2:
+                page.emit(AVAILABILITY_PATH)
+        result = self.run_gate(reservation_hook=hook)
+        self.assertEqual(result.code, 1)
+        self.assertFalse(result.report["passed"])
+        self.assert_clean(result)
+
+    def test_failed_read_only_reconciliation_does_not_publish_passed(self):
+        def hook(plugin, page, count):
+            if count == 2:
+                raise RuntimeError("private-state")
+        result = self.run_gate(reservation_hook=hook)
+        self.assertEqual(result.code, 1)
+        self.assertNotIn("private-state", result.output)
+        self.assert_clean(result)
+
+    def test_cleanup_failure_has_distinct_return_code(self):
+        def configure(plugin, page):
+            plugin.cleanup.side_effect = RuntimeError("private browser details")
+        result = self.run_gate(configure=configure)
+        self.assertEqual(result.code, 3)
+        self.assertFalse(result.report["passed"])
+        self.assertNotIn("private browser details", result.output)
+
+    def test_provider_exception_does_not_log_credentials_code_or_body(self):
+        def configure(plugin, page):
+            plugin.create_session.side_effect = RuntimeError(f"{USERNAME} {PASSWORD} {OTP} BODY private")
+        result = self.run_gate(configure=configure)
+        self.assertEqual(result.code, 1)
+        for secret in (USERNAME, PASSWORD, OTP, "BODY private"):
+            self.assertNotIn(secret, result.output)
+        result.plugin.cleanup.assert_called_once()
+
+
+class BookGateInputTests(unittest.TestCase):
+    def test_cleanup_avoids_installed_sdk_duplicate_stop_failure(self):
+        from DrissionPage._units.listener import Listener
+
+        listener = Listener.__new__(Listener)
+        listener.listening = False
+        driver = listener._driver = Mock()
+        listener.stop()
+        driver.stop.assert_called_once()
+        self.assertIsNone(listener._driver)
+        # Prove the actual SDK failure, then exercise our guarded cleanup.
+        with self.assertRaises(AttributeError):
+            listener.stop()
+        gate._stop_listener_if_active(SimpleNamespace(listen=listener))
+        driver.stop.assert_called_once()
+
+    def test_cleanup_stops_an_active_listener(self):
+        listener = SimpleNamespace(listening=True, stop=Mock())
+        gate._stop_listener_if_active(SimpleNamespace(listen=listener))
+        listener.stop.assert_called_once()
+
+    def test_diagnostic_only_reads_the_calendar_and_never_emits_service_value(self):
+        for path in ("/BookingCalendar", "/Services"):
+            with self.subTest(path=path):
+                page = SimpleNamespace(url=ORIGIN + path, run_js=Mock(return_value={
+                    "path": path, "count": 1, "value": PASSWORD,
+                }))
+                captured = StringIO()
+                with redirect_stdout(captured):
+                    gate._print_calendar_preparation_diagnostic(page)
+                self.assertNotIn(PASSWORD, captured.getvalue())
+                diagnostic = json.loads(captured.getvalue().split("=", 1)[1])
+                if path == "/BookingCalendar":
+                    self.assertEqual(diagnostic["valueLength"], len(PASSWORD))
+                    page.run_js.assert_called_once_with(calendar_book.RUNTIME_SERVICE_SCRIPT)
+                else:
+                    self.assertFalse(diagnostic["pathMatches"])
+                    page.run_js.assert_not_called()
+
+    def test_preparation_reasons_only_allow_exact_known_messages(self):
+        for message, reason in (*gate._PREPARATION_FAILURES.items(), (PASSWORD, None)):
+            with self.subTest(reason=reason):
+                captured = StringIO()
+                with redirect_stdout(captured):
+                    gate._failure("calendar_preparation", gate.BizLogicError(message))
+                failure = json.loads(captured.getvalue().split("=", 1)[1])
+                self.assertEqual(failure.get("reason"), reason)
+                self.assertNotIn(PASSWORD, captured.getvalue())
+
+    def test_credentials_project_only_book_fields(self):
+        env = {"ITA_USERNAME": "query@example.test", "ITA_PASSWORD": "query-secret",
+               "ITA_BOOK_USERNAME": USERNAME, "ITA_BOOK_PASSWORD": PASSWORD}
+        with patch.object(gate, "_get_credentials", return_value=(USERNAME, PASSWORD)) as helper, \
+                patch.object(gate, "load_local_account") as loader, redirect_stdout(StringIO()):
+            self.assertEqual(gate._book_credentials(env), (USERNAME, PASSWORD))
+        helper.assert_called_once_with({"ITA_USERNAME": USERNAME, "ITA_PASSWORD": PASSWORD}, non_interactive=False)
+        loader.assert_not_called()
+
+    def test_query_credentials_do_not_supply_fallback(self):
+        with patch.object(gate, "_get_credentials", return_value=(USERNAME, PASSWORD)) as helper, \
+                patch.object(gate, "load_local_account") as loader, redirect_stdout(StringIO()):
+            gate._book_credentials({"ITA_USERNAME": "query@example.test", "ITA_PASSWORD": "query-secret"})
+        helper.assert_called_once_with({"ITA_USERNAME": "", "ITA_PASSWORD": ""}, non_interactive=False)
+        loader.assert_not_called()
+
+    def test_local_account_opt_in_uses_complete_saved_pair_and_never_prompts(self):
+        env = {"ITA_BOOK_USERNAME": "other@example.test", "ITA_BOOK_PASSWORD": "other-pass",
+               "ITA_USERNAME": "general@example.test", "ITA_PASSWORD": "general-pass"}
+        captured = StringIO()
+        with patch.object(gate, "load_local_account", return_value=SimpleNamespace(
+            username=USERNAME, password=PASSWORD,
+        )) as loader, patch.object(gate, "_get_credentials") as prompt, redirect_stdout(captured):
+            self.assertEqual(
+                gate._book_credentials(env, use_local_query_account=True), (USERNAME, PASSWORD),
+            )
+        loader.assert_called_once_with(gate.ITA_QUERY_ACCOUNT_FILE)
+        prompt.assert_not_called()
+        self.assertIn("source=local_query_file", captured.getvalue())
+        for secret in (USERNAME, PASSWORD, *env.values()):
+            self.assertNotIn(secret, captured.getvalue())
+
+    def test_local_loader_errors_are_safe_and_never_switch_credentials(self):
+        for reason in ("missing file", "unsafe permissions", "invalid JSON", "missing password"):
+            with self.subTest(reason=reason), patch.object(
+                gate, "load_local_account",
+                side_effect=gate.LocalAccountConfigurationError(f"{reason} {PASSWORD}"),
+            ), patch.object(gate, "_get_credentials") as prompt:
+                with self.assertRaises(gate.BookGateError) as caught:
+                    gate._book_credentials(gate_env(), use_local_query_account=True)
+                prompt.assert_not_called()
+                self.assertNotIn(PASSWORD, str(caught.exception))
+                self.assertIn("config/ita_query_account.local.json", str(caught.exception))
+
+    def test_local_secrets_are_not_part_of_source_fingerprint(self):
+        self.assertNotIn(gate.ITA_QUERY_ACCOUNT_FILE, gate.BOOK_GATE_SOURCE_PATHS)
+        self.assertIn(gate.REPO_ROOT / "utils" / "local_account.py", gate.BOOK_GATE_SOURCE_PATHS)
+
+    def test_cli_defaults_to_no_external_actions(self):
+        with patch.object(gate, "run_book_gate", return_value=0) as runner:
+            self.assertEqual(gate.main([]), 0)
+        self.assertIs(runner.call_args.kwargs["execute"], False)
+        self.assertIs(runner.call_args.kwargs["use_local_query_account"], False)
+
+    def test_cli_forwards_explicit_local_account_selection(self):
+        for mode, execute in (("--preflight", False), ("--run", True)):
+            with self.subTest(mode=mode), patch.object(gate, "run_book_gate", return_value=0) as runner:
+                self.assertEqual(gate.main(["--use-local-query-account", mode]), 0)
+            self.assertIs(runner.call_args.kwargs["execute"], execute)
+            self.assertIs(runner.call_args.kwargs["use_local_query_account"], True)
+
+    def test_cli_maps_vfs_preferences_to_real_inputs(self):
+        with patch.object(gate, "run_book_gate", return_value=0) as runner:
+            gate.main(["--run", "--expected-start-date", "2026-10-01", "--expected-end-date", "2026-12-31"])
+        self.assertIs(runner.call_args.kwargs["execute"], True)
+        self.assertEqual(runner.call_args.kwargs["user_inputs"],
+                         {"expected_start_date": "2026-10-01", "expected_end_date": "2026-12-31"})
+
+    def test_audit_rejects_non_integer_counts(self):
+        audit = Mock()
+        for value in (True, -1, "0", None):
+            audit.settled_snapshot.return_value = {
+                "otpRequests": value, "avantiPosts": 0, "availabilityRequests": 0, "finalRequests": 0,
+            }
+            with self.subTest(value=value), self.assertRaises(gate.BookGateError):
+                gate._counts(audit)
+
+    def test_no_query_session_loader_or_profile_setup_or_final_click_in_tool(self):
+        source = Path(gate.__file__).read_text()
+        # Only the explicitly read-only diagnostic may mention the final button.
+        self.assertEqual(source.count(gate.BOOK_FAILURE_STATE_SCRIPT), 1)
+        source = source.replace(gate.BOOK_FAILURE_STATE_SCRIPT, "")
+        for forbidden in ("_get_query_credentials(", "_prepare_query_profile(", "prepare_ita_query_profile(",
+                          "#btnPrenotaNoOtp", "InsertNewBooking"):
+            self.assertNotIn(forbidden, source)
+        registrations = [node for node in ast.walk(ast.parse(source))
+                         if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute)
+                         and node.func.attr == "_record_calendar_prepared_route"]
+        self.assertEqual(len(registrations), 1)
+        self.assertEqual({kw.arg: ast.literal_eval(kw.value) for kw in registrations[0].keywords}, {"role": "book"})
+        self.assertIn("preparation.OneShotAction", source)
+        self.assertIn("plugin.book(trigger", source)
+
+
+def book_failure_state():
+    result = {key: False for key in gate._BOOK_STATE_BOOLS}
+    result.update({key: 0 for key in gate._BOOK_STATE_COUNTS})
+    result.update(pathMatches=True, serviceValuePresent=True, serviceControlCount=1,
+                  finalButtonCount=1, finalGuarded=True, slotStates=[])
+    return result
+
+
+class BookProductionDiagnosticTests(unittest.TestCase):
+    def test_static_reason_messages_exist_in_the_current_producer_source(self):
+        source = Path(calendar_book.__file__).read_text() + (gate.REPO_ROOT / "plugins/ita_plugin.py").read_text()
+        for message in gate._PRODUCTION_BOOK_FAILURES:
+            if message in {"Book precommit rejected (precommit_rejected)",
+                           "Book TimeSlots request fields changed"}:
+                continue  # Produced by the shared protocol/request formatters and covered by packet tests.
+            with self.subTest(message=message):
+                self.assertIn(message, source)
+
+    def test_plugin_internal_failure_keeps_its_classification(self):
+        output = StringIO()
+        with redirect_stdout(output):
+            gate._failure("production_book", gate.BizLogicError(
+                "Italy Book Calendar failed before final confirmation",
+            ))
+        failure = json.loads(output.getvalue().split("=", 1)[1])
+        self.assertEqual(failure["reason"], "calendar_internal_failure")
+
+    def capture_state(self, raw):
+        page = SimpleNamespace(url=ORIGIN + CALENDAR_PATH, run_js=Mock(return_value=raw))
+        output = StringIO()
+        with redirect_stdout(output):
+            gate._print_production_book_diagnostic(page)
+        page.run_js.assert_called_once_with(gate.BOOK_FAILURE_STATE_SCRIPT)
+        return output.getvalue(), json.loads(output.getvalue().split("=", 1)[1])
+
+    def test_all_allowlisted_failures_publish_only_the_fixed_reason(self):
+        for message, reason in gate._PRODUCTION_BOOK_FAILURES.items():
+            with self.subTest(reason=reason):
+                output = StringIO()
+                with redirect_stdout(output):
+                    gate._failure("production_book", gate.BizLogicError(message))
+                result = json.loads(output.getvalue().split("=", 1)[1])
+                self.assertEqual(result["reason"], reason)
+                self.assertNotEqual(result["message"], message)
+
+    def test_unknown_body_and_wrong_stage_or_exception_type_are_not_exposed(self):
+        secret = f"Book slot DOM did not match the response before timeout {USERNAME} {PASSWORD} {OTP}"
+        for stage, error in (("production_book", gate.BizLogicError(secret)),
+                             ("production_book", RuntimeError(secret)),
+                             ("calendar_preparation", gate.BizLogicError(secret))):
+            with self.subTest(stage=stage, error_type=type(error).__name__):
+                output = StringIO()
+                with redirect_stdout(output):
+                    gate._failure(stage, error)
+                for value in (USERNAME, PASSWORD, OTP):
+                    self.assertNotIn(value, output.getvalue())
+                self.assertNotIn('"reason": "slot_dom_timeout"', output.getvalue())
+
+    def test_protocol_messages_emit_a_category_without_echoing_dynamic_code(self):
+        for label, expected in (("TimeSlots protocol", "timeslot_protocol_rejected"),
+                                ("Calendar protocol", "calendar_protocol_rejected"),
+                                ("precommit", "precommit_readback_rejected")):
+            output = StringIO()
+            with redirect_stdout(output):
+                gate._failure("production_book", gate.BizLogicError(f"Book {label} rejected (synthetic_code)"))
+            self.assertIn(f'"reason": "{expected}"', output.getvalue())
+            self.assertNotIn("synthetic_code", output.getvalue())
+
+    def test_valid_shape_is_reported_as_after_failure_not_original_error_state(self):
+        state = book_failure_state()
+        state["slotStates"] = [{**{key: False for key in gate._BOOK_SLOT_BOOLS}, "hiddenInputCount": 1}]
+        state["slotCount"] = 1
+        _, result = self.capture_state(state)
+        self.assertTrue(result["afterFailure"])
+        self.assertTrue(result["readSucceeded"])
+        self.assertEqual(result["state"], state)
+
+    def test_unexpected_fields_and_types_fail_closed_without_partial_values(self):
+        bad = []
+        state = book_failure_state()
+        bad.append({**state, "serviceValue": PASSWORD})
+        bad.append({**state, "serviceValuePresent": PASSWORD})
+        bad.append({**state, "slotCount": PASSWORD})
+        bad.append({**state, "slotCount": True})
+        bad.append({**state, "slotStates": [{"body": PASSWORD}]})
+        bad.append({**state, "slotStates": [{}] * 13})
+        bad.append({**state, "timeSlotResourceEntries": -1})
+        for raw in bad:
+            with self.subTest(raw_keys=tuple(raw)):
+                output, result = self.capture_state(raw)
+                self.assertFalse(result["readSucceeded"])
+                self.assertNotIn("state", result)
+                self.assertNotIn(PASSWORD, output)
+
+    def test_non_calendar_page_is_not_read(self):
+        page = SimpleNamespace(url=ORIGIN + "/Reservation", run_js=Mock())
+        output = StringIO()
+        with redirect_stdout(output):
+            gate._print_production_book_diagnostic(page)
+        page.run_js.assert_not_called()
+        self.assertIn('"readSucceeded": false', output.getvalue())
+
+    @unittest.skipUnless(shutil.which("node"), "Node is required for the read-only JS fixture")
+    def test_readonly_script_distinguishes_offscreen_and_obscured_slots(self):
+        fixture = r"""
+const script = process.argv[1], mode = process.argv[2];
+let measured = [];
+const makeSlot = (index) => ({
+  index,
+  classList: {contains: value => index === 0 && value === 'notAvailableFascia'},
+  querySelector: () => null,
+  querySelectorAll: () => [{get value() {throw Error('must not read slot identity');}}],
+  getBoundingClientRect: () => {
+    measured.push(index);
+    const left = index === 1 ? 1100 : 10;
+    return {left, right:left+100, top:20, bottom:60, width:100, height:40};
+  },
+  contains: () => false,
+  get innerText() {throw Error('must not read slot text');},
+  click: () => {throw Error('must not click');},
+});
+const slots = Array.from({length:mode === 'many' ? 13 : 3}, (_, index) => makeSlot(index));
+const timelineLink = {dataset:{date:'2026-10-13'}};
+const document = {
+  querySelector: selector => selector === '.selected' ? timelineLink : null,
+  querySelectorAll: selector => {
+    if (selector === '#idServizio') return [{value:'private-runtime-identifier'}];
+    if (selector === '.events a.selected') return [timelineLink];
+    if (selector === '.events-content li.selected') return [{dataset:{date:'2026-10-13'},querySelectorAll:()=>slots}];
+    if (selector === '#btnPrenotaNoOtp') return [Object.freeze({disabled:true,dataset:{coordinateFinalGuard:'enabled'}})];
+    if (selector === '.fascia.act') return [];
+    throw Error('unexpected selector');
+  },
+  elementFromPoint: () => slots[0],
+};
+const window = {innerWidth:1000, innerHeight:800,
+  getComputedStyle:()=>({display:'block',visibility:'visible',pointerEvents:'auto',opacity:'1'})};
+const location = {origin:'https://prenotami.esteri.it',pathname:'/BookingCalendar'};
+const performance = {getEntriesByType:()=>[
+  {name:location.origin+'/BookingCalendar/RetrieveTimeSlots'},
+  {name:'https://other.example.test/BookingCalendar/RetrieveTimeSlots'},
+  {name:'not-a-url'},
+]};
+const result = new Function('document','window','location','performance',script)(document,window,location,performance);
+console.log(JSON.stringify({result,measured}));
+"""
+        for mode in ("normal", "many"):
+            with self.subTest(mode=mode):
+                result = subprocess.run([shutil.which("node"), "-e", fixture, gate.BOOK_FAILURE_STATE_SCRIPT, mode],
+                                        text=True, capture_output=True, timeout=10)
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertNotIn("private-runtime-identifier", result.stdout)
+                raw = json.loads(result.stdout)["result"]
+                self.assertTrue(raw["selectedDatesMatch"])
+                self.assertTrue(raw["firstSelectedIsTimeline"])
+                self.assertTrue(raw["finalGuarded"])
+                self.assertEqual(raw["timeSlotResourceEntries"], 1)
+                self.assertFalse(raw["slotStates"][1]["inViewport"])
+                self.assertTrue(raw["slotStates"][1]["cssVisible"])
+                self.assertTrue(raw["slotStates"][2]["inViewport"])
+                self.assertFalse(raw["slotStates"][2]["centerHit"])
+                self.assertEqual(len(raw["slotStates"]), 12 if mode == "many" else 3)
+                self.assertEqual(raw["slotStatesTruncated"], mode == "many")
+                _, accepted = self.capture_state(raw)
+                self.assertTrue(accepted["readSucceeded"])
+
+
+class BookGateFormBoundaryScriptTests(unittest.TestCase):
+    def test_valid_boundary_uses_original_preflight_and_native_hidden_sync(self):
+        node = shutil.which("node")
+        if node is None:
+            self.fail("Node is required to validate the real preparation script")
+        config = preparation.build_calendar_gate_config(gate_env(), username=USERNAME, password=PASSWORD)
+        route = gate.resolve_route_config(config.free_config["apt_configs"], "slot.hkg.it.tourist")
+        script = gate._guarded_preflight_script(route, "/Services/Booking/4937")
+        harness = r"""
+const location = {origin: 'https://prenotami.esteri.it', pathname: '/Services/Booking/4937',
+                  href: 'https://prenotami.esteri.it/Services/Booking/4937'};
+const hidden = {value: '0'}, companions = {value: '1'}, purposeHidden = {value: '0'};
+const booking = {value: '0', options: [{value: '1', textContent: 'Single booking'}],
+                 dispatchEvent: () => { hidden.value = '1'; companions.value = '0'; }};
+const purpose = {value: '0', options: [{value: '42', textContent: 'Tourism'}], dispatchEvent: () => {}};
+const privacy = {checked: false, click() { this.checked = true; }};
+const form = {action: location.href, method: 'post', enctype: 'multipart/form-data', querySelectorAll: () => []};
+const ids = {typeofbookingddl: booking, ddls_0: purpose, PrivacyCheck: privacy,
+             hiddenTipoPrenotazione: hidden, numAccSelected: companions, hiddenSelezionato_0: purposeHidden};
+const selectors = {'#bookingForm': [form], '#otp-input': [{value: ''}], '#otp-send': [{disabled: false}],
+                   '#btnAvanti': [{disabled: false}], 'input[name="cf-turnstile-response"]': [{value: 'fixture-only'}]};
+const document = {getElementById: (id) => ids[id], querySelector: () => form,
+                  querySelectorAll: (selector) => selectors[selector] || []};
+const output = new Function('document', 'location', 'window', SCRIPT)(document, location, {location});
+if (purposeHidden.value !== '0') throw Error('Must not write purpose hidden before native AVANTI');
+process.stdout.write(JSON.stringify(output));
+""".replace("SCRIPT", json.dumps(script))
+        completed = subprocess.run([node, "-e", harness], capture_output=True, text=True, timeout=10)
+        self.assertEqual(completed.returncode, 0, completed.stderr)
+        preparation.validate_booking_preflight(json.loads(completed.stdout))
+
+    def test_actual_script_checks_scope_before_reused_form_mutations(self):
+        node = shutil.which("node")
+        if node is None:
+            self.fail("Node is required to validate the real preparation boundary script")
+        config = preparation.build_calendar_gate_config(gate_env(), username=USERNAME, password=PASSWORD)
+        route = gate.resolve_route_config(config.free_config["apt_configs"], "slot.hkg.it.tourist")
+        script = gate._guarded_preflight_script(route, "/Services/Booking/4937")
+        harness = r"""
+const script = SCRIPT;
+const scenarios = ['wrongOrigin', 'wrongPath', 'noForm', 'twoForms', 'getForm',
+                   'wrongAction', 'queryAction', 'changedEnctype', 'upload'];
+for (const scenario of scenarios) {
+  let mutationReads = 0;
+  const location = {origin: 'https://prenotami.esteri.it', pathname: '/Services/Booking/4937',
+                    href: 'https://prenotami.esteri.it/Services/Booking/4937'};
+  const form = {method: 'post', enctype: 'multipart/form-data', action: location.href,
+                querySelectorAll: () => scenario === 'upload' ? [{}] : []};
+  if (scenario === 'wrongOrigin') location.origin = 'https://other.example';
+  if (scenario === 'wrongPath') location.pathname = '/BookingCalendar';
+  if (scenario === 'getForm') form.method = 'get';
+  if (scenario === 'wrongAction') form.action = 'https://other.example/Services/Booking/4937';
+  if (scenario === 'queryAction') form.action += '?changed=1';
+  if (scenario === 'changedEnctype') form.enctype = 'text/plain';
+  const document = {
+    querySelectorAll: () => scenario === 'noForm' ? [] : scenario === 'twoForms' ? [form, form] : [form],
+    querySelector: () => { mutationReads++; throw Error('Must stop before preflight'); }
+  };
+  const result = new Function('document', 'location', script)(document, location);
+  if (result.formReady !== false || mutationReads !== 0) throw Error(scenario);
+}
+process.stdout.write('FORM_BOUNDARY_OK');
+""".replace("SCRIPT", json.dumps(script))
+        completed = subprocess.run([node, "-e", harness], capture_output=True, text=True, timeout=10)
+        self.assertEqual(completed.returncode, 0, completed.stderr)
+        self.assertEqual(completed.stdout, "FORM_BOUNDARY_OK")
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 1578 - 0
test/ita/test_debug_ita_calendar_gate.py

@@ -0,0 +1,1578 @@
+import ast
+import hashlib
+import json
+import unittest
+from contextlib import redirect_stdout
+from io import StringIO
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from plugins.ita_plugin import CALENDAR_GUARD_SCRIPT
+from plugins.ita_plugin import resolve_route_config
+from tools.debug_ita_calendar_gate import (
+    BookingPreflightStage,
+    CalendarGateMode,
+    CalendarGateError,
+    CalendarGateEvidence,
+    CalendarMonthScanResult,
+    CalendarNextMonthUnavailableError,
+    CalendarProbeResult,
+    NEXT_MONTH_CONTROL_SCRIPT,
+    OneShotAction,
+    QCAL_TOOL_CONTRACT_VERSION,
+    QCAL_TOOL_SOURCE_FINGERPRINT,
+    ReservationSnapshot,
+    _click_next_month,
+    _enter_otp,
+    _read_manual_otp,
+    build_calendar_gate_config,
+    compare_availability_transport,
+    listen_once,
+    parse_availability_packet,
+    read_reservation_snapshot,
+    resolve_qcal_forward_months,
+    resolve_qcal_mode,
+    run_calendar_gate,
+    safe_avanti_failure_diagnostic,
+    safe_next_month_diagnostic,
+    safe_preflight_diagnostic,
+    scan_calendar_horizon,
+    transport_comparison_report,
+    validate_avanti_packet,
+    validate_booking_preflight,
+    validate_next_month_snapshot,
+    validate_otp_packet,
+    wait_for_booking_preflight,
+)
+
+
+def gate_env():
+    return {
+        "ITA_ROUTING_KEY": "slot.hkg.it.tourist",
+        "ITA_SERVICE_ID": "4937",
+        "ITA_CITY": "Hong Kong",
+        "ITA_VISA_TYPE": "Tourist",
+        "ITA_CALENDAR_LOOKAHEAD_MONTHS": "3",
+        "ITA_BOOKING_TYPE_CONTROL_ID": "typeofbookingddl",
+        "ITA_BOOKING_TYPE_VALUE": "1",
+        "ITA_BOOKING_TYPE_LABELS": "Prenotazione Singola|Single booking",
+        "ITA_PURPOSE_CONTROL_ID": "ddls_0",
+        "ITA_PURPOSE_VALUE": "42",
+        "ITA_PURPOSE_LABELS": "Turismo|Tourism",
+    }
+
+
+def booking_preflight_snapshot(**changes):
+    snapshot = {
+        "formReady": True,
+        "turnstileReady": True,
+        "otpValuePresent": False,
+        "otpSendEnabled": True,
+        "avantiEnabled": True,
+    }
+    snapshot.update(changes)
+    return snapshot
+
+
+class FakeResponse:
+    def __init__(self, status, *, url="", raw_body="", headers=None):
+        self.status = status
+        self.url = url
+        self.raw_body = raw_body
+        self.headers = headers or {}
+
+
+class FakePacket:
+    def __init__(
+        self,
+        *,
+        method,
+        url,
+        status,
+        response_url="",
+        raw_body="",
+        headers=None,
+        post_data=None,
+    ):
+        self.method = method
+        self.url = url
+        self.response = FakeResponse(
+            status,
+            url=response_url,
+            raw_body=raw_body,
+            headers=headers,
+        )
+        self.request = SimpleNamespace(postData=post_data)
+
+
+class FakeListener:
+    def __init__(self, packet=None):
+        self.packet = packet
+        self.starts = []
+        self.waits = []
+        self.stop_count = 0
+
+    def start(self, target, method=None):
+        self.starts.append((target, method))
+
+    def wait(self, timeout=None):
+        self.waits.append(timeout)
+        return self.packet
+
+    def stop(self):
+        self.stop_count += 1
+
+
+class FakeReservationTab:
+    def __init__(self, outputs):
+        self.outputs = list(outputs)
+        self.wait = SimpleNamespace(doc_loaded=lambda: None)
+        self.close_count = 0
+
+    def run_js(self, _script):
+        if len(self.outputs) > 1:
+            return self.outputs.pop(0)
+        return self.outputs[0]
+
+    def close(self):
+        self.close_count += 1
+
+
+class CalendarGateConfigTests(unittest.TestCase):
+    def test_builds_one_explicit_live_route_with_final_disabled(self):
+        config = build_calendar_gate_config(
+            gate_env(),
+            username="offline@example.test",
+            password="not-a-real-password",
+        )
+        free_config = config.free_config
+        route = resolve_route_config(
+            free_config["apt_configs"],
+            "slot.hkg.it.tourist",
+        )
+
+        self.assertEqual(free_config["query_mode"], "services_probe")
+        self.assertIs(free_config["final_submit_enabled"], False)
+        self.assertEqual(route.service_id, 4937)
+        self.assertEqual(route.capability.value, "single_schengen_tourism")
+        self.assertEqual(route.lookahead_months, 3)
+        self.assertEqual(route.booking_type.control_id, "typeofbookingddl")
+        self.assertEqual(route.booking_type.value, "1")
+        self.assertEqual(route.purpose.value, "42")
+
+    def test_missing_any_live_route_field_fails_closed(self):
+        for missing in (
+            "ITA_CALENDAR_LOOKAHEAD_MONTHS",
+            "ITA_BOOKING_TYPE_CONTROL_ID",
+            "ITA_BOOKING_TYPE_LABELS",
+            "ITA_PURPOSE_VALUE",
+        ):
+            with self.subTest(missing=missing):
+                env = gate_env()
+                env.pop(missing)
+                with self.assertRaisesRegex(CalendarGateError, missing):
+                    build_calendar_gate_config(
+                        env,
+                        username="offline@example.test",
+                        password="not-a-real-password",
+                    )
+
+    def test_resolves_a_separate_bounded_discovery_horizon(self):
+        self.assertEqual(resolve_qcal_forward_months({}), 1)
+        self.assertEqual(
+            resolve_qcal_forward_months({"ITA_QCAL_FORWARD_MONTHS": "12"}),
+            12,
+        )
+        for invalid in ("0", "13", "invalid", "1.5"):
+            with self.subTest(invalid=invalid):
+                with self.assertRaisesRegex(
+                    CalendarGateError,
+                    "ITA_QCAL_FORWARD_MONTHS",
+                ):
+                    resolve_qcal_forward_months(
+                        {"ITA_QCAL_FORWARD_MONTHS": invalid}
+                    )
+
+    def test_transport_comparison_is_explicit_and_default_remains_discovery(self):
+        self.assertIs(resolve_qcal_mode({}), CalendarGateMode.DISCOVERY_HORIZON)
+        self.assertIs(
+            resolve_qcal_mode({"ITA_QCAL_MODE": "transport_compare"}),
+            CalendarGateMode.TRANSPORT_COMPARE,
+        )
+        with self.assertRaisesRegex(CalendarGateError, "transport_compare"):
+            resolve_qcal_mode({"ITA_QCAL_MODE": "browser_fetch"})
+
+
+class GateValueObjectTests(unittest.TestCase):
+    def test_reservation_snapshot_requires_nonnegative_plain_integers(self):
+        self.assertEqual(
+            ReservationSnapshot(reservations=0, waitlist=1).total,
+            1,
+        )
+        for kwargs in (
+            {"reservations": -1, "waitlist": 0},
+            {"reservations": True, "waitlist": 0},
+            {"reservations": 0, "waitlist": "0"},
+        ):
+            with self.subTest(kwargs=kwargs):
+                with self.assertRaises(CalendarGateError):
+                    ReservationSnapshot(**kwargs)
+
+    def test_gate_evidence_passes_only_the_exact_qcal_contract(self):
+        empty = ReservationSnapshot(0, 0)
+        evidence = CalendarGateEvidence(
+            before=empty,
+            after=empty,
+            otp_requests=1,
+            avanti_posts=1,
+            availability_requests=2,
+            final_requests=0,
+            calendar_ready=True,
+        )
+        self.assertTrue(evidence.passed)
+
+        variants = (
+            {"after": ReservationSnapshot(1, 0)},
+            {"otp_requests": 0},
+            {"avanti_posts": 2},
+            {"availability_requests": 1},
+            {"final_requests": 1},
+            {"calendar_ready": False},
+        )
+        for changes in variants:
+            with self.subTest(changes=changes):
+                values = {
+                    "before": evidence.before,
+                    "after": evidence.after,
+                    "otp_requests": evidence.otp_requests,
+                    "avanti_posts": evidence.avanti_posts,
+                    "availability_requests": evidence.availability_requests,
+                    "final_requests": evidence.final_requests,
+                    "calendar_ready": evidence.calendar_ready,
+                }
+                values.update(changes)
+                self.assertFalse(CalendarGateEvidence(**values).passed)
+
+    def test_one_shot_action_marks_attempt_before_calling(self):
+        calls = []
+        guard = OneShotAction("OTP")
+        self.assertEqual(guard.run(lambda: calls.append("called") or 7), 7)
+        self.assertEqual(calls, ["called"])
+
+        with self.assertRaisesRegex(CalendarGateError, "OTP.*already attempted"):
+            guard.run(lambda: calls.append("second"))
+        self.assertEqual(calls, ["called"])
+
+        failing = OneShotAction("AVANTI")
+        with self.assertRaisesRegex(RuntimeError, "ambiguous"):
+            failing.run(
+                lambda: (_ for _ in ()).throw(RuntimeError("ambiguous"))
+            )
+        with self.assertRaisesRegex(CalendarGateError, "already attempted"):
+            failing.run(lambda: None)
+
+
+class NetworkContractTests(unittest.TestCase):
+    def test_listener_always_stops_and_performs_one_action(self):
+        packet = object()
+        listener = FakeListener(packet)
+        page = SimpleNamespace(listen=listener)
+        actions = []
+
+        result = listen_once(
+            page,
+            target="/safe-endpoint",
+            method="POST",
+            action=lambda: actions.append("one"),
+            timeout=9,
+        )
+
+        self.assertIs(result, packet)
+        self.assertEqual(actions, ["one"])
+        self.assertEqual(listener.starts, [("/safe-endpoint", "POST")])
+        self.assertEqual(listener.waits, [9])
+        self.assertEqual(listener.stop_count, 1)
+
+        failing_listener = FakeListener(None)
+        failing_page = SimpleNamespace(listen=failing_listener)
+        with self.assertRaisesRegex(CalendarGateError, "not observed"):
+            listen_once(
+                failing_page,
+                target="/safe-endpoint",
+                method="GET",
+                action=lambda: None,
+                timeout=1,
+            )
+        self.assertEqual(failing_listener.stop_count, 1)
+
+        raising_listener = FakeListener(packet)
+        raising_page = SimpleNamespace(listen=raising_listener)
+        with self.assertRaisesRegex(RuntimeError, "action failed"):
+            listen_once(
+                raising_page,
+                target="/safe-endpoint",
+                method="POST",
+                action=lambda: (_ for _ in ()).throw(
+                    RuntimeError("action failed")
+                ),
+                timeout=1,
+            )
+        self.assertEqual(raising_listener.stop_count, 1)
+
+    def test_otp_requires_exact_get_route_status_and_json_string(self):
+        packet = FakePacket(
+            method="GET",
+            url=(
+                "https://prenotami.esteri.it/BookingCalendar/GenerateOTP"
+                "?ServiceID=4937"
+            ),
+            status=200,
+            raw_body='"SENT"',
+        )
+        validate_otp_packet(packet, service_id=4937)
+
+        bad_packets = (
+            FakePacket(
+                method="POST",
+                url=packet.url,
+                status=200,
+                raw_body='"SENT"',
+            ),
+            FakePacket(
+                method="GET",
+                url=packet.url,
+                status=201,
+                raw_body='"SENT"',
+            ),
+            FakePacket(
+                method="GET",
+                url=packet.url,
+                status=200,
+                raw_body="SENT",
+            ),
+            FakePacket(
+                method="GET",
+                url=packet.url.replace("4937", "1321"),
+                status=200,
+                raw_body='"SENT"',
+            ),
+        )
+        for bad in bad_packets:
+            with self.subTest(packet=bad):
+                with self.assertRaises(CalendarGateError):
+                    validate_otp_packet(bad, service_id=4937)
+
+    def test_avanti_accepts_direct_302_to_the_observed_calendar(self):
+        packet = FakePacket(
+            method="POST",
+            url="https://prenotami.esteri.it/Services/Booking/4937",
+            status=302,
+            headers={
+                "Location": (
+                    "/BookingCalendar?selectedService="
+                    "Visti%20Nazionali%20e%20Schengen"
+                )
+            },
+        )
+        mode = validate_avanti_packet(
+            packet,
+            booking_path="/Services/Booking/4937",
+            final_page_url=(
+                "https://prenotami.esteri.it/BookingCalendar"
+                "?selectedService=Visti"
+            ),
+        )
+        self.assertEqual(mode, "direct_302")
+
+    def test_avanti_accepts_only_a_triply_consistent_followed_200(self):
+        packet = FakePacket(
+            method="POST",
+            url="https://prenotami.esteri.it/Services/Booking/4937",
+            status=200,
+            response_url=(
+                "https://prenotami.esteri.it/BookingCalendar"
+                "?selectedService=Visti"
+            ),
+        )
+        mode = validate_avanti_packet(
+            packet,
+            booking_path="/Services/Booking/4937",
+            final_page_url="https://prenotami.esteri.it/BookingCalendar",
+        )
+        self.assertEqual(mode, "followed_redirect_200")
+
+    def test_avanti_rejects_inconsistent_redirect_evidence(self):
+        cases = (
+            {
+                "status": 200,
+                "response_url": "https://prenotami.esteri.it/Services",
+                "final_page_url": "https://prenotami.esteri.it/BookingCalendar",
+            },
+            {
+                "status": 200,
+                "response_url": "https://example.test/BookingCalendar",
+                "final_page_url": "https://prenotami.esteri.it/BookingCalendar",
+            },
+            {
+                "status": 200,
+                "response_url": (
+                    "https://prenotami.esteri.it:444/BookingCalendar"
+                ),
+                "final_page_url": "https://prenotami.esteri.it/BookingCalendar",
+            },
+            {
+                "status": 200,
+                "response_url": "https://prenotami.esteri.it/BookingCalendar",
+                "final_page_url": "https://prenotami.esteri.it/Services",
+            },
+            {
+                "status": 201,
+                "response_url": "https://prenotami.esteri.it/BookingCalendar",
+                "final_page_url": "https://prenotami.esteri.it/BookingCalendar",
+            },
+        )
+        for case in cases:
+            with self.subTest(case=case):
+                bad = FakePacket(
+                    method="POST",
+                    url=(
+                        "https://prenotami.esteri.it/Services/Booking/4937"
+                    ),
+                    status=case["status"],
+                    response_url=case["response_url"],
+                )
+                with self.assertRaises(CalendarGateError):
+                    validate_avanti_packet(
+                        bad,
+                        booking_path="/Services/Booking/4937",
+                        final_page_url=case["final_page_url"],
+                    )
+
+    def test_avanti_rejects_bad_direct_redirects_and_requests(self):
+        for method, request_url, location in (
+            (
+                "POST",
+                "https://prenotami.esteri.it/Services/Booking/4937",
+                "/Services",
+            ),
+            (
+                "POST",
+                "https://prenotami.esteri.it/Services/Booking/4937",
+                "https://example.test/BookingCalendar",
+            ),
+            (
+                "POST",
+                "https://prenotami.esteri.it/Services/Booking/4937?retry=1",
+                "/BookingCalendar",
+            ),
+            (
+                "GET",
+                "https://prenotami.esteri.it/Services/Booking/4937",
+                "/BookingCalendar",
+            ),
+            (
+                "POST",
+                "https://prenotami.esteri.it/Services/Booking/1321",
+                "/BookingCalendar",
+            ),
+            (
+                "POST",
+                "https://example.test/Services/Booking/4937",
+                "/BookingCalendar",
+            ),
+            (
+                "POST",
+                "https://prenotami.esteri.it/Services/Booking/4937",
+                "",
+            ),
+        ):
+            with self.subTest(
+                method=method,
+                request_url=request_url,
+                location=location,
+            ):
+                packet = FakePacket(
+                    method=method,
+                    url=request_url,
+                    status=302,
+                    headers={"Location": location},
+                )
+                with self.assertRaises(CalendarGateError):
+                    validate_avanti_packet(
+                        packet,
+                        booking_path="/Services/Booking/4937",
+                        final_page_url=(
+                            "https://prenotami.esteri.it/BookingCalendar"
+                        ),
+                    )
+
+    def test_avanti_failure_diagnostic_is_strictly_allowlisted(self):
+        packet = FakePacket(
+            method="POST",
+            url="https://prenotami.esteri.it/Services/Booking/4937",
+            status=200,
+            response_url=(
+                "https://prenotami.esteri.it/Services/Booking/4937"
+                "?private-response-query"
+            ),
+            raw_body="private-response-body",
+            headers={
+                "Location": (
+                    "/BookingCalendar?private-location-query"
+                )
+            },
+            post_data="private-form-data",
+        )
+        raw = {
+            "path": "/Services/Booking/4937",
+            "bookingFormPresent": True,
+            "otpValuePresent": True,
+            "otpInvalidVisible": False,
+            "avantiDisabled": False,
+            "turnstileTokenPresent": False,
+            "visibleValidationCount": 1,
+            "visibleConfirmCount": 0,
+            "finalRequestCount": 0,
+            "mustNotLeak": "private-runtime-value",
+        }
+
+        diagnostic = safe_avanti_failure_diagnostic(
+            packet,
+            raw,
+            booking_path="/Services/Booking/4937",
+        )
+
+        self.assertEqual(
+            set(diagnostic),
+            {
+                "outcome",
+                "contract",
+                "sourceFingerprint",
+                "snapshotType",
+                "bookingPostObserved",
+                "requestMatches",
+                "responseStatus",
+                "responsePath",
+                "locationPath",
+                "browserPath",
+                "bookingFormPresent",
+                "otpValuePresent",
+                "otpInvalidVisible",
+                "avantiDisabled",
+                "turnstileReady",
+                "visibleValidationCount",
+                "visibleConfirmCount",
+                "finalRequestCount",
+            },
+        )
+        self.assertEqual(diagnostic["outcome"], "booking_form_returned")
+        self.assertIs(diagnostic["bookingPostObserved"], True)
+        self.assertIs(diagnostic["requestMatches"], True)
+        self.assertEqual(
+            diagnostic["responseStatus"],
+            {"type": "int", "value": 200},
+        )
+        self.assertEqual(diagnostic["responsePath"], "booking")
+        self.assertEqual(diagnostic["locationPath"], "calendar")
+        self.assertEqual(diagnostic["browserPath"], "booking")
+        self.assertEqual(
+            diagnostic["otpValuePresent"],
+            {"type": "bool", "value": True},
+        )
+        serialized = json.dumps(diagnostic)
+        for private_value in (
+            "private-response-query",
+            "private-response-body",
+            "private-location-query",
+            "private-form-data",
+            "private-runtime-value",
+        ):
+            self.assertNotIn(private_value, serialized)
+
+    def test_avanti_failure_diagnostic_degrades_unknown_values(self):
+        diagnostic = safe_avanti_failure_diagnostic(
+            None,
+            "private-runtime-value",
+            booking_path="/Services/Booking/4937",
+        )
+
+        self.assertEqual(
+            diagnostic["outcome"],
+            "booking_post_not_observed",
+        )
+        self.assertIs(diagnostic["bookingPostObserved"], False)
+        self.assertEqual(diagnostic["responsePath"], "missing")
+        self.assertEqual(diagnostic["browserPath"], "missing")
+        self.assertEqual(
+            diagnostic["otpValuePresent"],
+            {"type": "NoneType", "value": None},
+        )
+        self.assertNotIn(
+            "private-runtime-value",
+            json.dumps(diagnostic),
+        )
+
+    def test_availability_packet_reuses_the_strict_protocol_parser(self):
+        inner = json.dumps(
+            [
+                {
+                    "DateLibere": "01/10/2026 00:00:00",
+                    "SlotLiberi": 0,
+                    "SlotRimanenti": -1,
+                },
+                {
+                    "DateLibere": "02/10/2026 00:00:00",
+                    "SlotLiberi": 1,
+                    "SlotRimanenti": 0,
+                },
+            ]
+        )
+        packet = FakePacket(
+            method="POST",
+            url=(
+                "https://prenotami.esteri.it/BookingCalendar/"
+                "RetrieveCalendarAvailability"
+            ),
+            status=200,
+            raw_body=json.dumps(inner),
+            post_data=json.dumps(
+                {"_Servizio": "runtime-only", "selectedDay": "01/10/2026"}
+            ),
+        )
+
+        result = parse_availability_packet(packet)
+
+        self.assertEqual(result.item_count, 2)
+        self.assertEqual(result.available_count, 1)
+        self.assertEqual(result.selected_day, "01/10/2026")
+        self.assertEqual(result.selected_month, (2026, 10))
+        self.assertFalse(result.days[0].is_available)
+        self.assertTrue(result.days[1].is_available)
+
+        packet.request.postData = json.dumps(
+            {
+                "_Servizio": "runtime-only",
+                "selectedDay": "01/10/2026",
+                "guessed": True,
+            }
+        )
+        with self.assertRaisesRegex(CalendarGateError, "request keys"):
+            parse_availability_packet(packet)
+
+    def test_browser_fetch_transport_matches_the_native_month_without_leaking_service(self):
+        inner = json.dumps(
+            [
+                {
+                    "DateLibere": "01/10/2026 00:00:00",
+                    "SlotLiberi": 0,
+                    "SlotRimanenti": -1,
+                },
+                {
+                    "DateLibere": "02/10/2026 00:00:00",
+                    "SlotLiberi": 1,
+                    "SlotRimanenti": 0,
+                },
+            ]
+        )
+        raw_body = json.dumps(inner)
+        packet = FakePacket(
+            method="POST",
+            url="https://prenotami.esteri.it/BookingCalendar/RetrieveCalendarAvailability",
+            status=200,
+            raw_body=raw_body,
+            post_data=json.dumps(
+                {"_Servizio": "private-runtime-id", "selectedDay": "01/10/2026"}
+            ),
+        )
+        native = parse_availability_packet(packet)
+        calls = []
+
+        def fetch(*args, **kwargs):
+            calls.append((args, kwargs))
+            return SimpleNamespace(
+                status_code=200,
+                url=packet.url,
+                text=raw_body,
+            )
+
+        report = compare_availability_transport(
+            SimpleNamespace(), packet, native, fetch=fetch
+        )
+
+        self.assertEqual(
+            report,
+            {
+                "month": "2026-10",
+                "dayCount": 2,
+                "availableCount": 1,
+                "equivalent": True,
+            },
+        )
+        self.assertEqual(calls[0][0][1:3], ("POST", packet.url))
+        self.assertEqual(calls[0][1]["timeout"], 30)
+        self.assertEqual(
+            calls[0][1]["json_data"],
+            {"_Servizio": "private-runtime-id", "selectedDay": "01/10/2026"},
+        )
+        self.assertNotIn("private-runtime-id", json.dumps(report))
+
+    def test_browser_fetch_transport_rejects_inventory_status_and_raw_body_changes(self):
+        inner = json.dumps(
+            [{
+                "DateLibere": "01/10/2026 00:00:00",
+                "SlotLiberi": 0,
+                "SlotRimanenti": -1,
+            }]
+        )
+        packet = FakePacket(
+            method="POST",
+            url="https://prenotami.esteri.it/BookingCalendar/RetrieveCalendarAvailability",
+            status=200,
+            raw_body=json.dumps(inner),
+            post_data={"_Servizio": "private-runtime-id", "selectedDay": "01/10/2026"},
+        )
+        native = parse_availability_packet(packet)
+        changed = json.dumps(json.dumps([{
+            "DateLibere": "01/10/2026 00:00:00",
+            "SlotLiberi": 1,
+            "SlotRimanenti": 0,
+        }]))
+        cases = (
+            (
+                SimpleNamespace(status_code=200, url=packet.url, text=changed),
+                "inventory differed",
+            ),
+            (
+                SimpleNamespace(status_code=429, url=packet.url, text="private-rate-body"),
+                "rate limited",
+            ),
+            (
+                SimpleNamespace(status_code=401, url=packet.url, text="private-auth-body"),
+                "authentication expired",
+            ),
+            (
+                SimpleNamespace(status_code=403, url=packet.url, text="private-denied-body"),
+                "access was denied",
+            ),
+            (
+                SimpleNamespace(status_code=503, url=packet.url, text="private-transient-body"),
+                "temporarily failed",
+            ),
+            (
+                SimpleNamespace(status_code=200, url="https://iam.esteri.it/signin/", text="private-login"),
+                "response URL changed",
+            ),
+            (
+                SimpleNamespace(status_code=200, url=packet.url, text="private-malformed-body"),
+                "response rejected",
+            ),
+        )
+        for response, expected in cases:
+            with self.subTest(expected=expected):
+                with self.assertRaisesRegex(CalendarGateError, expected) as caught:
+                    compare_availability_transport(
+                        SimpleNamespace(), packet, native,
+                        fetch=lambda *_args, **_kwargs: response,
+                    )
+                self.assertNotIn("private", str(caught.exception))
+
+    def test_transport_report_requires_two_reads_per_month_and_no_business_writes(self):
+        comparisons = [
+            {"month": "2026-08", "dayCount": 2, "availableCount": 0, "equivalent": True},
+            {"month": "2026-09", "dayCount": 3, "availableCount": 1, "equivalent": True},
+        ]
+        before = {
+            "otpRequests": 1,
+            "avantiPosts": 1,
+            "availabilityRequests": 0,
+            "finalRequests": 0,
+        }
+        after = {**before, "availabilityRequests": 4}
+
+        report = transport_comparison_report(
+            comparisons, before, after, native_requests=2
+        )
+
+        self.assertTrue(report["coverageComplete"])
+        self.assertTrue(report["requestContractMatched"])
+        self.assertEqual(report["emptyMonths"], 1)
+        self.assertEqual(report["positiveMonths"], 1)
+        self.assertEqual(
+            report["compareRequestDelta"],
+            {
+                "otpRequests": 0,
+                "avantiPosts": 0,
+                "availabilityRequests": 4,
+                "finalRequests": 0,
+            },
+        )
+
+        for changed in (
+            {**after, "otpRequests": 2},
+            {**after, "avantiPosts": 2},
+            {**after, "finalRequests": 1},
+            {**after, "availabilityRequests": 3},
+        ):
+            with self.subTest(changed=changed):
+                bad = transport_comparison_report(
+                    comparisons, before, changed, native_requests=2
+                )
+                self.assertFalse(bad["requestContractMatched"])
+
+
+class NextMonthControlTests(unittest.TestCase):
+    def test_snapshot_requires_one_actionable_control_and_exact_shape(self):
+        ready = {
+            "pathMatches": True,
+            "candidateCount": 4,
+            "actionableCount": 1,
+            "clicked": False,
+        }
+        self.assertIs(
+            validate_next_month_snapshot(
+                ready,
+                expected_clicked=False,
+            ),
+            ready,
+        )
+
+        unready = {**ready, "actionableCount": 0}
+        validate_next_month_snapshot(
+            unready,
+            expected_clicked=False,
+            allow_unready=True,
+        )
+        for changed, message in (
+            ({**ready, "actionableCount": 2}, "uniquely actionable"),
+            ({**ready, "candidateCount": True}, "candidateCount"),
+            ({**ready, "clicked": True}, "acknowledgement"),
+            ({**ready, "private": "value"}, "unexpected fields"),
+        ):
+            with self.subTest(changed=changed):
+                with self.assertRaisesRegex(CalendarGateError, message):
+                    validate_next_month_snapshot(
+                        changed,
+                        expected_clicked=False,
+                    )
+
+    def test_click_waits_then_atomically_clicks_once(self):
+        outputs = [
+            {
+                "pathMatches": True,
+                "candidateCount": 4,
+                "actionableCount": 0,
+                "clicked": False,
+            },
+            {
+                "pathMatches": True,
+                "candidateCount": 4,
+                "actionableCount": 1,
+                "clicked": False,
+            },
+            {
+                "pathMatches": True,
+                "candidateCount": 4,
+                "actionableCount": 1,
+                "clicked": True,
+            },
+        ]
+        calls = []
+
+        def run_js(script, should_click):
+            calls.append((script, should_click))
+            return outputs.pop(0)
+
+        stdout = StringIO()
+        with redirect_stdout(stdout):
+            with patch("tools.debug_ita_calendar_gate.time.sleep"):
+                _click_next_month(
+                    SimpleNamespace(run_js=run_js),
+                    timeout=1,
+                )
+
+        self.assertEqual(
+            [should_click for _script, should_click in calls],
+            [False, False, True],
+        )
+        self.assertTrue(
+            all(script == NEXT_MONTH_CONTROL_SCRIPT for script, _ in calls)
+        )
+        self.assertEqual(
+            stdout.getvalue().count("ITA_QCAL_NEXT_MONTH_DIAGNOSTIC="),
+            1,
+        )
+        self.assertIn('"clicked": {"type": "bool", "value": true}', stdout.getvalue())
+
+    def test_click_uses_a_distinct_error_for_an_unavailable_boundary(self):
+        with self.assertRaises(CalendarNextMonthUnavailableError):
+            _click_next_month(
+                SimpleNamespace(run_js=lambda _script, _click: None),
+                timeout=0,
+            )
+
+    def test_diagnostic_allowlist_never_serializes_unknown_values(self):
+        raw = {
+            "pathMatches": True,
+            "candidateCount": 4,
+            "actionableCount": 1,
+            "clicked": False,
+            "private": "private-runtime-value",
+        }
+
+        diagnostic = safe_next_month_diagnostic(raw)
+
+        self.assertEqual(
+            set(diagnostic),
+            {
+                "contract",
+                "sourceFingerprint",
+                "snapshotType",
+                "pathMatches",
+                "candidateCount",
+                "actionableCount",
+                "clicked",
+            },
+        )
+        self.assertNotIn("private-runtime-value", json.dumps(diagnostic))
+
+
+class CalendarHorizonScanTests(unittest.TestCase):
+    @staticmethod
+    def packet(month: int, available: bool = False) -> FakePacket:
+        slots_free = 1 if available else 0
+        slots_remaining = 0 if available else -1
+        inner = json.dumps(
+            [
+                {
+                    "DateLibere": f"01/{month:02d}/2026 00:00:00",
+                    "SlotLiberi": slots_free,
+                    "SlotRimanenti": slots_remaining,
+                }
+            ]
+        )
+        return FakePacket(
+            method="POST",
+            url=(
+                "https://prenotami.esteri.it/BookingCalendar/"
+                "RetrieveCalendarAvailability"
+            ),
+            status=200,
+            raw_body=json.dumps(inner),
+            post_data=json.dumps(
+                {
+                    "_Servizio": "runtime-only",
+                    "selectedDay": f"01/{month:02d}/2026",
+                }
+            ),
+        )
+
+    def test_scans_the_initial_month_plus_the_forward_limit(self):
+        packets = [
+            self.packet(8),
+            self.packet(9, available=True),
+            self.packet(10),
+        ]
+        actions = []
+        guards = []
+
+        def fake_listen(_page, *, action, **_kwargs):
+            action()
+            return packets.pop(0)
+
+        stdout = StringIO()
+        with redirect_stdout(stdout):
+            with patch(
+                "tools.debug_ita_calendar_gate.listen_once",
+                side_effect=fake_listen,
+            ), patch(
+                "tools.debug_ita_calendar_gate._refresh_calendar",
+                side_effect=lambda _page: actions.append("refresh"),
+            ), patch(
+                "tools.debug_ita_calendar_gate._click_next_month",
+                side_effect=lambda _page: actions.append("next"),
+            ), patch(
+                "tools.debug_ita_calendar_gate._calendar_guard",
+                side_effect=lambda _page: guards.append("guard"),
+            ), patch("tools.debug_ita_calendar_gate.time.sleep"):
+                result = scan_calendar_horizon(
+                    SimpleNamespace(),
+                    forward_months=2,
+                )
+
+        self.assertEqual(actions, ["refresh", "next", "next"])
+        self.assertEqual(guards, ["guard", "guard", "guard"])
+        self.assertEqual(result.forward_clicks, 2)
+        self.assertEqual(result.availability_requests, 3)
+        self.assertEqual(result.stop_reason, "forward_limit_reached")
+        self.assertEqual(result.probes[1].available_count, 1)
+        self.assertEqual(result.probes[-1].available_count, 0)
+        self.assertEqual(result.safe_dict()["monthsWithAvailability"], 1)
+        self.assertEqual(
+            result.safe_dict()["earliestAvailableDate"],
+            "2026-09-01",
+        )
+        self.assertEqual(result.safe_dict()["furthestMonth"], "2026-10")
+        self.assertIn("ITA_QCAL_MONTH_SCAN_RESULT=", stdout.getvalue())
+
+    def test_transport_observer_receives_each_native_packet_after_guard(self):
+        packets = [self.packet(8), self.packet(9, available=True)]
+        events = []
+
+        def fake_listen(_page, *, action, **_kwargs):
+            action()
+            return packets.pop(0)
+
+        with patch(
+            "tools.debug_ita_calendar_gate.listen_once",
+            side_effect=fake_listen,
+        ), patch(
+            "tools.debug_ita_calendar_gate._refresh_calendar",
+            side_effect=lambda _page: events.append("refresh"),
+        ), patch(
+            "tools.debug_ita_calendar_gate._click_next_month",
+            side_effect=lambda _page: events.append("next"),
+        ), patch(
+            "tools.debug_ita_calendar_gate._calendar_guard",
+            side_effect=lambda _page: events.append("guard"),
+        ), patch("tools.debug_ita_calendar_gate.time.sleep"):
+            result = scan_calendar_horizon(
+                SimpleNamespace(),
+                forward_months=1,
+                packet_observer=lambda packet, probe: events.append(
+                    (packet.url, probe.selected_month)
+                ),
+            )
+
+        self.assertEqual(result.availability_requests, 2)
+        self.assertEqual(events[0:3], [
+            "refresh",
+            "guard",
+            (
+                "https://prenotami.esteri.it/BookingCalendar/RetrieveCalendarAvailability",
+                (2026, 8),
+            ),
+        ])
+        self.assertEqual(events[3], "next")
+        self.assertEqual(events[4], "guard")
+        self.assertEqual(events[5][1], (2026, 9))
+
+    def test_invalid_transport_observer_fails_before_browser_actions(self):
+        page = SimpleNamespace()
+        with self.assertRaisesRegex(CalendarGateError, "packet_observer"):
+            scan_calendar_horizon(page, forward_months=1, packet_observer=object())
+
+    def test_stops_cleanly_when_the_native_next_control_is_unavailable(self):
+        packets = [self.packet(8)]
+
+        def fake_listen(_page, *, action, **_kwargs):
+            action()
+            return packets.pop(0)
+
+        with patch(
+            "tools.debug_ita_calendar_gate.listen_once",
+            side_effect=fake_listen,
+        ), patch(
+            "tools.debug_ita_calendar_gate._refresh_calendar",
+        ), patch(
+            "tools.debug_ita_calendar_gate._click_next_month",
+            side_effect=CalendarNextMonthUnavailableError("bounded-stop"),
+        ), patch(
+            "tools.debug_ita_calendar_gate._calendar_guard",
+        ), patch("tools.debug_ita_calendar_gate.time.sleep"):
+            result = scan_calendar_horizon(
+                SimpleNamespace(),
+                forward_months=12,
+            )
+
+        self.assertEqual(result.forward_clicks, 0)
+        self.assertEqual(result.stop_reason, "next_control_unavailable")
+        self.assertTrue(result.safe_dict()["nextControlUnavailable"])
+
+    def test_result_rejects_skipped_or_excess_months(self):
+        august = CalendarProbeResult(
+            days=(),
+            selected_day="01/08/2026",
+        )
+        october = CalendarProbeResult(
+            days=(),
+            selected_day="01/10/2026",
+        )
+        with self.assertRaisesRegex(CalendarGateError, "exactly one month"):
+            CalendarMonthScanResult(
+                probes=(august, october),
+                requested_forward_months=2,
+                stop_reason="next_control_unavailable",
+            )
+        with self.assertRaisesRegex(CalendarGateError, "ended before"):
+            CalendarMonthScanResult(
+                probes=(august,),
+                requested_forward_months=2,
+                stop_reason="forward_limit_reached",
+            )
+
+    def test_result_accepts_an_exact_cross_year_transition(self):
+        december = CalendarProbeResult(
+            days=(),
+            selected_day="01/12/2026",
+        )
+        january = CalendarProbeResult(
+            days=(),
+            selected_day="01/01/2027",
+        )
+
+        result = CalendarMonthScanResult(
+            probes=(december, january),
+            requested_forward_months=1,
+            stop_reason="forward_limit_reached",
+        )
+
+        self.assertEqual(result.safe_dict()["startMonth"], "2026-12")
+        self.assertEqual(result.safe_dict()["furthestMonth"], "2027-01")
+        self.assertIsNone(result.safe_dict()["earliestAvailableDate"])
+
+
+class BookingPreflightTests(unittest.TestCase):
+    def test_diagnostic_is_stage_specific_and_strictly_allowlisted(self):
+        raw = booking_preflight_snapshot(otpSendEnabled=1)
+        raw["mustNotLeak"] = "private-runtime-value"
+
+        diagnostic = safe_preflight_diagnostic(
+            raw,
+            stage=BookingPreflightStage.AFTER_OTP_SEND,
+            outcome="rejected",
+        )
+
+        self.assertEqual(
+            set(diagnostic),
+            {
+                "contract",
+                "sourceFingerprint",
+                "outcome",
+                "stage",
+                "snapshotType",
+                "formReady",
+                "otpValuePresent",
+                "otpSendEnabled",
+                "avantiEnabled",
+                "turnstileReady",
+            },
+        )
+        self.assertEqual(
+            diagnostic["contract"],
+            QCAL_TOOL_CONTRACT_VERSION,
+        )
+        self.assertEqual(
+            diagnostic["sourceFingerprint"],
+            QCAL_TOOL_SOURCE_FINGERPRINT,
+        )
+        self.assertEqual(diagnostic["stage"], "after_otp_send")
+        self.assertEqual(
+            diagnostic["otpSendEnabled"],
+            {"type": "int", "value": None},
+        )
+        self.assertEqual(
+            diagnostic["otpValuePresent"],
+            {"type": "bool", "value": False},
+        )
+        self.assertNotIn(
+            "private-runtime-value",
+            json.dumps(diagnostic),
+        )
+
+        invalid_outcome = safe_preflight_diagnostic(
+            raw,
+            stage=BookingPreflightStage.AFTER_OTP_SEND,
+            outcome="private-runtime-value",
+        )
+        self.assertEqual(invalid_outcome["outcome"], "invalid")
+        self.assertNotIn(
+            "private-runtime-value",
+            json.dumps(invalid_outcome),
+        )
+
+    def test_rejected_preflight_logs_shape_without_runtime_values(self):
+        raw = booking_preflight_snapshot(otpSendEnabled=1)
+        raw["mustNotLeak"] = "private-runtime-value"
+        page = SimpleNamespace(run_js=lambda _script: raw)
+        stdout = StringIO()
+
+        with redirect_stdout(stdout):
+            with self.assertRaisesRegex(CalendarGateError, "otpSendEnabled"):
+                wait_for_booking_preflight(
+                    page,
+                    script="safe-script",
+                    stage=BookingPreflightStage.AFTER_OTP_SEND,
+                    timeout=1,
+                )
+
+        output = stdout.getvalue()
+        self.assertIn("ITA_QCAL_PREFLIGHT_DIAGNOSTIC=", output)
+        self.assertIn('"stage": "after_otp_send"', output)
+        self.assertIn('"type": "int"', output)
+        self.assertNotIn("private-runtime-value", output)
+
+    def test_timeout_diagnostic_stays_in_the_debug_gate(self):
+        raw = booking_preflight_snapshot(turnstileReady=False)
+        raw["mustNotLeak"] = "private-runtime-value"
+        page = SimpleNamespace(run_js=lambda _script: raw)
+        stdout = StringIO()
+
+        with patch("plugins.ita_plugin.time.monotonic", side_effect=[0, 0, 2]), \
+             patch("plugins.ita_plugin.time.sleep"), redirect_stdout(stdout), \
+             self.assertRaisesRegex(CalendarGateError, "turnstile_token_pending"):
+            wait_for_booking_preflight(page, script="safe-script", timeout=1)
+
+        output = stdout.getvalue()
+        self.assertIn("ITA_QCAL_PREFLIGHT_DIAGNOSTIC=", output)
+        self.assertIn('"outcome": "timeout"', output)
+        self.assertNotIn("private-runtime-value", output)
+
+    def test_preflight_requires_exact_safe_shape_without_reading_tokens(self):
+        raw = booking_preflight_snapshot()
+        validate_booking_preflight(raw)
+
+        for key in ("formReady", "turnstileReady", "otpValuePresent",
+                    "otpSendEnabled", "avantiEnabled"):
+            with self.subTest(key=key):
+                changed = dict(raw)
+                changed[key] = not changed[key]
+                with self.assertRaisesRegex(CalendarGateError, key):
+                    validate_booking_preflight(changed)
+
+    def test_post_otp_accepts_cooldown_without_relaxing_structure(self):
+        cooldown = booking_preflight_snapshot(
+            otpSendEnabled=False,
+            otpValuePresent=True,
+        )
+
+        with self.assertRaisesRegex(CalendarGateError, "otpValuePresent"):
+            validate_booking_preflight(cooldown)
+        validate_booking_preflight(
+            cooldown,
+            after_otp=True,
+        )
+
+        for key, value in (
+            ("otpSendEnabled", True),
+            ("otpValuePresent", False),
+            ("formReady", False),
+        ):
+            with self.subTest(key=key):
+                changed = dict(cooldown)
+                changed[key] = value
+                with self.assertRaisesRegex(CalendarGateError, key):
+                    validate_booking_preflight(
+                        changed,
+                        after_otp=True,
+                    )
+
+    def test_dynamic_wait_rechecks_token_without_relaxing_structure(self):
+        base = booking_preflight_snapshot(
+            avantiEnabled=False,
+            turnstileReady=False,
+        )
+        ready = dict(base)
+        ready["avantiEnabled"] = True
+        ready["turnstileReady"] = True
+        outputs = [base, ready]
+        page = SimpleNamespace(run_js=lambda _script: outputs.pop(0))
+
+        with patch("tools.debug_ita_calendar_gate.time.sleep"):
+            result = wait_for_booking_preflight(
+                page,
+                script="safe-script",
+                timeout=1,
+            )
+
+        self.assertIs(result, ready)
+
+    def test_post_otp_wait_accepts_disabled_send_button(self):
+        base = booking_preflight_snapshot(
+            otpSendEnabled=False,
+            otpValuePresent=True,
+            avantiEnabled=False,
+            turnstileReady=False,
+        )
+        ready = dict(base)
+        ready["avantiEnabled"] = True
+        ready["turnstileReady"] = True
+        outputs = [base, ready]
+        page = SimpleNamespace(run_js=lambda _script: outputs.pop(0))
+
+        stdout = StringIO()
+        with redirect_stdout(stdout):
+            with patch("tools.debug_ita_calendar_gate.time.sleep"):
+                result = wait_for_booking_preflight(
+                    page,
+                    script="safe-script",
+                    stage=BookingPreflightStage.AFTER_OTP_SEND,
+                    timeout=1,
+                )
+
+        self.assertIs(result, ready)
+        self.assertIn('"outcome": "ready"', stdout.getvalue())
+        self.assertIn('"stage": "after_otp_send"', stdout.getvalue())
+        self.assertIn('"type": "bool"', stdout.getvalue())
+
+
+class OtpEntryTests(unittest.TestCase):
+    def test_manual_otp_is_visible_and_still_validated(self):
+        prompt = StringIO()
+        with patch("builtins.input", return_value="123456") as input_mock:
+            with redirect_stdout(prompt):
+                result = _read_manual_otp()
+
+        self.assertEqual(result, "123456")
+        input_mock.assert_called_once_with(
+            "Italy booking OTP "
+            "(visible; terminal scrollback may retain it): "
+        )
+        self.assertNotIn("123456", prompt.getvalue())
+
+        for invalid in ("", "123", "1234567890123", "12a456"):
+            with self.subTest(invalid=invalid):
+                with patch("builtins.input", return_value=invalid):
+                    with self.assertRaisesRegex(
+                        CalendarGateError,
+                        "OTP must be 4-12 digits",
+                    ):
+                        _read_manual_otp()
+
+    def test_otp_entry_focuses_before_typing_and_compares_in_page(self):
+        events = []
+
+        class FakeOtpElement:
+            def input(self, value, clear=False):
+                events.append(("input", value, clear))
+
+            def run_js(self, script, value):
+                events.append(("compare", script, value))
+                return True
+
+        otp_element = FakeOtpElement()
+        plugin = SimpleNamespace(
+            page=SimpleNamespace(
+                ele=lambda selector, timeout=0: (
+                    otp_element if selector == "#otp-input" else None
+                )
+            ),
+            mouse=SimpleNamespace(
+                human_click_ele=lambda element: events.append(
+                    ("click", element)
+                )
+            ),
+        )
+        stdout = StringIO()
+
+        with redirect_stdout(stdout):
+            _enter_otp(plugin, "123456")
+
+        self.assertEqual(events[0], ("click", otp_element))
+        self.assertEqual(events[1], ("input", "123456", True))
+        self.assertEqual(events[2][0], "compare")
+        self.assertIn("this.value === arguments[0]", events[2][1])
+        self.assertEqual(events[2][2], "123456")
+        self.assertIn(
+            "ITA_QCAL_OTP_DOM_WRITE_VERIFIED matched=true",
+            stdout.getvalue(),
+        )
+        self.assertNotIn("123456", stdout.getvalue())
+
+    def test_otp_entry_fails_before_avanti_when_readback_differs(self):
+        otp_element = SimpleNamespace(
+            input=lambda _value, clear=False: None,
+            run_js=lambda _script, _value: False,
+        )
+        plugin = SimpleNamespace(
+            page=SimpleNamespace(ele=lambda _selector, timeout=0: otp_element),
+            mouse=SimpleNamespace(human_click_ele=lambda _element: None),
+        )
+
+        with self.assertRaisesRegex(
+            CalendarGateError,
+            "OTP DOM write verification failed",
+        ):
+            _enter_otp(plugin, "123456")
+
+
+class ToolContractTests(unittest.TestCase):
+    def test_contract_is_logged_before_route_or_credentials_are_read(self):
+        tool_path = (
+            Path(__file__).resolve().parents[2]
+            / "tools"
+            / "debug_ita_calendar_gate.py"
+        )
+        shared_path = (
+            Path(__file__).resolve().parents[2]
+            / "plugins"
+            / "ita_plugin.py"
+        )
+        plugin_path = tool_path.parents[1] / "plugins" / "ita_plugin.py"
+        protocol_path = tool_path.parents[1] / "plugins" / "ita_plugin.py"
+        expected_fingerprint = hashlib.sha256(
+            tool_path.read_bytes()
+            + (tool_path.parents[1] / "plugins" / "ita_plugin.py").read_bytes()
+            + shared_path.read_bytes()
+            + plugin_path.read_bytes() + protocol_path.read_bytes()
+            + (tool_path.parents[1] / "plugins" / "ita_plugin.py").read_bytes()
+            + (tool_path.parents[1] / "tools" / "debug_ita_soak.py").read_bytes()
+            + (tool_path.parents[1] / "toolkit" / "backoff.py").read_bytes()
+        ).hexdigest()[:12]
+        self.assertEqual(
+            QCAL_TOOL_SOURCE_FINGERPRINT,
+            expected_fingerprint,
+        )
+
+        stdout = StringIO()
+        with patch(
+            "tools.debug_ita_calendar_gate.resolve_debug_route",
+            side_effect=CalendarGateError("offline-stop"),
+        ):
+            with redirect_stdout(stdout):
+                with self.assertRaisesRegex(
+                    CalendarGateError,
+                    "offline-stop",
+                ):
+                    run_calendar_gate({})
+
+        self.assertEqual(
+            stdout.getvalue().strip(),
+            "ITA_QCAL_TOOL_CONTRACT "
+            f"version={QCAL_TOOL_CONTRACT_VERSION} "
+            f"source_sha256={QCAL_TOOL_SOURCE_FINGERPRINT}",
+        )
+
+
+class ReservationSnapshotTests(unittest.TestCase):
+    def test_reads_both_initialized_datatables_and_always_closes_tab(self):
+        loading = {
+            "path": "/Reservation",
+            "authenticated": True,
+            "tableCount": 2,
+            "ready": False,
+            "reservations": None,
+            "waitlist": None,
+        }
+        ready = {
+            **loading,
+            "ready": True,
+            "reservations": 2,
+            "waitlist": 1,
+        }
+        tab = FakeReservationTab([loading, ready, ready])
+        opened_urls = []
+        page = SimpleNamespace(
+            new_tab=lambda url: opened_urls.append(url) or tab
+        )
+
+        with patch("tools.debug_ita_calendar_gate.time.sleep"):
+            result = read_reservation_snapshot(
+                page,
+                timeout=1,
+                settle_seconds=0,
+            )
+
+        self.assertEqual(result, ReservationSnapshot(2, 1))
+        self.assertEqual(opened_urls, ["https://prenotami.esteri.it/Reservation"])
+        self.assertEqual(tab.close_count, 1)
+
+    def test_invalid_counts_fail_and_close_tab(self):
+        tab = FakeReservationTab(
+            [
+                {
+                    "path": "/Reservation",
+                    "authenticated": True,
+                    "tableCount": 2,
+                    "ready": True,
+                    "reservations": True,
+                    "waitlist": 0,
+                }
+            ]
+        )
+        page = SimpleNamespace(new_tab=lambda _url: tab)
+
+        with self.assertRaises(CalendarGateError):
+            read_reservation_snapshot(
+                page,
+                timeout=1,
+                settle_seconds=0,
+            )
+        self.assertEqual(tab.close_count, 1)
+
+
+class SourceSafetyTests(unittest.TestCase):
+    def test_gate_source_never_clicks_or_submits_the_final_control(self):
+        path = (
+            Path(__file__).resolve().parents[2]
+            / "tools"
+            / "debug_ita_calendar_gate.py"
+        )
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+        violations = []
+        one_shot_calls = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            function = node.func
+            function_name = (
+                function.attr
+                if isinstance(function, ast.Attribute)
+                else function.id
+                if isinstance(function, ast.Name)
+                else ""
+            )
+            string_arguments = {
+                child.value
+                for child in ast.walk(node)
+                if isinstance(child, ast.Constant)
+                and isinstance(child.value, str)
+            }
+            if function_name in {"submit", "click"} and any(
+                "btnPrenotaNoOtp" in value
+                or "InsertNewBooking" in value
+                for value in string_arguments
+            ):
+                violations.append((function_name, node.lineno))
+            if function_name == "human_click_ele" and any(
+                "btnPrenotaNoOtp" in value
+                for value in string_arguments
+            ):
+                violations.append((function_name, node.lineno))
+            if function_name == "run" and isinstance(function, ast.Attribute):
+                if isinstance(function.value, ast.Name):
+                    one_shot_calls.append(function.value.id)
+
+        self.assertEqual(violations, [])
+        self.assertEqual(one_shot_calls.count("otp_guard"), 1)
+        self.assertEqual(one_shot_calls.count("avanti_guard"), 1)
+        self.assertIn("button.disabled = true", CALENDAR_GUARD_SCRIPT)
+        self.assertIn('OneShotAction("OTP")', source)
+        self.assertIn('OneShotAction("AVANTI")', source)
+        self.assertIn(
+            '#datetimepicker',
+            NEXT_MONTH_CONTROL_SCRIPT,
+        )
+        self.assertIn(
+            'th.dtpicker-next',
+            NEXT_MONTH_CONTROL_SCRIPT,
+        )
+        for forbidden_selector in (
+            "btnPrenotaNoOtp",
+            "InsertNewBooking",
+            ".fascia",
+            ".events a",
+            "a.next",
+            "data-action",
+            "fetch(",
+            "XMLHttpRequest",
+        ):
+            self.assertNotIn(
+                forbidden_selector,
+                NEXT_MONTH_CONTROL_SCRIPT,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 370 - 0
test/ita/test_debug_ita_monitor.py

@@ -0,0 +1,370 @@
+import ast
+import io
+import subprocess
+import sys
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from tools.debug_ita_monitor import (
+    DEFAULT_MAX_PROBES,
+    DEFAULT_MAX_WAIT_SECONDS,
+    MIN_SAFE_WAIT_SECONDS,
+    run_monitor,
+)
+from tools.debug_ita_session import DebugConfigurationError
+from vs_types import AvailabilityStatus, VSQueryResult
+
+
+class FakeMonitorPage:
+    def __init__(self):
+        self.url = "https://prenotami.esteri.it/Services"
+        self.form_structure = None
+
+    def ele(self, _selector, timeout=None):
+        del timeout
+        return None
+
+    def run_js(self, _script):
+        return self.form_structure
+
+
+class FakeMonitorPlugin:
+    sequence = ["none"]
+    last_instance = None
+
+    def __init__(self, group_id):
+        self.group_id = group_id
+        self.page = FakeMonitorPage()
+        self.create_session_calls = 0
+        self.query_calls = 0
+        self.cleanup_calls = 0
+        FakeMonitorPlugin.last_instance = self
+
+    def set_log(self, logger):
+        self.logger = logger
+
+    def set_config(self, config):
+        self.config = config
+
+    def create_session(self):
+        self.create_session_calls += 1
+
+    def query(self, apt_type):
+        behavior = self.sequence[min(self.query_calls, len(self.sequence) - 1)]
+        self.query_calls += 1
+        if behavior == "weak":
+            self.page.form_structure = {
+                "path": "/Services/Booking/1321",
+                "form": {
+                    "method": "POST",
+                    "action_path": "/Services/Booking/1321",
+                    "secret": "must-not-appear",
+                },
+                "fields": [
+                    {
+                        "tag": "input",
+                        "type": "hidden",
+                        "id": "RequestToken",
+                        "name": "__RequestVerificationToken",
+                        "required": False,
+                        "value": "private@example.test",
+                    }
+                ],
+                "buttons": [],
+            }
+            return VSQueryResult(
+                success=True,
+                apt_type=apt_type,
+                availability_status=AvailabilityStatus.NoneAvailable,
+            )
+        if behavior == "unexpected":
+            return VSQueryResult(
+                success=True,
+                apt_type=apt_type,
+                availability_status=AvailabilityStatus.Available,
+            )
+        if behavior == "error":
+            raise RuntimeError(
+                "private@example.test failed with token "
+                "abcdefghijklmnopqrstuvwxyz123456"
+            )
+        return VSQueryResult(
+            success=False,
+            apt_type=apt_type,
+            availability_status=AvailabilityStatus.NoneAvailable,
+        )
+
+    def cleanup(self):
+        self.cleanup_calls += 1
+
+
+class DebugItaMonitorTests(unittest.TestCase):
+    def setUp(self):
+        FakeMonitorPlugin.sequence = ["none"]
+        FakeMonitorPlugin.last_instance = None
+
+    @staticmethod
+    def _run(
+        *,
+        apply=True,
+        max_probes=3,
+        randint=lambda _minimum, _maximum: 60,
+        sleep=lambda _seconds: None,
+    ):
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        with (
+            patch(
+                "tools.debug_ita_monitor.resolve_chrome_path",
+                return_value=Path("/test/chrome"),
+            ),
+            patch(
+                "tools.debug_ita_monitor._get_query_credentials",
+                return_value=("offline@example.test", "offline-password"),
+            ) as credential_reader,
+            patch(
+                "tools.debug_ita_monitor._prepare_query_profile",
+                return_value=Path("/offline/ita-query-profile"),
+            ) as profile_preparer,
+            patch(
+                "tools.debug_ita_monitor._bind_query_profile",
+                return_value=Mock(),
+            ),
+            patch("tools.debug_ita_monitor.ItaPlugin", FakeMonitorPlugin),
+            patch.dict("tools.debug_ita_monitor.os.environ", {}, clear=False),
+            redirect_stdout(stdout),
+            redirect_stderr(stderr),
+        ):
+            exit_code = run_monitor(
+                {},
+                apply=apply,
+                non_interactive=True,
+                min_wait=MIN_SAFE_WAIT_SECONDS,
+                max_wait=DEFAULT_MAX_WAIT_SECONDS,
+                max_probes=max_probes,
+                randint=randint,
+                sleep=sleep,
+            )
+        return (
+            exit_code,
+            stdout.getvalue(),
+            stderr.getvalue(),
+            credential_reader,
+            profile_preparer,
+        )
+
+    def test_default_preflight_requires_no_credentials_or_plugin(self):
+        exit_code, stdout, stderr, credential_reader, profile_preparer = self._run(
+            apply=False
+        )
+
+        self.assertEqual(exit_code, 0)
+        credential_reader.assert_not_called()
+        profile_preparer.assert_not_called()
+        self.assertIsNone(FakeMonitorPlugin.last_instance)
+        self.assertIn("ITA_MONITOR_PREFLIGHT_OK", stdout)
+        self.assertIn("external_request=false", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_no_slot_monitor_reuses_one_session_and_stops_at_max_probes(self):
+        FakeMonitorPlugin.sequence = ["none", "none", "none"]
+        waits = []
+        random_values = iter([60, 300])
+
+        exit_code, stdout, stderr, _, _ = self._run(
+            max_probes=3,
+            randint=lambda _minimum, _maximum: next(random_values),
+            sleep=waits.append,
+        )
+        plugin = FakeMonitorPlugin.last_instance
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(plugin.create_session_calls, 1)
+        self.assertEqual(plugin.query_calls, 3)
+        self.assertEqual(plugin.cleanup_calls, 1)
+        self.assertEqual(waits, [60, 300])
+        self.assertIn("probe=3", stdout)
+        self.assertIn("ITA_MONITOR_MAX_PROBES_REACHED", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_weak_signal_stops_immediately_and_prints_sanitized_alert(self):
+        FakeMonitorPlugin.sequence = ["none", "weak", "none"]
+        waits = []
+
+        exit_code, stdout, stderr, _, _ = self._run(
+            max_probes=3,
+            sleep=waits.append,
+        )
+        plugin = FakeMonitorPlugin.last_instance
+
+        self.assertEqual(exit_code, 4)
+        self.assertEqual(plugin.create_session_calls, 1)
+        self.assertEqual(plugin.query_calls, 2)
+        self.assertEqual(plugin.cleanup_calls, 1)
+        self.assertEqual(waits, [60])
+        self.assertIn("\aITA_MONITOR_WEAK_SIGNAL", stdout)
+        self.assertIn("action=start-user-book-recheck-now", stdout)
+        self.assertIn("ITA_BOOKING_FORM_STRUCTURE=", stdout)
+        self.assertNotIn("private@example.test", stdout)
+        self.assertNotIn("must-not-appear", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_weak_signal_publishes_one_local_handoff_only_when_enabled(self):
+        FakeMonitorPlugin.sequence = ["weak"]
+        published = []
+
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        with (
+            patch(
+                "tools.debug_ita_monitor.resolve_chrome_path",
+                return_value=Path("/test/chrome"),
+            ),
+            patch(
+                "tools.debug_ita_monitor._get_query_credentials",
+                return_value=("offline@example.test", "offline-password"),
+            ),
+            patch(
+                "tools.debug_ita_monitor._prepare_query_profile",
+                return_value=Path("/offline/ita-query-profile"),
+            ),
+            patch(
+                "tools.debug_ita_monitor._bind_query_profile",
+                return_value=Mock(),
+            ),
+            patch("tools.debug_ita_monitor.ItaPlugin", FakeMonitorPlugin),
+            patch.dict("tools.debug_ita_monitor.os.environ", {}, clear=False),
+            redirect_stdout(stdout),
+            redirect_stderr(stderr),
+        ):
+            exit_code = run_monitor(
+                {},
+                apply=True,
+                non_interactive=True,
+                min_wait=MIN_SAFE_WAIT_SECONDS,
+                max_wait=DEFAULT_MAX_WAIT_SECONDS,
+                max_probes=3,
+                publish_local_signal=True,
+                signal_publisher=lambda: published.append("weak"),
+            )
+
+        self.assertEqual(exit_code, 4)
+        self.assertEqual(published, ["weak"])
+        self.assertIn("ITA_MONITOR_HANDOFF_PUBLISHED", stdout.getvalue())
+        self.assertEqual(stderr.getvalue(), "")
+
+    def test_unexpected_result_stops_without_another_probe(self):
+        FakeMonitorPlugin.sequence = ["unexpected", "none"]
+
+        exit_code, stdout, _stderr, _, _ = self._run(max_probes=3)
+        plugin = FakeMonitorPlugin.last_instance
+
+        self.assertEqual(exit_code, 4)
+        self.assertEqual(plugin.query_calls, 1)
+        self.assertEqual(plugin.cleanup_calls, 1)
+        self.assertIn("ITA_MONITOR_SAFE_STOP", stdout)
+
+    def test_query_error_stops_without_retry_and_redacts_diagnostics(self):
+        FakeMonitorPlugin.sequence = ["error", "none"]
+
+        exit_code, stdout, stderr, _, _ = self._run(max_probes=3)
+        plugin = FakeMonitorPlugin.last_instance
+
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(plugin.query_calls, 1)
+        self.assertEqual(plugin.cleanup_calls, 1)
+        self.assertIn("ITA_MONITOR_FAILED type=RuntimeError", stdout)
+        self.assertNotIn("private@example.test", stdout)
+        self.assertNotIn("abcdefghijklmnopqrstuvwxyz123456", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_ctrl_c_during_wait_cleans_up_without_traceback(self):
+        def interrupted_sleep(_seconds):
+            raise KeyboardInterrupt
+
+        exit_code, stdout, stderr, _, _ = self._run(
+            max_probes=3,
+            sleep=interrupted_sleep,
+        )
+        plugin = FakeMonitorPlugin.last_instance
+
+        self.assertEqual(exit_code, 130)
+        self.assertEqual(plugin.query_calls, 1)
+        self.assertEqual(plugin.cleanup_calls, 1)
+        self.assertIn("ITA_MONITOR_CANCELLED", stdout)
+        self.assertIn("ITA_MONITOR_CLEANUP_OK", stdout)
+        self.assertNotIn("Traceback", stdout + stderr)
+
+    def test_unsafe_limits_fail_before_credentials_or_plugin(self):
+        with (
+            patch(
+                "tools.debug_ita_monitor._get_query_credentials",
+                side_effect=AssertionError("credentials must not be read"),
+            ),
+            patch(
+                "tools.debug_ita_monitor.ItaPlugin",
+                side_effect=AssertionError("plugin must not be created"),
+            ),
+            self.assertRaises(DebugConfigurationError),
+        ):
+            run_monitor(
+                {},
+                apply=True,
+                non_interactive=True,
+                min_wait=59,
+                max_wait=300,
+                max_probes=1,
+            )
+
+    def test_cli_default_is_a_real_zero_network_preflight(self):
+        repo_root = Path(__file__).resolve().parents[2]
+        completed = subprocess.run(
+            [sys.executable, str(repo_root / "tools" / "debug_ita_monitor.py")],
+            cwd=repo_root,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+        self.assertEqual(completed.returncode, 0)
+        self.assertIn("ITA_MONITOR_PREFLIGHT_OK", completed.stdout)
+        self.assertIn("external_request=false", completed.stdout)
+        self.assertEqual(completed.stderr, "")
+
+    def test_source_has_one_query_call_and_no_book_or_redis_dependency(self):
+        source_path = (
+            Path(__file__).resolve().parents[2]
+            / "tools"
+            / "debug_ita_monitor.py"
+        )
+        source = source_path.read_text(encoding="utf-8")
+        tree = ast.parse(source)
+        query_calls = [
+            node
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "query"
+        ]
+        book_calls = [
+            node
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "book"
+        ]
+
+        self.assertEqual(len(query_calls), 1)
+        self.assertEqual(book_calls, [])
+        self.assertNotIn("redis", source.lower())
+
+    def test_defaults_match_the_existing_italy_sentinel_cadence(self):
+        self.assertEqual(MIN_SAFE_WAIT_SECONDS, 60)
+        self.assertEqual(DEFAULT_MAX_WAIT_SECONDS, 300)
+        self.assertEqual(DEFAULT_MAX_PROBES, 10)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 554 - 0
test/ita/test_debug_ita_production_query_gate.py

@@ -0,0 +1,554 @@
+import json
+import unittest
+from contextlib import ExitStack, redirect_stdout
+from datetime import date, datetime
+from io import StringIO
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+from plugins.ita_plugin import (
+    AVAILABILITY_PATH,
+    CALENDAR_GUARD_SCRIPT,
+    NEXT_MONTH_CONTROL_SCRIPT,
+    CalendarGateError,
+    CalendarProbeResult,
+)
+from plugins.ita_plugin import ItaPlugin
+from plugins.ita_plugin import CalendarDay
+from tools.debug_ita_calendar_gate import (
+    OTP_PATH,
+    CalendarGateMode,
+    CalendarRequestAudit,
+    ReservationSnapshot,
+    build_calendar_gate_config,
+    resolve_qcal_mode,
+    run_calendar_gate,
+    run_production_query_acceptance,
+    validate_production_query_result,
+)
+from tools.debug_ita_query import resolve_debug_route
+from vs_types import AvailabilityStatus, DateAvailability, TimeSlot, VSQueryResult
+
+
+def gate_env():
+    return {
+        "ITA_QCAL_MODE": "production_query",
+        "ITA_ROUTING_KEY": "slot.sample.it.tourist",
+        "ITA_SERVICE_ID": "9001",
+        "ITA_CITY": "Sample City",
+        "ITA_VISA_TYPE": "Tourist",
+        "ITA_CALENDAR_LOOKAHEAD_MONTHS": "3",
+        "ITA_BOOKING_TYPE_CONTROL_ID": "typeofbookingddl",
+        "ITA_BOOKING_TYPE_VALUE": "1",
+        "ITA_BOOKING_TYPE_LABELS": "Single booking",
+        "ITA_PURPOSE_CONTROL_ID": "ddls_0",
+        "ITA_PURPOSE_VALUE": "42",
+        "ITA_PURPOSE_LABELS": "Tourism",
+    }
+
+
+def make_scan(positive_days=(12, 20), *, start_month=8):
+    probes = []
+    for month in range(start_month, 11):
+        days = (
+            tuple(
+                CalendarDay(date(2026, month, day), 1, 0)
+                for day in positive_days
+            )
+            if month == 10 and positive_days
+            else (CalendarDay(date(2026, month, 1), 0, -1),)
+        )
+        probes.append(CalendarProbeResult(days, f"01/{month:02d}/2026"))
+    return tuple(probes)
+
+
+def make_result(scan, apt_type):
+    available = scan[-1].available_days
+    earliest = available[0].day if available else None
+    value = datetime.combine(earliest, datetime.min.time()) if earliest else None
+    return VSQueryResult(
+        success=earliest is not None,
+        apt_type=apt_type,
+        availability_status=(
+            AvailabilityStatus.Available if earliest else AvailabilityStatus.NoneAvailable
+        ),
+        earliest_date=value,
+        availability=[DateAvailability(date=value, times=[])] if earliest else [],
+    )
+
+
+class FakeDriver:
+    def __init__(self):
+        self.event_handlers = {}
+        self.immediate_event_handlers = {}
+        self.is_running = True
+
+    def set_callback(self, event, callback, immediate=False):
+        handlers = self.immediate_event_handlers if immediate else self.event_handlers
+        if callback is None:
+            handlers.pop(event, None)
+        else:
+            handlers[event] = callback
+
+
+class FakeAuditPage:
+    def __init__(self):
+        self.driver = FakeDriver()
+        self.commands = []
+        self.final_requests = 0
+        self.url = "https://prenotami.esteri.it/BookingCalendar"
+        self.tab_id = "audit-fixture-tab"
+        self.runtime_service = "runtime-service"
+
+    def run_js(self, script, *args):
+        if "coordinate:ita-book-runtime-service" in script:
+            return {"path": "/BookingCalendar", "count": 1, "value": self.runtime_service}
+        if script == CALENDAR_GUARD_SCRIPT:
+            return {"path": "/BookingCalendar", "calendarFunctionPresent": True, "finalButtonCount": 1,
+                    "allFinalButtonsGuarded": True, "finalRequestCount": self.final_requests, "timeSlotRequestCount": 0}
+        raise AssertionError("Unexpected audit-page script")
+
+    def run_cdp(self, method):
+        self.commands.append(method)
+        return {}
+
+    def emit(self, path, method="POST", **request_fields):
+        if "/InsertNewBooking" in path:
+            self.final_requests += 1
+        callback = self.driver.immediate_event_handlers.get(CalendarRequestAudit.EVENT)
+        if callback:
+            callback(request={
+                "url": "https://prenotami.esteri.it" + path,
+                "method": method,
+                **request_fields,
+            })
+
+
+class FakeProductionListener:
+    def __init__(self, page):
+        self.page = page
+        self.starts = []
+        self.stops = 0
+
+    def start(self, target, method=None):
+        self.starts.append((target, method))
+        self.page.packet = None
+
+    def wait(self, timeout=None):
+        return self.page.packet
+
+    def stop(self):
+        self.stops += 1
+
+
+class FakeProductionPage(FakeAuditPage):
+    def __init__(self, plans, *, extra_request=None):
+        super().__init__()
+        self.plans = plans
+        self.extra_request = extra_request
+        self.refresh_calls = 0
+        self.month_index = 0
+        self.forward_clicks = []
+        self.packet = None
+        self.listen = FakeProductionListener(self)
+        self.wait = SimpleNamespace(doc_loaded=lambda: None)
+        self.tab_id = "production-query-fixture-tab"
+        self.runtime_service = "runtime-service"
+
+    def ele(self, selector, timeout=None):
+        if selector != "#pingid-button":
+            raise AssertionError(f"Unexpected production lookup: {selector}")
+        return None
+
+    def refresh(self):
+        self.refresh_calls += 1
+        self.month_index = 0
+        self._publish_month()
+        if self.extra_request:
+            self.emit(self.extra_request)
+
+    def _publish_month(self):
+        year, month, positive_days = self.plans[self.refresh_calls - 1][self.month_index]
+        items = [
+            {
+                "DateLibere": f"{day:02d}/{month:02d}/{year} 00:00:00",
+                "SlotLiberi": 1,
+                "SlotRimanenti": 0,
+            }
+            for day in positive_days
+        ] or [{
+            "DateLibere": f"01/{month:02d}/{year} 00:00:00",
+            "SlotLiberi": 0,
+            "SlotRimanenti": -1,
+        }]
+        self.emit(AVAILABILITY_PATH)
+        self.packet = SimpleNamespace(
+            url="https://prenotami.esteri.it" + AVAILABILITY_PATH,
+            method="POST",
+            request=SimpleNamespace(postData={
+                "_Servizio": "runtime-service",
+                "selectedDay": f"01/{month:02d}/{year}",
+            }),
+            response=SimpleNamespace(status=200, raw_body=json.dumps(json.dumps(items))),
+        )
+
+    def run_js(self, script, *args):
+        if script == NEXT_MONTH_CONTROL_SCRIPT:
+            clicked = args == (True,)
+            if clicked:
+                self.month_index += 1
+                plan = self.plans[self.refresh_calls - 1]
+                self.forward_clicks.append(plan[self.month_index][:2])
+                self._publish_month()
+            return {
+                "pathMatches": True,
+                "candidateCount": 1,
+                "actionableCount": 1,
+                "clicked": clicked,
+            }
+        return super().run_js(script, *args)
+
+
+def make_plugin(page):
+    env = gate_env()
+    route = resolve_debug_route(env)
+    config = build_calendar_gate_config(
+        env, username="offline@example.test", password="not-a-real-password", route=route
+    )
+    plugin = ItaPlugin.__new__(ItaPlugin)
+    plugin.page = page
+    plugin.config = config
+    plugin.free_config = config.free_config
+    plugin.group_id = "offline-production-query"
+    plugin.logger = Mock()
+    plugin.is_healthy = True
+    plugin.session_create_time = 1.0
+    plugin._record_calendar_prepared_route(plugin._resolve_route(route.appointment_type()), role="query")
+    # __new__ deliberately skips real browser/filesystem setup in these tests.
+    plugin.cleanup = Mock()
+    return plugin, route
+
+
+class ProductionGateModeTests(unittest.TestCase):
+    def test_mode_is_explicit_and_discovery_remains_the_default(self):
+        self.assertIs(resolve_qcal_mode({}), CalendarGateMode.DISCOVERY_HORIZON)
+        self.assertIs(resolve_qcal_mode(gate_env()), CalendarGateMode.PRODUCTION_QUERY)
+        with self.assertRaisesRegex(CalendarGateError, "ITA_QCAL_MODE"):
+            resolve_qcal_mode({"ITA_QCAL_MODE": "typo"})
+
+    def test_invalid_mode_is_rejected_before_credentials(self):
+        with patch("tools.debug_ita_calendar_gate._get_query_credentials") as credentials:
+            with redirect_stdout(StringIO()):
+                with self.assertRaisesRegex(CalendarGateError, "ITA_QCAL_MODE"):
+                    run_calendar_gate({"ITA_QCAL_MODE": "typo"})
+        credentials.assert_not_called()
+
+
+class PassiveRequestAuditTests(unittest.TestCase):
+    def test_counts_metadata_across_redirects_without_retaining_sensitive_data(self):
+        page = FakeAuditPage()
+        audit = CalendarRequestAudit(page)
+        audit.start()
+        page.emit(OTP_PATH + "?ServiceID=9001", "GET", postData="secret-otp-body")
+        page.emit("/Services/Booking/9001", "POST", headers={"Cookie": "secret-cookie"})
+        page.emit("/BookingCalendar", "GET")
+        page.emit(AVAILABILITY_PATH)
+        page.emit("/BookingCalendar/RetrieveTimeSlots")
+        page.emit("/BookingCalendar/InsertNewBooking")
+        audit._on_request(request={"url": "https://other.test/BookingCalendar/GenerateOTP", "method": "GET"})
+        self.assertEqual(audit.snapshot(), {
+            "otpRequests": 1, "avantiPosts": 1, "availabilityRequests": 1, "finalRequests": 1
+        })
+        self.assertNotIn("secret", repr(audit.__dict__))
+        self.assertEqual(page.commands, ["Network.enable"])
+        audit.stop()
+        self.assertEqual(page.driver.immediate_event_handlers, {})
+        self.assertEqual(page.driver.event_handlers, {})
+
+    def test_refuses_to_replace_an_existing_callback(self):
+        for name in ("event_handlers", "immediate_event_handlers"):
+            with self.subTest(name=name):
+                page = FakeAuditPage()
+                callback = Mock()
+                getattr(page.driver, name)[CalendarRequestAudit.EVENT] = callback
+                with self.assertRaisesRegex(CalendarGateError, "existing callback"):
+                    CalendarRequestAudit(page).start()
+                self.assertIs(getattr(page.driver, name)[CalendarRequestAudit.EVENT], callback)
+                self.assertEqual(page.commands, [])
+
+    def test_invalid_events_and_disconnection_fail_closed(self):
+        page = FakeAuditPage()
+        audit = CalendarRequestAudit(page)
+        audit.start()
+        audit._on_request(request=None)
+        with self.assertRaisesRegex(CalendarGateError, "invalid event"):
+            audit.snapshot()
+        audit.stop()
+        with self.assertRaisesRegex(CalendarGateError, "not connected"):
+            audit.snapshot()
+
+    def test_detaches_callback_when_network_enable_fails(self):
+        page = FakeAuditPage()
+        page.run_cdp = Mock(side_effect=RuntimeError("offline failure"))
+        with self.assertRaisesRegex(RuntimeError, "offline failure"):
+            CalendarRequestAudit(page).start()
+        self.assertEqual(page.driver.immediate_event_handlers, {})
+
+    def test_settled_snapshot_is_bounded_and_passive(self):
+        page = FakeAuditPage()
+        audit = CalendarRequestAudit(page)
+        audit.start()
+        try:
+            self.assertEqual(audit.settled_snapshot(timeout=1), audit.snapshot())
+        finally:
+            audit.stop()
+        self.assertEqual(page.commands, ["Network.enable", "Page.getFrameTree"])
+
+
+class ProductionResultContractTests(unittest.TestCase):
+    def test_positive_result_and_snapshot_match_the_real_scan(self):
+        scan = make_scan()
+        apt_type = resolve_debug_route(gate_env()).appointment_type()
+        report = validate_production_query_result(
+            make_result(scan, apt_type), scan, apt_type=apt_type, lookahead_months=3
+        )
+        self.assertEqual(report["earliestDate"], "2026-10-12")
+        self.assertEqual(report["stopReason"], "first_available_month")
+        self.assertEqual(report["timesCount"], 0)
+        self.assertTrue(report["snapshotVerified"])
+        self.assertNotIn("runtime", json.dumps(report))
+
+    def test_rejects_wrong_earliest_extra_dates_or_times(self):
+        scan = make_scan()
+        apt_type = resolve_debug_route(gate_env()).appointment_type()
+        for field, value in (
+            ("earliest_date", datetime(2026, 10, 20)),
+            ("success", False),
+            ("availability", []),
+            ("availability", [DateAvailability(date=datetime(2026, 10, 12), times=[TimeSlot(time="10:05")])]),
+            ("availability", [DateAvailability(date=datetime(2026, 10, 20))]),
+        ):
+            with self.subTest(field=field, value=value):
+                result = make_result(scan, apt_type)
+                setattr(result, field, value)
+                with self.assertRaises(CalendarGateError):
+                    validate_production_query_result(
+                        result, scan, apt_type=apt_type, lookahead_months=3
+                    )
+
+    def test_rejects_extra_snapshot_fields(self):
+        scan = make_scan()
+        apt_type = resolve_debug_route(gate_env()).appointment_type()
+        result = make_result(scan, apt_type)
+        payload = result.to_snapshot_payload()
+        payload["daily_id"] = "must-not-leak"
+        with patch.object(VSQueryResult, "to_snapshot_payload", return_value=payload):
+            with self.assertRaisesRegex(CalendarGateError, "snapshot contract"):
+                validate_production_query_result(
+                    result, scan, apt_type=apt_type, lookahead_months=3
+                )
+
+    def test_accepts_explicit_complete_negative_evidence(self):
+        scan = make_scan(())
+        apt_type = resolve_debug_route(gate_env()).appointment_type()
+        report = validate_production_query_result(
+            make_result(scan, apt_type), scan, apt_type=apt_type, lookahead_months=3
+        )
+        self.assertFalse(report["success"])
+        self.assertEqual(report["stopReason"], "horizon_exhausted")
+        self.assertIsNone(report["earliestDate"])
+
+
+class RealProductionEntryOfflineTests(unittest.TestCase):
+    def _run(self, page):
+        plugin, route = make_plugin(page)
+        audit = CalendarRequestAudit(page)
+        audit.start()
+        page.emit(OTP_PATH + "?ServiceID=9001", "GET")
+        page.emit("/Services/Booking/9001")
+        try:
+            with patch("tools.debug_ita_calendar_gate.time.sleep"), patch.object(
+                CalendarRequestAudit, "settled_snapshot", autospec=True,
+                side_effect=lambda value: value.snapshot(),
+            ), redirect_stdout(StringIO()):
+                reports = run_production_query_acceptance(plugin, route, audit)
+            return plugin, reports, audit.snapshot()
+        finally:
+            audit.stop()
+            self.assertEqual(plugin.free_config["query_mode"], "services_probe")
+
+    def test_real_query_and_real_scanner_stop_at_first_positive_month_twice(self):
+        plan = [(2026, 8, ()), (2026, 9, ()), (2026, 10, (20, 12))]
+        page = FakeProductionPage([plan, plan])
+        plugin, reports, counts = self._run(page)
+        self.assertEqual(page.refresh_calls, 2)
+        self.assertEqual(page.forward_clicks, [(2026, 9), (2026, 10)] * 2)
+        self.assertEqual(page.listen.stops, 6)
+        self.assertEqual([report["earliestDate"] for report in reports], ["2026-10-12"] * 2)
+        self.assertTrue(all(report["queryRequestDelta"]["otpRequests"] == 0 for report in reports))
+        self.assertEqual(counts, {
+            "otpRequests": 1, "avantiPosts": 1, "availabilityRequests": 6, "finalRequests": 0
+        })
+        self.assertIs(plugin.page, page)
+
+    def test_allows_inventory_to_change_without_requiring_equal_dates(self):
+        first = [(2026, 8, ()), (2026, 9, ()), (2026, 10, (12,))]
+        second = [(2026, 8, ()), (2026, 9, ()), (2026, 10, (13,))]
+        _, reports, _ = self._run(FakeProductionPage([first, second]))
+        self.assertEqual([report["earliestDate"] for report in reports], ["2026-10-12", "2026-10-13"])
+
+    def test_second_query_must_restart_from_the_same_initial_month(self):
+        first = [(2026, 8, ()), (2026, 9, ()), (2026, 10, (12,))]
+        second = [(2026, 9, (1,))]
+        with self.assertRaisesRegex(CalendarGateError, "same initial month"):
+            self._run(FakeProductionPage([first, second]))
+
+    def test_rejects_repeated_otp_or_extra_availability_requests(self):
+        plan = [(2026, 8, (1,))]
+        for extra in (OTP_PATH, AVAILABILITY_PATH):
+            with self.subTest(extra=extra):
+                with self.assertRaisesRegex(CalendarGateError, "read-only request contract"):
+                    self._run(FakeProductionPage([plan], extra_request=extra))
+
+    def test_two_negative_queries_remain_negative_not_fake_positive(self):
+        plan = [(2026, 8, ()), (2026, 9, ()), (2026, 10, ())]
+        _, reports, _ = self._run(FakeProductionPage([plan, plan]))
+        self.assertEqual(len(reports), 2)
+        self.assertFalse(any(report["success"] for report in reports))
+
+
+class ProductionGateWorkflowTests(unittest.TestCase):
+    def _run_gate(self, positives=(True, True), *, reservation_changed=False, query_error=None):
+        env = {**gate_env(), "ITA_QCAL_FORWARD_MONTHS": "ignored-in-production-mode"}
+        page = FakeAuditPage()
+        page.set = SimpleNamespace(auto_handle_alert=Mock())
+        plugin, route = make_plugin(page)
+        plugin.create_session = Mock()
+        plugin.mouse = SimpleNamespace(human_click_ele=Mock())
+        plugin._enter_service = Mock(return_value=VSQueryResult(success=True))
+        plugin.query = Mock(side_effect=AssertionError("Preparation must not call public Query"))
+
+        def set_config(config):
+            plugin.config = config
+            plugin.free_config = config.free_config
+
+        plugin.set_config = Mock(side_effect=set_config)
+
+        def listen(_page, *, target, method, action, timeout):
+            action()
+            page.emit(target, method)
+            if target == OTP_PATH:
+                return SimpleNamespace(
+                    url="https://prenotami.esteri.it" + OTP_PATH + "?ServiceID=9001",
+                    method="GET",
+                    response=SimpleNamespace(status=200, raw_body=json.dumps("SENT")),
+                )
+            return SimpleNamespace(
+                url="https://prenotami.esteri.it" + route.booking_path,
+                method="POST",
+                response=SimpleNamespace(
+                    status=302, headers={"Location": "/BookingCalendar"}
+                ),
+            )
+
+        def acceptance(_plugin, _route, _audit):
+            if query_error:
+                raise query_error
+            reports = []
+            for positive in positives:
+                page.emit(AVAILABILITY_PATH)
+                reports.append({
+                    "success": positive,
+                    "queryRequestDelta": {"availabilityRequests": 1},
+                })
+            return tuple(reports)
+
+        stdout = StringIO()
+        with ExitStack() as stack:
+            stack.enter_context(patch.dict("os.environ"))
+            patches = {
+                "resolve_chrome_path": {"return_value": Path("/offline/chrome")},
+                "_get_query_credentials": {"return_value": ("offline@example.test", "not-a-real-password")},
+                "_prepare_query_profile": {"return_value": None},
+                "ItaPlugin": {"return_value": plugin},
+                "read_reservation_snapshot": {"side_effect": [
+                    ReservationSnapshot(0, 0),
+                    ReservationSnapshot(1 if reservation_changed else 0, 0),
+                ]},
+                "wait_for_booking_preflight": {"return_value": {}},
+                "_element_or_fail": {"side_effect": lambda _page, selector: selector},
+                "_enter_otp": {},
+                "_wait_for_calendar": {},
+                "_calendar_guard": {"return_value": {"finalRequestCount": 0}},
+                "listen_once": {"side_effect": listen},
+                "run_production_query_acceptance": {"side_effect": acceptance},
+                "scan_calendar_horizon": {},
+            }
+            mocks = {
+                name: stack.enter_context(patch("tools.debug_ita_calendar_gate." + name, **kwargs))
+                for name, kwargs in patches.items()
+            }
+            stack.enter_context(patch.object(
+                CalendarRequestAudit, "settled_snapshot", autospec=True,
+                side_effect=lambda value: value.snapshot(),
+            ))
+            stack.enter_context(redirect_stdout(stdout))
+            otp_reader = Mock(return_value="123456")
+            exit_code = run_calendar_gate(env, otp_reader=otp_reader)
+        return exit_code, stdout.getvalue(), plugin, page, mocks, otp_reader
+
+    def test_prepares_once_runs_production_mode_and_always_cleans_up(self):
+        code, output, plugin, page, mocks, otp_reader = self._run_gate()
+        self.assertEqual(code, 0)
+        plugin.create_session.assert_called_once()
+        plugin.set_config.assert_called_once()
+        plugin.cleanup.assert_called_once()
+        plugin._enter_service.assert_called_once()
+        plugin.query.assert_not_called()
+        otp_reader.assert_called_once()
+        mocks["_enter_otp"].assert_called_once()
+        mocks["run_production_query_acceptance"].assert_called_once()
+        mocks["scan_calendar_horizon"].assert_not_called()
+        self.assertEqual(plugin.mouse.human_click_ele.call_count, 2)
+        self.assertEqual(page.driver.immediate_event_handlers, {})
+        self.assertIn("ITA_QCAL_PRODUCTION_QUERY_GATE_RESULT=", output)
+        self.assertIn('"passed": true', output)
+        self.assertNotIn("123456", output)
+        self.assertNotIn("not-a-real-password", output)
+
+    def test_natural_negative_evidence_returns_two_not_a_fake_pass(self):
+        code, output, plugin, _, _, _ = self._run_gate((False, False))
+        self.assertEqual(code, 2)
+        self.assertIn('"passed": false', output)
+        self.assertIn("ITA_QCAL_PRODUCTION_QUERY_NOT_READY", output)
+        plugin.cleanup.assert_called_once()
+
+    def test_gate_requires_exactly_two_query_reports(self):
+        code, output, plugin, _, _, _ = self._run_gate((True, True, True))
+        self.assertEqual(code, 1)
+        self.assertIn('"passed": false', output)
+        self.assertIn("exactly two Query calls", output)
+        plugin.cleanup.assert_called_once()
+
+    def test_reservation_change_fails_the_gate(self):
+        code, output, plugin, _, _, _ = self._run_gate(reservation_changed=True)
+        self.assertEqual(code, 1)
+        self.assertIn('"passed": false', output)
+        plugin.cleanup.assert_called_once()
+
+    def test_query_failure_does_not_repeat_preparation(self):
+        code, output, plugin, page, mocks, otp_reader = self._run_gate(
+            query_error=CalendarGateError("offline query failure")
+        )
+        self.assertEqual(code, 1)
+        otp_reader.assert_called_once()
+        mocks["_enter_otp"].assert_called_once()
+        self.assertEqual(plugin.mouse.human_click_ele.call_count, 2)
+        plugin.cleanup.assert_called_once()
+        self.assertEqual(page.driver.immediate_event_handlers, {})
+        self.assertIn("offline query failure", output)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 861 - 0
test/ita/test_debug_ita_query_book.py

@@ -0,0 +1,861 @@
+"""Real framework creation/publication/dispatch/execution, synthetic I/O only.
+
+No test-owned signal schema, expiry rule, account dispatcher or retry policy.
+The already-existing Redis fixture simulates a retained server key. Snapshot
+encoding/decoding, account binding, route/date/cooldown decisions and public
+Italy Query/Book remain the real implementations.
+"""
+import contextlib
+import copy
+from datetime import date
+import io
+import itertools
+import json
+import tempfile
+from pathlib import Path
+from types import SimpleNamespace
+import unittest
+from unittest.mock import Mock, patch
+
+from tools import debug_ita_query_book as cli
+from test.ita.test_ita_plugin import OrderBookerGCO, FakeRetainedSignalRedis
+from sentinel import SentinelGCO
+from test.ita import test_ita_calendar_book_flow as book_flow
+from test.ita.test_ita_query_recovery import RecoveryPage, prepared_plugin
+from vs_types import AvailabilityStatus, GroupConfig, QueryWaitMode
+
+
+class ExistingFrameworkJointTests(unittest.TestCase):
+    def setUp(self):
+        # Fail closed if a future test accidentally stops isolating I/O.
+        for target in ("socket.socket.connect", "socket.socket.connect_ex", "socket.create_connection",
+                       "requests.sessions.Session.request", "subprocess.Popen"):
+            self.enterContext(patch(target, side_effect=AssertionError("Offline test attempted external I/O")))
+        self.clock = {"now": 1000.0}
+        self.retained = None
+        self.query_page = RecoveryPage()
+        self.query_page.plans = [[(2026, 8, []), (2026, 9, []), (2026, 10, [13, 20])]] * 10
+        self.query, self.route = prepared_plugin(self.query_page)
+        self.apt = self.route.appointment_type()
+        self.apt.weight = 1
+        self.query._transient_user_data_path = "/nonexistent/ita-framework-query"
+        self.query.free_config.update(otp_mode="manual", final_submit_enabled=False)
+        self.query.query = Mock(wraps=self.query.query)
+        # Existing fixture is already on Calendar; restore its prepared marker
+        # after the framework's real set_config clears per-session state.
+        self.query.create_session = Mock(side_effect=lambda:
+            self.query._record_calendar_prepared_route(self.query._resolve_route(self.apt), role="query"))
+        self.query.cleanup = Mock()
+
+        self.inputs = {"username": "applicant@example.test", "password": "synthetic-applicant-password",
+                       "expected_start_date": "2026-08-01", "expected_end_date": "2026-10-31"}
+        self.order = {"id": 991, "order_id": "SYNTHETIC-ORDER", "status": "processing",
+                      "user_inputs": copy.deepcopy(self.inputs)}
+        self.cloud = Mock()
+        self.cloud.get_next_account.return_value = {
+            "id": 21, "username": "pool-query@example.test", "password": "synthetic-pool-password"}
+        self.cloud.get_vas_task_pop.return_value = self.order
+        self.redis = Mock()
+        self.redis.setex.side_effect = self.capture_redis_write
+        self.redis.get.side_effect = lambda key: (
+            self.retained.get(key) if self.retained is not None and key == self.signal_key else None)
+        self.redis.delete.side_effect = self.delete_redis_key
+        self.signal_key = "vs:signal:" + self.apt.routing_key
+        self.executor = Mock()
+        self.log = Mock()
+
+        # Existing test pattern: isolate only method dependencies, not methods.
+        # Use each loaded class's globals to avoid import-cache/stub ambiguity.
+        dependencies = {
+            "SafeRedisClient": Mock(return_value=self.redis),
+            "VSCloudApi": SimpleNamespace(Instance=lambda: self.cloud, lock_account=Mock()),
+            "time": SimpleNamespace(time=lambda: self.clock["now"], sleep=lambda _seconds: None),
+        }
+        for cls in (SentinelGCO, OrderBookerGCO):
+            self.enterContext(patch.dict(cls.__init__.__globals__, dependencies))
+        self.enterContext(patch.dict(OrderBookerGCO._execute_book_job.__globals__,
+                                    ThreadPool=SimpleNamespace(getInstance=lambda: self.executor)))
+        self.final = self.enterContext(patch("plugins.ita_plugin.submit_final",
+                                            side_effect=AssertionError("Final submission forbidden")))
+        # Query month navigation uses only the synthetic page above.
+        self.enterContext(patch("plugins.ita_plugin.time.sleep"))
+
+        self.query_config = GroupConfig(
+            identifier="offline-query", need_account=True, appointment_types=[self.apt],
+            plugin_config={"plugin_name": "ita_plugin"}, free_config=copy.deepcopy(self.query.free_config),
+            sentinel={"account_pool_id": "fixture.query.pool", "account_cd": 10800,
+                      "signal_ttl": 30, "query_wait": {"mode": QueryWaitMode.Fixed, "fixed_wait": 1}})
+        self.book_plugin, self.book_page = self.new_book_plugin()
+        self.book_config = GroupConfig(
+            identifier="offline-book", need_account=True, appointment_types=[self.apt],
+            plugin_config={"plugin_name": "ita_plugin"}, free_config=copy.deepcopy(self.book_plugin.free_config),
+            booker={"account_source": "order", "target_instances": 1, "booking_cooldown": 45})
+        self.sentinel = SentinelGCO(self.query_config, {}, self.log)
+        self.booker = OrderBookerGCO(self.book_config, {}, self.log)
+        self.sentinel.m_factory.create = Mock(return_value=self.query)
+        self.booker.m_factory.create = Mock(return_value=self.book_plugin)
+        self.booker._execute_book_job = Mock(wraps=self.booker._execute_book_job)
+        # Real GCO stop/cleanup is exercised; browser cleanup remains a fixture.
+        self.addCleanup(self.sentinel.stop)
+        self.addCleanup(self.booker.stop)
+
+    def new_book_plugin(self):
+        page = book_flow.FlowPage([book_flow.month("2026-10", {13: 0, 14: 1})])
+        plugin, _, _ = book_flow.prepared_plugin(page, routing_key=self.apt.routing_key)
+        plugin.free_config.update(otp_mode="cloud", final_submit_enabled=False)
+        plugin.is_healthy = True
+        plugin.cleanup = Mock()
+        # Login/OTP are already independently tested; this fixture starts at
+        # the prepared Calendar but binds it AFTER real order account wiring.
+        plugin.create_session = Mock(side_effect=lambda:
+            plugin._record_calendar_prepared_route(plugin._resolve_route(self.apt), role="book"))
+        original_book = plugin.book
+        plugin.observed_approval = None
+        def observed_book(trigger, inputs):
+            result, plugin.observed_approval = book_flow.book_with_approval(
+                plugin, trigger, inputs, call=original_book,
+            )
+            return result
+        plugin.book = Mock(side_effect=observed_book)
+        return plugin, page
+
+    def capture_redis_write(self, key, ttl, payload):
+        self.assertEqual(key, self.signal_key)
+        # Reuse existing retained-key fixture, not a new signal/TTL algorithm.
+        self.retained = FakeRetainedSignalRedis(json.loads(payload), self.clock,
+                                               ttl=self.clock["now"] + ttl)
+        return True
+
+    def delete_redis_key(self, key):
+        if key == self.signal_key:
+            self.retained = None
+        return 1
+
+    def spawn(self):
+        self.sentinel._spawn_sentinel_worker()
+        self.booker._spawn_worker(self.apt.routing_key)
+
+    def publish_once(self, *, positive=True):
+        # Bound the EXISTING loop to one cycle; do not reimplement its body.
+        with patch.object(self.sentinel.m_stop_event, "is_set", side_effect=[False, True]):
+            self.sentinel._monitor_loop()
+        if positive:
+            self.assertIsNotNone(self.retained, self.log.call_args_list)
+
+    def trigger_once(self, page=None):
+        with book_flow.browser_navigation(page or self.book_page), \
+                patch.object(self.booker.m_stop_event, "is_set", side_effect=[False, True]):
+            # Existing Thread creation and joins run as-is inside this loop.
+            self.booker._booking_trigger_loop()
+
+    def assert_no_final_or_success_report(self):
+        self.final.assert_not_called()
+        self.executor.enqueue.assert_not_called()
+        self.cloud.update_vas_task.assert_not_called()
+        self.cloud.push_weixin_text.assert_not_called()
+
+    def test_real_framework_pool_query_json_order_book_rechecks_current_inventory(self):
+        self.spawn()
+        self.assertEqual(len(self.sentinel.m_tasks), 1)
+        self.assertEqual(len(self.booker.m_tasks), 1)
+        self.cloud.get_next_account.assert_called_once_with("fixture.query.pool", 10800)
+        self.cloud.get_vas_task_pop.assert_called_once_with("auto." + self.apt.routing_key)
+        self.assertEqual(self.query.config.account.username, "pool-query@example.test")
+        self.assertEqual(self.query.config.account.id, 21)
+        self.assertEqual(self.book_plugin.config.account.username, self.inputs["username"])
+        self.assertEqual(self.book_plugin.config.account.password, self.inputs["password"])
+        self.assertFalse(self.sentinel.m_tasks[0].book_allowed)
+        self.assertEqual(self.booker.m_tasks[0].task_ref, 991)
+        self.assertEqual(self.booker.m_tasks[0].acceptable_routing_keys, [self.apt.routing_key])
+        self.assertIsNot(self.query.page, self.book_plugin.page)
+
+        self.publish_once()
+        self.query.query.assert_called_once_with(self.apt)
+        self.redis.setex.assert_called_once()
+        key, ttl, raw = self.redis.setex.call_args.args
+        self.assertEqual((key, ttl), (self.signal_key, 30))
+        payload = json.loads(raw)
+        self.assertEqual(set(payload), {"group_id", "apt_type", "query_result", "timestamp"})
+        self.assertEqual(payload["group_id"], self.query_config.identifier)
+        self.assertEqual(payload["apt_type"], self.apt.model_dump())
+        self.assertEqual(payload["query_result"]["earliest_date"], "2026-10-13")
+        self.assertEqual(payload["query_result"]["availability_status"], "Available")
+        self.assertNotIn("success", payload["query_result"])
+        self.assertNotIn("password", raw)
+        self.assertNotIn("pool-query", raw)
+        self.assertEqual(self.query_page.forward_clicks, [(2026, 9), (2026, 10)])
+
+        self.trigger_once()
+        self.booker._execute_book_job.assert_called_once()
+        self.book_plugin.book.assert_called_once()
+        trigger, inputs = self.book_plugin.book.call_args.args
+        self.assertEqual(trigger.apt_type, self.apt)
+        self.assertIs(trigger.availability_status, AvailabilityStatus.Available)
+        self.assertFalse(trigger.success)  # Actual framework decode default.
+        self.assertEqual(trigger.earliest_date.date(), date(2026, 10, 13))
+        self.assertEqual(inputs, self.inputs)
+        self.assertEqual(self.book_plugin.observed_approval.candidate.day, date(2026, 10, 14))
+        self.assertEqual(self.book_page.refreshes, 1)  # Applicant inventory is scanned once.
+        self.assertGreater(len(self.book_page.requests), 0)
+        self.assert_no_final_or_success_report()
+        self.sentinel.stop()
+        self.booker.stop()
+        self.query.cleanup.assert_called_once()
+        self.book_plugin.cleanup.assert_called_once()
+
+    def test_no_account_or_login_failure_does_not_create_query_task(self):
+        self.cloud.get_next_account.side_effect = RuntimeError("synthetic pool failure")
+        self.sentinel._spawn_sentinel_worker()
+        self.assertEqual(self.sentinel.m_tasks, [])
+        self.sentinel.m_factory.create.assert_not_called()
+        self.cloud.get_next_account.reset_mock(side_effect=True)
+        self.query.create_session.side_effect = RuntimeError("synthetic login failure")
+        self.sentinel._spawn_sentinel_worker()
+        self.assertEqual(self.sentinel.m_tasks, [])
+        self.query.cleanup.assert_called_once()
+        self.assertGreater(self.sentinel.m_spawn_cooldown_until, self.clock["now"])
+
+    def test_no_order_does_not_take_pool_account_for_book(self):
+        self.cloud.get_vas_task_pop.return_value = None
+        self.booker._spawn_worker(self.apt.routing_key)
+        self.assertEqual(self.booker.m_tasks, [])
+        self.booker.m_factory.create.assert_not_called()
+        self.cloud.get_next_account.assert_not_called()
+
+    def test_order_login_failure_uses_existing_cleanup_without_query_account_fallback(self):
+        self.book_plugin.create_session.side_effect = RuntimeError("synthetic login failure")
+        self.booker._spawn_worker(self.apt.routing_key)
+        self.assertEqual(self.booker.m_tasks, [])
+        self.assertEqual(self.booker.m_task_data_cache, {})
+        self.book_plugin.cleanup.assert_called_once()
+        self.cloud.get_next_account.assert_not_called()
+
+    def test_no_availability_does_not_publish_or_trigger_book(self):
+        self.query_page.outcomes = ["none"]
+        self.spawn()
+        self.publish_once(positive=False)
+        self.trigger_once()
+        self.redis.setex.assert_not_called()
+        self.book_plugin.book.assert_not_called()
+        self.cloud.slot_refresh_success.assert_called_once()
+        self.assert_no_final_or_success_report()
+
+    def test_bad_query_protocol_does_not_publish_a_positive_signal(self):
+        self.query_page.outcomes = ["malformed"]
+        self.spawn()
+        self.publish_once(positive=False)
+        self.trigger_once()
+        self.redis.setex.assert_not_called()
+        self.cloud.slot_refresh_fail.assert_called_once()
+        self.book_plugin.book.assert_not_called()
+
+    def test_server_expired_signal_does_not_trigger_book(self):
+        self.spawn()
+        self.publish_once()
+        self.clock["now"] += self.query_config.sentinel.signal_ttl + 1
+        self.trigger_once()
+        self.book_plugin.book.assert_not_called()
+
+    def test_same_signal_obeys_existing_task_cooldown_not_new_one_shot_rule(self):
+        self.query_config.sentinel.signal_ttl = 180
+        self.spawn()
+        self.publish_once()
+        self.trigger_once()
+        self.clock["now"] += 1
+        self.trigger_once()
+        self.book_plugin.book.assert_called_once()
+        self.clock["now"] += self.book_config.booker.booking_cooldown
+        self.trigger_once()
+        self.assertEqual(self.book_plugin.book.call_count, 2)
+        self.assert_no_final_or_success_report()
+
+    def test_unmatched_routing_key_is_filtered_by_real_trigger_loop(self):
+        self.spawn()
+        self.publish_once()
+        self.booker.m_tasks[0].acceptable_routing_keys = ["slot.other.it.tourist"]
+        self.trigger_once()
+        self.book_plugin.book.assert_not_called()
+
+    def test_date_outside_order_end_is_filtered_before_book(self):
+        self.order["user_inputs"]["expected_end_date"] = "2026-10-12"
+        self.spawn()
+        self.publish_once()
+        self.trigger_once()
+        self.book_plugin.book.assert_not_called()
+
+    def test_order_start_bound_reaches_real_book_selection(self):
+        self.order["user_inputs"]["expected_start_date"] = "2026-10-15"
+        self.spawn()
+        self.publish_once()
+        self.trigger_once()
+        self.book_plugin.book.assert_called_once()
+        self.assertIsNone(self.book_plugin.observed_approval)
+        self.assert_no_final_or_success_report()
+
+    def test_paused_order_is_removed_without_book(self):
+        self.spawn()
+        self.publish_once()
+        self.order["status"] = "pause"
+        self.trigger_once()
+        self.book_plugin.book.assert_not_called()
+        self.assertEqual(self.booker.m_tasks, [])
+        self.book_plugin.cleanup.assert_called_once()
+
+    def test_corrupt_redis_payload_uses_existing_delete_branch(self):
+        self.spawn()
+        self.publish_once()
+        self.retained.payload = "invalid-json"
+        self.trigger_once()
+        self.redis.delete.assert_called_once_with(self.signal_key)
+        self.book_plugin.book.assert_not_called()
+
+    def test_one_shared_signal_can_trigger_two_separately_bound_orders(self):
+        self.spawn()
+        other, other_page = self.new_book_plugin()
+        other_order = copy.deepcopy(self.order)
+        other_order.update(id=992, order_id="SYNTHETIC-OTHER")
+        other_order["user_inputs"]["username"] = "second-applicant@example.test"
+        self.cloud.get_vas_task_pop.return_value = other_order
+        self.booker.m_factory.create.return_value = other
+        self.booker._spawn_worker(self.apt.routing_key)
+        self.publish_once()
+        # Both fixtures start directly in the positive month; no month-click
+        # adapter is needed for this two-thread test, only no-delay sleeps.
+        with patch.object(self.booker.m_stop_event, "is_set", side_effect=[False, True]):
+            self.booker._booking_trigger_loop()
+        self.book_plugin.book.assert_called_once()
+        other.book.assert_called_once()
+        self.assertEqual(other.config.account.username, "second-applicant@example.test")
+        self.assertIsNot(self.book_page, other_page)
+        self.assertEqual(other.observed_approval.candidate.day, date(2026, 10, 14))
+        self.assertEqual(self.booker._execute_book_job.call_count, 2)
+        self.cloud.get_next_account.assert_called_once()
+        self.assert_no_final_or_success_report()
+
+    def test_later_negative_query_keeps_existing_signal_until_redis_expiry(self):
+        self.spawn()
+        self.publish_once()
+        original = self.retained.payload
+        self.query_page.outcomes = ["none"]
+        self.clock["now"] += 2
+        self.publish_once(positive=False)
+        self.assertEqual(self.query.query.call_count, 2)
+        self.redis.setex.assert_called_once()
+        self.redis.delete.assert_not_called()
+        self.assertEqual(self.retained.payload, original)
+
+
+class OfflineCliTests(unittest.TestCase):
+    def test_old_live_flag_is_rejected_before_loading_tests(self):
+        with patch.object(cli.unittest.defaultTestLoader, "loadTestsFromNames") as load, \
+                contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as caught:
+            cli.main(["--run"])
+        self.assertEqual(caught.exception.code, 2)
+        load.assert_not_called()
+
+    def test_cli_runs_only_existing_framework_suite_and_reports_offline(self):
+        result = SimpleNamespace(testsRun=26, failures=[], errors=[], skipped=[], wasSuccessful=lambda: True)
+        with patch.object(cli.unittest.defaultTestLoader, "loadTestsFromNames") as load, \
+                patch.object(cli.unittest, "TextTestRunner") as runner, \
+                contextlib.redirect_stdout(io.StringIO()) as output:
+            runner.return_value.run.return_value = result
+            self.assertEqual(cli.main([]), 0)
+        load.assert_called_once_with(cli.TEST_NAMES)
+        summary = json.loads(output.getvalue().split("ITA_QUERY_BOOK_FRAMEWORK_RESULT=")[1])
+        self.assertTrue(summary["passed"])
+        self.assertFalse(summary["liveAcceptance"])
+        self.assertEqual(summary["externalBoundaries"], "simulated")
+
+    def test_empty_skipped_or_failed_suite_does_not_pass(self):
+        for count, skipped, successful in ((0, [], True), (1, ["fixture"], True), (1, [], False)):
+            result = SimpleNamespace(testsRun=count, failures=[], errors=[], skipped=skipped,
+                                     wasSuccessful=lambda: successful)
+            with patch.object(cli.unittest.defaultTestLoader, "loadTestsFromNames"), \
+                    patch.object(cli.unittest, "TextTestRunner") as runner, \
+                    contextlib.redirect_stdout(io.StringIO()):
+                runner.return_value.run.return_value = result
+                self.assertEqual(cli.main(["--offline"]), 1)
+
+
+class LocalHarnessTests(unittest.TestCase):
+    """Same real GCO fixtures; site/pool/Redis are synthetic in offline runs."""
+
+    def setUp(self):
+        from tools import ita_query_book_local as local
+        self.local = local
+        self.fixture = ExistingFrameworkJointTests()
+        self.fixture.setUp()
+        self.addCleanup(self.fixture.doCleanups)
+        self.enterContext(contextlib.redirect_stdout(io.StringIO()))
+        self.enterContext(patch.object(local, "validate_cloud_otp_environment"))
+        f = self.fixture
+        f.cloud.get_next_account.return_value.update(pool_name="fixture.query.pool", status="active")
+        self.applicant = local.VSAccount(username=f.inputs["username"], password=f.inputs["password"])
+        self.cloud = local.LocalCloudBoundary(f.cloud, f.query_config,
+            SimpleNamespace(routing_key=f.route.routing_key, mail=None),
+            SimpleNamespace(model_dump=lambda: {}), self.applicant,
+            {key: f.inputs[key] for key in ("expected_start_date", "expected_end_date")})
+        self.enterContext(patch.object(local, "CalendarRequestAudit", return_value=Mock(**{
+            "settled_snapshot.return_value": {"otpRequests": 0, "avantiPosts": 0,
+                "availabilityRequests": 1, "timeSlotRequests": 1, "finalRequests": 0}})))
+        self.enterContext(patch.object(local.SentinelGCO, "_is_within_active_hours", return_value=True))
+        self.enterContext(patch.object(local.OrderBookerGCO, "_is_within_active_hours", return_value=True))
+        # Factories still belong to the GCO. Substitute only browser creation.
+        real_observe = local.observe_factory
+
+        def synthetic_factory(gco, role, stack, observed, on_created=None):
+            gco.m_factory.create = Mock(return_value=f.query if role == "query" else f.book_plugin)
+            return real_observe(gco, role, stack, observed, on_created=on_created)
+
+        self.enterContext(patch.object(local, "observe_factory", side_effect=synthetic_factory))
+        self.enterContext(book_flow.browser_navigation(f.book_page))
+
+    def run_case(self):
+        return self.local.run_framework_once(self.fixture.query_config, self.fixture.book_config,
+                                             self.fixture.route, self.cloud, {})
+
+    def test_one_real_framework_iteration_preserves_pool_order_signal_and_selection(self):
+        report = self.run_case()
+        self.assertTrue(report["passed"], report)
+        self.assertEqual(report["outcome"], "pre_final")
+        self.assertEqual((report["queryCalls"], report["bookCalls"]), (1, 1))
+        self.assertTrue(report["signalPublished"])
+        self.assertTrue(report["signalReadByBooker"])
+        self.assertTrue(report["selectionVerified"])
+        self.assertTrue(report["cleanupVerified"])
+        self.assertFalse(report["cloudOrders"])
+        self.fixture.cloud.get_next_account.assert_called_once_with("fixture.query.pool", 10800)
+        self.fixture.cloud.get_vas_task_pop.assert_not_called()
+        self.fixture.cloud.update_vas_task.assert_not_called()
+        self.fixture.cloud.slot_snapshot_report.assert_not_called()
+        self.assertNotEqual(self.fixture.query.config.account.username, self.fixture.book_plugin.config.account.username)
+        self.assertEqual(self.fixture.book_plugin.config.account.username, self.applicant.username)
+        self.assertEqual(self.fixture.book_plugin.book.call_args.args[1], self.cloud.order["user_inputs"])
+
+    def test_no_availability_does_not_call_book(self):
+        self.fixture.query_page.plans = [[(2026, 8, []), (2026, 9, []), (2026, 10, [])]] * 2
+        report = self.run_case()
+        self.assertFalse(report["passed"])
+        self.assertEqual(report["outcome"], "no_availability")
+        self.assertEqual(report["bookCalls"], 0)
+        self.assertFalse(report["signalPublished"])
+        self.assertTrue(report["cleanupVerified"])
+
+    def test_failed_redis_write_is_not_a_successful_handoff(self):
+        self.fixture.redis.setex.side_effect = lambda *_: False
+        report = self.run_case()
+        self.assertFalse(report["passed"])
+        self.assertEqual(report["reason"], "redis_publication_failed")
+        self.assertEqual(report["bookCalls"], 0)
+
+    def test_expired_signal_does_not_trigger_or_get_republished(self):
+        self.fixture.redis.get.side_effect = lambda *_: None
+        report = self.run_case()
+        self.assertTrue(report["signalPublished"])
+        self.assertFalse(report["signalReadByBooker"])
+        self.assertEqual(report["bookCalls"], 0)
+        self.assertEqual(report["outcome"], "not_triggered_expired_or_date_filtered")
+        self.fixture.redis.setex.assert_called_once()
+
+    def test_order_date_range_filters_real_trigger_without_calling_book(self):
+        self.cloud.order["user_inputs"]["expected_end_date"] = "2026-09-30"
+        report = self.run_case()
+        self.assertEqual(report["bookCalls"], 0)
+        self.assertTrue(report["signalReadByBooker"])
+        self.assertFalse(report["passed"])
+
+    def test_pool_failure_is_redacted_and_does_not_retry(self):
+        self.fixture.cloud.get_next_account.side_effect = RuntimeError("secret-password-and-body")
+        report = self.run_case()
+        self.assertEqual(report["reason"], "pool_allocation_failed")
+        self.assertEqual(self.cloud.pool_calls, 1)
+        self.assertNotIn("secret-password", json.dumps(report))
+        self.assertTrue(report["cleanupVerified"])
+
+    def test_same_account_cannot_masquerade_as_dual_account_acceptance(self):
+        self.fixture.cloud.get_next_account.return_value["username"] = self.applicant.username
+        report = self.run_case()
+        self.assertFalse(report["passed"])
+        self.assertEqual(report["reason"], "query_and_book_accounts_same_choose_other_applicant")
+        self.assertEqual(report["queryCalls"], 0)
+
+    def test_cloud_order_and_reporting_methods_are_not_forwarded(self):
+        for name in ("update_vas_task", "push_weixin_text", "get_vas_task", "return_vas_task_to_queue"):
+            with self.assertRaises(self.local.LocalAcceptanceError):
+                getattr(self.cloud, name)
+            getattr(self.fixture.cloud, name).assert_not_called()
+
+    def test_unexpected_final_request_fails_even_after_selection(self):
+        self.local.CalendarRequestAudit.return_value.settled_snapshot.return_value["finalRequests"] = 1
+        report = self.run_case()
+        self.assertFalse(report["passed"])
+        self.assertEqual(report["reason"], "unexpected_final_request_do_not_rerun")
+
+    def test_book_exception_does_not_escape_as_success_or_leak_body(self):
+        self.fixture.book_plugin.book.side_effect = RuntimeError("secret-otp-body")
+        report = self.run_case()
+        self.assertEqual(report["reason"], "book_failed")
+        self.assertEqual(report["bookErrorType"], "RuntimeError")
+        self.assertNotIn("secret-otp", json.dumps(report))
+        self.assertTrue(report["cleanupVerified"])
+
+    def test_final_success_cannot_be_reported_by_prefinal_test(self):
+        from vs_types import VSBookResult
+        self.fixture.book_plugin.book.side_effect = None
+        self.fixture.book_plugin.book.return_value = VSBookResult(success=True)
+        report = self.run_case()
+        self.assertFalse(report["passed"])
+        self.assertEqual(report["reason"], "unexpected_book_success_before_final")
+        self.fixture.cloud.update_vas_task.assert_not_called()
+        self.assertGreater(self.cloud.forbidden_calls, 0)
+
+    def test_book_login_failure_does_not_allocate_pool_account(self):
+        self.fixture.book_plugin.create_session.side_effect = RuntimeError("secret-provider-response")
+        report = self.run_case()
+        self.assertEqual(report["reason"], "applicant_session_not_created")
+        self.fixture.cloud.get_next_account.assert_not_called()
+        self.assertTrue(report["cleanupVerified"])
+
+    def test_interrupt_during_query_cleans_both_sessions_without_book(self):
+        self.fixture.query.query.side_effect = KeyboardInterrupt()
+        report = self.run_case()
+        self.assertEqual(report["outcome"], "interrupted")
+        self.assertTrue(report["cleanupVerified"])
+        self.assertEqual(report["bookCalls"], 0)
+
+    def test_cleanup_failure_invalidates_otherwise_successful_selection(self):
+        self.fixture.book_plugin.cleanup.side_effect = RuntimeError("synthetic-cleanup-failure")
+        report = self.run_case()
+        self.assertTrue(report["selectionVerified"])
+        self.assertFalse(report["passed"])
+        self.assertFalse(report["cleanupVerified"])
+
+    def test_repeated_otp_is_not_accepted_as_single_round(self):
+        self.local.CalendarRequestAudit.return_value.settled_snapshot.return_value["otpRequests"] = 2
+        report = self.run_case()
+        self.assertFalse(report["passed"])
+        self.assertEqual(report["reason"], "unexpected_repeated_preparation")
+
+
+class LocalFinalTests(unittest.TestCase):
+    def setUp(self):
+        from tools import ita_query_book_local as local
+        self.local = local
+        self.applicant = SimpleNamespace(
+            username="Applicant@example.test", password="fixture-password")
+        self.route = SimpleNamespace(
+            service_id=9001, routing_key="slot.fixture.it.tourist",
+            capability="single_schengen_tourism", lookahead_months=3)
+        candidate = SimpleNamespace(
+            day=date(2026, 10, 13), time_label="10:05 - 11:05", slots_free=1)
+        self.approval = SimpleNamespace(candidate=candidate)
+        self.plugin = SimpleNamespace(config=SimpleNamespace(account=self.applicant))
+        self.audit = Mock()
+        self.audit.settled_snapshot.return_value = {
+            "otpRequests": 0, "avantiPosts": 0, "availabilityRequests": 0,
+            "timeSlotRequests": 0, "finalRequests": 0,
+        }
+        self.observed = {
+            "book": SimpleNamespace(plugin=self.plugin, audit=self.audit),
+            "query": SimpleNamespace(plugin=object(), audit=self.audit),
+        }
+        self.control = local.LocalFinalSubmission(self.applicant, self.route)
+
+    def submit(self, result):
+        production = Mock(return_value=result)
+        with patch.object(self.local, "verify_plugin_selection"):
+            returned = self.control.submit(
+                self.plugin, self.route, self.approval, self.observed, production)
+        production.assert_called_once_with(self.plugin, self.route, self.approval)
+        return returned
+
+    def test_standard_success_delegates_once_without_private_fence(self):
+        result = SimpleNamespace(success=True)
+        self.assertIs(self.submit(result), result)
+        self.assertTrue(self.control.used)
+        self.assertTrue(self.control.dispatched)
+        self.assertFalse(hasattr(self.control, "claim_path"))
+
+    def test_standard_failure_remains_retryable_by_the_shared_booker(self):
+        result = SimpleNamespace(success=False)
+        self.assertIs(self.submit(result), result)
+        self.assertTrue(self.control.dispatched)
+        self.assertNotEqual(getattr(self.control, "failure_reason", None), "unknown_do_not_retry")
+
+    def test_same_local_control_cannot_dispatch_twice_in_one_run(self):
+        self.submit(SimpleNamespace(success=False))
+        with self.assertRaises(self.local.LocalAcceptanceError):
+            self.control.submit(
+                self.plugin, self.route, self.approval, self.observed, Mock())
+
+    def test_wrong_applicant_or_existing_final_request_is_rejected(self):
+        production = Mock()
+        self.plugin.config.account.username = "other@example.test"
+        with self.assertRaises(self.local.LocalAcceptanceError):
+            self.control.submit(
+                self.plugin, self.route, self.approval, self.observed, production,
+            )
+        production.assert_not_called()
+
+
+class LocalFinalCompositionTests(unittest.TestCase):
+    def setUp(self):
+        from tools import ita_query_book_local as local
+        self.local = local
+
+    def test_noninteractive_failure_uses_ordinary_exit_code(self):
+        args = SimpleNamespace(
+            submit_once=True, local_run=True, local_preflight=False,
+            book_account_file="fixture")
+        group = SimpleNamespace(sentinel=SimpleNamespace(account_pool_id="fixture"))
+        route = SimpleNamespace(routing_key="fixture", mail=None)
+        applicant = SimpleNamespace(
+            username="applicant@example.test", password="fixture-password")
+        result = {
+            "passed": False, "outcome": "book_failed_retryable",
+            "finalDispatched": True,
+        }
+        with contextlib.redirect_stdout(io.StringIO()), \
+                patch.object(self.local, "load_settings", return_value=(group, route, Mock(), {})), \
+                patch("sys.stdin.isatty", return_value=False), \
+                patch("builtins.input", side_effect=AssertionError("No interactive input")) as prompt, \
+                patch.object(self.local, "check_dependencies", return_value=("fixture", "fixture")), \
+                patch.object(self.local, "load_local_account", return_value=applicant), \
+                patch.object(self.local, "validate_cloud_otp_environment"), \
+                patch.object(self.local, "LocalFinalSubmission"), \
+                patch.object(self.local, "build_groups", return_value=(Mock(), Mock())), \
+                patch.object(self.local, "LocalCloudBoundary"), \
+                patch.object(self.local.VSCloudApi, "Instance"), \
+                patch.object(self.local, "private_redis", return_value=contextlib.nullcontext({})), \
+                patch.object(self.local, "run_framework_once", return_value=result):
+            self.assertEqual(self.local.main_local(args), 1)
+            result.update(passed=True, outcome="confirmed")
+            self.assertEqual(self.local.main_local(args), 0)
+            prompt.assert_not_called()
+class LocalConfigurationTests(unittest.TestCase):
+    def setUp(self):
+        from tools import ita_query_book_local as local
+        self.local = local
+        self.enterContext(contextlib.redirect_stdout(io.StringIO()))
+
+    def settings_fixture(self):
+        args = SimpleNamespace(config="synthetic.json", group="synthetic-group", proxy="http://127.0.0.1:6268",
+                               expected_start_date=None, expected_end_date=None)
+        group = {"identifier": args.group, "plugin_config": {"plugin_name": "ita_plugin"},
+                 "sentinel": {"account_pool_id": "synthetic-pool", "signal_ttl": 30},
+                 "appointment_types": [{"routing_key": "slot.other.it.tourist", "weight": 1}],
+                 "free_config": {"query_mode": "calendar", "otp_mode": "cloud", "final_submit_enabled": False,
+                                 "apt_configs": {"slot.other.it.tourist": {
+                                     "service_id": 9001, "capability": "single_schengen_tourism",
+                                     "calendar_scan": {"lookahead_months": 3},
+                                     "form": {"booking_type_control_id": "typeofbookingddl", "booking_type_value": "1",
+                                              "booking_type_labels": ["Single booking"], "purpose_control_id": "ddls_0",
+                                              "purpose_value": "42", "purpose_labels": ["Tourism"]},
+                                     "mail": {"authorization_source": "account"}}}}}
+        return args, group
+
+    def test_real_settings_parser_accepts_other_region_without_fixed_mailbox(self):
+        args, group = self.settings_fixture()
+        with patch.object(self.local.Path, "read_text", return_value=json.dumps([group])), \
+                patch.object(self.local.configure, "TEST_ACCOUNT", None):
+            source, route, proxy, preferences = self.local.load_settings(args)
+        self.assertEqual(route.service_id, 9001)
+        self.assertEqual(source.sentinel.account_pool_id, "synthetic-pool")
+        self.assertEqual(route.mail.mailbox_for("second@example.test"), "second@example.test")
+        self.assertEqual(proxy.port, 6268)
+        self.assertEqual(preferences, {})
+
+    def test_invalid_settings_cannot_reach_dependencies_or_pool(self):
+        args, template = self.settings_fixture()
+        for changes in ({"query_mode": "services_probe"}, {"otp_mode": "manual"}, {"final_submit_enabled": True}):
+            group = copy.deepcopy(template)
+            group["free_config"].update(changes)
+            with self.subTest(changes=changes), \
+                    patch.object(self.local.Path, "read_text", return_value=json.dumps([group])), \
+                    patch.object(self.local.configure, "TEST_ACCOUNT", None), \
+                    self.assertRaises(self.local.LocalAcceptanceError):
+                self.local.load_settings(args)
+
+    def test_public_proxy_and_reversed_date_range_are_rejected_before_run(self):
+        args, group = self.settings_fixture()
+        for proxy, start, end in (("http://remote.example.test:6268", None, None),
+                                  (args.proxy, "2026-10-31", "2026-10-01")):
+            args.proxy, args.expected_start_date, args.expected_end_date = proxy, start, end
+            with patch.object(self.local.Path, "read_text", return_value=json.dumps([group])), \
+                    patch.object(self.local.configure, "TEST_ACCOUNT", None), \
+                    self.assertRaises(Exception):
+                self.local.load_settings(args)
+
+    def test_successful_preflight_never_prompts_allocates_or_launches(self):
+        args = SimpleNamespace(local_preflight=True)
+        group = SimpleNamespace(sentinel=SimpleNamespace(account_pool_id="synthetic-pool"))
+        route = SimpleNamespace(routing_key="synthetic-route")
+        with patch.object(self.local, "load_settings", return_value=(group, route, Mock(), {})), \
+                patch.object(self.local, "check_dependencies", return_value=("redis-server", "/synthetic/chrome")), \
+                patch.object(self.local, "_get_credentials") as credentials, \
+                patch.object(self.local.VSCloudApi, "Instance") as api, \
+                patch.object(self.local, "private_redis") as private_redis:
+            self.assertEqual(self.local.main_local(args), 0)
+        credentials.assert_not_called()
+        api.assert_not_called()
+        private_redis.assert_not_called()
+
+    def test_default_cli_never_starts_local_run_and_explicit_mode_is_forwarded(self):
+        with patch.object(self.local, "main_local", return_value=7) as live:
+            self.assertEqual(cli.main(["--local-run", "--group", "my-route-group"]), 7)
+            self.assertEqual(live.call_args.args[0].group, "my-route-group")
+            self.assertTrue(live.call_args.args[0].local_run)
+
+    def test_preflight_checks_dependencies_before_api_or_credentials(self):
+        args = SimpleNamespace(local_preflight=True)
+        with patch.object(self.local, "load_settings", return_value=(Mock(), Mock(), Mock(), {})), \
+                patch.object(self.local, "check_dependencies", side_effect=self.local.LocalAcceptanceError("missing_dependency")), \
+                patch.object(self.local, "_get_credentials") as credentials, \
+                patch.object(self.local.VSCloudApi, "Instance") as api:
+            self.assertEqual(self.local.main_local(args), 1)
+        credentials.assert_not_called()
+        api.assert_not_called()
+
+    def test_group_copy_preserves_service_and_ttl_not_production_config(self):
+        group = GroupConfig(identifier="source", sentinel={"account_pool_id": "test-pool", "signal_ttl": 37},
+            appointment_types=[{"routing_key": "slot.other.it.tourist", "weight": 1}],
+            free_config={"query_mode": "calendar", "otp_mode": "cloud", "final_submit_enabled": False,
+                         "persistent_browser_profile_path": "/never-touch", "apt_configs": {"some-route": {"service_id": 999}}})
+        before = group.model_dump()
+        query, book = self.local.build_groups(group, "synthetic")
+        self.assertEqual(group.model_dump(), before)
+        self.assertEqual(query.sentinel.signal_ttl, 37)
+        self.assertEqual(query.sentinel.account_pool_id, "test-pool")
+        self.assertEqual(query.free_config["apt_configs"], before["free_config"]["apt_configs"])
+        self.assertEqual(book.booker.account_source, "order")
+        self.assertEqual(book.free_config["query_mode"], "services_probe")
+        self.assertNotIn("persistent_browser_profile_path", query.free_config)
+        self.assertFalse(book.free_config["final_submit_enabled"])
+
+    def test_final_flag_only_enables_applicant_copy_and_requires_live_cli(self):
+        group = GroupConfig(identifier="source", free_config={"final_submit_enabled": False})
+        group.appointment_types = [SimpleNamespace(weight=1)]
+        query, book = self.local.build_groups(group, "fixture", submit_once=True)
+        self.assertFalse(group.free_config["final_submit_enabled"])
+        self.assertFalse(query.free_config["final_submit_enabled"])
+        self.assertTrue(book.free_config["final_submit_enabled"])
+        with patch.object(self.local, "main_local", return_value=0) as live:
+            for args in (["--submit-once"], ["--local-preflight", "--submit-once"], ["--offline", "--submit-once"]):
+                with self.assertRaises(SystemExit), contextlib.redirect_stderr(io.StringIO()):
+                    cli.main(args)
+            live.assert_not_called()
+            self.assertEqual(cli.main(["--local-run", "--submit-once"]), 0)
+            self.assertTrue(live.call_args.args[0].submit_once)
+
+    def test_final_requires_explicit_live_mode_before_pool_or_browser(self):
+        args = SimpleNamespace(submit_once=True, local_run=False)
+        with patch.object(self.local, "load_settings", return_value=(Mock(), Mock(), Mock(), {})), \
+                patch.object(self.local, "check_dependencies") as dependencies, \
+                patch.object(self.local.VSCloudApi, "Instance") as api:
+            self.assertEqual(self.local.main_local(args), 1)
+        dependencies.assert_not_called()
+        api.assert_not_called()
+
+    def test_private_redis_is_owned_socket_only_no_shared_flush(self):
+        process = Mock()
+        process.poll.return_value = None
+        with patch.object(self.local.subprocess, "Popen", return_value=process) as popen, \
+                patch.object(self.local.redis, "Redis") as redis:
+            redis.return_value.ping.return_value = True
+            with self.local.private_redis("/synthetic/redis-server") as config:
+                self.assertTrue(config["unix_socket_path"].startswith("/tmp/ita-qb-"))
+                self.assertNotIn("host", config)
+                command = popen.call_args.args[0]
+                self.assertEqual(command[command.index("--port") + 1], "0")
+                self.assertEqual(command[command.index("--save") + 1], "")
+                self.assertEqual(command[command.index("--appendonly") + 1], "no")
+        process.terminate.assert_called_once()
+        process.wait.assert_called_once_with(timeout=5)
+        redis.return_value.flushdb.assert_not_called()
+        redis.return_value.flushall.assert_not_called()
+        self.assertFalse(self.local.Path(config["unix_socket_path"]).parent.exists())
+
+    def test_private_redis_cleanup_also_runs_when_test_fails(self):
+        process = Mock()
+        process.poll.return_value = None
+        with patch.object(self.local.subprocess, "Popen", return_value=process), \
+                patch.object(self.local.redis, "Redis") as redis:
+            redis.return_value.ping.return_value = True
+            with self.assertRaisesRegex(RuntimeError, "synthetic"):
+                with self.local.private_redis("/synthetic/redis-server"):
+                    raise RuntimeError("synthetic")
+        process.terminate.assert_called_once()
+
+    def test_private_redis_startup_failure_closes_client_and_never_yields(self):
+        process = Mock()
+        process.poll.return_value = 1
+        with patch.object(self.local.subprocess, "Popen", return_value=process), \
+                patch.object(self.local.redis, "Redis") as redis:
+            with self.assertRaisesRegex(self.local.LocalAcceptanceError, "private_redis_exited"):
+                with self.local.private_redis("/synthetic/redis-server"):
+                    self.fail("Dead Redis cannot be used")
+            redis.return_value.close.assert_called_once()
+
+
+class LocalRedisIntegrationTests(unittest.TestCase):
+    """Opt-in class: real disposable Redis, synthetic website/account I/O.
+
+Not included in the CLI's --offline TEST_NAMES, which promises no subprocesses.
+"""
+
+    def run_real_redis_case(self, *, expire=False):
+        import shutil
+        import socket
+        import time
+        from tools import ita_query_book_local as local
+        from utils.safe_redis_cli import SafeRedisClient
+        executable = shutil.which("redis-server")
+        if not executable:
+            self.skipTest("redis-server is needed for the explicitly selected Redis integration test")
+        original_connect = socket.socket.connect
+        real_sleep = time.sleep
+        with local.private_redis(executable) as config:
+            case = LocalHarnessTests()
+            case.setUp()
+            try:
+                def socket_only(connection, address):
+                    if address != config["unix_socket_path"]:
+                        raise AssertionError("Redis integration attempted non-owned socket")
+                    return original_connect(connection, address)
+
+                case.enterContext(patch.object(socket.socket, "connect", socket_only))
+                for cls in (local.SentinelGCO, local.OrderBookerGCO):
+                    case.enterContext(patch.dict(cls.__init__.__globals__, {"SafeRedisClient": SafeRedisClient}))
+                if expire:
+                    case.fixture.query_config.sentinel.signal_ttl = 1
+                    read = SafeRedisClient.get
+
+                    def after_expiry(client, key):
+                        real_sleep(1.1)  # Fixture mocks time.sleep; use actual server wall clock here.
+                        return read(client, key)
+
+                    case.enterContext(patch.object(SafeRedisClient, "get", after_expiry))
+                report = local.run_framework_once(case.fixture.query_config, case.fixture.book_config,
+                                                  case.fixture.route, case.cloud, config)
+            finally:
+                case.doCleanups()
+        self.assertFalse(local.Path(config["unix_socket_path"]).parent.exists())
+        return report
+
+    def test_real_framework_publishes_and_consumes_real_redis(self):
+        report = self.run_real_redis_case()
+        self.assertTrue(report["passed"], report)
+        self.assertTrue(report["signalPublished"])
+        self.assertTrue(report["signalReadByBooker"])
+        self.assertEqual(report["bookCalls"], 1)
+
+    def test_real_redis_expiry_prevents_book_without_republishing(self):
+        report = self.run_real_redis_case(expire=True)
+        self.assertTrue(report["signalPublished"])
+        self.assertFalse(report["signalReadByBooker"])
+        self.assertEqual(report["bookCalls"], 0)
+        self.assertFalse(report["passed"])
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 26 - 0
test/ita/test_debug_ita_reservation.py

@@ -0,0 +1,26 @@
+"""The legacy Italy reservation diagnostic is intentionally retired."""
+
+import unittest
+
+from plugins import ita_plugin
+from tools import debug_ita_reservation as diagnostic
+
+
+class RetiredReservationDiagnosticTests(unittest.TestCase):
+    def test_cli_reports_retired_without_browser_or_network(self):
+        self.assertEqual(diagnostic.main([]), 0)
+
+    def test_old_receipt_parsers_are_not_production_symbols(self):
+        for name in (
+            "LIST_READ_SCRIPT", "ReservationReadError", "ReservationState",
+            "read_reservation_listing",
+        ):
+            self.assertFalse(hasattr(ita_plugin, name), name)
+
+    def test_compatibility_entrypoints_fail_explicitly(self):
+        with self.assertRaises(diagnostic.ReservationDiagnosticRetired):
+            diagnostic.read_reservation_detail(object())
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 571 - 0
test/ita/test_debug_ita_soak.py

@@ -0,0 +1,571 @@
+import ast
+import io
+import json
+import os
+import stat
+import subprocess
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from DrissionPage.errors import BrowserConnectError, PageDisconnectedError
+
+from plugins.ita_plugin import ItaTargetServiceLinkMissingError
+from tools.debug_ita_session import DebugConfigurationError
+from tools.debug_ita_soak import (
+    DAY_SECONDS,
+    DEFAULT_MAX_SESSION_ATTEMPTS,
+    DEFAULT_MAX_WAIT_SECONDS,
+    DEFAULT_MIN_WAIT_SECONDS,
+    run_soak,
+    write_soak_status,
+)
+from vs_types import (
+    AvailabilityStatus,
+    SessionExpiredOrInvalidError,
+    VSQueryResult,
+)
+
+
+class FakeClock:
+    def __init__(self):
+        self.now = 0.0
+
+    def monotonic(self):
+        return self.now
+
+    def wall_time(self):
+        return 1_800_000_000.0 + self.now
+
+    def sleep(self, seconds):
+        self.now += seconds
+
+
+class FakeSoakPage:
+    url = "https://prenotami.esteri.it/Services/Booking/1321"
+    title = "Index - Prenot@Mi"
+
+    def ele(self, _selector, timeout=None):
+        del timeout
+        return None
+
+    def run_js(self, _script):
+        if "coordinate:ita-service-list-structure" in _script:
+            return {
+                "path": "/Services", "ready_state": "complete", "table_count": 1,
+                "row_count": 0, "booking_link_count": 0, "target_link_count": 0,
+            }
+        return {
+            "path": "/Services/Booking/1321",
+            "form": {
+                "method": "POST",
+                "action_path": "/Services/Booking/1321",
+            },
+            "field_count": 0,
+            "fields": [],
+            "button_count": 0,
+            "buttons": [],
+        }
+
+
+class FakeSoakPlugin:
+    session_behaviors = [["none"]]
+    create_behaviors = ["ok"]
+    instances = []
+
+    def __init__(self, group_id):
+        self.group_id = group_id
+        session_index = len(self.instances)
+        configured_index = min(
+            session_index,
+            len(self.session_behaviors) - 1,
+        )
+        self.behaviors = list(self.session_behaviors[configured_index])
+        create_index = min(
+            session_index,
+            len(self.create_behaviors) - 1,
+        )
+        self.create_behavior = self.create_behaviors[create_index]
+        self.query_calls = 0
+        self.create_session_calls = 0
+        self.cleanup_calls = 0
+        self.page = FakeSoakPage()
+        self.instances.append(self)
+
+    def set_log(self, logger):
+        self.logger = logger
+
+    def set_config(self, config):
+        self.config = config
+
+    def create_session(self):
+        self.create_session_calls += 1
+        if self.create_behavior == "connect-error":
+            raise BrowserConnectError("offline browser connection failed")
+
+    def query(self, apt_type):
+        index = min(self.query_calls, len(self.behaviors) - 1)
+        behavior = self.behaviors[index]
+        self.query_calls += 1
+        if behavior == "missing-link":
+            raise ItaTargetServiceLinkMissingError(
+                "Italy target service link is missing after the bounded wait"
+            )
+        if behavior == "expired":
+            raise SessionExpiredOrInvalidError("offline session expired")
+        if behavior == "disconnected":
+            raise PageDisconnectedError("offline browser disconnected")
+        if behavior == "weak":
+            return VSQueryResult(
+                success=True,
+                apt_type=apt_type,
+                availability_status=AvailabilityStatus.NoneAvailable,
+            )
+        if behavior == "error":
+            raise RuntimeError(
+                "private@example.test token abcdefghijklmnopqrstuvwxyz123456"
+            )
+        return VSQueryResult(
+            success=False,
+            apt_type=apt_type,
+            availability_status=AvailabilityStatus.NoneAvailable,
+        )
+
+    def cleanup(self):
+        self.cleanup_calls += 1
+
+
+class DebugItaSoakTests(unittest.TestCase):
+    def setUp(self):
+        FakeSoakPlugin.session_behaviors = [["none"]]
+        FakeSoakPlugin.create_behaviors = ["ok"]
+        FakeSoakPlugin.instances = []
+
+    @staticmethod
+    def _run(
+        *,
+        duration_seconds=120,
+        min_wait=60,
+        max_wait=60,
+        max_session_attempts=DEFAULT_MAX_SESSION_ATTEMPTS,
+        restart_wait=60,
+        sleep=None,
+    ):
+        clock = FakeClock()
+        statuses = []
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        if sleep is None:
+            sleep = clock.sleep
+        with (
+            patch(
+                "tools.debug_ita_soak.resolve_chrome_path",
+                return_value=Path("/test/chrome"),
+            ),
+            patch(
+                "tools.debug_ita_soak._get_query_credentials",
+                return_value=("query@example.test", "query-password"),
+            ) as credential_reader,
+            patch(
+                "tools.debug_ita_soak._prepare_query_profile",
+                return_value=Path("/offline/query-profile"),
+            ) as profile_preparer,
+            patch(
+                "tools.debug_ita_soak._bind_query_profile",
+                return_value=Mock(),
+            ),
+            patch.dict("tools.debug_ita_soak.os.environ", {}, clear=False),
+            redirect_stdout(stdout),
+            redirect_stderr(stderr),
+        ):
+            exit_code = run_soak(
+                {},
+                apply=True,
+                non_interactive=True,
+                duration_seconds=duration_seconds,
+                min_wait=min_wait,
+                max_wait=max_wait,
+                max_session_attempts=max_session_attempts,
+                restart_wait=restart_wait,
+                randint=lambda _minimum, _maximum: max_wait,
+                sleep=sleep,
+                monotonic=clock.monotonic,
+                wall_time=clock.wall_time,
+                plugin_factory=FakeSoakPlugin,
+                status_writer=lambda body: statuses.append(dict(body)),
+            )
+        return (
+            exit_code,
+            stdout.getvalue(),
+            stderr.getvalue(),
+            clock,
+            statuses,
+            credential_reader,
+            profile_preparer,
+        )
+
+    def test_accelerated_full_day_uses_one_session_and_completes(self):
+        result = self._run(
+            duration_seconds=DAY_SECONDS,
+            min_wait=DEFAULT_MAX_WAIT_SECONDS,
+            max_wait=DEFAULT_MAX_WAIT_SECONDS,
+        )
+        exit_code, stdout, stderr, clock, statuses, _, _ = result
+        plugin = FakeSoakPlugin.instances[0]
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(clock.now, DAY_SECONDS)
+        self.assertEqual(len(FakeSoakPlugin.instances), 1)
+        self.assertEqual(plugin.create_session_calls, 1)
+        self.assertEqual(plugin.query_calls, 288)
+        self.assertEqual(plugin.cleanup_calls, 1)
+        self.assertIn(
+            "ITA_SOAK_COMPLETED duration_seconds=86400 probes=288",
+            stdout,
+        )
+        self.assertIn("ITA_SOAK_CLEANUP_OK", stdout)
+        self.assertEqual(statuses[-1]["state"], "completed")
+        self.assertEqual(statuses[-1]["elapsed_seconds"], DAY_SECONDS)
+        self.assertEqual(statuses[-1]["exit_code"], 0)
+        self.assertEqual(stderr, "")
+
+    def test_accelerated_full_day_survives_many_normal_session_expirations(self):
+        FakeSoakPlugin.session_behaviors = [
+            ["none", "none", "expired"] for _ in range(200)
+        ]
+
+        result = self._run(
+            duration_seconds=DAY_SECONDS,
+            min_wait=DEFAULT_MAX_WAIT_SECONDS,
+            max_wait=DEFAULT_MAX_WAIT_SECONDS,
+        )
+        exit_code, stdout, stderr, clock, statuses, _, _ = result
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(clock.now, DAY_SECONDS)
+        self.assertGreaterEqual(statuses[-1]["session_expirations"], 96)
+        self.assertGreaterEqual(statuses[-1]["session_attempts"], 97)
+        self.assertEqual(
+            statuses[-1]["consecutive_session_expirations"],
+            0,
+        )
+        self.assertEqual(statuses[-1]["state"], "completed")
+        self.assertIn("ITA_SOAK_COMPLETED duration_seconds=86400", stdout)
+        self.assertNotIn("max-session-attempts-reached", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_one_missing_link_is_recorded_then_next_probe_can_recover(self):
+        FakeSoakPlugin.session_behaviors = [["missing-link", "none"]]
+
+        exit_code, stdout, stderr, _, statuses, _, _ = self._run()
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(FakeSoakPlugin.instances[0].query_calls, 2)
+        self.assertIn("ITA_SOAK_TRANSIENT", stdout)
+        self.assertIn("consecutive=1 total=1", stdout)
+        self.assertIn("ITA_SERVICE_LIST_STRUCTURE=", stdout)
+        self.assertIn('"target_link_count": 0', stdout)
+        self.assertNotIn("ITA_SERVICE_LIST_STRUCTURE=not-available", stdout)
+        self.assertEqual(statuses[-1]["transient_errors"], 1)
+        self.assertEqual(stderr, "")
+
+    def test_failed_diagnostic_does_not_interrupt_missing_link_recovery(self):
+        FakeSoakPlugin.session_behaviors = [["missing-link", "none"]]
+        with patch.object(FakeSoakPage, "run_js", side_effect=RuntimeError("server-secret")):
+            exit_code, stdout, stderr, _, statuses, _, _ = self._run()
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(FakeSoakPlugin.instances[0].query_calls, 2)
+        self.assertEqual(FakeSoakPlugin.instances[0].cleanup_calls, 1)
+        self.assertEqual(statuses[-1]["transient_errors"], 1)
+        self.assertIn("ITA_SERVICE_LIST_STRUCTURE=not-available", stdout)
+        self.assertNotIn("server-secret", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_second_consecutive_missing_link_stops_without_third_query(self):
+        FakeSoakPlugin.session_behaviors = [
+            ["missing-link", "missing-link", "none"]
+        ]
+
+        exit_code, stdout, stderr, _, statuses, _, _ = self._run(
+            duration_seconds=DAY_SECONDS
+        )
+
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(FakeSoakPlugin.instances[0].query_calls, 2)
+        self.assertIn(
+            "ITA_SOAK_FAILED reason=consecutive-target-link-misses",
+            stdout,
+        )
+        self.assertEqual(statuses[-1]["state"], "failed")
+        self.assertEqual(statuses[-1]["exit_code"], 1)
+        self.assertEqual(stderr, "")
+
+    def test_expired_session_is_cleaned_then_recreated_after_safe_wait(self):
+        FakeSoakPlugin.session_behaviors = [["expired"], ["none"]]
+
+        exit_code, stdout, stderr, clock, statuses, _, _ = self._run()
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(len(FakeSoakPlugin.instances), 2)
+        self.assertEqual(FakeSoakPlugin.instances[0].cleanup_calls, 1)
+        self.assertEqual(FakeSoakPlugin.instances[1].cleanup_calls, 1)
+        self.assertEqual(clock.now, 120)
+        self.assertIn("ITA_SOAK_SESSION_EXPIRED", stdout)
+        self.assertIn("session_attempts=2", stdout)
+        self.assertEqual(statuses[-1]["session_attempts"], 2)
+        self.assertEqual(stderr, "")
+
+    def test_second_consecutive_session_expiration_stops_without_third_session(self):
+        FakeSoakPlugin.session_behaviors = [
+            ["expired"],
+            ["expired"],
+            ["none"],
+        ]
+
+        exit_code, stdout, stderr, _, statuses, _, _ = self._run(
+            duration_seconds=DAY_SECONDS
+        )
+
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(len(FakeSoakPlugin.instances), 2)
+        self.assertIn(
+            "ITA_SOAK_FAILED reason=consecutive-session-expirations",
+            stdout,
+        )
+        self.assertEqual(statuses[-1]["session_expirations"], 2)
+        self.assertEqual(
+            statuses[-1]["consecutive_session_expirations"],
+            2,
+        )
+        self.assertEqual(statuses[-1]["state"], "failed")
+        self.assertEqual(stderr, "")
+
+    def test_reauthentication_rate_limit_stops_dense_login_loop(self):
+        FakeSoakPlugin.session_behaviors = [
+            ["none", "expired"] for _ in range(10)
+        ]
+
+        exit_code, stdout, stderr, _, statuses, _, _ = self._run(
+            duration_seconds=DAY_SECONDS
+        )
+
+        self.assertEqual(exit_code, 1)
+        self.assertIn(
+            "ITA_SOAK_FAILED reason=reauthentication-rate-limit",
+            stdout,
+        )
+        self.assertEqual(statuses[-1]["session_expirations"], 7)
+        self.assertEqual(
+            statuses[-1]["session_reauthentications_last_hour"],
+            7,
+        )
+        self.assertEqual(statuses[-1]["state"], "failed")
+        self.assertEqual(stderr, "")
+
+    def test_disconnected_browser_is_cleaned_then_recreated_after_safe_wait(self):
+        FakeSoakPlugin.session_behaviors = [["disconnected"], ["none"]]
+
+        exit_code, stdout, stderr, clock, statuses, _, _ = self._run()
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(len(FakeSoakPlugin.instances), 2)
+        self.assertEqual(FakeSoakPlugin.instances[0].cleanup_calls, 1)
+        self.assertEqual(FakeSoakPlugin.instances[1].cleanup_calls, 1)
+        self.assertEqual(clock.now, 120)
+        self.assertIn("ITA_SOAK_BROWSER_DISCONNECTED", stdout)
+        self.assertIn("consecutive=1 total=1", stdout)
+        self.assertEqual(statuses[-1]["browser_disconnects"], 1)
+        self.assertEqual(statuses[-1]["session_attempts"], 2)
+        self.assertEqual(stderr, "")
+
+    def test_second_consecutive_browser_disconnect_stops_without_third_session(self):
+        FakeSoakPlugin.session_behaviors = [
+            ["disconnected"],
+            ["disconnected"],
+            ["none"],
+        ]
+
+        exit_code, stdout, stderr, _, statuses, _, _ = self._run(
+            duration_seconds=DAY_SECONDS
+        )
+
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(len(FakeSoakPlugin.instances), 2)
+        self.assertEqual(FakeSoakPlugin.instances[0].cleanup_calls, 1)
+        self.assertEqual(FakeSoakPlugin.instances[1].cleanup_calls, 1)
+        self.assertIn(
+            "ITA_SOAK_FAILED reason=consecutive-browser-disconnects",
+            stdout,
+        )
+        self.assertEqual(statuses[-1]["browser_disconnects"], 2)
+        self.assertEqual(statuses[-1]["state"], "failed")
+        self.assertEqual(statuses[-1]["exit_code"], 1)
+        self.assertEqual(stderr, "")
+
+    def test_one_browser_connect_failure_is_retried_after_safe_wait(self):
+        FakeSoakPlugin.create_behaviors = ["connect-error", "ok"]
+        FakeSoakPlugin.session_behaviors = [["none"], ["none"]]
+
+        exit_code, stdout, stderr, clock, statuses, _, _ = self._run()
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(len(FakeSoakPlugin.instances), 2)
+        self.assertEqual(FakeSoakPlugin.instances[0].cleanup_calls, 1)
+        self.assertEqual(FakeSoakPlugin.instances[1].cleanup_calls, 1)
+        self.assertEqual(clock.now, 120)
+        self.assertIn("ITA_SOAK_BROWSER_CONNECT_FAILED", stdout)
+        self.assertIn("consecutive=1 total=1", stdout)
+        self.assertEqual(statuses[-1]["browser_connect_failures"], 1)
+        self.assertEqual(statuses[-1]["session_attempts"], 2)
+        self.assertEqual(stderr, "")
+
+    def test_second_browser_connect_failure_stops_without_third_attempt(self):
+        FakeSoakPlugin.create_behaviors = [
+            "connect-error",
+            "connect-error",
+            "ok",
+        ]
+
+        exit_code, stdout, stderr, _, statuses, _, _ = self._run(
+            duration_seconds=DAY_SECONDS
+        )
+
+        self.assertEqual(exit_code, 1)
+        self.assertEqual(len(FakeSoakPlugin.instances), 2)
+        self.assertIn(
+            "ITA_SOAK_FAILED reason=consecutive-browser-connect-failures",
+            stdout,
+        )
+        self.assertEqual(statuses[-1]["browser_connect_failures"], 2)
+        self.assertEqual(statuses[-1]["state"], "failed")
+        self.assertEqual(statuses[-1]["exit_code"], 1)
+        self.assertEqual(stderr, "")
+
+    def test_weak_signal_stops_immediately_without_waiting_or_booking(self):
+        FakeSoakPlugin.session_behaviors = [["weak", "none"]]
+
+        exit_code, stdout, stderr, clock, statuses, _, _ = self._run(
+            duration_seconds=DAY_SECONDS
+        )
+
+        self.assertEqual(exit_code, 4)
+        self.assertEqual(clock.now, 0)
+        self.assertEqual(FakeSoakPlugin.instances[0].query_calls, 1)
+        self.assertIn("ITA_SOAK_WEAK_SIGNAL", stdout)
+        self.assertEqual(statuses[-1]["state"], "weak_signal")
+        self.assertEqual(statuses[-1]["exit_code"], 4)
+        self.assertEqual(stderr, "")
+
+    def test_default_preflight_reads_no_credentials_and_makes_no_session(self):
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        with (
+            patch(
+                "tools.debug_ita_soak._get_query_credentials",
+                side_effect=AssertionError("credentials must not be read"),
+            ),
+            redirect_stdout(stdout),
+            redirect_stderr(stderr),
+        ):
+            exit_code = run_soak(
+                {},
+                apply=False,
+                non_interactive=True,
+                duration_seconds=DAY_SECONDS,
+                min_wait=DEFAULT_MIN_WAIT_SECONDS,
+                max_wait=DEFAULT_MAX_WAIT_SECONDS,
+            )
+
+        self.assertEqual(exit_code, 0)
+        self.assertEqual(FakeSoakPlugin.instances, [])
+        self.assertIn("ITA_SOAK_PREFLIGHT_OK", stdout.getvalue())
+        self.assertIn("external_request=false", stdout.getvalue())
+        self.assertEqual(stderr.getvalue(), "")
+
+    def test_duration_over_one_day_is_rejected_before_credentials(self):
+        with (
+            patch(
+                "tools.debug_ita_soak._get_query_credentials",
+                side_effect=AssertionError("credentials must not be read"),
+            ),
+            self.assertRaises(DebugConfigurationError),
+        ):
+            run_soak(
+                {},
+                apply=True,
+                non_interactive=True,
+                duration_seconds=DAY_SECONDS + 1,
+                min_wait=DEFAULT_MIN_WAIT_SECONDS,
+                max_wait=DEFAULT_MAX_WAIT_SECONDS,
+            )
+
+    def test_status_file_is_private_and_contains_no_credentials(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            status_path = Path(temp_dir) / "ita_soak" / "status.json"
+            write_soak_status(
+                {
+                    "state": "running",
+                    "service_id": 1321,
+                    "elapsed_seconds": 60,
+                    "probes": 1,
+                },
+                status_path=status_path,
+            )
+            body = status_path.read_text(encoding="utf-8")
+
+            self.assertEqual(json.loads(body)["state"], "running")
+            self.assertNotIn("username", body.lower())
+            self.assertNotIn("password", body.lower())
+            self.assertNotIn("cookie", body.lower())
+            if os.name == "posix":
+                self.assertEqual(
+                    stat.S_IMODE(status_path.parent.stat().st_mode),
+                    0o700,
+                )
+                self.assertEqual(
+                    stat.S_IMODE(status_path.stat().st_mode),
+                    0o600,
+                )
+
+    def test_cli_default_is_zero_network_preflight(self):
+        repo_root = Path(__file__).resolve().parents[2]
+        completed = subprocess.run(
+            [sys.executable, str(repo_root / "tools" / "debug_ita_soak.py")],
+            cwd=repo_root,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+
+        self.assertEqual(completed.returncode, 0)
+        self.assertIn("ITA_SOAK_PREFLIGHT_OK", completed.stdout)
+        self.assertIn("duration_seconds=86400", completed.stdout)
+        self.assertIn("external_request=false", completed.stdout)
+        self.assertEqual(completed.stderr, "")
+
+    def test_source_has_one_query_call_and_no_book_call(self):
+        source_path = (
+            Path(__file__).resolve().parents[2] / "tools" / "debug_ita_soak.py"
+        )
+        tree = ast.parse(source_path.read_text(encoding="utf-8"))
+        query_calls = []
+        book_calls = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call):
+                continue
+            if not isinstance(node.func, ast.Attribute):
+                continue
+            if node.func.attr == "query":
+                query_calls.append(node)
+            if node.func.attr == "book":
+                book_calls.append(node)
+
+        self.assertEqual(len(query_calls), 1)
+        self.assertEqual(book_calls, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 147 - 0
test/ita/test_ita_booker_integration.py

@@ -0,0 +1,147 @@
+"""Italy Book integration with the existing shared OrderBooker."""
+
+import json
+import threading
+import unittest
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+from plugins.ita_plugin import FINAL_PATH, NATIVE_FINAL_SCRIPT
+from test.ita import test_ita_calendar_book_flow as flow
+from test.ita.test_ita_plugin import OrderBookerGCO
+
+
+class FinalPage(flow.FlowPage):
+    def __init__(self):
+        super().__init__([flow.month("2026-09", {1: 0}), flow.month("2026-10", {13: 2})])
+        self.url += "?selectedService=Visti%20Nazionali%20e%20Schengen"
+        self.final_count = 0
+        self.response_error = ""
+        self.wrong_request_day = False
+
+    def run_js(self, script, *args):
+        if script != NATIVE_FINAL_SCRIPT:
+            return super().run_js(script, *args)
+        _service, day, daily_id, time_label, capacity = args
+        self.final_count += 1
+        self.listen.queue.append(SimpleNamespace(
+            url="https://prenotami.esteri.it" + FINAL_PATH,
+            method="POST",
+            tab_id=self.tab_id,
+            is_failed=False,
+            request=SimpleNamespace(postData={
+                "idCalendarioGiornaliero": daily_id,
+                "selectedDay": "2026-10-14" if self.wrong_request_day else day,
+                "selectedHour": f"{time_label}\n({capacity})",
+            }),
+            response=SimpleNamespace(
+                status=200,
+                url="https://prenotami.esteri.it" + FINAL_PATH,
+                raw_body=json.dumps({
+                    "errorMessage": self.response_error,
+                    "url": "/Reservation" if not self.response_error else "/BookingCalendar",
+                }),
+            ),
+        ))
+        return {"clicked": True}
+
+
+class BookerIntegrationTests(unittest.TestCase):
+    def setUp(self):
+        self.page = FinalPage()
+        self.plugin, self.route, self.trigger = flow.prepared_plugin(self.page)
+        self.plugin.free_config.update(otp_mode="manual", final_submit_enabled=True)
+        self.plugin.is_healthy = True
+        self.plugin._log = Mock()
+        self.inputs = {
+            "username": self.plugin.config.account.username,
+            "password": "synthetic-not-for-reporting",
+            "expected_start_date": "2026-09-01",
+            "expected_end_date": "2026-10-31",
+        }
+        self.task = SimpleNamespace(task_ref=991, book_allowed=True, instance=self.plugin)
+        self.booker = OrderBookerGCO.__new__(OrderBookerGCO)
+        self.booker.m_lock = threading.RLock()
+        self.booker.m_tasks = [self.task]
+        self.booker.m_task_data_cache = {"991": {
+            "status": "processing", "order_id": "SYNTHETIC-ORDER", "user_inputs": self.inputs,
+        }}
+        self.booker.m_tracker_key = "synthetic-tracker"
+        self.booker.redis_client = Mock()
+        self.booker._log = Mock()
+        self.booker._cleanup_task = Mock()
+        self.booker._on_task_removed = Mock()
+        self.cloud = Mock()
+        self.queue = []
+        self.executor = Mock()
+        self.executor.enqueue.side_effect = self.queue.append
+        self.enterContext(patch.dict(
+            self.booker._execute_book_job.__func__.__globals__,
+            VSCloudApi=SimpleNamespace(Instance=lambda: self.cloud),
+            ThreadPool=SimpleNamespace(getInstance=lambda: self.executor),
+        ))
+        self.enterContext(flow.browser_navigation(self.page))
+
+    def run_booker(self):
+        self.booker._execute_book_job(self.task, self.trigger)
+
+    def drain_reports(self):
+        while self.queue:
+            self.queue.pop(0)()
+
+    def test_explicit_site_success_uses_shared_success_reporting(self):
+        self.run_booker()
+        self.assertEqual(self.page.final_count, 1)
+        self.assertEqual(self.booker.m_tasks, [])
+        self.booker._cleanup_task.assert_called_once_with(self.task, "booking success")
+        self.assertEqual(len(self.queue), 1)
+        self.drain_reports()
+        task_id, payload = self.cloud.update_vas_task.call_args.args
+        self.assertEqual(task_id, "991")
+        self.assertEqual(payload["status"], "grabbed")
+        history = payload["grabbed_history"]
+        self.assertEqual(history["urn"], "")
+        self.assertEqual(history["account"], self.inputs["username"].lower())
+        self.assertEqual(history["slot_date"], "2026-10-13")
+        self.assertEqual(history["slot_time"], "10:05 - 11:05")
+        self.assertNotIn(self.inputs["password"], json.dumps(payload))
+
+    def test_site_rejection_stays_in_shared_retry_on_next_signal_branch(self):
+        self.page.response_error = "Synthetic slot no longer available"
+        self.run_booker()
+        self.assertEqual(self.page.final_count, 1)
+        self.assertEqual(self.booker.m_tasks, [self.task])
+        self.assertTrue(self.task.book_allowed)
+        self.assertIsNone(self.plugin._prepared_calendar)
+        self.cloud.update_vas_task.assert_not_called()
+        self.executor.enqueue.assert_not_called()
+
+    def test_later_signal_can_retry_after_fresh_calendar_preparation(self):
+        self.page.response_error = "Synthetic rejection"
+        self.run_booker()
+        self.plugin._record_calendar_prepared_route(self.route, role="book")
+        self.page.response_error = ""
+        self.run_booker()
+        self.assertEqual(self.page.final_count, 2)
+        self.assertEqual(self.booker.m_tasks, [])
+        self.assertTrue(any("Will retry on next signal" in str(call) for call in self.booker._log.call_args_list))
+
+    def test_unmatched_post_is_failure_not_pause(self):
+        self.page.wrong_request_day = True
+        self.run_booker()
+        self.assertEqual(self.page.final_count, 1)
+        self.assertEqual(self.booker.m_tasks, [self.task])
+        self.assertTrue(self.task.book_allowed)
+        self.cloud.update_vas_task.assert_not_called()
+
+    def test_prefinal_mode_never_calls_final_or_reports_success(self):
+        self.plugin.free_config["final_submit_enabled"] = False
+        self.run_booker()
+        self.assertEqual(self.page.final_count, 0)
+        self.assertEqual(self.booker.m_tasks, [self.task])
+        self.executor.enqueue.assert_not_called()
+        self.cloud.update_vas_task.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 230 - 0
test/ita/test_ita_booking_final.py

@@ -0,0 +1,230 @@
+"""Offline contracts for the thin Italy final-submit adapter."""
+
+import json
+import unittest
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+from plugins import ita_plugin as final
+from plugins.ita_plugin import (
+    FINAL_ACCEPTED_LABEL,
+    FINAL_FAILED_LABEL,
+    FINAL_PATH,
+    NATIVE_FINAL_SCRIPT,
+    _final_packet_accepted,
+    _submit_final_once,
+)
+from test.ita.test_ita_calendar_book import FakePage, SERVICE, select
+from test.ita import test_ita_calendar_book_flow as flow
+
+
+def target():
+    """Small synthetic target retained for debug-tool fixtures."""
+    page = FakePage()
+    approval = select(page)
+    return SimpleNamespace(
+        applicant="applicant@example.test",
+        tab_id="applicant-tab",
+        routing_key="slot.fixture.it.tourist",
+        runtime_service=SERVICE,
+        approval=approval,
+    )
+
+
+def final_packet(booking_target=None, *, error="", destination="/Reservation"):
+    booking_target = booking_target or target()
+    slot = booking_target.approval.candidate
+    return SimpleNamespace(
+        url="https://prenotami.esteri.it" + FINAL_PATH,
+        method="POST",
+        tab_id=booking_target.tab_id,
+        is_failed=False,
+        request=SimpleNamespace(postData={
+            "idCalendarioGiornaliero": slot.daily_calendar_id,
+            "selectedDay": slot.day.isoformat(),
+            "selectedHour": f"{slot.time_label}\n({slot.slots_free})",
+        }),
+        response=SimpleNamespace(
+            status=200,
+            url="https://prenotami.esteri.it" + FINAL_PATH,
+            raw_body=json.dumps({"errorMessage": error, "url": destination}),
+        ),
+    )
+
+
+class Listener:
+    def __init__(self, page):
+        self.page = page
+        self.packet = None
+        self.started = self.stopped = 0
+
+    def start(self, target_path, method):
+        self.started += 1
+        if target_path != FINAL_PATH or method != "POST":
+            raise AssertionError("unexpected listener contract")
+
+    def wait(self, timeout):
+        return self.packet
+
+    def stop(self):
+        self.stopped += 1
+
+
+class NativePage(FakePage):
+    def __init__(self, booking_target=None):
+        super().__init__()
+        booking_target = booking_target or target()
+        self.tab_id = booking_target.tab_id
+        self.active = True
+        self.final_clicks = 0
+        self.final_packet = final_packet(booking_target)
+        self.listen = Listener(self)
+
+    def run_js(self, script, *args):
+        if script == NATIVE_FINAL_SCRIPT:
+            self.final_clicks += 1
+            self.listen.packet = self.final_packet
+            return {"clicked": True}
+        return super().run_js(script, *args)
+
+
+class PacketAcceptanceTests(unittest.TestCase):
+    def setUp(self):
+        self.target = target()
+        self.packet = final_packet(self.target)
+
+    def accepted(self):
+        return _final_packet_accepted(
+            self.packet, self.target.approval, self.target.tab_id)
+
+    def test_exact_native_post_and_explicit_site_success_are_accepted(self):
+        self.assertTrue(self.accepted())
+        self.packet.request.postData = (
+            "idCalendarioGiornaliero=80001001&"
+            "selectedDay=2026-10-13&selectedHour=10%3A05+-+11%3A05%0A%281%29"
+        )
+        self.assertTrue(self.accepted())
+
+    def test_site_error_is_an_ordinary_rejection(self):
+        self.packet.response.raw_body = json.dumps(
+            {"errorMessage": "slot unavailable", "url": "/BookingCalendar"})
+        self.assertFalse(self.accepted())
+
+    def test_request_identity_must_match_current_selection(self):
+        mutations = (
+            ("url", "https://prenotami.esteri.it/Other"),
+            ("method", "GET"),
+            ("tab_id", "other-tab"),
+            ("is_failed", True),
+        )
+        for field, value in mutations:
+            with self.subTest(field=field):
+                packet = final_packet(self.target)
+                setattr(packet, field, value)
+                self.assertFalse(_final_packet_accepted(
+                    packet, self.target.approval, self.target.tab_id))
+
+    def test_body_requires_exact_unique_fields_and_current_runtime_id(self):
+        bodies = (
+            {},
+            {"idCalendarioGiornaliero": "80001001", "selectedDay": "2026-10-13"},
+            {"idCalendarioGiornaliero": "wrong", "selectedDay": "2026-10-13",
+             "selectedHour": "10:05 - 11:05\n(1)"},
+            "idCalendarioGiornaliero=80001001&idCalendarioGiornaliero=80001001&"
+            "selectedDay=2026-10-13&selectedHour=10%3A05+-+11%3A05%0A%281%29",
+        )
+        for body in bodies:
+            with self.subTest(body=body):
+                packet = final_packet(self.target)
+                packet.request.postData = body
+                self.assertFalse(_final_packet_accepted(
+                    packet, self.target.approval, self.target.tab_id))
+
+    def test_response_must_be_bounded_same_origin_explicit_json_success(self):
+        values = (
+            (500, '{"errorMessage":"","url":"/Reservation"}'),
+            (200, "not-json"),
+            (200, '{"url":"/Reservation"}'),
+            (200, '{"errorMessage":null,"url":"/Reservation"}'),
+            (200, '{"errorMessage":"","url":"https://attacker.test"}'),
+        )
+        for status, raw in values:
+            with self.subTest(status=status, raw=raw):
+                packet = final_packet(self.target)
+                packet.response.status = status
+                packet.response.raw_body = raw
+                self.assertFalse(_final_packet_accepted(
+                    packet, self.target.approval, self.target.tab_id))
+
+
+class SubmitOnceTests(unittest.TestCase):
+    def setUp(self):
+        bootstrap = target()
+        self.page = NativePage(bootstrap)
+        self.plugin, self.route, _ = flow.prepared_plugin(
+            self.page, routing_key=bootstrap.routing_key)
+        self.plugin._log = Mock()
+        self.approval = bootstrap.approval
+
+    def test_success_uses_one_native_click_and_standard_result(self):
+        result = _submit_final_once(self.plugin, self.route, self.approval)
+        self.assertTrue(result.success)
+        self.assertEqual(result.label, FINAL_ACCEPTED_LABEL)
+        self.assertEqual(result.account, "applicant@example.test")
+        self.assertEqual(result.book_date, "2026-10-13")
+        self.assertEqual(result.book_time, "10:05 - 11:05")
+        self.assertEqual(self.page.final_clicks, 1)
+        self.assertEqual((self.page.listen.started, self.page.listen.stopped), (1, 1))
+        self.assertIsNotNone(self.plugin._prepared_calendar)
+
+    def test_site_rejection_returns_false_and_discards_attempt_context(self):
+        self.page.final_packet.response.raw_body = json.dumps(
+            {"errorMessage": "slot unavailable", "url": "/BookingCalendar"})
+        result = _submit_final_once(self.plugin, self.route, self.approval)
+        self.assertFalse(result.success)
+        self.assertEqual(result.label, FINAL_FAILED_LABEL)
+        self.assertEqual(self.page.final_clicks, 1)
+        self.assertIsNone(self.plugin._prepared_calendar)
+
+    def test_timeout_or_mismatched_packet_is_false_not_unknown_pause(self):
+        for mode in ("timeout", "wrong-day"):
+            with self.subTest(mode=mode):
+                self.setUp()
+                if mode == "timeout":
+                    self.page.final_packet = None
+                else:
+                    self.page.final_packet.request.postData["selectedDay"] = "2026-10-14"
+                result = _submit_final_once(self.plugin, self.route, self.approval)
+                self.assertFalse(result.success)
+                self.assertEqual(self.page.final_clicks, 1)
+                self.assertIsNone(self.plugin._prepared_calendar)
+
+    def test_changed_applicant_or_selection_never_clicks(self):
+        self.plugin.config.account.username = "other@example.test"
+        result = _submit_final_once(self.plugin, self.route, self.approval)
+        self.assertFalse(result.success)
+        self.assertEqual(self.page.final_clicks, 0)
+        self.assertIsNone(self.plugin._prepared_calendar)
+
+    def test_second_call_without_fresh_preparation_never_clicks_again(self):
+        self.page.final_packet = None
+        self.assertFalse(_submit_final_once(self.plugin, self.route, self.approval).success)
+        self.assertFalse(_submit_final_once(self.plugin, self.route, self.approval).success)
+        self.assertEqual(self.page.final_clicks, 1)
+
+
+class SourceContractTests(unittest.TestCase):
+    def test_old_unknown_and_receipt_state_machine_is_not_in_runtime(self):
+        for name in (
+            "FinalOutcomeUnknown", "FinalBookingAttempt", "NativeFinalSubmitter",
+            "SubmissionSignal", "ReservationSnapshot", "ReservationState",
+        ):
+            self.assertFalse(hasattr(final, name), name)
+
+    def test_query_and_selection_do_not_call_final_adapter(self):
+        self.assertNotIn("coordinate:ita-native-final-once", final.CALENDAR_GUARD_SCRIPT)
+        self.assertIn("coordinate:ita-native-final-once", NATIVE_FINAL_SCRIPT)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 614 - 0
test/ita/test_ita_calendar_book.py

@@ -0,0 +1,614 @@
+import ast
+import json
+import shutil
+import subprocess
+import traceback
+import unittest
+from datetime import date, datetime
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+from plugins import ita_plugin as book_calendar
+
+from plugins.ita_plugin import (
+    RUNTIME_SERVICE_SCRIPT,
+    SLOT_SELECTION_SCRIPT,
+    TIME_SLOTS_PATH,
+    CalendarBookError,
+    parse_book_time_slots,
+    select_slot_before_final,
+)
+from plugins.ita_plugin import AVAILABILITY_PATH, CALENDAR_GUARD_SCRIPT
+from test.ita.test_ita_protocol import availability_item, double_json, slot_item
+
+
+DAY = date(2026, 10, 13)
+SERVICE = "7002"
+DAILY_ID = 80001001
+
+
+def packet(path, body, items):
+    return SimpleNamespace(
+        url="https://prenotami.esteri.it" + path,
+        method="POST",
+        request=SimpleNamespace(postData=body),
+        response=SimpleNamespace(status=200, raw_body=double_json(items)),
+    )
+
+
+def packets(*, free=1, remaining=0):
+    availability = packet(
+        AVAILABILITY_PATH,
+        {"_Servizio": "month-runtime-key", "selectedDay": "01/10/2026"},
+        [availability_item("13/10/2026 00:00:00", free, remaining)],
+    )
+    times = packet(
+        TIME_SLOTS_PATH,
+        {"selectedDay": DAY.isoformat(), "idService": SERVICE},
+        [slot_item("13/10/2026 00:00:00", (10, 5), (11, 5), free, remaining, DAILY_ID)],
+    )
+    return availability, times
+
+
+class FakePage:
+    def __init__(self):
+        self.url = "https://prenotami.esteri.it/BookingCalendar"
+        self.service = SERVICE
+        self.context_count = 1
+        self.active = False
+        self.events = []
+        self.overrides = {}
+        self.after_overrides = {}
+        self.click_ack = True
+        self.browser_error = None
+        self.guard_final_count = 0
+        self.last_candidate = None
+
+    @property
+    def clicks(self):
+        return self.events.count("slot-click")
+
+    def run_js(self, script, *args):
+        if self.browser_error:
+            raise RuntimeError(self.browser_error)
+        if script == RUNTIME_SERVICE_SCRIPT:
+            return {"path": "/BookingCalendar", "count": self.context_count, "value": self.service}
+        if script == CALENDAR_GUARD_SCRIPT:
+            self.events.append("guard")
+            return {
+                "path": "/BookingCalendar", "calendarFunctionPresent": True,
+                "finalButtonCount": 1, "allFinalButtonsGuarded": True,
+                "finalRequestCount": self.guard_final_count,
+            }
+        if script != SLOT_SELECTION_SCRIPT:
+            raise AssertionError("Unknown browser action")
+        service, day, daily_id, label, capacity, click = args
+        self.last_candidate = (daily_id, label, capacity)
+        if click and self.click_ack:
+            self.events.append("slot-click")
+            self.active = True
+        raw = {
+            "contextReady": service == self.service,
+            "candidateCount": 1,
+            "candidateReady": True,
+            "selected": self.active,
+            "clicked": click and self.click_ack,
+        }
+        raw.update(self.overrides)
+        if self.clicks:
+            raw.update(self.after_overrides)
+        return raw
+
+
+def select(page, pair=None):
+    availability, times = pair or packets()
+    service = SERVICE  # The caller's service binding at inventory capture time.
+    return select_slot_before_final(
+        page, target_day=DAY, runtime_service=service,
+        probe=book_calendar.parse_availability_packet(availability),
+        slots=book_calendar.parse_book_time_slots(times, target_day=DAY, runtime_service_id=service),
+    )
+
+
+class PrecommitReadbackTests(unittest.TestCase):
+    """Migrate the old pure-state checks to the actual read-only browser boundary."""
+
+    def setUp(self):
+        self.page = FakePage()
+        self.page.active = True
+        self.day = book_calendar.parse_calendar_availability(
+            double_json([availability_item("09/10/2026 00:00:00", 1, 0)])
+        )[0]
+        self.negative_candidate, self.candidate = book_calendar.parse_time_slots(double_json([
+            slot_item("09/10/2026 00:00:00", (9, 15), (10, 0), 0, -1, 301),
+            slot_item("09/10/2026 00:00:00", (10, 5), (11, 5), 1, 0, 302),
+        ]))
+
+    def readback(self, *, calendar_day=None, candidate=None):
+        approval = book_calendar.PrecommitApproval(calendar_day or self.day, candidate or self.candidate)
+        return book_calendar.verify_precommit_selection(
+            self.page, runtime_service=SERVICE, approval=approval,
+        )
+
+    def reject(self, **kwargs):
+        with self.assertRaises(CalendarBookError):
+            self.readback(**kwargs)
+        self.assertEqual(self.page.clicks, 0)
+
+    def test_e44_positive_selection_approves_precommit(self):
+        approval = self.readback()
+        self.assertIs(approval.calendar_day, self.day)
+        self.assertIs(approval.candidate, self.candidate)
+        self.assertNotIn(self.candidate.daily_calendar_id, repr(approval))
+        self.assertEqual(self.page.clicks, 0)
+
+    def test_readback_rejects_wrong_types_and_extra_fields(self):
+        for mutation in (
+            {"candidateCount": True}, {"candidateCount": 1.0},
+            {"contextReady": 1}, {"candidateReady": 1}, {"selected": 1},
+            {"clicked": 0}, {"extra": "unexpected"},
+        ):
+            with self.subTest(mutation=mutation):
+                self.page.overrides = mutation
+                self.reject()
+
+    def test_rejects_every_unsafe_control_semantic(self):
+        for mutation in (
+            {"contextReady": False}, {"candidateCount": 0}, {"candidateCount": 2},
+            {"candidateReady": False}, {"selected": False}, {"clicked": True},
+        ):
+            with self.subTest(mutation=mutation):
+                self.page.overrides = mutation
+                self.reject()
+
+    def test_rejects_negative_candidate_even_if_dom_marks_it_active(self):
+        self.reject(candidate=self.negative_candidate)
+
+    def test_rejects_negative_calendar_day(self):
+        negative = book_calendar.parse_calendar_availability(
+            double_json([availability_item("09/10/2026 00:00:00", 0, -1)])
+        )[0]
+        self.reject(calendar_day=negative)
+
+    def test_calendar_and_slot_must_belong_to_the_same_day(self):
+        other = book_calendar.parse_calendar_availability(
+            double_json([availability_item("10/10/2026 00:00:00", 1, 0)])
+        )[0]
+        self.reject(calendar_day=other)
+
+
+class CalendarServiceReadinessTests(unittest.TestCase):
+    def setUp(self):
+        self.page = FakePage()
+        self.page.tab_id = "book-tab"
+        self.now = 0.0
+        self.sleeps = []
+        self.sleep_hook = None
+        self.enterContext(patch.object(book_calendar.time, "monotonic", side_effect=lambda: self.now))
+        self.enterContext(patch.object(book_calendar.time, "sleep", side_effect=self.advance))
+
+    def advance(self, seconds):
+        self.sleeps.append(seconds)
+        self.now += seconds
+        if self.sleep_hook:
+            self.sleep_hook()
+
+    def wait(self, **kwargs):
+        options = {"session_is_current": lambda: True, "timeout": 0.25}
+        options.update(kwargs)
+        return book_calendar.wait_for_calendar_service(self.page, **options)
+
+    def test_ready_returns_immediately_without_network_or_clicks(self):
+        self.assertEqual(self.wait(), SERVICE)
+        self.assertEqual(self.sleeps, [])
+        self.assertEqual(self.page.events, ["guard"])
+
+    def test_empty_then_ready_uses_actual_value_without_full_delay(self):
+        self.page.service = ""
+        self.sleep_hook = lambda: setattr(self.page, "service", "synthetic-runtime-key")
+        self.assertEqual(self.wait(), "synthetic-runtime-key")
+        self.assertEqual(self.sleeps, [0.1])
+        self.assertEqual(self.page.clicks, 0)
+
+    def test_empty_timeout_is_bounded_and_does_not_supply_a_default_id(self):
+        self.page.service = ""
+        with self.assertRaises(book_calendar.CalendarServiceNotReadyError):
+            self.wait()
+        self.assertAlmostEqual(sum(self.sleeps), 0.25)
+        self.assertEqual(self.page.service, "")
+        self.assertEqual(self.page.clicks, 0)
+
+    def test_stable_phase_strict_read_does_not_wait(self):
+        self.page.service = ""
+        with self.assertRaises(CalendarBookError):
+            book_calendar.read_calendar_service(self.page)
+        self.assertEqual(self.sleeps, [])
+
+    def test_zero_budget_accepts_ready_but_rejects_empty_without_sleep(self):
+        self.assertEqual(self.wait(timeout=0), SERVICE)
+        self.page.service = ""
+        with self.assertRaises(book_calendar.CalendarServiceNotReadyError):
+            self.wait(timeout=0)
+        self.assertEqual(self.sleeps, [])
+
+    def test_invalid_structure_or_value_is_not_treated_as_pending(self):
+        for attribute, value in (("context_count", 0), ("context_count", 2),
+                                 ("context_count", True), ("service", None),
+                                 ("service", 4937), ("service", " "),
+                                 ("service", "x" * 129)):
+            with self.subTest(attribute=attribute, value_type=type(value).__name__):
+                original = getattr(self.page, attribute)
+                setattr(self.page, attribute, value)
+                with self.assertRaises(CalendarBookError) as caught:
+                    self.wait()
+                self.assertNotIsInstance(caught.exception, book_calendar.CalendarServiceNotReadyError)
+                self.assertEqual(self.sleeps, [])
+                setattr(self.page, attribute, original)
+
+    def test_service_change_after_refresh_is_not_accepted(self):
+        self.page.service = ""
+        self.sleep_hook = lambda: setattr(self.page, "service", "other-service")
+        with self.assertRaisesRegex(CalendarBookError, "runtime service changed"):
+            self.wait(expected_service=SERVICE)
+
+    def test_tab_or_path_drift_during_wait_stops(self):
+        for attribute, value in (("tab_id", "other-tab"), ("url", "https://prenotami.esteri.it/UserArea")):
+            with self.subTest(attribute=attribute):
+                original = getattr(self.page, attribute)
+                self.page.service = ""
+                self.sleep_hook = lambda: setattr(self.page, attribute, value)
+                with self.assertRaises(CalendarBookError):
+                    self.wait()
+                setattr(self.page, attribute, original)
+
+    def test_session_change_during_dom_read_is_checked_before_accepting_value(self):
+        checks = iter([True, False])
+        with self.assertRaisesRegex(CalendarBookError, "Session changed"):
+            self.wait(session_is_current=lambda: next(checks))
+        self.assertEqual(self.sleeps, [])
+
+    def test_guard_violation_and_transport_failure_are_not_retried(self):
+        self.page.guard_final_count = 1
+        with self.assertRaises(book_calendar.CalendarGateError):
+            self.wait()
+        self.page.guard_final_count = 0
+        self.page.browser_error = "browser offline"
+        with self.assertRaises(RuntimeError):
+            self.wait()
+        self.assertEqual(self.sleeps, [])
+
+    def test_invalid_wait_contract_is_rejected(self):
+        for timeout in (-1, True, "1", float("inf"), float("nan")):
+            with self.subTest(timeout=timeout), self.assertRaises(CalendarBookError):
+                self.wait(timeout=timeout)
+        with self.assertRaises(CalendarBookError):
+            self.wait(session_is_current=None)
+        self.assertEqual(self.page.events, [])
+
+
+class BookPacketTests(unittest.TestCase):
+    def test_positive_one_zero_uses_current_runtime_service(self):
+        _, times = packets()
+        result = parse_book_time_slots(times, target_day=DAY, runtime_service_id=SERVICE)
+        self.assertEqual(len(result), 1)
+        self.assertTrue(result[0].is_available)
+        self.assertNotIn(str(DAILY_ID), repr(result))
+
+    def test_accepts_json_request_and_day_month_year_date(self):
+        _, times = packets()
+        times.request.postData = json.dumps({"selectedDay": "13/10/2026", "idService": int(SERVICE)})
+        self.assertEqual(len(parse_book_time_slots(times, target_day=DAY, runtime_service_id=SERVICE)), 1)
+
+    def test_rejects_wrong_metadata_without_disclosing_packet(self):
+        mutations = [
+            lambda p: setattr(p, "url", "https://other.example.test" + TIME_SLOTS_PATH),
+            lambda p: setattr(p, "url", "https://prenotami.esteri.it/BookingCalendar/Other"),
+            lambda p: setattr(p, "method", "GET"),
+            lambda p: setattr(p.response, "status", 302),
+            lambda p: setattr(p.response, "status", True),
+            lambda p: p.request.postData.update(idService="4937"),
+            lambda p: p.request.postData.update(idService=True),
+            lambda p: p.request.postData.update(idService=None),
+            lambda p: p.request.postData.update(selectedDay="2026-10-14"),
+            lambda p: p.request.postData.update(selectedDay="2026-10-13-unverified"),
+            lambda p: p.request.postData.update(unexpected="secret-body-marker"),
+            lambda p: setattr(p.request, "postData", "secret-body-marker"),
+            lambda p: setattr(p.response, "raw_body", "secret-body-marker"),
+            lambda p: setattr(p.response, "raw_body", json.dumps([])),
+        ]
+        for mutate in mutations:
+            with self.subTest(mutation=mutations.index(mutate)):
+                _, times = packets()
+                mutate(times)
+                try:
+                    parse_book_time_slots(times, target_day=DAY, runtime_service_id=SERVICE)
+                except CalendarBookError:
+                    self.assertNotIn("secret-body-marker", traceback.format_exc())
+                else:
+                    self.fail("Invalid packet was accepted")
+
+    def test_rejects_wrong_response_day_before_capacity_filtering(self):
+        _, times = packets()
+        times.response.raw_body = double_json([
+            slot_item("14/10/2026 00:00:00", (10, 5), (11, 5), 0, -1, DAILY_ID),
+        ])
+        with self.assertRaisesRegex(CalendarBookError, "another day"):
+            parse_book_time_slots(times, target_day=DAY, runtime_service_id=SERVICE)
+
+    def test_capacity_conflict_is_not_no_availability(self):
+        _, times = packets(free=1, remaining=-1)
+        with self.assertRaises(CalendarBookError):
+            parse_book_time_slots(times, target_day=DAY, runtime_service_id=SERVICE)
+
+
+class BookSelectionTests(unittest.TestCase):
+    def test_selects_once_and_returns_only_precommit_approval(self):
+        page = FakePage()
+        result = select(page)
+        self.assertEqual(result.candidate.day, DAY)
+        self.assertEqual(result.candidate.time_label, "10:05 - 11:05")
+        self.assertFalse(hasattr(result, "success"))
+        self.assertNotIn(str(DAILY_ID), repr(result))
+        self.assertEqual(page.events, ["guard", "slot-click", "guard"])
+
+    def test_repeated_selection_does_not_repeat_native_click(self):
+        page = FakePage()
+        select(page)
+        select(page)
+        self.assertEqual(page.clicks, 1)
+
+    def test_no_slots_returns_none_and_never_clicks(self):
+        page = FakePage()
+        self.assertIsNone(select(page, packets(free=0, remaining=-1)))
+        self.assertEqual(page.events, ["guard", "guard"])
+
+    def test_slots_disappearing_after_positive_day_is_safe_none(self):
+        page = FakePage()
+        availability, _ = packets()
+        _, times = packets(free=0, remaining=-1)
+        self.assertIsNone(select(page, (availability, times)))
+        self.assertEqual(page.clicks, 0)
+
+    def test_positive_slots_with_negative_day_is_conflict(self):
+        page = FakePage()
+        availability, _ = packets(free=0, remaining=-1)
+        _, times = packets()
+        with self.assertRaisesRegex(CalendarBookError, "disagree"):
+            select(page, (availability, times))
+        self.assertEqual(page.clicks, 0)
+
+    def test_uses_earliest_time_even_if_later_slots_have_more_capacity(self):
+        page = FakePage()
+        availability, times = packets(free=8, remaining=7)
+        times.response.raw_body = double_json([
+            slot_item("13/10/2026 00:00:00", (9, 0), (10, 0), 1, 0, 80001002),
+            slot_item("13/10/2026 00:00:00", (12, 0), (13, 0), 4, 3, 80001003),
+            slot_item("13/10/2026 00:00:00", (10, 0), (11, 0), 4, 3, 80001004),
+        ])
+        result = select(page, (availability, times))
+        self.assertEqual(result.candidate.time_label, "09:00 - 10:00")
+        self.assertEqual(page.last_candidate, ("80001002", "09:00 - 10:00", 1))
+
+    def test_rejects_bad_context_before_any_click(self):
+        for field, value in (("url", "https://other.example.test/BookingCalendar"),
+                             ("url", "https://prenotami.esteri.it/UserArea"),
+                             ("context_count", 2), ("context_count", True),
+                             ("service", ""), ("service", None)):
+            with self.subTest(field=field, value=value):
+                page = FakePage()
+                setattr(page, field, value)
+                with self.assertRaises(CalendarBookError):
+                    select(page)
+                self.assertEqual(page.clicks, 0)
+
+    def test_rejects_wrong_availability_month(self):
+        page = FakePage()
+        availability, times = packets()
+        availability.request.postData["selectedDay"] = "01/11/2026"
+        availability.response.raw_body = double_json([])
+        with self.assertRaisesRegex(CalendarBookError, "another month"):
+            select(page, (availability, times))
+        self.assertEqual(page.clicks, 0)
+
+    def test_preclick_invariants_reject_without_clicking(self):
+        mutations = [
+            {"contextReady": False}, {"candidateCount": 2},
+            {"candidateReady": False}, {"clicked": True},
+            {"candidateCount": True}, {"candidateReady": 1},
+            {"extra": "unexpected"},
+        ]
+        for changes in mutations:
+            with self.subTest(changes=changes):
+                page = FakePage()
+                page.overrides = changes
+                with self.assertRaises(CalendarBookError):
+                    select(page)
+                self.assertEqual(page.clicks, 0)
+                self.assertEqual(page.events[-1], "guard")
+
+    def test_failed_click_is_not_retried(self):
+        page = FakePage()
+        page.click_ack = False
+        with self.assertRaisesRegex(CalendarBookError, "acknowledged"):
+            select(page)
+        self.assertEqual(page.clicks, 0)
+
+    def test_postclick_drift_is_rejected_and_not_retried(self):
+        mutations = [
+            {"contextReady": False}, {"candidateCount": 2},
+            {"candidateReady": False}, {"selected": False},
+        ]
+        for changes in mutations:
+            with self.subTest(changes=changes):
+                page = FakePage()
+                page.after_overrides = changes
+                with self.assertRaises(CalendarBookError):
+                    select(page)
+                self.assertEqual(page.clicks, 1)
+                self.assertEqual(page.events[-1], "guard")
+
+    def test_observed_final_request_is_never_accepted(self):
+        page = FakePage()
+        page.guard_final_count = 1
+        with self.assertRaises(CalendarBookError):
+            select(page)
+        self.assertEqual(page.clicks, 0)
+
+    def test_browser_exception_does_not_leak_content(self):
+        page = FakePage()
+        page.browser_error = "secret-browser-body-marker"
+        try:
+            select(page)
+        except CalendarBookError:
+            self.assertNotIn("secret-browser-body-marker", traceback.format_exc())
+        else:
+            self.fail("Browser failure was accepted")
+
+    def test_requires_date_not_datetime_or_string(self):
+        for target in (DAY.isoformat(), datetime(2026, 10, 13), None):
+            with self.subTest(target=target):
+                page = FakePage()
+                with self.assertRaises(CalendarBookError):
+                    select_slot_before_final(page, target_day=target, probe=None, slots=(), runtime_service=SERVICE)
+                self.assertEqual(page.events, [])
+
+    def test_adapter_has_no_query_tool_network_or_final_action(self):
+        from test.ita.ita_source_sections import section
+        source = section("calendar_book")
+        module = ast.parse(source)
+        imports = [node.module or "" for node in ast.walk(module) if isinstance(node, ast.ImportFrom)]
+        self.assertFalse(any(name.startswith("tools") or name == "plugins.ita_plugin" for name in imports))
+        for token in ("GenerateOTP", "btnAvanti", "InsertNewBooking", "fetch(", "XMLHttpRequest", ".submit("):
+            self.assertNotIn(token, source)
+        self.assertEqual(SLOT_SELECTION_SCRIPT.count("candidate.click()"), 1)
+
+
+JS_HARNESS = r"""
+const vm = require('node:vm');
+const payload = JSON.parse(require('node:fs').readFileSync(0, 'utf8'));
+const mode = payload.mode;
+const day = '2026-10-13';
+let slotClicks = 0, finalClicks = 0;
+function element(classes = [], extras = {}) {
+  const set = new Set(classes);
+  return Object.assign({
+    dataset: {}, isConnected: true, children: [], style: {},
+    classList: {contains: (c) => set.has(c), add: (c) => set.add(c), remove: (c) => set.delete(c)},
+    hasAttribute: () => false, getAttribute: () => null,
+    getBoundingClientRect: () => ({left: 20, right: 200, top: 20, bottom: 100}),
+    contains(other) {return other === this || this.children.some((c) => c.contains(other));},
+  }, extras);
+}
+const timeline = element(['input-async-abilitato', 'selected'], {dataset: {date: day}});
+const content = element(['selected'], {dataset: {date: day}});
+const input = element([], {type: 'hidden', id: 'idHiddenFasciaServizio', value: '80001001'});
+const spans = [element([], {textContent: '10:05 - 11:05'}), element([], {textContent: '(1)'})];
+const candidate = element([], {children: [input, ...spans]});
+const fields = [input];
+let red = false;
+candidate.querySelectorAll = (selector) => selector === 'input' ? fields : selector === 'span' ? spans : [];
+candidate.querySelector = (selector) => selector === '.dotRed' && red ? element(['dotRed']) : null;
+const slots = [candidate];
+content.children = slots;
+content.querySelectorAll = (selector) => selector === '.fascia' ? slots : [];
+const finalButton = element([], {disabled: true, dataset: {coordinateFinalGuard: 'enabled'}, click: () => finalClicks++});
+const service = {value: '7002'};
+let occluded = false;
+candidate.click = () => {
+  slotClicks++;
+  slots.forEach((slot) => slot.classList.remove('act'));
+  candidate.classList.add('act');
+  if (mode === 'drift') content.dataset.date = '2026-10-14';
+  if (mode === 'drift_origin') window.location.origin = 'https://other.example.test';
+};
+if (mode === 'already_active') candidate.classList.add('act');
+if (mode === 'negative') candidate.classList.add('notAvailableFascia');
+if (mode === 'red') red = true;
+if (mode === 'wrong_time') spans[0].textContent = '09:00 - 10:00';
+if (mode === 'wrong_capacity') spans[1].textContent = '(0)';
+if (mode === 'wrong_id') input.value = '80009999';
+if (mode === 'extra_input') fields.push(element([], {type: 'hidden', value: 'extra'}));
+if (mode === 'duplicate_slot') slots.push(candidate);
+if (mode === 'wrong_date') content.dataset.date = '2026-10-14';
+if (mode === 'wrong_service') service.value = '7003';
+if (mode === 'unguarded_final') finalButton.disabled = false;
+if (mode === 'hidden') candidate.style.display = 'none';
+if (mode === 'occluded') occluded = true;
+if (mode === 'disabled_day') timeline.classList.add('input-async-disabilitato');
+const document = {
+  querySelectorAll(selector) {
+    if (selector === '#idServizio') return [service];
+    if (selector === '#btnPrenotaNoOtp') return [finalButton];
+    if (selector === '.events a.selected') return [timeline];
+    if (selector === '.events-content li.selected') return [content];
+    if (selector === '.events a[data-date]') return [timeline];
+    if (selector === '.fascia.act') return slots.filter((slot) => slot.classList.contains('act'));
+    throw Error('Unexpected selector ' + selector);
+  },
+  querySelector(selector) {
+    if (selector === '.selected') return mode === 'foreign_selected_first' ? element(['selected']) : timeline;
+    throw Error('Unexpected selector ' + selector);
+  },
+  elementFromPoint: () => occluded ? element() : candidate,
+};
+const window = {
+  location: {origin: mode === 'wrong_origin' ? 'https://other.example.test' : 'https://prenotami.esteri.it', pathname: '/BookingCalendar'},
+  innerWidth: 1000, innerHeight: 800,
+  getComputedStyle: (item) => Object.assign({display: 'block', visibility: 'visible', pointerEvents: 'auto', opacity: '1'}, item.style),
+};
+const run = (click) => vm.runInNewContext('(function(){' + payload.source + '\n}).apply(null, args)',
+  {document, window, args: ['7002', day, '80001001', '10:05 - 11:05', 1, click]}, {timeout: 1000});
+const before = run(false), acted = run(true), after = run(false);
+process.stdout.write(JSON.stringify({before, acted, after, slotClicks, finalClicks}));
+"""
+
+
+@unittest.skipUnless(shutil.which("node"), "Node is required for offline JavaScript DOM-contract checks")
+class BookJavaScriptContractTests(unittest.TestCase):
+    def run_case(self, mode):
+        result = subprocess.run(
+            [shutil.which("node"), "-e", JS_HARNESS],
+            input=json.dumps({"source": SLOT_SELECTION_SCRIPT, "mode": mode}),
+            text=True, capture_output=True, timeout=10, check=True,
+        )
+        return json.loads(result.stdout)
+
+    def test_actual_script_clicks_only_positive_candidate(self):
+        result = self.run_case("positive")
+        self.assertTrue(result["before"]["candidateReady"])
+        self.assertEqual(result["slotClicks"], 1)
+        self.assertEqual(result["finalClicks"], 0)
+        self.assertTrue(result["after"]["selected"])
+
+    def test_actual_script_does_not_click_again_when_already_selected(self):
+        result = self.run_case("already_active")
+        self.assertEqual(result["slotClicks"], 0)
+        self.assertTrue(result["after"]["selected"])
+
+    def test_actual_script_rejects_unsafe_dom_before_click(self):
+        modes = ("negative", "red", "wrong_time", "wrong_capacity", "wrong_id", "extra_input",
+                 "duplicate_slot", "wrong_date", "wrong_service", "unguarded_final", "hidden",
+                 "occluded", "disabled_day", "foreign_selected_first", "wrong_origin")
+        for mode in modes:
+            with self.subTest(mode=mode):
+                result = self.run_case(mode)
+                self.assertEqual(result["slotClicks"], 0)
+                self.assertEqual(result["finalClicks"], 0)
+
+    def test_actual_script_readback_exposes_postclick_date_drift(self):
+        result = self.run_case("drift")
+        self.assertEqual(result["slotClicks"], 1)
+        self.assertFalse(result["after"]["contextReady"])
+        self.assertFalse(result["after"]["selected"])
+        self.assertEqual(result["finalClicks"], 0)
+
+    def test_actual_script_readback_exposes_postclick_origin_drift(self):
+        result = self.run_case("drift_origin")
+        self.assertEqual(result["slotClicks"], 1)
+        self.assertFalse(result["after"]["contextReady"])
+        self.assertEqual(result["finalClicks"], 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 949 - 0
test/ita/test_ita_calendar_book_flow.py

@@ -0,0 +1,949 @@
+import copy
+import json
+import shutil
+import subprocess
+import traceback
+import unittest
+from contextlib import contextmanager
+from datetime import date, datetime
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin as book_calendar
+from plugins.ita_plugin import (
+    DATE_SELECTION_SCRIPT, SLOT_SELECTION_SCRIPT, TIME_SLOTS_PATH,
+    CalendarBookError, book_date_preferences, recheck_calendar_before_final,
+)
+from plugins.ita_plugin import AVAILABILITY_PATH, CalendarNextMonthUnavailableError
+from plugins.ita_plugin import (
+    BOOKING_CALENDAR_PREFINAL_STOP_LABEL, BOOKING_RECHECK_NONE_AVAILABLE_LABEL, ItaPlugin,
+)
+from test.ita.test_ita_calendar_book import FakePage, SERVICE, packet
+from test.ita import test_ita_plugin as plugin_fixtures
+from test.ita.test_ita_protocol import availability_item, slot_item
+from vs_types import (
+    AppointmentType, BizLogicError, DateAvailability, RateLimiteddError,
+    SessionExpiredOrInvalidError, TimeSlot, VSAccount, VSPlgConfig, VSQueryResult,
+)
+
+
+def month(value, inventory, *, automatic_day=None, slots=None):
+    """Synthetic inventory only; IDs and accounts below never leave the tests."""
+    return {"month": value, "inventory": inventory, "automatic_day": automatic_day,
+            "slots": slots or {}}
+
+
+def positive_month():
+    return month("2026-10", {13: 1})
+
+
+class FakeListener:
+    def __init__(self, page):
+        self.page = page
+        self.queue = []
+        self.listening = False
+        self.starts = 0
+        self.stops = 0
+        self.target = None
+
+    def start(self, targets, method):
+        self.starts += 1
+        self.target = targets
+        self.queue.clear()  # Matches the installed Listener.start contract.
+        self.listening = True
+        self.page.events.append("listen-start")
+        if method != "POST":
+            raise AssertionError("Unexpected listener method")
+
+    def wait(self, timeout, raise_err=False):
+        if not self.listening:
+            raise AssertionError("Wait without listener")
+        if self.page.wait_hook:
+            self.page.wait_hook()
+        if not self.queue:
+            return False
+        result = self.queue.pop(0)
+        if result.url.endswith(TIME_SLOTS_PATH):
+            self.page.selected_day = getattr(result, "fixture_day", None)
+            self.page.content_day = self.page.render_day or self.page.selected_day
+            self.page.current_slots = getattr(result, "fixture_slots", [])
+            self.page.active = False
+        return result
+
+    def stop(self):
+        self.stops += 1
+        self.queue.clear()
+        self.listening = False
+        self.page.events.append("listen-stop")
+
+
+class FlowPage(FakePage):
+    def __init__(self, months=None, *, passes=None):
+        super().__init__()
+        self.tab_id = "book-tab"
+        self.listen = FakeListener(self)
+        self.wait = Mock()
+        self.quit = Mock()
+        self.passes = passes or [months or [positive_month()]]
+        self.refreshes = 0
+        self.month_index = 0
+        self.month_spec = self.passes[0][0]
+        self.selected_day = None
+        self.content_day = None
+        self.current_slots = []
+        self.date_clicks = []
+        self.month_clicks = 0
+        self.requests = []
+        self.request_mutator = None
+        self.wait_hook = None
+        self.render_day = None
+        self.reverse_responses = False
+        self.drop_automatic = False
+        self.duplicate_availability = False
+        self.date_ack = True
+        self.date_candidate_count = None
+        self.date_enabled = True
+        self.date_runtime_matches = True
+
+    def response_packet(self, path, body, items, day=None):
+        result = packet(path, body, items)
+        result.tab_id = self.tab_id
+        result.is_failed = False
+        result.fixture_day = day
+        result.fixture_slots = items
+        if self.request_mutator:
+            self.request_mutator(result)
+        self.requests.append(result)
+        return result
+
+    def times_packet(self, day):
+        number = int(day[-2:])
+        free = self.month_spec["slots"].get(number, self.month_spec["inventory"].get(number, 0))
+        day_value = date.fromisoformat(day)
+        items = [slot_item(day_value.strftime("%d/%m/%Y 00:00:00"), (10, 5), (11, 5),
+                           free, free - 1, 80000000 + self.refreshes * 100 + number)]
+        return self.response_packet(TIME_SLOTS_PATH, {"selectedDay": day, "idService": SERVICE}, items, day)
+
+    def load_month(self):
+        self.selected_day = self.content_day = None
+        value = self.month_spec["month"]
+        inventory = self.month_spec["inventory"]
+        items = [availability_item(date.fromisoformat(f"{value}-{day:02d}").strftime("%d/%m/%Y 00:00:00"),
+                                   free, free - 1) for day, free in inventory.items()]
+        availability = self.response_packet(
+            AVAILABILITY_PATH,
+            {"_Servizio": "calendar-runtime-key", "selectedDay": f"{value}-01"}, items,
+        )
+        responses = [availability]
+        if self.duplicate_availability:
+            responses.append(availability)
+        elif inventory and not self.drop_automatic:
+            auto = self.month_spec["automatic_day"] or min(inventory)
+            responses.append(self.times_packet(f"{value}-{auto:02d}"))
+        if self.reverse_responses:
+            responses.reverse()
+        self.listen.queue.extend(responses)
+
+    def refresh(self):
+        self.refreshes += 1
+        self.month_index = 0
+        self.month_spec = self.passes[min(self.refreshes - 1, len(self.passes) - 1)][0]
+        self.events.append("refresh")
+        self.load_month()
+
+    def next_month(self):
+        self.month_clicks += 1
+        self.month_index += 1
+        sequence = self.passes[min(self.refreshes - 1, len(self.passes) - 1)]
+        if self.month_index >= len(sequence):
+            raise CalendarNextMonthUnavailableError("No next month in fixture")
+        self.month_spec = sequence[self.month_index]
+        self.events.append("next-month")
+        self.load_month()
+
+    def run_js(self, script, *args):
+        if script == DATE_SELECTION_SCRIPT:
+            service, day, click = args
+            count = int(day[:7] == self.month_spec["month"] and int(day[-2:]) in self.month_spec["inventory"])
+            if self.date_candidate_count is not None:
+                count = self.date_candidate_count
+            selected = day == self.selected_day == self.content_day
+            context = self.date_runtime_matches and service == self.service
+            ready = context and count == 1 and self.date_enabled
+            clicked = bool(click and self.date_ack and ready and not selected)
+            raw = {"contextReady": context, "candidateCount": count,
+                   "candidateReady": ready, "selected": context and count == 1 and selected,
+                   "clicked": clicked}
+            if clicked:
+                self.date_clicks.append(day)
+                self.events.append("date-click")
+                self.listen.queue.append(self.times_packet(day))
+            return raw
+        raw = super().run_js(script, *args)
+        if script == SLOT_SELECTION_SCRIPT:
+            _, day, daily_id, label, free, _ = args
+            matching = [item for item in self.current_slots
+                        if str(item["IDCalendarioServizioGiornaliero"]) == daily_id]
+            raw["contextReady"] = raw["contextReady"] and day == self.selected_day == self.content_day
+            raw["candidateCount"] = len(matching)
+            raw["candidateReady"] = (raw["contextReady"] and len(matching) == 1
+                                     and matching[0]["SlotLiberi"] == free)
+            raw["selected"] = raw["candidateReady"] and self.active
+            raw.update(self.after_overrides if self.clicks else {})
+        return raw
+
+
+@contextmanager
+def browser_navigation(page):
+    original_click = book_calendar.click_next_month
+    # Query and Book now share this function's module. Only intercept the
+    # synthetic Book page; concurrent Query keeps its own native adapter.
+    with patch.object(book_calendar, "click_next_month", side_effect=lambda actual:
+                      page.next_month() if actual is page else original_click(actual)), \
+            patch.object(book_calendar.time, "sleep"):
+        yield
+
+
+def book_with_approval(plugin, trigger, inputs, *, call=None):
+    captured = []
+    original = book_calendar.recheck_calendar_before_final
+
+    def observe(*args, **kwargs):
+        approval = original(*args, **kwargs)
+        captured.append(approval)
+        return approval
+
+    with patch.object(book_calendar, "recheck_calendar_before_final", side_effect=observe):
+        result = (call or plugin.book)(trigger, inputs)
+    return result, captured[0] if captured else None
+
+
+def run_flow(page, **kwargs):
+    options = dict(lookahead_months=3, start_day=date(2026, 8, 1), end_day=date(2026, 12, 31),
+                   session_is_current=lambda: True, month_click_interval_seconds=0, dom_timeout=0)
+    options.update(kwargs)
+    with browser_navigation(page):
+        return recheck_calendar_before_final(page, **options)
+
+
+class BookCalendarFlowTests(unittest.TestCase):
+    def assert_stopped(self, page):
+        self.assertFalse(page.listen.listening)
+        self.assertEqual(page.listen.starts, page.listen.stops)
+
+    def test_refresh_waits_for_runtime_reassignment_without_repeating_refresh(self):
+        page = FlowPage()
+        original_run_js = page.run_js
+        pending_reads = []
+
+        def delayed(script, *args):
+            result = original_run_js(script, *args)
+            if script == book_calendar.RUNTIME_SERVICE_SCRIPT and page.refreshes:
+                pending_reads.append(True)
+                if len(pending_reads) == 1:
+                    return {**result, "value": ""}
+            return result
+
+        page.run_js = delayed
+        self.assertIsNotNone(run_flow(page, dom_timeout=1))
+        self.assertEqual(page.refreshes, 1)
+        self.assertEqual(page.clicks, 1)
+        self.assertEqual(len(page.requests), 2)
+        self.assert_stopped(page)
+
+    def test_empty_after_refresh_times_out_without_selecting_or_refreshing_again(self):
+        page = FlowPage()
+        original_refresh = page.refresh
+
+        def empty_refresh():
+            original_refresh()
+            page.service = ""
+
+        page.refresh = empty_refresh
+        with self.assertRaises(book_calendar.CalendarServiceNotReadyError):
+            run_flow(page)
+        self.assertEqual(page.refreshes, 1)
+        self.assertEqual(page.clicks, 0)
+        self.assert_stopped(page)
+
+    def test_automatic_positive_day_uses_fresh_response_without_date_click(self):
+        page = FlowPage()
+        result = run_flow(page)
+        self.assertEqual(result.candidate.day, date(2026, 10, 13))
+        self.assertEqual(result.candidate.daily_calendar_id, "80000113")
+        self.assertEqual(page.refreshes, 1)
+        self.assertEqual(page.date_clicks, [])
+        self.assertEqual(page.clicks, 1)
+        self.assertEqual(len(page.requests), 2)
+        self.assert_stopped(page)
+
+    def test_native_date_click_is_followed_by_current_time_slots(self):
+        page = FlowPage([month("2026-10", {1: 0, 13: 1})])
+        result = run_flow(page)
+        self.assertEqual(result.candidate.day, date(2026, 10, 13))
+        self.assertEqual(page.date_clicks, ["2026-10-13"])
+        self.assertEqual(page.listen.starts, 2)
+        self.assertEqual(len(page.requests), 3)
+        self.assert_stopped(page)
+
+    def test_each_captured_inventory_response_is_parsed_once(self):
+        for inventory in ({13: 1}, {1: 0, 13: 1}):
+            with self.subTest(inventory=inventory):
+                page = FlowPage([month("2026-10", inventory)])
+                with patch.object(book_calendar, "parse_availability_packet",
+                                  wraps=book_calendar.parse_availability_packet) as availability_parser, \
+                        patch.object(book_calendar, "parse_book_time_slots",
+                                     wraps=book_calendar.parse_book_time_slots) as slots_parser:
+                    self.assertIsNotNone(run_flow(page))
+                self.assertEqual(availability_parser.call_count,
+                                 sum(p.url.endswith(AVAILABILITY_PATH) for p in page.requests))
+                self.assertEqual(slots_parser.call_count,
+                                 sum(p.url.endswith(TIME_SLOTS_PATH) for p in page.requests))
+                self.assertEqual(page.clicks, 1)
+                self.assert_stopped(page)
+
+    def test_candidate_is_filtered_once_while_waiting_for_delayed_dom(self):
+        page = FlowPage()
+        original = page.run_js
+        slot_reads = []
+        clock = [0.0]
+
+        def delayed(script, *args):
+            raw = original(script, *args)
+            if script == SLOT_SELECTION_SCRIPT:
+                slot_reads.append(args[-1])
+                if len(slot_reads) <= 2:
+                    raw.update(candidateReady=False, candidateCount=0)
+            return raw
+
+        page.run_js = delayed
+        with browser_navigation(page), \
+                patch.object(book_calendar.time, "monotonic", side_effect=lambda: clock[0]), \
+                patch.object(book_calendar.time, "sleep", side_effect=lambda delay: clock.__setitem__(0, clock[0] + delay)), \
+                patch.object(book_calendar, "available_slot_candidates", wraps=book_calendar.available_slot_candidates) as select_candidates:
+            result = recheck_calendar_before_final(
+                page, lookahead_months=1, start_day=date(2026, 10, 1), end_day=date(2026, 10, 31),
+                session_is_current=lambda: True, dom_timeout=0.5,
+            )
+        self.assertIsNotNone(result)
+        self.assertEqual(select_candidates.call_count, 1)
+        self.assertEqual(slot_reads, [False, False, False, True, False])
+        self.assertEqual(page.clicks, 1)
+        self.assertEqual(page.refreshes, 1)
+        self.assertEqual(len(page.requests), 2)
+        self.assert_stopped(page)
+
+    def test_delayed_slot_timeout_is_bounded_without_extra_request_or_click(self):
+        page = FlowPage()
+        original = page.run_js
+        clock = [0.0]
+
+        def missing_slot(script, *args):
+            raw = original(script, *args)
+            if script == SLOT_SELECTION_SCRIPT:
+                raw.update(candidateReady=False, candidateCount=0)
+            return raw
+
+        page.run_js = missing_slot
+        with browser_navigation(page), \
+                patch.object(book_calendar.time, "monotonic", side_effect=lambda: clock[0]), \
+                patch.object(book_calendar.time, "sleep", side_effect=lambda delay: clock.__setitem__(0, clock[0] + delay)), \
+                self.assertRaisesRegex(CalendarBookError, "slot DOM did not match"):
+            recheck_calendar_before_final(
+                page, lookahead_months=1, start_day=date(2026, 10, 1), end_day=date(2026, 10, 31),
+                session_is_current=lambda: True, dom_timeout=0.25,
+            )
+        self.assertAlmostEqual(clock[0], 0.25)
+        self.assertEqual(page.clicks, 0)
+        self.assertEqual(page.refreshes, 1)
+        self.assertEqual(len(page.requests), 2)
+        self.assert_stopped(page)
+
+    def test_old_listener_queue_is_cleared_before_month_action(self):
+        page = FlowPage()
+        stale = packet(TIME_SLOTS_PATH, {}, [])
+        stale.tab_id = "query-tab"
+        page.listen.queue.append(stale)
+        result = run_flow(page)
+        self.assertIsNotNone(result)
+        self.assertIsNot(page.requests[-1], stale)
+
+    def test_can_collect_automatic_response_before_availability_delivery(self):
+        page = FlowPage()
+        page.reverse_responses = True
+        self.assertIsNotNone(run_flow(page))
+        self.assertEqual(page.date_clicks, [])
+
+    def test_cross_year_scan_stops_at_first_usable_day(self):
+        page = FlowPage([month("2026-12", {1: 0}), month("2027-01", {5: 1}), month("2027-02", {1: 4})])
+        result = run_flow(page, end_day=date(2027, 3, 1))
+        self.assertEqual(result.candidate.day, date(2027, 1, 5))
+        self.assertEqual(page.month_clicks, 1)
+
+    def test_applies_inclusive_preferences_even_if_earlier_month_is_positive(self):
+        page = FlowPage([month("2026-09", {1: 2}), month("2026-10", {12: 2, 13: 1, 14: 3})])
+        result = run_flow(page, start_day=date(2026, 10, 13), end_day=date(2026, 10, 13))
+        self.assertEqual(result.candidate.day, date(2026, 10, 13))
+        self.assertEqual(page.date_clicks, ["2026-10-13"])
+        self.assertEqual(page.month_clicks, 1)
+
+    def test_date_inventory_race_tries_next_day_without_repeating_failed_candidate(self):
+        page = FlowPage([month("2026-10", {13: 1, 14: 2}, slots={13: 0})])
+        result = run_flow(page)
+        self.assertEqual(result.candidate.day, date(2026, 10, 14))
+        self.assertEqual(page.date_clicks, ["2026-10-14"])
+        self.assertEqual(page.clicks, 1)
+
+    def test_later_automatic_day_is_recaptured_after_another_date_was_selected(self):
+        page = FlowPage([month("2026-10", {13: 1, 14: 1}, automatic_day=14, slots={13: 0})])
+        result = run_flow(page)
+        self.assertEqual(result.candidate.day, date(2026, 10, 14))
+        self.assertEqual(page.date_clicks, ["2026-10-13", "2026-10-14"])
+
+    def test_scans_applicant_inventory_once_in_chronological_order(self):
+        page = FlowPage([month("2026-09", {9: 2}), month("2026-10", {13: 1})])
+        result = run_flow(page)
+        self.assertEqual(result.candidate.day, date(2026, 9, 9))
+        self.assertEqual(page.refreshes, 1)
+        self.assertEqual(page.month_clicks, 0)
+
+    def test_full_negative_horizon_returns_none_without_slot_clicks(self):
+        page = FlowPage([month("2026-08", {1: 0}), month("2026-09", {}), month("2026-10", {1: 0})])
+        self.assertIsNone(run_flow(page))
+        self.assertEqual(page.month_clicks, 2)
+        self.assertEqual(page.date_clicks, [])
+        self.assertEqual(page.clicks, 0)
+        self.assert_stopped(page)
+
+    def test_no_month_beyond_user_end_is_requested(self):
+        page = FlowPage([month("2026-10", {1: 0})])
+        self.assertIsNone(run_flow(page, end_day=date(2026, 10, 31)))
+        self.assertEqual(page.month_clicks, 0)
+
+    def test_missing_next_month_is_an_error_not_no_inventory(self):
+        page = FlowPage([month("2026-10", {})])
+        with self.assertRaises(CalendarBookError):
+            run_flow(page)
+        self.assert_stopped(page)
+
+    def test_month_jump_is_rejected(self):
+        page = FlowPage([month("2026-08", {}), month("2026-10", {13: 1})])
+        with self.assertRaisesRegex(CalendarBookError, "exactly one month"):
+            run_flow(page)
+        self.assertEqual(page.clicks, 0)
+        self.assert_stopped(page)
+
+    def test_bad_packet_metadata_is_never_used_or_retried(self):
+        mutations = [
+            lambda p: setattr(p, "tab_id", "query-tab"),
+            lambda p: setattr(p, "is_failed", True),
+            lambda p: setattr(p, "url", "https://other.example.test" + AVAILABILITY_PATH),
+            lambda p: setattr(p, "method", "GET"),
+            lambda p: setattr(p.response, "status", 429),
+            lambda p: p.request.postData.update(_Servizio=None),
+        ]
+        for mutate in mutations:
+            with self.subTest(mutation=mutations.index(mutate)):
+                page = FlowPage()
+                page.request_mutator = mutate
+                with self.assertRaises(CalendarBookError):
+                    run_flow(page)
+                self.assertEqual(page.refreshes, 1)
+                self.assertEqual(page.clicks, 0)
+                self.assert_stopped(page)
+
+    def test_time_slots_from_wrong_date_or_service_fail(self):
+        for field, value in (("selectedDay", "2026-10-14"), ("idService", "wrong-service")):
+            page = FlowPage()
+            page.request_mutator = lambda p: p.request.postData.update({field: value}) if p.url.endswith(TIME_SLOTS_PATH) else None
+            with self.subTest(field=field), self.assertRaises(CalendarBookError):
+                run_flow(page)
+            self.assertEqual(page.clicks, 0)
+            self.assert_stopped(page)
+
+    def test_date_click_response_is_bound_to_that_day_and_tab(self):
+        for field in ("tab", "day"):
+            with self.subTest(field=field):
+                page = FlowPage([month("2026-10", {1: 0, 13: 1})])
+
+                def corrupt_after_click(result):
+                    if not page.date_clicks:
+                        return
+                    if field == "tab":
+                        result.tab_id = "old-query-tab"
+                    else:
+                        result.request.postData["selectedDay"] = "2026-10-01"
+
+                page.request_mutator = corrupt_after_click
+                with self.assertRaises(CalendarBookError):
+                    run_flow(page)
+                self.assertEqual(page.date_clicks, ["2026-10-13"])
+                self.assertEqual(page.clicks, 0)
+                self.assert_stopped(page)
+
+    def test_availability_service_must_remain_same_across_months(self):
+        page = FlowPage([month("2026-09", {}), positive_month()])
+        page.request_mutator = lambda p: p.request.postData.update(_Servizio="changed") if page.month_clicks and p.url.endswith(AVAILABILITY_PATH) else None
+        with self.assertRaisesRegex(CalendarBookError, "runtime service changed"):
+            run_flow(page)
+
+    def test_missing_automatic_response_and_duplicate_month_stop_listener(self):
+        for option in ("drop_automatic", "duplicate_availability"):
+            with self.subTest(option=option):
+                page = FlowPage()
+                setattr(page, option, True)
+                with self.assertRaises(CalendarBookError):
+                    run_flow(page)
+                self.assertEqual(page.date_clicks, [])
+                self.assert_stopped(page)
+
+    def test_negative_availability_but_positive_auto_slot_is_conflict(self):
+        page = FlowPage([month("2026-10", {13: 0}, slots={13: 1})])
+        with self.assertRaisesRegex(CalendarBookError, "disagree"):
+            run_flow(page)
+        self.assertEqual(page.clicks, 0)
+
+    def test_site_date_fallback_does_not_select_wrong_day(self):
+        page = FlowPage()
+        page.render_day = "2026-10-01"
+        with self.assertRaisesRegex(CalendarBookError, "selected date"):
+            run_flow(page)
+        self.assertEqual(page.clicks, 0)
+        self.assert_stopped(page)
+
+    def test_failed_date_click_is_not_retried(self):
+        page = FlowPage([month("2026-10", {1: 0, 13: 1})])
+        page.date_ack = False
+        with self.assertRaisesRegex(CalendarBookError, "acknowledged"):
+            run_flow(page)
+        self.assertEqual(page.date_clicks, [])
+        self.assert_stopped(page)
+
+    def test_bad_date_control_is_rejected_without_click(self):
+        for field, value in (("date_candidate_count", 2), ("date_enabled", False),
+                             ("date_runtime_matches", False)):
+            with self.subTest(field=field):
+                page = FlowPage([month("2026-10", {1: 0, 13: 1})])
+                setattr(page, field, value)
+                with self.assertRaises(CalendarBookError):
+                    run_flow(page)
+                self.assertEqual(page.date_clicks, [])
+                self.assert_stopped(page)
+
+    def test_post_slot_click_error_stops_without_trying_another_day(self):
+        page = FlowPage([month("2026-10", {13: 1, 14: 2})])
+        page.after_overrides = {"selected": False}
+        with self.assertRaises(CalendarBookError):
+            run_flow(page)
+        self.assertEqual(page.clicks, 1)
+        self.assertEqual(page.date_clicks, [])
+
+    def test_context_invalid_before_or_during_capture_blocks_selection(self):
+        page = FlowPage()
+        with self.assertRaises(CalendarBookError):
+            run_flow(page, session_is_current=lambda: False)
+        self.assertEqual(page.refreshes, 0)
+        current = [True]
+        page = FlowPage()
+        page.wait_hook = lambda: current.__setitem__(0, False)
+        with self.assertRaises(CalendarBookError):
+            run_flow(page, session_is_current=lambda: current[0])
+        self.assertEqual(page.clicks, 0)
+        self.assert_stopped(page)
+
+    def test_invalid_settings_do_not_navigate(self):
+        for kwargs in ({"lookahead_months": True}, {"lookahead_months": 0},
+                       {"start_day": None}, {"end_day": date(2025, 1, 1)},
+                       {"timeout": 0},
+                       {"timeout": float("nan")}, {"dom_timeout": -1}):
+            with self.subTest(kwargs=kwargs):
+                page = FlowPage()
+                with self.assertRaises(CalendarBookError):
+                    run_flow(page, **kwargs)
+                self.assertEqual(page.refreshes, 0)
+
+    def test_provider_error_does_not_leak_raw_body(self):
+        page = FlowPage()
+        page.wait_hook = Mock(side_effect=RuntimeError("secret-response-body"))
+        try:
+            run_flow(page)
+        except CalendarBookError:
+            self.assertNotIn("secret-response-body", traceback.format_exc())
+        else:
+            self.fail("Provider error was accepted")
+        self.assert_stopped(page)
+
+
+class BookPreferenceTests(unittest.TestCase):
+    def test_uses_existing_keys_and_does_not_mutate_inputs(self):
+        values = {"expected_start_date": "2026-10-13", "expected_end_date": "2026-10-13", "other": "keep"}
+        before = copy.deepcopy(values)
+        self.assertEqual(book_date_preferences(values), (date(2026, 10, 13), date(2026, 10, 13)))
+        self.assertEqual(values, before)
+        self.assertEqual(book_date_preferences({}), (date(2000, 1, 1), date(2100, 1, 1)))
+
+    def test_rejects_unknown_formats_and_inverted_range(self):
+        for values in (None, {"expected_start_date": None}, {"expected_start_date": "20261013"},
+                       {"expected_start_date": "2026-02-30"}, {"expected_start_date": "secret-input"},
+                       {"expected_start_date": "2026-10-14", "expected_end_date": "2026-10-13"}):
+            with self.subTest(values=values), self.assertRaises(CalendarBookError) as raised:
+                book_date_preferences(values)
+            self.assertNotIn("secret-input", str(raised.exception))
+
+
+def prepared_plugin(page, *, routing_key="slot.example.it.tourist"):
+    plugin = plugin_fixtures.ItaPluginQuerySafetyTests._plugin(
+        page, routing_key=routing_key, service_id=9001,
+        capability="single_schengen_tourism", lookahead_months=3,
+    )
+    plugin.config = VSPlgConfig(account=VSAccount(username="applicant@example.test"), free_config=plugin.free_config)
+    plugin.instance_id = "book-offline"
+    plugin.session_create_time = 111.0
+    plugin.user_data_path = "/nonexistent/ita-book-flow-test"
+    plugin._reset_calendar_state()
+    route = plugin._resolve_route(AppointmentType(routing_key=routing_key))
+    plugin._record_calendar_prepared_route(route, role="book")
+    plugin.query = Mock(side_effect=AssertionError("Calendar Book must not call Query"))
+    trigger = VSQueryResult(apt_type=AppointmentType(routing_key=routing_key))
+    return plugin, route, trigger
+
+
+class BookEntryTests(unittest.TestCase):
+    def test_query_and_book_share_month_reader_but_not_account_inventory(self):
+        from test.ita.test_debug_ita_production_query_gate import FakeProductionPage, make_plugin
+
+        query_page = FakeProductionPage([[(2026, 9, ()), (2026, 10, (13,))]])
+        query, query_route = make_plugin(query_page)
+        query.free_config["query_mode"] = "calendar"
+        book_page = FlowPage([month("2026-10", {13: 0, 14: 1})])
+        applicant, _, _ = prepared_plugin(book_page, routing_key=query_route.routing_key)
+        with browser_navigation(book_page), patch.object(
+            book_calendar, "_capture_month", wraps=book_calendar._capture_month
+        ) as capture:
+            signal = query.query(query_route.appointment_type())
+            result, approval = book_with_approval(
+                applicant, signal, {"username": "applicant@example.test"},
+            )
+
+        self.assertTrue(signal.success)
+        self.assertEqual(signal.earliest_date, datetime(2026, 10, 13))
+        self.assertFalse(result.success)  # Pre-final selection is not a booking.
+        self.assertEqual(result.label, BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        self.assertEqual(approval.candidate.day, date(2026, 10, 14))
+        self.assertNotEqual(query.config.account.username, applicant.config.account.username)
+        self.assertEqual([call.args[0] for call in capture.call_args_list],
+                         [query_page, query_page, book_page])
+        self.assertTrue(all(call.kwargs.get("service") is None for call in capture.call_args_list[:2]))
+        self.assertEqual(capture.call_args_list[2].kwargs["service"], SERVICE)
+        self.assertEqual(query_page.final_requests, 0)
+        self.assertEqual(book_page.guard_final_count, 0)
+        self.assertEqual(book_page.clicks, 1)
+        self.assertEqual(query_page.listen.stops, len(query_page.listen.starts))
+        self.assertEqual(book_page.listen.stops, book_page.listen.starts)
+        applicant.query.assert_not_called()
+
+    def test_real_entry_runs_flow_and_keeps_book_result_unsuccessful(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        inputs = {"username": "applicant@example.test", "expected_start_date": "2026-10-13",
+                  "expected_end_date": "2026-10-13"}
+        original = copy.deepcopy(inputs)
+        with browser_navigation(page):
+            result, approval = book_with_approval(plugin, trigger, inputs)
+        self.assertFalse(result.success)
+        self.assertEqual(result.label, BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        self.assertEqual((result.urn, result.book_date, result.book_time, result.account), ("", "", "", ""))
+        self.assertEqual(approval.candidate.day, date(2026, 10, 13))
+        self.assertNotIn("80000113", str(plugin.logger.call_args_list))
+        self.assertNotIn("applicant@example.test", str(plugin.logger.call_args_list))
+        self.assertEqual(inputs, original)
+        plugin.query.assert_not_called()
+
+    def test_entry_signal_date_does_not_override_earlier_applicant_inventory(self):
+        page = FlowPage([month("2026-09", {1: 1}), month("2026-10", {13: 1})])
+        plugin, _, trigger = prepared_plugin(page)
+        trigger.earliest_date = datetime(2026, 10, 13)
+        trigger.availability = [DateAvailability(date=datetime(2026, 10, 13),
+                                               times=[TimeSlot(time="01:23", label="stale-query-slot")])]
+        with browser_navigation(page):
+            result, approval = book_with_approval(
+                plugin, trigger, {"username": "applicant@example.test"},
+            )
+        self.assertEqual(result.label, BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        self.assertEqual(approval.candidate.day, date(2026, 9, 1))
+        self.assertEqual(approval.candidate.time_label, "10:05 - 11:05")
+        self.assertEqual(page.refreshes, 1)
+        self.assertEqual(page.month_clicks, 0)
+
+    def test_query_preparation_cannot_be_converted_into_book_preparation(self):
+        page = FlowPage()
+        plugin, route, trigger = prepared_plugin(page)
+        plugin._reset_calendar_state()
+        plugin._record_calendar_prepared_route(route, role="query")
+        with self.assertRaises(BizLogicError):
+            plugin._record_calendar_prepared_route(route, role="book")
+        with self.assertRaises(BizLogicError):
+            plugin.book(trigger, {"username": "applicant@example.test"})
+        self.assertEqual(page.refreshes, 0)
+
+    def test_url_alone_is_not_a_book_preparation_proof(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        plugin._reset_calendar_state()
+        plugin._enter_service = Mock(side_effect=BizLogicError("fresh preparation required"))
+        with self.assertRaises(BizLogicError):
+            plugin.book(trigger, {"username": "applicant@example.test"})
+        plugin._enter_service.assert_called_once()
+        self.assertEqual(page.refreshes, 0)
+        plugin.query.assert_not_called()
+
+    def test_missing_or_different_applicant_is_rejected(self):
+        for inputs in (None, {}, {"username": "other@example.test"}):
+            with self.subTest(inputs=inputs):
+                page = FlowPage()
+                plugin, _, trigger = prepared_plugin(page)
+                with self.assertRaises(BizLogicError):
+                    plugin.book(trigger, inputs)
+                self.assertEqual(page.refreshes, 0)
+
+    def test_changed_account_page_login_or_route_is_rejected(self):
+        mutations = [
+            lambda p: setattr(p.config.account, "username", "other@example.test"),
+            lambda p: setattr(p, "page", FlowPage()),
+            lambda p: setattr(p, "session_create_time", 222.0),
+            lambda p: setattr(p.page, "tab_id", "another-tab"),
+            lambda p: p.free_config["apt_configs"]["slot.example.it.tourist"].update(service_id=9002),
+            lambda p: p.free_config.update(final_submit_enabled=True),
+            lambda p: setattr(p.page, "service", "another-runtime"),
+        ]
+        for mutation in mutations:
+            with self.subTest(mutation=mutations.index(mutation)):
+                page = FlowPage()
+                plugin, _, trigger = prepared_plugin(page)
+                mutation(plugin)
+                with self.assertRaises(BizLogicError):
+                    plugin.book(trigger, {"username": "applicant@example.test"})
+                self.assertEqual(page.refreshes, 0)
+
+    def test_preparation_from_another_page_is_rejected(self):
+        first, _, _ = prepared_plugin(FlowPage())
+        second, _, trigger = prepared_plugin(FlowPage())
+        second._prepared_calendar = first._prepared_calendar
+        with self.assertRaises(BizLogicError):
+            second.book(trigger, {"username": "applicant@example.test"})
+
+    def test_second_book_call_rechecks_current_inventory(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        with browser_navigation(page):
+            first, first_approval = book_with_approval(
+                plugin, trigger, {"username": "applicant@example.test"},
+            )
+            second, second_approval = book_with_approval(
+                plugin, trigger, {"username": "applicant@example.test"},
+            )
+        self.assertEqual(first.label, BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        self.assertEqual(second.label, BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        self.assertEqual(first_approval.candidate.day, second_approval.candidate.day)
+        self.assertEqual(first_approval.candidate.time_label, second_approval.candidate.time_label)
+        self.assertEqual(page.refreshes, 2)
+        self.assertEqual(page.clicks, 2)
+
+    def test_no_inventory_within_preferences_is_not_reported_as_success(self):
+        page = FlowPage([month("2026-10", {13: 0})])
+        plugin, _, trigger = prepared_plugin(page)
+        with browser_navigation(page):
+            result, approval = book_with_approval(
+                plugin, trigger,
+                {"username": "applicant@example.test", "expected_end_date": "2026-10-31"},
+            )
+        self.assertFalse(result.success)
+        self.assertEqual(result.label, BOOKING_RECHECK_NONE_AVAILABLE_LABEL)
+        self.assertIsNone(approval)
+
+    def test_mid_capture_account_change_invalidates_preparation(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        page.wait_hook = lambda: setattr(plugin.config.account, "username", "other@example.test")
+        with browser_navigation(page), self.assertRaises(BizLogicError):
+            plugin.book(trigger, {"username": "applicant@example.test"})
+        self.assertIsNone(plugin._prepared_calendar)
+        self.assertEqual(page.clicks, 0)
+
+    def test_account_change_during_candidate_dom_read_blocks_the_click(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        original = page.run_js
+
+        def changed_account(script, *args):
+            raw = original(script, *args)
+            if script == SLOT_SELECTION_SCRIPT and args[-1] is False:
+                plugin.config.account.username = "other@example.test"
+            return raw
+
+        page.run_js = changed_account
+        with browser_navigation(page), self.assertRaises(BizLogicError):
+            plugin.book(trigger, {"username": "applicant@example.test"})
+        self.assertIsNone(plugin._prepared_calendar)
+        self.assertEqual(page.clicks, 0)
+        self.assertEqual(page.date_clicks, [])
+
+    def test_lifecycle_operations_clear_book_preparation(self):
+        for action in ("config", "login", "cleanup"):
+            with self.subTest(action=action):
+                plugin, _, _ = prepared_plugin(FlowPage())
+                if action == "config":
+                    plugin.set_config(plugin.config)
+                elif action == "login":
+                    with patch("plugins.ita_plugin.init_chromium_options", side_effect=RuntimeError("offline stop")):
+                        with self.assertRaises(RuntimeError):
+                            plugin.create_session()
+                else:
+                    plugin.cleanup()
+                self.assertIsNone(plugin._prepared_calendar)
+                self.assertFalse(hasattr(plugin, "last_booking_precommit"))
+
+    def test_http_auth_and_rate_limit_use_existing_framework_errors(self):
+        for status, error in ((401, SessionExpiredOrInvalidError), (429, RateLimiteddError)):
+            with self.subTest(status=status):
+                page = FlowPage()
+                plugin, _, trigger = prepared_plugin(page)
+                page.request_mutator = lambda p: setattr(p.response, "status", status)
+                with browser_navigation(page), self.assertRaises(error):
+                    plugin.book(trigger, {"username": "applicant@example.test"})
+                self.assertIsNone(plugin._prepared_calendar)
+                self.assertEqual(page.clicks, 0)
+
+    def test_provider_failure_at_entry_is_sanitized_and_invalidates_proof(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        page.browser_error = "secret-provider-body"
+        try:
+            plugin.book(trigger, {"username": "applicant@example.test"})
+        except BizLogicError:
+            self.assertNotIn("secret-provider-body", traceback.format_exc())
+        else:
+            self.fail("Provider failure was accepted")
+        self.assertIsNone(plugin._prepared_calendar)
+
+    def test_two_route_keys_share_the_same_calendar_flow(self):
+        for key in ("slot.hkg.it.tourist", "slot.dub.it.tourist"):
+            with self.subTest(key=key):
+                page = FlowPage()
+                plugin, _, trigger = prepared_plugin(page, routing_key=key)
+                with browser_navigation(page):
+                    result = plugin.book(trigger, {"username": "applicant@example.test"})
+                self.assertEqual(result.label, BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+
+    def test_query_mode_does_not_drive_the_prepared_book_branch(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        plugin.free_config["query_mode"] = "calendar"
+        with browser_navigation(page):
+            result = plugin.book(trigger, {"username": "applicant@example.test"})
+        self.assertEqual(result.label, BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        plugin.query.assert_not_called()
+
+    def test_final_request_observation_rejects_instead_of_reporting_precommit(self):
+        page = FlowPage()
+        plugin, _, trigger = prepared_plugin(page)
+        page.guard_final_count = 1
+        with browser_navigation(page), self.assertRaises(BizLogicError):
+            plugin.book(trigger, {"username": "applicant@example.test"})
+        self.assertEqual(page.refreshes, 0)
+        self.assertEqual(page.clicks, 0)
+
+
+DATE_JS_HARNESS = r"""
+const vm = require('node:vm');
+const {source, mode} = JSON.parse(require('node:fs').readFileSync(0, 'utf8'));
+let clicks = 0, finalClicks = 0;
+const zeroSize = mode.startsWith('zero_size') || mode === 'selected_zero_size';
+function node(day) {
+  const classes = new Set(['input-async-abilitato']);
+  return {dataset: {date: day}, isConnected: true,
+    classList: {contains: c => classes.has(c), add: c => classes.add(c)},
+    hasAttribute: () => false, getAttribute: () => null,
+    getBoundingClientRect: () => ({width: zeroSize || mode === 'zero_width' ? 0 : 90,
+                                  height: zeroSize || mode === 'zero_height' ? 0 : 30, left: 3000}),
+  };
+}
+const old = node('2026-10-01'), link = node('2026-10-13');
+let selected = ['already_selected', 'selected_zero_size'].includes(mode) ? link : old;
+const content = node(selected.dataset.date);
+link.click = () => {clicks++; selected = link; content.dataset.date = link.dataset.date;};
+if (['disabled', 'zero_size_disabled'].includes(mode)) link.classList.add('input-async-disabilitato');
+if (mode === 'negative') link.classList.add('notAvailableDay');
+const final = {disabled: mode !== 'unguarded', dataset: {coordinateFinalGuard: 'enabled'}, click: () => finalClicks++};
+const document = {
+  querySelectorAll(q) {
+    if (q === '#idServizio') return [{value: mode === 'wrong_service' ? 'wrong' : '7002'}];
+    if (q === '#btnPrenotaNoOtp') return [final];
+    if (q === '.events a[data-date]') return mode === 'duplicate' ? [old, link, link] : [old, link];
+    if (q === '.events a.selected') return [selected];
+    if (q === '.events-content li.selected') return [content];
+    throw Error('Unexpected selector');
+  },
+  querySelector(q) {if (q === '.selected') return selected; throw Error('Unexpected selector');},
+};
+const window = {
+  location: {origin: mode === 'wrong_origin' ? 'https://other.example.test' : 'https://prenotami.esteri.it', pathname: '/BookingCalendar'},
+  getComputedStyle: element => ({
+    display: ['hidden', 'zero_size_hidden'].includes(mode) ? 'none' : 'block',
+    visibility: 'visible', opacity: '1',
+    pointerEvents: mode === 'zero_size_pointer_blocked' ||
+      (mode === 'selected_zero_size' && element === selected) ? 'none' : 'auto',
+  }),
+};
+const run = click => vm.runInNewContext('(function(){' + source + '\n}).apply(null, args)',
+  {document, window, args: ['7002', '2026-10-13', click]}, {timeout: 1000});
+const before = run(false), acted = run(true), after = run(false);
+process.stdout.write(JSON.stringify({before, acted, after, clicks, finalClicks}));
+"""
+
+
+@unittest.skipUnless(shutil.which("node"), "Node is required for the native-date script contract")
+class BookDateJavaScriptTests(unittest.TestCase):
+    def run_case(self, mode):
+        completed = subprocess.run([shutil.which("node"), "-e", DATE_JS_HARNESS],
+                                   input=json.dumps({"source": DATE_SELECTION_SCRIPT, "mode": mode}),
+                                   text=True, capture_output=True, timeout=10, check=True)
+        return json.loads(completed.stdout)
+
+    def test_native_date_selection_can_target_offscreen_timeline_and_never_final(self):
+        result = self.run_case("positive")
+        self.assertEqual(result["clicks"], 1)
+        self.assertTrue(result["after"]["selected"])
+        self.assertEqual(result["finalClicks"], 0)
+
+    def test_already_selected_date_is_not_clicked_again(self):
+        result = self.run_case("already_selected")
+        self.assertEqual(result["clicks"], 0)
+        self.assertTrue(result["before"]["selected"])
+
+    def test_zero_size_enabled_dates_follow_native_click_and_readback(self):
+        for mode in ("zero_width", "zero_height", "zero_size"):
+            with self.subTest(mode=mode):
+                result = self.run_case(mode)
+                self.assertTrue(result["before"]["candidateReady"])
+                self.assertEqual(result["clicks"], 1)
+                self.assertTrue(result["after"]["selected"])
+                self.assertEqual(result["finalClicks"], 0)
+
+    def test_selected_zero_size_pointer_blocked_date_is_not_reclicked(self):
+        result = self.run_case("selected_zero_size")
+        self.assertTrue(result["before"]["selected"])
+        self.assertFalse(result["before"]["candidateReady"])
+        self.assertEqual(result["clicks"], 0)
+        self.assertEqual(result["finalClicks"], 0)
+
+    def test_guarded_native_date_action_rejects_unsafe_controls(self):
+        for mode in ("disabled", "negative", "unguarded", "wrong_service", "wrong_origin", "duplicate", "hidden",
+                     "zero_size_disabled", "zero_size_hidden", "zero_size_pointer_blocked"):
+            with self.subTest(mode=mode):
+                result = self.run_case(mode)
+                self.assertEqual(result["clicks"], 0)
+                self.assertEqual(result["finalClicks"], 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 271 - 0
test/ita/test_ita_calendar_query.py

@@ -0,0 +1,271 @@
+import json
+import shutil
+import subprocess
+import unittest
+from unittest.mock import Mock, patch
+
+from plugins.ita_plugin import (
+    CalendarGateError,
+    CalendarNextMonthUnavailableError,
+    CalendarProbeResult,
+    NEXT_MONTH_CONTROL_SCRIPT,
+    scan_until_first_available_month,
+)
+from plugins.ita_plugin import parse_calendar_availability
+
+
+MONTH_CONTROL_HARNESS = r"""
+const vm = require('node:vm');
+const {source, mode} = JSON.parse(require('node:fs').readFileSync(0, 'utf8'));
+let clicks = 0;
+const node = {
+  isConnected: mode !== 'detached',
+  hasAttribute: name => name === 'disabled' && mode === 'disabled',
+  getAttribute: name => name === 'aria-disabled' && mode === 'aria_disabled' ? 'true' : null,
+  getBoundingClientRect: () => ({left: 20, right: mode === 'zero_size' ? 20 : 100,
+                                top: mode === 'offscreen' ? 2000 : 20, bottom: 100}),
+  contains: item => item === node,
+  click: () => clicks++,
+};
+const document = {
+  querySelectorAll: selector => {
+    if (selector !== '#datetimepicker th.dtpicker-next') throw Error('Unexpected selector');
+    return mode === 'missing' ? [] : mode === 'duplicate' ? [node, node] : [node];
+  },
+  elementFromPoint: () => mode === 'occluded' ? {} : node,
+};
+const window = {
+  location: {origin: mode === 'wrong_origin' ? 'https://other.example.test' : 'https://prenotami.esteri.it',
+             pathname: mode === 'wrong_path' ? '/UserArea' : '/BookingCalendar'},
+  innerWidth: 1000, innerHeight: 800,
+  getComputedStyle: () => ({display: mode === 'hidden' ? 'none' : 'block',
+    visibility: mode === 'invisible' ? 'hidden' : 'visible',
+    pointerEvents: mode === 'pointer_blocked' ? 'none' : 'auto', opacity: mode === 'transparent' ? '0' : '1'}),
+};
+const run = click => vm.runInNewContext('(function(){' + source + '\n}).apply(null, args)',
+  {document, window, args: [click]}, {timeout: 1000});
+const before = run(false), acted = run(true);
+process.stdout.write(JSON.stringify({before, acted, clicks}));
+"""
+
+
+@unittest.skipUnless(shutil.which("node"), "Node is required for actual Calendar-control scripts")
+class MonthControlJavaScriptTests(unittest.TestCase):
+    def run_case(self, mode):
+        result = subprocess.run(
+            [shutil.which("node"), "-e", MONTH_CONTROL_HARNESS],
+            input=json.dumps({"source": NEXT_MONTH_CONTROL_SCRIPT, "mode": mode}),
+            text=True, capture_output=True, timeout=10, check=True,
+        )
+        return json.loads(result.stdout)
+
+    def test_shared_control_check_only_clicks_the_ready_month_control(self):
+        result = self.run_case("ready")
+        self.assertFalse(result["before"]["clicked"])
+        self.assertEqual(result["before"]["actionableCount"], 1)
+        self.assertTrue(result["acted"]["clicked"])
+        self.assertEqual(result["clicks"], 1)
+
+    def test_hidden_disabled_covered_duplicate_or_foreign_controls_are_not_clicked(self):
+        for mode in ("detached", "disabled", "aria_disabled", "zero_size", "offscreen", "occluded",
+                     "missing", "duplicate", "hidden", "invisible", "pointer_blocked", "transparent",
+                     "wrong_origin", "wrong_path"):
+            with self.subTest(mode=mode):
+                result = self.run_case(mode)
+                self.assertFalse(result["acted"]["clicked"])
+                self.assertEqual(result["clicks"], 0)
+
+
+def double_json(items):
+    return json.dumps(json.dumps(items))
+
+
+def probe(year, month, capacities):
+    items = [
+        {
+            "DateLibere": f"{day:02d}/{month:02d}/{year:04d} 00:00:00",
+            "SlotLiberi": slots_free,
+            "SlotRimanenti": slots_remaining,
+        }
+        for day, slots_free, slots_remaining in capacities
+    ]
+    return CalendarProbeResult(
+        days=parse_calendar_availability(double_json(items)),
+        selected_day=f"01/{month:02d}/{year:04d}",
+    )
+
+
+class CalendarProductionScanTests(unittest.TestCase):
+    def test_selected_month_preserves_both_observed_date_formats(self):
+        for selected_day in ("01/09/2026", "2026-09-01", " 01/09/2026 00:00:00 "):
+            with self.subTest(selected_day=selected_day):
+                result = CalendarProbeResult(days=(), selected_day=selected_day)
+                self.assertEqual(result.selected_month, (2026, 9))
+        for selected_day in ("not-a-date", "2026-13-01"):
+            with self.subTest(selected_day=selected_day), self.assertRaises(CalendarGateError):
+                CalendarProbeResult(days=(), selected_day=selected_day)
+
+    def test_rejects_dates_outside_the_requested_month(self):
+        october_days = parse_calendar_availability(
+            double_json(
+                [
+                    {
+                        "DateLibere": "01/10/2026 00:00:00",
+                        "SlotLiberi": 1,
+                        "SlotRimanenti": 0,
+                    }
+                ]
+            )
+        )
+
+        with self.assertRaisesRegex(
+            CalendarGateError,
+            "escaped the requested month",
+        ):
+            CalendarProbeResult(
+                days=october_days,
+                selected_day="01/09/2026",
+            )
+
+    def test_stops_on_the_initial_positive_month(self):
+        august = probe(2026, 8, [(20, 2, 1), (12, 1, 0)])
+
+        with patch("plugins.ita_plugin._capture_month", side_effect=[august]) as capture:
+            result = scan_until_first_available_month(
+                Mock(),
+                lookahead_months=12,
+                month_click_interval_seconds=0,
+            )
+
+        capture.assert_called_once()
+        self.assertEqual(len(result), 1)
+        self.assertEqual(
+            result[-1].available_days[0].day.isoformat(),
+            "2026-08-12",
+        )
+
+    def test_scans_sequentially_then_stops_at_the_first_positive_month(self):
+        august = probe(2026, 8, [(31, 0, -1)])
+        september = probe(2026, 9, [(30, 0, -1)])
+        october = probe(
+            2026,
+            10,
+            [(20, 8, 7), (12, 1, 0), (1, 0, -1)],
+        )
+        november = probe(2026, 11, [(2, 10, 9)])
+        log = Mock()
+
+        with patch(
+            "plugins.ita_plugin._capture_month",
+            side_effect=[august, september, october, november],
+        ) as capture:
+            result = scan_until_first_available_month(
+                Mock(),
+                lookahead_months=12,
+                log=log,
+                month_click_interval_seconds=0,
+            )
+
+        self.assertEqual(capture.call_count, 3)
+        self.assertEqual(len(result), 3)
+        self.assertEqual(
+            result[-1].available_days[0].day.isoformat(),
+            "2026-10-12",
+        )
+        self.assertEqual(
+            [item.day.isoformat() for item in result[-1].available_days],
+            ["2026-10-12", "2026-10-20"],
+        )
+        self.assertEqual(log.call_count, 3)
+
+    def test_returns_none_only_after_the_complete_horizon(self):
+        months = [
+            probe(2026, month, [(1, 0, -1)])
+            for month in (8, 9, 10)
+        ]
+
+        with patch("plugins.ita_plugin._capture_month", side_effect=months) as capture:
+            result = scan_until_first_available_month(
+                Mock(),
+                lookahead_months=3,
+                month_click_interval_seconds=0,
+            )
+
+        self.assertEqual(capture.call_count, 3)
+        self.assertEqual(len(result), 3)
+        self.assertEqual(result[-1].available_days, ())
+
+    def test_accepts_an_exact_cross_year_transition(self):
+        december = probe(2026, 12, [(1, 0, -1)])
+        january = probe(2027, 1, [(4, 1, 0)])
+
+        with patch("plugins.ita_plugin._capture_month", side_effect=[december, january]):
+            result = scan_until_first_available_month(
+                Mock(),
+                lookahead_months=2,
+                month_click_interval_seconds=0,
+            )
+
+        self.assertEqual(
+            result[-1].available_days[0].day.isoformat(),
+            "2027-01-04",
+        )
+
+    def test_rejects_a_skipped_month_instead_of_publishing_a_signal(self):
+        august = probe(2026, 8, [(1, 0, -1)])
+        october = probe(2026, 10, [(1, 1, 0)])
+
+        with patch("plugins.ita_plugin._capture_month", side_effect=[august, october]):
+            with self.assertRaisesRegex(
+                CalendarGateError,
+                "exactly one month",
+            ):
+                scan_until_first_available_month(
+                    Mock(),
+                    lookahead_months=2,
+                    month_click_interval_seconds=0,
+                )
+
+    def test_incomplete_native_navigation_is_not_misreported_as_no_slots(self):
+        august = probe(2026, 8, [(1, 0, -1)])
+
+        with patch(
+            "plugins.ita_plugin._capture_month",
+            side_effect=[august, CalendarNextMonthUnavailableError("bounded")],
+        ):
+            with self.assertRaisesRegex(
+                CalendarGateError,
+                "before the configured horizon",
+            ):
+                scan_until_first_available_month(
+                    Mock(),
+                    lookahead_months=2,
+                    month_click_interval_seconds=0,
+                )
+
+    def test_rejects_invalid_scan_bounds(self):
+        for value in (True, 0, 121):
+            with self.subTest(value=value):
+                with self.assertRaisesRegex(
+                    CalendarGateError,
+                    "lookahead_months",
+                ):
+                    scan_until_first_available_month(
+                        Mock(),
+                        lookahead_months=value,
+                        month_click_interval_seconds=0,
+                    )
+
+    def test_invalid_scan_interval_never_touches_the_browser(self):
+        for value in (True, None, "1", -1, float("nan"), float("inf")):
+            with self.subTest(value=value):
+                page = Mock()
+                with self.assertRaisesRegex(CalendarGateError, "interval"):
+                    scan_until_first_available_month(
+                        page, lookahead_months=3, month_click_interval_seconds=value
+                    )
+                self.assertEqual(page.mock_calls, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 446 - 0
test/ita/test_ita_calendar_soak.py

@@ -0,0 +1,446 @@
+"""Exercise the existing soak loop with real Italy Query and fake browser IO."""
+
+import io
+import json
+import tempfile
+import time
+import unittest
+from contextlib import ExitStack, redirect_stderr, redirect_stdout
+from dataclasses import fields, replace
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from DrissionPage.errors import BrowserConnectError
+
+from plugins.ita_plugin import ItaPlugin
+from test.ita.test_debug_ita_production_query_gate import gate_env
+from test.ita.test_debug_ita_soak import FakeClock
+from test.ita.test_ita_query_recovery import RecoveryPage, prepared_plugin
+from tools.debug_ita_calendar_gate import CalendarRequestAudit, ReservationSnapshot
+from tools.debug_ita_soak import (
+    CalendarSoakContext, calendar_soak_limits, main, run_soak,
+)
+from tools.debug_ita_session import DebugConfigurationError
+
+
+class CalendarSoakLifecycleTests(unittest.TestCase):
+    def run_case(
+        self, outcomes=("available",), *, restored_outcomes=("available",),
+        restore_outcome="calendar", duration=900, restart=0,
+        max_sessions=0, end_snapshot=None, cleanup_failure=False,
+        create_outcomes=("ok",), interrupt_wait=False, interrupt_health=False,
+        soak_env=None, checkpoint_mutator=None,
+    ):
+        clock = FakeClock()
+        output = io.StringIO()
+        statuses = []
+        instances = []
+        pages = []
+        with tempfile.TemporaryDirectory() as task_tmp, ExitStack() as stack:
+            profile = Path(task_tmp) / "profile"
+            profile.mkdir(mode=0o700)
+            profile = profile.resolve()  # Match set_config's canonical macOS /private/var path.
+            stack.enter_context(patch.object(
+                CalendarRequestAudit, "settled_snapshot", CalendarRequestAudit.snapshot,
+            ))
+            stack.enter_context(patch("plugins.ita_plugin.time.sleep", clock.sleep))
+            stack.enter_context(patch(
+                "tools.debug_ita_calendar_gate.read_reservation_snapshot",
+                return_value=end_snapshot or ReservationSnapshot(0, 0),
+            ))
+            credentials = stack.enter_context(patch(
+                "tools.debug_ita_soak._get_query_credentials",
+                side_effect=AssertionError("must not reload credentials after preparation"),
+            ))
+
+            def make_instance(query_outcomes, *, restoring=False):
+                page = RecoveryPage(query_outcomes, restore_outcome=restore_outcome)
+                plugin, route = prepared_plugin(page)
+                plugin.instance_id = f"offline-{len(instances)}"
+                plugin._transient_user_data_path = str(Path(task_tmp) / plugin.instance_id / "user-data")
+                plugin.root_workspace = str(Path(task_tmp) / plugin.instance_id)
+                plugin.user_data_path = str(profile)
+                plugin.free_config["persistent_browser_profile_path"] = str(profile)
+                plugin.tunnel = None
+                plugin._record_calendar_prepared_route(plugin._resolve_route(route.appointment_type()), role="query")
+                plugin.book = Mock(side_effect=AssertionError("Book must not run in Query soak"))
+                create_index = max(0, len(instances) - 1)
+                create_outcome = create_outcomes[min(create_index, len(create_outcomes) - 1)]
+
+                def create():
+                    plugin._reset_calendar_state()
+                    if create_outcome == "connect-error":
+                        raise BrowserConnectError("offline connection failed")
+                    plugin.page.url = "https://prenotami.esteri.it/UserArea"
+                    plugin.is_healthy = True
+                    plugin.session_create_time = time.time()
+
+                plugin.create_session = Mock(side_effect=create)
+
+                def cleanup():
+                    page.driver.is_running = False
+                    plugin.page = None
+                    plugin.is_healthy = False
+                    plugin._reset_calendar_state()
+                    if cleanup_failure:
+                        raise RuntimeError("private@example.test secret-token")
+
+                plugin.cleanup = Mock(side_effect=cleanup)
+                instances.append(plugin)
+                pages.append(page)
+                return plugin, route
+
+            initial, route = make_instance(outcomes)
+            audit = CalendarRequestAudit(initial.page, include_time_slots=True)
+            audit.start()
+            initial.page.emit("/BookingCalendar/GenerateOTP?ServiceID=9001", "GET")
+            initial.page.emit("/Services/Booking/9001", "POST")
+            context = CalendarSoakContext(
+                plugin=initial, route=route, request_audit=audit, before=ReservationSnapshot(0, 0),
+            )
+            if checkpoint_mutator is not None:
+                checkpoint_mutator(context, initial, route)
+            if interrupt_health:
+                initial.page.run_js = Mock(side_effect=KeyboardInterrupt)
+
+            def factory(_group_id):
+                return make_instance(restored_outcomes, restoring=True)[0]
+
+            def sleep(seconds):
+                if interrupt_wait:
+                    raise KeyboardInterrupt
+                clock.sleep(seconds)
+
+            with redirect_stdout(output), redirect_stderr(output):
+                code = run_soak(
+                    gate_env() if soak_env is None else soak_env, apply=True, non_interactive=True,
+                    duration_seconds=duration, min_wait=300, max_wait=300,
+                    max_session_attempts=max_sessions, restart_after_probes=restart,
+                    plugin_factory=factory, prepared_calendar=context,
+                    sleep=sleep, monotonic=clock.monotonic, wall_time=clock.wall_time,
+                    randint=lambda minimum, maximum: minimum,
+                    status_writer=lambda body: statuses.append(json.loads(json.dumps(body))),
+                )
+            credentials.assert_not_called()
+            for instance in instances:
+                instance.book.assert_not_called()
+            for page in pages:
+                self.assertEqual(page.driver.immediate_event_handlers, {})
+            result_lines = [line for line in output.getvalue().splitlines()
+                            if line.startswith("ITA_SOAK_CALENDAR_RESULT=")]
+            self.assertEqual(len(result_lines), 1)
+            report = json.loads(result_lines[0].split("=", 1)[1])
+            # Assert ownership before object finalizers can call cleanup again.
+            cleanup_calls = [instance.cleanup.call_count for instance in instances]
+            for instance in instances:
+                instance.cleanup = Mock()  # neutralize __del__, not loop verification
+            return SimpleResult(code, report, statuses, output.getvalue(), instances, pages, cleanup_calls)
+
+    def test_positive_negative_positive_continues_with_fresh_results(self):
+        result = self.run_case(["available", "none", "available"])
+        self.assertEqual(result.code, 0, result.output)
+        self.assertTrue(result.report["passed"])
+        self.assertEqual(result.report["positiveQueries"], 2)
+        self.assertEqual(result.report["negativeQueries"], 1)
+        self.assertEqual(result.report["queryRequests"]["availabilityRequests"], 5)
+        self.assertEqual(result.report["queryRequests"]["timeSlotRequests"], 3)
+        self.assertEqual(result.cleanup_calls, [1])
+        self.assertEqual(len(result.instances), 1)
+        self.assertEqual(result.report["latestQuery"]["earliestDate"], "2026-08-12")
+        self.assertNotIn("private@example.test", result.output)
+
+    def test_controlled_restart_uses_same_profile_and_new_query_without_otp(self):
+        result = self.run_case(restart=1)
+        self.assertEqual(result.code, 0, result.output)
+        self.assertTrue(result.report["controlledRestart"])
+        self.assertEqual(result.report["restores"], 1)
+        self.assertEqual(result.cleanup_calls, [1, 1])
+        self.assertEqual(result.pages[0].refresh_calls, 1)
+        self.assertGreater(result.pages[1].refresh_calls, 0)
+        self.assertEqual(result.pages[1].get_calls, ["https://prenotami.esteri.it/BookingCalendar"])
+        for key in ("otpRequests", "avantiPosts", "finalRequests"):
+            self.assertEqual(result.report["queryRequests"][key], 0)
+
+    def test_soak_checkpoint_is_local_and_contains_no_credentials_or_inventory(self):
+        def inspect(context, plugin, _route):
+            self.assertEqual(
+                {item.name for item in fields(context.checkpoint)},
+                {"route", "username", "profile_path", "calendar_url", "runtime_service"},
+            )
+            body = repr(context.checkpoint)
+            self.assertNotIn(plugin.config.account.username, body)
+            self.assertNotIn(plugin.config.account.password, body)
+            self.assertNotIn("earliest", body.lower())
+            self.assertNotIn("slot", body.lower())
+
+        result = self.run_case(restart=1, checkpoint_mutator=inspect)
+        self.assertEqual(result.code, 0, result.output)
+        self.assertEqual(result.report["restores"], 1)
+
+    def test_soak_restore_rejects_changed_owner_profile_or_route_before_navigation(self):
+        def mutate(field_name):
+            def apply(context, _plugin, _route):
+                checkpoint = context.checkpoint
+                if field_name == "username":
+                    context.checkpoint = replace(checkpoint, username="other@example.test")
+                elif field_name == "profile":
+                    context.checkpoint = replace(checkpoint, profile_path="/offline/other-profile")
+                else:
+                    context.checkpoint = replace(
+                        checkpoint, route=replace(checkpoint.route, service_id=9002),
+                    )
+            return apply
+
+        for field_name in ("username", "profile", "route"):
+            with self.subTest(field=field_name):
+                result = self.run_case(restart=1, checkpoint_mutator=mutate(field_name))
+                self.assertNotEqual(result.code, 0, result.output)
+                self.assertEqual(result.pages[1].get_calls, [])
+                self.assertEqual(result.report["restores"], 0)
+
+    def test_soak_restore_rejects_foreign_or_unobserved_calendar_url_before_navigation(self):
+        for calendar_url in (
+            "https://foreign.example/BookingCalendar",
+            "https://prenotami.esteri.it/BookingCalendar?unknown=1",
+        ):
+            def mutate(context, _plugin, _route, value=calendar_url):
+                context.checkpoint = replace(context.checkpoint, calendar_url=value)
+
+            with self.subTest(calendar_url=calendar_url):
+                result = self.run_case(restart=1, checkpoint_mutator=mutate)
+                self.assertNotEqual(result.code, 0, result.output)
+                self.assertEqual(result.pages[1].get_calls, [])
+                self.assertEqual(result.report["restores"], 0)
+
+    def test_prepared_context_owns_route_without_reloading_environment(self):
+        result = self.run_case(restart=1, soak_env={})
+        self.assertEqual(result.code, 0, result.output)
+        self.assertEqual(result.report["restores"], 1)
+        self.assertEqual(result.cleanup_calls, [1, 1])
+        self.assertEqual(result.statuses[-1]["service_id"], 9001)
+
+    def test_expired_session_rebuilds_then_continues_new_queries(self):
+        result = self.run_case(["expired"])
+        self.assertEqual(result.code, 0, result.output)
+        self.assertEqual(result.report["restores"], 1)
+        self.assertEqual(result.cleanup_calls, [1, 1])
+        self.assertGreater(result.report["positiveQueries"], 0)
+        self.assertEqual(result.instances[1].create_session.call_count, 1)
+
+    def test_disconnect_recovers_but_reports_audit_gap_not_false_pass(self):
+        result = self.run_case(["disconnect"])
+        self.assertEqual(result.code, 6, result.output)
+        self.assertFalse(result.report["passed"])
+        self.assertEqual(result.report["auditGaps"], 1)
+        self.assertEqual(result.report["restores"], 1)
+        self.assertGreater(result.report["positiveQueries"], 0)
+        self.assertEqual(result.cleanup_calls, [1, 1])
+
+    def test_two_expirations_stop_without_third_session(self):
+        result = self.run_case(["expired"], restored_outcomes=["expired"])
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.report["reason"], "consecutive-session-expirations")
+        self.assertEqual(len(result.instances), 2)
+        self.assertEqual(result.cleanup_calls, [1, 1])
+
+    def test_transient_network_failure_retries_same_browser(self):
+        result = self.run_case(["timeout", "available"])
+        self.assertEqual(result.code, 0, result.output)
+        self.assertEqual(len(result.instances), 1)
+        self.assertGreater(result.report["positiveQueries"], 0)
+        self.assertEqual(result.report["restores"], 0)
+
+    def test_two_transient_failures_stop_without_relogin_or_third_probe(self):
+        result = self.run_case(["timeout"])
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.pages[0].attempts, 2)
+        self.assertEqual(result.report["reason"], "consecutive-calendar-network-errors")
+        self.assertEqual(len(result.instances), 1)
+
+    def test_otp_reentry_is_pending_todo_not_attempted_again(self):
+        result = self.run_case(["expired"], restore_outcome="form")
+        self.assertEqual(result.code, 4, result.output)
+        self.assertEqual(result.report["state"], "needs_manual")
+        self.assertEqual(result.report["automaticOtpTodo"], "ITA-OTP-01")
+        self.assertIsNone(result.report["latestQuery"])
+        self.assertEqual(result.pages[1].refresh_calls, 0)
+        self.assertEqual(result.report["queryRequests"]["otpRequests"], 0)
+        self.assertEqual(result.report["queryRequests"]["avantiPosts"], 0)
+
+    def test_rate_limit_stops_without_account_rotation_or_relogin(self):
+        result = self.run_case(["available", "rate"])
+        self.assertEqual(result.code, 5, result.output)
+        self.assertEqual(result.report["state"], "rate_limited")
+        self.assertEqual(len(result.instances), 1)
+        self.assertEqual(result.pages[0].attempts, 2)
+        self.assertIsNone(result.report["latestQuery"])
+
+    def test_permission_denied_stops_for_operator(self):
+        result = self.run_case(["denied"])
+        self.assertEqual(result.code, 4, result.output)
+        self.assertEqual(result.report["state"], "needs_manual")
+        self.assertEqual(result.pages[0].attempts, 1)
+
+    def test_unknown_schema_stops_without_false_inventory_or_secret_log(self):
+        result = self.run_case(["malformed"])
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.report["positiveQueries"], 0)
+        self.assertEqual(result.report["negativeQueries"], 0)
+        self.assertEqual(result.pages[0].attempts, 1)
+        self.assertNotIn("secret-token", result.output)
+        self.assertNotIn("private@example.test", result.output)
+
+    def test_unexpected_write_request_cannot_pass(self):
+        result = self.run_case(["unexpected-otp"])
+        self.assertNotEqual(result.code, 0, result.output)
+        self.assertFalse(result.report["passed"])
+        self.assertEqual(result.report["queryRequests"]["otpRequests"], 1)
+        self.assertEqual(result.report["positiveQueries"], 0)
+
+    def test_wrong_service_after_relogin_stops_without_querying_it(self):
+        result = self.run_case(["expired"], restore_outcome="wrong-service")
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.pages[1].refresh_calls, 0)
+        self.assertFalse(result.report["passed"])
+
+    def test_unverified_reservation_counts_cannot_pass(self):
+        result = self.run_case(end_snapshot=ReservationSnapshot(1, 0))
+        self.assertEqual(result.code, 6, result.output)
+        self.assertFalse(result.report["passed"])
+        self.assertFalse(result.report["reservationVerified"])
+
+    def test_cancel_does_not_recreate_or_submit(self):
+        result = self.run_case(interrupt_wait=True)
+        self.assertEqual(result.code, 130, result.output)
+        self.assertEqual(result.cleanup_calls, [1])
+        self.assertFalse(result.report["passed"])
+
+    def test_cancel_during_health_probe_cleans_up_without_relogin(self):
+        result = self.run_case(interrupt_health=True)
+        self.assertEqual(result.code, 130, result.output)
+        self.assertEqual(result.cleanup_calls, [1])
+        self.assertEqual(len(result.instances), 1)
+        self.assertEqual(result.pages[0].attempts, 0)
+        self.assertFalse(result.report["passed"])
+
+    def test_cleanup_failure_is_not_reported_as_success(self):
+        result = self.run_case(cleanup_failure=True)
+        self.assertEqual(result.code, 3, result.output)
+        self.assertFalse(result.report["passed"])
+        self.assertNotIn("secret-token", result.output)
+
+    def test_connect_error_reuses_existing_bounded_creation_retry(self):
+        result = self.run_case(["expired"], create_outcomes=["connect-error", "ok"])
+        self.assertEqual(result.code, 0, result.output)
+        self.assertEqual(len(result.instances), 3)
+        self.assertEqual(result.cleanup_calls, [1, 1, 1])
+
+    def test_session_attempt_cap_stops_instead_of_silently_finishing(self):
+        result = self.run_case(["expired"], max_sessions=1)
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.report["reason"], "max-session-attempts-reached")
+        self.assertEqual(len(result.instances), 1)
+
+    def test_failed_cleanup_during_recovery_prevents_another_browser(self):
+        result = self.run_case(["expired"], cleanup_failure=True)
+        self.assertEqual(result.code, 3, result.output)
+        self.assertEqual(result.report["reason"], "cleanup-failed")
+        self.assertEqual(len(result.instances), 1)
+        self.assertNotIn("ITA_SOAK_CLEANUP_OK", result.output)
+
+    def test_two_connection_failures_stop_using_existing_cap(self):
+        result = self.run_case(["expired"], create_outcomes=["connect-error"])
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.report["reason"], "consecutive-browser-connect-failures")
+        self.assertEqual(len(result.instances), 3)  # prepared + two failed starts
+
+    def test_two_disconnections_stop_without_third_browser(self):
+        result = self.run_case(["disconnect"], restored_outcomes=["disconnect"])
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.report["reason"], "consecutive-browser-disconnects")
+        self.assertEqual(len(result.instances), 2)
+
+    def test_hourly_reauthentication_cap_survives_successful_queries_between_failures(self):
+        result = self.run_case(["expired"], restored_outcomes=["available", "expired"], duration=7200)
+        self.assertEqual(result.code, 1, result.output)
+        self.assertEqual(result.report["reason"], "reauthentication-rate-limit")
+        self.assertEqual(len(result.instances), 7)
+
+    def test_deadline_before_successful_retry_is_incomplete_not_a_pass(self):
+        result = self.run_case(["timeout"], duration=60)
+        self.assertEqual(result.code, 6, result.output)
+        self.assertEqual(result.report["positiveQueries"], 0)
+
+    def test_unexercised_requested_restart_is_not_marked_verified(self):
+        result = self.run_case(restart=100)
+        self.assertEqual(result.code, 6, result.output)
+        self.assertFalse(result.report["controlledRestart"])
+
+
+class SimpleResult:
+    def __init__(self, code, report, statuses, output, instances, pages, cleanup_calls):
+        self.code, self.report, self.statuses, self.output = code, report, statuses, output
+        self.instances, self.pages, self.cleanup_calls = instances, pages, cleanup_calls
+
+
+class CalendarSoakCliTests(unittest.TestCase):
+    def test_gate_transfers_the_same_prepared_instance_and_cleanup_once(self):
+        from test.ita import test_debug_ita_production_query_gate as workflow
+        from tools.debug_ita_calendar_gate import CalendarGateMode
+
+        def soak(_env, *, plugin, route, request_audit, before):
+            self.assertEqual(route.service_id, 9001)
+            self.assertEqual(before, ReservationSnapshot(0, 0))
+            self.assertEqual(request_audit.snapshot()["otpRequests"], 1)
+            self.assertEqual(request_audit.snapshot()["avantiPosts"], 1)
+            plugin.page.set.auto_handle_alert.assert_called_with(accept=False)
+            request_audit.stop()
+            plugin.cleanup()
+            return 0
+
+        with patch("tools.debug_ita_calendar_gate.resolve_qcal_mode", return_value=CalendarGateMode.CALENDAR_SOAK), \
+                patch("tools.debug_ita_soak.run_prepared_calendar_soak", side_effect=soak) as handoff:
+            code, output, plugin, page, mocks, otp_reader = workflow.ProductionGateWorkflowTests()._run_gate()
+        self.assertEqual(code, 0, output)
+        handoff.assert_called_once()
+        otp_reader.assert_called_once()
+        plugin.cleanup.assert_called_once()
+        mocks["run_production_query_acceptance"].assert_not_called()
+        mocks["scan_calendar_horizon"].assert_not_called()
+
+    def test_preflight_checks_calendar_config_without_credentials_or_browser(self):
+        output = io.StringIO()
+        with patch.dict("os.environ", gate_env(), clear=True), \
+                patch("tools.debug_ita_calendar_gate.run_calendar_gate") as run, \
+                patch("tools.debug_ita_soak._get_query_credentials") as credentials, \
+                redirect_stdout(output):
+            code = main(["--calendar", "--duration-seconds", "900"])
+        self.assertEqual(code, 0)
+        run.assert_not_called()
+        credentials.assert_not_called()
+        self.assertIn("external_request=false", output.getvalue())
+
+    def test_unsafe_cadence_is_rejected_before_gate_or_otp(self):
+        with patch.dict("os.environ", gate_env(), clear=True), \
+                patch("tools.debug_ita_calendar_gate.run_calendar_gate") as run, \
+                redirect_stderr(io.StringIO()):
+            code = main(["--calendar", "--run", "--min-wait", "10"])
+        self.assertEqual(code, 2)
+        run.assert_not_called()
+
+    def test_actual_gate_is_only_entered_with_run(self):
+        with patch.dict("os.environ", gate_env(), clear=True), \
+                patch("tools.debug_ita_calendar_gate.run_calendar_gate", return_value=0) as run:
+            self.assertEqual(main(["--calendar", "--run", "--restart-after-probes", "1"]), 0)
+        env = run.call_args.args[0]
+        self.assertEqual(env["ITA_QCAL_MODE"], "calendar_soak")
+        self.assertEqual(env["ITA_SOAK_RESTART_AFTER_PROBES"], "1")
+
+    def test_limits_reject_bad_values_before_external_actions(self):
+        for value in ("nan", "0", "86401"):
+            with self.subTest(value=value), self.assertRaises(DebugConfigurationError):
+                calendar_soak_limits({"ITA_SOAK_DURATION_SECONDS": value})
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 292 - 0
test/ita/test_ita_compact.py

@@ -0,0 +1,292 @@
+import json
+import unittest
+from datetime import date, datetime, time
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin as ita
+from vs_types import (
+    AppointmentType, AvailabilityStatus, VSAccount, VSPlgConfig, VSQueryResult,
+)
+
+
+def encoded(records):
+    return json.dumps(json.dumps(records))
+
+
+def day(value="01/10/2026 00:00:00", free=1, remaining=0):
+    return {"DateLibere": value, "SlotLiberi": free, "SlotRimanenti": remaining}
+
+
+def slot(value="01/10/2026 00:00:00", free=1, remaining=0, daily_id=12345678):
+    clock = lambda hour, minute: {
+        "Hours": hour, "Minutes": minute, "Seconds": 0, "Milliseconds": 0,
+    }
+    return {
+        "Data": value, "SlotLiberi": free, "SlotRimanenti": remaining,
+        "IDCalendarioServizioGiornaliero": daily_id,
+        "OrarioInizioFascia": clock(10, 5),
+        "OrarioFineFascia": clock(11, 5),
+    }
+
+
+def route_config(service=4937):
+    return {
+        "capability": "single_schengen_tourism",
+        "service_id": service,
+        "calendar_scan": {"lookahead_months": 12},
+        "form": {
+            "booking_type_control_id": "typeofbookingddl",
+            "booking_type_value": "1",
+            "booking_type_labels": ["Single booking"],
+            "purpose_control_id": "ddls_0",
+            "purpose_value": "42",
+            "purpose_labels": ["Tourism"],
+        },
+        "mail": {"authorization_source": "account"},
+    }
+
+
+class Response:
+    def __init__(self, status, text="", url=""):
+        self.status_code, self.text, self.url = status, text, url
+
+    def json(self):
+        try:
+            return json.loads(self.text)
+        except Exception:
+            return {}
+
+
+class CompactProtocolTests(unittest.TestCase):
+    def test_route_is_configuration_driven(self):
+        routes = {"slot.hkg.it.tourist": route_config(4937),
+                  "slot.syd.it.tourist": route_config(8123)}
+        self.assertEqual(ita.resolve_route_config(routes, "slot.hkg.it.tourist").service_id, 4937)
+        self.assertEqual(ita.resolve_route_config(routes, "slot.syd.it.tourist").service_id, 8123)
+
+    def test_inventory_and_last_slot_semantics(self):
+        days = ita.parse_calendar_availability(encoded([day()]))
+        slots = ita.parse_time_slots(encoded([slot()]))
+        self.assertTrue(days[0].is_available)
+        self.assertTrue(slots[0].is_available)
+        self.assertEqual(slots[0].time_label, "10:05 - 11:05")
+
+    def test_zero_inventory_is_unavailable(self):
+        self.assertFalse(ita.parse_calendar_availability(
+            encoded([day(free=0, remaining=-1)]))[0].is_available)
+
+
+class CompactCalendarTests(unittest.TestCase):
+    def test_query_stops_at_first_positive_month(self):
+        empty = ()
+        positive = (ita.CalendarDay(date(2026, 9, 2), 1, 0),)
+        with patch.object(ita, "read_calendar_context", return_value=("4937", date(2026, 8, 1))), \
+             patch.object(ita, "fetch_calendar_month", side_effect=[empty, positive]) as fetch:
+            result = ita.scan_until_first_available_month(
+                object(), lookahead_months=12, month_click_interval_seconds=0)
+        self.assertEqual(result, (empty, positive))
+        self.assertEqual(fetch.call_count, 2)
+
+    def test_calendar_fetch_uses_existing_browser_fetch(self):
+        response = Response(200, encoded([day()]),
+                            "https://prenotami.esteri.it/BookingCalendar/RetrieveCalendarAvailability")
+        with patch.object(ita, "perform_browser_fetch", return_value=response) as fetch:
+            result = ita.fetch_calendar_month(object(), "4937", date(2026, 10, 1))
+        self.assertEqual(len(ita.available_calendar_days(result)), 1)
+        self.assertEqual(fetch.call_args.kwargs["json_data"], {
+            "_Servizio": "4937", "selectedDay": "01/10/2026",
+        })
+
+    def test_calendar_status_mapping(self):
+        cases = ((401, ita.CalendarAuthenticationExpiredError),
+                 (403, ita.CalendarAccessDeniedError),
+                 (429, ita.CalendarRateLimitedError),
+                 (504, ita.CalendarTransientError))
+        for status, error in cases:
+            with self.subTest(status=status), patch.object(
+                    ita, "perform_browser_fetch", return_value=Response(
+                        status, "", ita.AVAILABILITY_PATH)):
+                with self.assertRaises(error):
+                    ita.fetch_calendar_month(object(), "4937", date(2026, 10, 1))
+
+    def test_book_rechecks_applicant_inventory_and_selects_first_slot(self):
+        day_value = ita.CalendarDay(date(2026, 10, 2), 1, 0)
+        candidate = ita.SlotCandidate(
+            day_value.day, 1, 0, time(10, 5), time(11, 5), "12345678")
+        with patch.object(ita, "read_calendar_context", return_value=("4937", date(2026, 8, 1))), \
+             patch.object(ita, "fetch_calendar_month", side_effect=[
+                 (), (), (day_value,)]), \
+             patch.object(ita, "_move_to_month") as move, \
+             patch.object(ita, "fetch_calendar_slots", return_value=(candidate,)), \
+             patch.object(ita, "select_slot_before_final", return_value=candidate) as select:
+            result = ita.recheck_calendar_before_final(
+                object(), lookahead_months=12, start_day=date(2026, 8, 1),
+                end_day=date(2026, 12, 31), session_is_current=lambda: True,
+                month_click_interval_seconds=0)
+        self.assertEqual(result, candidate)
+        move.assert_called_once_with(unittest.mock.ANY, "4937", (2026, 10), 30)
+        self.assertEqual(select.call_args.kwargs["target_day"], date(2026, 10, 2))
+
+    def test_service_mismatch_fails_instead_of_timing_out(self):
+        with patch.object(ita, "read_calendar_service", return_value="9999"):
+            with self.assertRaisesRegex(ita.CalendarBookError, "service changed"):
+                ita.wait_for_calendar_service(
+                    object(), session_is_current=lambda: True,
+                    expected_service=4937, timeout=0.1)
+
+
+class CompactPreflightTests(unittest.TestCase):
+    @staticmethod
+    def snapshot(**changes):
+        value = {
+            "formReady": True, "turnstileReady": True,
+            "otpValuePresent": False, "otpSendEnabled": True,
+            "avantiEnabled": True,
+        }
+        value.update(changes)
+        return value
+
+    def test_async_form_options_are_polled_before_turnstile_interaction(self):
+        page = SimpleNamespace(run_js=Mock(side_effect=[
+            self.snapshot(formReady=False, turnstileReady=False),
+            self.snapshot(turnstileReady=False),
+            self.snapshot(),
+        ]))
+        bypasser = Mock()
+        with patch.object(ita.time, "monotonic", side_effect=[0, 0, 1, 2]), \
+             patch.object(ita.time, "sleep"), \
+             patch.object(ita, "CloudflareBypasser", return_value=bypasser) as factory:
+            result = ita.wait_for_booking_preflight(page, script="offline")
+        self.assertTrue(result["formReady"])
+        self.assertEqual(page.run_js.call_count, 3)
+        factory.assert_called_once_with(page, log=False)
+        bypasser.click_verification_button.assert_called_once_with(is_dfs=False)
+
+    def test_never_ready_form_times_out_without_touching_turnstile(self):
+        page = SimpleNamespace(run_js=Mock(return_value=self.snapshot(
+            formReady=False, turnstileReady=False)))
+        with patch.object(ita.time, "monotonic", side_effect=[0, 0, 121]), \
+             patch.object(ita.time, "sleep"), \
+             patch.object(ita, "CloudflareBypasser") as factory, \
+             self.assertRaisesRegex(ita.CalendarGateError, "form_pending"):
+            ita.wait_for_booking_preflight(page, script="offline")
+        factory.assert_not_called()
+
+    def test_otp_send_button_must_be_ready_before_preflight_returns(self):
+        page = SimpleNamespace(run_js=Mock(return_value=self.snapshot(
+            otpSendEnabled=False)))
+        with patch.object(ita.time, "monotonic", side_effect=[0, 0, 121]), \
+             patch.object(ita.time, "sleep"), \
+             self.assertRaisesRegex(ita.CalendarGateError, "otp_send_disabled"):
+            ita.wait_for_booking_preflight(page, script="offline")
+
+    def test_after_otp_accepts_the_expected_send_button_cooldown(self):
+        raw = self.snapshot(otpValuePresent=True, otpSendEnabled=False)
+        ita.validate_booking_preflight(raw, after_otp=True)
+
+    def test_query_failure_keeps_the_safe_calendar_reason(self):
+        plugin = object.__new__(ita.ItaPlugin)
+        plugin._prepared_calendar = object()
+        error = plugin._calendar_failure(
+            ita.CalendarGateError("Italy booking verification timed out: form_pending"),
+            "Query")
+        self.assertIn("form_pending", str(error))
+
+
+class CompactFinalTests(unittest.TestCase):
+    def setUp(self):
+        self.route = ita.resolve_route_config({"route": route_config()}, "route")
+        self.day = ita.CalendarDay(date(2026, 10, 2), 1, 0)
+        self.slot = ita.SlotCandidate(
+            self.day.day, 1, 0, time(10, 5), time(11, 5), "12345678")
+        self.page = SimpleNamespace(
+            tab_id="tab", url="https://prenotami.esteri.it/BookingCalendar")
+        self.plugin = SimpleNamespace(
+            page=self.page,
+            config=SimpleNamespace(account=VSAccount(username="applicant@example.com")),
+            _require_calendar_context=Mock(return_value=SimpleNamespace(
+                tab_id="tab", runtime_service="4937")),
+            _reset_calendar_state=Mock(), _log=Mock(),
+        )
+
+    def test_final_submits_once_and_requires_explicit_success(self):
+        response = Response(200, json.dumps({
+            "errorMessage": "", "url": "/Reservation",
+        }), "https://prenotami.esteri.it/BookingCalendar/InsertNewBooking")
+        with patch.object(ita, "verify_precommit_selection"), \
+             patch.object(ita, "perform_browser_fetch", return_value=response) as fetch:
+            result = ita._submit_final_once(self.plugin, self.route, self.slot)
+        self.assertTrue(result.success)
+        self.assertEqual(fetch.call_count, 1)
+        self.assertEqual(fetch.call_args.kwargs["data"]["idCalendarioGiornaliero"], "12345678")
+        self.plugin._reset_calendar_state.assert_not_called()
+
+    def test_ambiguous_final_response_is_retryable_failure(self):
+        response = Response(200, "{}",
+                            "https://prenotami.esteri.it/BookingCalendar/InsertNewBooking")
+        with patch.object(ita, "verify_precommit_selection"), \
+             patch.object(ita, "perform_browser_fetch", return_value=response) as fetch:
+            result = ita._submit_final_once(self.plugin, self.route, self.slot)
+        self.assertFalse(result.success)
+        self.assertEqual(fetch.call_count, 1)
+        self.plugin._reset_calendar_state.assert_called_once()
+
+
+class CompactPluginTests(unittest.TestCase):
+    def plugin(self, *, query_mode="calendar", final=False):
+        plugin = object.__new__(ita.ItaPlugin)
+        plugin.config = VSPlgConfig(
+            account=VSAccount(username="applicant@example.com", password="secret"),
+            free_config={
+                "query_mode": query_mode, "otp_mode": "cloud",
+                "final_submit_enabled": final,
+                "apt_configs": {"route": route_config()},
+            },
+        )
+        plugin.free_config = plugin.config.free_config
+        plugin.group_id = "ita.compact"
+        plugin.page = SimpleNamespace(
+            tab_id="tab", url="https://prenotami.esteri.it/BookingCalendar")
+        plugin.is_healthy = True
+        plugin._prepared_calendar = object()
+        plugin.logger = None
+        return plugin
+
+    def test_query_publishes_only_real_calendar_availability(self):
+        plugin, apt = self.plugin(), AppointmentType(routing_key="route")
+        positive = (ita.CalendarDay(date(2026, 10, 2), 1, 0),)
+        with patch.object(plugin, "health_check", return_value=True), \
+             patch.object(plugin, "_require_calendar_context"), \
+             patch.object(ita, "scan_until_first_available_month", return_value=(positive,)):
+            result = plugin.query(apt)
+        self.assertTrue(result.success)
+        self.assertEqual(result.availability_status, AvailabilityStatus.Available)
+        self.assertEqual(result.earliest_date.date(), date(2026, 10, 2))
+
+    def test_book_rejects_pool_account_signal_as_applicant_identity(self):
+        plugin, apt = self.plugin(query_mode="services_probe"), AppointmentType(routing_key="route")
+        signal = VSQueryResult(success=True, apt_type=apt,
+                               availability_status=AvailabilityStatus.Available)
+        with self.assertRaisesRegex(Exception, "applicant account"):
+            plugin.book(signal, {"username": "pool@example.com"})
+
+    def test_prefinal_book_does_not_submit(self):
+        plugin, apt = self.plugin(query_mode="services_probe"), AppointmentType(routing_key="route")
+        signal = VSQueryResult(success=True, apt_type=apt,
+                               availability_status=AvailabilityStatus.Available)
+        selected_day = ita.CalendarDay(date(2026, 10, 2), 1, 0)
+        slot = ita.SlotCandidate(
+            selected_day.day, 1, 0, time(10, 5), time(11, 5), "12345678")
+        with patch.object(ita, "book_date_preferences", return_value=(date.min, date.max)), \
+             patch.object(plugin, "_calendar_context_matches", return_value=True), \
+             patch.object(ita, "recheck_calendar_before_final", return_value=slot), \
+             patch.object(ita, "_submit_final_once") as submit:
+            result = plugin.book(signal, {"username": "applicant@example.com"})
+        self.assertFalse(result.success)
+        self.assertEqual(result.label, ita.BOOKING_CALENDAR_PREFINAL_STOP_LABEL)
+        submit.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 16 - 0
test/ita/test_ita_final_attribution.py

@@ -0,0 +1,16 @@
+"""Italy no longer attributes final success through Reservation history."""
+
+import unittest
+
+from plugins import ita_plugin
+
+
+class FinalAttributionContractTests(unittest.TestCase):
+    def test_explicit_final_response_replaces_receipt_delta_attribution(self):
+        self.assertTrue(hasattr(ita_plugin, "_final_packet_accepted"))
+        for name in ("inspect_final_packet", "FinalBookingAttempt", "ReservationSnapshot"):
+            self.assertFalse(hasattr(ita_plugin, name), name)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 31 - 0
test/ita/test_ita_final_evidence.py

@@ -0,0 +1,31 @@
+"""Local final evidence delegates to the installed production adapter."""
+
+import unittest
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+from tools.ita_final_evidence import FinalEvidenceRun
+
+
+class FinalEvidenceTests(unittest.TestCase):
+    def test_success_and_failure_are_standard_results(self):
+        for success, outcome in ((True, "confirmed"), (False, "failed_retryable")):
+            with self.subTest(success=success):
+                result = SimpleNamespace(
+                    success=success, book_date="2026-10-13", book_time="10:05 - 11:05")
+                submit = Mock(return_value=result)
+                # FinalEvidenceRun resolves through the instance runtime; a tiny
+                # stand-in object makes that boundary explicit.
+                class Plugin:
+                    def book(self):
+                        pass
+                plugin = Plugin()
+                Plugin.book.__globals__["submit_final"] = submit
+                run = FinalEvidenceRun(plugin, object())
+                self.assertEqual(run.execute()["outcome"], outcome)
+                self.assertIs(run.result, result)
+                submit.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 39 - 0
test/ita/test_ita_final_read_port.py

@@ -0,0 +1,39 @@
+"""Receipt read-port was removed from the Italy production contract."""
+
+import unittest
+from unittest.mock import Mock
+
+from plugins import ita_plugin
+
+
+class ReceiptTab:
+    def __init__(self, browser):
+        self.browser = browser
+        self.close = Mock(side_effect=lambda: browser.on_close(self))
+
+
+class Browser:
+    """Minimal synthetic browser retained for unrelated debug fixture imports."""
+
+    def __init__(self):
+        self.id = "synthetic-browser"
+        self.raw = {}
+        self.after = None
+        self.pages = []
+        self.on_close = lambda _page: None
+        self.new_tab = Mock(side_effect=self.open_tab)
+
+    def open_tab(self, **_kwargs):
+        tab = ReceiptTab(self)
+        self.pages.append(tab)
+        return tab
+
+
+class RetiredReadPortTests(unittest.TestCase):
+    def test_runtime_contains_no_reservation_read_port(self):
+        for name in ("FinalBookingAttempt", "ReservationSnapshot", "read_reservation_listing"):
+            self.assertFalse(hasattr(ita_plugin, name), name)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 366 - 0
test/ita/test_ita_local_handoff.py

@@ -0,0 +1,366 @@
+import io
+import json
+import os
+import stat
+import tempfile
+import unittest
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from plugins.ita_plugin import BOOKING_FORM_DISCOVERY_STOP_LABEL
+from tools.debug_ita_book import run_book_recheck_once
+from tools.debug_ita_monitor import run_monitor
+from tools.ita_local_handoff import (
+    ItaLocalHandoffError,
+    ItaLocalSignalStaleError,
+    claim_local_weak_signal,
+    publish_local_weak_signal,
+)
+from vs_types import AvailabilityStatus, VSBookResult, VSQueryResult
+
+
+SERVICE_ID = 1321
+ROUTING_KEY = "slot.dub.it.tourist"
+
+
+class _FlowPage:
+    url = "https://prenotami.esteri.it/Services/Booking/1321"
+
+    def ele(self, _selector, timeout=None):
+        del timeout
+        return None
+
+    def run_js(self, _script):
+        return {
+            "path": "/Services/Booking/1321",
+            "form": {
+                "method": "POST",
+                "action_path": "/Services/Booking/1321",
+            },
+            "field_count": 0,
+            "fields": [],
+            "button_count": 1,
+            "buttons": [
+                {
+                    "tag": "button",
+                    "type": "submit",
+                    "id": "btnAvanti",
+                    "name": None,
+                    "text": "Avanti",
+                }
+            ],
+        }
+
+
+class _FlowQueryPlugin:
+    last_instance = None
+
+    def __init__(self, group_id):
+        self.group_id = group_id
+        self.page = _FlowPage()
+        self.query_calls = 0
+        self.book_calls = 0
+        self.cleanup_calls = 0
+        _FlowQueryPlugin.last_instance = self
+
+    def set_log(self, logger):
+        self.logger = logger
+
+    def set_config(self, config):
+        self.config = config
+
+    def create_session(self):
+        return None
+
+    def query(self, apt_type):
+        self.query_calls += 1
+        return VSQueryResult(
+            success=True,
+            apt_type=apt_type,
+            availability_status=AvailabilityStatus.NoneAvailable,
+        )
+
+    def cleanup(self):
+        self.cleanup_calls += 1
+
+
+class _FlowBookPlugin:
+    last_instance = None
+
+    def __init__(self, group_id):
+        self.group_id = group_id
+        self.page = _FlowPage()
+        self.query_calls = 0
+        self.book_calls = 0
+        self.cleanup_calls = 0
+        self.last_trigger = None
+        _FlowBookPlugin.last_instance = self
+
+    def set_log(self, logger):
+        self.logger = logger
+
+    def set_config(self, config):
+        self.config = config
+
+    def create_session(self):
+        return None
+
+    def book(self, trigger, user_inputs=None):
+        del user_inputs
+        self.last_trigger = trigger
+        self.book_calls += 1
+        return VSBookResult(
+            success=False,
+            label=BOOKING_FORM_DISCOVERY_STOP_LABEL,
+        )
+
+    def cleanup(self):
+        self.cleanup_calls += 1
+
+
+class ItaLocalHandoffStorageTests(unittest.TestCase):
+    def test_signal_is_private_metadata_only_and_consumed_once(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir) / "handoff"
+            signal_path = publish_local_weak_signal(
+                service_id=SERVICE_ID,
+                routing_key=ROUTING_KEY,
+                issued_at=100.0,
+                handoff_root=root,
+            )
+
+            body = signal_path.read_text(encoding="utf-8")
+            payload = json.loads(body)
+            self.assertEqual(payload["service_id"], SERVICE_ID)
+            self.assertEqual(payload["routing_key"], ROUTING_KEY)
+            self.assertEqual(payload["evidence"], "booking-form")
+            self.assertNotIn("username", body.lower())
+            self.assertNotIn("password", body.lower())
+            self.assertNotIn("cookie", body.lower())
+            if os.name == "posix":
+                self.assertEqual(stat.S_IMODE(root.stat().st_mode), 0o700)
+                self.assertEqual(stat.S_IMODE(signal_path.stat().st_mode), 0o600)
+
+            claimed = claim_local_weak_signal(
+                expected_service_id=SERVICE_ID,
+                expected_routing_key=ROUTING_KEY,
+                now=110.0,
+                handoff_root=root,
+            )
+            claimed_again = claim_local_weak_signal(
+                expected_service_id=SERVICE_ID,
+                expected_routing_key=ROUTING_KEY,
+                now=110.0,
+                handoff_root=root,
+            )
+
+            self.assertIsNotNone(claimed)
+            self.assertEqual(claimed.service_id, SERVICE_ID)
+            self.assertIsNone(claimed_again)
+
+    def test_stale_signal_is_rejected_and_removed(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir) / "handoff"
+            publish_local_weak_signal(
+                service_id=SERVICE_ID,
+                routing_key=ROUTING_KEY,
+                issued_at=100.0,
+                handoff_root=root,
+            )
+
+            with self.assertRaises(ItaLocalSignalStaleError):
+                claim_local_weak_signal(
+                    expected_service_id=SERVICE_ID,
+                    expected_routing_key=ROUTING_KEY,
+                    now=131.0,
+                    handoff_root=root,
+                )
+
+            self.assertIsNone(
+                claim_local_weak_signal(
+                    expected_service_id=SERVICE_ID,
+                    expected_routing_key=ROUTING_KEY,
+                    now=131.0,
+                    handoff_root=root,
+                )
+            )
+
+    def test_two_consumers_can_claim_the_signal_only_once(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir) / "handoff"
+            publish_local_weak_signal(
+                service_id=SERVICE_ID,
+                routing_key=ROUTING_KEY,
+                issued_at=100.0,
+                handoff_root=root,
+            )
+
+            def claim():
+                return claim_local_weak_signal(
+                    expected_service_id=SERVICE_ID,
+                    expected_routing_key=ROUTING_KEY,
+                    now=110.0,
+                    handoff_root=root,
+                )
+
+            with ThreadPoolExecutor(max_workers=2) as pool:
+                results = list(pool.map(lambda _index: claim(), range(2)))
+
+            self.assertEqual(sum(item is not None for item in results), 1)
+
+    def test_wrong_target_is_consumed_and_never_available_for_book(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir) / "handoff"
+            publish_local_weak_signal(
+                service_id=9999,
+                routing_key=ROUTING_KEY,
+                issued_at=100.0,
+                handoff_root=root,
+            )
+
+            with self.assertRaisesRegex(
+                ItaLocalHandoffError,
+                "service_id does not match",
+            ):
+                claim_local_weak_signal(
+                    expected_service_id=SERVICE_ID,
+                    expected_routing_key=ROUTING_KEY,
+                    now=110.0,
+                    handoff_root=root,
+                )
+
+            self.assertIsNone(
+                claim_local_weak_signal(
+                    expected_service_id=SERVICE_ID,
+                    expected_routing_key=ROUTING_KEY,
+                    now=110.0,
+                    handoff_root=root,
+                )
+            )
+
+
+class ItaLocalHandoffFlowTests(unittest.TestCase):
+    def test_one_query_weak_signal_triggers_one_independent_book_recheck(self):
+        query_stdout = io.StringIO()
+        book_stdout = io.StringIO()
+        stderr = io.StringIO()
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir) / "handoff"
+
+            def publish():
+                publish_local_weak_signal(
+                    service_id=SERVICE_ID,
+                    routing_key=ROUTING_KEY,
+                    issued_at=100.0,
+                    handoff_root=root,
+                )
+
+            with (
+                patch(
+                    "tools.debug_ita_monitor.resolve_chrome_path",
+                    return_value=Path("/test/chrome"),
+                ),
+                patch(
+                    "tools.debug_ita_monitor._get_query_credentials",
+                    return_value=("query@example.test", "query-password"),
+                ),
+                patch(
+                    "tools.debug_ita_monitor._prepare_query_profile",
+                    return_value=Path("/offline/query-profile"),
+                ),
+                patch(
+                    "tools.debug_ita_monitor._bind_query_profile",
+                    return_value=Mock(),
+                ),
+                patch("tools.debug_ita_monitor.ItaPlugin", _FlowQueryPlugin),
+                patch.dict("tools.debug_ita_monitor.os.environ", {}, clear=False),
+                redirect_stdout(query_stdout),
+                redirect_stderr(stderr),
+            ):
+                monitor_exit = run_monitor(
+                    {},
+                    apply=True,
+                    non_interactive=True,
+                    min_wait=60,
+                    max_wait=60,
+                    max_probes=1,
+                    publish_local_signal=True,
+                    signal_publisher=publish,
+                )
+
+            def claim():
+                return claim_local_weak_signal(
+                    expected_service_id=SERVICE_ID,
+                    expected_routing_key=ROUTING_KEY,
+                    now=110.0,
+                    handoff_root=root,
+                )
+
+            with (
+                patch(
+                    "tools.debug_ita_book.resolve_chrome_path",
+                    return_value=Path("/test/chrome"),
+                ),
+                patch(
+                    "tools.debug_ita_book._get_credentials",
+                    return_value=("user@example.test", "user-password"),
+                ),
+                patch(
+                    "tools.debug_ita_book._assert_distinct_local_accounts"
+                ),
+                patch("tools.debug_ita_book.ItaPlugin", _FlowBookPlugin),
+                patch.dict("tools.debug_ita_book.os.environ", {}, clear=False),
+                redirect_stdout(book_stdout),
+                redirect_stderr(stderr),
+            ):
+                book_exit = run_book_recheck_once(
+                    {},
+                    non_interactive=True,
+                    wait_for_local_signal=True,
+                    signal_timeout=1,
+                    signal_claimer=claim,
+                    monotonic=lambda: 0.0,
+                    sleep=lambda _seconds: None,
+                )
+
+            query_plugin = _FlowQueryPlugin.last_instance
+            book_plugin = _FlowBookPlugin.last_instance
+            self.assertEqual(monitor_exit, 4)
+            self.assertEqual(book_exit, 4)
+            self.assertIsNot(query_plugin, book_plugin)
+            self.assertEqual(query_plugin.query_calls, 1)
+            self.assertEqual(query_plugin.book_calls, 0)
+            self.assertEqual(book_plugin.query_calls, 0)
+            self.assertEqual(book_plugin.book_calls, 1)
+            self.assertTrue(book_plugin.last_trigger.success)
+            self.assertEqual(
+                book_plugin.last_trigger.availability_status,
+                AvailabilityStatus.NoneAvailable,
+            )
+            self.assertEqual(book_plugin.cleanup_calls, 1)
+            self.assertIn(
+                "ITA_MONITOR_HANDOFF_PUBLISHED",
+                query_stdout.getvalue(),
+            )
+            self.assertIn("ITA_BOOK_SIGNAL_CLAIMED", book_stdout.getvalue())
+            self.assertIn(
+                "stage=before-avanti submit_attempts=0",
+                book_stdout.getvalue(),
+            )
+            combined_output = query_stdout.getvalue() + book_stdout.getvalue()
+            for secret in (
+                "query@example.test",
+                "query-password",
+                "user@example.test",
+                "user-password",
+            ):
+                self.assertNotIn(secret, combined_output)
+            self.assertIsNone(claim())
+            self.assertEqual(stderr.getvalue(), "")
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 121 - 0
test/ita/test_ita_login_flow.py

@@ -0,0 +1,121 @@
+"""W2/UT-04: real Italy entry and BaseFlow, synthetic browser only."""
+from contextlib import ExitStack
+from tempfile import TemporaryDirectory
+import unittest
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin as ita
+from test.ita.ita_test_fakes import FakeChromiumOptions, FakeKeyboard, FakeMouse, FakePage
+from utils.flow_engine import BaseFlow
+from vs_types import BizLogicError, VSAccount, VSPlgConfig
+
+
+class DelayedFormPage(FakePage):
+    def __init__(self):
+        super().__init__()
+        self.password_reads = 0
+
+    def ele(self, selector, timeout=None):
+        if self.state == "pingid" and selector == "@name=callback_2":
+            self.password_reads += 1
+            if self.password_reads < 3:
+                return None
+        return super().ele(selector, timeout)
+
+
+class ServerErrorPage(FakePage):
+    @property
+    def html(self):
+        return "503 Service Temporarily Unavailable" if self.state == "pingid" else ""
+
+
+class LoginFlowTests(unittest.TestCase):
+    def setup_plugin(self, page):
+        stack = ExitStack()
+        self.addCleanup(stack.close)
+        workspace = stack.enter_context(TemporaryDirectory())
+        with patch.object(ita.os.path, "abspath", return_value=workspace):
+            plugin = ita.ItaPlugin("offline-login-flow")
+        plugin.set_config(VSPlgConfig(account=VSAccount(username="fixture@example.test", password="synthetic-password")))
+        plugin.set_log(Mock())
+        self.addCleanup(plugin.cleanup)
+        stack.enter_context(patch("utils.plugin_utils.ChromiumOptions", FakeChromiumOptions))
+        stack.enter_context(patch("utils.plugin_utils.get_free_port", return_value=9900))
+        stack.enter_context(patch.object(ita, "ChromiumPage", return_value=page))
+        stack.enter_context(patch.object(ita, "HumanMouse", FakeMouse))
+        stack.enter_context(patch.object(ita, "HumanKeyboard", FakeKeyboard))
+        stack.enter_context(patch.object(ita.time, "sleep"))
+        return plugin
+
+    def test_login_uses_tls_host_engine_with_no_stuck_refresh(self):
+        page = FakePage()
+        plugin = self.setup_plugin(page)
+        plugin.create_session()
+        flow = ita.ItaLoginFlow(plugin)
+        self.assertIs(ita.ItaLoginFlow.run, BaseFlow.run)
+        self.assertIsNone(flow.max_stuck_cycles)
+        self.assertEqual(flow.interval, 3)
+        self.assertTrue(plugin.is_healthy)
+        self.assertEqual(page.refresh_calls, 0)
+        self.assertEqual(page.clicked.count("submit"), 1)
+
+    def test_delayed_password_control_does_not_partially_fill_or_repeat_credentials(self):
+        page = DelayedFormPage()
+        plugin = self.setup_plugin(page)
+        plugin.create_session()
+        self.assertEqual(page.password_reads, 3)
+        self.assertEqual(page.clicked, ["login", "username", "password", "submit"])
+        self.assertTrue(plugin.is_healthy)
+
+    def test_foreign_origin_or_port_never_receives_credentials(self):
+        for url in ("https://untrusted.example/signin/", "https://iam.esteri.it.attacker.example/signin/",
+                    "http://iam.esteri.it/signin/", "https://iam.esteri.it:8443/signin/",
+                    "https://userinfo-secret@iam.esteri.it/signin/"):
+            with self.subTest(url=url):
+                page = FakePage()
+                page.URLS = {**page.URLS, "pingid": url}
+                plugin = self.setup_plugin(page)
+                with self.assertRaisesRegex(BizLogicError, "left the expected website") as caught:
+                    plugin.create_session()
+                self.assertEqual(page.input_values, {})
+                self.assertEqual(page.clicked, ["login"])
+                self.assertFalse(plugin.is_healthy)
+
+    def test_explicit_default_https_port_is_accepted(self):
+        page = FakePage()
+        page.URLS = {**page.URLS, "pingid": "https://iam.esteri.it:443/signin/?state=private-state"}
+        plugin = self.setup_plugin(page)
+        plugin.create_session()
+        self.assertTrue(plugin.is_healthy)
+
+    def test_stalled_login_keeps_once_only_submission(self):
+        page = FakePage(submit_succeeds=False)
+        plugin = self.setup_plugin(page)
+        with self.assertRaisesRegex(BizLogicError, "流程步数耗尽") as caught:
+            plugin.create_session()
+        output = str(caught.exception) + "\n".join(c.args[0] for c in plugin.logger.call_args_list)
+        self.assertNotIn("synthetic-password", output)
+        self.assertEqual(page.clicked.count("submit"), 1)
+        self.assertEqual(page.refresh_calls, 0)
+        self.assertFalse(plugin.is_healthy)
+
+    def test_server_error_after_entry_does_not_refresh_or_submit(self):
+        page = ServerErrorPage()
+        plugin = self.setup_plugin(page)
+        with self.assertRaisesRegex(BizLogicError, "failed after login started"):
+            plugin.create_session()
+        self.assertEqual(page.clicked, ["login"])
+        self.assertEqual(page.input_values, {})
+        self.assertEqual(page.refresh_calls, 0)
+
+    def test_stale_dashboard_on_wrong_host_is_not_authentication(self):
+        page = FakePage()
+        page.URLS = {**page.URLS, "dashboard": "https://untrusted.example/UserArea"}
+        plugin = self.setup_plugin(page)
+        with self.assertRaisesRegex(BizLogicError, "left the expected website"):
+            plugin.create_session()
+        self.assertFalse(plugin.is_healthy)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 165 - 0
test/ita/test_ita_otp.py

@@ -0,0 +1,165 @@
+"""Italy-only cloud OTP contract: synthetic messages, no network or credentials."""
+import traceback
+from unittest import TestCase
+from unittest.mock import Mock
+
+from plugins import ita_plugin as otp
+from plugins.ita_plugin import CalendarGateError
+from plugins.ita_plugin import OtpMailConfig, ItaProtocolError, parse_otp_body, resolve_route_config
+from vs_types import BizLogicError, PermissionDeniedError, SessionExpiredOrInvalidError
+
+
+class OtpParserTests(TestCase):
+    def test_observed_marker_preserves_zero_and_deduplicates_mime_alternatives(self):
+        self.assertEqual(parse_otp_body('OTP Code:001234 <p>OTP Code: <b>001234</b></p>'), '001234')
+
+    def test_rejects_unknown_ambiguous_and_malformed_messages(self):
+        for body in (None, '', '123456', 'OTP Code:1234567', 'OTP Code:123456x',
+                     'OTP Code:123456', 'OTP Code:1234567',
+                     'OTP Code:123456 OTP Code:654321'):
+            with self.subTest(body=body), self.assertRaises(ItaProtocolError):
+                parse_otp_body(body)
+        with self.assertRaises(ItaProtocolError):
+            parse_otp_body('OTP Code:123456', max_chars=5)
+
+    def test_mail_filters_cannot_be_broadened(self):
+        for field, value in [('subject_keywords', 'OTP Code,anything'), ('body_keywords', 'Code'),
+                             ('expiry_seconds', True), ('expiry_seconds', 301)]:
+            with self.subTest(field=field), self.assertRaises(ItaProtocolError):
+                OtpMailConfig('mailbox@example.test', **{field: value})
+
+    def test_account_source_resolves_each_mailbox_without_mutating_shared_config(self):
+        config = OtpMailConfig(authorization_source="account")
+        for address in ("first@example.test", "second@example.test", "first@example.test"):
+            self.assertEqual(config.mailbox_for(address), address)
+            self.assertIsNone(config.authorization_email)
+            self.assertNotIn(address, repr(config))
+        self.assertEqual(config.authorization_source, "account")
+        with self.assertRaises(ItaProtocolError):
+            config.mailbox_for("not-an-email")
+
+    def test_mailbox_source_is_explicit_and_rejects_ambiguous_configuration(self):
+        for config in ({}, {"authorization_source": "unknown"}, {"authorization_source": None},
+                       {"authorization_source": "account", "authorization_email": "old@example.test"},
+                       {"authorization_source": "account", "authorization_email": ""}):
+            with self.subTest(config=config), self.assertRaises(ItaProtocolError):
+                OtpMailConfig(**config)
+        fixed = OtpMailConfig("shared@example.test")
+        self.assertEqual(fixed.mailbox_for("different@example.test"), "shared@example.test")
+
+    def test_route_parser_accepts_account_source_without_widening_sender_filters(self):
+        from test.ita.test_ita_protocol import live_route
+        route = live_route()
+        route["mail"] = {"authorization_source": "account"}
+        result = resolve_route_config({"slot.sample.it.tourist": route}, "slot.sample.it.tourist")
+        self.assertEqual(result.mail.mailbox_for("pooled@example.test"), "pooled@example.test")
+        for key, value in (("sender", "other@example.test"), ("subject_keywords", "anything"),
+                           ("body_keywords", "anything"), ("expiry_seconds", 301)):
+            with self.subTest(key=key), self.assertRaises(ItaProtocolError):
+                changed = {**route, "mail": {**route["mail"], key: value}}
+                resolve_route_config({"slot.sample.it.tourist": changed}, "slot.sample.it.tourist")
+
+
+class CloudOtpTests(TestCase):
+    def setUp(self):
+        self.config = OtpMailConfig('mailbox@example.test')
+        self.client = Mock()
+        self.client.fetch_mail_content.return_value = 'OTP Code:001234'
+
+    def fetch(self):
+        return otp.fetch_otp_from_cloud(self.config, recipient='applicant@example.test',
+            sent_at='2026-08-31 01:02:03', api=self.client)
+
+    def test_exact_sdk_call_and_no_top_fallback(self):
+        self.assertEqual(self.fetch(), '001234')
+        self.client.fetch_mail_content.assert_called_once_with(
+            email='mailbox@example.test', sender='noreply-prenotami@esteri.it',
+            recipient='applicant@example.test', subject_keywords='OTP Code',
+            body_keywords='OTP Code:', sent_date='2026-08-31 01:02:03', expiry=300, only_text=True)
+        self.client.fetch_mail_content_from_top.assert_not_called()
+
+    def test_account_source_uses_each_actual_account_for_mailbox_and_recipient(self):
+        config = OtpMailConfig(authorization_source="account")
+        for address in ("first@example.test", "second@example.test", "first@example.test"):
+            with self.subTest(address=address):
+                self.client.reset_mock()
+                self.assertEqual(otp.fetch_otp_from_cloud(config, recipient=address,
+                    sent_at="2026-08-31 01:02:03", api=self.client), "001234")
+                self.client.fetch_mail_content.assert_called_once_with(
+                    email=address, recipient=address, sender="noreply-prenotami@esteri.it",
+                    subject_keywords="OTP Code", body_keywords="OTP Code:",
+                    sent_date="2026-08-31 01:02:03", expiry=300, only_text=True)
+                self.client.fetch_mail_content_from_top.assert_not_called()
+                self.assertIsNone(config.authorization_email)
+
+    def test_account_mailbox_failure_does_not_read_another_inbox(self):
+        config = OtpMailConfig(authorization_source="account")
+        self.client.fetch_mail_content.side_effect = PermissionDeniedError("private-provider-details")
+        with self.assertRaisesRegex(CalendarGateError, "not permitted"):
+            otp.fetch_otp_from_cloud(config, recipient="second@example.test",
+                sent_at="2026-08-31 01:02:03", api=self.client)
+        self.client.fetch_mail_content.assert_called_once()
+        self.assertEqual(self.client.fetch_mail_content.call_args.kwargs["email"], "second@example.test")
+        self.client.fetch_mail_content_from_top.assert_not_called()
+
+    def test_mail_environment_validation_has_no_logger_policy(self):
+        self.assertEqual(
+            otp.validate_cloud_otp_environment(self.config, ' applicant@example.test '),
+            'applicant@example.test',
+        )
+        self.client.fetch_mail_content.assert_not_called()
+
+    def test_provider_failures_are_redacted_and_not_site_session_errors(self):
+        marker = 'PRIVATE_MAIL_CONTENT_001234'
+        for error in (BizLogicError(marker), PermissionDeniedError(marker),
+                      SessionExpiredOrInvalidError(marker), ValueError(marker), TimeoutError(marker)):
+            self.client.reset_mock()
+            self.client.fetch_mail_content.side_effect = error
+            with self.subTest(error=type(error).__name__):
+                with self.assertRaises(CalendarGateError) as caught:
+                    self.fetch()
+                rendered = ''.join(traceback.format_exception(caught.exception))
+                self.assertNotIn(marker, rendered)
+                self.client.fetch_mail_content.assert_called_once()
+                self.client.fetch_mail_content_from_top.assert_not_called()
+
+    def test_invalid_input_never_reads_mail(self):
+        with self.assertRaises(CalendarGateError):
+            otp.fetch_otp_from_cloud(self.config, recipient='not-an-address', sent_at='invalid', api=self.client)
+        self.client.fetch_mail_content.assert_not_called()
+
+    def test_real_sdk_contract_with_fake_transport(self):
+        # Exercise the actual VFS/BLS shared SDK without its singleton settings
+        # or any external HTTP. Neither existing SDK nor global log state is edited.
+        client = object.__new__(otp.VSCloudApi)
+        client.base_url = "https://mail.example.test"
+        client.api_token = "synthetic-only"
+        client.session = Mock()
+        for status in (200, 401, 403, 429, 504):
+            with self.subTest(status=status):
+                response = Mock(status_code=status, text="PRIVATE_MAIL OTP Code:001234")
+                response.json.return_value = {"code": 0, "data": {"body": "OTP Code:001234"}}
+                client.session.request.reset_mock()
+                client.session.request.return_value = response
+                if status == 200:
+                    self.assertEqual(otp.fetch_otp_from_cloud(self.config,
+                        recipient="applicant@example.test", sent_at="2026-08-31 01:02:03", api=client), "001234")
+                else:
+                    with self.assertRaises(CalendarGateError) as raised:
+                        otp.fetch_otp_from_cloud(self.config, recipient="applicant@example.test",
+                                                sent_at="2026-08-31 01:02:03", api=client)
+                    rendered = ''.join(traceback.format_exception(raised.exception))
+                    self.assertNotIn("PRIVATE_MAIL", rendered)
+                    self.assertNotIn("001234", rendered)
+                client.session.request.assert_called_once()
+                args = client.session.request.call_args.kwargs
+                self.assertEqual(args["params"]["sentDate"], "2026-08-31 01:02:03")
+                self.assertEqual(args["params"]["expiry"], "300")
+                self.assertEqual(args["timeout"], 300)
+    def test_bad_mail_body_is_rejected_without_fallback(self):
+        for body in (None, "unknown template", "OTP Code:123456 OTP Code:654321"):
+            with self.subTest(body=body):
+                self.client.fetch_mail_content.return_value = body
+                with self.assertRaises(CalendarGateError):
+                    self.fetch()
+                self.client.fetch_mail_content_from_top.assert_not_called()

+ 1292 - 0
test/ita/test_ita_plugin.py

@@ -0,0 +1,1292 @@
+import inspect
+import json
+import sys
+import threading
+import types
+import unittest
+from dataclasses import replace
+from datetime import date
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest.mock import Mock, patch
+
+from plugins.ita_plugin import (
+    BOOKING_FORM_DISCOVERY_STOP_LABEL,
+    BOOKING_RECHECK_NONE_AVAILABLE_LABEL,
+    SERVICE_LINK_WAIT_SECONDS,
+    ItaAuthenticationChallengeError,
+    ItaPlugin,
+    ItaTargetServiceLinkMissingError,
+)
+
+try:
+    from booker import OrderBookerGCO
+except ModuleNotFoundError as exc:
+    if exc.name != "redis":
+        raise
+    redis_stub = types.ModuleType("redis")
+    redis_stub.Redis = Mock
+    with patch.dict(sys.modules, {"redis": redis_stub}):
+        from booker import OrderBookerGCO
+from vs_types import (
+    AppointmentType,
+    AvailabilityStatus,
+    BizLogicError,
+    GroupConfig,
+    SessionExpiredOrInvalidError,
+    Task,
+    VSAccount,
+    VSPlgConfig,
+    VSQueryResult,
+)
+
+
+class FakeChromiumOptions:
+    def set_local_port(self, _port):
+        return self
+
+    def set_user_data_path(self, _path):
+        return self
+
+    def set_paths(self, **_kwargs):
+        return self
+
+    def set_argument(self, _argument):
+        return self
+
+    def headless(self, _enabled):
+        return self
+
+
+class FakeWait:
+    def doc_loaded(self):
+        return None
+
+    def load_start(self):
+        return None
+
+
+class FakeRect:
+    viewport_size = (1920, 1080)
+
+
+class FakeElement:
+    def __init__(self, page, name):
+        self.page = page
+        self.name = name
+
+    def input(self, value, clear=False):
+        self.page.input_values[self.name] = {
+            "value": value,
+            "clear": clear,
+        }
+
+
+class FakePage:
+    URLS = {
+        "landing": "https://prenotami.esteri.it/",
+        "pingid": (
+            "https://iam.esteri.it/signin/?realm=/external"
+            "&state=sensitive-state"
+            "&code_challenge=sensitive-challenge#/"
+        ),
+        "dashboard": "https://prenotami.esteri.it/UserArea",
+        "services": "https://prenotami.esteri.it/Services",
+        "radware": (
+            "https://validate.perfdrive.com/"
+            "8ab9454422ad153e7d4ce3a5b41556a7/"
+        ),
+    }
+
+    def __init__(
+        self,
+        *,
+        submit_succeeds=True,
+        has_services_link=True,
+        login_target="pingid",
+    ):
+        self.state = "landing"
+        self.submit_succeeds = submit_succeeds
+        self.has_services_link = has_services_link
+        self.login_target = login_target
+        self.wait = FakeWait()
+        self.rect = FakeRect()
+        self.clicked = []
+        self.input_values = {}
+        self.refresh_calls = 0
+        self.quit_called = False
+        self.quit_force = None
+
+    @property
+    def url(self):
+        return self.URLS[self.state]
+
+    @property
+    def title(self):
+        return {
+            "landing": "Login",
+            "pingid": "Sign in",
+            "dashboard": "Home",
+            "services": "Services",
+            "radware": "Access Denied",
+        }[self.state]
+
+    @property
+    def html(self):
+        return ""
+
+    def get(self, _url):
+        self.state = "landing"
+
+    def refresh(self):
+        self.refresh_calls += 1
+
+    def quit(self, force=False):
+        self.quit_called = True
+        self.quit_force = force
+
+    def ele(self, selector, timeout=None):
+        del timeout
+        if selector == "tag:a@@href=/Language/ChangeLanguage?lang=2":
+            return FakeElement(self, "language") if self.state == "landing" else None
+        if selector == "#pingid-button" and self.state == "landing":
+            return FakeElement(self, "login")
+        if selector == "@name=callback_1" and self.state == "pingid":
+            return FakeElement(self, "username")
+        if selector == "@name=callback_2" and self.state == "pingid":
+            return FakeElement(self, "password")
+        if selector == "tag:button@type=submit" and self.state == "pingid":
+            return FakeElement(self, "submit")
+        if selector == ".app-menu" and self.state == "dashboard":
+            return FakeElement(self, "app-menu")
+        if (
+            selector == "@href=/Services"
+            and self.state == "dashboard"
+            and self.has_services_link
+        ):
+            return FakeElement(self, "book")
+        return None
+
+
+class FakeMouse:
+    def __init__(self, page, debug=False):
+        self.page = page
+        self.debug = debug
+
+    def move(self, _x, _y):
+        return None
+
+    def human_click_ele(self, element):
+        if element is None:
+            raise AssertionError("The state machine attempted to click a missing element")
+        self.page.clicked.append(element.name)
+        if element.name == "login":
+            self.page.state = self.page.login_target
+        elif element.name == "submit" and self.page.submit_succeeds:
+            self.page.state = "dashboard"
+        elif element.name == "book":
+            self.page.state = "services"
+
+
+class FakeKeyboard:
+    def __init__(self, page):
+        self.page = page
+
+
+class FakeQueryWait:
+    def __init__(self):
+        self.load_start_calls = 0
+        self.doc_loaded_calls = 0
+
+    def load_start(self):
+        self.load_start_calls += 1
+
+    def doc_loaded(self):
+        self.doc_loaded_calls += 1
+
+
+class FakeQueryElement:
+    def __init__(
+        self,
+        page,
+        name,
+        attributes=None,
+        *,
+        text="",
+        property_value=None,
+    ):
+        self.page = page
+        self.name = name
+        self.attributes = attributes or {}
+        self.text = text
+        self.value = property_value
+
+    def attr(self, name):
+        return self.attributes.get(name)
+
+
+class FakeQueryPage:
+    URLS = {
+        "services": "https://prenotami.esteri.it/Services",
+        "user_area": "https://prenotami.esteri.it/UserArea",
+        "no_slots": "https://prenotami.esteri.it/Services",
+        "property_no_slots": "https://prenotami.esteri.it/Services",
+        "visible_no_slots": "https://prenotami.esteri.it/Services",
+        "unknown_popup": "https://prenotami.esteri.it/Services",
+        "empty_warning": "https://prenotami.esteri.it/Services",
+        "login": "https://iam.esteri.it/login/oauth2/authorize",
+        "calendar": "https://prenotami.esteri.it/BookingCalendar",
+        "unknown": "https://prenotami.esteri.it/Unexpected",
+    }
+
+    def __init__(
+        self,
+        outcome="no_slots",
+        *,
+        has_link=True,
+        initial_state="services",
+        service_id=1321,
+        already_booked_notice_rows=0,
+    ):
+        self.outcome = outcome
+        self.has_link = has_link
+        self.state = initial_state
+        self.service_id = service_id
+        self.already_booked_notice_rows = already_booked_notice_rows
+        self.wait = FakeQueryWait()
+        self.clicked = []
+        self.get_calls = []
+        self.looked_up = []
+        self.run_js_calls = []
+        self.tab_id = "query-fixture-tab"
+
+    @property
+    def url(self):
+        if self.state in {"booking_form", "booking_path_without_form"}:
+            return (
+                "https://prenotami.esteri.it/Services/Booking/"
+                f"{self.service_id}"
+            )
+        return self.URLS[self.state]
+
+    def get(self, url):
+        self.get_calls.append(url)
+        if url != "https://prenotami.esteri.it/Services":
+            raise AssertionError(f"Unexpected query navigation: {url}")
+        self.state = "services"
+
+    def run_js(self, script):
+        self.run_js_calls.append(script)
+        if "coordinate:ita-book-runtime-service" in script:
+            return {"path": "/BookingCalendar", "count": 1, "value": str(self.service_id)}
+        if "coordinate:ita-service-list-structure" in script:
+            return {
+                "path": "/Services",
+                "ready_state": "complete",
+                "table_count": 1,
+                "row_count": 0,
+                "booking_link_count": 0,
+                "target_link_count": 0,
+                "already_booked_notice_row_count": self.already_booked_notice_rows,
+            }
+        if self.state != "booking_form":
+            return None
+        return {
+            "path": f"/Services/Booking/{self.service_id}",
+            "form": {
+                "method": "POST",
+                "action_path": f"/Services/Booking/{self.service_id}",
+                "untrusted": "must-not-survive",
+            },
+            "field_count": 2,
+            "fields_truncated": False,
+            "fields": [
+                {
+                    "tag": "input",
+                    "type": "hidden",
+                    "id": "RequestToken",
+                    "name": "__RequestVerificationToken",
+                    "required": False,
+                    "value": "must-not-survive",
+                },
+                {
+                    "tag": "select",
+                    "type": None,
+                    "id": "BookingType",
+                    "name": "BookingType",
+                    "required": True,
+                },
+            ],
+            "button_count": 1,
+            "buttons_truncated": False,
+            "buttons": [
+                {
+                    "tag": "button",
+                    "type": "submit",
+                    "id": "btnAvanti",
+                    "name": None,
+                    "text": "Avanti",
+                    "value": "must-not-survive",
+                }
+            ],
+            "untrusted": "must-not-survive",
+        }
+
+    def ele(self, selector, timeout=None):
+        self.looked_up.append((selector, timeout))
+        if selector == "#pingid-button" and self.state == "login":
+            return FakeQueryElement(self, "login")
+        if (
+            selector
+            == f"tag:a@@href=/Services/Booking/{self.service_id}"
+            and self.state == "services"
+            and self.has_link
+        ):
+            return FakeQueryElement(self, f"booking-{self.service_id}")
+        if selector == "#WNotAvailable" and self.state == "no_slots":
+            return FakeQueryElement(
+                self,
+                "not-available",
+                {"value": "No appointments are currently available."},
+            )
+        if selector == "#WNotAvailable" and self.state == "property_no_slots":
+            return FakeQueryElement(
+                self,
+                "property-not-available",
+                property_value="No appointments are currently available.",
+            )
+        if selector == "#WNotAvailable" and self.state == "empty_warning":
+            return FakeQueryElement(self, "empty-warning", {"value": "  "})
+        if selector == ".jconfirm-content" and self.state == "visible_no_slots":
+            return FakeQueryElement(
+                self,
+                "visible-not-available",
+                text=(
+                    "  STANTE L’ELEVATA RICHIESTA\n"
+                    "i posti disponibili per il servizio scelto sono esauriti.  "
+                ),
+            )
+        if selector == ".jconfirm-content" and self.state == "unknown_popup":
+            return FakeQueryElement(
+                self,
+                "unknown-popup",
+                text="Il servizio richiede una nuova verifica.",
+            )
+        if selector == "#bookingForm" and self.state == "booking_form":
+            return FakeQueryElement(self, "booking-form")
+        return None
+
+
+class FakeQueryMouse:
+    def __init__(self, page):
+        self.page = page
+
+    def human_click_ele(self, element):
+        if element is None:
+            raise AssertionError("Query attempted to click a missing element")
+        self.page.clicked.append(element.name)
+        self.page.state = self.page.outcome
+
+
+class ItaPluginRandomSleepTests(unittest.TestCase):
+    def test_random_sleep_uses_generated_duration_within_requested_range(self):
+        plugin = ItaPlugin.__new__(ItaPlugin)
+        plugin.group_id = "test-group"
+        plugin.logger = Mock()
+        plugin.page = None
+        plugin.root_workspace = "/nonexistent/ita-plugin-unit-test"
+        plugin.tunnel = None
+
+        with (
+            patch("plugins.ita_plugin.random.uniform", return_value=4.25) as uniform,
+            patch("plugins.ita_plugin.time.sleep") as sleep,
+        ):
+            plugin._random_sleep(3, 5)
+
+        uniform.assert_called_once_with(3, 5)
+        sleep.assert_called_once_with(4.25)
+        plugin.logger.assert_called_once_with(
+            "[ItaPlugin] [test-group] "
+            "Anti-Rate-Limit: Sleeping for 4.25 seconds..."
+        )
+
+
+class ItaPluginCreateSessionStateMachineTests(unittest.TestCase):
+    @staticmethod
+    def _config():
+        return VSPlgConfig(
+            account=VSAccount(
+                id=0,
+                username="offline-test@example.test",
+                password="offline-password",
+            )
+        )
+
+    def test_stops_at_authenticated_user_area_without_opening_services(self):
+        fake_page = FakePage()
+        config = self._config()
+        logger = Mock()
+
+        with TemporaryDirectory() as workspace:
+            with patch(
+                "plugins.ita_plugin.os.path.abspath",
+                return_value=str(Path(workspace)),
+            ):
+                plugin = ItaPlugin("offline-state-machine")
+            plugin.set_log(logger)
+            plugin.set_config(config)
+
+            with (
+                patch("utils.plugin_utils.ChromiumOptions", FakeChromiumOptions),
+                patch("plugins.ita_plugin.ChromiumPage", return_value=fake_page),
+                patch("plugins.ita_plugin.HumanMouse", FakeMouse),
+                patch("plugins.ita_plugin.HumanKeyboard", FakeKeyboard),
+                patch("plugins.ita_plugin.time.sleep"),
+            ):
+                try:
+                    plugin.create_session()
+                finally:
+                    plugin.cleanup()
+
+        self.assertEqual(fake_page.state, "dashboard")
+        self.assertGreater(plugin.session_create_time, 0)
+        self.assertEqual(
+            fake_page.clicked,
+            ["login", "username", "password", "submit"],
+        )
+        self.assertEqual(
+            fake_page.input_values,
+            {
+                "username": {
+                    "value": "offline-test@example.test",
+                    "clear": True,
+                },
+                "password": {
+                    "value": "offline-password",
+                    "clear": True,
+                },
+            },
+        )
+        self.assertEqual(fake_page.refresh_calls, 0)
+        self.assertTrue(fake_page.quit_called)
+
+        log_output = "\n".join(
+            call.args[0] for call in logger.call_args_list if call.args
+        )
+        self.assertIn("Entering username", log_output)
+        self.assertIn("Successfully reached authenticated /UserArea", log_output)
+
+    def test_never_resubmits_credentials_or_refreshes_after_login_submission(self):
+        fake_page = FakePage(submit_succeeds=False)
+        config = self._config()
+
+        with TemporaryDirectory() as workspace:
+            with patch(
+                "plugins.ita_plugin.os.path.abspath",
+                return_value=str(Path(workspace)),
+            ):
+                plugin = ItaPlugin("offline-stalled-login")
+            plugin.set_log(Mock())
+            plugin.set_config(config)
+
+            with (
+                patch("utils.plugin_utils.ChromiumOptions", FakeChromiumOptions),
+                patch("plugins.ita_plugin.ChromiumPage", return_value=fake_page),
+                patch("plugins.ita_plugin.HumanMouse", FakeMouse),
+                patch("plugins.ita_plugin.HumanKeyboard", FakeKeyboard),
+                patch("plugins.ita_plugin.time.sleep"),
+            ):
+                try:
+                    with self.assertRaisesRegex(
+                        BizLogicError,
+                        "Failed to create authenticated /UserArea session",
+                    ):
+                        plugin.create_session()
+                finally:
+                    plugin.cleanup()
+
+        self.assertEqual(fake_page.clicked.count("login"), 1)
+        self.assertEqual(fake_page.clicked.count("username"), 1)
+        self.assertEqual(fake_page.clicked.count("password"), 1)
+        self.assertEqual(fake_page.clicked.count("submit"), 1)
+        self.assertEqual(fake_page.refresh_calls, 0)
+
+    def test_requires_user_area_services_link_as_authentication_marker(self):
+        fake_page = FakePage(has_services_link=False)
+        config = self._config()
+
+        with TemporaryDirectory() as workspace:
+            with patch(
+                "plugins.ita_plugin.os.path.abspath",
+                return_value=str(Path(workspace)),
+            ):
+                plugin = ItaPlugin("offline-incomplete-dashboard")
+            plugin.set_log(Mock())
+            plugin.set_config(config)
+
+            with (
+                patch("utils.plugin_utils.ChromiumOptions", FakeChromiumOptions),
+                patch("plugins.ita_plugin.ChromiumPage", return_value=fake_page),
+                patch("plugins.ita_plugin.HumanMouse", FakeMouse),
+                patch("plugins.ita_plugin.HumanKeyboard", FakeKeyboard),
+                patch("plugins.ita_plugin.time.sleep"),
+            ):
+                try:
+                    with self.assertRaisesRegex(
+                        BizLogicError,
+                        "Failed to create authenticated /UserArea session",
+                    ):
+                        plugin.create_session()
+                finally:
+                    plugin.cleanup()
+
+        self.assertEqual(fake_page.state, "dashboard")
+        self.assertEqual(fake_page.clicked.count("submit"), 1)
+
+    def test_create_session_source_has_no_language_or_services_navigation(self):
+        create_session_source = inspect.getsource(ItaPlugin.create_session)
+
+        self.assertNotIn("ChangeLanguage", create_session_source)
+        self.assertNotIn("book_btn", create_session_source)
+
+    def test_radware_validation_is_classified_before_credentials_or_refresh(self):
+        fake_page = FakePage(login_target="radware")
+        config = self._config()
+        logger = Mock()
+
+        with TemporaryDirectory() as workspace:
+            with patch(
+                "plugins.ita_plugin.os.path.abspath",
+                return_value=str(Path(workspace)),
+            ):
+                plugin = ItaPlugin("offline-radware")
+            plugin.set_log(logger)
+            plugin.set_config(config)
+
+            with (
+                patch("utils.plugin_utils.ChromiumOptions", FakeChromiumOptions),
+                patch("plugins.ita_plugin.ChromiumPage", return_value=fake_page),
+                patch("plugins.ita_plugin.HumanMouse", FakeMouse),
+                patch("plugins.ita_plugin.HumanKeyboard", FakeKeyboard),
+                patch("plugins.ita_plugin.time.sleep"),
+            ):
+                try:
+                    with self.assertRaisesRegex(
+                        ItaAuthenticationChallengeError,
+                        "Radware browser validation",
+                    ):
+                        plugin.create_session()
+                finally:
+                    plugin.cleanup()
+
+        self.assertEqual(fake_page.clicked, ["login"])
+        self.assertEqual(fake_page.input_values, {})
+        self.assertEqual(fake_page.refresh_calls, 0)
+        self.assertTrue(any("@radware" in call.args[0] for call in logger.call_args_list))
+
+
+class ItaPluginQuerySafetyTests(unittest.TestCase):
+    @staticmethod
+    def _appointment_type(
+        routing_key="slot.dub.it.tourist",
+        *,
+        city="Dublin",
+    ):
+        return AppointmentType(
+            routing_key=routing_key,
+            city=city,
+            country="Italy",
+            visa_type="Tourist",
+        )
+
+    @staticmethod
+    def _plugin(
+        page,
+        *,
+        service_id=1321,
+        routing_key="slot.dub.it.tourist",
+        query_mode="services_probe",
+        capability="services_probe_only",
+        lookahead_months=3,
+    ):
+        plugin = ItaPlugin.__new__(ItaPlugin)
+        plugin.group_id = "offline-query"
+        plugin.logger = Mock()
+        plugin.page = page
+        plugin.mouse = FakeQueryMouse(page)
+        route = {
+            "service_id": service_id,
+            "capability": capability,
+        }
+        if capability == "single_schengen_tourism":
+            route.update(
+                {
+                    "calendar_scan": {
+                        "lookahead_months": lookahead_months,
+                    },
+                    "form": {
+                        "booking_type_control_id": "typeofbookingddl",
+                        "booking_type_value": "1",
+                        "booking_type_labels": ["Single booking"],
+                        "purpose_control_id": "ddls_0",
+                        "purpose_value": "42",
+                        "purpose_labels": ["Tourism"],
+                    },
+                }
+            )
+        plugin.free_config = {
+            "query_mode": query_mode,
+            "final_submit_enabled": False,
+            "apt_configs": {
+                routing_key: route,
+            },
+        }
+        plugin.ita_url = "https://prenotami.esteri.it"
+        plugin.root_workspace = "/nonexistent/ita-plugin-query-test"
+        plugin.tunnel = None
+        plugin.is_healthy = True
+        plugin.session_create_time = 111.0
+        plugin.config = VSPlgConfig(account=VSAccount(username="query@example.test"), free_config=plugin.free_config)
+        plugin._reset_calendar_state()
+        if (page is not None and query_mode == "calendar" and capability == "single_schengen_tourism"
+                and page.url.startswith("https://prenotami.esteri.it/BookingCalendar")):
+            plugin._record_calendar_prepared_route(
+                plugin._resolve_route(AppointmentType(routing_key=routing_key)), role="query")
+        return plugin
+
+    def test_returns_none_available_only_for_non_empty_w_not_available(self):
+        page = FakeQueryPage(outcome="no_slots")
+        plugin = self._plugin(page)
+        apt_type = self._appointment_type()
+
+        result = plugin._enter_service(apt_type)
+
+        self.assertFalse(result.success)
+        self.assertEqual(result.availability_status, AvailabilityStatus.NoneAvailable)
+        self.assertEqual(result.apt_type, apt_type)
+        self.assertEqual(page.clicked, ["booking-1321"])
+        self.assertEqual(page.wait.load_start_calls, 1)
+        self.assertEqual(page.wait.doc_loaded_calls, 2)
+
+    def test_returns_none_available_for_property_only_w_not_available(self):
+        page = FakeQueryPage(outcome="property_no_slots")
+        plugin = self._plugin(page)
+
+        result = plugin._enter_service(self._appointment_type())
+
+        self.assertFalse(result.success)
+        self.assertEqual(result.availability_status, AvailabilityStatus.NoneAvailable)
+        self.assertEqual(page.clicked, ["booking-1321"])
+
+    def test_returns_none_available_for_verified_visible_italian_notice(self):
+        page = FakeQueryPage(outcome="visible_no_slots")
+        plugin = self._plugin(page)
+
+        result = plugin._enter_service(self._appointment_type())
+
+        self.assertFalse(result.success)
+        self.assertEqual(result.availability_status, AvailabilityStatus.NoneAvailable)
+        self.assertEqual(page.clicked, ["booking-1321"])
+
+    def test_unknown_visible_notice_fails_closed(self):
+        page = FakeQueryPage(outcome="unknown_popup")
+        plugin = self._plugin(page)
+
+        with self.assertRaisesRegex(BizLogicError, "unrecognized visible"):
+            plugin._enter_service(self._appointment_type())
+
+        self.assertEqual(page.clicked, ["booking-1321"])
+
+    def test_changed_notice_is_not_guessed_as_no_availability(self):
+        plugin = self._plugin(FakeQueryPage())
+
+        status = plugin._classify_service_notice(
+            "I posti disponibili per il servizio scelto non sono esauriti."
+        )
+
+        self.assertIsNone(status)
+
+    def test_reloads_services_before_each_no_slot_probe(self):
+        page = FakeQueryPage(outcome="no_slots")
+        plugin = self._plugin(page)
+        apt_type = self._appointment_type()
+
+        first_result = plugin._enter_service(apt_type)
+        second_result = plugin._enter_service(apt_type)
+
+        self.assertFalse(first_result.success)
+        self.assertFalse(second_result.success)
+        self.assertEqual(
+            page.get_calls,
+            [
+                "https://prenotami.esteri.it/Services",
+                "https://prenotami.esteri.it/Services",
+            ],
+        )
+        self.assertEqual(page.clicked, ["booking-1321", "booking-1321"])
+        self.assertEqual(page.wait.load_start_calls, 2)
+        self.assertEqual(page.wait.doc_loaded_calls, 4)
+
+    def test_empty_w_not_available_is_not_treated_as_no_slots(self):
+        page = FakeQueryPage(outcome="empty_warning")
+        plugin = self._plugin(page)
+
+        with self.assertRaisesRegex(BizLogicError, "non-empty"):
+            plugin._enter_service(self._appointment_type())
+
+        self.assertEqual(page.clicked, ["booking-1321"])
+
+    def test_internal_entry_reports_form_without_inventory(self):
+        page = FakeQueryPage(outcome="booking_form")
+        plugin = self._plugin(page)
+
+        result = plugin._enter_service(self._appointment_type())
+
+        self.assertTrue(result.success)
+        self.assertEqual(result.availability_status, AvailabilityStatus.NoneAvailable)
+        self.assertIsNone(result.earliest_date)
+        self.assertEqual(result.availability, [])
+        self.assertEqual(page.clicked, ["booking-1321"])
+
+    def test_internal_entry_can_be_reprobed_without_publishing_inventory(self):
+        page = FakeQueryPage(outcome="booking_form")
+        plugin = self._plugin(page)
+        apt_type = self._appointment_type()
+
+        first_result = plugin._enter_service(apt_type)
+        second_result = plugin._enter_service(apt_type)
+
+        self.assertTrue(first_result.success)
+        self.assertTrue(second_result.success)
+        self.assertEqual(
+            page.get_calls,
+            [
+                "https://prenotami.esteri.it/Services",
+                "https://prenotami.esteri.it/Services",
+            ],
+        )
+        self.assertEqual(page.clicked, ["booking-1321", "booking-1321"])
+
+    def test_booking_path_without_form_fails_closed(self):
+        page = FakeQueryPage(outcome="booking_path_without_form")
+        plugin = self._plugin(page)
+
+        with self.assertRaisesRegex(BizLogicError, "without #bookingForm"):
+            plugin._enter_service(self._appointment_type())
+
+        self.assertEqual(page.clicked, ["booking-1321"])
+
+    def test_missing_target_link_is_a_structure_error_not_no_slots(self):
+        page = FakeQueryPage(has_link=False)
+        plugin = self._plugin(page)
+
+        with self.assertRaisesRegex(
+            ItaTargetServiceLinkMissingError,
+            "target service link is missing",
+        ):
+            plugin._enter_service(self._appointment_type())
+
+        self.assertEqual(page.clicked, [])
+        self.assertIn(
+            ("tag:a@@href=/Services/Booking/1321", SERVICE_LINK_WAIT_SECONDS),
+            page.looked_up,
+        )
+        self.assertFalse(any("service-list-structure" in script for script in page.run_js_calls))
+
+    def test_missing_link_with_page_notice_is_not_attributed_to_the_target(self):
+        page = FakeQueryPage(has_link=False, already_booked_notice_rows=1)
+        plugin = self._plugin(page)
+
+        with self.assertRaises(ItaTargetServiceLinkMissingError) as raised:
+            plugin._enter_service(self._appointment_type())
+
+        self.assertIn("target service link is missing", str(raised.exception))
+        self.assertNotIn("already-booked notice", str(raised.exception))
+        self.assertFalse(any("service-list-structure" in script for script in page.run_js_calls))
+        self.assertEqual(page.clicked, [])
+        self.assertEqual(page.get_calls, ["https://prenotami.esteri.it/Services"])
+
+    def test_existing_other_service_booking_does_not_block_present_target_link(self):
+        page = FakeQueryPage(outcome="booking_form", already_booked_notice_rows=1)
+        plugin = self._plugin(page)
+
+        result = plugin._enter_service(self._appointment_type())
+
+        self.assertTrue(result.success)
+        self.assertEqual(page.clicked, ["booking-1321"])
+        self.assertFalse(any("service-list-structure" in script for script in page.run_js_calls))
+
+    def test_invalid_notice_counts_do_not_claim_an_existing_booking(self):
+        for raw_count in (None, True, "1", -1, {}, []):
+            with self.subTest(raw_count=raw_count):
+                page = FakeQueryPage(has_link=False, already_booked_notice_rows=raw_count)
+                plugin = self._plugin(page)
+                with self.assertRaises(ItaTargetServiceLinkMissingError) as raised:
+                    plugin._enter_service(self._appointment_type())
+                self.assertNotIn("already-booked notice", str(raised.exception))
+                self.assertEqual(page.clicked, [])
+
+    def test_book_propagates_missing_link_without_creating_a_success(self):
+        page = FakeQueryPage(has_link=False, already_booked_notice_rows=1)
+        plugin = self._plugin(page)
+        trigger = VSQueryResult(apt_type=self._appointment_type())
+
+        with self.assertRaisesRegex(ItaTargetServiceLinkMissingError, "target service link is missing"):
+            plugin.book(trigger)
+
+        self.assertEqual(page.clicked, [])
+
+    def test_invalid_route_service_id_is_a_configuration_error(self):
+        page = FakeQueryPage()
+        plugin = self._plugin(page, service_id=0)
+
+        with self.assertRaisesRegex(
+            BizLogicError,
+            "route configuration rejected.*positive_integer_required",
+        ):
+            plugin._enter_service(self._appointment_type())
+
+        self.assertEqual(page.clicked, [])
+
+    def test_second_sede_uses_same_entry_without_a_city_branch(self):
+        routing_key = "slot.hkg.it.tourist"
+        page = FakeQueryPage(
+            outcome="booking_form",
+            service_id=4937,
+        )
+        plugin = self._plugin(
+            page,
+            service_id=4937,
+            routing_key=routing_key,
+        )
+
+        result = plugin._enter_service(
+            self._appointment_type(routing_key, city="Hong Kong")
+        )
+
+        self.assertTrue(result.success)
+        self.assertEqual(page.clicked, ["booking-4937"])
+
+    def test_public_query_rejects_legacy_probe_before_browser_actions(self):
+        for mode in (None, "services_probe"):
+            for capability in ("services_probe_only", "single_schengen_tourism"):
+                with self.subTest(mode=mode, capability=capability):
+                    page = FakeQueryPage(outcome="booking_form")
+                    plugin = self._plugin(page, capability=capability)
+                    if mode is None:
+                        plugin.free_config.pop("query_mode")
+                    with self.assertRaisesRegex(BizLogicError, "diagnostic-only"):
+                        plugin.query(self._appointment_type())
+                    self.assertEqual(page.get_calls, [])
+                    self.assertEqual(page.clicked, [])
+                    self.assertEqual(page.run_js_calls, [])
+
+    def test_calendar_mode_returns_vfs_style_earliest_date_only(self):
+        routing_key = "slot.sample.it.tourist"
+        page = FakeQueryPage(initial_state="calendar", service_id=9001)
+        plugin = self._plugin(
+            page,
+            service_id=9001,
+            routing_key=routing_key,
+            query_mode="calendar",
+            capability="single_schengen_tourism",
+            lookahead_months=12,
+        )
+        apt_type = self._appointment_type(
+            routing_key,
+            city="Sample City",
+        )
+        scan = (types.SimpleNamespace(
+            available_days=(types.SimpleNamespace(day=date(2026, 10, 12)),)
+        ),)
+
+        with patch(
+            "plugins.ita_plugin.scan_until_first_available_month",
+            return_value=scan,
+        ) as scanner:
+            result = plugin.query(apt_type)
+
+        scanner.assert_called_once_with(
+            page,
+            lookahead_months=12,
+            log=plugin._log,
+        )
+        self.assertTrue(result.success)
+        self.assertEqual(
+            result.availability_status,
+            AvailabilityStatus.Available,
+        )
+        self.assertEqual(
+            result.earliest_date.strftime("%Y-%m-%d"),
+            "2026-10-12",
+        )
+        self.assertEqual(len(result.availability), 1)
+        self.assertEqual(
+            result.availability[0].date.strftime("%Y-%m-%d"),
+            "2026-10-12",
+        )
+        self.assertEqual(result.availability[0].times, [])
+        self.assertEqual(page.clicked, [])
+        self.assertFalse(hasattr(plugin, "last_calendar_query_scan"))
+
+    def test_failed_query_does_not_create_diagnostic_state(self):
+        routing_key = "slot.sample.it.tourist"
+        page = FakeQueryPage(initial_state="calendar", service_id=9001)
+        plugin = self._plugin(
+            page,
+            service_id=9001,
+            routing_key=routing_key,
+            query_mode="calendar",
+            capability="single_schengen_tourism",
+        )
+        plugin._prepared_calendar = None
+
+        with self.assertRaisesRegex(BizLogicError, "identity or route"):
+            plugin.query(self._appointment_type(routing_key, city="Sample City"))
+
+        self.assertFalse(hasattr(plugin, "last_calendar_query_scan"))
+
+    def test_calendar_mode_returns_none_only_after_scanner_exhaustion(self):
+        routing_key = "slot.sample.it.tourist"
+        page = FakeQueryPage(initial_state="calendar", service_id=9001)
+        plugin = self._plugin(
+            page,
+            service_id=9001,
+            routing_key=routing_key,
+            query_mode="calendar",
+            capability="single_schengen_tourism",
+        )
+        apt_type = self._appointment_type(
+            routing_key,
+            city="Sample City",
+        )
+
+        with patch(
+            "plugins.ita_plugin.scan_until_first_available_month",
+            return_value=(types.SimpleNamespace(available_days=()),),
+        ):
+            result = plugin.query(apt_type)
+
+        self.assertFalse(result.success)
+        self.assertEqual(
+            result.availability_status,
+            AvailabilityStatus.NoneAvailable,
+        )
+        self.assertIsNone(result.earliest_date)
+        self.assertEqual(result.availability, [])
+
+    def test_calendar_mode_requires_a_route_confirmed_calendar_session(self):
+        routing_key = "slot.sample.it.tourist"
+        page = FakeQueryPage(initial_state="user_area", service_id=9001)
+        plugin = self._plugin(
+            page,
+            service_id=9001,
+            routing_key=routing_key,
+            query_mode="calendar",
+            capability="single_schengen_tourism",
+        )
+        plugin._prepared_calendar = None
+
+        with patch(
+            "plugins.ita_plugin.scan_until_first_available_month"
+        ) as scanner:
+            with self.assertRaisesRegex(
+                BizLogicError,
+                "preparation is not complete",
+            ):
+                plugin.query(
+                    self._appointment_type(
+                        routing_key,
+                        city="Sample City",
+                    )
+                )
+
+        scanner.assert_not_called()
+
+    def test_calendar_mode_rejects_a_different_prepared_route(self):
+        routing_key = "slot.sample.it.tourist"
+        page = FakeQueryPage(initial_state="calendar", service_id=9001)
+        plugin = self._plugin(
+            page,
+            service_id=9001,
+            routing_key=routing_key,
+            query_mode="calendar",
+            capability="single_schengen_tourism",
+        )
+        plugin._prepared_calendar = replace(plugin._prepared_calendar,
+            route=replace(plugin._prepared_calendar.route, routing_key="slot.other.it.tourist"))
+
+        with patch(
+            "plugins.ita_plugin.scan_until_first_available_month"
+        ) as scanner:
+            with self.assertRaisesRegex(
+                BizLogicError,
+                "identity or route",
+            ):
+                plugin.query(
+                    self._appointment_type(
+                        routing_key,
+                        city="Sample City",
+                    )
+                )
+
+        scanner.assert_not_called()
+
+    def test_calendar_mode_rejects_a_probe_only_route(self):
+        page = FakeQueryPage(initial_state="calendar")
+        plugin = self._plugin(page, query_mode="calendar")
+
+        with self.assertRaisesRegex(
+            BizLogicError,
+            "single_schengen_tourism",
+        ):
+            plugin.query(self._appointment_type())
+
+    def test_login_redirect_is_reported_as_expired_session(self):
+        page = FakeQueryPage(initial_state="login")
+        plugin = self._plugin(page, query_mode="calendar", capability="single_schengen_tourism")
+
+        with self.assertRaises(SessionExpiredOrInvalidError):
+            plugin.query(self._appointment_type())
+
+        self.assertEqual(page.clicked, [])
+
+    def test_query_source_contains_no_otp_or_submission_path(self):
+        query_source = inspect.getsource(ItaPlugin.query)
+        forbidden_fragments = (
+            "otp-send",
+            "otp-input",
+            "123456",
+            "PrivacyCheck",
+            "btnAvanti",
+            "InsertNewBooking",
+            "_perform_request",
+        )
+
+        for fragment in forbidden_fragments:
+            with self.subTest(fragment=fragment):
+                self.assertNotIn(fragment, query_source)
+
+
+class ItaPluginBookDiscoveryTests(unittest.TestCase):
+    @staticmethod
+    def _appointment_type():
+        return AppointmentType(
+            routing_key="slot.dub.it.tourist",
+            city="Dublin",
+            country="Italy",
+            visa_type="Tourist",
+        )
+
+    @classmethod
+    def _weak_signal(cls):
+        return VSQueryResult(
+            success=False,
+            apt_type=cls._appointment_type(),
+            availability_status=AvailabilityStatus.NoneAvailable,
+        )
+
+    @staticmethod
+    def _plugin(page):
+        plugin = ItaPlugin.__new__(ItaPlugin)
+        plugin.group_id = "offline-book-discovery"
+        plugin.logger = Mock()
+        plugin.page = page
+        plugin.mouse = FakeQueryMouse(page)
+        plugin.free_config = {
+            "query_mode": "services_probe",
+            "final_submit_enabled": False,
+            "apt_configs": {
+                "slot.dub.it.tourist": {
+                    "service_id": 1321,
+                    "capability": "services_probe_only",
+                }
+            },
+        }
+        plugin.ita_url = "https://prenotami.esteri.it"
+        plugin.root_workspace = "/nonexistent/ita-plugin-book-test"
+        plugin.tunnel = None
+        plugin._reset_calendar_state()
+        plugin.query = Mock(side_effect=AssertionError("Book must not call public Query"))
+        return plugin
+
+    def test_book_rechecks_once_and_returns_false_when_user_has_no_slot(self):
+        page = FakeQueryPage(outcome="no_slots", initial_state="user_area")
+        plugin = self._plugin(page)
+
+        result = plugin.book(self._weak_signal(), user_inputs={})
+
+        self.assertFalse(result.success)
+        self.assertEqual(result.label, BOOKING_RECHECK_NONE_AVAILABLE_LABEL)
+        self.assertEqual(page.clicked, ["booking-1321"])
+        self.assertEqual(page.run_js_calls, [])
+        plugin.query.assert_not_called()
+
+    def test_book_diagnostic_mode_stops_before_avanti_without_collecting_metadata(self):
+        page = FakeQueryPage(outcome="booking_form", initial_state="user_area")
+        plugin = self._plugin(page)
+
+        result = plugin.book(self._weak_signal(), user_inputs={})
+
+        self.assertFalse(result.success)
+        self.assertEqual(result.label, BOOKING_FORM_DISCOVERY_STOP_LABEL)
+        self.assertEqual(page.clicked, ["booking-1321"])
+        self.assertEqual(page.run_js_calls, [])
+        plugin.query.assert_not_called()
+
+    def test_book_rejects_a_form_on_an_unexpected_actual_page(self):
+        page = FakeQueryPage(outcome="unknown", initial_state="user_area")
+        original_ele = page.ele
+        page.ele = lambda selector, timeout=None: (
+            FakeQueryElement(page, "wrong-form")
+            if selector == "#bookingForm" and page.state == "unknown"
+            else original_ele(selector, timeout))
+        plugin = self._plugin(page)
+
+        with self.assertRaisesRegex(BizLogicError, "unexpected path"):
+            plugin.book(self._weak_signal(), user_inputs={})
+
+        self.assertEqual(page.clicked, ["booking-1321"])
+        self.assertEqual(page.run_js_calls, [])
+        plugin.query.assert_not_called()
+
+    def test_book_source_contains_no_form_submission_calendar_or_otp_path(self):
+        book_source = inspect.getsource(ItaPlugin.book)
+        forbidden_fragments = (
+            "GenerateOTP",
+            "get_email_verify_code",
+            "fetch_mail_content",
+            "PrivacyCheck",
+            "btnAvanti",
+            "BookingCalendar",
+            "InsertNewBooking",
+            "_perform_request",
+            ".submit(",
+            ".click(",
+        )
+
+        for fragment in forbidden_fragments:
+            with self.subTest(fragment=fragment):
+                self.assertNotIn(fragment, book_source)
+
+
+class FakeRetainedSignalRedis:
+    def __init__(self, payload, clock, *, ttl):
+        self.payload = json.dumps(payload)
+        self.clock = clock
+        self.ttl = ttl
+
+    def get(self, _name):
+        if self.clock["now"] <= self.ttl:
+            return self.payload
+        return None
+
+    def delete(self, *_names):
+        return 0
+
+
+class CountingItaOrderBooker(OrderBookerGCO):
+    def _execute_book_job(self, task, query_result):
+        del task, query_result
+        self.book_calls += 1
+
+
+class ItaSignalReuseTests(unittest.TestCase):
+    @staticmethod
+    def _appointment_type():
+        return AppointmentType(
+            routing_key="slot.dub.it.tourist",
+            city="Dublin",
+            country="Italy",
+            visa_type="Tourist",
+        )
+
+    def test_retained_thirty_second_signal_triggers_one_book_call(self):
+        apt_type = self._appointment_type()
+        weak_result = VSQueryResult(
+            success=True,
+            apt_type=apt_type,
+            availability_status=AvailabilityStatus.NoneAvailable,
+        )
+        payload = {
+            "apt_type": apt_type.model_dump(),
+            "query_result": weak_result.to_snapshot_payload(),
+        }
+        clock = {"now": 0.0}
+
+        task = Task(
+            instance=Mock(),
+            next_run=0.0,
+            task_ref=1,
+            acceptable_routing_keys=[apt_type.routing_key],
+            source_queue=apt_type.routing_key,
+            book_allowed=True,
+        )
+        config = GroupConfig(
+            identifier="pernotami.ie.it",
+            appointment_types=[apt_type],
+            booker={
+                "account_source": "order",
+                "target_instances": 1,
+                "booking_cooldown": 45,
+            },
+        )
+
+        booker = CountingItaOrderBooker.__new__(CountingItaOrderBooker)
+        booker.m_cfg = config
+        booker.m_logger = Mock()
+        booker.m_tasks = [task]
+        booker.m_lock = threading.RLock()
+        booker.m_stop_event = threading.Event()
+        booker.m_task_data_cache = {}
+        booker.redis_client = FakeRetainedSignalRedis(payload, clock, ttl=30)
+        booker.book_calls = 0
+
+        def fake_sleep(seconds):
+            clock["now"] += seconds
+            if clock["now"] > 31:
+                booker.m_stop_event.set()
+
+        booker_time = OrderBookerGCO._booking_trigger_loop.__globals__["time"]
+        with (
+            patch.object(booker_time, "sleep", side_effect=fake_sleep),
+            patch.object(booker_time, "time", side_effect=lambda: clock["now"]),
+        ):
+            booker._booking_trigger_loop()
+
+        self.assertEqual(booker.book_calls, 1)
+        self.assertGreater(task.next_run, 30)
+
+    def test_italy_config_keeps_existing_single_worker_cooldown_contract(self):
+        repo_root = Path(__file__).resolve().parents[2]
+        booker_groups = json.loads(
+            (repo_root / "config" / "config_booker.json").read_text()
+        )
+        sentinel_groups = json.loads(
+            (repo_root / "config" / "config_sentinel.json").read_text()
+        )
+        booker_group = next(
+            group
+            for group in booker_groups
+            if group["identifier"] == "pernotami.ie.it"
+        )
+        sentinel_group = next(
+            group
+            for group in sentinel_groups
+            if group["identifier"] == "pernotami.ie.it"
+        )
+
+        self.assertEqual(booker_group["booker"]["target_instances"], 1)
+        self.assertEqual(sentinel_group["sentinel"]["target_instances"], 1)
+        self.assertGreater(
+            booker_group["booker"]["booking_cooldown"],
+            sentinel_group["sentinel"]["signal_ttl"],
+        )
+        self.assertGreater(
+            sentinel_group["sentinel"]["query_wait"]["random_min"],
+            booker_group["booker"]["booking_cooldown"],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 363 - 0
test/ita/test_ita_preflight.py

@@ -0,0 +1,363 @@
+"""Offline regression for Italy form readiness; never contact the real site."""
+import io
+import json
+import shutil
+import subprocess
+import unittest
+from contextlib import redirect_stdout
+from dataclasses import asdict
+from types import SimpleNamespace
+from unittest import TestCase
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin as session
+from plugins import ita_plugin as turnstile
+from test.ita.test_debug_ita_calendar_gate import booking_preflight_snapshot
+from test.ita.test_ita_protocol import live_route
+
+
+class PreflightWaitTests(TestCase):
+    def run_wait(self, raw, **kwargs):
+        page = SimpleNamespace(run_js=Mock(return_value=raw))
+        with patch.object(session.time, 'monotonic', side_effect=[0, 0, 121]), \
+             patch.object(session.time, 'sleep'):
+            return session.wait_for_booking_preflight(page, script='offline', **kwargs)
+
+    def test_timeout_distinguishes_token_and_button(self):
+        for token, enabled, expected in (
+            (False, True, 'turnstile_token_pending'),
+            (True, False, 'avanti_disabled'),
+            (False, False, 'turnstile_and_avanti_pending'),
+        ):
+            with self.subTest(expected=expected), redirect_stdout(io.StringIO()):
+                with self.assertRaises(session.CalendarGateError) as raised:
+                    self.run_wait(booking_preflight_snapshot(
+                        turnstileReady=token, avantiEnabled=enabled))
+                self.assertIn(expected, str(raised.exception))
+
+    def test_production_wait_does_not_emit_private_snapshots_without_a_diagnostic(self):
+        raw = booking_preflight_snapshot(turnstileReady=False)
+        raw.update(token='PRIVATE-TOKEN', email='private@example.test',
+                   turnstileApiPresent=True, documentVisible=False)
+        output = io.StringIO()
+        with redirect_stdout(output), self.assertRaises(session.CalendarGateError):
+            self.run_wait(raw)
+        self.assertNotIn('ITA_BOOK_PREFLIGHT_DIAGNOSTIC=', output.getvalue())
+        self.assertNotIn('PRIVATE-TOKEN', output.getvalue())
+        self.assertNotIn('private@example.test', output.getvalue())
+
+    def test_ready_never_invokes_recovery(self):
+        action = Mock()
+        with redirect_stdout(io.StringIO()):
+            self.run_wait(booking_preflight_snapshot(), wait_action=action)
+        action.assert_not_called()
+
+    def test_bad_structure_never_invokes_recovery(self):
+        action = Mock()
+        with redirect_stdout(io.StringIO()), self.assertRaises(session.CalendarGateError):
+            self.run_wait(booking_preflight_snapshot(formReady=False), wait_action=action)
+        action.assert_not_called()
+
+    def test_session_guard_runs_before_dom_read(self):
+        current = Mock(side_effect=session.CalendarGateError('session changed'))
+        page = SimpleNamespace(run_js=Mock())
+        with self.assertRaises(session.CalendarGateError):
+            session.wait_for_booking_preflight(page, script='offline', check_current=current)
+        page.run_js.assert_not_called()
+
+    def test_wait_action_does_not_substitute_for_a_new_ready_snapshot(self):
+        raw = booking_preflight_snapshot(turnstileReady=False)
+        action = Mock(return_value=True)
+        with redirect_stdout(io.StringIO()), self.assertRaises(session.CalendarGateError):
+            self.run_wait(raw, wait_action=action)
+        action.assert_called_once()
+
+    def test_bad_dynamic_boolean_is_not_hidden_by_wait_validation(self):
+        for field in ('turnstileReady', 'avantiEnabled'):
+            with self.subTest(field=field), redirect_stdout(io.StringIO()), \
+                 self.assertRaisesRegex(session.CalendarGateError, field):
+                self.run_wait(booking_preflight_snapshot(**{field: 'private-string'}))
+
+    def test_pending_validation_does_not_rewrite_snapshot_or_relax_other_fields(self):
+        raw = booking_preflight_snapshot(turnstileReady=False, avantiEnabled=False)
+        original = dict(raw)
+        session.validate_booking_preflight(raw, allow_pending=True)
+        self.assertEqual(raw, original)
+        with self.assertRaises(session.CalendarGateError):
+            session.validate_booking_preflight(raw)
+        for key, value in (("formReady", False), ("otpValuePresent", True),
+                           ("otpSendEnabled", False)):
+            with self.subTest(key=key), self.assertRaisesRegex(session.CalendarGateError, key):
+                session.validate_booking_preflight({**raw, key: value}, allow_pending=True)
+
+    def test_pending_policy_requires_a_real_boolean(self):
+        for value in (None, 1, "true"):
+            with self.subTest(value=value), self.assertRaisesRegex(session.CalendarGateError, "policy"):
+                session.validate_booking_preflight(booking_preflight_snapshot(), allow_pending=value)
+
+    def test_dom_exception_is_redacted(self):
+        page = SimpleNamespace(run_js=Mock(side_effect=ValueError('PRIVATE_JS_VALUE')))
+        output = io.StringIO()
+        with redirect_stdout(output), self.assertRaisesRegex(session.CalendarGateError, 'read_failed') as raised:
+            session.wait_for_booking_preflight(page, script='offline')
+        self.assertNotIn('PRIVATE_JS_VALUE', str(raised.exception) + output.getvalue())
+
+    def test_wait_can_observe_readiness_after_recovery(self):
+        page = SimpleNamespace(run_js=Mock(side_effect=[
+            booking_preflight_snapshot(turnstileReady=False), booking_preflight_snapshot()]))
+        action = Mock()
+        with patch.object(session.time, 'monotonic', side_effect=[0, 0, 1]), \
+             patch.object(session.time, 'sleep'), redirect_stdout(io.StringIO()):
+            result = session.wait_for_booking_preflight(page, script='offline', wait_action=action)
+        self.assertTrue(result['turnstileReady'])
+        self.assertEqual(page.run_js.call_count, 2)
+        action.assert_called_once()
+
+    def test_contract_fields_are_plain_booleans(self):
+        for field in ('formReady', 'turnstileReady', 'otpValuePresent',
+                      'otpSendEnabled', 'avantiEnabled'):
+            for value in (1, 0, 1.0, 0.0, 'true', None):
+                with self.subTest(field=field, value=value), redirect_stdout(io.StringIO()), \
+                     self.assertRaisesRegex(session.CalendarGateError, field):
+                    self.run_wait(booking_preflight_snapshot(**{field: value}))
+
+
+FORM_JS_HARNESS = r"""
+const vm = require('node:vm');
+const input = JSON.parse(require('node:fs').readFileSync(0, 'utf8'));
+const cfg = input.config, mode = input.mode;
+const calls = [];
+const fields = {
+  hiddenTipoPrenotazione: {value: '0'}, numAccSelected: {value: '0'},
+  hiddenSelezionato_0: {value: '0'},
+  PrivacyCheck: {checked: false, click() {this.checked = true; calls.push('privacy');}},
+  'otp-input': {value: ''}, 'otp-send': {disabled: false}, btnAvanti: {disabled: false},
+};
+function control(spec, role) {
+  fields[spec.control_id] = {
+    value: '0', options: [{value: spec.value, textContent: mode === role + '_wrong_label'
+      ? 'Unrelated service' : '  ' + spec.labels[0].toUpperCase() + '  '}],
+    dispatchEvent(event) {
+      if (event.type !== 'change' || event.bubbles !== true) throw Error('Wrong change event');
+      calls.push(role);
+      if (role === 'booking' && mode !== 'hidden_unsynced') fields.hiddenTipoPrenotazione.value = this.value;
+      if (role === 'booking' && mode === 'navigated_during_change') location.pathname = '/Services';
+    },
+  };
+  if (mode === role + '_missing') delete fields[spec.control_id];
+}
+control(cfg.booking_type, 'booking');
+control(cfg.purpose, 'purpose');
+if (mode === 'companions') fields.numAccSelected.value = '1';
+if (mode === 'purpose_hidden') fields.hiddenSelezionato_0.value = '999';
+const token = {value: mode === 'pending' ? '' : 'synthetic-widget-token'};
+const location = {
+  origin: mode === 'wrong_origin' ? 'https://other.example.test' : 'https://prenotami.esteri.it',
+  pathname: mode === 'wrong_path' ? '/Services' : '/Services/Booking/' + cfg.service_id,
+};
+location.href = location.origin + location.pathname;
+const form = {
+  action: mode === 'wrong_action' ? 'https://other.example.test/submit' : location.href,
+  method: mode === 'wrong_method' ? 'GET' : 'POST',
+  enctype: mode === 'wrong_enctype' ? 'application/json' : 'multipart/form-data',
+  querySelectorAll(selector) {
+    if (selector === 'input[type="file"]') return mode === 'upload' ? [{}] : [];
+    if (selector === '[required]') return mode === 'unknown_required' ? [{id: 'new-mandatory-field'}] : [];
+    throw Error('Unexpected form selector: ' + selector);
+  },
+};
+const document = {
+  visibilityState: 'visible',
+  getElementById: id => fields[id] || null,
+  querySelector(selector) {
+    if (selector === '#bookingForm') return form;
+    if (selector.startsWith('script[')) return {};
+    throw Error('Unexpected selector: ' + selector);
+  },
+  querySelectorAll(selector) {
+    if (selector === '#bookingForm') return mode === 'duplicate_form' ? [form, form] : [form];
+    if (selector === 'input[name="cf-turnstile-response"]') return mode === 'duplicate_token' ? [token, token] : [token];
+    if (selector === '#otp-input' && mode === 'duplicate_otp') return [fields['otp-input'], fields['otp-input']];
+    if (selector === '#otp-send' && mode === 'duplicate_send') return [fields['otp-send'], fields['otp-send']];
+    if (selector === '#btnAvanti' && mode === 'duplicate_avanti') return [fields.btnAvanti, fields.btnAvanti];
+    const field = fields[selector.slice(1)];
+    if (field) return [field];
+    throw Error('Unexpected selector: ' + selector);
+  },
+};
+const context = {document, location, window: {location, turnstile: {}}, URL,
+  Event: class {constructor(type, options) {this.type = type; this.bubbles = options.bubbles;}}};
+const run = () => vm.runInNewContext('(function(){' + input.source + '\n})()', context, {timeout: 1000});
+const before = run(), second = run();
+fields['otp-input'].value = '001234';
+fields['otp-send'].disabled = true;
+const after = run();
+process.stdout.write(JSON.stringify({before, second, after, calls}));
+"""
+
+
+@unittest.skipUnless(shutil.which('node'), 'Node required for actual form JavaScript execution')
+class FormJavaScriptTests(TestCase):
+    def run_case(self, mode='ready', *, alternate=False, source_factory=None):
+        config = live_route()
+        if alternate:
+            config['service_id'] = 9012
+            config['form'].update(booking_type_control_id='other-booking', booking_type_value='31',
+                                  booking_type_labels=['Individual'], purpose_control_id='other-purpose',
+                                  purpose_value='67', purpose_labels=['Tourism'])
+        route = session.resolve_route_config({'sample': config}, 'sample')
+        source = (source_factory or session.guarded_preflight_script)(
+            route, f'/Services/Booking/{route.service_id}')
+        completed = subprocess.run([shutil.which('node'), '-e', FORM_JS_HARNESS],
+            input=json.dumps({'source': source, 'mode': mode, 'config': asdict(route)}),
+            capture_output=True, text=True, timeout=10)
+        self.assertEqual(completed.returncode, 0, completed.stderr)
+        return json.loads(completed.stdout)
+
+    def test_two_routes_configure_controls_once_and_preserve_post_otp_cooldown(self):
+        for alternate in (False, True):
+            with self.subTest(alternate=alternate):
+                result = self.run_case(alternate=alternate)
+                session.validate_booking_preflight(result['before'])
+                session.validate_booking_preflight(result['second'])
+                session.validate_booking_preflight(result['after'], after_otp=True)
+                self.assertEqual(result['calls'], ['booking', 'purpose', 'privacy'])
+                self.assertNotIn('001234', json.dumps(result))
+                self.assertNotIn('synthetic-widget-token', json.dumps(result))
+
+    def test_boundary_rejects_before_any_form_changes(self):
+        for mode in ('wrong_origin', 'wrong_path', 'wrong_action', 'wrong_method',
+                     'wrong_enctype', 'upload', 'duplicate_form'):
+            with self.subTest(mode=mode):
+                result = self.run_case(mode)
+                self.assertEqual(result['calls'], [])
+                with self.assertRaises(session.CalendarGateError):
+                    session.validate_booking_preflight(result['before'])
+
+    def test_unknown_controls_unsynced_values_and_duplicate_otp_remain_rejected(self):
+        for mode in ('booking_wrong_label', 'purpose_wrong_label', 'booking_missing',
+                     'purpose_missing', 'hidden_unsynced', 'companions', 'purpose_hidden',
+                     'unknown_required', 'duplicate_otp', 'pending'):
+            with self.subTest(mode=mode):
+                result = self.run_case(mode)
+                with self.assertRaises(session.CalendarGateError):
+                    session.validate_booking_preflight(result['before'])
+                if mode.startswith('booking_'):
+                    self.assertNotIn('booking', result['calls'])
+                if mode.startswith('purpose_') and mode != 'purpose_hidden':
+                    self.assertNotIn('purpose', result['calls'])
+
+    def test_existing_calendar_debug_entry_uses_the_same_guarded_form(self):
+        from tools import debug_ita_calendar_gate as gate
+        for alternate in (False, True):
+            for mode in ('ready', 'wrong_origin', 'wrong_action', 'upload'):
+                with self.subTest(alternate=alternate, mode=mode):
+                    result = self.run_case(mode, alternate=alternate,
+                                           source_factory=gate.guarded_preflight_script)
+                    if mode == 'ready':
+                        session.validate_booking_preflight(result['before'])
+                        session.validate_booking_preflight(result['after'],
+                            after_otp=True)
+                        self.assertEqual(result['calls'], ['booking', 'purpose', 'privacy'])
+                    else:
+                        self.assertEqual(result['calls'], [])
+                        with self.assertRaises(session.CalendarGateError):
+                            session.validate_booking_preflight(result['before'])
+
+    def test_duplicate_business_controls_cannot_pass_either_otp_stage(self):
+        for mode in ('duplicate_send', 'duplicate_avanti', 'duplicate_token'):
+            with self.subTest(mode=mode):
+                result = self.run_case(mode)
+                for snapshot, after_otp in (('before', False), ('after', True)):
+                    self.assertFalse(result[snapshot]['formReady'])
+                    with self.assertRaises(session.CalendarGateError):
+                        session.validate_booking_preflight(result[snapshot], after_otp=after_otp)
+
+    def test_native_change_navigation_is_not_reported_as_a_ready_form(self):
+        result = self.run_case('navigated_during_change')
+        self.assertFalse(result['before']['formReady'])
+        with self.assertRaisesRegex(session.CalendarGateError, 'formReady'):
+            session.validate_booking_preflight(result['before'])
+        self.assertEqual(result['second'], {
+            'formReady': False, 'turnstileReady': False, 'otpValuePresent': False,
+            'otpSendEnabled': False, 'avantiEnabled': False,
+        })
+
+
+class TurnstileRecoveryTests(TestCase):
+    def setUp(self):
+        self.page = SimpleNamespace(title='Booking - Prenot@Mi', refresh=Mock(), run_js=Mock())
+        self.guard = Mock()
+        self.recovery = turnstile.turnstile_recovery(self.page, self.guard)
+        self.helper = Mock()
+        self.helper.click_verification_button.return_value = True
+        self.factory = patch.object(turnstile, 'CloudflareBypasser', return_value=self.helper)
+        self.factory_mock = self.factory.start()
+        self.addCleanup(self.factory.stop)
+
+    def attempt(self, elapsed=5, remaining=100, raw=None, after_otp=False):
+        self.recovery(raw if raw is not None else booking_preflight_snapshot(turnstileReady=False),
+            after_otp=after_otp,
+            elapsed=elapsed, remaining=remaining)
+
+    def test_reuses_vfs_widget_method_not_title_based_bypass(self):
+        with redirect_stdout(io.StringIO()):
+            self.attempt()
+        self.factory_mock.assert_called_once_with(self.page, log=False)
+        self.helper.click_verification_button.assert_called_once_with(is_dfs=False)
+        self.helper.bypass.assert_not_called()
+        self.page.refresh.assert_not_called()
+        self.page.run_js.assert_not_called()
+        self.assertEqual(self.guard.call_count, 2)
+
+    def test_waits_initially_and_leaves_successful_widget_untouched(self):
+        self.attempt(elapsed=4)
+        self.attempt(elapsed=5, remaining=1)
+        self.attempt(raw=booking_preflight_snapshot(avantiEnabled=False))
+        self.attempt(raw=booking_preflight_snapshot())
+        self.factory_mock.assert_not_called()
+
+    def test_attempt_budget_and_interval_apply_even_if_control_cannot_be_clicked(self):
+        self.helper.click_verification_button.return_value = False
+        with redirect_stdout(io.StringIO()):
+            for seconds in (5, 5.5, 10, 15, 16, 25, 35, 55, 100):
+                self.attempt(elapsed=seconds)
+        self.assertEqual(self.helper.click_verification_button.call_count, 3)
+
+    def test_stage_change_does_not_reset_total_attempt_budget(self):
+        with redirect_stdout(io.StringIO()):
+            for seconds in (5, 15, 25):
+                self.attempt(elapsed=seconds)
+            self.attempt(elapsed=5, after_otp=True)
+        self.assertEqual(self.helper.click_verification_button.call_count, 3)
+
+    def test_wrong_form_or_missing_field_cannot_interact(self):
+        for changes in ({'formReady': False}, {'turnstileReady': None}):
+            with self.subTest(changes=changes), self.assertRaises(session.CalendarGateError):
+                raw = booking_preflight_snapshot(turnstileReady=False)
+                raw.update(changes)
+                self.attempt(raw=raw)
+        self.factory_mock.assert_not_called()
+
+    def test_session_change_prevents_interaction(self):
+        self.guard.side_effect = session.CalendarGateError('session changed')
+        with self.assertRaises(session.CalendarGateError):
+            self.attempt()
+        self.factory_mock.assert_not_called()
+
+    def test_helper_errors_are_bounded_and_do_not_leak_browser_data(self):
+        self.helper.click_verification_button.side_effect = RuntimeError('PRIVATE_BROWSER_DATA')
+        output = io.StringIO()
+        with redirect_stdout(output):
+            self.attempt()
+        self.assertNotIn('PRIVATE_BROWSER_DATA', output.getvalue())
+        self.assertNotIn('ITA_BOOK_TURNSTILE_INTERACTION=', output.getvalue())
+        self.assertEqual(self.helper.click_verification_button.call_count, 1)
+
+    def test_interaction_success_alone_cannot_release_preflight(self):
+        page = SimpleNamespace(run_js=Mock(return_value=booking_preflight_snapshot(turnstileReady=False)))
+        with patch.object(session.time, 'monotonic', side_effect=[0, 5, 121]), \
+             patch.object(session.time, 'sleep'), redirect_stdout(io.StringIO()):
+            with self.assertRaisesRegex(session.CalendarGateError, 'turnstile_token_pending'):
+                session.wait_for_booking_preflight(page, script='offline', wait_action=self.recovery)
+        self.helper.click_verification_button.assert_called_once()

+ 491 - 0
test/ita/test_ita_protocol.py

@@ -0,0 +1,491 @@
+import copy
+import json
+import unittest
+from datetime import date, time
+
+from plugins.ita_plugin import (
+    MAX_LOOKAHEAD_MONTHS,
+    MAX_PROTOCOL_ITEMS,
+    MAX_PROTOCOL_PAYLOAD_CHARS,
+    CalendarDay,
+    ItaCapability,
+    ItaProtocolError,
+    SlotCandidate,
+    available_calendar_days,
+    available_slot_candidates,
+    decode_double_json_array,
+    month_starts,
+    parse_calendar_availability,
+    parse_time_slots,
+    resolve_route_config,
+)
+
+
+def double_json(items):
+    return json.dumps(json.dumps(items, separators=(",", ":")))
+
+
+def availability_item(day, slots_free, slots_remaining):
+    return {
+        "DateLibere": day,
+        "SlotLiberi": slots_free,
+        "SlotRimanenti": slots_remaining,
+    }
+
+
+def time_value(hours, minutes, *, seconds=0, milliseconds=0):
+    return {
+        "Hours": hours,
+        "Minutes": minutes,
+        "Seconds": seconds,
+        "Milliseconds": milliseconds,
+    }
+
+
+def slot_item(
+    day,
+    start,
+    end,
+    slots_free,
+    slots_remaining,
+    daily_id,
+):
+    return {
+        "Data": day,
+        "OrarioInizioFascia": time_value(*start),
+        "OrarioFineFascia": time_value(*end),
+        "SlotLiberi": slots_free,
+        "SlotRimanenti": slots_remaining,
+        "IDCalendarioServizioGiornaliero": daily_id,
+    }
+
+
+def live_route():
+    return {
+        "service_id": 100,
+        "capability": "single_schengen_tourism",
+        "calendar_scan": {"lookahead_months": 3},
+        "form": {
+            "booking_type_control_id": "booking-type",
+            "booking_type_value": "single",
+            "booking_type_labels": ["Label One", "Label Two"],
+            "purpose_control_id": "purpose",
+            "purpose_value": "tourism",
+            "purpose_labels": ["Purpose One", "Purpose Two"],
+        },
+    }
+
+
+class ProtocolTestCase(unittest.TestCase):
+    def assert_protocol_error(self, code, action):
+        with self.assertRaises(ItaProtocolError) as raised:
+            action()
+        self.assertEqual(raised.exception.code, code)
+
+
+class RouteConfigTests(ProtocolTestCase):
+    def test_resolves_vfs_bls_style_live_route_without_locale_logic(self):
+        routing_key = "slot.sample.it.tourist"
+        result = resolve_route_config({routing_key: live_route()}, routing_key)
+
+        self.assertEqual(result.routing_key, routing_key)
+        self.assertEqual(result.service_id, 100)
+        self.assertIs(result.capability, ItaCapability.SINGLE_SCHENGEN_TOURISM)
+        self.assertEqual(result.lookahead_months, 3)
+        self.assertEqual(result.booking_type.value, "single")
+        self.assertEqual(result.booking_type.labels, ("Label One", "Label Two"))
+        self.assertEqual(result.purpose.value, "tourism")
+
+    def test_resolves_minimal_services_probe_route(self):
+        routing_key = "slot.sample.it.probe"
+        result = resolve_route_config(
+            {
+                routing_key: {
+                    "service_id": 101,
+                    "capability": "services_probe_only",
+                }
+            },
+            routing_key,
+        )
+
+        self.assertIs(result.capability, ItaCapability.SERVICES_PROBE_ONLY)
+        self.assertEqual(result.lookahead_months, 0)
+        self.assertIsNone(result.booking_type)
+        self.assertIsNone(result.purpose)
+
+    def test_rejects_missing_route(self):
+        self.assert_protocol_error(
+            "route_missing",
+            lambda: resolve_route_config({}, "slot.sample.it.tourist"),
+        )
+
+    def test_rejects_invalid_service_ids(self):
+        for invalid in (0, -1, True, "100", None):
+            with self.subTest(invalid=invalid):
+                route = live_route()
+                route["service_id"] = invalid
+                self.assert_protocol_error(
+                    "positive_integer_required",
+                    lambda route=route: resolve_route_config(
+                        {"route": route},
+                        "route",
+                    ),
+                )
+
+    def test_rejects_unknown_or_missing_capability(self):
+        for invalid in (None, "", "guessed_live"):
+            with self.subTest(invalid=invalid):
+                route = live_route()
+                route["capability"] = invalid
+                expected = (
+                    "capability_unsupported"
+                    if invalid == "guessed_live"
+                    else "string_required"
+                )
+                self.assert_protocol_error(
+                    expected,
+                    lambda route=route: resolve_route_config(
+                        {"route": route},
+                        "route",
+                    ),
+                )
+
+    def test_live_route_requires_calendar_and_form_contracts(self):
+        variants = []
+        no_calendar = live_route()
+        no_calendar.pop("calendar_scan")
+        variants.append(no_calendar)
+        no_form = live_route()
+        no_form.pop("form")
+        variants.append(no_form)
+
+        for route in variants:
+            with self.subTest(keys=sorted(route)):
+                self.assert_protocol_error(
+                    "mapping_required",
+                    lambda route=route: resolve_route_config(
+                        {"route": route},
+                        "route",
+                    ),
+                )
+
+    def test_live_route_rejects_invalid_lookahead(self):
+        for invalid, expected in (
+            (0, "positive_integer_required"),
+            (True, "positive_integer_required"),
+            (MAX_LOOKAHEAD_MONTHS + 1, "lookahead_too_large"),
+        ):
+            with self.subTest(invalid=invalid):
+                route = live_route()
+                route["calendar_scan"]["lookahead_months"] = invalid
+                self.assert_protocol_error(
+                    expected,
+                    lambda route=route: resolve_route_config(
+                        {"route": route},
+                        "route",
+                    ),
+                )
+
+    def test_live_route_rejects_missing_empty_or_duplicate_labels(self):
+        for labels, expected in (
+            (None, "labels_required"),
+            ([], "labels_required"),
+            (["Same", "Same"], "labels_duplicate"),
+            (["Valid", ""], "string_required"),
+        ):
+            with self.subTest(labels=labels):
+                route = live_route()
+                route["form"]["purpose_labels"] = labels
+                self.assert_protocol_error(
+                    expected,
+                    lambda route=route: resolve_route_config(
+                        {"route": route},
+                        "route",
+                    ),
+                )
+
+
+class DoubleJsonTests(ProtocolTestCase):
+    def test_decodes_exactly_two_json_layers(self):
+        items = ({"value": 1}, {"value": 2})
+        self.assertEqual(decode_double_json_array(double_json(items)), items)
+        self.assertEqual(decode_double_json_array(double_json([])), ())
+
+    def test_inner_json_and_payload_limit_keep_distinct_error_categories(self):
+        self.assert_protocol_error(
+            "inner_json_invalid", lambda: decode_double_json_array(json.dumps("not-json")),
+        )
+        self.assert_protocol_error(
+            "payload_too_large",
+            lambda: decode_double_json_array(" " * (MAX_PROTOCOL_PAYLOAD_CHARS + 1)),
+        )
+
+    def test_rejects_bad_single_triple_and_non_array_payloads(self):
+        cases = (
+            ("not-json", "outer_json_invalid"),
+            (json.dumps([{"value": 1}]), "payload_layer_count"),
+            (json.dumps(json.dumps(json.dumps([]))), "payload_layer_count"),
+            (json.dumps(json.dumps({"value": 1})), "payload_layer_count"),
+            (json.dumps(json.dumps([1])), "item_type"),
+        )
+        for payload, expected in cases:
+            with self.subTest(expected=expected):
+                self.assert_protocol_error(
+                    expected,
+                    lambda payload=payload: decode_double_json_array(payload),
+                )
+
+    def test_rejects_non_string_and_item_limit(self):
+        for invalid in (None, b"[]", ""):
+            with self.subTest(invalid=invalid):
+                self.assert_protocol_error(
+                    "payload_type",
+                    lambda invalid=invalid: decode_double_json_array(invalid),
+                )
+
+        oversized = [{} for _ in range(MAX_PROTOCOL_ITEMS + 1)]
+        self.assert_protocol_error(
+            "item_limit_exceeded",
+            lambda: decode_double_json_array(double_json(oversized)),
+        )
+        self.assert_protocol_error(
+            "max_items_invalid",
+            lambda: decode_double_json_array(double_json([]), max_items=True),
+        )
+
+
+class CalendarAvailabilityTests(ProtocolTestCase):
+    def setUp(self):
+        self.items = [
+            availability_item("09/10/2026 00:00:00", 1, 0),
+            availability_item("31/08/2026 00:00:00", 0, -1),
+            availability_item("12/10/2026 00:00:00", 8, 7),
+        ]
+
+    def test_parses_e43_positive_and_negative_days_and_sorts(self):
+        days = parse_calendar_availability(double_json(self.items))
+
+        self.assertEqual(
+            tuple(item.day for item in days),
+            (date(2026, 8, 31), date(2026, 10, 9), date(2026, 10, 12)),
+        )
+        self.assertFalse(days[0].is_available)
+        self.assertTrue(days[1].is_available)
+        self.assertEqual((days[1].slots_free, days[1].slots_remaining), (1, 0))
+
+    def test_does_not_stop_after_an_earlier_negative_month(self):
+        days = parse_calendar_availability(double_json(self.items))
+        positives = available_calendar_days(days)
+
+        self.assertEqual(
+            tuple(item.day for item in positives),
+            (date(2026, 10, 9), date(2026, 10, 12)),
+        )
+
+    def test_filters_inclusive_date_boundaries_and_sorts(self):
+        days = parse_calendar_availability(double_json(self.items))
+        positives = available_calendar_days(
+            tuple(reversed(days)),
+            start_day=date(2026, 10, 9),
+            end_day=date(2026, 10, 9),
+        )
+
+        self.assertEqual(tuple(item.day for item in positives), (date(2026, 10, 9),))
+
+    def test_rejects_duplicate_invalid_and_conflicting_days(self):
+        duplicate = self.items + [self.items[0].copy()]
+        self.assert_protocol_error(
+            "duplicate_calendar_day",
+            lambda: parse_calendar_availability(double_json(duplicate)),
+        )
+
+        invalid_dates = (
+            "9/10/2026 00:00:00",
+            "31/02/2026 00:00:00",
+            "09/10/2026 01:00:00",
+        )
+        for invalid in invalid_dates:
+            with self.subTest(invalid=invalid):
+                item = availability_item(invalid, 1, 0)
+                self.assert_protocol_error(
+                    "date_format" if invalid != "31/02/2026 00:00:00" else "date_invalid",
+                    lambda item=item: parse_calendar_availability(double_json([item])),
+                )
+
+        for counters in ((0, 0), (1, -1), (-1, -2), (0, 1)):
+            with self.subTest(counters=counters):
+                item = availability_item(
+                    "09/10/2026 00:00:00",
+                    *counters,
+                )
+                self.assert_protocol_error(
+                    "inventory_conflict",
+                    lambda item=item: parse_calendar_availability(double_json([item])),
+                )
+
+    def test_rejects_missing_or_non_integer_counters(self):
+        missing = availability_item("09/10/2026 00:00:00", 1, 0)
+        missing.pop("SlotLiberi")
+        self.assert_protocol_error(
+            "field_missing",
+            lambda: parse_calendar_availability(double_json([missing])),
+        )
+
+        for invalid in (True, "1", 1.0, None):
+            with self.subTest(invalid=invalid):
+                item = availability_item("09/10/2026 00:00:00", invalid, 0)
+                self.assert_protocol_error(
+                    "integer_required",
+                    lambda item=item: parse_calendar_availability(double_json([item])),
+                )
+
+    def test_month_starts_cross_year_and_validate_bounds(self):
+        self.assertEqual(
+            month_starts(date(2026, 11, 20), 3),
+            (date(2026, 11, 1), date(2026, 12, 1), date(2027, 1, 1)),
+        )
+        self.assert_protocol_error(
+            "positive_integer_required",
+            lambda: month_starts(date(2026, 1, 1), 0),
+        )
+        self.assert_protocol_error(
+            "lookahead_too_large",
+            lambda: month_starts(
+                date(2026, 1, 1),
+                MAX_LOOKAHEAD_MONTHS + 1,
+            ),
+        )
+        self.assert_protocol_error(
+            "date_range_invalid",
+            lambda: available_calendar_days(
+                (),
+                start_day=date(2026, 2, 1),
+                end_day=date(2026, 1, 1),
+            ),
+        )
+
+
+class TimeSlotTests(ProtocolTestCase):
+    def setUp(self):
+        self.items = [
+            slot_item("09/10/2026 00:00:00", (9, 15), (10, 0), 0, -1, 101),
+            slot_item("09/10/2026 00:00:00", (10, 5), (11, 5), 1, 0, 102),
+            slot_item("09/10/2026 00:00:00", (11, 15), (12, 40), 0, -1, 103),
+        ]
+
+    def test_parses_e43_slots_without_exposing_runtime_id_in_repr(self):
+        slots = parse_time_slots(double_json(self.items))
+
+        self.assertEqual(len(slots), 3)
+        self.assertFalse(slots[0].is_available)
+        self.assertTrue(slots[1].is_available)
+        self.assertEqual(slots[1].time_label, "10:05 - 11:05")
+        self.assertEqual((slots[1].slots_free, slots[1].slots_remaining), (1, 0))
+        self.assertNotIn(slots[1].daily_calendar_id, repr(slots[1]))
+
+    def test_filters_and_sorts_by_day_then_time_not_capacity(self):
+        items = [
+            slot_item("12/10/2026 00:00:00", (9, 0), (10, 0), 4, 3, 201),
+            slot_item("09/10/2026 00:00:00", (10, 5), (11, 5), 1, 0, 202),
+            slot_item("09/10/2026 00:00:00", (11, 15), (12, 0), 8, 7, 203),
+        ]
+        candidates = available_slot_candidates(
+            tuple(reversed(parse_time_slots(double_json(items)))),
+            start_day=date(2026, 10, 9),
+            end_day=date(2026, 10, 12),
+        )
+
+        self.assertEqual(
+            tuple((item.day, item.slots_free, item.start_time) for item in candidates),
+            (
+                (date(2026, 10, 9), 1, time(10, 5)),
+                (date(2026, 10, 9), 8, time(11, 15)),
+                (date(2026, 10, 12), 4, time(9, 0)),
+            ),
+        )
+
+    def test_time_components_keep_missing_and_wrong_type_field_locations(self):
+        for key, value, expected in (
+            ("Hours", None, "field_missing"),
+            ("Minutes", True, "integer_required"),
+            ("Seconds", "0", "integer_required"),
+            ("Milliseconds", False, "integer_required"),
+        ):
+            with self.subTest(key=key):
+                item = copy.deepcopy(self.items[1])
+                if value is None:
+                    del item["OrarioInizioFascia"][key]
+                else:
+                    item["OrarioInizioFascia"][key] = value
+                with self.assertRaises(ItaProtocolError) as caught:
+                    parse_time_slots(double_json([item]))
+                self.assertEqual(caught.exception.code, expected)
+                self.assertEqual(caught.exception.path, f"time_slots[0].OrarioInizioFascia.{key}")
+
+    def test_rejects_missing_invalid_or_conflicting_slot_fields(self):
+        missing = self.items[1].copy()
+        missing.pop("IDCalendarioServizioGiornaliero")
+        self.assert_protocol_error(
+            "field_missing",
+            lambda: parse_time_slots(double_json([missing])),
+        )
+
+        invalid_cases = []
+        end_before_start = copy.deepcopy(self.items[1])
+        end_before_start["OrarioFineFascia"] = time_value(9, 0)
+        invalid_cases.append((end_before_start, "time_range_invalid"))
+        invalid_hour = copy.deepcopy(self.items[1])
+        invalid_hour["OrarioInizioFascia"] = time_value(24, 0)
+        invalid_cases.append((invalid_hour, "time_invalid"))
+        invalid_precision = copy.deepcopy(self.items[1])
+        invalid_precision["OrarioInizioFascia"] = time_value(10, 5, seconds=1)
+        invalid_cases.append((invalid_precision, "time_precision"))
+        invalid_counter = copy.deepcopy(self.items[1])
+        invalid_counter["SlotLiberi"] = True
+        invalid_cases.append((invalid_counter, "integer_required"))
+        conflict = copy.deepcopy(self.items[1])
+        conflict["SlotLiberi"] = 0
+        conflict["SlotRimanenti"] = 0
+        invalid_cases.append((conflict, "inventory_conflict"))
+        invalid_id = copy.deepcopy(self.items[1])
+        invalid_id["IDCalendarioServizioGiornaliero"] = 0
+        invalid_cases.append((invalid_id, "positive_integer_required"))
+
+        for item, expected in invalid_cases:
+            with self.subTest(expected=expected):
+                self.assert_protocol_error(
+                    expected,
+                    lambda item=item: parse_time_slots(double_json([item])),
+                )
+
+    def test_rejects_duplicate_time_ranges_and_daily_ids(self):
+        duplicate_range = [self.items[1], copy.deepcopy(self.items[1])]
+        duplicate_range[1]["IDCalendarioServizioGiornaliero"] = 104
+        self.assert_protocol_error(
+            "duplicate_time_range",
+            lambda: parse_time_slots(double_json(duplicate_range)),
+        )
+
+        duplicate_id = [self.items[0], self.items[1]]
+        duplicate_id[1] = copy.deepcopy(duplicate_id[1])
+        duplicate_id[1]["IDCalendarioServizioGiornaliero"] = 101
+        self.assert_protocol_error(
+            "duplicate_daily_id",
+            lambda: parse_time_slots(double_json(duplicate_id)),
+        )
+
+    def test_inventory_objects_expose_derived_availability(self):
+        positive = CalendarDay(date(2026, 10, 9), 1, 0)
+        self.assertTrue(positive.is_available)
+        with self.assertRaises(TypeError):
+            CalendarDay(
+                day=date(2026, 10, 9),
+                slots_free=1,
+                slots_remaining=0,
+                is_available=False,
+            )
+
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 330 - 0
test/ita/test_ita_query_recovery.py

@@ -0,0 +1,330 @@
+"""Offline recovery contracts; no browser, credentials, or website requests."""
+
+import json
+import sys
+import threading
+import time
+import types
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+from DrissionPage.errors import PageDisconnectedError
+
+from plugins.ita_plugin import RUNTIME_SERVICE_SCRIPT
+from plugins.ita_plugin import (
+    AVAILABILITY_PATH, CalendarAccessDeniedError, CalendarAuthenticationExpiredError,
+    CalendarGateError, CalendarRateLimitedError, CalendarTransientError,
+    parse_availability_packet,
+)
+from plugins.ita_plugin import (
+    ItaCalendarTransientError, ItaPlugin,
+)
+from test.ita.test_debug_ita_production_query_gate import (
+    FakeProductionPage, gate_env, make_plugin,
+)
+from vs_types import (
+    BizLogicError, PermissionDeniedError, RateLimiteddError,
+    SessionExpiredOrInvalidError,
+)
+
+
+class RecoveryPage(FakeProductionPage):
+    """Real Query and audit mechanics run against deterministic page responses."""
+
+    def __init__(self, outcomes=("available",), *, restore_outcome="calendar"):
+        plans = [[(2026, 8, [12])]] * 100
+        super().__init__(plans)
+        self.outcomes = list(outcomes)
+        self.attempts = 0
+        self.tab_id = "offline-tab"
+        self.runtime_service = "offline-runtime-service"
+        self.restore_outcome = restore_outcome
+        self.get_calls = []
+
+    def run_js(self, script, *args):
+        if script == RUNTIME_SERVICE_SCRIPT:
+            return {"path": "/BookingCalendar", "count": 1, "value": self.runtime_service}
+        if script == "return 1;":
+            if not self.driver.is_running:
+                raise PageDisconnectedError("offline disconnected")
+            return 1
+        return super().run_js(script, *args)
+
+    def get(self, url):
+        self.get_calls.append(url)
+        if self.restore_outcome == "form":
+            self.url = "https://prenotami.esteri.it/Services/Booking/9001"
+        elif self.restore_outcome == "expired":
+            self.url = "https://iam.esteri.it/signin/"
+        else:
+            self.url = url
+            if self.restore_outcome == "wrong-service":
+                self.runtime_service = "different-runtime-service"
+
+    def refresh(self):
+        outcome = self.outcomes[min(self.attempts, len(self.outcomes) - 1)]
+        self.attempts += 1
+        if outcome == "disconnect":
+            self.driver.is_running = False
+            raise PageDisconnectedError("offline private@example.test secret-token")
+        if outcome == "cancel":
+            raise KeyboardInterrupt
+        if outcome in {"expired", "timeout"}:
+            if outcome == "expired":
+                self.url = "https://iam.esteri.it/signin/"
+            self.packet = None
+            return
+        if outcome == "none":
+            self.plans[self.refresh_calls] = [(2026, month, []) for month in (8, 9, 10)]
+        super().refresh()
+        if outcome in {"rate", "denied"}:
+            self.packet.response.status = 429 if outcome == "rate" else 403
+        if outcome == "malformed":
+            self.packet.response.raw_body = "private@example.test secret-token"
+        if outcome == "unexpected-otp":
+            self.emit("/BookingCalendar/GenerateOTP?ServiceID=9001", "GET")
+        self.emit("/BookingCalendar/RetrieveTimeSlots")  # native auto-load, not a Query fanout
+
+
+def prepared_plugin(page=None):
+    page = page or RecoveryPage()
+    plugin, route = make_plugin(page)
+    plugin.free_config["query_mode"] = "calendar"
+    plugin.is_healthy = True
+    plugin.session_create_time = time.time()
+    plugin._reset_calendar_state()
+    plugin._record_calendar_prepared_route(plugin._resolve_route(route.appointment_type()), role="query")
+    return plugin, route
+
+
+def availability_packet(status=200, *, response_url=None):
+    response = SimpleNamespace(status=status, raw_body=json.dumps(json.dumps([])))
+    if response_url is not None:
+        response.url = response_url
+    return SimpleNamespace(
+        url="https://prenotami.esteri.it" + AVAILABILITY_PATH, method="POST",
+        request=SimpleNamespace(postData={"_Servizio": "test-runtime", "selectedDay": "01/08/2026"}),
+        response=response,
+    )
+
+
+class CalendarFailureClassificationTests(unittest.TestCase):
+    def test_distinguishes_http_failure_categories(self):
+        cases = {
+            401: CalendarAuthenticationExpiredError, 403: CalendarAccessDeniedError,
+            429: CalendarRateLimitedError, 408: CalendarTransientError,
+            502: CalendarTransientError, 503: CalendarTransientError,
+            504: CalendarTransientError, 418: CalendarGateError,
+        }
+        for status, expected in cases.items():
+            with self.subTest(status=status):
+                packet = availability_packet(status)
+                packet.response.raw_body = "private@example.test secret-token"
+                with self.assertRaises(expected) as caught:
+                    parse_availability_packet(packet)
+                self.assertNotIn("private@example.test", str(caught.exception))
+                self.assertNotIn("secret-token", str(caught.exception))
+
+    def test_followed_login_redirect_is_not_schema_or_no_inventory(self):
+        with self.assertRaises(CalendarAuthenticationExpiredError):
+            parse_availability_packet(availability_packet(response_url="https://iam.esteri.it/signin/"))
+
+    def test_direct_login_redirect_is_classified_without_exposing_oauth_values(self):
+        packet = availability_packet(302)
+        packet.response.headers = {"Location": "https://iam.esteri.it/signin/?state=secret-token"}
+        with self.assertRaises(CalendarAuthenticationExpiredError) as caught:
+            parse_availability_packet(packet)
+        self.assertNotIn("secret-token", str(caught.exception))
+
+    def test_invalid_http_status_is_not_a_retryable_network_failure(self):
+        for value in (False, "200", None):
+            with self.subTest(value=value), self.assertRaises(CalendarGateError) as caught:
+                parse_availability_packet(availability_packet(value))
+            self.assertNotIsInstance(caught.exception, CalendarTransientError)
+
+    def test_foreign_or_unexpected_response_never_becomes_inventory(self):
+        for url in ("https://foreign.example" + AVAILABILITY_PATH,
+                    "https://prenotami.esteri.it/Services"):
+            with self.subTest(url=url), self.assertRaises(CalendarGateError):
+                parse_availability_packet(availability_packet(response_url=url))
+
+    def test_auth_rate_and_permission_errors_invalidate_health_and_scan(self):
+        for outcome, expected in (("expired", SessionExpiredOrInvalidError),
+                                  ("rate", RateLimiteddError), ("denied", PermissionDeniedError)):
+            with self.subTest(outcome=outcome):
+                plugin, route = prepared_plugin(RecoveryPage([outcome]))
+                with self.assertRaises(expected):
+                    plugin.query(route.appointment_type())
+                self.assertFalse(plugin.is_healthy)
+                self.assertFalse(plugin.health_check())
+                self.assertFalse(hasattr(plugin, "last_calendar_query_scan"))
+                self.assertIsNone(plugin._prepared_calendar)
+                with self.assertRaises(SessionExpiredOrInvalidError):
+                    plugin.query(route.appointment_type())
+                self.assertEqual(plugin.page.attempts, 1)
+
+    def test_transient_error_keeps_valid_session_without_old_scan(self):
+        plugin, route = prepared_plugin(RecoveryPage(["timeout", "available"]))
+        with self.assertRaises(ItaCalendarTransientError):
+            plugin.query(route.appointment_type())
+        self.assertTrue(plugin.is_healthy)
+        self.assertFalse(hasattr(plugin, "last_calendar_query_scan"))
+        self.assertTrue(plugin.query(route.appointment_type()).success)
+
+    def test_browser_disconnection_invalidates_health_without_hiding_type(self):
+        plugin, route = prepared_plugin(RecoveryPage(["disconnect"]))
+        with self.assertRaises(PageDisconnectedError):
+            plugin.query(route.appointment_type())
+        self.assertFalse(plugin.health_check())
+        self.assertIsNone(plugin._prepared_calendar)
+
+    def test_configured_lifetime_and_health_probe_clear_preparation(self):
+        plugin, route = prepared_plugin()
+        plugin.session_create_time = 1
+        self.assertFalse(plugin.health_check())
+        self.assertFalse(plugin.is_healthy)
+        self.assertIsNone(plugin._prepared_calendar)
+
+    def test_health_probe_does_not_turn_operator_cancel_into_disconnection(self):
+        plugin, _ = prepared_plugin()
+        plugin.page.run_js = Mock(side_effect=KeyboardInterrupt)
+        with self.assertRaises(KeyboardInterrupt):
+            plugin.health_check()
+        self.assertTrue(plugin.is_healthy)
+
+
+class CalendarSessionOwnershipTests(unittest.TestCase):
+    def test_ordinary_query_checks_identity_without_exporting_a_checkpoint(self):
+        for mutation in ("account", "page", "generation", "service", "tab", "route"):
+            with self.subTest(mutation=mutation):
+                plugin, route = prepared_plugin()
+                original = plugin.page
+                if mutation == "account":
+                    plugin.config.account.username = "other@example.test"
+                elif mutation == "page":
+                    plugin.page = RecoveryPage()
+                elif mutation == "generation":
+                    plugin.session_create_time += 1
+                elif mutation == "service":
+                    plugin.page.runtime_service = "different-runtime"
+                elif mutation == "tab":
+                    plugin.page.tab_id = "different-tab"
+                elif mutation == "route":
+                    plugin.free_config["apt_configs"][route.routing_key]["service_id"] = 9002
+                with self.assertRaises(BizLogicError):
+                    plugin.query(route.appointment_type())
+                self.assertEqual(original.refresh_calls, 0)
+                self.assertEqual(plugin.page.refresh_calls, 0)
+
+    def test_query_proof_cannot_be_copied_to_another_page(self):
+        first, route = prepared_plugin()
+        second, _ = prepared_plugin()
+        second.session_create_time = first.session_create_time
+        second._prepared_calendar = first._prepared_calendar
+        with self.assertRaises(BizLogicError):
+            second.query(route.appointment_type())
+        self.assertEqual(second.page.refresh_calls, 0)
+
+    def test_preparation_cannot_attest_a_replaced_page_after_reading_the_old_one(self):
+        plugin, route = prepared_plugin()
+        old_page = plugin.page
+        read = old_page.run_js
+        def replace_page_during_read(script, *args):
+            result = read(script, *args)
+            plugin.page = RecoveryPage()
+            return result
+        old_page.run_js = replace_page_during_read
+        with self.assertRaises(BizLogicError):
+            plugin._record_calendar_prepared_route(plugin._resolve_route(route.appointment_type()), role="query")
+        self.assertIsNone(plugin._prepared_calendar)
+        self.assertEqual(old_page.refresh_calls, 0)
+        self.assertEqual(plugin.page.refresh_calls, 0)
+
+    def test_query_rechecks_ownership_before_publishing_inventory(self):
+        plugin, route = prepared_plugin()
+        publish = plugin.page._publish_month
+        def change_account_during_response():
+            publish()
+            plugin.config.account.username = "other@example.test"
+        plugin.page._publish_month = change_account_during_response
+        with self.assertRaises(BizLogicError):
+            plugin.query(route.appointment_type())
+        self.assertEqual(plugin.page.refresh_calls, 1)
+        self.assertFalse(hasattr(plugin, "last_calendar_query_scan"))
+        self.assertEqual(plugin.page.final_requests, 0)
+
+    def test_changed_runtime_tab_or_generation_rejects_next_query(self):
+        for mutation in ("service", "tab", "generation"):
+            with self.subTest(mutation=mutation):
+                plugin, route = prepared_plugin()
+                if mutation == "service":
+                    plugin.page.runtime_service = "changed"
+                elif mutation == "tab":
+                    plugin.page.tab_id = "changed"
+                else:
+                    plugin.session_create_time += 1
+                with self.assertRaises(BizLogicError):
+                    plugin.query(route.appointment_type())
+                self.assertEqual(plugin.page.refresh_calls, 0)
+
+    def test_real_cleanup_uses_shared_best_effort_contract(self):
+        plugin, _route = prepared_plugin()
+        plugin.__dict__.pop("cleanup")
+        plugin.root_workspace = "/nonexistent/ita-offline-cleanup-test"
+        plugin.tunnel = SimpleNamespace(stop=Mock())
+        page = plugin.page
+        page.quit = Mock(side_effect=RuntimeError("private@example.test secret-token"))
+        plugin.cleanup()
+        self.assertIsNone(plugin.page)
+        self.assertFalse(plugin.is_healthy)
+        plugin.__del__()
+        page.quit.assert_called_once()
+
+
+class ExistingSentinelLifecycleTests(unittest.TestCase):
+    def test_real_monitor_retires_failed_italy_session_once_without_publishing(self):
+        # Import from the same already-stubbed dependency environment as other
+        # repository tests. Neither __init__ nor live API/Redis is invoked.
+        from test.ita.test_ita_plugin import GroupConfig, Task
+        try:
+            from sentinel import SentinelGCO
+        except ModuleNotFoundError as exc:
+            if exc.name != "redis":
+                raise
+            redis_stub = types.ModuleType("redis")
+            redis_stub.Redis = Mock
+            with patch.dict(sys.modules, {"redis": redis_stub}):
+                from sentinel import SentinelGCO
+        from vs_types import QueryWaitConfig, QueryWaitMode
+        plugin, route = prepared_plugin(RecoveryPage(["expired"]))
+        config = GroupConfig(identifier="offline-italy")
+        config.appointment_types = [route.appointment_type()]
+        config.appointment_types[0].weight = 1
+        config.sentinel.query_wait = QueryWaitConfig(mode=QueryWaitMode.Fixed, fixed_wait=60)
+        sentinel = SentinelGCO.__new__(SentinelGCO)
+        sentinel.m_cfg = config
+        sentinel.m_logger = Mock()
+        sentinel.redis_client = Mock()
+        sentinel.m_lock = threading.RLock()
+        sentinel.m_tasks = [Task(instance=plugin, qw_cfg=config.sentinel.query_wait, next_run=0)]
+        sentinel.m_stop_event = Mock()
+        sentinel.m_stop_event.is_set.side_effect = [False, False, True]
+        # Patch the loaded method's dependencies directly. patch.dict(sys.modules)
+        # removes temporary modules on exit, so string-based patch would import
+        # Sentinel again and require an installed/live Redis dependency.
+        isolated = {
+            "time": SimpleNamespace(sleep=lambda _delay: None, time=lambda: 1000),
+            "VSCloudApi": SimpleNamespace(Instance=Mock(return_value=Mock())),
+        }
+        with patch.dict(SentinelGCO._monitor_loop.__globals__, isolated):
+            sentinel._monitor_loop()
+        self.assertEqual(sentinel.m_tasks, [])
+        plugin.cleanup.assert_called_once()
+        sentinel.redis_client.setex.assert_not_called()
+        self.assertEqual(plugin.page.attempts, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 61 - 0
test/ita/test_ita_reservation.py

@@ -0,0 +1,61 @@
+"""Synthetic receipt shapes retained only for old debug-fixture compatibility."""
+
+import copy
+import unittest
+
+from plugins import ita_plugin
+from tools import debug_ita_reservation as diagnostic
+
+
+HEADERS = ["Codice Prenotazione", "Ufficio", "Servizio", "Data", "Ora", "Stato"]
+
+
+def detail():
+    return {"path": "/ReservationDetail/Index/synthetic-link", "statusCode": "3", "fields": {
+        "Servizio Consolare": "Visti", "Servizio Erogato": "Visti Nazionali e Schengen",
+        "Codice Prenotazione": "SYNTHETIC-REFERENCE", "Tipo Prenotazione": "Prenotazione Singola",
+        "Data": "13 ottobre 2026", "Ora": "10:25", "Stato": "Annullata",
+    }}
+
+
+def listing():
+    return {"path": "/Reservation", "tables": [{
+        "id": "dataTableReservations", "structuralEmpty": False,
+        "headers": [*HEADERS, ""], "count": 1,
+        "rows": [{"reference": "SYNTHETIC-REFERENCE", "office": "Visti",
+                  "service": "Visti Nazionali e Schengen", "date": "13 ottobre 2026",
+                  "time": "10:25", "status": "Annullata"}],
+    }, {"id": "dataTableReservationsWL", "structuralEmpty": True}]}
+
+
+def confirmed_detail():
+    raw = copy.deepcopy(detail())
+    raw.update(path="/ReservationDetail/Index/confirmed-synthetic", statusCode="2")
+    raw["fields"].update({"Codice Prenotazione": "CONFIRMED-SYNTHETIC",
+                          "Data": "3 settembre 2026", "Ora": "09:26", "Stato": "Confermata"})
+    return raw
+
+
+def confirmed_listing():
+    raw = copy.deepcopy(listing())
+    raw["tables"][0]["rows"].append({
+        **raw["tables"][0]["rows"][0], "reference": "CONFIRMED-SYNTHETIC",
+        "date": "3 settembre 2026", "time": "09:26", "status": "Confermata",
+    })
+    raw["tables"][0]["count"] = 2
+    return raw
+
+
+class RetiredReservationTests(unittest.TestCase):
+    def test_runtime_has_no_receipt_attribution_state_machine(self):
+        for name in ("ReservationState", "ReservationRecord", "read_reservation_listing"):
+            self.assertFalse(hasattr(ita_plugin, name), name)
+
+    def test_diagnostic_reports_retirement_without_external_io(self):
+        self.assertEqual(diagnostic.main([]), 0)
+        with self.assertRaises(diagnostic.ReservationDiagnosticRetired):
+            diagnostic.parse_reservation_detail(detail())
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 250 - 0
test/ita/test_ita_route_wiring.py

@@ -0,0 +1,250 @@
+import ast
+import json
+import unittest
+from pathlib import Path
+
+from plugins.ita_plugin import ItaPlugin
+from tools.debug_ita_query import (
+    DEFAULT_ITA_ROUTING_KEY,
+    DEFAULT_ITA_SERVICE_ID,
+    build_query_config,
+    resolve_debug_route,
+)
+from vs_types import AppointmentType, BizLogicError, VSPlgConfig
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ITALY_GROUP_ID = "pernotami.ie.it"
+
+
+def appointment_type(routing_key, *, city):
+    return AppointmentType(
+        routing_key=routing_key,
+        country="Italy",
+        city=city,
+        visa_type="Tourist",
+    )
+
+
+def probe_route(service_id):
+    return {
+        "service_id": service_id,
+        "capability": "services_probe_only",
+    }
+
+
+class ItaPluginRouteWiringTests(unittest.TestCase):
+    @staticmethod
+    def _plugin(apt_configs):
+        plugin = ItaPlugin.__new__(ItaPlugin)
+        plugin.page = None
+        plugin.root_workspace = "/nonexistent/ita-route-wiring"
+        plugin.tunnel = None
+        plugin.free_config = {
+            "query_mode": "services_probe",
+            "final_submit_enabled": False,
+            "apt_configs": apt_configs,
+        }
+        return plugin
+
+    def test_two_sede_fixtures_use_the_same_route_resolver(self):
+        first_key = "slot.dub.it.tourist"
+        second_key = "slot.hkg.it.tourist"
+        plugin = self._plugin(
+            {
+                first_key: probe_route(1321),
+                second_key: probe_route(4937),
+            }
+        )
+
+        first = plugin._resolve_route(
+            appointment_type(first_key, city="Dublin")
+        )
+        second = plugin._resolve_route(
+            appointment_type(second_key, city="Hong Kong")
+        )
+
+        self.assertEqual(first.routing_key, first_key)
+        self.assertEqual(first.service_id, 1321)
+        self.assertEqual(second.routing_key, second_key)
+        self.assertEqual(second.service_id, 4937)
+
+    def test_top_level_service_id_is_not_a_runtime_fallback(self):
+        plugin = self._plugin({})
+        plugin.free_config["service_id"] = 1321
+
+        with self.assertRaisesRegex(
+            BizLogicError,
+            "route configuration rejected.*route_missing",
+        ):
+            plugin._resolve_route(
+                appointment_type("slot.sample.it.tourist", city="Sample")
+            )
+
+    def test_unknown_capability_fails_closed(self):
+        routing_key = "slot.sample.it.tourist"
+        plugin = self._plugin(
+            {
+                routing_key: {
+                    "service_id": 100,
+                    "capability": "guessed_live",
+                }
+            }
+        )
+
+        with self.assertRaisesRegex(
+            BizLogicError,
+            "route configuration rejected.*capability_unsupported",
+        ):
+            plugin._resolve_route(
+                appointment_type(routing_key, city="Sample")
+            )
+
+    def test_cs3_accepts_calendar_mode_but_keeps_final_disabled(self):
+        plugin = ItaPlugin.__new__(ItaPlugin)
+        plugin.page = None
+        plugin._transient_user_data_path = "/nonexistent/transient"
+        plugin.root_workspace = "/nonexistent/root"
+        plugin.tunnel = None
+
+        plugin.set_config(
+            VSPlgConfig(free_config={"query_mode": "calendar"})
+        )
+        self.assertEqual(plugin.free_config["query_mode"], "calendar")
+
+        for free_config, expected in (
+            ({"query_mode": "unknown"}, "query_mode"),
+            ({"final_submit_enabled": True}, "final submission requires explicit OTP mode on an applicant Book configuration"),
+        ):
+            with self.subTest(free_config=free_config):
+                with self.assertRaisesRegex(BizLogicError, expected):
+                    plugin.set_config(VSPlgConfig(free_config=free_config))
+
+
+class ItaDebugRouteTests(unittest.TestCase):
+    def test_default_route_is_only_a_backward_compatible_default(self):
+        route = resolve_debug_route({})
+
+        self.assertEqual(route.routing_key, DEFAULT_ITA_ROUTING_KEY)
+        self.assertEqual(route.service_id, DEFAULT_ITA_SERVICE_ID)
+
+    def test_explicit_route_changes_key_service_and_display_metadata_together(self):
+        route = resolve_debug_route(
+            {
+                "ITA_ROUTING_KEY": "slot.sample.it.tourist",
+                "ITA_SERVICE_ID": "9001",
+                "ITA_CITY": "Sample City",
+                "ITA_VISA_TYPE": "Short-stay tourism",
+            }
+        )
+        config = build_query_config(
+            {
+                "ITA_ROUTING_KEY": route.routing_key,
+                "ITA_SERVICE_ID": str(route.service_id),
+                "ITA_CITY": route.city,
+                "ITA_VISA_TYPE": route.visa_type,
+            },
+            username="offline-test@example.test",
+            password="offline-password",
+        )
+
+        apt_type = route.appointment_type()
+        self.assertEqual(apt_type.routing_key, route.routing_key)
+        self.assertEqual(apt_type.city, route.city)
+        self.assertEqual(
+            config.free_config["apt_configs"][route.routing_key],
+            probe_route(route.service_id),
+        )
+        self.assertNotIn("service_id", config.free_config)
+        self.assertEqual(config.free_config["query_mode"], "services_probe")
+        self.assertIs(config.free_config["final_submit_enabled"], False)
+
+    def test_partial_route_override_fails_closed(self):
+        for env in (
+            {"ITA_SERVICE_ID": "4937"},
+            {"ITA_ROUTING_KEY": "slot.hkg.it.tourist"},
+            {
+                "ITA_ROUTING_KEY": "slot.hkg.it.tourist",
+                "ITA_SERVICE_ID": "4937",
+                "ITA_CITY": "Hong Kong",
+            },
+        ):
+            with self.subTest(env=env):
+                with self.assertRaisesRegex(
+                    ValueError,
+                    "route override must set",
+                ):
+                    resolve_debug_route(env)
+
+    def test_invalid_explicit_service_id_is_rejected(self):
+        for value in ("0", "-1", "not-an-integer"):
+            with self.subTest(value=value):
+                with self.assertRaisesRegex(ValueError, "ITA_SERVICE_ID"):
+                    resolve_debug_route(
+                        {
+                            "ITA_ROUTING_KEY": "slot.sample.it.tourist",
+                            "ITA_SERVICE_ID": value,
+                            "ITA_CITY": "Sample City",
+                            "ITA_VISA_TYPE": "Short-stay tourism",
+                        }
+                    )
+
+
+class ItaProductionConfigParityTests(unittest.TestCase):
+    @staticmethod
+    def _italy_group(path):
+        groups = json.loads(path.read_text(encoding="utf-8"))
+        return next(
+            group for group in groups if group["identifier"] == ITALY_GROUP_ID
+        )
+
+    def test_sentinel_and_booker_share_the_same_safe_route_contract(self):
+        sentinel = self._italy_group(
+            REPO_ROOT / "config" / "config_sentinel.json"
+        )
+        booker = self._italy_group(
+            REPO_ROOT / "config" / "config_booker.json"
+        )
+
+        for group in (sentinel, booker):
+            free_config = group["free_config"]
+            self.assertNotIn("service_id", free_config)
+            self.assertEqual(free_config["query_mode"], "services_probe")
+            self.assertIs(free_config["final_submit_enabled"], False)
+
+        self.assertEqual(
+            sentinel["free_config"]["apt_configs"],
+            booker["free_config"]["apt_configs"],
+        )
+        routing_key = sentinel["appointment_types"][0]["routing_key"]
+        self.assertIn(routing_key, sentinel["free_config"]["apt_configs"])
+
+    def test_runtime_code_has_no_sede_or_service_id_control_branch(self):
+        paths = [
+            REPO_ROOT / "plugins" / "ita_plugin.py",
+            REPO_ROOT / "tools" / "debug_ita_query.py",
+            REPO_ROOT / "tools" / "debug_ita_book.py",
+            REPO_ROOT / "tools" / "debug_ita_monitor.py",
+            REPO_ROOT / "tools" / "debug_ita_soak.py",
+            REPO_ROOT / "tools" / "debug_ita_calendar_gate.py",
+            REPO_ROOT / "tools" / "ita_local_handoff.py",
+        ]
+        forbidden_constants = {1321, 4937, "Dublin", "Hong Kong", "hkg"}
+        violations = []
+        for path in paths:
+            tree = ast.parse(path.read_text(encoding="utf-8"))
+            for node in ast.walk(tree):
+                if not isinstance(node, (ast.If, ast.IfExp)):
+                    continue
+                for child in ast.walk(node.test):
+                    if (
+                        isinstance(child, ast.Constant)
+                        and child.value in forbidden_constants
+                    ):
+                        violations.append((path.name, node.lineno, child.value))
+
+        self.assertEqual(violations, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 127 - 0
test/ita/test_ita_shared_lifecycle.py

@@ -0,0 +1,127 @@
+"""W1: exercise the shared implementations, mocking only external boundaries."""
+from contextlib import ExitStack
+from datetime import date
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import SimpleNamespace
+import unittest
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin as ita
+from test.ita.ita_test_fakes import FakeChromiumOptions, FakeKeyboard, FakeMouse, FakePage
+from utils import plugin_utils as shared
+from vs_types import VSAccount, VSPlgConfig
+
+
+class SharedInitializationTests(unittest.TestCase):
+    def test_real_shared_options_cover_direct_and_authenticated_proxy(self):
+        for proxy in (None, SimpleNamespace(ip="proxy.test", port=8080, proto="http", username="", password=""),
+                      SimpleNamespace(ip="proxy.test", port=8080, proto="http", username="fixture", password="synthetic")):
+            with self.subTest(authenticated=bool(proxy and proxy.username)), ExitStack() as stack:
+                options, tunnel = Mock(), Mock()
+                tunnel.start.return_value = "http://127.0.0.1:9901"
+                stack.enter_context(patch.object(shared, "ChromiumOptions", return_value=options))
+                stack.enter_context(patch.object(shared, "get_free_port", return_value=9900))
+                factory = stack.enter_context(patch.object(shared, "MihomoTunnel", return_value=tunnel))
+                fp = stack.enter_context(patch.object(shared, "FingerprintGenerator"))
+                fp.return_value.generate.return_value = {"seed": 9, "platform": "macos", "brand": "Chrome"}
+                stack.enter_context(patch.object(shared.configure, "CHROME_PATH", "/fixture/chrome"))
+                stack.enter_context(patch.object(shared.configure, "MIHOMO_BIN_PATH", "/fixture/mihomo"))
+                stack.enter_context(patch.object(shared.configure, "MIHOMO_RELAY_NODES", None))
+                stack.enter_context(patch.object(shared.os.path, "exists", return_value=True))
+                actual_options, actual_tunnel = shared.init_chromium_options(
+                    "/fixture/profile", username_seed="fixture@example.test", proxy=proxy)
+                self.assertIs(actual_options, options)
+                options.set_local_port.assert_called_once_with(9900)
+                options.set_user_data_path.assert_called_once_with("/fixture/profile")
+                options.set_paths.assert_called_once_with(browser_path="/fixture/chrome")
+                options.headless.assert_called_once_with(False)
+                options.set_argument.assert_any_call("--window-size=1920,1080")
+                fp.return_value.generate.assert_called_once_with("fixture@example.test")
+                if proxy and proxy.username:
+                    self.assertIs(actual_tunnel, tunnel)
+                    factory.assert_called_once()
+                    options.set_argument.assert_any_call("--proxy-server=http://127.0.0.1:9901")
+                else:
+                    self.assertIsNone(actual_tunnel)
+                    factory.assert_not_called()
+                    if proxy:
+                        options.set_argument.assert_any_call("--proxy-server=http://proxy.test:8080")
+
+    def test_italy_calls_real_shared_initializer_and_creates_only_one_page(self):
+        page = FakePage()
+        with TemporaryDirectory() as workspace, ExitStack() as stack:
+            stack.enter_context(patch.object(ita.os.path, "abspath", return_value=workspace))
+            plugin = ita.ItaPlugin("offline-shared-init")
+            plugin.set_log(Mock())
+            plugin.set_config(VSPlgConfig(account=VSAccount(username="fixture@example.test", password="synthetic")))
+            stack.enter_context(patch.object(shared, "ChromiumOptions", FakeChromiumOptions))
+            stack.enter_context(patch.object(shared, "get_free_port", return_value=9900))
+            initialize = stack.enter_context(patch.object(ita, "init_chromium_options", wraps=shared.init_chromium_options))
+            create = stack.enter_context(patch.object(ita, "ChromiumPage", return_value=page))
+            stack.enter_context(patch.object(ita, "HumanMouse", FakeMouse))
+            stack.enter_context(patch.object(ita, "HumanKeyboard", FakeKeyboard))
+            stack.enter_context(patch.object(ita.time, "sleep"))
+            try:
+                plugin.create_session()
+                self.assertTrue(plugin.is_healthy)
+                initialize.assert_called_once_with(
+                    user_data_path=plugin.user_data_path, username_seed=plugin.config.account.username,
+                    proxy=plugin.config.proxy, headless=False, window_size="1920,1080", logger=plugin._log)
+                create.assert_called_once()
+                self.assertEqual(page.clicked.count("submit"), 1)
+            finally:
+                plugin.cleanup()
+
+
+class SharedCleanupTests(unittest.TestCase):
+    def test_legacy_positional_call_still_swallows_failures_and_cleans_other_resources(self):
+        # Exact positional signature used by VFS/TLS; no opt-in behavior change.
+        with TemporaryDirectory() as parent:
+            root = Path(parent) / "workspace"
+            root.mkdir()
+            page, tunnel = Mock(), Mock()
+            page.quit.side_effect = RuntimeError("synthetic")
+            tunnel.stop.side_effect = RuntimeError("synthetic")
+            with patch.object(shared.time, "sleep"):
+                self.assertIsNone(shared.cleanup_browser_workspace(page, str(root), tunnel, Mock()))
+            page.quit.assert_called_once_with(force=True)
+            tunnel.stop.assert_called_once()
+            self.assertFalse(root.exists())
+
+    def test_italy_cleanup_uses_the_unchanged_shared_contract(self):
+        with TemporaryDirectory() as parent, ExitStack() as stack:
+            root = Path(parent) / "workspace"
+            root.mkdir()
+            plugin = ita.ItaPlugin.__new__(ita.ItaPlugin)
+            plugin.page, plugin.tunnel = Mock(), Mock()
+            page, tunnel = plugin.page, plugin.tunnel
+            plugin.root_workspace = str(root)
+            plugin.is_healthy = True
+            plugin._prepared_calendar = object()
+            plugin._log = Mock()
+            cleanup = stack.enter_context(patch.object(
+                ita, "cleanup_browser_workspace", wraps=shared.cleanup_browser_workspace,
+            ))
+            stack.enter_context(patch.object(shared.time, "sleep"))
+            plugin.cleanup()
+            cleanup.assert_called_once_with(page, str(root), tunnel, plugin._log)
+            self.assertFalse(root.exists())
+            self.assertFalse(plugin.is_healthy)
+
+class SharedDateTests(unittest.TestCase):
+    def test_positive_days_use_shared_filter_without_shuffle_or_missing_bound(self):
+        days = tuple(ita.CalendarDay(date(2026, 10, n), 1, 0) for n in (20, 13, 9))
+        for bounds, expected in (({}, (9, 13, 20)), ({"start_day": date(2026, 10, 13)}, (13, 20)),
+                                 ({"end_day": date(2026, 10, 13)}, (9, 13))):
+            with self.subTest(bounds=bounds), patch.object(ita, "filter_dates_in_range", wraps=shared.filter_dates_in_range) as select:
+                actual = ita.available_calendar_days(days, **bounds)
+                self.assertEqual(tuple(d.day.day for d in actual), expected)
+                select.assert_called_once()
+                self.assertIs(select.call_args.kwargs["shuffle"], False)
+                self.assertTrue(select.call_args.args[1])
+                self.assertTrue(select.call_args.args[2])
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 198 - 0
test/ita/test_ita_single_file.py

@@ -0,0 +1,198 @@
+"""Offline single-artifact install, factory loading and hot-reload contracts."""
+import ast
+import builtins
+from contextlib import ExitStack, redirect_stdout
+import hashlib
+from io import StringIO
+import os
+from pathlib import Path
+import sys
+from tempfile import TemporaryDirectory
+from types import SimpleNamespace
+import unittest
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin  # Preload shared host dependencies, not a loader substitute.
+from test.ita.test_ita_calendar_book import FakePage
+from test.ita.test_ita_protocol import live_route
+from tools import ita_query_book_local as local
+from utils import plugin_updater
+from vs_plg_factory import VSPlgFactory
+from vs_plg import IVSPlg
+from vs_types import AppointmentType, VSBookResult, VSQueryResult
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+class SingleFileSourceContractTests(unittest.TestCase):
+    def test_runtime_compiles_and_implements_the_host_interface(self):
+        source = (ROOT / "plugins/ita_plugin.py").read_text()
+        compile(source, "ita_plugin.py", "exec")
+        tree = ast.parse(source)
+        plugins = [node for node in tree.body if isinstance(node, ast.ClassDef) and node.name == "ItaPlugin"]
+        self.assertEqual(len(plugins), 1)
+        methods = {node.name for node in plugins[0].body if isinstance(node, ast.FunctionDef)}
+        self.assertTrue(IVSPlg.__abstractmethods__ <= methods)
+        self.assertTrue(issubclass(ita_plugin.ItaPlugin, IVSPlg))
+
+    def test_browser_lifecycle_reuses_the_installed_host_helpers(self):
+        from utils import plugin_utils
+        for name in ("init_chromium_options", "cleanup_browser_workspace", "filter_dates_in_range"):
+            self.assertIs(getattr(ita_plugin, name), getattr(plugin_utils, name))
+
+    def test_runtime_has_no_private_italy_or_tool_imports_or_dynamic_packaging(self):
+        tree = ast.parse((ROOT / "plugins/ita_plugin.py").read_text())
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                names = [node.module or ""] if isinstance(node, ast.ImportFrom) else [a.name for a in node.names]
+                self.assertFalse(any(name == "plugins" or name.startswith(("plugins.", "tools.")) for name in names), names)
+            if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+                self.assertNotIn(node.func.id, {"exec", "eval", "__import__"})
+        self.assertEqual(sorted(p.name for p in (ROOT / "plugins").glob("ita_*.py")), ["ita_plugin.py"])
+
+
+class SingleFileInstallationTests(unittest.TestCase):
+    def setUp(self):
+        self.stack = ExitStack()
+        self.addCleanup(self.stack.close)
+        self.directory = Path(self.stack.enter_context(TemporaryDirectory()))
+        self.source = (ROOT / "plugins/ita_plugin.py").read_text()
+        self.path = self.directory / "ita_plugin.py"
+        old_cwd = Path.cwd()
+        os.chdir(self.directory)
+        self.stack.callback(os.chdir, old_cwd)
+        self.stack.enter_context(redirect_stdout(StringIO()))
+        old_module = sys.modules.get("ita_plugin")
+        def restore_module():
+            sys.modules.pop("ita_plugin", None)
+            if old_module is not None:
+                sys.modules["ita_plugin"] = old_module
+        self.stack.callback(restore_module)
+        original_import = builtins.__import__
+        def guarded_import(name, *args, **kwargs):
+            if name == "plugins" or name.startswith(("plugins.", "tools.")):
+                raise AssertionError("Single artifact attempted a private runtime import: " + name)
+            return original_import(name, *args, **kwargs)
+        self.stack.enter_context(patch("builtins.__import__", side_effect=guarded_import))
+        for target in ("socket.socket.connect", "socket.create_connection", "requests.sessions.Session.request",
+                       "subprocess.Popen"):
+            self.stack.enter_context(patch(target, side_effect=AssertionError("Unexpected external I/O")))
+        self.stack.enter_context(patch.object(sys, "dont_write_bytecode", True))
+        self.factory = VSPlgFactory()
+        self.factory.register_plugin("ita_plugin", str(self.path), "ItaPlugin")
+        self.install(self.source, "1.0.1")
+
+    def install(self, source, version):
+        self.assertTrue(plugin_updater.download_and_install_plugin(
+            "ita_plugin", version, code_content=source, plugins_dir=str(self.directory),
+            expected_sha256=hashlib.sha256(source.encode()).hexdigest()))
+
+    def create(self):
+        plugin = self.factory.create("offline-single-file", "ita_plugin")
+        self.stack.callback(plugin.cleanup)
+        return plugin
+
+    def test_only_one_uploaded_file_loads_all_runtime_sections(self):
+        self.assertEqual([p.name for p in self.directory.glob("*.py")], ["ita_plugin.py"])
+        plugin = self.create()
+        runtime = type(plugin).book.__globals__
+        for name in ("ItaRouteConfig", "_submit_final_once",
+                     "parse_otp_body", "prepare_calendar", "recheck_calendar_before_final", "submit_final"):
+            self.assertEqual(runtime[name].__module__, "ita_plugin", name)
+        self.assertEqual(runtime["parse_otp_body"]("OTP Code:001234"), "001234")
+        self.assertEqual(plugin_updater.get_installed_plugins(str(self.directory))["ita_plugin"], "1.0.1")
+        self.assertIsNot(runtime["ItaCapability"], ita_plugin.ItaCapability)
+
+    def test_public_query_and_book_bind_the_loaded_file_not_canonical_import(self):
+        plugin = self.create()
+        plugin.page = SimpleNamespace(url="https://prenotami.esteri.it/UserArea", quit=Mock())
+        plugin.free_config = {"otp_mode": "cloud", "query_mode": "calendar"}
+        negative = VSQueryResult(success=False)
+        runtime = type(plugin).book.__globals__
+        with patch.dict(runtime, prepare_query_if_needed=Mock(return_value=negative)):
+            self.assertIs(plugin.query(AppointmentType(routing_key="fixture")), negative)
+            runtime["prepare_query_if_needed"].assert_called_once()
+        key = "slot.fixture.it.tourist"
+        plugin.free_config = {"otp_mode": "cloud", "query_mode": "services_probe",
+                              "final_submit_enabled": False, "apt_configs": {key: live_route()}}
+        plugin.config = SimpleNamespace(account=SimpleNamespace(username="fixture@example.test"))
+        plugin.session_create_time = 1
+        plugin.page = FakePage()
+        plugin.page.tab_id = "fixture-tab"
+        plugin.page.quit = Mock()
+        route = runtime["resolve_route_config"](plugin.free_config["apt_configs"], key)
+        plugin._record_calendar_prepared_route(route, role="book")
+        trigger = VSQueryResult(success=True, apt_type=AppointmentType(routing_key=key))
+        with patch.dict(runtime, recheck_calendar_before_final=Mock(return_value=None)), \
+             patch.object(ita_plugin, "recheck_calendar_before_final", side_effect=AssertionError("canonical runtime used")):
+            result = plugin.book(trigger, {"username": "fixture@example.test"})
+            self.assertFalse(result.success)
+            self.assertEqual(result.label, runtime["BOOKING_RECHECK_NONE_AVAILABLE_LABEL"])
+            runtime["recheck_calendar_before_final"].assert_called_once()
+
+    def test_loaded_final_adapter_uses_the_instance_runtime_after_cache_replacement(self):
+        plugin = self.create()
+        runtime = type(plugin).book.__globals__
+        key = "slot.fixture.it.tourist"
+        config = {key: live_route()}
+        route = runtime["resolve_route_config"](config, key)
+        configured_route = ita_plugin.resolve_route_config(config, key)
+        self.assertNotEqual(route, configured_route)  # Distinct loaded dataclass types.
+        self.assertEqual(route.routing_key, configured_route.routing_key)
+        expected = VSBookResult(success=False, label="synthetic")
+        adapter = Mock(return_value=expected)
+        self.create()  # The host overwrites sys.modules['ita_plugin'] for Query.
+        self.assertIsNot(sys.modules["ita_plugin"].ItaPlugin, type(plugin))
+        approval = object()
+        with patch.dict(runtime, _submit_final_once=adapter):
+            self.assertIs(runtime["submit_final"](plugin, route, approval), expected)
+        adapter.assert_called_once_with(plugin, route, approval)
+
+    def test_local_observer_preserves_standard_false_book_result(self):
+        plugin = self.create()
+        observer = local.ObservedPlugin(plugin, "book")
+        result = VSBookResult(success=False, label="retryable")
+        plugin.book = Mock(return_value=result)
+        self.assertIs(observer.book(VSQueryResult(), {}), result)
+        self.assertIsNone(observer.error)
+
+    def test_real_reload_replaces_code_and_preserves_process_wide_otp_lock(self):
+        first = self.create()
+        old = type(first).book.__globals__
+        updated = self.source.replace('version = "1.0.1"', 'version = "1.0.200"')
+        self.install(updated, "1.0.200")
+        owner = self
+        events = []
+        cfg = SimpleNamespace(plugin_config=SimpleNamespace(plugin_name="ita_plugin"))
+        previous = SimpleNamespace(m_cfg=cfg, stop=lambda: events.append("stop"))
+        class Wrapper:
+            def __init__(self, cls, config, redis):
+                self.m_cfg = config
+            def load(self):
+                events.append("load")
+                self.plugin = owner.create()
+            def start(self):
+                events.append("start")
+        # Execute the unmodified host function without importing/starting main.
+        node = next(n for n in ast.parse((ROOT / "main.py").read_text()).body
+                    if isinstance(n, ast.FunctionDef) and n.name == "reload_wrappers_for_plugin")
+        namespace = {"Dict": dict, "GCOWrapper": Wrapper, "sys": sys, "REDIS_CFG": {}}
+        exec(compile(ast.Module(body=[node], type_ignores=[]), str(ROOT / "main.py"), "exec"), namespace)
+        wrappers = {"fixture": previous}
+        namespace["reload_wrappers_for_plugin"]("ita_plugin", wrappers, {"fixture": object}, Mock())
+        new = type(wrappers["fixture"].plugin).book.__globals__
+        self.assertEqual(events, ["stop", "load", "start"])
+        self.assertEqual(wrappers["fixture"].plugin.version, "1.0.200")
+        for name in ("ItaPlugin", "ItaCapability", "OtpMailConfig", "_submit_final_once",
+                     "fetch_otp_from_cloud", "prepare_calendar", "submit_final"):
+            self.assertIsNot(new[name], old[name], name)
+        self.assertIsNot(new["ItaPlugin"].book, old["ItaPlugin"].book)
+        self.assertIs(new["_OTP_INPUT_LOCK"], old["_OTP_INPUT_LOCK"])
+        self.assertIs(new["_OTP_INPUT_LOCK"], ita_plugin._OTP_INPUT_LOCK)
+        with old["_OTP_INPUT_LOCK"]:
+            self.assertFalse(new["_OTP_INPUT_LOCK"].acquire(blocking=False))
+        self.assertIs(type(first).book.__globals__, old)
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 689 - 0
test/ita/test_ita_workflow.py

@@ -0,0 +1,689 @@
+"""Offline production-entry tests: no credentials, site calls, or cloud writes."""
+import ast
+import itertools
+from dataclasses import replace
+from contextlib import ExitStack
+from datetime import datetime
+from pathlib import Path
+from io import StringIO
+from contextlib import redirect_stdout
+from types import MethodType, SimpleNamespace
+from unittest import TestCase
+from unittest.mock import Mock, patch
+
+from plugins import ita_plugin as workflow
+from plugins import ita_plugin as preparation
+from plugins.ita_plugin import ItaPlugin
+from plugins.ita_plugin import fetch_otp_from_cloud as real_fetch_otp_from_cloud
+from plugins import ita_plugin as ita_turnstile
+from plugins.ita_plugin import OtpMailConfig
+from test.ita import test_ita_calendar_book_flow as flow
+from test.ita.test_debug_ita_calendar_gate import booking_preflight_snapshot
+from vs_types import AvailabilityStatus, BizLogicError, PermissionDeniedError, VSBookResult, VSPlgConfig, VSQueryResult
+
+
+class PreparationTests(TestCase):
+    def setUp(self):
+        _, self.route, _ = flow.prepared_plugin(flow.FlowPage())
+        self.path = f"/Services/Booking/{self.route.service_id}"
+        self.page = SimpleNamespace(url="https://prenotami.esteri.it" + self.path,
+                                    tab_id="fixture-tab", wait=Mock(), set=Mock())
+        self.otp_present = False
+        self.clicks = []
+        self.page.run_js = Mock(side_effect=lambda _: booking_preflight_snapshot(
+            otpValuePresent=self.otp_present, otpSendEnabled=not self.otp_present))
+        otp_input = Mock()
+        otp_input.input.side_effect = lambda *a, **k: setattr(self, "otp_present", True)
+        otp_input.run_js.return_value = True
+        otp_input.selector = "#otp-input"
+        controls = {"#otp-input": otp_input, "#otp-send": SimpleNamespace(selector="#otp-send"),
+                    "#btnAvanti": SimpleNamespace(selector="#btnAvanti")}
+        self.page.ele = Mock(side_effect=lambda selector, **kwargs: controls[selector])
+        self.plugin = SimpleNamespace(
+            page=self.page, session_create_time=1, free_config={"otp_mode": "manual"},
+            config=SimpleNamespace(account=SimpleNamespace(username="fixture@example.test")),
+            mouse=SimpleNamespace(human_click_ele=lambda ele: self.clicks.append(ele.selector)),
+            _booking_path=lambda route: self.path, _log=Mock(),
+            _record_calendar_prepared_route=Mock(),
+        )
+        self.plugin._book_final_configuration_valid = MethodType(ItaPlugin._book_final_configuration_valid, self.plugin)
+        self.stack = ExitStack()
+        self.addCleanup(self.stack.close)
+        self.tty = self.stack.enter_context(patch.object(workflow.sys.stdin, "isatty", return_value=True))
+        self.reader = self.stack.enter_context(patch.object(preparation, "_read_manual_otp", return_value="123456"))
+        self.listener = self.stack.enter_context(patch.object(workflow, "listen_once", side_effect=self.listen))
+        self.stack.enter_context(patch.object(workflow, "guard_calendar"))
+        self.stack.enter_context(patch.object(workflow, "wait_for_calendar_service", return_value="9001"))
+
+    def listen(self, page, *, target, method, timeout, action):
+        action()
+        if target == self.path:
+            page.url = "https://prenotami.esteri.it/BookingCalendar?selectedService=Example"
+        return SimpleNamespace(tab_id=page.tab_id, is_failed=False, method=method,
+            url="https://prenotami.esteri.it" + target + ("?ServiceID=9001" if method == "GET" else ""),
+            response=SimpleNamespace(status=200, raw_body='"SENT"', url=page.url))
+
+    def test_native_preparation_sends_once_writes_once_and_records_query_role(self):
+        workflow.prepare_calendar(self.plugin, self.route, role="query")
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input", "#btnAvanti"])
+        self.assertEqual(self.listener.call_count, 2)
+        self.reader.assert_called_once()
+        self.plugin._record_calendar_prepared_route.assert_called_once_with(self.route, role="query")
+        self.assertEqual(self.page.run_js.call_count, 2)
+        self.assertIn("form-boundary", self.page.run_js.call_args.args[0])
+
+    def test_book_role_does_not_mark_query_prepared(self):
+        workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.plugin._record_calendar_prepared_route.assert_called_once_with(self.route, role="book")
+
+    def test_no_terminal_stops_before_otp_or_form_changes(self):
+        self.tty.return_value = False
+        with self.assertRaises(PermissionDeniedError):
+            workflow.prepare_calendar(self.plugin, self.route, role="query")
+        self.listener.assert_not_called()
+        self.page.run_js.assert_not_called()
+
+    def test_wrong_otp_readback_prevents_avanti_and_repeated_otp(self):
+        self.page.ele("#otp-input").run_js.return_value = False
+        with self.assertRaisesRegex(preparation.CalendarGateError, "verification failed"):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        with self.assertRaises(PermissionDeniedError):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input"])
+        self.assertEqual(self.listener.call_count, 1)
+
+    def test_wrong_tab_response_never_reads_otp_or_submits_form(self):
+        self.listener.side_effect = None
+        self.listener.return_value = SimpleNamespace(tab_id="foreign", is_failed=False)
+        with self.assertRaises(preparation.CalendarGateError):
+            workflow.prepare_calendar(self.plugin, self.route, role="query")
+        self.reader.assert_not_called()
+        self.plugin._record_calendar_prepared_route.assert_not_called()
+
+
+class CloudPreparationTests(TestCase):
+    """Reuse the manual site's fixture, replacing only the OTP provider."""
+    listen = PreparationTests.listen
+
+    def setUp(self):
+        PreparationTests.setUp(self)
+        self.plugin.free_config["otp_mode"] = "cloud"
+        self.route = replace(self.route, mail=OtpMailConfig("mailbox@example.test"))
+        self.tty.return_value = False
+        self.fetch = self.stack.enter_context(patch.object(workflow, "fetch_otp_from_cloud",
+                                                          return_value="001234"))
+        self.utc = self.stack.enter_context(patch.object(workflow, "utc_sent_at",
+                                                        return_value="2026-08-31 01:02:03"))
+
+    def test_automatic_preparation_without_tty_reuses_native_controls_and_readback(self):
+        observed = []
+        def fetch(mail, **kwargs):
+            observed.extend(self.clicks)
+            return "001234"
+        self.fetch.side_effect = fetch
+        output = StringIO()
+        with redirect_stdout(output):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.assertEqual(observed, ["#otp-send"])
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input", "#btnAvanti"])
+        self.fetch.assert_called_once_with(self.route.mail, recipient="fixture@example.test",
+                                           sent_at="2026-08-31 01:02:03")
+        self.page.ele("#otp-input").input.assert_called_once_with("001234", clear=True)
+        self.reader.assert_not_called()
+        self.assertNotIn("001234", output.getvalue() + str(self.plugin._log.call_args_list))
+        self.plugin._record_calendar_prepared_route.assert_called_once_with(self.route, role="book")
+
+    def test_send_timestamp_is_captured_before_native_send(self):
+        def click(ele):
+            if ele.selector == "#otp-send":
+                self.utc.assert_called_once()
+            self.clicks.append(ele.selector)
+        self.plugin.mouse.human_click_ele = click
+        workflow.prepare_calendar(self.plugin, self.route, role="book")
+
+    def test_mail_failure_has_no_avanti_no_manual_fallback_no_same_session_resend(self):
+        self.fetch.side_effect = preparation.CalendarGateError("Italy OTP mailbox read failed")
+        with self.assertRaises(preparation.CalendarGateError):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        with self.assertRaises(PermissionDeniedError):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.assertEqual(self.clicks, ["#otp-send"])
+        self.fetch.assert_called_once()
+        self.reader.assert_not_called()
+
+    def test_late_response_is_discarded_before_dom_write(self):
+        with patch.object(workflow, "monotonic", side_effect=[0, 1, 300]):
+            with self.assertRaisesRegex(preparation.CalendarGateError, "window expired"):
+                workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.assertEqual(self.clicks, ["#otp-send"])
+
+    def test_expiration_during_preflight_prevents_avanti(self):
+        with patch.object(workflow, "monotonic", side_effect=[0, 1, 2, 300]):
+            with self.assertRaisesRegex(preparation.CalendarGateError, "window expired"):
+                workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input"])
+
+    def test_account_change_during_read_discards_code(self):
+        def changed(*args, **kwargs):
+            self.plugin.config.account.username = "other@example.test"
+            return "001234"
+        self.fetch.side_effect = changed
+        with self.assertRaises(preparation.CalendarGateError):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.assertEqual(self.clicks, ["#otp-send"])
+
+    def test_cloud_dom_write_failure_stops_avanti(self):
+        self.page.ele("#otp-input").input.side_effect = RuntimeError("private typed 001234")
+        with self.assertRaisesRegex(preparation.CalendarGateError, "DOM write failed"):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input"])
+
+    def test_wrong_cloud_role_or_invalid_final_flag(self):
+        with self.assertRaises(PermissionDeniedError):
+            workflow.prepare_calendar(self.plugin, self.route, role="query")
+        self.plugin.free_config["final_submit_enabled"] = 1
+        with self.assertRaises(PermissionDeniedError):
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        self.listener.assert_not_called()
+        self.fetch.assert_not_called()
+
+    def test_missing_mail_stops_before_any_site_action(self):
+        with self.assertRaises(preparation.CalendarGateError):
+            workflow.prepare_calendar(self.plugin, replace(self.route, mail=None), role="book")
+        self.listener.assert_not_called()
+        self.page.run_js.assert_not_called()
+
+
+class CloudFinalPreparationTests(CloudPreparationTests):
+    """Run the same OTP/session/expiry/privacy cases with final explicitly on."""
+    def setUp(self):
+        super().setUp()
+        self.plugin.free_config["final_submit_enabled"] = True
+
+    def test_preparation_does_not_itself_submit_final(self):
+        with patch.object(workflow, "submit_final") as submit:
+            workflow.prepare_calendar(self.plugin, self.route, role="book")
+        submit.assert_not_called()
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input", "#btnAvanti"])
+
+
+class CloudQueryPreparationTests(TestCase):
+    """Use the same preparation, mail adapter and fixtures as applicant Book."""
+    listen = PreparationTests.listen
+
+    def setUp(self):
+        CloudPreparationTests.setUp(self)
+        self.plugin.free_config.update(query_mode="calendar", final_submit_enabled=False)
+
+    def prepare(self):
+        workflow.prepare_calendar(self.plugin, self.route, role="query")
+
+    def query_plugin(self, results):
+        self.plugin.query = MethodType(ItaPlugin.query, self.plugin)
+        self.plugin._prepared_calendar = None
+        self.plugin._resolve_route = Mock(return_value=self.route)
+        self.plugin._enter_service = Mock(return_value=results[0])
+        self.plugin._query_once = Mock(side_effect=results[1:])
+        self.plugin._reset_calendar_state = Mock()
+        return self.plugin
+
+    def test_public_query_prepares_once_with_shared_mail_adapter_and_no_terminal(self):
+        strong = VSQueryResult(success=True, availability_status=AvailabilityStatus.Available,
+                               earliest_date=datetime(2026, 10, 13))
+        plugin = self.query_plugin([VSQueryResult(success=True), strong, strong])
+        client = Mock()
+        client.fetch_mail_content.return_value = "OTP Code:001234"
+        self.fetch.side_effect = lambda *args, **kwargs: real_fetch_otp_from_cloud(
+            *args, **kwargs, api=client)
+        output = StringIO()
+        with patch.object(workflow, "submit_final") as final, redirect_stdout(output):
+            self.assertIs(plugin.query(Mock()), strong)
+            self.assertIs(plugin.query(Mock()), strong)
+        client.fetch_mail_content.assert_called_once_with(
+            email=self.route.mail.authorization_email, sender="noreply-prenotami@esteri.it",
+            recipient=plugin.config.account.username, subject_keywords="OTP Code",
+            body_keywords="OTP Code:", sent_date="2026-08-31 01:02:03", expiry=300, only_text=True)
+        client.fetch_mail_content_from_top.assert_not_called()
+        plugin._enter_service.assert_called_once()
+        self.assertEqual(plugin._query_once.call_count, 2)
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input", "#btnAvanti"])
+        self.assertEqual(self.listener.call_count, 2)
+        self.reader.assert_not_called()
+        final.assert_not_called()
+        self.plugin._record_calendar_prepared_route.assert_called_once_with(self.route, role="query")
+        self.assertNotIn("001234", output.getvalue() + str(plugin._log.call_args_list))
+
+    def test_account_mailbox_query_uses_the_new_pool_account_without_fixed_address(self):
+        self.route = replace(self.route, mail=OtpMailConfig(authorization_source="account"))
+        self.plugin.config.account.username = "new-pool-account@example.test"
+        strong = VSQueryResult(success=True, availability_status=AvailabilityStatus.Available,
+                               earliest_date=datetime(2026, 10, 13))
+        plugin = self.query_plugin([VSQueryResult(success=True), strong, strong])
+        client = Mock()
+        client.fetch_mail_content.return_value = "OTP Code:001234"
+        self.fetch.side_effect = lambda *args, **kwargs: real_fetch_otp_from_cloud(*args, **kwargs, api=client)
+        with patch.object(workflow, "submit_final") as final, redirect_stdout(StringIO()):
+            self.assertIs(plugin.query(Mock()), strong)
+            self.assertIs(plugin.query(Mock()), strong)
+        client.fetch_mail_content.assert_called_once()
+        self.assertEqual(client.fetch_mail_content.call_args.kwargs["email"], "new-pool-account@example.test")
+        self.assertEqual(client.fetch_mail_content.call_args.kwargs["recipient"], "new-pool-account@example.test")
+        self.assertIsNone(self.route.mail.authorization_email)
+        self.assertEqual(self.clicks, ["#otp-send", "#otp-input", "#btnAvanti"])
+        self.reader.assert_not_called()
+        final.assert_not_called()
+
+    def test_negative_entry_never_sends_otp_or_reads_mail(self):
+        negative = VSQueryResult(success=False)
+        plugin = self.query_plugin([negative])
+        self.assertIs(plugin.query(Mock()), negative)
+        self.page.run_js.assert_not_called()
+        self.listener.assert_not_called()
+        self.fetch.assert_not_called()
+        self.reader.assert_not_called()
+
+    def test_mail_failure_never_resends_or_falls_back_to_manual_in_same_session(self):
+        self.fetch.side_effect = preparation.CalendarGateError("Italy OTP mailbox read failed")
+        with redirect_stdout(StringIO()):
+            with self.assertRaises(preparation.CalendarGateError):
+                self.prepare()
+            with self.assertRaises(PermissionDeniedError):
+                self.prepare()
+        self.fetch.assert_called_once()
+        self.reader.assert_not_called()
+        self.assertEqual(self.clicks, ["#otp-send"])
+        self.plugin._record_calendar_prepared_route.assert_not_called()
+
+    def test_expired_mail_is_not_written(self):
+        with patch.object(workflow, "monotonic", side_effect=[0, 1, 300]), redirect_stdout(StringIO()):
+            with self.assertRaisesRegex(preparation.CalendarGateError, "window expired"):
+                self.prepare()
+        self.assertEqual(self.clicks, ["#otp-send"])
+        self.reader.assert_not_called()
+
+    def test_account_change_during_mail_read_prevents_code_write(self):
+        def changed(*args, **kwargs):
+            self.plugin.config.account.username = "other@example.test"
+            return "001234"
+        self.fetch.side_effect = changed
+        with redirect_stdout(StringIO()), self.assertRaises(preparation.CalendarGateError):
+            self.prepare()
+        self.assertEqual(self.clicks, ["#otp-send"])
+        self.reader.assert_not_called()
+
+    def test_ambiguous_mail_rejected_by_existing_parser_before_avanti(self):
+        client = Mock()
+        client.fetch_mail_content.return_value = "OTP Code:001234 OTP Code:654321"
+        self.fetch.side_effect = lambda *args, **kwargs: real_fetch_otp_from_cloud(
+            *args, **kwargs, api=client)
+        with redirect_stdout(StringIO()), self.assertRaisesRegex(preparation.CalendarGateError, "mail rejected"):
+            self.prepare()
+        self.assertEqual(self.clicks, ["#otp-send"])
+        self.reader.assert_not_called()
+        client.fetch_mail_content_from_top.assert_not_called()
+
+    def test_missing_mail_configuration_stops_before_site_actions(self):
+        self.route = replace(self.route, mail=None)
+        with self.assertRaisesRegex(preparation.CalendarGateError, "configuration is missing"):
+            self.prepare()
+        self.page.run_js.assert_not_called()
+        self.listener.assert_not_called()
+        self.fetch.assert_not_called()
+
+    def test_query_cannot_enable_final_submission_or_use_book_preparation(self):
+        for values, role in (({}, "book"), ({"final_submit_enabled": True}, "query")):
+            with self.subTest(role=role):
+                self.plugin.free_config.update(values)
+                with self.assertRaises(PermissionDeniedError):
+                    workflow.prepare_calendar(self.plugin, self.route, role=role)
+        self.page.run_js.assert_not_called()
+        self.listener.assert_not_called()
+        self.fetch.assert_not_called()
+
+class RecoveryWorkflowTests(TestCase):
+    listen = PreparationTests.listen
+
+    def setUp(self):
+        PreparationTests.setUp(self)
+        self.token_ready = False
+        self.page.run_js.side_effect = lambda _: booking_preflight_snapshot(
+            turnstileReady=self.token_ready, otpValuePresent=self.otp_present,
+            otpSendEnabled=not self.otp_present)
+        self.helper = Mock()
+        self.helper.click_verification_button.return_value = False
+        self.factory = self.stack.enter_context(patch.object(ita_turnstile, 'CloudflareBypasser',
+                                                             return_value=self.helper))
+        self.stack.enter_context(patch.object(preparation.time, 'sleep'))
+
+    def assert_preparation_recovers(self, role):
+        def clicked(**kwargs):
+            self.assertEqual(self.clicks, [])
+            self.token_ready = True
+            return True
+        self.helper.click_verification_button.side_effect = clicked
+        times = itertools.chain([0, 0, 5, 6], itertools.count(7))
+        output = StringIO()
+        with patch.object(preparation.time, 'monotonic', side_effect=lambda: next(times)), redirect_stdout(output):
+            workflow.prepare_calendar(self.plugin, self.route, role=role)
+        self.helper.click_verification_button.assert_called_once_with(is_dfs=False)
+        self.assertEqual(self.clicks, ['#otp-send', '#otp-input', '#btnAvanti'])
+        self.reader.assert_called_once()
+        self.assertEqual(self.listener.call_count, 2)
+        self.assertGreaterEqual(self.page.run_js.call_count, 3)
+        self.assertNotIn('ITA_BOOK_PREFLIGHT_DIAGNOSTIC=', output.getvalue())
+        self.factory.assert_called_once_with(self.page, log=False)
+        self.helper.bypass.assert_not_called()
+
+    def test_book_interaction_is_followed_by_real_readback_before_one_otp(self):
+        self.assert_preparation_recovers('book')
+        self.plugin._record_calendar_prepared_route.assert_called_once_with(self.route, role="book")
+
+    def test_query_reuses_book_recovery_then_records_only_query_preparation(self):
+        self.assert_preparation_recovers('query')
+        self.plugin._record_calendar_prepared_route.assert_called_once_with(self.route, role="query")
+
+    def test_query_three_clicks_without_token_cannot_release_otp(self):
+        self.helper.click_verification_button.return_value = True
+        with patch.object(preparation.time, 'monotonic', side_effect=[0, 0, 5, 15, 25, 35, 121]), \
+             redirect_stdout(StringIO()), self.assertRaisesRegex(preparation.CalendarGateError, 'turnstile_token_pending'):
+            workflow.prepare_calendar(self.plugin, self.route, role='query')
+        self.assertEqual(self.helper.click_verification_button.call_count, 3)
+        self.listener.assert_not_called()
+        self.reader.assert_not_called()
+        self.assertEqual(self.clicks, [])
+        self.plugin._record_calendar_prepared_route.assert_not_called()
+
+    def test_query_stages_share_one_recovery_budget(self):
+        # The third click yields a real token. Expiry after sending OTP must not
+        # create a fresh recovery budget or allow AVANTI without a new token.
+        def clicked(**kwargs):
+            if self.helper.click_verification_button.call_count == 3:
+                self.token_ready = True
+            return True
+        self.helper.click_verification_button.side_effect = clicked
+        def click(ele):
+            self.clicks.append(ele.selector)
+            if ele.selector == '#otp-send':
+                self.token_ready = False
+        self.plugin.mouse.human_click_ele = click
+        ticks = [0, 0, 5, 15, 25, 26, 27, 27, 32, 42, 52, 148]
+        with patch.object(preparation.time, 'monotonic', side_effect=ticks), \
+             redirect_stdout(StringIO()), self.assertRaisesRegex(preparation.CalendarGateError, 'turnstile_token_pending'):
+            workflow.prepare_calendar(self.plugin, self.route, role='query')
+        self.factory.assert_called_once_with(self.page, log=False)
+        self.assertEqual(self.helper.click_verification_button.call_count, 3)
+        self.assertEqual(self.clicks, ['#otp-send', '#otp-input'])
+        self.assertEqual(self.listener.call_count, 1)
+        self.plugin._record_calendar_prepared_route.assert_not_called()
+
+    def test_query_ready_widget_does_not_invoke_helper(self):
+        self.token_ready = True
+        with redirect_stdout(StringIO()):
+            workflow.prepare_calendar(self.plugin, self.route, role='query')
+        self.factory.assert_not_called()
+        self.assertEqual(self.clicks, ['#otp-send', '#otp-input', '#btnAvanti'])
+
+    def test_prepared_query_skips_recovery_and_all_preparation_actions(self):
+        self.page.url = 'https://prenotami.esteri.it/BookingCalendar'
+        with patch.object(workflow, 'turnstile_recovery') as recovery:
+            self.assertIsNone(workflow.prepare_query_if_needed(self.plugin, Mock()))
+        recovery.assert_not_called()
+        self.factory.assert_not_called()
+        self.listener.assert_not_called()
+        self.page.run_js.assert_not_called()
+
+    def test_book_timeout_stops_before_otp(self):
+        output = StringIO()
+        with patch.object(preparation.time, 'monotonic', side_effect=[0, 0, 5, 121]), \
+             redirect_stdout(output), self.assertRaisesRegex(preparation.CalendarGateError, 'turnstile_token_pending'):
+            workflow.prepare_calendar(self.plugin, self.route, role='book')
+        self.listener.assert_not_called()
+        self.reader.assert_not_called()
+        self.assertEqual(self.clicks, [])
+        self.assertIn('ITA_BOOK_WAITING_FOR_FORM:', output.getvalue())
+        self.assertNotIn('ITA_BOOK_PREFLIGHT_DIAGNOSTIC=', output.getvalue())
+        self.helper.bypass.assert_not_called()
+
+    def test_cloud_book_timeout_never_calls_mail_api(self):
+        self.plugin.free_config['otp_mode'] = 'cloud'
+        self.route = replace(self.route, mail=OtpMailConfig('mailbox@example.test'))
+        with patch.object(preparation.time, 'monotonic', side_effect=[0, 0, 5, 121]), \
+             patch.object(workflow, 'fetch_otp_from_cloud') as fetch, \
+             redirect_stdout(StringIO()), self.assertRaises(preparation.CalendarGateError):
+            workflow.prepare_calendar(self.plugin, self.route, role='book')
+        fetch.assert_not_called()
+        self.listener.assert_not_called()
+        self.reader.assert_not_called()
+
+
+class ProductionEntryTests(TestCase):
+    def setUp(self):
+        self.plugin, self.route, self.trigger = flow.prepared_plugin(flow.FlowPage())
+        self.plugin.free_config["otp_mode"] = "manual"
+        self.inputs = {"username": self.plugin.config.account.username}
+        self.plugin.is_healthy = True
+        self.plugin._log = Mock()
+
+    def test_prepared_book_reuses_real_calendar_adapter_and_defaults_to_prefinal(self):
+        with patch.object(workflow, "submit_final") as submit, patch.object(workflow, "prepare_calendar") as prepare:
+            result = self.plugin.book(self.trigger, self.inputs)
+        self.assertFalse(result.success)
+        self.assertEqual(result.label, "calendar-ready-before-final")
+        self.assertEqual(self.plugin.page.clicks, 1)
+        self.assertEqual(self.plugin.page.guard_final_count, 0)
+        submit.assert_not_called()
+        prepare.assert_not_called()
+
+    def test_cloud_book_reuses_selection_without_enabling_final(self):
+        self.plugin.free_config["otp_mode"] = "cloud"
+        with patch.object(workflow, "submit_final") as submit:
+            result = self.plugin.book(self.trigger, self.inputs)
+        self.assertEqual(result.label, "calendar-ready-before-final")
+        self.assertEqual(self.plugin.page.clicks, 1)
+        self.assertFalse(result.success)
+        submit.assert_not_called()
+
+    def test_cloud_final_uses_the_existing_submitter_after_fresh_selection(self):
+        self.plugin.free_config.update(otp_mode="cloud", final_submit_enabled=True)
+        confirmed = VSBookResult(success=True, book_date="2026-10-13", book_time="09:26")
+        with patch.object(workflow, "submit_final", return_value=confirmed) as submit:
+            result = self.plugin.book(self.trigger, self.inputs)
+        self.assertIs(result, confirmed)
+        self.assertIs(submit.call_args.args[0], self.plugin)
+        self.assertEqual(submit.call_args.args[1], self.route)
+        self.assertIsNotNone(submit.call_args.args[2])
+
+    def test_invalid_final_flag_is_rejected_before_site_actions(self):
+        self.plugin.free_config.update(otp_mode="cloud", final_submit_enabled="true")
+        with patch.object(workflow, "submit_final") as submit, \
+             patch.object(workflow, "prepare_calendar") as prepare, self.assertRaises(PermissionDeniedError):
+            self.plugin.book(self.trigger, self.inputs)
+        submit.assert_not_called()
+        prepare.assert_not_called()
+
+    def test_cloud_final_no_inventory_never_submits(self):
+        self.plugin.free_config.update(otp_mode="cloud", final_submit_enabled=True)
+        self.plugin.page = flow.FlowPage([flow.month(m, {}) for m in ("2026-10", "2026-11", "2026-12")])
+        self.plugin._record_calendar_prepared_route(self.route, role="book")
+        with patch.object(workflow, "submit_final") as submit, flow.browser_navigation(self.plugin.page):
+            result = self.plugin.book(self.trigger, self.inputs)
+        self.assertFalse(result.success)
+        submit.assert_not_called()
+
+    def test_enabled_book_returns_standard_result_after_real_slot_selection(self):
+        self.plugin.free_config["final_submit_enabled"] = True
+        confirmed = VSBookResult(success=True, book_date="2026-10-13", book_time="09:26")
+        with patch.object(workflow, "submit_final", return_value=confirmed) as submit:
+            result = self.plugin.book(self.trigger, self.inputs)
+        self.assertIs(result, confirmed)
+        self.assertIs(submit.call_args.args[0], self.plugin)
+        self.assertEqual(submit.call_args.args[1], self.route)
+        self.assertIsNotNone(submit.call_args.args[2])
+
+    def test_one_public_book_call_prepares_and_selects_from_dashboard(self):
+        plugin = self.plugin
+        plugin.page.url = "https://prenotami.esteri.it/UserArea"
+        plugin._prepared_calendar = None
+        def entry(apt, **kwargs):
+            plugin.page.url = "https://prenotami.esteri.it" + plugin._booking_path(self.route)
+            return VSQueryResult(success=True)
+        plugin._enter_service = Mock(side_effect=entry)
+        def prepare(p, route, *, role):
+            self.assertEqual(role, "book")
+            p.page.url = "https://prenotami.esteri.it/BookingCalendar"
+            p._record_calendar_prepared_route(route, role="book")
+        with patch.object(workflow, "prepare_calendar", side_effect=prepare) as prep:
+            result = plugin.book(self.trigger, self.inputs)
+        prep.assert_called_once()
+        plugin._enter_service.assert_called_once_with(self.trigger.apt_type, route=self.route)
+        plugin.query.assert_not_called()
+        self.assertEqual(result.label, "calendar-ready-before-final")
+        self.assertEqual(plugin.page.clicks, 1)
+
+    def test_final_config_requires_explicit_supported_applicant_mode(self):
+        for values, accepted in (({}, True), ({"otp_mode": "manual"}, True),
+                ({"otp_mode": "cloud"}, True),
+                ({"otp_mode": "cloud", "final_submit_enabled": True}, True),
+                ({"otp_mode": "cloud", "query_mode": "calendar"}, True),
+                ({"otp_mode": "cloud", "query_mode": "calendar", "final_submit_enabled": True}, False),
+                ({"otp_mode": "cloud", "final_submit_enabled": "true"}, False),
+                ({"otp_mode": "cloud", "final_submit_enabled": 1}, False),
+                ({"otp_mode": "manual", "final_submit_enabled": True}, True),
+                ({"final_submit_enabled": True}, False),
+                ({"otp_mode": "manual", "final_submit_enabled": 1}, False),
+                ({"otp_mode": "manual", "final_submit_enabled": True, "query_mode": "calendar"}, False)):
+            with self.subTest(values=values):
+                config = VSPlgConfig(free_config=values)
+                if accepted:
+                    self.plugin.set_config(config)
+                else:
+                    with self.assertRaises(BizLogicError):
+                        self.plugin.set_config(config)
+
+    def test_no_inventory_never_calls_final(self):
+        self.plugin.page = flow.FlowPage([flow.month(m, {}) for m in ("2026-10", "2026-11", "2026-12")])
+        self.plugin._record_calendar_prepared_route(self.route, role="book")
+        with patch.object(workflow, "submit_final") as submit, flow.browser_navigation(self.plugin.page):
+            result = self.plugin.book(self.trigger, self.inputs)
+        self.assertFalse(result.success)
+        submit.assert_not_called()
+
+    def test_query_or_another_applicant_cannot_book(self):
+        context = self.plugin._prepared_calendar
+        for query_key, username in ((self.route.routing_key, self.inputs["username"]), (None, "other@example.test")):
+            self.plugin._prepared_calendar = replace(context, role="query" if query_key else "book")
+            with self.assertRaises(BizLogicError), patch.object(workflow, "submit_final") as submit:
+                self.plugin.book(self.trigger, {"username": username})
+            submit.assert_not_called()
+
+    def test_cloud_final_rejects_query_session_and_other_applicant(self):
+        self.plugin.free_config.update(otp_mode="cloud", final_submit_enabled=True)
+        context = self.plugin._prepared_calendar
+        for query_key, username in ((self.route.routing_key, self.inputs["username"]), (None, "other@example.test")):
+            self.plugin._prepared_calendar = replace(context, role="query" if query_key else "book")
+            with patch.object(workflow, "submit_final") as submit, self.assertRaises(BizLogicError):
+                self.plugin.book(self.trigger, {"username": username})
+            submit.assert_not_called()
+
+    def test_query_from_dashboard_prepares_once_and_never_returns_weak_positive(self):
+        plugin = self.plugin
+        plugin.query = MethodType(ItaPlugin.query, plugin)
+        plugin.free_config["query_mode"] = "calendar"
+        plugin.page.url = "https://prenotami.esteri.it/UserArea"
+        plugin._prepared_calendar = None
+        strong = VSQueryResult(success=True, availability_status=AvailabilityStatus.Available,
+                               earliest_date=datetime(2026, 10, 13), apt_type=self.trigger.apt_type)
+        plugin._enter_service = Mock(return_value=VSQueryResult(success=True))
+        plugin._query_once = Mock(return_value=strong)
+        def prepare(p, route, *, role):
+            self.assertEqual(role, "query")
+            p.page.url = "https://prenotami.esteri.it/BookingCalendar"
+        with patch.object(workflow, "prepare_calendar", side_effect=prepare) as prep:
+            self.assertIs(plugin.query(self.trigger.apt_type), strong)
+            self.assertIs(plugin.query(self.trigger.apt_type), strong)
+        self.assertEqual(prep.call_count, 1)
+        plugin._enter_service.assert_called_once()
+        self.assertEqual(plugin._query_once.call_count, 2)
+
+    def test_entry_no_availability_does_not_send_otp(self):
+        self.plugin.page.url = "https://prenotami.esteri.it/UserArea"
+        negative = VSQueryResult(success=False)
+        self.plugin._enter_service = Mock(return_value=negative)
+        with patch.object(workflow, "prepare_calendar") as prep:
+            self.assertIs(workflow.prepare_query_if_needed(self.plugin, self.trigger.apt_type), negative)
+        prep.assert_not_called()
+
+    def test_production_modules_never_import_debug_tools(self):
+        root = Path(__file__).resolve().parents[2]
+        for filename in ("ita_plugin.py",):
+            tree = ast.parse((root / "plugins" / filename).read_text())
+            imports = [n.module for n in ast.walk(tree) if isinstance(n, ast.ImportFrom)]
+            self.assertFalse(any(name and name.startswith("tools") for name in imports))
+
+
+class BookerReuseTests(TestCase):
+    def setUp(self):
+        # Reuse existing offline Redis import fixture; never open Redis/cloud.
+        from test.ita.test_ita_plugin import OrderBookerGCO
+        from threading import RLock
+        self.booker = OrderBookerGCO.__new__(OrderBookerGCO)
+        self.booker.m_lock = RLock()
+        self.booker.m_task_data_cache = {"fixture": {"status": "running", "order_id": "order", "user_inputs": {}}}
+        self.booker._log = Mock()
+        self.booker._remove_task = Mock()
+        self.booker._push_success_notification = Mock()
+        self.booker.redis_client = Mock()
+        self.booker.m_tracker_key = "fixture"
+        self.task = SimpleNamespace(task_ref="fixture", book_allowed=True, instance=Mock())
+        self.api = Mock()
+        api_patch = patch.dict(self.booker._execute_book_job.__func__.__globals__, VSCloudApi=self.api)
+        api_patch.start()
+        self.addCleanup(api_patch.stop)
+
+    def test_standard_success_still_uses_existing_reporting(self):
+        result = VSBookResult(success=True, book_date="2026-10-13", book_time="09:26")
+        self.task.instance.book.return_value = result
+        self.booker._execute_book_job(self.task, VSQueryResult())
+        self.booker._push_success_notification.assert_called_once_with("fixture", "order", result)
+
+    def test_standard_failure_is_called_again_on_the_next_signal(self):
+        self.task.instance.book.return_value = VSBookResult(success=False)
+        self.booker._execute_book_job(self.task, VSQueryResult())
+        self.booker._execute_book_job(self.task, VSQueryResult())
+        self.api.Instance.return_value.update_vas_task.assert_not_called()
+        self.assertTrue(self.task.book_allowed)
+        self.assertEqual(self.task.instance.book.call_count, 2)
+        self.booker._push_success_notification.assert_not_called()
+
+
+class QueryCliTests(TestCase):
+    def test_workflow_flag_reuses_route_builder_and_calls_standard_query(self):
+        from tools import debug_ita_query as cli
+        from test.ita.test_debug_ita_calendar_gate import gate_env
+        plugin = Mock()
+        plugin.query.return_value = VSQueryResult(success=True, availability_status=AvailabilityStatus.Available,
+                                                   earliest_date=datetime(2026, 10, 13))
+        stdout = StringIO()
+        with patch.object(cli, "ItaPlugin", return_value=plugin), \
+                patch.object(cli, "resolve_chrome_path", return_value=Path("/offline/chrome")), \
+                patch.object(cli, "_get_query_credentials", return_value=("query@example.test", "fixture")), \
+                patch.object(cli, "_prepare_query_profile", return_value=Path("/offline/profile")), \
+                patch.object(cli, "_bind_query_profile", return_value=Mock()), \
+                redirect_stdout(stdout):
+            code = cli.run_query_once(gate_env(), non_interactive=False, production_workflow=True)
+        self.assertEqual(code, 0)
+        config = plugin.set_config.call_args.args[0]
+        self.assertEqual(config.free_config["query_mode"], "calendar")
+        self.assertEqual(config.free_config["otp_mode"], "manual")
+        self.assertIs(config.free_config["final_submit_enabled"], False)
+        plugin.query.assert_called_once()
+        plugin.book.assert_not_called()
+        plugin.cleanup.assert_called_once()
+        self.assertIn("ITA_QUERY_WORKFLOW_RESULT=", stdout.getvalue())
+
+    def test_headless_workflow_rejected_before_credentials(self):
+        from tools import debug_ita_query as cli
+        with patch.object(cli, "_get_query_credentials") as credentials:
+            with self.assertRaises(cli.DebugConfigurationError):
+                cli.run_query_once({}, non_interactive=True, production_workflow=True)
+        credentials.assert_not_called()

+ 259 - 0
test/ita/test_plugin_tester_ita_config.py

@@ -0,0 +1,259 @@
+"""Offline checks for the Italy profile consumed by the existing public tester."""
+
+import copy
+from contextlib import redirect_stderr, redirect_stdout
+import io
+import json
+import logging
+from pathlib import Path
+from types import SimpleNamespace
+import unittest
+from unittest.mock import Mock, patch
+
+from plugins.ita_plugin import ItaCapability, resolve_route_config
+from sentinel import SentinelGCO
+from tools import debug_ita_query_book as query_book_cli
+from tools.plugin_tester import PluginTester
+from vs_types import GroupConfig
+
+
+def hong_kong_group():
+    groups = json.loads((Path(__file__).resolve().parents[2] / "config/config_sentinel.json").read_text())
+    matches = [group for group in groups if group["identifier"] == "ita.hong_kong"]
+    if len(matches) != 1:
+        raise AssertionError("Expected exactly one Hong Kong Sentinel profile")
+    return GroupConfig.from_json(matches[0])
+
+
+class ItalyPublicTesterConfigTests(unittest.TestCase):
+    def setUp(self):
+        # Exercise the actual JSON loader and registration, never create a plugin,
+        # open a browser, or use the configured credentials in an assertion.
+        with patch("vs_plg_factory.VSC_INFO"), patch(
+            "tools.plugin_tester.VSPlgFactory.create",
+            side_effect=AssertionError("Offline configuration check must not create a plugin"),
+        ):
+            self.tester = PluginTester.from_json_config(
+                "ita_plugin",
+                str(Path(__file__).resolve().parents[2] / "config/test_conf.json"),
+                user_override="query@example.test",
+                password_override="synthetic-not-a-secret",
+                proxy_override="http://127.0.0.1:9999",
+            )
+
+    def test_existing_loader_resolves_one_hong_kong_appointment(self):
+        self.assertIsNone(self.tester.plugin)
+        self.assertEqual(self.tester.group_id, "ita.hong_kong")
+        self.assertEqual(len(self.tester.appointment_types), 1)
+        appointment = self.tester.appointment_types[0]
+        self.assertEqual(appointment.routing_key, "slot.hkg.it.tourist")
+        self.assertEqual(appointment.city, "Hong Kong")
+        self.assertEqual(appointment.country, "Italy")
+        self.assertEqual(appointment.visa_type, "Tourist")
+
+    def test_query_profile_uses_cloud_preparation_and_disables_final_submission(self):
+        config = self.tester.config
+        self.assertIs(config.debug, False)
+        self.assertEqual(config.free_config["query_mode"], "calendar")
+        self.assertEqual(config.free_config["otp_mode"], "cloud")
+        self.assertIs(config.free_config["final_submit_enabled"], False)
+
+    def test_existing_protocol_parser_accepts_evidenced_form_and_scan_settings(self):
+        route = resolve_route_config(
+            self.tester.config.free_config["apt_configs"],
+            self.tester.appointment_types[0].routing_key,
+        )
+        self.assertEqual(route.service_id, 4937)
+        self.assertIs(route.capability, ItaCapability.SINGLE_SCHENGEN_TOURISM)
+        self.assertEqual(route.lookahead_months, 12)
+        self.assertEqual(route.booking_type.control_id, "typeofbookingddl")
+        self.assertEqual(route.booking_type.value, "1")
+        self.assertEqual(route.booking_type.labels, ("Prenotazione Singola", "Single booking"))
+        self.assertEqual(route.purpose.control_id, "ddls_0")
+        self.assertEqual(route.purpose.value, "42")
+        self.assertEqual(route.purpose.labels, ("Turismo", "Tourism"))
+        self.assertIsNotNone(route.mail)
+        self.assertEqual(route.mail.authorization_source, "account")
+        self.assertIsNone(route.mail.authorization_email)
+        self.assertEqual(route.mail.mailbox_for("query@example.test"), "query@example.test")
+
+    def test_public_tester_and_sentinel_share_route_and_otp_contract(self):
+        group = hong_kong_group()
+        config = self.tester.config.free_config
+        self.assertEqual(group.appointment_types, self.tester.appointment_types)
+        for key in ("website", "query_mode", "otp_mode", "final_submit_enabled", "apt_configs"):
+            self.assertEqual(group.free_config[key], config[key])
+
+
+class ItalySingleAccountPoolConfigTests(unittest.TestCase):
+    def setUp(self):
+        self.group = hong_kong_group()
+        # Do not create browsers, read account secrets or call a live backend.
+        for target in ("socket.socket.connect", "socket.socket.connect_ex", "socket.create_connection",
+                       "requests.sessions.Session.request", "subprocess.Popen"):
+            self.enterContext(patch(target, side_effect=AssertionError("Offline test attempted external I/O")))
+        self.cloud = Mock()
+        self.cloud.get_next_account.return_value = {
+            "id": 71, "pool_name": "hkg.it.sentinel", "username": "pooled@example.test",
+            "password": "synthetic-pool-password", "status": "active",
+        }
+        self.cloud.get_next_proxy.return_value = {"id": 72, "ip": "127.0.0.1", "port": 9999}
+        self.redis = Mock()
+        self.enterContext(patch.dict(SentinelGCO.__init__.__globals__, {
+            "SafeRedisClient": Mock(return_value=self.redis),
+            "VSCloudApi": SimpleNamespace(Instance=lambda: self.cloud),
+        }))
+        self.sentinel = SentinelGCO(self.group, {}, Mock())
+        self.plugin = Mock()
+        self.sentinel.m_factory.create = Mock(return_value=self.plugin)
+        self.addCleanup(self.sentinel.stop)
+
+    def test_profile_is_disabled_single_instance_cloud_query_without_local_credentials(self):
+        group = self.group
+        self.assertFalse(group.enable)
+        self.assertFalse(group.debug)
+        self.assertTrue(group.need_account)
+        self.assertEqual(group.sentinel.account_source, "built-in")
+        self.assertEqual(group.sentinel.account_pool_id, "hkg.it.sentinel")
+        self.assertEqual(group.sentinel.target_instances, 1)
+        self.assertEqual(group.sentinel.account_cd, group.session_max_life)
+        self.assertEqual(group.sentinel.account_cd, 1800)
+        self.assertEqual(group.free_config["otp_mode"], "cloud")
+        self.assertIs(group.free_config["final_submit_enabled"], False)
+        for key in ("account", "password", "local_account_file", "authorization_code"):
+            self.assertNotIn(key, group.free_config)
+        self.sentinel.start()
+        self.sentinel.m_factory.create.assert_not_called()
+        self.cloud.get_next_account.assert_not_called()
+
+    def test_existing_sentinel_spawner_binds_pool_account_and_mail_configuration(self):
+        before = copy.deepcopy(self.group)
+        self.sentinel._spawn_sentinel_worker()
+        self.cloud.get_next_account.assert_called_once_with("hkg.it.sentinel", 1800)
+        self.cloud.get_next_proxy.assert_called_once_with(self.group.proxy_pool, self.group.proxy_cd)
+        self.plugin.set_config.assert_called_once()
+        config = self.plugin.set_config.call_args.args[0]
+        self.assertEqual(config.account.id, 71)
+        self.assertEqual(config.account.username, "pooled@example.test")
+        self.assertEqual(config.account.password, "synthetic-pool-password")
+        self.assertEqual(config.free_config, self.group.free_config)
+        self.assertEqual(self.group, before)
+        self.plugin.create_session.assert_called_once()
+        self.assertEqual(len(self.sentinel.m_tasks), 1)
+        self.assertFalse(self.sentinel.m_tasks[0].book_allowed)
+        self.plugin.book.assert_not_called()
+        self.redis.setex.assert_not_called()
+
+    def test_empty_or_cooling_pool_does_not_fall_back_to_a_local_account(self):
+        self.cloud.get_next_account.side_effect = RuntimeError("synthetic unavailable pool")
+        self.sentinel._spawn_sentinel_worker()
+        self.cloud.get_next_account.assert_called_once_with("hkg.it.sentinel", 1800)
+        self.sentinel.m_factory.create.assert_not_called()
+        self.plugin.create_session.assert_not_called()
+        self.assertEqual(self.sentinel.m_tasks, [])
+
+
+class ItalyPoolQueryCommandTests(unittest.TestCase):
+    def setUp(self):
+        for target in ("socket.socket.connect", "socket.socket.connect_ex", "socket.create_connection",
+                       "requests.sessions.Session.request", "subprocess.Popen"):
+            self.enterContext(patch(target, side_effect=AssertionError("Offline test attempted external I/O")))
+        logger = logging.Logger("ita-pool-command-offline", level=logging.INFO)
+        self.enterContext(patch("vs_log_macros._active_logger", logger))
+        self.enterContext(patch("configure.TEST_ACCOUNT", None))
+        self.cloud = Mock()
+        self.cloud.get_next_account.return_value = {
+            "id": 71, "username": "first-pool-account@example.test",
+            "password": "synthetic-command-password", "pool_name": "hkg.it.sentinel", "status": "active",
+        }
+        self.enterContext(patch("toolkit.vs_cloud_api.VSCloudApi.Instance", return_value=self.cloud))
+        self.pipeline = self.enterContext(patch.object(PluginTester, "run_pipeline", autospec=True, return_value=True))
+        self.enterContext(patch("utils.local_account.load_local_account",
+                                side_effect=AssertionError("Pool test must not load a local account")))
+
+    def run_pool_query(self):
+        output = io.StringIO()
+        with redirect_stdout(output):
+            code = query_book_cli.main(["--pool-query"])
+        return code, output.getvalue()
+
+    def test_supported_command_uses_existing_sdk_and_public_tester_query_only(self):
+        code, output = self.run_pool_query()
+        self.assertEqual(code, 0)
+        self.cloud.get_next_account.assert_called_once_with("hkg.it.sentinel", 1800)
+        self.pipeline.assert_called_once()
+        self.assertEqual(self.pipeline.call_args.kwargs, {"test_book": False})
+        tester = self.pipeline.call_args.args[0]
+        self.assertEqual(tester.config.account.id, 71)
+        self.assertEqual(tester.config.account.password, "synthetic-command-password")
+        self.assertEqual(tester.config.free_config, hong_kong_group().free_config)
+        self.assertEqual(tester.config.proxy.port, 6268)
+        self.assertIsNone(tester.plugin)
+        self.assertIn("ITA_POOL_QUERY_SOURCE=cloud_pool pool=hkg.it.sentinel book=false", output)
+        self.assertNotIn("synthetic-command-password", output)
+        self.assertIn("ITA_POOL_QUERY_CONTRACT=account-mailbox-v3", output)
+
+    def test_second_pool_account_is_accepted_and_resolves_its_own_mailbox(self):
+        for address in ("first-pool-account@example.test", "second-pool-account@example.test"):
+            with self.subTest(address=address):
+                self.pipeline.reset_mock()
+                self.cloud.get_next_account.return_value["username"] = address
+                code, _ = self.run_pool_query()
+                self.assertEqual(code, 0)
+                tester = self.pipeline.call_args.args[0]
+                route = resolve_route_config(tester.config.free_config["apt_configs"],
+                                             tester.appointment_types[0].routing_key)
+                self.assertEqual(route.mail.mailbox_for(tester.config.account.username), address)
+                self.assertIsNone(route.mail.authorization_email)
+
+    def test_debug_payload_logging_is_not_an_italy_allocation_gate(self):
+        with patch("vs_log_macros._active_logger", logging.Logger("unsafe-fixture", level=logging.DEBUG)):
+            code, output = self.run_pool_query()
+        self.assertEqual(code, 0)
+        self.assertIn("ITA_POOL_QUERY_SOURCE=cloud_pool", output)
+        self.cloud.get_next_account.assert_called_once()
+        self.pipeline.assert_called_once()
+
+    def test_test_account_override_stops_before_pool_allocation(self):
+        with patch("configure.TEST_ACCOUNT", {"username": "fixture@example.test"}):
+            code, output = self.run_pool_query()
+        self.assertEqual(code, 1)
+        self.assertIn("ITA_POOL_QUERY_ACCOUNT_REJECTED reason=test_account_override_enabled", output)
+        self.cloud.get_next_account.assert_not_called()
+        self.pipeline.assert_not_called()
+
+    def test_pool_failure_does_not_fall_back_or_print_backend_error_body(self):
+        self.cloud.get_next_account.side_effect = RuntimeError("synthetic-sensitive-response")
+        code, output = self.run_pool_query()
+        self.assertEqual(code, 1)
+        self.assertIn("ITA_POOL_QUERY_ACCOUNT_FAILED type=RuntimeError", output)
+        self.assertNotIn("synthetic-sensitive-response", output)
+        self.pipeline.assert_not_called()
+
+    def test_wrong_pool_empty_password_or_disabled_account_stops_before_browser(self):
+        original = self.cloud.get_next_account.return_value.copy()
+        for field, value in (("pool_name", "other.pool"), ("password", ""), ("status", "disable")):
+            with self.subTest(field=field):
+                self.cloud.get_next_account.return_value = {**original, field: value}
+                code, output = self.run_pool_query()
+                self.assertEqual(code, 1)
+                self.assertIn("ITA_POOL_QUERY_ACCOUNT_REJECTED", output)
+                self.pipeline.assert_not_called()
+
+    def test_invalid_account_email_stops_before_browser(self):
+        self.cloud.get_next_account.return_value["username"] = "not-an-email"
+        code, output = self.run_pool_query()
+        self.assertEqual(code, 1)
+        self.assertIn("ITA_POOL_QUERY_MAIL_CONFIG_FAILED", output)
+        self.pipeline.assert_not_called()
+
+    def test_pool_query_rejects_final_submission_before_account_allocation(self):
+        with self.assertRaises(SystemExit) as raised, redirect_stderr(io.StringIO()):
+            query_book_cli.main(["--pool-query", "--submit-once"])
+        self.assertEqual(raised.exception.code, 2)
+        self.cloud.get_next_account.assert_not_called()
+        self.pipeline.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 123 - 0
utils/local_account.py

@@ -0,0 +1,123 @@
+"""Load a locally stored account without exposing its secret values."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+from vs_types import VSAccount
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+LOCAL_ACCOUNT_KEYS = frozenset(
+    {"username", "password", "account_upload_token"}
+)
+
+
+class LocalAccountConfigurationError(ValueError):
+    """Raised when a local account file cannot be used safely."""
+
+
+def _resolved_path(
+    path: str | Path,
+    *,
+    allowed_root: Path | None,
+) -> Path:
+    candidate = Path(path).expanduser()
+    if not candidate.is_absolute():
+        candidate = (allowed_root or PROJECT_ROOT) / candidate
+    resolved = candidate.resolve()
+
+    if allowed_root is not None:
+        resolved_root = allowed_root.resolve()
+        if resolved != resolved_root and not resolved.is_relative_to(resolved_root):
+            raise LocalAccountConfigurationError(
+                "local account file must stay inside the configured project root"
+            )
+    return resolved
+
+
+def read_local_account_config(
+    path: str | Path,
+    *,
+    allowed_root: Path | None = PROJECT_ROOT,
+) -> dict[str, str]:
+    """Read the shared local JSON schema used by runtime and onboarding tools."""
+    if not str(path).strip():
+        raise LocalAccountConfigurationError("local_account_file is required")
+
+    resolved = _resolved_path(path, allowed_root=allowed_root)
+    try:
+        file_stat = resolved.stat()
+    except FileNotFoundError as exc:
+        raise LocalAccountConfigurationError(
+            "local account file does not exist"
+        ) from exc
+    except OSError as exc:
+        raise LocalAccountConfigurationError(
+            f"cannot inspect local account file ({type(exc).__name__})"
+        ) from exc
+
+    if os.name == "posix" and file_stat.st_mode & (stat.S_IRWXG | stat.S_IRWXO):
+        raise LocalAccountConfigurationError(
+            "local account file permissions must deny group and other access"
+        )
+
+    try:
+        raw_config = resolved.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise LocalAccountConfigurationError(
+            f"cannot read local account file ({type(exc).__name__})"
+        ) from exc
+
+    try:
+        body = json.loads(raw_config)
+    except json.JSONDecodeError as exc:
+        raise LocalAccountConfigurationError(
+            f"local account file is invalid JSON at line {exc.lineno}, "
+            f"column {exc.colno}"
+        ) from exc
+
+    if not isinstance(body, dict):
+        raise LocalAccountConfigurationError(
+            "local account file must be a JSON object"
+        )
+
+    unexpected_keys = sorted(set(body) - LOCAL_ACCOUNT_KEYS)
+    if unexpected_keys:
+        raise LocalAccountConfigurationError(
+            "local account file contains unsupported keys: "
+            + ", ".join(unexpected_keys)
+        )
+
+    values: dict[str, str] = {}
+    for key in LOCAL_ACCOUNT_KEYS:
+        value = body.get(key, "")
+        if not isinstance(value, str):
+            raise LocalAccountConfigurationError(
+                f"local account field {key} must be a string"
+            )
+        values[key] = value
+    return values
+
+
+def load_local_account(
+    path: str | Path,
+    *,
+    allowed_root: Path | None = PROJECT_ROOT,
+) -> VSAccount:
+    """Build the framework account object from a private local JSON file."""
+    values = read_local_account_config(path, allowed_root=allowed_root)
+    username = values["username"].strip()
+    password = values["password"]
+    if not username:
+        raise LocalAccountConfigurationError(
+            "local account username is required"
+        )
+    if not password:
+        raise LocalAccountConfigurationError(
+            "local account password is required"
+        )
+    return VSAccount(id=0, username=username, password=password)

+ 3 - 1
vs_types.py

@@ -53,6 +53,9 @@ class BizLogicError(BizException):
     def __init__(self, message="Business logic error"):
         super().__init__(code=40001, message=message)
 
+class BookingOutcomeUnknownError(RuntimeError):
+    """A booking may already exist; pause for reconciliation, not a new attempt."""
+
 class AvailabilityStatus(str, Enum):
     NoneAvailable = "NoAvailable"
     Available = "Available"
@@ -301,4 +304,3 @@ class RoleStatus:
 # 语义化别名
 RunnerStatus = RoleStatus
 CoordinatorStatus = RoleStatus
-