Bladeren bron

refactor(italy): consolidate runtime for single-file hot updates

zhangweijp 2 maanden geleden
bovenliggende
commit
a22596f1fc
46 gewijzigde bestanden met toevoegingen van 5631 en 4916 verwijderingen
  1. 86 0
      docs/ita-single-file-migration.json
  2. 6 2
      docs/ita_query_book_acceptance.md
  3. 96 0
      docs/ita_single_file_refactor.md
  4. 0 457
      plugins/ita_booking_final.py
  5. 0 761
      plugins/ita_calendar_book.py
  6. 0 607
      plugins/ita_calendar_query.py
  7. 0 603
      plugins/ita_calendar_session.py
  8. 0 252
      plugins/ita_final_read_port.py
  9. 0 140
      plugins/ita_otp.py
  10. 4759 0
      plugins/ita_plugin.py
  11. 0 1168
      plugins/ita_protocol.py
  12. 0 464
      plugins/ita_reservation.py
  13. 0 66
      plugins/ita_turnstile.py
  14. 0 236
      plugins/ita_workflow.py
  15. 12 0
      test/ita_source_sections.py
  16. 3 3
      test/test_debug_ita_book.py
  17. 5 5
      test/test_debug_ita_book_gate.py
  18. 6 6
      test/test_debug_ita_calendar_gate.py
  19. 2 2
      test/test_debug_ita_production_query_gate.py
  20. 14 13
      test/test_debug_ita_query_book.py
  21. 2 2
      test/test_debug_ita_reservation.py
  22. 3 3
      test/test_ita_booker_integration.py
  23. 13 8
      test/test_ita_booking_final.py
  24. 5 5
      test/test_ita_calendar_book.py
  25. 8 4
      test/test_ita_calendar_book_flow.py
  26. 14 14
      test/test_ita_calendar_query.py
  27. 1 1
      test/test_ita_calendar_soak.py
  28. 2 2
      test/test_ita_final_attribution.py
  29. 1 1
      test/test_ita_final_evidence.py
  30. 7 7
      test/test_ita_final_read_port.py
  31. 3 3
      test/test_ita_otp.py
  32. 2 2
      test/test_ita_preflight.py
  33. 1 1
      test/test_ita_protocol.py
  34. 2 2
      test/test_ita_query_recovery.py
  35. 7 7
      test/test_ita_reservation.py
  36. 254 0
      test/test_ita_single_file.py
  37. 13 12
      test/test_ita_workflow.py
  38. 1 1
      test/test_plugin_tester_ita_config.py
  39. 204 0
      tools/consolidate_ita_plugin.py
  40. 5 5
      tools/debug_ita_book.py
  41. 11 11
      tools/debug_ita_book_gate.py
  42. 8 8
      tools/debug_ita_calendar_gate.py
  43. 6 6
      tools/debug_ita_reservation.py
  44. 1 1
      tools/debug_ita_soak.py
  45. 3 3
      tools/ita_final_evidence.py
  46. 65 22
      tools/ita_query_book_local.py

+ 86 - 0
docs/ita-single-file-migration.json

@@ -0,0 +1,86 @@
+{
+  "sourceRevision": "62c2388",
+  "target": "plugins/ita_plugin.py",
+  "integrationChanges": [
+    "ItaPlugin.version: 1.0.0 -> 1.0.1",
+    "trim Python-only trailing whitespace",
+    "retain process-wide OTP lock on the existing shared vs_plg host module"
+  ],
+  "sections": [
+    {
+      "source": "plugins/ita_protocol.py",
+      "sourceSha256": "d405aba044040292c93b5f1f7a9b4fec26e070dc0c8b62750745201a02254894",
+      "relocatedSha256": "cdbb7ccd5798ca738b7bcef0081e895eaca524bb3a3a50695a564dbf1594b5f7",
+      "renames": {
+        "time": "datetime_time"
+      }
+    },
+    {
+      "source": "plugins/ita_calendar_query.py",
+      "sourceSha256": "6f199ad0d6a03f78416708ae894cdb2ca4b8ed04b135b31ffb4b577cb8856fac",
+      "relocatedSha256": "215d46c39da2212ed889950e824d1cf0c1e458ac3a25b5742fae52b02bd7c771",
+      "renames": {}
+    },
+    {
+      "source": "plugins/ita_calendar_book.py",
+      "sourceSha256": "af0da1ed5e2c3f555ad8818857d02a12e77c2eeeb8159d7a5814e671e0b84458",
+      "relocatedSha256": "4e94d95b6521126775b29b9f84fd5a7e3ac69833cfd394ba0573f24e6f441e91",
+      "renames": {}
+    },
+    {
+      "source": "plugins/ita_booking_final.py",
+      "sourceSha256": "04b4a587f46038f7dd05af3b32786b9c95f7a5be51b53bc63e34a8c4f1062b52",
+      "relocatedSha256": "7f4fb9164ebb4d0e5561856d1500df0f8067bf9df2272764f2b9ebfee1165e34",
+      "renames": {
+        "_text": "_final_text"
+      }
+    },
+    {
+      "source": "plugins/ita_reservation.py",
+      "sourceSha256": "6e984fff53e78c89e33916a90390360b3626a03a65fa1e774c8b1d6dbd1394a5",
+      "relocatedSha256": "2d1fb0659898b37b309183519e22078360cb49da3274a749e77f83fcca5a6b5b",
+      "renames": {
+        "_text": "_reservation_text"
+      }
+    },
+    {
+      "source": "plugins/ita_final_read_port.py",
+      "sourceSha256": "5fea80217be06324d29dd7bdd47e5d22fc1668f389535f36b722f8593b55236f",
+      "relocatedSha256": "38a8975edbf1806b9aa98c11dddaf6297c288fda93b1aee9fc92147996f75471",
+      "renames": {}
+    },
+    {
+      "source": "plugins/ita_calendar_session.py",
+      "sourceSha256": "b15f123e472e9dfcc077338bc2956a5e738ec6ad9e4151d9167aa8aa8a3eb236",
+      "relocatedSha256": "f41550ec8bbbc458048683a1b6701fa006a05be5a434a81676396e2d4048f980",
+      "renames": {}
+    },
+    {
+      "source": "plugins/ita_otp.py",
+      "sourceSha256": "7217a3893aef964c44200ce3096c7f1f4f4cb8da65cffe81e1dbd9ac2ef679f8",
+      "relocatedSha256": "60caf74a441f8491ebded96f145dec11f8f36f7942127854aaf9ac3e07747bff",
+      "renames": {
+        "_EMAIL_PATTERN": "_OTP_EMAIL_PATTERN"
+      }
+    },
+    {
+      "source": "plugins/ita_turnstile.py",
+      "sourceSha256": "34618d8bc98038206234bda0d4ad6781d37ad6166e6359cb686fa6a94b35aae2",
+      "relocatedSha256": "b023ee6165d9ae65cd5cc4289af0554a0731c26827c2925f8651c0a8dffb54ca",
+      "renames": {}
+    },
+    {
+      "source": "plugins/ita_workflow.py",
+      "sourceSha256": "33aabe5841e772537769f8c9509056f09692a40e0486b8a0d84616e4d98c8838",
+      "relocatedSha256": "e40c830896c1dadc767393bd7416c0d163565737a86b206eb1104bcbb7c91990",
+      "renames": {}
+    },
+    {
+      "source": "plugins/ita_plugin.py",
+      "sourceSha256": "dd95b06faa6328f0bb4ccdd198c22e2eea1ee57e72e2d8433d0e81ba7e4521e6",
+      "relocatedSha256": "d8e7bc1d4b3b98d0cf218c6af3cc2e6567140f66b6aaeb2791b9d6ab2b89cc11",
+      "renames": {}
+    }
+  ],
+  "targetSha256": "d2088578c17f0f898a5af307d933b6b55c8e048eecdb9e46b3789acdea98364e"
+}

+ 6 - 2
docs/ita_query_book_acceptance.md

@@ -1,5 +1,9 @@
 # Italy Query → Book:复用现有框架的验收
 
+当前代码位置:Italy 专属运行时已机械迁移到 `plugins/ita_plugin.py`。
+下文历史名称对应其中的同名分区;可执行示例已更新导入。
+参见 [单文件重构、热更新验证与宿主要求](ita_single_file_refactor.md)。
+
 更新日期:2026-08-31。合同:`existing-framework-offline-v2`。
 
 **本轮完成的是“真实框架代码 + 模拟外部依赖”的离线协同验收,不是真实网站、真实 Redis 或上线验收。**
@@ -228,8 +232,8 @@ python -B -c '
 import json
 from pathlib import Path
 import configure
-from plugins.ita_protocol import resolve_route_config
-from plugins.ita_otp import validate_cloud_otp_environment, validate_cloud_otp_logging
+from plugins.ita_plugin import resolve_route_config
+from plugins.ita_plugin import validate_cloud_otp_environment, validate_cloud_otp_logging
 from toolkit.vs_cloud_api import VSCloudApi
 from tools.plugin_tester import PluginTester
 from vs_types import GroupConfig, VSAccount, VSPlgConfig

+ 96 - 0
docs/ita_single_file_refactor.md

@@ -0,0 +1,96 @@
+# Italy 单文件发布重构
+
+## 结论与范围
+
+Italy 专属运行时代码现统一放在 `plugins/ita_plugin.py`,版本为 **1.0.1**。
+以后修改和上传这个文件即可,不需要先运行打包脚本,也不需要上传 Italy 辅助模块。
+
+本次是代码搬迁和接线调整,不是重新实现 Query、Book、OTP 或预约结果核验。
+未修改账号、领区配置、Sentinel、Booker、上传器、插件工厂,也未操作真实网站、邮箱或预约。
+
+## 为什么必须这样改
+
+现有 `utils/plugin_updater.py::download_and_install_plugin` 只写入一个 `.py` 文件;
+`vs_plg_factory.py::VSPlgFactory.create` 按文件加载插件;
+`main.py::reload_wrappers_for_plugin` 只移除该插件名称的模块缓存。
+原来的 Italy 多文件运行时既无法随单次上传完整交付,也可能在更新入口后继续使用旧辅助模块。
+
+这里沿用现有发布机制,没有扩展压缩包、依赖安装器或动态执行源码的机制。
+
+## 搬迁与可核对性
+
+源代码基线:`62c23889992ca7ee9395efad47c707dbd7cd2cee`。
+
+| 原文件(均在 plugins 下) | 现在的位置:ita_plugin.py 内部分区 |
+| --- | --- |
+| ita_protocol.py | PROTOCOL:配置、协议、日期和 OTP 解析 |
+| ita_calendar_query.py | CALENDAR_QUERY:逐月查询 |
+| ita_calendar_book.py | CALENDAR_BOOK:申请人会话中重新查号、选时段 |
+| ita_booking_final.py | BOOKING_FINAL:一次提交与结果状态 |
+| ita_reservation.py | RESERVATION:预约记录解析 |
+| ita_final_read_port.py | FINAL_READ_PORT:独立标签页读取回执 |
+| ita_calendar_session.py | CALENDAR_SESSION:表单准备、请求审计 |
+| ita_otp.py | OTP:复用既有云端邮件读取接口 |
+| ita_turnstile.py | TURNSTILE:既有准备流程 |
+| ita_workflow.py | WORKFLOW:串起 Query / Book |
+| ita_plugin.py | PLUGIN:框架公开接口 |
+
+`tools/consolidate_ita_plugin.py` 从固定 Git 基线读取原文,用 AST 定位后做文本搬迁,
+不通过重新生成函数体的方式改写业务。`docs/ita-single-file-migration.json` 记录每个源文件、
+搬迁分区以及最终文件的 SHA-256。
+
+必要的接线改动:
+
+1. 移除 Italy 内部导入和模块限定名,保留宿主已有共享依赖。
+2. 区分 `datetime.time` 与 `time` 模块,以及两处不同含义的 `_text`、OTP 私有邮箱正则。
+3. 统一 future import,去掉原分模块的 `__all__`,清理 Python 行尾空白;保留字符串内容,包括页面 JavaScript。
+4. 版本从 1.0.0 升到 1.0.1,供现有更新器识别。
+5. 保留 OTP 锁的进程共享语义:现有工厂每次创建实例都会重新执行插件文件,因此仅将这把
+   原生锁保存在已存在的 `vs_plg` 宿主模块上。那里不保存插件函数、类或旧业务代码,也不需要修改宿主文件。
+6. 测试和调试工具改为引用单文件。本地 Query+Book 验收拦截跟随**实际插件实例所属代码**,
+   不通过可能已被下一次工厂加载替换的模块缓存寻找实现。跨加载版本的配置按完整数据比较,
+   不取消账号、路由、请求次数或提交保护。
+
+原十个辅助运行时文件从当前树移除,完整内容仍可由上述 Git 提交恢复。
+测试、调试工具和历史证据文档可以继续分文件,它们不属于上传产物。
+
+## 验证及准出
+
+2026-08-31 本地验证结果:完整 Italy 回归 **838 项通过、0 跳过**(10.863 秒),
+其中包含单文件专项 8 项;既有 Query+Book CLI 离线验收 **75 项通过**(属于前述回归子集)。
+机械搬迁复现检查、`git diff --check` 均以 exit code 0 结束。
+
+`test/test_ita_single_file.py` 包含以下离线检查:
+
+- 对全部 11 个原分区做独立 AST 对比,只有上述白名单接线变化;函数控制流和字面量未重写。
+- 在临时目录只放一个插件文件,通过真实安装器和真实工厂加载;禁止插件导入任何 `plugins.*` / `tools.*`。
+- 公开 Query / Book 入口调用当前加载文件的实现。
+- 执行原样的宿主热重载函数,验证停止、加载、启动顺序,类、枚举和函数换新,进程共享 OTP 锁保持一致。
+- 多次动态加载后,本地提交保护仍绑定原申请人实例;只创建一次本地提交标记,不重试。
+- 不确定结果仍继承宿主的 `BookingOutcomeUnknownError`,不会丢失 Booker 的暂停语义。
+
+复现命令(不访问真实站点,不提交预约):
+
+```bash
+.venv/bin/python -B tools/consolidate_ita_plugin.py
+.venv/bin/python -B -m unittest -q test.test_ita_single_file
+.venv/bin/python -B tools/debug_ita_query_book.py --offline
+git diff --check
+```
+
+完整 Italy 回归覆盖 `test/test_ita*.py`、`test/test_debug_ita*.py`、
+`test/test_plugin_tester_ita_config.py`。
+
+注意:搬迁脚本是**本次初始迁移的审计工具,不是今后的构建步骤**。
+正常开发直接编辑 `ita_plugin.py`;未来业务变化后,初始迁移逐字比对理应报告差异,需由对应变更更新验收基线。
+审计测试需要上述源 Git 对象;插件运行、上传和热更新不需要 Git、脚本或清单文件。
+
+## 发布边界
+
+- 上传产物只有 `plugins/ita_plugin.py`,但不是脱离宿主的独立应用。继续复用框架类型、云端 API、
+  浏览器和鼠标/键盘等已有工具,与其他插件一致。
+- 宿主至少需要当前 Italy 集成基线中的共享接口,尤其 `vs_types.BookingOutcomeUnknownError`
+  及 Booker 对该异常的处理。单文件插件不会替老宿主升级这些公共接口。
+- 领区差异仍来自 `apt_configs` 等原有配置,没有新增香港硬编码或修改配置格式。
+- 本次没有执行远端上传、上线或真实预约;本地热更新通过不等同于线上预约成功。
+- 不在进行中的真实预约提交期间切换版本;沿用宿主的停止/清理后更新流程。

+ 0 - 457
plugins/ita_booking_final.py

@@ -1,457 +0,0 @@
-"""Italy final-stage building blocks shared by production and local validation.
-
-ReservationSnapshot is an internal read-port contract, NOT a discovered website
-schema. A real adapter must prove identity, status and pagination completeness
-before this module can be enabled. Attempts are process-local; the existing
-Booker task pause handles uncertain outcomes. No automatic retry is provided.
-The opt-in local evidence gate adds a checkout-local fence and human confirmation;
-it observes unknown receipts without claiming that production success is proven.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import threading
-import time
-from dataclasses import dataclass, field
-from datetime import date
-from enum import Enum
-from typing import Callable
-from urllib.parse import parse_qsl, urljoin
-
-from plugins.ita_calendar_book import SLOT_SELECTION_SCRIPT, verify_precommit_selection
-from plugins.ita_calendar_query import CALENDAR_PATH, listen_once, same_origin_path
-from plugins.ita_protocol import CalendarDay, MAX_PROTOCOL_PAYLOAD_CHARS, PrecommitApproval, SlotCandidate
-from vs_types import VSBookResult, BookingOutcomeUnknownError
-
-
-FINAL_PATH = "/BookingCalendar/InsertNewBooking"
-
-
-class FinalBookingError(RuntimeError):
-    """Fixed messages only: do not include page text, requests or credentials."""
-
-
-class FinalOutcomeUnknown(FinalBookingError, BookingOutcomeUnknownError):
-    def __init__(self):
-        super().__init__("Italy final outcome requires read-only reconciliation")
-
-
-class ReservationState(str, Enum):
-    ACTIVE = "active"
-    CANCELLED = "cancelled"
-    WAITLIST = "waitlist"
-    UNKNOWN = "unknown"
-
-
-class SubmissionSignal(str, Enum):
-    ACCEPTED = "accepted_hint"
-    REJECTED = "rejected_hint"
-    UNKNOWN = "unknown"
-
-
-def _text(value: object) -> bool:
-    return (isinstance(value, str) and 0 < len(value) <= 256 and value == value.strip()
-            and not any(ord(ch) < 32 or ord(ch) == 127 for ch in value))
-
-
-@dataclass(frozen=True, slots=True)
-class FinalTarget:
-    applicant: str = field(repr=False)
-    session_key: str = field(repr=False)
-    tab_id: str = field(repr=False)
-    routing_key: str
-    service_id: str = field(repr=False)
-    runtime_service: str = field(repr=False)
-    approval: PrecommitApproval = field(repr=False)
-    service_name: str | None = field(default=None, repr=False)
-
-    def __post_init__(self):
-        if not all(_text(getattr(self, key)) for key in (
-            "applicant", "session_key", "tab_id", "routing_key", "service_id", "runtime_service",
-        )):
-            raise FinalBookingError("Italy final target identity is invalid")
-        if not isinstance(self.approval, PrecommitApproval):
-            raise FinalBookingError("Italy final requires a Book precommit approval")
-        if self.service_name is not None and not _text(self.service_name):
-            raise FinalBookingError("Italy final displayed service is invalid")
-        day, slot = self.approval.calendar_day, self.approval.candidate
-        if (not isinstance(day, CalendarDay) or not isinstance(slot, SlotCandidate)
-                or day.day != slot.day or not day.is_available or not slot.is_available):
-            raise FinalBookingError("Italy final target inventory is inconsistent")
-
-
-@dataclass(frozen=True, slots=True, repr=False)
-class VerifiedSubmission:
-    """Native POST matched this exact session/tab/precommit; not a receipt field.
-
-    Created from an observed packet, even when its RESPONSE schema is unknown.
-    A caller must also enforce the one-request audit before passing it to a read port.
-    """
-
-    target: FinalTarget
-
-
-@dataclass(frozen=True, slots=True)
-class ReservationRecord:
-    """Normalized by a verified, identity-bound site reader.
-
-    time_label is an independently evidenced selected interval, not an interval
-    inferred from appointment_time. A real receipt may expose only the assigned
-    HH:mm time. That is enough to preserve cancelled history, not prove a new
-    record belongs to the selected slot. Cancelled history may have an unbound
-    service_id only with a fingerprint retaining all observed business facts.
-    This exception never establishes a target-service or selected-slot binding.
-    submission is a separate verified native-request witness, used by the bound
-    real read port for new active receipts. It never rewrites the receipt fields.
-    """
-
-    reference: str = field(repr=False)
-    service_id: str | None = field(repr=False)
-    day: date
-    time_label: str | None
-    state: ReservationState
-    appointment_time: str | None = None
-    receipt_fingerprint: str | None = field(default=None, repr=False)
-    submission: VerifiedSubmission | None = field(default=None, repr=False)
-
-
-def _valid_receipt_time(record: ReservationRecord) -> bool:
-    interval, assigned = record.time_label, record.appointment_time
-    if interval is None and assigned is None:
-        return False
-    if interval is not None and (
-        not isinstance(interval, str)
-        or re.fullmatch(r"(?:[01][0-9]|2[0-3]):[0-5][0-9] - (?:[01][0-9]|2[0-3]):[0-5][0-9]", interval) is None
-        or interval[:5] >= interval[-5:]
-    ):
-        return False
-    assigned_valid = assigned is None or (
-        isinstance(assigned, str)
-        and re.fullmatch(r"(?:[01][0-9]|2[0-3]):[0-5][0-9]", assigned) is not None
-    )
-    if not assigned_valid:
-        return False
-    # Negative consistency check only: containment never creates a binding.
-    return interval is None or assigned is None or interval[:5] <= assigned <= interval[-5:]
-
-
-@dataclass(frozen=True, slots=True)
-class ReservationSnapshot:
-    applicant: str = field(repr=False)
-    session_key: str = field(repr=False)
-    captured_at: float
-    complete: bool
-    records: tuple[ReservationRecord, ...] = field(repr=False)
-
-
-# Reuse the actual slot readback JS in the same synchronous browser turn as the
-# native final click, so a Python/browser round trip cannot select another slot.
-# Never reconstruct the POST payload: the website handler remains its owner.
-NATIVE_FINAL_SCRIPT = r"""
-/* coordinate:ita-native-final-once */
-const [serviceId, day, dailyId, timeLabel, capacity] = arguments;
-const state = (function () {
-""" + SLOT_SELECTION_SCRIPT + r"""
-}).apply(null, [serviceId, day, dailyId, timeLabel, capacity, false]);
-const positive = ['runtimeMatches', 'finalGuarded', 'firstSelectedMatches',
-  'dayPositive', 'candidateReady', 'activeIsCandidate', 'activeIdMatches',
-  'activeDayMatches', 'activeTimeMatches', 'activeCapacityMatches'];
-const negative = ['dayDisabled', 'dayNegative', 'activeUnavailable', 'activeRedDot', 'clicked'];
-const ready = positive.every(k => state[k] === true) && negative.every(k => state[k] === false) &&
-  ['matchingDateCount', 'candidateCount', 'activeCount', 'activeInputCount'].every(k => state[k] === 1) &&
-  JSON.stringify(state.timelineDays) === JSON.stringify([day]) &&
-  JSON.stringify(state.contentDays) === JSON.stringify([day]);
-const buttons = Array.from(document.querySelectorAll('#btnPrenotaNoOtp'));
-if (!ready || buttons.length !== 1 || !buttons[0].isConnected ||
-    buttons[0].dataset.coordinateFinalAttemptConsumed) return {clicked: false};
-const button = buttons[0];
-button.dataset.coordinateFinalAttemptConsumed = 'true';
-try {
-  button.disabled = false;
-  button.removeAttribute('aria-disabled');
-  button.click();
-  return {clicked: true};
-} finally {
-  button.disabled = true;
-  button.setAttribute('aria-disabled', 'true');
-  button.dataset.coordinateFinalGuard = 'enabled';
-}
-"""
-
-
-def _unique_object(pairs):
-    result = {}
-    for key, value in pairs:
-        if key in result:
-            raise ValueError("duplicate field")
-        result[key] = value
-    return result
-
-
-def inspect_final_packet(packet: object, target: FinalTarget) -> tuple[SubmissionSignal, VerifiedSubmission | None, str]:
-    """Validate the observed request before interpreting a response as a hint.
-
-    Invalid metadata/HTTP/schema is UNKNOWN after a write, not a retryable
-    authentication/no-slot error. Never expose the raw server errorMessage.
-    """
-    evidence = None
-    reason = "request_metadata"
-    try:
-        path, parsed = same_origin_path(packet.url)
-        if (path != FINAL_PATH or parsed.query or parsed.fragment or packet.method != "POST"
-                or packet.tab_id != target.tab_id or getattr(packet, "is_failed", False)):
-            return SubmissionSignal.UNKNOWN, None, reason
-        reason = "request_fields"
-        body = packet.request.postData
-        if isinstance(body, str) and len(body) <= MAX_PROTOCOL_PAYLOAD_CHARS:
-            body = _unique_object(parse_qsl(body, keep_blank_values=True, strict_parsing=True))
-        if not isinstance(body, dict) or set(body) != {
-            "idCalendarioGiornaliero", "selectedDay", "selectedHour",
-        } or any(not isinstance(value, str) for value in body.values()):
-            return SubmissionSignal.UNKNOWN, None, reason
-        reason = "request_selection"
-        slot = target.approval.candidate
-        if body["idCalendarioGiornaliero"] != slot.daily_calendar_id or body["selectedDay"] != slot.day.isoformat():
-            return SubmissionSignal.UNKNOWN, None, reason
-        compact = lambda value: re.sub(r"\s+", "", value)
-        if compact(body["selectedHour"]) != compact(f"{slot.time_label}({slot.slots_free})"):
-            return SubmissionSignal.UNKNOWN, None, reason
-        evidence = VerifiedSubmission(target)
-        reason = "response_metadata"
-        response = packet.response
-        if type(response.status) is not int or response.status != 200:
-            return SubmissionSignal.UNKNOWN, evidence, reason
-        response_url = getattr(response, "url", None)
-        if response_url:
-            response_path, response_parsed = same_origin_path(response_url)
-            if response_path != FINAL_PATH or response_parsed.query or response_parsed.fragment:
-                return SubmissionSignal.UNKNOWN, evidence, reason
-        reason = "response_body"
-        raw = response.raw_body
-        if not isinstance(raw, str) or not 0 < len(raw) <= MAX_PROTOCOL_PAYLOAD_CHARS:
-            return SubmissionSignal.UNKNOWN, evidence, reason
-        data = json.loads(raw, object_pairs_hook=_unique_object)
-        reason = "response_fields"
-        if not isinstance(data, dict) or not {"errorMessage", "url"} <= set(data):
-            return SubmissionSignal.UNKNOWN, evidence, reason
-        error, destination = data["errorMessage"], data["url"]
-        if not isinstance(error, str) or not _text(destination):
-            return SubmissionSignal.UNKNOWN, evidence, reason
-        reason = "response_destination"
-        same_origin_path(urljoin(packet.url, destination))
-        return (SubmissionSignal.REJECTED if error.strip() else SubmissionSignal.ACCEPTED), evidence, "recognized"
-    except Exception:
-        return SubmissionSignal.UNKNOWN, evidence, reason
-
-
-def classify_final_packet(packet: object, target: FinalTarget) -> SubmissionSignal:
-    return inspect_final_packet(packet, target)[0]
-
-
-class NativeFinalSubmitter:
-    """One native click with the existing listener; no navigation/retry/OTP.
-
-    A process-local latch is not a durable task fence. Production reaches this
-    adapter only with explicit final-submit configuration; default pre-final
-    CLIs never call it. The opt-in local evidence gate has its own persistent fence.
-    """
-
-    def __init__(self, page: object, target: FinalTarget, session_is_current: Callable[[], bool]):
-        self.page, self.target, self.session_is_current = page, target, session_is_current
-        self._lock = threading.Lock()
-        self._consumed = False
-        self.submitted_selection: VerifiedSubmission | None = None
-        self.diagnostic = {"requestMatched": False, "reason": "not_observed"}
-
-    def __call__(self) -> SubmissionSignal:
-        with self._lock:
-            if self._consumed:
-                raise FinalBookingError("Italy native final attempt is already consumed")
-            self._consumed = True
-        target = self.target
-
-        def require_context():
-            if (self.session_is_current() is not True or self.page.tab_id != target.tab_id
-                    or same_origin_path(self.page.url)[0] != CALENDAR_PATH):
-                raise FinalBookingError("Italy native final context changed")
-
-        def action():
-            require_context()
-            slot = target.approval.candidate
-            raw = self.page.run_js(
-                NATIVE_FINAL_SCRIPT, target.runtime_service, slot.day.isoformat(),
-                slot.daily_calendar_id, slot.time_label, slot.slots_free,
-            )
-            if raw != {"clicked": True} or type(raw.get("clicked")) is not bool:
-                raise FinalBookingError("Italy native final click was not acknowledged")
-
-        try:
-            require_context()
-            verify_precommit_selection(self.page, runtime_service=target.runtime_service, approval=target.approval)
-            packet = listen_once(self.page, target=FINAL_PATH, method="POST", action=action, timeout=30)
-            signal, self.submitted_selection, reason = inspect_final_packet(packet, target)
-            self.diagnostic = {"requestMatched": self.submitted_selection is not None, "reason": reason}
-            return signal
-        except Exception:
-            # A lost browser acknowledgement can follow a committed write.
-            self.diagnostic = {"requestMatched": False, "reason": "native_or_listener_error"}
-            return SubmissionSignal.UNKNOWN
-
-
-class FinalBookingAttempt:
-    """Single-use orchestration; reconciliation only after a possible write.
-
-    read_reservations must perform a fresh, complete, read-only site read bound
-    to this applicant/session. The real read port accepts only empty/cancelled
-    baselines, then binds new confirmed receipts to a verified native request. submit_native
-    is an injected NativeFinalSubmitter (or an offline test double), not an HTTP
-    replay function. Context checks must work after a same-session redirect.
-    """
-
-    def __init__(
-        self, target: FinalTarget, *, read_reservations: Callable[[], ReservationSnapshot],
-        submit_native: Callable[[], SubmissionSignal], session_is_current: Callable[[], bool],
-    ):
-        if not isinstance(target, FinalTarget) or not all(callable(item) for item in (
-            read_reservations, submit_native, session_is_current,
-        )):
-            raise FinalBookingError("Italy final adapters are required")
-        self.target = target
-        self._read_reservations = read_reservations
-        self._submit_native = submit_native
-        self._session_is_current = session_is_current
-        self._lock = threading.Lock()
-        self._state = "ready"
-        self._signal = SubmissionSignal.UNKNOWN
-        self._before: ReservationSnapshot | None = None
-
-    @property
-    def state(self) -> str:
-        return self._state
-
-    def _require_context(self):
-        if self._session_is_current() is not True:
-            raise FinalBookingError("Italy final applicant or Session changed")
-
-    def _read(self) -> ReservationSnapshot:
-        self._require_context()
-        started = time.monotonic()
-        snapshot = self._read_reservations()
-        self._require_context()
-        now = time.monotonic()
-        if (not isinstance(snapshot, ReservationSnapshot) or snapshot.complete is not True
-                or snapshot.applicant != self.target.applicant or snapshot.session_key != self.target.session_key
-                or type(snapshot.captured_at) not in (int, float) or not started <= snapshot.captured_at <= now
-                or not isinstance(snapshot.records, tuple) or len(snapshot.records) > 512):
-            raise FinalBookingError("Italy reservation snapshot is incomplete or not current")
-        seen = set()
-        for record in snapshot.records:
-            if (not isinstance(record, ReservationRecord) or not _text(record.reference)
-                    or record.reference in seen or type(record.day) is not date
-                    or not _valid_receipt_time(record)
-                    or not isinstance(record.state, ReservationState) or record.state is ReservationState.UNKNOWN):
-                raise FinalBookingError("Italy reservation records require verified identity and status")
-            fingerprint = record.receipt_fingerprint
-            if fingerprint is not None and (not isinstance(fingerprint, str) or
-                                            re.fullmatch(r"[0-9a-f]{64}", fingerprint) is None):
-                raise FinalBookingError("Italy receipt fingerprint is invalid")
-            if record.submission is not None and not self._submitted_binding(record):
-                raise FinalBookingError("Italy receipt submission evidence does not match this attempt")
-            if not _text(record.service_id) and not (
-                    record.service_id is None and fingerprint is not None and
-                    (record.state is ReservationState.CANCELLED or self._submitted_binding(record))):
-                raise FinalBookingError("Italy live reservation service binding is unverified")
-            seen.add(record.reference)
-        return snapshot
-
-    def _submitted_binding(self, record: ReservationRecord) -> bool:
-        slot = self.target.approval.candidate
-        return (self._state in {"submitted", "unknown"} and
-                isinstance(record.submission, VerifiedSubmission) and
-                record.submission.target == self.target and _text(self.target.service_name) and
-                record.state is ReservationState.ACTIVE and record.service_id is None and
-                record.time_label is None and record.receipt_fingerprint is not None and
-                record.day == slot.day and isinstance(record.appointment_time, str) and
-                slot.time_label[:5] <= record.appointment_time <= slot.time_label[-5:])
-
-    def _live(self, snapshot: ReservationSnapshot) -> list[ReservationRecord]:
-        return [record for record in snapshot.records if (record.service_id == self.target.service_id or
-                self._submitted_binding(record))
-                and record.state in {ReservationState.ACTIVE, ReservationState.WAITLIST}]
-
-    def execute(self, *, enabled: bool = False) -> VSBookResult:
-        if enabled is not True:
-            raise FinalBookingError("Italy final submission is disabled")
-        if not self._lock.acquire(blocking=False):
-            raise FinalBookingError("Italy final attempt is already running")
-        try:
-            if self._state != "ready":
-                raise FinalBookingError("Italy final attempt is already consumed")
-            self._state = "checking"
-            try:
-                self._before = self._read()
-                self._require_context()
-            except Exception:
-                self._state = "blocked"
-                raise FinalBookingError("Italy final preflight blocked; no submission attempted") from None
-            if self._live(self._before):
-                self._state = "blocked"
-                raise FinalBookingError("Italy service already has an active reservation or waitlist")
-            self._state = "submitted"
-            try:
-                signal = self._submit_native()
-                self._signal = signal if isinstance(signal, SubmissionSignal) else SubmissionSignal.UNKNOWN
-            except Exception:
-                self._signal = SubmissionSignal.UNKNOWN
-            return self._reconcile()
-        finally:
-            # Ctrl-C/SystemExit must not make a possibly dispatched write look
-            # unattempted, nor make read-only reconciliation impossible.
-            if self._state == "submitted":
-                self._state = "unknown"
-            elif self._state == "checking":
-                self._state = "blocked"
-            self._lock.release()
-
-    def reconcile(self) -> VSBookResult:
-        """One read-only check. Never enters the native submit path."""
-        if not self._lock.acquire(blocking=False):
-            raise FinalBookingError("Italy final attempt is already running")
-        try:
-            if self._state != "unknown":
-                raise FinalBookingError("Italy final attempt does not need reconciliation")
-            return self._reconcile()
-        finally:
-            self._lock.release()
-
-    def _reconcile(self) -> VSBookResult:
-        self._state = "unknown"
-        try:
-            after = self._read()
-            live = self._live(after)
-            before = {record.reference: record for record in self._before.records}
-            after_by_id = {record.reference: record for record in after.records}
-            # Missing/modified history and unrelated new rows make attribution
-            # ambiguous. Do not equate a count increment with this appointment.
-            if any(after_by_id.get(key) != value for key, value in before.items()):
-                raise FinalOutcomeUnknown()
-            new = [record for record in after.records if record.reference not in before]
-            slot = self.target.approval.candidate
-            if (len(new) == 1 and len(live) == 1 and new[0] == live[0]
-                    and live[0].state is ReservationState.ACTIVE and live[0].day == slot.day
-                    and (live[0].time_label == slot.time_label or self._submitted_binding(live[0]))
-                    and self._signal is not SubmissionSignal.REJECTED):
-                self._state = "confirmed"
-                return VSBookResult(
-                    success=True, account=self.target.applicant, urn=live[0].reference,
-                    book_date=slot.day.isoformat(), book_time=live[0].appointment_time or slot.time_label,
-                )
-            if not new and not live and self._signal is SubmissionSignal.REJECTED:
-                self._state = "rejected"
-                return VSBookResult(success=False, label="italy-final-rejected")
-        except Exception:
-            pass
-        self._state = "unknown"
-        raise FinalOutcomeUnknown() from None

+ 0 - 761
plugins/ita_calendar_book.py

@@ -1,761 +0,0 @@
-"""Book-side Calendar response binding and native slot selection.
-
-The caller owns login, route continuity, date preferences and fresh packet
-capture in the applicant's browser. This adapter neither fetches inventory nor
-accepts a Query snapshot. A returned approval is a pre-final checkpoint, never
-permission to submit or evidence of a completed booking.
-"""
-
-from __future__ import annotations
-
-import json
-import time
-from dataclasses import dataclass, field
-from datetime import date, datetime
-from typing import Callable, Mapping
-
-from plugins.ita_calendar_query import (
-    CALENDAR_PATH,
-    AVAILABILITY_PATH,
-    DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
-    CalendarGateError,
-    CalendarProbeResult,
-    click_next_month,
-    guard_calendar,
-    listen_once,
-    month_text,
-    next_month_value,
-    parse_availability_packet,
-    refresh_calendar,
-    require_plain_nonnegative_int,
-    same_origin_path,
-)
-from plugins.ita_protocol import (
-    CalendarDay,
-    DateSelectionState,
-    ItaProtocolError,
-    PrecommitApproval,
-    SlotCandidate,
-    SlotSelectionState,
-    approve_precommit,
-    available_calendar_days,
-    available_slot_candidates,
-    month_starts,
-    parse_time_slots,
-)
-
-
-TIME_SLOTS_PATH = "/BookingCalendar/RetrieveTimeSlots"
-
-RUNTIME_SERVICE_SCRIPT = r"""
-/* coordinate:ita-book-runtime-service */
-const controls = Array.from(document.querySelectorAll('#idServizio'));
-return {
-  path: window.location.pathname,
-  count: controls.length,
-  value: controls.length === 1 ? controls[0].value : null,
-};
-"""
-
-SLOT_SELECTION_SCRIPT = r"""
-/* coordinate:ita-book-slot-selection */
-const [serviceId, day, dailyId, timeLabel, capacity, shouldClick] = arguments;
-const normalize = (text) => String(text || '').replace(/\s+/g, ' ').trim();
-const service = Array.from(document.querySelectorAll('#idServizio'));
-const runtimeMatches = window.location.origin === 'https://prenotami.esteri.it' &&
-  window.location.pathname === '/BookingCalendar' &&
-  service.length === 1 && service[0].value === serviceId;
-const finalButtons = Array.from(document.querySelectorAll('#btnPrenotaNoOtp'));
-const finalGuarded = finalButtons.length === 1 && finalButtons[0].disabled &&
-  finalButtons[0].dataset.coordinateFinalGuard === 'enabled';
-const timeline = Array.from(document.querySelectorAll('.events a.selected'));
-const content = Array.from(document.querySelectorAll('.events-content li.selected'));
-const links = Array.from(document.querySelectorAll('.events a[data-date]'))
-  .filter((element) => element.dataset.date === day);
-const link = links.length === 1 ? links[0] : null;
-const datesMatch = timeline.length === 1 && content.length === 1 &&
-  timeline[0].dataset.date === day && content[0].dataset.date === day;
-const firstSelectedMatches = datesMatch && document.querySelector('.selected') === timeline[0];
-const disabled = (element) => !element || element.hasAttribute('disabled') ||
-  element.getAttribute('aria-disabled') === 'true' ||
-  element.classList.contains('disabled') ||
-  element.classList.contains('input-async-disabilitato');
-const dayNegative = !link || link.classList.contains('notAvailableDay');
-const dayPositive = Boolean(link && link.classList.contains('input-async-abilitato'));
-const inputs = (slot) => slot ? Array.from(slot.querySelectorAll('input')) : [];
-const idMatches = (slot) => {
-  const fields = inputs(slot);
-  return fields.length === 1 && fields[0].type === 'hidden' &&
-    fields[0].id === 'idHiddenFasciaServizio' && fields[0].value === dailyId;
-};
-const timeMatches = (slot) => {
-  const spans = slot ? slot.querySelectorAll('span') : [];
-  return spans.length === 2 && normalize(spans[0].textContent) === timeLabel;
-};
-const capacityMatches = (slot) => {
-  const spans = slot ? slot.querySelectorAll('span') : [];
-  return spans.length === 2 && normalize(spans[1].textContent) === `(${capacity})`;
-};
-const negative = (slot) => !slot || slot.classList.contains('notAvailableFascia');
-const redDot = (slot) => Boolean(slot && slot.querySelector('.dotRed'));
-const actionable = (element) => {
-  if (!element || !element.isConnected || disabled(element)) return false;
-  const style = window.getComputedStyle(element);
-  if (style.display === 'none' || style.visibility === 'hidden' ||
-      style.pointerEvents === 'none' || Number.parseFloat(style.opacity || '1') <= 0) return false;
-  const rect = element.getBoundingClientRect();
-  const left = Math.max(0, rect.left), right = Math.min(window.innerWidth, rect.right);
-  const top = Math.max(0, rect.top), bottom = Math.min(window.innerHeight, rect.bottom);
-  if (right <= left || bottom <= top) return false;
-  const hit = document.elementFromPoint((left + right) / 2, (top + bottom) / 2);
-  return Boolean(hit && (hit === element || element.contains(hit)));
-};
-const slots = content.length === 1 ? Array.from(content[0].querySelectorAll('.fascia')) : [];
-const matches = slots.filter(idMatches);
-const candidate = matches.length === 1 ? matches[0] : null;
-const candidateReady = Boolean(candidate && !negative(candidate) && !redDot(candidate) &&
-  timeMatches(candidate) && capacityMatches(candidate) && actionable(candidate));
-let active = Array.from(document.querySelectorAll('.fascia.act'));
-const alreadyActive = active.length === 1 && active[0] === candidate;
-let clicked = false;
-if (shouldClick === true && runtimeMatches && finalGuarded && datesMatch &&
-    firstSelectedMatches && links.length === 1 && !disabled(link) && !dayNegative &&
-    dayPositive && candidateReady && !alreadyActive) {
-  candidate.click();
-  clicked = true;
-}
-active = Array.from(document.querySelectorAll('.fascia.act'));
-const selected = active.length === 1 ? active[0] : null;
-return {
-  runtimeMatches, finalGuarded, firstSelectedMatches,
-  timelineDays: timeline.map((element) => element.dataset.date || ''),
-  contentDays: content.map((element) => element.dataset.date || ''),
-  matchingDateCount: links.length,
-  dayDisabled: disabled(link), dayNegative, dayPositive,
-  candidateCount: matches.length, candidateReady, clicked,
-  activeCount: active.length,
-  activeIsCandidate: Boolean(selected && selected === candidate),
-  activeUnavailable: negative(selected), activeRedDot: redDot(selected),
-  activeInputCount: inputs(selected).length,
-  activeIdMatches: idMatches(selected),
-  activeDayMatches: Boolean(selected && datesMatch && content[0].contains(selected)),
-  activeTimeMatches: timeMatches(selected),
-  activeCapacityMatches: capacityMatches(selected),
-};
-"""
-
-
-class CalendarBookError(CalendarGateError):
-    """A safe stage error; never includes response bodies or runtime IDs."""
-
-    def __init__(self, message: str, *, http_status: int | None = None):
-        super().__init__(message)
-        self.http_status = http_status
-
-
-class CalendarServiceNotReadyError(CalendarBookError):
-    """The service control stayed empty during a known initialization boundary."""
-
-
-_BOOL_FIELDS = {
-    "runtimeMatches", "finalGuarded", "firstSelectedMatches", "dayDisabled",
-    "dayNegative", "dayPositive", "candidateReady", "clicked",
-    "activeIsCandidate", "activeUnavailable", "activeRedDot", "activeIdMatches",
-    "activeDayMatches", "activeTimeMatches", "activeCapacityMatches",
-}
-_COUNT_FIELDS = {"matchingDateCount", "candidateCount", "activeCount", "activeInputCount"}
-_DATE_FIELDS = {"timelineDays", "contentDays"}
-
-
-def _runtime_id(value: object) -> str:
-    if type(value) is int and value > 0:
-        return str(value)
-    if isinstance(value, str) and value and value == value.strip() and len(value) <= 128:
-        return value
-    raise CalendarBookError("Book runtime service identifier was invalid")
-
-
-def _read_calendar_service_value(page: object) -> str:
-    path, _ = same_origin_path(page.url)
-    if path != CALENDAR_PATH:
-        raise CalendarBookError("Book selection requires the current Calendar page")
-    raw = page.run_js(RUNTIME_SERVICE_SCRIPT)
-    if not isinstance(raw, dict) or set(raw) != {"path", "count", "value"}:
-        raise CalendarBookError("Book Calendar runtime context changed")
-    if raw["path"] != CALENDAR_PATH or type(raw["count"]) is not int or raw["count"] != 1:
-        raise CalendarBookError("Book Calendar requires one runtime service control")
-    if not isinstance(raw["value"], str):
-        raise CalendarBookError("Book Calendar runtime service control has no value")
-    return raw["value"]
-
-
-def read_calendar_service(page: object) -> str:
-    """Strict read for stable phases; empty values are never a valid identity."""
-    return _runtime_id(_read_calendar_service_value(page))
-
-
-def wait_for_calendar_service(
-    page: object, *, session_is_current: Callable[[], bool],
-    expected_service: str | None = None, timeout: float = 5,
-) -> str:
-    """Await the site's field assignment without requesting or retrying anything.
-
-    Call only after AVANTI or native Calendar loading. Stable-phase checks stay
-    strict: only an exactly empty string is pending, not malformed identities,
-    missing/duplicate controls, another service, or a changed applicant/tab.
-    The deadline bounds polling; browser transport failures propagate normally.
-    """
-    if type(timeout) not in (int, float) or not 0 <= timeout < float("inf"):
-        raise CalendarBookError("Book Calendar readiness timeout must be finite and nonnegative")
-    if not callable(session_is_current):
-        raise CalendarBookError("Book Calendar readiness requires a Session check")
-    if expected_service is not None:
-        expected_service = _runtime_id(expected_service)
-    tab_id = getattr(page, "tab_id", None)
-    if not isinstance(tab_id, str) or not tab_id:
-        raise CalendarBookError("Book Calendar tab identity was unavailable")
-    deadline = time.monotonic() + timeout
-
-    def require_session() -> None:
-        if session_is_current() is not True or getattr(page, "tab_id", None) != tab_id:
-            raise CalendarBookError("Book applicant, route or browser Session changed")
-        if same_origin_path(page.url)[0] != CALENDAR_PATH:
-            raise CalendarBookError("Book readiness left the current Calendar page")
-
-    while True:
-        require_session()
-        guard_calendar(page)
-        value = _read_calendar_service_value(page)
-        require_session()
-        if value != "":
-            service = _runtime_id(value)
-            if expected_service is not None and service != expected_service:
-                raise CalendarBookError("Book Calendar runtime service changed")
-            return service
-        remaining = deadline - time.monotonic()
-        if remaining <= 0:
-            raise CalendarServiceNotReadyError("Book Calendar service did not initialize before timeout")
-        time.sleep(min(0.1, remaining))
-
-
-def _request_day(value: object) -> date:
-    if isinstance(value, str):
-        for date_format in ("%Y-%m-%d", "%d/%m/%Y"):
-            try:
-                return datetime.strptime(value, date_format).date()
-            except ValueError:
-                pass
-    raise CalendarBookError("Book TimeSlots request date format changed")
-
-
-def parse_book_time_slots(
-    packet: object, *, target_day: date, runtime_service_id: str,
-) -> tuple[SlotCandidate, ...]:
-    """Bind TimeSlots metadata to the selected day and current DOM service."""
-    try:
-        path, _ = same_origin_path(packet.url)
-        if str(packet.method).upper() != "POST" or path != TIME_SLOTS_PATH:
-            raise CalendarBookError("Book TimeSlots request method or path changed")
-        if type(packet.response.status) is not int or packet.response.status != 200:
-            raise CalendarBookError(
-                "Book TimeSlots response status was not 200",
-                http_status=packet.response.status if type(packet.response.status) is int else None,
-            )
-        body = packet.request.postData
-        if isinstance(body, str):
-            body = json.loads(body)
-        if not isinstance(body, dict) or set(body) != {"selectedDay", "idService"}:
-            raise CalendarBookError("Book TimeSlots request fields changed")
-        if _runtime_id(body["idService"]) != runtime_service_id:
-            raise CalendarBookError("Book TimeSlots request does not match the current service")
-        if _request_day(body["selectedDay"]) != target_day:
-            raise CalendarBookError("Book TimeSlots request does not match the target day")
-        candidates = parse_time_slots(packet.response.raw_body)
-        if any(item.day != target_day for item in candidates):
-            raise CalendarBookError("Book TimeSlots response contains another day")
-        return candidates
-    except CalendarBookError:
-        raise
-    except ItaProtocolError as exc:
-        raise CalendarBookError(f"Book TimeSlots protocol rejected ({exc.code})") from None
-    except Exception:
-        raise CalendarBookError("Book TimeSlots packet could not be validated") from None
-
-
-def _snapshot(page: object, service: str, target: date, candidate: SlotCandidate, *, click: bool) -> dict:
-    raw = page.run_js(
-        SLOT_SELECTION_SCRIPT, service, target.isoformat(), candidate.daily_calendar_id,
-        candidate.time_label, candidate.slots_free, click,
-    )
-    if not isinstance(raw, dict) or set(raw) != _BOOL_FIELDS | _COUNT_FIELDS | _DATE_FIELDS:
-        raise CalendarBookError("Book slot snapshot fields changed")
-    if any(type(raw[key]) is not bool for key in _BOOL_FIELDS):
-        raise CalendarBookError("Book slot snapshot boolean types changed")
-    for key in _COUNT_FIELDS:
-        require_plain_nonnegative_int(raw[key], key)
-    for key in _DATE_FIELDS:
-        if not isinstance(raw[key], list) or any(not isinstance(item, str) for item in raw[key]):
-            raise CalendarBookError("Book selected-date snapshot types changed")
-    return raw
-
-
-def _require_ready(raw: dict, target_day: date) -> None:
-    positive = ("runtimeMatches", "finalGuarded", "firstSelectedMatches", "dayPositive", "candidateReady")
-    if any(raw[key] is not True for key in positive):
-        raise CalendarBookError("Book candidate is not safely selectable")
-    if raw["dayDisabled"] or raw["dayNegative"]:
-        raise CalendarBookError("Book selected day is marked unavailable")
-    if raw["matchingDateCount"] != 1 or raw["candidateCount"] != 1:
-        raise CalendarBookError("Book date or slot is not unique")
-    expected = [target_day.isoformat()]
-    if raw["timelineDays"] != expected or raw["contentDays"] != expected:
-        raise CalendarBookError("Book timeline and content dates do not match the target")
-
-
-def _approve_selection_snapshot(
-    calendar_day: CalendarDay, candidate: SlotCandidate, raw: dict,
-) -> PrecommitApproval:
-    _require_ready(raw, candidate.day)
-    if raw["clicked"]:
-        raise CalendarBookError("Book readback unexpectedly clicked")
-    return approve_precommit(
-        calendar_day, candidate,
-        DateSelectionState(
-            planned_day=candidate.day, matching_availability_count=1,
-            timeline_selected_days=tuple(date.fromisoformat(item) for item in raw["timelineDays"]),
-            content_selected_days=tuple(date.fromisoformat(item) for item in raw["contentDays"]),
-            day_disabled=raw["dayDisabled"], day_not_available=raw["dayNegative"],
-            day_has_positive_state=raw["dayPositive"],
-        ),
-        SlotSelectionState(
-            active_slot_count=raw["activeCount"], active_is_candidate=raw["activeIsCandidate"],
-            active_has_unavailable_class=raw["activeUnavailable"], active_has_red_dot=raw["activeRedDot"],
-            active_hidden_input_count=raw["activeInputCount"],
-            active_daily_id_matches_candidate=raw["activeIdMatches"],
-            active_day_matches_candidate=raw["activeDayMatches"],
-            active_time_matches_candidate=raw["activeTimeMatches"],
-            active_capacity_matches_candidate=raw["activeCapacityMatches"],
-        ),
-    )
-
-
-def verify_precommit_selection(
-    page: object, *, runtime_service: str, approval: PrecommitApproval,
-) -> PrecommitApproval:
-    """Read the current selected slot; never select, refresh, or submit anything.
-
-    The caller still owns applicant/session binding and freshness of the Book
-    inventory. This is a consistency check, not a reservation or inventory lock.
-    """
-    if not isinstance(approval, PrecommitApproval):
-        raise CalendarBookError("Book selection requires a precommit approval")
-    try:
-        if read_calendar_service(page) != runtime_service:
-            raise CalendarBookError("Book Calendar runtime service changed")
-        raw = _snapshot(page, runtime_service, approval.candidate.day, approval.candidate, click=False)
-        return _approve_selection_snapshot(approval.calendar_day, approval.candidate, raw)
-    except CalendarBookError:
-        raise
-    except Exception:
-        raise CalendarBookError("Book precommit readback failed") from None
-
-
-def select_slot_before_final(
-    page: object, *, target_day: date, availability_packet: object, time_slots_packet: object,
-) -> PrecommitApproval | None:
-    """Select one positive slot from caller-captured Book packets; never submit.
-
-    Both packets must be fresh captures from this page. Their content alone
-    cannot prove capture time, applicant identity or route continuity. The
-    orchestrator must establish these preconditions before calling this method.
-    """
-    if type(target_day) is not date:
-        raise CalendarBookError("Book target day must be a date")
-    try:
-        service = read_calendar_service(page)
-        guard_calendar(page)
-        try:
-            probe = parse_availability_packet(availability_packet)
-            if probe.selected_month != (target_day.year, target_day.month):
-                raise CalendarBookError("Book Availability belongs to another month")
-            slots = parse_book_time_slots(
-                time_slots_packet, target_day=target_day, runtime_service_id=service,
-            )
-            days = [item for item in probe.days if item.day == target_day]
-            candidates = available_slot_candidates(slots, start_day=target_day, end_day=target_day)
-            if not days or not days[0].is_available:
-                if candidates:
-                    raise CalendarBookError("Book Availability and TimeSlots disagree")
-                return None
-            if not candidates:
-                return None
-            candidate = candidates[0]
-            before = _snapshot(page, service, target_day, candidate, click=False)
-            _require_ready(before, target_day)
-            if before["clicked"]:
-                raise CalendarBookError("Book read-only snapshot unexpectedly clicked")
-            if not (before["activeCount"] == 1 and before["activeIsCandidate"]):
-                acted = _snapshot(page, service, target_day, candidate, click=True)
-                _require_ready(acted, target_day)
-                if not acted["clicked"]:
-                    raise CalendarBookError("Book slot click was not acknowledged")
-            after = _snapshot(page, service, target_day, candidate, click=False)
-            return _approve_selection_snapshot(days[0], candidate, after)
-        finally:
-            guard_calendar(page)
-    except CalendarBookError:
-        raise
-    except ItaProtocolError as exc:
-        raise CalendarBookError(f"Book precommit rejected ({exc.code})") from None
-    except Exception:
-        raise CalendarBookError("Book Calendar selection or final guard failed") from None
-
-
-DATE_SELECTION_SCRIPT = r"""
-/* coordinate:ita-book-date-selection */
-const [serviceId, day, shouldClick] = arguments;
-const services = Array.from(document.querySelectorAll('#idServizio'));
-const runtimeMatches = window.location.origin === 'https://prenotami.esteri.it' &&
-  window.location.pathname === '/BookingCalendar' && services.length === 1 &&
-  services[0].value === serviceId;
-const buttons = Array.from(document.querySelectorAll('#btnPrenotaNoOtp'));
-const finalGuarded = buttons.length === 1 && buttons[0].disabled === true &&
-  buttons[0].dataset.coordinateFinalGuard === 'enabled';
-const candidates = Array.from(document.querySelectorAll('.events a[data-date]'))
-  .filter((link) => link.dataset.date === day);
-const link = candidates.length === 1 ? candidates[0] : null;
-const enabled = (element) => {
-  if (!element || !element.isConnected || element.hasAttribute('disabled') ||
-      element.getAttribute('aria-disabled') === 'true' ||
-      element.classList.contains('disabled') || element.classList.contains('notAvailableDay') ||
-      element.classList.contains('input-async-disabilitato') ||
-      !element.classList.contains('input-async-abilitato')) return false;
-  const style = window.getComputedStyle(element);
-  // Calendar timeline links can have zero layout size while logically enabled.
-  // The site's initialization uses HTMLElement.click(), as we do here, rather
-  // than a pointer hit. Keep disabled/style checks and response/date readback;
-  // do not require a clickable rectangle for this native date action.
-  return style.display !== 'none' && style.visibility !== 'hidden' &&
-    style.pointerEvents !== 'none' && Number.parseFloat(style.opacity || '1') > 0;
-};
-const timeline = Array.from(document.querySelectorAll('.events a.selected'));
-const content = Array.from(document.querySelectorAll('.events-content li.selected'));
-const selectedMatches = timeline.length === 1 && content.length === 1 &&
-  timeline[0].dataset.date === day && content[0].dataset.date === day &&
-  document.querySelector('.selected') === timeline[0];
-const candidateEnabled = enabled(link);
-let clicked = false;
-if (shouldClick === true && runtimeMatches && finalGuarded && candidateEnabled && !selectedMatches) {
-  link.click();
-  clicked = true;
-}
-return {runtimeMatches, finalGuarded, candidateCount: candidates.length,
-        candidateEnabled, selectedMatches, clicked};
-"""
-
-
-@dataclass(frozen=True, slots=True)
-class _CapturedMonth:
-    probe: CalendarProbeResult
-    availability_packet: object = field(repr=False)
-    availability_service: str = field(repr=False)
-    automatic_day: date | None = None
-    automatic_slots_packet: object | None = field(default=None, repr=False)
-
-
-def book_date_preferences(user_inputs: Mapping[str, object]) -> tuple[date, date]:
-    """Use the VFS preference keys and inclusive bounds without mutating inputs."""
-    if not isinstance(user_inputs, Mapping):
-        raise CalendarBookError("Book user inputs must be a mapping")
-    dates = []
-    for key, default in (("expected_start_date", "2000-01-01"),
-                         ("expected_end_date", "2100-01-01")):
-        value = user_inputs.get(key, default)
-        try:
-            parsed = date.fromisoformat(value) if isinstance(value, str) else None
-        except ValueError:
-            parsed = None
-        if parsed is None or parsed.isoformat() != value:
-            raise CalendarBookError(f"Book {key} must use YYYY-MM-DD")
-        dates.append(parsed)
-    if dates[0] > dates[1]:
-        raise CalendarBookError("Book date preference start exceeds end")
-    return dates[0], dates[1]
-
-
-def _require_context(page: object, service: str, session_is_current: Callable[[], bool]) -> None:
-    if session_is_current() is not True:
-        raise CalendarBookError("Book applicant, route or browser Session changed")
-    if read_calendar_service(page) != service:
-        raise CalendarBookError("Book Calendar runtime service changed")
-    guard_calendar(page)
-
-
-def _require_packet_tab(page: object, packet: object) -> None:
-    tab = getattr(page, "tab_id", None)
-    if not isinstance(tab, str) or not tab or getattr(packet, "tab_id", None) != tab:
-        raise CalendarBookError("Book response did not belong to the current browser tab")
-    if getattr(packet, "is_failed", False) is not False:
-        raise CalendarBookError("Book browser request failed")
-
-
-def _post_body(packet: object) -> dict:
-    body = packet.request.postData
-    if isinstance(body, str):
-        body = json.loads(body)
-    if not isinstance(body, dict):
-        raise CalendarBookError("Book request body was not an object")
-    return body
-
-
-def _date_snapshot(page: object, service: str, day: date, *, click: bool = False) -> dict:
-    raw = page.run_js(DATE_SELECTION_SCRIPT, service, day.isoformat(), click)
-    boolean_keys = {"runtimeMatches", "finalGuarded", "candidateEnabled", "selectedMatches", "clicked"}
-    if not isinstance(raw, dict) or set(raw) != boolean_keys | {"candidateCount"}:
-        raise CalendarBookError("Book date control structure changed")
-    if any(type(raw[key]) is not bool for key in boolean_keys):
-        raise CalendarBookError("Book date control types changed")
-    require_plain_nonnegative_int(raw["candidateCount"], "candidateCount")
-    if not raw["runtimeMatches"] or not raw["finalGuarded"] or raw["candidateCount"] > 1:
-        raise CalendarBookError("Book date control context was not unique and guarded")
-    if not click and raw["clicked"]:
-        raise CalendarBookError("Book date readback unexpectedly clicked")
-    return raw
-
-
-def _wait_selected_day(page: object, service: str, day: date, *, timeout: float) -> None:
-    deadline = time.monotonic() + timeout
-    while True:
-        raw = _date_snapshot(page, service, day)
-        if raw["candidateCount"] == 1 and raw["selectedMatches"]:
-            return
-        if time.monotonic() >= deadline:
-            raise CalendarBookError("Book selected date did not match the response before timeout")
-        time.sleep(0.1)
-
-
-def _click_date(page: object, service: str, day: date, *, timeout: float) -> None:
-    deadline = time.monotonic() + timeout
-    while True:
-        raw = _date_snapshot(page, service, day)
-        if raw["selectedMatches"]:
-            raise CalendarBookError("Book date is already selected without a fresh captured response")
-        if raw["candidateCount"] == 1 and raw["candidateEnabled"]:
-            break
-        if time.monotonic() >= deadline:
-            raise CalendarBookError("Book date control was not ready before timeout")
-        time.sleep(0.1)
-    acted = _date_snapshot(page, service, day, click=True)
-    if not acted["clicked"]:
-        raise CalendarBookError("Book date click was not acknowledged")
-
-
-def _capture_month(
-    page: object, *, action: Callable[[], None], service: str,
-    session_is_current: Callable[[], bool], timeout: float, dom_timeout: float,
-    previous: _CapturedMonth | None = None,
-) -> _CapturedMonth:
-    """Capture Availability plus the site's automatic first-day TimeSlots."""
-    _require_context(page, service, session_is_current)
-    page.listen.start([AVAILABILITY_PATH, TIME_SLOTS_PATH], method="POST")
-    try:
-        action()
-        wait_for_calendar_service(
-            page, session_is_current=session_is_current,
-            expected_service=service, timeout=min(dom_timeout, timeout),
-        )
-        _require_context(page, service, session_is_current)
-        deadline = time.monotonic() + timeout
-        captured = {}
-        probe = None
-        # Only two matching responses belong to one normal month-load action.
-        for _ in range(2):
-            remaining = deadline - time.monotonic()
-            if remaining <= 0:
-                raise CalendarBookError("Book month responses exceeded the time budget")
-            packet = page.listen.wait(timeout=remaining, raise_err=False)
-            if not packet:
-                raise CalendarBookError("Book month response was not observed before timeout")
-            _require_packet_tab(page, packet)
-            status = packet.response.status
-            if type(status) is not int or status != 200:
-                raise CalendarBookError("Book Calendar response status was not 200",
-                                        http_status=status if type(status) is int else None)
-            path, _ = same_origin_path(packet.url)
-            if path not in {AVAILABILITY_PATH, TIME_SLOTS_PATH} or path in captured:
-                raise CalendarBookError("Book month produced an unexpected or duplicate response")
-            captured[path] = packet
-            if path == AVAILABILITY_PATH:
-                probe = parse_availability_packet(packet)
-                if previous and probe.selected_month != next_month_value(previous.probe.selected_month):
-                    raise CalendarBookError("Book Calendar did not advance exactly one month")
-                if not probe.days or TIME_SLOTS_PATH in captured:
-                    break
-            elif probe is not None:
-                break
-        if probe is None:
-            raise CalendarBookError("Book month did not return Availability")
-        availability_packet = captured[AVAILABILITY_PATH]
-        availability_service = _runtime_id(_post_body(availability_packet).get("_Servizio"))
-        if previous and availability_service != previous.availability_service:
-            raise CalendarBookError("Book Availability runtime service changed")
-        automatic = captured.get(TIME_SLOTS_PATH)
-        automatic_day = None
-        if probe.days:
-            if automatic is None:
-                raise CalendarBookError("Book automatic day response was not captured")
-            automatic_day = _request_day(_post_body(automatic).get("selectedDay"))
-            if automatic_day not in {item.day for item in probe.days}:
-                raise CalendarBookError("Book automatic day escaped current Availability")
-            auto_slots = parse_book_time_slots(automatic, target_day=automatic_day, runtime_service_id=service)
-            auto_inventory = next(item for item in probe.days if item.day == automatic_day)
-            if not auto_inventory.is_available and available_slot_candidates(auto_slots):
-                raise CalendarBookError("Book automatic Availability and TimeSlots disagree")
-            _wait_selected_day(page, service, automatic_day, timeout=dom_timeout)
-        elif automatic is not None:
-            raise CalendarBookError("Book empty Availability unexpectedly returned TimeSlots")
-        _require_context(page, service, session_is_current)
-        return _CapturedMonth(probe, availability_packet, availability_service, automatic_day, automatic)
-    finally:
-        page.listen.stop()
-
-
-def _try_day(
-    page: object, month: _CapturedMonth, day: date, *, service: str,
-    session_is_current: Callable[[], bool], timeout: float, dom_timeout: float,
-) -> PrecommitApproval | None:
-    _require_context(page, service, session_is_current)
-    current_date = _date_snapshot(page, service, day)
-    if day == month.automatic_day and current_date["selectedMatches"]:
-        times_packet = month.automatic_slots_packet
-        _wait_selected_day(page, service, day, timeout=dom_timeout)
-    else:
-        times_packet = listen_once(
-            page, target=TIME_SLOTS_PATH, method="POST",
-            action=lambda: _click_date(page, service, day, timeout=dom_timeout),
-            timeout=timeout,
-        )
-        _require_packet_tab(page, times_packet)
-        parse_book_time_slots(times_packet, target_day=day, runtime_service_id=service)
-        _wait_selected_day(page, service, day, timeout=dom_timeout)
-    slots = parse_book_time_slots(times_packet, target_day=day, runtime_service_id=service)
-    candidates = available_slot_candidates(slots, start_day=day, end_day=day)
-    if not candidates:
-        # Inventory competition is not a protocol error. No slot was clicked.
-        _require_context(page, service, session_is_current)
-        return None
-    deadline = time.monotonic() + dom_timeout
-    while True:
-        _require_context(page, service, session_is_current)
-        raw = _snapshot(page, service, day, candidates[0], click=False)
-        if not raw["runtimeMatches"] or not raw["finalGuarded"] or raw["candidateCount"] > 1:
-            raise CalendarBookError("Book slot DOM changed its context or uniqueness")
-        if raw["candidateReady"]:
-            _require_ready(raw, day)
-            break
-        if time.monotonic() >= deadline:
-            raise CalendarBookError("Book slot DOM did not match the response before timeout")
-        time.sleep(0.1)
-    approval = select_slot_before_final(
-        page, target_day=day, availability_packet=month.availability_packet,
-        time_slots_packet=times_packet,
-    )
-    _require_context(page, service, session_is_current)
-    return approval
-
-
-def recheck_calendar_before_final(
-    page: object, *, lookahead_months: int, start_day: date, end_day: date,
-    session_is_current: Callable[[], bool], preferred_day: date | None = None,
-    month_click_interval_seconds: float = DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
-    timeout: float = 30, dom_timeout: float = 5,
-    log: Callable[[str], None] | None = None,
-) -> PrecommitApproval | None:
-    """Fresh Book-only scan with an optional date hint; never submit a booking.
-
-    There are at most two bounded passes: the hinted day, then an ascending
-    fallback. The caller must attest the prepared applicant/route Session via
-    session_is_current. No external snapshot or cached response is accepted.
-    """
-    try:
-        # Use existing pure validators before starting any browser action.
-        month_starts(date(2000, 1, 1), lookahead_months)
-        if type(start_day) is not date or type(end_day) is not date:
-            raise CalendarBookError("Book date bounds must be dates")
-        available_calendar_days((), start_day=start_day, end_day=end_day)
-        if preferred_day is not None and type(preferred_day) is not date:
-            raise CalendarBookError("Book preferred day must be a date")
-        for value in (timeout, dom_timeout, month_click_interval_seconds):
-            if type(value) not in (int, float) or not 0 <= value < float("inf"):
-                raise CalendarBookError("Book time budget must be finite and nonnegative")
-        if timeout == 0 or not callable(session_is_current):
-            raise CalendarBookError("Book requires a positive timeout and a Session check")
-        service = read_calendar_service(page)
-        _require_context(page, service, session_is_current)
-        common = dict(service=service, session_is_current=session_is_current,
-                      timeout=timeout, dom_timeout=dom_timeout)
-
-        def initial() -> _CapturedMonth:
-            return _capture_month(page, action=lambda: refresh_calendar(page), **common)
-
-        def advance(previous: _CapturedMonth) -> _CapturedMonth:
-            if month_click_interval_seconds:
-                time.sleep(month_click_interval_seconds)
-            return _capture_month(page, action=lambda: click_next_month(page), previous=previous, **common)
-
-        def positive_days(month: _CapturedMonth) -> tuple:
-            return available_calendar_days(month.probe.days, start_day=start_day, end_day=end_day)
-
-        first = initial()
-        anchor = first.probe.selected_month
-        current = first
-        attempted = set()
-        if preferred_day is not None and start_day <= preferred_day <= end_day:
-            offset = (preferred_day.year - anchor[0]) * 12 + preferred_day.month - anchor[1]
-            if 0 <= offset < lookahead_months:
-                for _ in range(offset):
-                    current = advance(current)
-                if preferred_day in {item.day for item in positive_days(current)}:
-                    attempted.add(preferred_day)
-                    approval = _try_day(page, current, preferred_day, **common)
-                    if approval is not None:
-                        return approval
-                # A failed hint cannot cause a stale earlier month's response
-                # to be reused. Restart the native scan once and recapture.
-                first = initial()
-                if (first.probe.selected_month != anchor or
-                        first.availability_service != current.availability_service):
-                    raise CalendarBookError("Book fallback restart changed the Calendar anchor")
-
-        current = first
-        for index in range(lookahead_months):
-            if current.probe.selected_month > (end_day.year, end_day.month):
-                return None
-            days = positive_days(current)
-            if log:
-                log(f"Italy Book Calendar month={month_text(current.probe.selected_month)} candidates={len(days)}")
-            for item in days:
-                if item.day in attempted:
-                    continue
-                attempted.add(item.day)
-                approval = _try_day(page, current, item.day, **common)
-                if approval is not None:
-                    return approval
-            if current.probe.selected_month >= (end_day.year, end_day.month):
-                return None
-            if index + 1 < lookahead_months:
-                current = advance(current)
-        return None
-    except CalendarBookError:
-        raise
-    except ItaProtocolError as exc:
-        raise CalendarBookError(f"Book Calendar protocol rejected ({exc.code})") from None
-    except Exception:
-        raise CalendarBookError("Book Calendar recheck failed; no further action was attempted") from None
-    finally:
-        # Do not leave the final button enabled after a native refresh or error.
-        try:
-            if same_origin_path(page.url)[0] == CALENDAR_PATH:
-                guard_calendar(page)
-        except Exception:
-            raise CalendarBookError("Book final-button guard could not be verified") from None

+ 0 - 607
plugins/ita_calendar_query.py

@@ -1,607 +0,0 @@
-"""Shared browser adapter for read-only Prenot@Mi Calendar queries.
-
-The pure wire-format rules live in :mod:`plugins.ita_protocol`.  This module
-owns only the browser-facing mechanics that production Query and the Q-CAL
-diagnostic tool must share: one-shot listeners, strict packet metadata,
-native month navigation, the final-button guard, and bounded scanning.
-"""
-
-from __future__ import annotations
-
-import json
-import time
-from dataclasses import dataclass
-from datetime import date, datetime
-from typing import Any, Callable
-from urllib.parse import urljoin, urlparse
-
-from plugins.ita_protocol import (
-    CalendarDay,
-    ItaProtocolError,
-    available_calendar_days,
-    parse_calendar_availability,
-)
-
-
-CALENDAR_PATH = "/BookingCalendar"
-AVAILABILITY_PATH = "/BookingCalendar/RetrieveCalendarAvailability"
-MAX_QUERY_LOOKAHEAD_MONTHS = 120
-DEFAULT_MONTH_CLICK_INTERVAL_SECONDS = 1.5
-
-
-CALENDAR_GUARD_SCRIPT = r"""
-/* coordinate:ita-calendar-query-final-guard */
-const finalButtons = Array.from(
-  document.querySelectorAll('#btnPrenotaNoOtp')
-);
-finalButtons.forEach((button) => {
-  button.disabled = true;
-  button.setAttribute('aria-disabled', 'true');
-  button.dataset.coordinateFinalGuard = 'enabled';
-});
-const resources = performance.getEntriesByType('resource');
-return {
-  path: window.location.pathname,
-  calendarFunctionPresent:
-    typeof window.CaricaTimelineOrizzontale === 'function',
-  finalButtonCount: finalButtons.length,
-  allFinalButtonsGuarded: finalButtons.every(
-    (button) => button.disabled &&
-      button.dataset.coordinateFinalGuard === 'enabled'
-  ),
-  finalRequestCount: resources.filter(
-    (entry) => entry.name.includes(
-      '/BookingCalendar/InsertNewBooking'
-    )
-  ).length,
-  timeSlotRequestCount: resources.filter(
-    (entry) => entry.name.includes(
-      '/BookingCalendar/RetrieveTimeSlots'
-    )
-  ).length,
-};
-"""
-
-
-NEXT_MONTH_CONTROL_SCRIPT = r"""
-/* coordinate:ita-calendar-query-next-month */
-const shouldClick = arguments[0] === true;
-const selector = '#datetimepicker th.dtpicker-next';
-const candidates = Array.from(document.querySelectorAll(selector));
-const isActionable = (element) => {
-  if (
-    !element.isConnected ||
-    element.hasAttribute('disabled') ||
-    element.getAttribute('aria-disabled') === 'true'
-  ) {
-    return false;
-  }
-  const style = window.getComputedStyle(element);
-  if (
-    style.display === 'none' ||
-    style.visibility === 'hidden' ||
-    style.pointerEvents === 'none' ||
-    Number.parseFloat(style.opacity || '1') <= 0
-  ) {
-    return false;
-  }
-  const rect = element.getBoundingClientRect();
-  const left = Math.max(0, rect.left);
-  const right = Math.min(window.innerWidth, rect.right);
-  const top = Math.max(0, rect.top);
-  const bottom = Math.min(window.innerHeight, rect.bottom);
-  if (right <= left || bottom <= top) return false;
-  const topNode = document.elementFromPoint(
-    (left + right) / 2,
-    (top + bottom) / 2
-  );
-  return Boolean(topNode && (
-    topNode === element || element.contains(topNode)
-  ));
-};
-const actionable = candidates.filter(isActionable);
-let clicked = false;
-if (shouldClick && actionable.length === 1) {
-  clicked = true;
-  actionable[0].click();
-}
-return {
-  pathMatches: window.location.pathname === '/BookingCalendar',
-  candidateCount: candidates.length,
-  actionableCount: actionable.length,
-  clicked,
-};
-"""
-
-
-class CalendarGateError(RuntimeError):
-    """Fail-closed Calendar adapter error without sensitive response data."""
-
-
-class CalendarAuthenticationExpiredError(CalendarGateError):
-    """An observed response explicitly rejected the authenticated session."""
-
-
-class CalendarRateLimitedError(CalendarGateError):
-    """The server explicitly limited requests; callers must not rotate accounts."""
-
-
-class CalendarAccessDeniedError(CalendarGateError):
-    """Permission or browser verification requires operator attention."""
-
-
-class CalendarTransientError(CalendarGateError):
-    """A read failed without evidence that authentication or schema changed."""
-
-
-class CalendarNextMonthUnavailableError(CalendarGateError):
-    """Raised when the native next-month control cannot be used safely."""
-
-
-def require_plain_nonnegative_int(value: object, name: str) -> int:
-    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
-        raise CalendarGateError(f"{name} must be a nonnegative integer")
-    return value
-
-
-def same_origin_path(raw_url: object) -> tuple[str, object]:
-    parsed = urlparse(str(raw_url or ""))
-    try:
-        port = parsed.port
-    except ValueError as exc:
-        raise CalendarGateError(
-            "Observed request used an unexpected origin"
-        ) from exc
-    if (
-        parsed.scheme != "https"
-        or parsed.hostname != "prenotami.esteri.it"
-        or port not in (None, 443)
-        or parsed.username is not None
-        or parsed.password is not None
-    ):
-        raise CalendarGateError("Observed request used an unexpected origin")
-    return parsed.path, parsed
-
-
-def header_value(headers: object, name: str) -> str:
-    if not hasattr(headers, "items"):
-        return ""
-    for key, value in headers.items():
-        if str(key).casefold() == name.casefold():
-            return str(value)
-    return ""
-
-
-@dataclass(frozen=True, slots=True)
-class CalendarProbeResult:
-    days: tuple[CalendarDay, ...]
-    selected_day: str
-
-    def __post_init__(self) -> None:
-        if not isinstance(self.selected_day, str) or not self.selected_day.strip():
-            raise CalendarGateError("selected_day must be a non-empty string")
-        if any(not isinstance(item, CalendarDay) for item in self.days):
-            raise CalendarGateError("days must contain CalendarDay values")
-        selected_month = self.selected_month
-        if any(
-            (item.day.year, item.day.month) != selected_month
-            for item in self.days
-        ):
-            raise CalendarGateError(
-                "Availability response escaped the requested month"
-            )
-
-    @property
-    def item_count(self) -> int:
-        return len(self.days)
-
-    @property
-    def available_days(self) -> tuple[CalendarDay, ...]:
-        return available_calendar_days(self.days)
-
-    @property
-    def available_count(self) -> int:
-        return len(self.available_days)
-
-    @property
-    def selected_month(self) -> tuple[int, int]:
-        value = self.selected_day.strip()[:10]
-        for date_format in ("%Y-%m-%d", "%d/%m/%Y"):
-            try:
-                parsed = datetime.strptime(value, date_format)
-            except ValueError:
-                continue
-            return parsed.year, parsed.month
-        raise CalendarGateError(
-            "Availability selectedDay used an unknown date format"
-        )
-
-
-def next_month_value(value: tuple[int, int]) -> tuple[int, int]:
-    year, month = value
-    return (year + 1, 1) if month == 12 else (year, month + 1)
-
-
-def month_text(value: tuple[int, int]) -> str:
-    return f"{value[0]:04d}-{value[1]:02d}"
-
-
-@dataclass(frozen=True, slots=True)
-class CalendarQueryScanResult:
-    """Result of scanning until the first positive month or the horizon end."""
-
-    probes: tuple[CalendarProbeResult, ...]
-    lookahead_months: int
-    stop_reason: str
-
-    def __post_init__(self) -> None:
-        _validate_lookahead_months(self.lookahead_months)
-        if not self.probes or any(
-            not isinstance(probe, CalendarProbeResult)
-            for probe in self.probes
-        ):
-            raise CalendarGateError(
-                "Calendar query scan requires parsed probe results"
-            )
-        if len(self.probes) > self.lookahead_months:
-            raise CalendarGateError(
-                "Calendar query scan exceeded the configured horizon"
-            )
-        for previous, current in zip(self.probes, self.probes[1:]):
-            if current.selected_month != next_month_value(
-                previous.selected_month
-            ):
-                raise CalendarGateError(
-                    "Calendar request did not advance exactly one month"
-                )
-
-        if self.stop_reason == "first_available_month":
-            if self.probes[-1].available_count == 0:
-                raise CalendarGateError(
-                    "first-available stop requires a positive final probe"
-                )
-            if any(probe.available_count for probe in self.probes[:-1]):
-                raise CalendarGateError(
-                    "Calendar query scanned beyond the first positive month"
-                )
-        elif self.stop_reason == "horizon_exhausted":
-            if len(self.probes) != self.lookahead_months:
-                raise CalendarGateError(
-                    "Calendar query ended before the configured horizon"
-                )
-            if any(probe.available_count for probe in self.probes):
-                raise CalendarGateError(
-                    "Calendar query ignored a positive month"
-                )
-        else:
-            raise CalendarGateError(
-                "Calendar query scan used an unknown stop reason"
-            )
-
-    @property
-    def scanned_months(self) -> int:
-        return len(self.probes)
-
-    @property
-    def available_days(self) -> tuple[CalendarDay, ...]:
-        if self.stop_reason != "first_available_month":
-            return ()
-        return self.probes[-1].available_days
-
-    @property
-    def earliest_available_date(self) -> date | None:
-        return (
-            self.available_days[0].day
-            if self.available_days
-            else None
-        )
-
-
-def _validate_lookahead_months(value: object) -> int:
-    if (
-        isinstance(value, bool)
-        or not isinstance(value, int)
-        or not 1 <= value <= MAX_QUERY_LOOKAHEAD_MONTHS
-    ):
-        raise CalendarGateError(
-            "lookahead_months must be between 1 and 120"
-        )
-    return value
-
-
-def listen_once(
-    page: object,
-    *,
-    target: str,
-    method: str,
-    action: Callable[[], Any],
-    timeout: float,
-) -> object:
-    """Listen around one native action and always stop the listener."""
-
-    page.listen.start(target, method=method)
-    try:
-        action()
-        packet = page.listen.wait(timeout=timeout)
-        if not packet:
-            raise CalendarTransientError(
-                f"Expected {method} {target} was not observed"
-            )
-        return packet
-    finally:
-        page.listen.stop()
-
-
-def parse_availability_packet(packet: object) -> CalendarProbeResult:
-    path, _ = same_origin_path(packet.url)
-    if str(packet.method).upper() != "POST" or path != AVAILABILITY_PATH:
-        raise CalendarGateError("Availability request method or path changed")
-    response = packet.response
-    status = response.status
-    if type(status) is not int:
-        raise CalendarGateError("Availability HTTP status was not an integer")
-    if status in {301, 302, 303, 307, 308}:
-        location = header_value(getattr(response, "headers", None), "Location")
-        destination = urlparse(urljoin(packet.url, location))
-        if location and destination.scheme == "https" and destination.hostname == "iam.esteri.it":
-            raise CalendarAuthenticationExpiredError("Calendar response redirected to IAM")
-    response_url = getattr(response, "url", None)
-    if isinstance(response_url, str) and response_url:
-        destination = urlparse(response_url)
-        if destination.scheme == "https" and destination.hostname == "iam.esteri.it":
-            raise CalendarAuthenticationExpiredError("Calendar response returned to IAM")
-        response_path, _ = same_origin_path(response_url)
-        if response_path != AVAILABILITY_PATH:
-            raise CalendarGateError("Availability response reached an unexpected path")
-    if status == 401:
-        raise CalendarAuthenticationExpiredError("Calendar authentication expired")
-    if status == 429:
-        raise CalendarRateLimitedError("Calendar request was rate limited")
-    if status == 403:
-        raise CalendarAccessDeniedError("Calendar access requires operator attention")
-    if status in {0, 408, 502, 503, 504}:
-        raise CalendarTransientError("Calendar request temporarily failed")
-    if status != 200:
-        raise CalendarGateError("Availability response status was not 200")
-
-    post_data = packet.request.postData
-    if isinstance(post_data, str):
-        try:
-            post_data = json.loads(post_data)
-        except json.JSONDecodeError as exc:
-            raise CalendarGateError(
-                "Availability request body was not JSON"
-            ) from exc
-    if not isinstance(post_data, dict) or set(post_data) != {
-        "_Servizio",
-        "selectedDay",
-    }:
-        raise CalendarGateError("Availability request keys changed")
-    if isinstance(post_data["_Servizio"], bool) or not str(
-        post_data["_Servizio"]
-    ).strip():
-        raise CalendarGateError("Availability runtime service id was empty")
-    if (
-        not isinstance(post_data["selectedDay"], str)
-        or not post_data["selectedDay"].strip()
-    ):
-        raise CalendarGateError("Availability selectedDay was empty")
-
-    try:
-        days = parse_calendar_availability(packet.response.raw_body)
-    except ItaProtocolError as exc:
-        raise CalendarGateError(
-            f"Availability response rejected ({exc.code})"
-        ) from exc
-    return CalendarProbeResult(
-        days=days,
-        selected_day=post_data["selectedDay"],
-    )
-
-
-def validate_next_month_snapshot(
-    raw: object,
-    *,
-    expected_clicked: bool,
-    allow_unready: bool = False,
-) -> dict[str, object]:
-    """Require the exact, non-sensitive Calendar month-control shape."""
-
-    if not isinstance(raw, dict):
-        raise CalendarGateError(
-            "Calendar next-month control did not return an object"
-        )
-    expected_keys = {
-        "pathMatches",
-        "candidateCount",
-        "actionableCount",
-        "clicked",
-    }
-    if set(raw) != expected_keys:
-        raise CalendarGateError(
-            "Calendar next-month control returned unexpected fields"
-        )
-    if raw["pathMatches"] is not True:
-        raise CalendarGateError(
-            "Calendar next-month control was evaluated outside Calendar"
-        )
-    candidate_count = require_plain_nonnegative_int(
-        raw["candidateCount"],
-        "candidateCount",
-    )
-    actionable_count = require_plain_nonnegative_int(
-        raw["actionableCount"],
-        "actionableCount",
-    )
-    if actionable_count > candidate_count:
-        raise CalendarGateError(
-            "Calendar next-month actionable count exceeded candidates"
-        )
-    if not isinstance(expected_clicked, bool):
-        raise CalendarGateError("expected_clicked must be a boolean")
-    if raw["clicked"] is not expected_clicked:
-        raise CalendarGateError(
-            "Calendar next-month click acknowledgement changed"
-        )
-    if actionable_count != 1 and not (
-        allow_unready and actionable_count == 0
-    ):
-        raise CalendarGateError(
-            "Calendar next-month control was not uniquely actionable"
-        )
-    return raw
-
-
-def click_next_month(
-    page: object,
-    *,
-    timeout: float = 10,
-    diagnostic: Callable[[object], None] | None = None,
-) -> None:
-    """Click only the unique visible Bootstrap day-view month control."""
-
-    deadline = time.monotonic() + timeout
-    last_raw: object = None
-    while time.monotonic() < deadline:
-        last_raw = page.run_js(NEXT_MONTH_CONTROL_SCRIPT, False)
-        try:
-            snapshot = validate_next_month_snapshot(
-                last_raw,
-                expected_clicked=False,
-                allow_unready=True,
-            )
-        except CalendarGateError:
-            if diagnostic:
-                diagnostic(last_raw)
-            raise
-        if snapshot["actionableCount"] == 1:
-            break
-        time.sleep(0.25)
-    else:
-        if diagnostic:
-            diagnostic(last_raw)
-        raise CalendarNextMonthUnavailableError(
-            "Calendar next-month control was not actionable before timeout"
-        )
-
-    clicked = page.run_js(NEXT_MONTH_CONTROL_SCRIPT, True)
-    if diagnostic:
-        diagnostic(clicked)
-    validate_next_month_snapshot(clicked, expected_clicked=True)
-
-
-def refresh_calendar(page: object) -> None:
-    page.refresh()
-    page.wait.doc_loaded()
-
-
-def guard_calendar(page: object) -> dict[str, object]:
-    """Disable the final button and reject any observed final request."""
-
-    raw = page.run_js(CALENDAR_GUARD_SCRIPT)
-    if not isinstance(raw, dict):
-        raise CalendarGateError("Calendar guard did not return an object")
-    expected = {
-        "path": CALENDAR_PATH,
-        "calendarFunctionPresent": True,
-        "finalButtonCount": 1,
-        "allFinalButtonsGuarded": True,
-        "finalRequestCount": 0,
-    }
-    for key, expected_value in expected.items():
-        if raw.get(key) != expected_value:
-            raise CalendarGateError(f"Calendar guard rejected {key}")
-    return raw
-
-
-def capture_initial_probe(page: object) -> CalendarProbeResult:
-    packet = listen_once(
-        page,
-        target=AVAILABILITY_PATH,
-        method="POST",
-        action=lambda: refresh_calendar(page),
-        timeout=30,
-    )
-    probe = parse_availability_packet(packet)
-    guard_calendar(page)
-    return probe
-
-
-def capture_next_probe(page: object) -> CalendarProbeResult:
-    packet = listen_once(
-        page,
-        target=AVAILABILITY_PATH,
-        method="POST",
-        action=lambda: click_next_month(page),
-        timeout=30,
-    )
-    probe = parse_availability_packet(packet)
-    guard_calendar(page)
-    return probe
-
-
-def scan_until_first_available_month(
-    page: object,
-    *,
-    lookahead_months: int,
-    log: Callable[[str], None] | None = None,
-    month_click_interval_seconds: float = DEFAULT_MONTH_CLICK_INTERVAL_SECONDS,
-) -> CalendarQueryScanResult:
-    """Scan sequential months and stop immediately at the first positive one."""
-
-    months = _validate_lookahead_months(lookahead_months)
-    if (
-        isinstance(month_click_interval_seconds, bool)
-        or not isinstance(month_click_interval_seconds, (int, float))
-        or month_click_interval_seconds < 0
-    ):
-        raise CalendarGateError(
-            "month_click_interval_seconds must be nonnegative"
-        )
-
-    probes = [capture_initial_probe(page)]
-    if log:
-        log(
-            "Italy Calendar probe "
-            f"index=0 available={probes[0].available_count}"
-        )
-    if probes[0].available_count:
-        return CalendarQueryScanResult(
-            probes=tuple(probes),
-            lookahead_months=months,
-            stop_reason="first_available_month",
-        )
-
-    for index in range(1, months):
-        if month_click_interval_seconds:
-            time.sleep(month_click_interval_seconds)
-        try:
-            probe = capture_next_probe(page)
-        except CalendarNextMonthUnavailableError as exc:
-            raise CalendarGateError(
-                "Calendar scan ended before the configured horizon"
-            ) from exc
-        if probe.selected_month != next_month_value(
-            probes[-1].selected_month
-        ):
-            raise CalendarGateError(
-                "Calendar request did not advance exactly one month"
-            )
-        probes.append(probe)
-        if log:
-            log(
-                "Italy Calendar probe "
-                f"index={index} available={probe.available_count}"
-            )
-        if probe.available_count:
-            return CalendarQueryScanResult(
-                probes=tuple(probes),
-                lookahead_months=months,
-                stop_reason="first_available_month",
-            )
-
-    return CalendarQueryScanResult(
-        probes=tuple(probes),
-        lookahead_months=months,
-        stop_reason="horizon_exhausted",
-    )

+ 0 - 603
plugins/ita_calendar_session.py

@@ -1,603 +0,0 @@
-"""Shared Italy form preparation and passive request audit.
-
-Extracted from the real-tested Calendar gate. Production and diagnostic tools
-use the same protocol; no tool imports, credentials, or network calls on import.
-"""
-from __future__ import annotations
-
-import json
-import time
-from enum import Enum
-from threading import Lock
-from urllib.parse import parse_qs, urljoin, urlparse
-
-from plugins.ita_calendar_query import (
-    AVAILABILITY_PATH, CALENDAR_PATH, CalendarGateError,
-    header_value as _header, same_origin_path as _same_origin_path,
-)
-from plugins.ita_protocol import ItaRouteConfig
-
-OTP_PATH = "/BookingCalendar/GenerateOTP"
-
-
-def booking_preflight_state(raw: object) -> str:
-    """Classify observed readiness, not the unknown cause of a widget failure."""
-    if not isinstance(raw, dict):
-        return "snapshot_unavailable"
-    token, disabled = raw.get("turnstileTokenPresent"), raw.get("avantiDisabled")
-    if type(token) is not bool or type(disabled) is not bool:
-        return "invalid_snapshot"
-    if not token:
-        return "turnstile_and_avanti_pending" if disabled else "turnstile_token_pending"
-    return "avanti_disabled" if disabled else "ready"
-
-
-def safe_booking_preflight_diagnostic(raw: object, *, stage, outcome: str) -> dict:
-    """Only bounded booleans/counts and fixed categories; never token/value/HTML."""
-    snapshot = raw if isinstance(raw, dict) else {}
-    result = {
-        "contract": "ita-book-preflight-v2",
-        "stage": stage.value if isinstance(stage, BookingPreflightStage) else "invalid",
-        "outcome": outcome if outcome in {"ready", "waiting", "rejected", "timeout", "read_failed"} else "invalid",
-        "state": booking_preflight_state(raw),
-    }
-    for key in ("pathMatches", "formPresent", "privacyChecked", "otpDisabled", "otpValuePresent",
-                "turnstileTokenPresent", "avantiDisabled", "turnstileApiPresent",
-                "turnstileScriptPresent", "documentVisible"):
-        value = snapshot.get(key)
-        result[key] = value if type(value) is bool else None
-    for key in ("turnstileCount", "avantiButtonCount", "unknownRequiredCount"):
-        value = snapshot.get(key)
-        result[key] = value if type(value) is int and 0 <= value <= 1000 else None
-    return result
-
-
-def _print_booking_preflight_diagnostic(raw: object, *, stage, outcome: str) -> None:
-    print("ITA_BOOK_PREFLIGHT_DIAGNOSTIC=" + json.dumps(
-        safe_booking_preflight_diagnostic(raw, stage=stage, outcome=outcome), sort_keys=True,
-    ), flush=True)
-
-
-def wait_for_booking_preflight(
-    page: object,
-    *,
-    script: str,
-    stage: BookingPreflightStage = None,
-    timeout: float = 120,
-    diagnostic=None,
-    wait_action=None,
-    check_current=None,
-) -> dict[str, object]:
-    """Wait without relaxing structure; optional bounded form interaction.
-
-    An interaction return value is never evidence of readiness: only the next
-    validated site snapshot can permit OTP/AVANTI. No recovery is enabled by
-    default; callers must explicitly supply their preparation recovery.
-    """
-
-    stage = stage if stage is not None else BookingPreflightStage.BEFORE_OTP_SEND
-    report = diagnostic or _print_booking_preflight_diagnostic
-    started = time.monotonic()
-    deadline = started + timeout
-    announced = False
-    raw = None
-    last_state = None
-    next_report = started
-    while (now := time.monotonic()) < deadline:
-        if check_current is not None:
-            check_current()
-        try:
-            raw = page.run_js(script)
-        except Exception:
-            report(None, stage=stage, outcome="read_failed")
-            raise CalendarGateError("Italy booking preflight read_failed") from None
-        if check_current is not None:
-            check_current()
-        try:
-            _validate_preflight_except_dynamic_token(raw, stage=stage)
-        except CalendarGateError:
-            report(
-                raw,
-                stage=stage,
-                outcome="rejected",
-            )
-            raise
-        if raw.get("turnstileTokenPresent") and not raw.get("avantiDisabled"):
-            try:
-                validate_booking_preflight(raw, stage=stage)
-            except CalendarGateError:
-                report(
-                    raw,
-                    stage=stage,
-                    outcome="rejected",
-                )
-                raise
-            report(
-                raw,
-                stage=stage,
-                outcome="ready",
-            )
-            return raw
-        if not announced:
-            print("ITA_BOOK_WAITING_FOR_FORM: watch the opened browser; complete any human verification. "
-                  "Do not click OTP, AVANTI, or final Prenota.", flush=True)
-            announced = True
-        state = booking_preflight_state(raw)
-        if state != last_state or now >= next_report:
-            report(raw, stage=stage, outcome="waiting")
-            last_state, next_report = state, now + 15
-        if wait_action is not None:
-            wait_action(raw, stage=stage, elapsed=now - started, remaining=deadline - now)
-        time.sleep(0.5)
-    report(raw, stage=stage, outcome="timeout")
-    raise CalendarGateError(f"Italy booking preflight timed out: {booking_preflight_state(raw)}")
-
-def guarded_preflight_script(route: ItaRouteConfig, booking_path: str) -> str:
-    """Check scope before the reused script changes any visible form control."""
-    prefix = """
-/* coordinate:ita-book-gate-form-boundary */
-const bookGateForms = document.querySelectorAll('#bookingForm');
-const bookGateForm = bookGateForms.length === 1 ? bookGateForms[0] : null;
-let bookGateAction = null;
-try { bookGateAction = bookGateForm ? new URL(bookGateForm.action, location.href) : null; }
-catch (_) {}
-if (location.origin !== 'https://prenotami.esteri.it' ||
-    location.pathname !== BOOK_GATE_PATH || !bookGateForm ||
-    bookGateForm.method.toUpperCase() !== 'POST' ||
-    bookGateForm.enctype !== 'multipart/form-data' ||
-    !bookGateAction || bookGateAction.origin !== location.origin ||
-    bookGateAction.pathname !== BOOK_GATE_PATH || bookGateAction.search || bookGateAction.hash ||
-    bookGateForm.querySelectorAll('input[type="file"]').length !== 0) {
-  return {pathMatches: false, formPresent: false};
-}
-""".replace("BOOK_GATE_PATH", json.dumps(booking_path))
-    return prefix + _booking_preflight_script(route, booking_path)
-
-class BookingPreflightStage(Enum):
-    BEFORE_OTP_SEND = "before_otp_send"
-    AFTER_OTP_SEND = "after_otp_send"
-
-
-class CalendarRequestAudit:
-    """Passively count business requests across refreshes; never retain bodies.
-
-    The production page.listen owns a separate CDP connection. This diagnostic
-    callback uses the page driver and refuses to replace an existing handler.
-    It never enables Fetch interception or changes any browser request.
-    """
-
-    EVENT = "Network.requestWillBeSent"
-
-    def __init__(self, page: object, *, include_time_slots: bool = False) -> None:
-        self.page = page
-        self.driver = page.driver
-        self._callback = self._on_request
-        self._lock = Lock()
-        self._started = False
-        self._invalid_event = False
-        self._counts = {
-            "otpRequests": 0,
-            "avantiPosts": 0,
-            "availabilityRequests": 0,
-            "finalRequests": 0,
-        }
-        if include_time_slots:
-            self._counts["timeSlotRequests"] = 0
-
-    def enable_time_slot_counting(self) -> None:
-        """Opt in for the soak; existing gate counter shapes stay unchanged."""
-        with self._lock:
-            self._counts.setdefault("timeSlotRequests", 0)
-
-    def start(self) -> None:
-        if self._started:
-            raise CalendarGateError("Passive request audit was already started")
-        for name in ("event_handlers", "immediate_event_handlers"):
-            handlers = getattr(self.driver, name, None)
-            if not isinstance(handlers, dict) or self.EVENT in handlers:
-                raise CalendarGateError(
-                    "Passive request audit cannot replace an existing callback"
-                )
-        self.driver.set_callback(self.EVENT, self._callback, immediate=True)
-        self._started = True
-        try:
-            self.page.run_cdp("Network.enable")
-        except Exception:
-            self.stop()
-            raise
-
-    def stop(self) -> None:
-        if not self._started:
-            return
-        if self.driver.immediate_event_handlers.get(self.EVENT) is not self._callback:
-            raise CalendarGateError("Passive request audit callback changed")
-        self.driver.set_callback(self.EVENT, None, immediate=True)
-        self._started = False
-
-    def _on_request(self, **event: object) -> None:
-        request = event.get("request")
-        if (
-            not isinstance(request, dict)
-            or not isinstance(request.get("url"), str)
-            or not isinstance(request.get("method"), str)
-        ):
-            with self._lock:
-                self._invalid_event = True
-            return
-        try:
-            path, _ = _same_origin_path(request["url"])
-        except CalendarGateError:
-            return
-        method = request["method"].upper()
-        key = None
-        if path == OTP_PATH:
-            key = "otpRequests"
-        elif path == "/BookingCalendar/InsertNewBooking":
-            key = "finalRequests"
-        elif method == "POST" and path.startswith("/Services/Booking/"):
-            key = "avantiPosts"
-        elif path == AVAILABILITY_PATH:
-            key = "availabilityRequests"
-        elif path == "/BookingCalendar/RetrieveTimeSlots" and "timeSlotRequests" in self._counts:
-            key = "timeSlotRequests"
-        if key is not None:
-            with self._lock:
-                self._counts[key] += 1
-
-    def require_active_on(self, page: object) -> None:
-        """Validate a borrowed audit without registering or removing callbacks."""
-        if self.page is not page or self.driver is not getattr(page, "driver", None):
-            raise CalendarGateError("Passive request audit belongs to another page or driver")
-        if not self._started or self.driver.is_running is not True:
-            raise CalendarGateError("Passive request audit is not connected")
-        immediate = getattr(self.driver, "immediate_event_handlers", None)
-        regular = getattr(self.driver, "event_handlers", None)
-        if (not isinstance(immediate, dict) or immediate.get(self.EVENT) is not self._callback
-                or not isinstance(regular, dict) or self.EVENT in regular):
-            raise CalendarGateError("Passive request audit callback changed")
-
-    def snapshot(self) -> dict[str, int]:
-        self.require_active_on(self.page)
-        with self._lock:
-            if self._invalid_event:
-                raise CalendarGateError("Passive request audit received an invalid event")
-            return dict(self._counts)
-
-    def retained_snapshot(self) -> dict[str, int]:
-        """Best-effort last observed counters, not proof after a disconnect."""
-        with self._lock:
-            if self._invalid_event:
-                raise CalendarGateError("Passive request audit received an invalid event")
-            return dict(self._counts)
-
-    def settled_snapshot(self, *, timeout: float = 3) -> dict[str, int]:
-        # A read-only CDP round trip plus a bounded stable-count window lets
-        # already-arriving callbacks catch up before a per-query comparison.
-        self.page.run_cdp("Page.getFrameTree")
-        deadline = time.monotonic() + timeout
-        previous = self.snapshot()
-        stable_since = time.monotonic()
-        while time.monotonic() < deadline:
-            time.sleep(0.1)
-            current = self.snapshot()
-            if current != previous:
-                previous = current
-                stable_since = time.monotonic()
-            elif time.monotonic() - stable_since >= 0.3:
-                return current
-        raise CalendarGateError("Passive business-request counts did not settle")
-
-
-def validate_otp_packet(packet: object, *, service_id: int) -> None:
-    path, parsed = _same_origin_path(packet.url)
-    if str(packet.method).upper() != "GET" or path != OTP_PATH:
-        raise CalendarGateError("OTP request method or path changed")
-    if parse_qs(parsed.query) != {"ServiceID": [str(service_id)]}:
-        raise CalendarGateError("OTP request service id changed")
-    if packet.response.status != 200:
-        raise CalendarGateError("OTP response status was not 200")
-    raw_body = packet.response.raw_body
-    if not isinstance(raw_body, str):
-        raise CalendarGateError("OTP response body type changed")
-    try:
-        decoded = json.loads(raw_body)
-    except json.JSONDecodeError as exc:
-        raise CalendarGateError("OTP response was not the observed JSON string") from exc
-    if decoded != "SENT":
-        raise CalendarGateError("OTP response did not confirm SENT")
-
-
-def validate_avanti_packet(
-    packet: object,
-    *,
-    booking_path: str,
-    final_page_url: str,
-) -> str:
-    path, request_url = _same_origin_path(packet.url)
-    if (
-        str(packet.method).upper() != "POST"
-        or path != booking_path
-        or request_url.query
-        or request_url.fragment
-    ):
-        raise CalendarGateError("AVANTI request method or path changed")
-
-    status = packet.response.status
-    if status == 302:
-        raw_location = _header(packet.response.headers, "location")
-        redirect_path, _ = _same_origin_path(
-            urljoin("https://prenotami.esteri.it", raw_location)
-        )
-        if redirect_path != CALENDAR_PATH:
-            raise CalendarGateError("AVANTI redirect did not target Calendar")
-        transition_mode = "direct_302"
-    elif status == 200:
-        response_path, _ = _same_origin_path(
-            getattr(packet.response, "url", "")
-        )
-        if response_path != CALENDAR_PATH:
-            raise CalendarGateError(
-                "AVANTI followed response did not target Calendar"
-            )
-        transition_mode = "followed_redirect_200"
-    else:
-        raise CalendarGateError(
-            "AVANTI response status was not an allowed redirect representation"
-        )
-
-    final_path, _ = _same_origin_path(final_page_url)
-    if final_path != CALENDAR_PATH:
-        raise CalendarGateError("AVANTI browser did not finish on Calendar")
-    return transition_mode
-
-
-def validate_booking_preflight(
-    raw: object,
-    *,
-    stage: BookingPreflightStage = BookingPreflightStage.BEFORE_OTP_SEND,
-) -> None:
-    """Validate shared form shape and the stage-sensitive OTP-send control."""
-
-    if not isinstance(raw, dict):
-        raise CalendarGateError("Booking preflight did not return an object")
-    if not isinstance(stage, BookingPreflightStage):
-        raise CalendarGateError("Booking preflight stage is invalid")
-    true_fields = (
-        "pathMatches",
-        "formPresent",
-        "bookingTypeOptionMatched",
-        "purposeOptionMatched",
-        "bookingVisibleMatches",
-        "bookingHiddenMatches",
-        "companionsHiddenIsZero",
-        "purposeVisibleMatches",
-        "purposeHiddenIsPreSubmit",
-        "privacyChecked",
-        "turnstileTokenPresent",
-    )
-    for field_name in true_fields:
-        if raw.get(field_name) is not True:
-            raise CalendarGateError(
-                f"Booking preflight rejected {field_name}"
-            )
-    for field_name in (
-        "otpInputCount",
-        "otpButtonCount",
-        "avantiButtonCount",
-        "turnstileCount",
-    ):
-        if raw.get(field_name) != 1:
-            raise CalendarGateError(
-                f"Booking preflight rejected {field_name}"
-            )
-    otp_disabled = raw.get("otpDisabled")
-    if not isinstance(otp_disabled, bool) or (
-        stage is BookingPreflightStage.BEFORE_OTP_SEND
-        and otp_disabled
-    ):
-        raise CalendarGateError(
-            "Booking preflight rejected otpDisabled"
-        )
-    if raw.get("avantiDisabled") is not False:
-        raise CalendarGateError(
-            "Booking preflight rejected avantiDisabled"
-        )
-    otp_value_present = raw.get("otpValuePresent")
-    expected_otp_value_present = (
-        stage is BookingPreflightStage.AFTER_OTP_SEND
-    )
-    if (
-        not isinstance(otp_value_present, bool)
-        or otp_value_present is not expected_otp_value_present
-    ):
-        raise CalendarGateError(
-            "Booking preflight rejected otpValuePresent"
-        )
-    if raw.get("unknownRequiredCount") != 0:
-        raise CalendarGateError(
-            "Booking preflight rejected unknownRequiredCount"
-        )
-
-
-def _booking_preflight_script(
-    route: ItaRouteConfig,
-    booking_path: str,
-) -> str:
-    if route.booking_type is None or route.purpose is None:
-        raise CalendarGateError("Q-CAL route is missing form controls")
-    config = {
-        "bookingPath": booking_path,
-        "bookingTypeId": route.booking_type.control_id,
-        "bookingTypeValue": route.booking_type.value,
-        "bookingTypeLabels": list(route.booking_type.labels),
-        "purposeId": route.purpose.control_id,
-        "purposeValue": route.purpose.value,
-        "purposeLabels": list(route.purpose.labels),
-    }
-    config_json = json.dumps(config, ensure_ascii=False)
-    return f"""
-/* coordinate:ita-qcal-booking-preflight */
-const cfg = {config_json};
-const normalize = (value) => String(value || '')
-  .replace(/\\s+/g, ' ').trim().toLocaleLowerCase();
-const form = document.querySelector('#bookingForm');
-const booking = document.getElementById(cfg.bookingTypeId);
-const purpose = document.getElementById(cfg.purposeId);
-const bookingOption = booking
-  ? Array.from(booking.options).find(
-      (option) => option.value === cfg.bookingTypeValue
-    )
-  : null;
-const purposeOption = purpose
-  ? Array.from(purpose.options).find(
-      (option) => option.value === cfg.purposeValue
-    )
-  : null;
-const bookingLabels = cfg.bookingTypeLabels.map(normalize);
-const purposeLabels = cfg.purposeLabels.map(normalize);
-const bookingTypeOptionMatched = Boolean(
-  bookingOption && bookingLabels.includes(normalize(bookingOption.textContent))
-);
-const purposeOptionMatched = Boolean(
-  purposeOption && purposeLabels.includes(normalize(purposeOption.textContent))
-);
-if (bookingTypeOptionMatched && booking.value !== cfg.bookingTypeValue) {{
-  booking.value = cfg.bookingTypeValue;
-  booking.dispatchEvent(new Event('change', {{bubbles: true}}));
-}}
-if (purposeOptionMatched && purpose.value !== cfg.purposeValue) {{
-  purpose.value = cfg.purposeValue;
-  purpose.dispatchEvent(new Event('change', {{bubbles: true}}));
-}}
-const privacy = document.getElementById('PrivacyCheck');
-if (privacy && !privacy.checked) privacy.click();
-const allowedRequiredIds = new Set([
-  cfg.bookingTypeId,
-  cfg.purposeId,
-  'otp-input',
-  'PrivacyCheck',
-  'hiddenTipoPrenotazione',
-  'numAccSelected',
-  'hiddenSelezionato_0',
-]);
-const allowedRequiredNames = new Set([
-  'otp-input',
-  'PrivacyCheck',
-  'cf-turnstile-response',
-  '__RequestVerificationToken',
-]);
-const unknownRequired = form
-  ? Array.from(form.querySelectorAll('[required]')).filter((element) =>
-      !allowedRequiredIds.has(element.id) &&
-      !allowedRequiredNames.has(element.name)
-    )
-  : [];
-const bookingHidden = document.getElementById('hiddenTipoPrenotazione');
-const companionsHidden = document.getElementById('numAccSelected');
-const purposeHidden = document.getElementById('hiddenSelezionato_0');
-const otpInputs = document.querySelectorAll('#otp-input');
-const otpButtons = document.querySelectorAll('#otp-send');
-const avantiButtons = document.querySelectorAll('#btnAvanti');
-const turnstile = document.querySelectorAll(
-  'input[name="cf-turnstile-response"]'
-);
-return {{
-  pathMatches: window.location.pathname === cfg.bookingPath,
-  formPresent: Boolean(form),
-  bookingTypeOptionMatched,
-  purposeOptionMatched,
-  bookingVisibleMatches: Boolean(
-    booking && booking.value === cfg.bookingTypeValue
-  ),
-  bookingHiddenMatches: Boolean(
-    bookingHidden && bookingHidden.value === cfg.bookingTypeValue
-  ),
-  companionsHiddenIsZero: Boolean(
-    companionsHidden && companionsHidden.value === '0'
-  ),
-  purposeVisibleMatches: Boolean(
-    purpose && purpose.value === cfg.purposeValue
-  ),
-  purposeHiddenIsPreSubmit: Boolean(
-    purposeHidden && ['0', cfg.purposeValue].includes(purposeHidden.value)
-  ),
-  privacyChecked: Boolean(privacy && privacy.checked),
-  otpInputCount: otpInputs.length,
-  otpValuePresent: Boolean(
-    otpInputs.length === 1 && String(otpInputs[0].value || '').trim()
-  ),
-  otpButtonCount: otpButtons.length,
-  otpDisabled: otpButtons.length === 1 ? otpButtons[0].disabled : null,
-  avantiButtonCount: avantiButtons.length,
-  avantiDisabled:
-    avantiButtons.length === 1 ? avantiButtons[0].disabled : null,
-  turnstileCount: turnstile.length,
-  turnstileTokenPresent: Boolean(
-    turnstile.length === 1 && turnstile[0].value
-  ),
-  turnstileApiPresent: Boolean(window.turnstile),
-  turnstileScriptPresent: Boolean(document.querySelector(
-    'script[src^="https://challenges.cloudflare.com/turnstile/"]'
-  )),
-  documentVisible: document.visibilityState === 'visible',
-  unknownRequiredCount: unknownRequired.length,
-}};
-"""
-
-
-def _validate_preflight_except_dynamic_token(
-    raw: object,
-    *,
-    stage: BookingPreflightStage,
-) -> None:
-    if not isinstance(raw, dict):
-        raise CalendarGateError("Booking preflight did not return an object")
-    for key in ("turnstileTokenPresent", "avantiDisabled"):
-        if type(raw.get(key)) is not bool:
-            raise CalendarGateError(f"Booking preflight rejected {key}")
-    candidate = dict(raw)
-    candidate["turnstileTokenPresent"] = True
-    candidate["avantiDisabled"] = False
-    validate_booking_preflight(candidate, stage=stage)
-
-
-def _wait_for_calendar(page: object, timeout: float = 30) -> None:
-    deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        if (urlparse(str(page.url or "")).path.rstrip("/") or "/") == CALENDAR_PATH:
-            page.wait.doc_loaded()
-            return
-        time.sleep(0.25)
-    raise CalendarGateError("AVANTI did not reach Calendar before timeout")
-
-
-def _element_or_fail(page: object, selector: str) -> object:
-    element = page.ele(selector, timeout=5)
-    if not element:
-        raise CalendarGateError(f"Required element is missing: {selector}")
-    return element
-
-
-def _read_manual_otp() -> str:
-    otp = input(
-        "Italy booking OTP "
-        "(visible; terminal scrollback may retain it): "
-    ).strip()
-    if not otp.isdigit() or not 4 <= len(otp) <= 12:
-        raise CalendarGateError("OTP must be 4-12 digits")
-    return otp
-
-
-def _enter_otp(plugin: object, otp: str) -> None:
-    """Focus, type, and compare in-page without returning the OTP value."""
-
-    otp_input = _element_or_fail(plugin.page, "#otp-input")
-    plugin.mouse.human_click_ele(otp_input)
-    otp_input.input(otp, clear=True)
-    value_matches = otp_input.run_js(
-        "return this.value === arguments[0];",
-        otp,
-    )
-    if value_matches is not True:
-        raise CalendarGateError("OTP DOM write verification failed")
-    print("ITA_QCAL_OTP_DOM_WRITE_VERIFIED matched=true")

+ 0 - 252
plugins/ita_final_read_port.py

@@ -1,252 +0,0 @@
-"""Read-port adapter shared by production Book and local final validation.
-
-Preserves the applicant Calendar in its original tab. Reads existing receipts in
-an owned background tab of the SAME browser/context. Baselines allow only empty
-or cancelled history. A new confirmed receipt may bind to a verified native POST;
-observed receipt fields remain distinct from submission evidence.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import threading
-import time
-from dataclasses import dataclass, field
-from uuid import uuid4
-from urllib.parse import parse_qsl
-
-from plugins.ita_booking_final import (
-    FinalBookingError, FinalTarget, ReservationRecord, ReservationSnapshot, ReservationState, VerifiedSubmission,
-)
-from plugins.ita_calendar_query import CALENDAR_PATH, same_origin_path
-from plugins.ita_protocol import ItaCapability, ItaRouteConfig, PrecommitApproval
-from plugins.ita_reservation import read_reservation_detail, read_reservation_listing
-
-
-LIST_URL = "https://prenotami.esteri.it/Reservation"
-MAX_DETAIL_READS = 20
-
-
-@dataclass(frozen=True, repr=False)
-class ReceiptObservation:
-    """Bound display evidence only; UNKNOWN is never promoted to success."""
-
-    records: tuple = field(repr=False)  # (verified list row, matching detail)
-
-
-def _require(condition, reason):
-    if condition is not True:
-        raise FinalBookingError(reason)
-
-
-def _cancelled_record(row, detail) -> ReservationRecord:
-    _require(row.state is ReservationState.CANCELLED and detail.state is ReservationState.CANCELLED and
-             detail.status_code == "3" and all(getattr(row, field) == getattr(detail, field) for field in (
-                 "reference", "office", "service_name", "day", "appointment_time", "status_text")),
-             "Italy cancelled receipt is not verified")
-    # Equality of fingerprints preserves changes to fields absent from the final
-    # model (office, displayed service, booking type). It is NOT identity proof.
-    facts = [detail.reference, row.detail_url, detail.office, detail.service_name, detail.booking_type,
-             detail.day.isoformat(), detail.appointment_time, detail.status_text, detail.status_code]
-    digest = hashlib.sha256(json.dumps(facts, ensure_ascii=True, separators=(",", ":")).encode()).hexdigest()
-    return ReservationRecord(detail.reference, None, detail.day, None, ReservationState.CANCELLED,
-                             appointment_time=detail.appointment_time, receipt_fingerprint=digest)
-
-
-def _confirmed_record(row, detail, submission: VerifiedSubmission) -> ReservationRecord:
-    target, slot = submission.target, submission.target.approval.candidate
-    _require(row.state is ReservationState.ACTIVE and detail.state is ReservationState.ACTIVE and
-             detail.status_code == "2" and detail.booking_type == "Prenotazione Singola" and
-             isinstance(target.service_name, str) and detail.service_name == target.service_name and
-             detail.day == slot.day and slot.time_label[:5] <= detail.appointment_time <= slot.time_label[-5:] and
-             all(getattr(row, key) == getattr(detail, key) for key in (
-                 "reference", "office", "service_name", "day", "appointment_time", "status_text")),
-             "Italy confirmed receipt does not match the submitted selection")
-    facts = [detail.reference, row.detail_url, detail.office, detail.service_name, detail.booking_type,
-             detail.day.isoformat(), detail.appointment_time, detail.status_text, detail.status_code]
-    digest = hashlib.sha256(json.dumps(facts, ensure_ascii=True, separators=(",", ":")).encode()).hexdigest()
-    # The website receipt supplies neither service_id nor the selected interval.
-    # Keep them None; the separate evidence explicitly identifies the native POST.
-    return ReservationRecord(detail.reference, None, detail.day, None, ReservationState.ACTIVE,
-                             appointment_time=detail.appointment_time, receipt_fingerprint=digest,
-                             submission=submission)
-
-
-class FinalReceiptReadPort:
-    """Capture an existing applicant Book precommit, then read fresh snapshots.
-
-    Uses the plugin's established session/route checks, not a caller-supplied
-    username assertion. Constructor does no navigation. Calling the port reads
-    only; it never touches final buttons, rebuilds calendars or generates OTP.
-    The owning Book workflow must serialize this with other browser work.
-    """
-
-    def __init__(self, plugin, route: ItaRouteConfig, *, observe_tab=None):
-        try:
-            _require(isinstance(route, ItaRouteConfig) and
-                     route.capability is ItaCapability.SINGLE_SCHENGEN_TOURISM,
-                     "Italy final read route is invalid")
-            self._plugin, self._route = plugin, route
-            _require(observe_tab is None or callable(observe_tab), "Italy receipt observer is invalid")
-            self._observe_tab = observe_tab
-            self._page = plugin.page
-            self._browser = self._page.browser
-            self._browser_id = self._browser.id
-            self._generation = plugin.session_create_time
-            self._prepared = plugin._calendar_book_prepared_context
-            self._approval = plugin.last_booking_precommit
-            self._username = plugin.config.account.username.strip().casefold()
-            _require(isinstance(self._approval, PrecommitApproval) and
-                     isinstance(self._prepared, tuple) and len(self._prepared) == 7 and
-                     isinstance(self._browser_id, str) and bool(self._browser_id) and
-                     same_origin_path(self._page.url)[0] == CALENDAR_PATH,
-                     "Italy final read requires the current Book precommit")
-            _, calendar_url = same_origin_path(self._page.url)
-            names = [value for key, value in parse_qsl(calendar_url.query, keep_blank_values=True)
-                     if key == "selectedService"]
-            service_name = names[0] if len(names) == 1 and names[0] else None
-            self._target = FinalTarget(self._username, uuid4().hex, self._page.tab_id,
-                                       route.routing_key, str(route.service_id), self._prepared[5], self._approval,
-                                       service_name=service_name)
-            self._lock = threading.Lock()
-            self._unusable = False
-            self._baseline = None
-            self._submission = None
-            _require(self.session_is_current(), "Italy final read Session is not current")
-        except Exception:
-            raise FinalBookingError("Italy final read context could not be captured") from None
-
-    @property
-    def target(self):
-        return self._target
-
-    def session_is_current(self) -> bool:
-        try:
-            p = self._plugin
-            same_origin_path(self._page.url)
-            return (not self._unusable and p.page is self._page and self._page.browser is self._browser and
-                    self._browser.id == self._browser_id and self._page.tab_id == self._target.tab_id and
-                    p.session_create_time == self._generation and p.is_healthy is True and
-                    p.last_booking_precommit is self._approval and
-                    p._calendar_book_prepared_context == self._prepared and
-                    p.config.account.username.strip().casefold() == self._username and
-                    p._calendar_book_context_matches(self._route, self._username) is True)
-        except Exception:
-            return False
-
-    def __call__(self) -> ReservationSnapshot:
-        snapshot = self._read(observation=False)
-        if self._submission is None:
-            self._baseline = snapshot
-        return snapshot
-
-    def record_submission(self, submission: VerifiedSubmission) -> None:
-        """Called only after a matched native POST and one-request audit."""
-        _require(self.session_is_current() and self._baseline is not None and self._submission is None and
-                 isinstance(submission, VerifiedSubmission) and submission.target == self.target and
-                 self.target.service_name is not None, "Italy submission binding is not current")
-        self._submission = submission
-
-    def observe_receipts(self) -> ReceiptObservation:
-        """Read unknown status text for controlled discovery, NOT reconciliation."""
-        return self._read(observation=True)
-
-    def _read(self, *, observation: bool):
-        if not self._lock.acquire(blocking=False):
-            raise FinalBookingError("Italy receipt read is already running")
-        receipt_page = None
-        finish_observation = None
-        close_failed = False
-        cleanup_interrupt = None
-        try:
-            _require(self.session_is_current(), "Italy final read Session changed")
-            origin = (self._page.url, self._page.tab_id)
-            candidate = self._browser.new_tab(background=True, new_context=False)
-            # Only close a separately identified tab created by our own browser.
-            # A broken factory returning the original/foreign page is not owned.
-            _require(candidate is not self._page and candidate.browser is self._browser and
-                     isinstance(candidate.tab_id, str) and bool(candidate.tab_id) and
-                     candidate.tab_id != self._target.tab_id, "Italy receipt tab ownership is unverified")
-            receipt_page, receipt_tab = candidate, candidate.tab_id
-            if self._observe_tab is not None:
-                finish_observation = self._observe_tab(receipt_page)
-                _require(callable(finish_observation), "Italy receipt observer did not start")
-
-            def context():
-                _require(self.session_is_current() and (self._page.url, self._page.tab_id) == origin and
-                         receipt_page.browser is self._browser and receipt_page.tab_id == receipt_tab,
-                         "Italy receipt read context changed")
-
-            def navigate(url):
-                context()
-                _require(receipt_page.get(url, retry=0, timeout=30) is not False,
-                         "Italy receipt navigation failed")
-                context()
-                same_origin_path(receipt_page.url)
-                _require(receipt_page.url == url, "Italy receipt navigation was redirected")
-
-            navigate(LIST_URL)
-            before = read_reservation_listing(receipt_page)
-            context()
-            _require(before.waitlist_count == 0 and len(before.rows) <= MAX_DETAIL_READS,
-                     "Italy receipt coverage exceeds supported verification")
-            if not observation and self._submission is None:
-                _require(all(row.state is ReservationState.CANCELLED for row in before.rows),
-                         "Italy live receipt attribution is not verified")
-            records = []
-            for row in before.rows:
-                # Only actual links accepted by the established listing parser.
-                navigate(row.detail_url)
-                detail = read_reservation_detail(receipt_page)
-                context()
-                _require(all(getattr(row, key) == getattr(detail, key) for key in (
-                    "reference", "office", "service_name", "day", "appointment_time", "status_text")),
-                    "Italy observed receipt does not match its list row")
-                if observation:
-                    records.append((row, detail))
-                elif row.state is ReservationState.CANCELLED:
-                    records.append(_cancelled_record(row, detail))
-                else:
-                    _require(self._submission is not None and self._baseline is not None and
-                             row.reference not in {r.reference for r in self._baseline.records},
-                             "Italy receipt is not new to this submission")
-                    records.append(_confirmed_record(row, detail, self._submission))
-            navigate(LIST_URL)
-            after = read_reservation_listing(receipt_page)
-            context()
-            _require({r.reference: r for r in before.rows} == {r.reference: r for r in after.rows} and
-                     before.waitlist_count == after.waitlist_count, "Italy receipt history changed during read")
-            snapshot = (ReceiptObservation(tuple(records)) if observation else
-                        ReservationSnapshot(self._target.applicant, self._target.session_key,
-                                            time.monotonic(), True, tuple(records)))
-        except Exception:
-            raise FinalBookingError("Italy bound receipt read could not be verified") from None
-        finally:
-            if callable(finish_observation):
-                try:
-                    finish_observation()
-                except BaseException as exc:
-                    self._unusable = True
-                    if isinstance(exc, Exception):
-                        close_failed = True
-                    else:
-                        cleanup_interrupt = exc
-            if receipt_page is not None:
-                try:
-                    receipt_page.close()
-                except BaseException as exc:
-                    # Do not trust a later read after losing control of an owned tab.
-                    self._unusable = True
-                    if isinstance(exc, Exception):
-                        close_failed = True
-                    else:
-                        cleanup_interrupt = exc
-            self._lock.release()
-            if cleanup_interrupt is not None:
-                raise cleanup_interrupt
-            if close_failed:
-                raise FinalBookingError("Italy owned receipt tab cleanup failed") from None
-        _require(self.session_is_current() and (self._page.url, self._page.tab_id) == origin,
-                 "Italy final read context changed during cleanup")
-        return snapshot

+ 0 - 140
plugins/ita_otp.py

@@ -1,140 +0,0 @@
-"""Italy-only OTP adapter.
-
-The adapter deliberately reuses ``VSCloudApi.fetch_mail_content`` instead of
-creating another mail provider.  It adds the Italy contract around that call:
-one sent-time window, a fixed Prenot@Mi sender filter, deterministic body
-parsing, and fail-closed errors that never carry the raw mail body.
-
-The provider returns body only: its header/time filtering is a dependency, not
-independent sender authentication or freshness proof by this adapter.
-"""
-
-from __future__ import annotations
-
-import logging
-import re
-from datetime import datetime, timezone
-
-import vs_log_macros
-from plugins.ita_calendar_query import CalendarGateError
-from plugins.ita_protocol import (
-    ItaProtocolError,
-    OtpMailConfig,
-    PRENOTAMI_OTP_SENDER,
-    parse_otp_body,
-)
-from toolkit.vs_cloud_api import VSCloudApi
-from vs_types import (
-    BizLogicError,
-    PermissionDeniedError,
-    RateLimiteddError,
-    SessionExpiredOrInvalidError,
-)
-
-
-_EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
-_SENT_AT_FORMAT = "%Y-%m-%d %H:%M:%S"
-
-
-def utc_sent_at() -> str:
-    """Return the exact UTC format required by the existing cloud endpoint."""
-
-    return datetime.now(timezone.utc).strftime(_SENT_AT_FORMAT)
-
-
-def validate_cloud_otp_logging() -> None:
-    """Validate before any shared SDK call; never change logging state.
-
-    Existing SDK DEBUG output includes raw mail. Automatic Italy OTP therefore
-    requires a stable INFO-or-higher logger throughout the call. Runtime log
-    reconfiguration and backend logging are outside this local guarantee.
-    """
-    logger = getattr(vs_log_macros, "_active_logger", None)
-    if not isinstance(logger, logging.Logger) or logger.isEnabledFor(logging.DEBUG):
-        raise CalendarGateError("Italy automatic OTP requires DEBUG payload logging to be disabled")
-
-
-def validate_cloud_otp_environment(mail_config: OtpMailConfig, recipient: str) -> None:
-    """Validate the configured mailbox policy and actual account before OTP."""
-    if not isinstance(mail_config, OtpMailConfig):
-        raise CalendarGateError("Italy OTP mail configuration is missing")
-    recipient_value = _validate_recipient(recipient)
-    mail_config.mailbox_for(recipient_value)
-    validate_cloud_otp_logging()
-
-
-def _validate_recipient(recipient: str) -> str:
-    if not isinstance(recipient, str):
-        raise CalendarGateError("Italy OTP recipient must be an email address")
-    value = recipient.strip()
-    if not _EMAIL_PATTERN.fullmatch(value):
-        raise CalendarGateError("Italy OTP recipient must be an email address")
-    return value
-
-
-def _validate_sent_at(sent_at: str) -> str:
-    if not isinstance(sent_at, str):
-        raise CalendarGateError("Italy OTP sent time is invalid")
-    value = sent_at.strip()
-    try:
-        datetime.strptime(value, _SENT_AT_FORMAT)
-    except ValueError:
-        raise CalendarGateError("Italy OTP sent time is invalid") from None
-    return value
-
-
-def fetch_otp_from_cloud(
-    mail_config: OtpMailConfig,
-    *,
-    recipient: str,
-    sent_at: str,
-    api: VSCloudApi | None = None,
-) -> str:
-    """Read and parse one new Italy OTP through the existing cloud API.
-
-    The call is intentionally one-shot.  ``fetch-top`` is not a fallback and
-    no retry or second OTP request is issued after a read/parse failure.
-    """
-
-    validate_cloud_otp_environment(mail_config, recipient)
-    recipient_value = _validate_recipient(recipient)
-    sent_at_value = _validate_sent_at(sent_at)
-    try:
-        client = api if api is not None else VSCloudApi.Instance()
-        # Keep the body inside this scope; callers receive only the parsed
-        # digits and must not log either the body or the code.
-        body = client.fetch_mail_content(
-            email=mail_config.mailbox_for(recipient_value),
-            sender=PRENOTAMI_OTP_SENDER,
-            recipient=recipient_value,
-            subject_keywords=mail_config.subject_keywords,
-            body_keywords=mail_config.body_keywords,
-            sent_date=sent_at_value,
-            expiry=mail_config.expiry_seconds,
-            only_text=True,
-        )
-    except SessionExpiredOrInvalidError:
-        # Mail API authentication is NOT the appointment site's Session.
-        raise CalendarGateError("Italy OTP mailbox API authentication failed") from None
-    except PermissionDeniedError:
-        raise CalendarGateError(
-            "Italy OTP mailbox authorization is not permitted"
-        ) from None
-    except RateLimiteddError:
-        raise CalendarGateError("Italy OTP mailbox read was rate limited") from None
-    except BizLogicError:
-        # The shared SDK may include a provider response body in this error.
-        raise CalendarGateError("Italy OTP mailbox read failed") from None
-    except Exception:
-        # Suppress provider exception context in standard traceback rendering.
-        raise CalendarGateError("Italy OTP mailbox read failed") from None
-
-    try:
-        return parse_otp_body(body)
-    except ItaProtocolError as exc:
-        raise CalendarGateError(
-            f"Italy OTP mail rejected ({exc.code})"
-        ) from None
-
-
-__all__ = ["fetch_otp_from_cloud", "utc_sent_at", "validate_cloud_otp_environment", "validate_cloud_otp_logging"]

File diff suppressed because it is too large
+ 4759 - 0
plugins/ita_plugin.py


+ 0 - 1168
plugins/ita_protocol.py

@@ -1,1168 +0,0 @@
-"""Pure Prenot@Mi protocol parsing and precommit validation.
-
-This module is the functional core of the Italy plugin.  It deliberately owns
-no browser, network, session, OTP, or form-submission behavior.  Callers pass
-already-captured, sanitized data in and receive immutable value objects back.
-"""
-
-from __future__ import annotations
-
-import json
-import html
-import re
-from dataclasses import dataclass, field
-from datetime import date, datetime, time
-from enum import Enum
-from typing import Any, Mapping, Sequence
-
-
-MAX_PROTOCOL_ITEMS = 512
-MAX_PROTOCOL_PAYLOAD_CHARS = 1_000_000
-MAX_LOOKAHEAD_MONTHS = 120
-_SITE_DATE_PATTERN = re.compile(r"^\d{2}/\d{2}/\d{4} 00:00:00$")
-PRENOTAMI_OTP_SENDER = "noreply-prenotami@esteri.it"
-_EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
-_OTP_CONTEXT_PATTERN = re.compile(
-    r"(?<!\w)OTP\s+Code\s*:\s*([0-9]{6})(?!\w)",
-    re.IGNORECASE,
-)
-
-
-class ItaProtocolError(ValueError):
-    """Fail-closed protocol error with a stable, non-sensitive category."""
-
-    def __init__(self, code: str, message: str, *, path: str = "") -> None:
-        self.code = code
-        self.path = path
-        location = f" at {path}" if path else ""
-        super().__init__(f"Italy protocol error [{code}]{location}: {message}")
-
-
-class ItaCapability(str, Enum):
-    SERVICES_PROBE_ONLY = "services_probe_only"
-    SINGLE_SCHENGEN_TOURISM = "single_schengen_tourism"
-
-
-class InventoryState(str, Enum):
-    AVAILABLE = "available"
-    UNAVAILABLE = "unavailable"
-
-
-@dataclass(frozen=True, slots=True)
-class CalendarScanConfig:
-    lookahead_months: int
-
-
-@dataclass(frozen=True, slots=True)
-class FormControlConfig:
-    control_id: str
-    value: str
-    labels: tuple[str, ...]
-
-
-@dataclass(frozen=True, slots=True)
-class OtpMailConfig:
-    """Allowlisted cloud-mail query settings for one Italy route.
-
-    The authorization mailbox is configured explicitly or derived per call
-    from the current account, never cached on a shared route or included in
-    diagnostic objects or log messages. The sender is
-    fixed to Prenot@Mi's observed official address; a route may not widen the
-    allowlist through configuration.
-    """
-
-    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) -> None:
-        if self.authorization_source not in ("configured", "account"):
-            raise ItaProtocolError(
-                "otp_authorization_source_invalid",
-                "authorization source must be configured or account",
-                path="mail.authorization_source",
-            )
-        if self.authorization_source == "account":
-            if self.authorization_email is not None:
-                raise ItaProtocolError(
-                    "otp_authorization_source_conflict",
-                    "account source cannot also specify a fixed authorization mailbox",
-                    path="mail.authorization_email",
-                )
-        else:
-            object.__setattr__(self, "authorization_email", self._require_mailbox(self.authorization_email))
-        for field_name, expected in (("subject_keywords", "OTP Code"), ("body_keywords", "OTP Code:")):
-            value = getattr(self, field_name)
-            if not isinstance(value, str) or value.strip() != expected:
-                raise ItaProtocolError(
-                    "otp_filter_invalid",
-                    "mail filters must match the observed Prenot@Mi OTP template",
-                    path=f"mail.{field_name}",
-                )
-            object.__setattr__(self, field_name, value.strip())
-        if (
-            not isinstance(self.expiry_seconds, int)
-            or isinstance(self.expiry_seconds, bool)
-            or not 1 <= self.expiry_seconds <= 300
-        ):
-            raise ItaProtocolError(
-                "otp_expiry_invalid",
-                "mail expiry must be an integer between 1 and 300 seconds",
-                path="mail.expiry_seconds",
-            )
-
-    @staticmethod
-    def _require_mailbox(value: Any) -> str:
-        if not isinstance(value, str) or not _EMAIL_PATTERN.fullmatch(value.strip()):
-            raise ItaProtocolError(
-                "otp_authorization_email_invalid",
-                "authorization mailbox must be a valid email address",
-                path="mail.authorization_email",
-            )
-        return value.strip()
-
-    def mailbox_for(self, account_email: str) -> str:
-        """Bind per call; never mutate the route shared by pool instances.
-
-        Account mode requires that each account's own inbox has an existing
-        backend authorization. Configured mode preserves shared/forwarded
-        inbox support; recipient filtering remains bound to the site account.
-        """
-        return self._require_mailbox(
-            account_email if self.authorization_source == "account" else self.authorization_email
-        )
-
-
-@dataclass(frozen=True, slots=True)
-class ItaRouteConfig:
-    routing_key: str
-    service_id: int
-    capability: ItaCapability
-    calendar_scan: CalendarScanConfig | None = None
-    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
-    state: InventoryState
-
-    def __post_init__(self) -> None:
-        _require_date(self.day, "CalendarDay.day")
-        slots_free = _require_int(self.slots_free, "CalendarDay.slots_free")
-        slots_remaining = _require_int(
-            self.slots_remaining,
-            "CalendarDay.slots_remaining",
-        )
-        expected_state = _classify_inventory(
-            slots_free,
-            slots_remaining,
-            path="CalendarDay",
-        )
-        if self.state is not expected_state:
-            raise ItaProtocolError(
-                "inventory_state_mismatch",
-                "declared state differs from the slot counters",
-                path="CalendarDay.state",
-            )
-
-    @property
-    def is_available(self) -> bool:
-        return self.state is InventoryState.AVAILABLE
-
-
-@dataclass(frozen=True, slots=True)
-class SlotCandidate:
-    day: date
-    start_time: time
-    end_time: time
-    slots_free: int
-    slots_remaining: int
-    state: InventoryState
-    daily_calendar_id: str = field(repr=False)
-
-    def __post_init__(self) -> None:
-        _require_date(self.day, "SlotCandidate.day")
-        start = _require_time(self.start_time, "SlotCandidate.start_time")
-        end = _require_time(self.end_time, "SlotCandidate.end_time")
-        if start >= end:
-            raise ItaProtocolError(
-                "time_range_invalid",
-                "slot start time must be earlier than end time",
-                path="SlotCandidate",
-            )
-        slots_free = _require_int(
-            self.slots_free,
-            "SlotCandidate.slots_free",
-        )
-        slots_remaining = _require_int(
-            self.slots_remaining,
-            "SlotCandidate.slots_remaining",
-        )
-        expected_state = _classify_inventory(
-            slots_free,
-            slots_remaining,
-            path="SlotCandidate",
-        )
-        if self.state is not expected_state:
-            raise ItaProtocolError(
-                "inventory_state_mismatch",
-                "declared state differs from the slot counters",
-                path="SlotCandidate.state",
-            )
-        if (
-            not isinstance(self.daily_calendar_id, str)
-            or not self.daily_calendar_id.isdigit()
-            or int(self.daily_calendar_id) <= 0
-        ):
-            raise ItaProtocolError(
-                "daily_id_invalid",
-                "runtime daily identifier must be a positive integer string",
-                path="SlotCandidate.daily_calendar_id",
-            )
-
-    @property
-    def is_available(self) -> bool:
-        return self.state is InventoryState.AVAILABLE
-
-    @property
-    def time_label(self) -> str:
-        return (
-            f"{self.start_time.strftime('%H:%M')} - "
-            f"{self.end_time.strftime('%H:%M')}"
-        )
-
-
-@dataclass(frozen=True, slots=True)
-class DateSelectionState:
-    planned_day: date
-    matching_availability_count: int
-    timeline_selected_days: tuple[date, ...]
-    content_selected_days: tuple[date, ...]
-    day_disabled: bool
-    day_not_available: bool
-    day_has_positive_state: bool
-
-    def __post_init__(self) -> None:
-        _require_date(self.planned_day, "DateSelectionState.planned_day")
-        _require_nonnegative_int(
-            self.matching_availability_count,
-            "DateSelectionState.matching_availability_count",
-        )
-        _require_date_tuple(
-            self.timeline_selected_days,
-            "DateSelectionState.timeline_selected_days",
-        )
-        _require_date_tuple(
-            self.content_selected_days,
-            "DateSelectionState.content_selected_days",
-        )
-        for field_name in (
-            "day_disabled",
-            "day_not_available",
-            "day_has_positive_state",
-        ):
-            _require_bool(
-                getattr(self, field_name),
-                f"DateSelectionState.{field_name}",
-            )
-
-
-@dataclass(frozen=True, slots=True)
-class SlotSelectionState:
-    active_slot_count: int
-    active_is_candidate: bool
-    active_has_unavailable_class: bool
-    active_has_red_dot: bool
-    active_hidden_input_count: int
-    active_daily_id_matches_candidate: bool
-    active_day_matches_candidate: bool
-    active_time_matches_candidate: bool
-    active_capacity_matches_candidate: bool
-
-    def __post_init__(self) -> None:
-        for field_name in (
-            "active_slot_count",
-            "active_hidden_input_count",
-        ):
-            _require_nonnegative_int(
-                getattr(self, field_name),
-                f"SlotSelectionState.{field_name}",
-            )
-        for field_name in (
-            "active_is_candidate",
-            "active_has_unavailable_class",
-            "active_has_red_dot",
-            "active_daily_id_matches_candidate",
-            "active_day_matches_candidate",
-            "active_time_matches_candidate",
-            "active_capacity_matches_candidate",
-        ):
-            _require_bool(
-                getattr(self, field_name),
-                f"SlotSelectionState.{field_name}",
-            )
-
-
-@dataclass(frozen=True, slots=True)
-class PrecommitApproval:
-    """Immutable value returned by :func:`approve_precommit`."""
-
-    calendar_day: CalendarDay
-    candidate: SlotCandidate
-
-
-def resolve_route_config(
-    apt_configs: Mapping[str, Any],
-    routing_key: str,
-) -> ItaRouteConfig:
-    """Resolve one VFS/BLS-style ``apt_configs[routing_key]`` entry."""
-
-    configs = _require_mapping(apt_configs, "apt_configs")
-    key = _require_nonempty_string(routing_key, "routing_key")
-    if key not in configs:
-        raise ItaProtocolError(
-            "route_missing",
-            "no route is configured for the requested routing key",
-            path="apt_configs",
-        )
-
-    raw_route = _require_mapping(configs[key], f"apt_configs.{key}")
-    service_id = _require_positive_int(
-        raw_route.get("service_id"),
-        f"apt_configs.{key}.service_id",
-    )
-
-    raw_capability = _require_nonempty_string(
-        raw_route.get("capability"),
-        f"apt_configs.{key}.capability",
-    )
-    try:
-        capability = ItaCapability(raw_capability)
-    except ValueError as exc:
-        raise ItaProtocolError(
-            "capability_unsupported",
-            "route capability is not supported",
-            path=f"apt_configs.{key}.capability",
-        ) from exc
-
-    if capability is ItaCapability.SERVICES_PROBE_ONLY:
-        return ItaRouteConfig(
-            routing_key=key,
-            service_id=service_id,
-            capability=capability,
-        )
-
-    calendar_scan_raw = _require_mapping(
-        raw_route.get("calendar_scan"),
-        f"apt_configs.{key}.calendar_scan",
-    )
-    calendar_scan = CalendarScanConfig(
-        lookahead_months=_require_lookahead_months(
-            calendar_scan_raw.get("lookahead_months"),
-            f"apt_configs.{key}.calendar_scan.lookahead_months",
-        )
-    )
-
-    form_raw = _require_mapping(
-        raw_route.get("form"),
-        f"apt_configs.{key}.form",
-    )
-    booking_type = _parse_form_control(
-        form_raw,
-        prefix="booking_type",
-        path=f"apt_configs.{key}.form",
-    )
-    purpose = _parse_form_control(
-        form_raw,
-        prefix="purpose",
-        path=f"apt_configs.{key}.form",
-    )
-    mail = _parse_mail_config(
-        raw_route.get("mail"),
-        path=f"apt_configs.{key}.mail",
-    )
-
-    return ItaRouteConfig(
-        routing_key=key,
-        service_id=service_id,
-        capability=capability,
-        calendar_scan=calendar_scan,
-        booking_type=booking_type,
-        purpose=purpose,
-        mail=mail,
-    )
-
-
-def decode_double_json_array(
-    payload: str,
-    *,
-    max_items: int = MAX_PROTOCOL_ITEMS,
-) -> tuple[Mapping[str, Any], ...]:
-    """Strictly decode the JSON-string-containing-a-JSON-array wire shape."""
-
-    if not isinstance(payload, str) or not payload:
-        raise ItaProtocolError(
-            "payload_type",
-            "payload must be a non-empty JSON string",
-        )
-    if len(payload) > MAX_PROTOCOL_PAYLOAD_CHARS:
-        raise ItaProtocolError(
-            "payload_too_large",
-            "payload exceeds the local parsing limit",
-        )
-    if not _is_positive_int(max_items):
-        raise ItaProtocolError(
-            "max_items_invalid",
-            "max_items must be a positive integer",
-        )
-
-    try:
-        outer = json.loads(payload)
-    except (TypeError, json.JSONDecodeError) as exc:
-        raise ItaProtocolError(
-            "outer_json_invalid",
-            "outer JSON cannot be decoded",
-        ) from exc
-    if not isinstance(outer, str):
-        raise ItaProtocolError(
-            "payload_layer_count",
-            "payload must contain exactly two JSON layers",
-        )
-    if len(outer) > MAX_PROTOCOL_PAYLOAD_CHARS:
-        raise ItaProtocolError(
-            "payload_too_large",
-            "inner payload exceeds the local parsing limit",
-        )
-
-    try:
-        items = json.loads(outer)
-    except (TypeError, json.JSONDecodeError) as exc:
-        raise ItaProtocolError(
-            "inner_json_invalid",
-            "inner JSON cannot be decoded",
-        ) from exc
-    if not isinstance(items, list):
-        raise ItaProtocolError(
-            "payload_layer_count",
-            "inner JSON must be an array",
-        )
-    if len(items) > max_items:
-        raise ItaProtocolError(
-            "item_limit_exceeded",
-            "response contains more items than the configured parsing limit",
-        )
-
-    result: list[Mapping[str, Any]] = []
-    for index, item in enumerate(items):
-        if not isinstance(item, Mapping):
-            raise ItaProtocolError(
-                "item_type",
-                "every response item must be an object",
-                path=f"items[{index}]",
-            )
-        result.append(item)
-    return tuple(result)
-
-
-def parse_calendar_availability(
-    payload: str,
-    *,
-    max_items: int = MAX_PROTOCOL_ITEMS,
-) -> tuple[CalendarDay, ...]:
-    """Parse and classify calendar-day capacity without guessing conflicts."""
-
-    items = decode_double_json_array(payload, max_items=max_items)
-    days: list[CalendarDay] = []
-    seen_days: set[date] = set()
-
-    for index, item in enumerate(items):
-        path = f"availability[{index}]"
-        parsed_day = _parse_site_date(
-            _require_key(item, "DateLibere", path),
-            f"{path}.DateLibere",
-        )
-        if parsed_day in seen_days:
-            raise ItaProtocolError(
-                "duplicate_calendar_day",
-                "calendar response contains a duplicate date",
-                path=path,
-            )
-        seen_days.add(parsed_day)
-
-        slots_free = _require_int(
-            _require_key(item, "SlotLiberi", path),
-            f"{path}.SlotLiberi",
-        )
-        slots_remaining = _require_int(
-            _require_key(item, "SlotRimanenti", path),
-            f"{path}.SlotRimanenti",
-        )
-        state = _classify_inventory(
-            slots_free,
-            slots_remaining,
-            path=path,
-        )
-        days.append(
-            CalendarDay(
-                day=parsed_day,
-                slots_free=slots_free,
-                slots_remaining=slots_remaining,
-                state=state,
-            )
-        )
-
-    return tuple(sorted(days, key=lambda item: item.day))
-
-
-def parse_time_slots(
-    payload: str,
-    *,
-    max_items: int = MAX_PROTOCOL_ITEMS,
-) -> tuple[SlotCandidate, ...]:
-    """Parse TimeSlots items while keeping the runtime ID memory-only."""
-
-    items = decode_double_json_array(payload, max_items=max_items)
-    candidates: list[SlotCandidate] = []
-    seen_ranges: set[tuple[date, time, time]] = set()
-    seen_daily_ids: set[str] = set()
-
-    for index, item in enumerate(items):
-        path = f"time_slots[{index}]"
-        parsed_day = _parse_site_date(
-            _require_key(item, "Data", path),
-            f"{path}.Data",
-        )
-        start_time = _parse_site_time(
-            _require_key(item, "OrarioInizioFascia", path),
-            f"{path}.OrarioInizioFascia",
-        )
-        end_time = _parse_site_time(
-            _require_key(item, "OrarioFineFascia", path),
-            f"{path}.OrarioFineFascia",
-        )
-        if start_time >= end_time:
-            raise ItaProtocolError(
-                "time_range_invalid",
-                "slot start time must be earlier than end time",
-                path=path,
-            )
-
-        slots_free = _require_int(
-            _require_key(item, "SlotLiberi", path),
-            f"{path}.SlotLiberi",
-        )
-        slots_remaining = _require_int(
-            _require_key(item, "SlotRimanenti", path),
-            f"{path}.SlotRimanenti",
-        )
-        state = _classify_inventory(
-            slots_free,
-            slots_remaining,
-            path=path,
-        )
-
-        daily_id = str(
-            _require_positive_int(
-                _require_key(item, "IDCalendarioServizioGiornaliero", path),
-                f"{path}.IDCalendarioServizioGiornaliero",
-            )
-        )
-        time_range = (parsed_day, start_time, end_time)
-        if time_range in seen_ranges:
-            raise ItaProtocolError(
-                "duplicate_time_range",
-                "time-slot response contains a duplicate time range",
-                path=path,
-            )
-        if daily_id in seen_daily_ids:
-            raise ItaProtocolError(
-                "duplicate_daily_id",
-                "time-slot response reuses a runtime daily identifier",
-                path=path,
-            )
-        seen_ranges.add(time_range)
-        seen_daily_ids.add(daily_id)
-
-        candidates.append(
-            SlotCandidate(
-                day=parsed_day,
-                start_time=start_time,
-                end_time=end_time,
-                slots_free=slots_free,
-                slots_remaining=slots_remaining,
-                state=state,
-                daily_calendar_id=daily_id,
-            )
-        )
-
-    return tuple(
-        sorted(
-            candidates,
-            key=lambda item: (item.day, item.start_time, item.end_time),
-        )
-    )
-
-
-def available_calendar_days(
-    days: Sequence[CalendarDay],
-    *,
-    start_day: date | None = None,
-    end_day: date | None = None,
-) -> tuple[CalendarDay, ...]:
-    """Return positive days in an inclusive date range, sorted ascending."""
-
-    start, end = _validate_date_range(start_day, end_day)
-    seen: set[date] = set()
-    selected: list[CalendarDay] = []
-    for index, item in enumerate(days):
-        if not isinstance(item, CalendarDay):
-            raise ItaProtocolError(
-                "calendar_day_type",
-                "days must contain CalendarDay values",
-                path=f"days[{index}]",
-            )
-        if item.day in seen:
-            raise ItaProtocolError(
-                "duplicate_calendar_day",
-                "days contain a duplicate date",
-                path=f"days[{index}]",
-            )
-        seen.add(item.day)
-        if item.is_available and _date_in_range(item.day, start, end):
-            selected.append(item)
-    return tuple(sorted(selected, key=lambda item: item.day))
-
-
-def available_slot_candidates(
-    candidates: Sequence[SlotCandidate],
-    *,
-    start_day: date | None = None,
-    end_day: date | None = None,
-) -> tuple[SlotCandidate, ...]:
-    """Filter and deterministically order positive Book-side candidates."""
-
-    start, end = _validate_date_range(start_day, end_day)
-    seen_ranges: set[tuple[date, time, time]] = set()
-    selected: list[SlotCandidate] = []
-    for index, item in enumerate(candidates):
-        if not isinstance(item, SlotCandidate):
-            raise ItaProtocolError(
-                "slot_candidate_type",
-                "candidates must contain SlotCandidate values",
-                path=f"candidates[{index}]",
-            )
-        identity = (item.day, item.start_time, item.end_time)
-        if identity in seen_ranges:
-            raise ItaProtocolError(
-                "duplicate_time_range",
-                "candidates contain a duplicate time range",
-                path=f"candidates[{index}]",
-            )
-        seen_ranges.add(identity)
-        if item.is_available and _date_in_range(item.day, start, end):
-            selected.append(item)
-
-    return tuple(
-        sorted(
-            selected,
-            key=lambda item: (
-                item.day,
-                -item.slots_free,
-                item.start_time,
-                item.end_time,
-            ),
-        )
-    )
-
-
-def parse_otp_body(
-    body: str,
-    *,
-    max_chars: int = MAX_PROTOCOL_PAYLOAD_CHARS,
-) -> str:
-    """Extract exactly one Prenot@Mi OTP from a cloud-mail body.
-
-    The cloud endpoint returns a body-only string and may include both the
-    plain-text and HTML MIME alternatives.  HTML tags are replaced with
-    spaces, then only the observed ``OTP Code:`` marker followed by six ASCII
-    digits is accepted.  Repeated identical matches (plain + HTML) are fine;
-    different candidates fail closed.  No caller should log ``body`` or the
-    returned code.
-    """
-
-    if not isinstance(body, str) or not body.strip():
-        raise ItaProtocolError(
-            "otp_body_invalid",
-            "OTP mail body must be a non-empty string",
-            path="mail.body",
-        )
-    if not isinstance(max_chars, int) or isinstance(max_chars, bool) or max_chars <= 0:
-        raise ItaProtocolError(
-            "otp_body_limit_invalid",
-            "OTP body limit must be a positive integer",
-            path="mail.max_chars",
-        )
-    if len(body) > max_chars:
-        raise ItaProtocolError(
-            "otp_body_too_large",
-            "OTP mail body exceeds the local parsing limit",
-            path="mail.body",
-        )
-
-    # The existing cloud service can concatenate text/plain and text/html.
-    # Projecting HTML to text avoids depending on a browser or executing any
-    # markup while preserving the marker when tags surround the code.
-    projected = html.unescape(re.sub(r"<[^>]{0,4096}>", " ", body))
-    projected = re.sub(r"\s+", " ", projected).strip()
-    matches = _OTP_CONTEXT_PATTERN.findall(projected)
-    unique = tuple(dict.fromkeys(matches))
-    if not unique:
-        raise ItaProtocolError(
-            "otp_not_found",
-            "mail body did not contain the expected OTP marker",
-            path="mail.body",
-        )
-    if len(unique) != 1:
-        raise ItaProtocolError(
-            "otp_ambiguous",
-            "mail body contained multiple different OTP candidates",
-            path="mail.body",
-        )
-    return unique[0]
-
-
-def month_starts(anchor_day: date, lookahead_months: int) -> tuple[date, ...]:
-    """Return deterministic month starts for the configured scan window."""
-
-    anchor = _require_date(anchor_day, "anchor_day")
-    months = _require_lookahead_months(lookahead_months, "lookahead_months")
-    result: list[date] = []
-    year = anchor.year
-    month = anchor.month
-    for _ in range(months):
-        result.append(date(year, month, 1))
-        month += 1
-        if month == 13:
-            year += 1
-            month = 1
-    return tuple(result)
-
-
-def approve_precommit(
-    calendar_day: CalendarDay,
-    candidate: SlotCandidate,
-    date_state: DateSelectionState,
-    slot_state: SlotSelectionState,
-) -> PrecommitApproval:
-    """Approve final-button readiness only when every observed invariant holds."""
-
-    if not isinstance(calendar_day, CalendarDay):
-        raise ItaProtocolError(
-            "precommit_type",
-            "calendar_day must be a CalendarDay",
-        )
-    if not isinstance(candidate, SlotCandidate):
-        raise ItaProtocolError(
-            "precommit_type",
-            "candidate must be a SlotCandidate",
-        )
-    if not isinstance(date_state, DateSelectionState):
-        raise ItaProtocolError(
-            "precommit_type",
-            "date_state must be a DateSelectionState",
-        )
-    if not isinstance(slot_state, SlotSelectionState):
-        raise ItaProtocolError(
-            "precommit_type",
-            "slot_state must be a SlotSelectionState",
-        )
-
-    checks = (
-        (calendar_day.is_available, "calendar day is not positively available"),
-        (candidate.is_available, "slot candidate is not positively available"),
-        (calendar_day.day == candidate.day, "calendar and slot dates differ"),
-        (
-            date_state.planned_day == candidate.day,
-            "selected date differs from the planned date",
-        ),
-        (
-            date_state.matching_availability_count == 1,
-            "planned date must map to exactly one availability item",
-        ),
-        (
-            date_state.timeline_selected_days == (candidate.day,),
-            "timeline must have exactly one matching selected date",
-        ),
-        (
-            date_state.content_selected_days == (candidate.day,),
-            "content must have exactly one matching selected date",
-        ),
-        (not date_state.day_disabled, "selected date is disabled"),
-        (
-            not date_state.day_not_available,
-            "selected date has a negative availability marker",
-        ),
-        (
-            date_state.day_has_positive_state,
-            "selected date lacks the verified positive state",
-        ),
-        (
-            slot_state.active_slot_count == 1,
-            "there must be exactly one active slot",
-        ),
-        (
-            slot_state.active_is_candidate,
-            "active slot is not the approved candidate",
-        ),
-        (
-            not slot_state.active_has_unavailable_class,
-            "active slot has an unavailable class",
-        ),
-        (
-            not slot_state.active_has_red_dot,
-            "active slot has a negative red marker",
-        ),
-        (
-            slot_state.active_hidden_input_count == 1,
-            "active slot must contain exactly one runtime identifier input",
-        ),
-        (
-            slot_state.active_daily_id_matches_candidate,
-            "active slot runtime identifier differs from the candidate",
-        ),
-        (
-            slot_state.active_day_matches_candidate,
-            "active slot date differs from the candidate",
-        ),
-        (
-            slot_state.active_time_matches_candidate,
-            "active slot time differs from the candidate",
-        ),
-        (
-            slot_state.active_capacity_matches_candidate,
-            "active slot capacity differs from the candidate",
-        ),
-    )
-    for passed, message in checks:
-        if not passed:
-            raise ItaProtocolError("precommit_rejected", message)
-
-    return PrecommitApproval(calendar_day=calendar_day, candidate=candidate)
-
-
-def _parse_form_control(
-    form: Mapping[str, Any],
-    *,
-    prefix: str,
-    path: str,
-) -> FormControlConfig:
-    return FormControlConfig(
-        control_id=_require_nonempty_string(
-            form.get(f"{prefix}_control_id"),
-            f"{path}.{prefix}_control_id",
-        ),
-        value=_require_nonempty_string(
-            form.get(f"{prefix}_value"),
-            f"{path}.{prefix}_value",
-        ),
-        labels=_require_string_tuple(
-            form.get(f"{prefix}_labels"),
-            f"{path}.{prefix}_labels",
-        ),
-    )
-
-
-def _parse_mail_config(
-    raw_mail: Any,
-    *,
-    path: str,
-) -> OtpMailConfig | None:
-    if raw_mail is None:
-        return None
-    mail = _require_mapping(raw_mail, path)
-    sender = mail.get("sender", PRENOTAMI_OTP_SENDER)
-    if not isinstance(sender, str) or sender.strip().casefold() != PRENOTAMI_OTP_SENDER:
-        raise ItaProtocolError(
-            "otp_sender_not_allowlisted",
-            "mail sender must match Prenot@Mi's official OTP address",
-            path=f"{path}.sender",
-        )
-    return OtpMailConfig(
-        authorization_email=mail.get("authorization_email"),
-        subject_keywords=mail.get("subject_keywords", "OTP Code"),
-        body_keywords=mail.get("body_keywords", "OTP Code:"),
-        expiry_seconds=mail.get("expiry_seconds", 300),
-        authorization_source=mail.get("authorization_source", "configured"),
-    )
-
-
-def _classify_inventory(
-    slots_free: int,
-    slots_remaining: int,
-    *,
-    path: str,
-) -> InventoryState:
-    if slots_free > 0 and slots_remaining >= 0:
-        return InventoryState.AVAILABLE
-    if slots_free == 0 and slots_remaining < 0:
-        return InventoryState.UNAVAILABLE
-    raise ItaProtocolError(
-        "inventory_conflict",
-        "slot counters do not match an observed allowlisted state",
-        path=path,
-    )
-
-
-def _parse_site_date(value: Any, path: str) -> date:
-    if not isinstance(value, str) or not _SITE_DATE_PATTERN.fullmatch(value):
-        raise ItaProtocolError(
-            "date_format",
-            "date must match DD/MM/YYYY 00:00:00",
-            path=path,
-        )
-    try:
-        return datetime.strptime(value, "%d/%m/%Y %H:%M:%S").date()
-    except ValueError as exc:
-        raise ItaProtocolError(
-            "date_invalid",
-            "date is not a real calendar date",
-            path=path,
-        ) from exc
-
-
-def _parse_site_time(value: Any, path: str) -> time:
-    mapping = _require_mapping(value, path)
-    hours = _require_int(_require_key(mapping, "Hours", path), f"{path}.Hours")
-    minutes = _require_int(
-        _require_key(mapping, "Minutes", path),
-        f"{path}.Minutes",
-    )
-    seconds = _require_int(mapping.get("Seconds", 0), f"{path}.Seconds")
-    milliseconds = _require_int(
-        mapping.get("Milliseconds", 0),
-        f"{path}.Milliseconds",
-    )
-    if seconds != 0 or milliseconds != 0:
-        raise ItaProtocolError(
-            "time_precision",
-            "sub-minute slot precision is not supported by the observed protocol",
-            path=path,
-        )
-    try:
-        return time(hour=hours, minute=minutes)
-    except ValueError as exc:
-        raise ItaProtocolError(
-            "time_invalid",
-            "slot time is outside the 24-hour clock",
-            path=path,
-        ) from exc
-
-
-def _validate_date_range(
-    start_day: date | None,
-    end_day: date | None,
-) -> tuple[date | None, date | None]:
-    start = _require_date(start_day, "start_day") if start_day is not None else None
-    end = _require_date(end_day, "end_day") if end_day is not None else None
-    if start is not None and end is not None and start > end:
-        raise ItaProtocolError(
-            "date_range_invalid",
-            "start_day must not be later than end_day",
-        )
-    return start, end
-
-
-def _date_in_range(
-    value: date,
-    start_day: date | None,
-    end_day: date | None,
-) -> bool:
-    return (
-        (start_day is None or value >= start_day)
-        and (end_day is None or value <= end_day)
-    )
-
-
-def _require_mapping(value: Any, path: str) -> Mapping[str, Any]:
-    if not isinstance(value, Mapping):
-        raise ItaProtocolError(
-            "mapping_required",
-            "value must be an object",
-            path=path,
-        )
-    return value
-
-
-def _require_key(mapping: Mapping[str, Any], key: str, path: str) -> Any:
-    if key not in mapping:
-        raise ItaProtocolError(
-            "field_missing",
-            "required field is missing",
-            path=f"{path}.{key}",
-        )
-    return mapping[key]
-
-
-def _require_nonempty_string(value: Any, path: str) -> str:
-    if not isinstance(value, str) or not value.strip():
-        raise ItaProtocolError(
-            "string_required",
-            "value must be a non-empty string",
-            path=path,
-        )
-    return value.strip()
-
-
-def _require_string_tuple(value: Any, path: str) -> tuple[str, ...]:
-    if isinstance(value, (str, bytes)) or not isinstance(value, Sequence):
-        raise ItaProtocolError(
-            "labels_required",
-            "labels must be a non-empty array of strings",
-            path=path,
-        )
-    labels = tuple(
-        _require_nonempty_string(item, f"{path}[{index}]")
-        for index, item in enumerate(value)
-    )
-    if not labels:
-        raise ItaProtocolError(
-            "labels_required",
-            "labels must be a non-empty array of strings",
-            path=path,
-        )
-    if len(set(labels)) != len(labels):
-        raise ItaProtocolError(
-            "labels_duplicate",
-            "labels must not contain duplicates",
-            path=path,
-        )
-    return labels
-
-
-def _is_positive_int(value: Any) -> bool:
-    return isinstance(value, int) and not isinstance(value, bool) and value > 0
-
-
-def _require_positive_int(value: Any, path: str) -> int:
-    if not _is_positive_int(value):
-        raise ItaProtocolError(
-            "positive_integer_required",
-            "value must be a positive integer",
-            path=path,
-        )
-    return value
-
-
-def _require_int(value: Any, path: str) -> int:
-    if not isinstance(value, int) or isinstance(value, bool):
-        raise ItaProtocolError(
-            "integer_required",
-            "value must be an integer",
-            path=path,
-        )
-    return value
-
-
-def _require_nonnegative_int(value: Any, path: str) -> int:
-    number = _require_int(value, path)
-    if number < 0:
-        raise ItaProtocolError(
-            "nonnegative_integer_required",
-            "value must be a non-negative integer",
-            path=path,
-        )
-    return number
-
-
-def _require_bool(value: Any, path: str) -> bool:
-    if not isinstance(value, bool):
-        raise ItaProtocolError(
-            "boolean_required",
-            "value must be a boolean",
-            path=path,
-        )
-    return value
-
-
-def _require_lookahead_months(value: Any, path: str) -> int:
-    months = _require_positive_int(value, path)
-    if months > MAX_LOOKAHEAD_MONTHS:
-        raise ItaProtocolError(
-            "lookahead_too_large",
-            "lookahead exceeds the local scan safety limit",
-            path=path,
-        )
-    return months
-
-
-def _require_date(value: Any, path: str) -> date:
-    if not isinstance(value, date) or isinstance(value, datetime):
-        raise ItaProtocolError(
-            "date_required",
-            "value must be a date",
-            path=path,
-        )
-    return value
-
-
-def _require_date_tuple(value: Any, path: str) -> tuple[date, ...]:
-    if not isinstance(value, tuple):
-        raise ItaProtocolError(
-            "date_tuple_required",
-            "value must be a tuple of dates",
-            path=path,
-        )
-    for index, item in enumerate(value):
-        _require_date(item, f"{path}[{index}]")
-    return value
-
-
-def _require_time(value: Any, path: str) -> time:
-    if not isinstance(value, time):
-        raise ItaProtocolError(
-            "time_required",
-            "value must be a time",
-            path=path,
-        )
-    if value.second != 0 or value.microsecond != 0:
-        raise ItaProtocolError(
-            "time_precision",
-            "slot time must use minute precision",
-            path=path,
-        )
-    return value
-
-
-__all__ = [
-    "CalendarDay",
-    "CalendarScanConfig",
-    "DateSelectionState",
-    "FormControlConfig",
-    "InventoryState",
-    "ItaCapability",
-    "ItaProtocolError",
-    "ItaRouteConfig",
-    "MAX_LOOKAHEAD_MONTHS",
-    "MAX_PROTOCOL_ITEMS",
-    "OtpMailConfig",
-    "PrecommitApproval",
-    "PRENOTAMI_OTP_SENDER",
-    "SlotCandidate",
-    "SlotSelectionState",
-    "approve_precommit",
-    "available_calendar_days",
-    "available_slot_candidates",
-    "decode_double_json_array",
-    "month_starts",
-    "parse_calendar_availability",
-    "parse_otp_body",
-    "parse_time_slots",
-    "resolve_route_config",
-]

+ 0 - 464
plugins/ita_reservation.py

@@ -1,464 +0,0 @@
-"""Read-only Prenot@Mi receipt adapter, not a final-submit read port.
-
-These objects contain observed display facts, not an inferred service/account
-binding or proof linking an assigned appointment time to a selected slot.
-Only observed Italian cancelled/confirmed states are classified; others stay UNKNOWN.
-No navigation, credentials, OTP, form writes or final actions live here.
-"""
-
-from __future__ import annotations
-
-import math
-import re
-import time
-from dataclasses import dataclass, field
-from datetime import date
-
-from plugins.ita_booking_final import ReservationState
-from plugins.ita_calendar_query import same_origin_path
-from plugins.ita_protocol import MAX_PROTOCOL_ITEMS
-
-
-LIST_PATH = "/Reservation"
-DETAIL_PREFIX = "/ReservationDetail/Index/"
-HEADERS = ("Codice Prenotazione", "Ufficio", "Servizio", "Data", "Ora", "Stato", "Dati Richiedente")
-DETAIL_LABELS = ("Servizio Consolare", "Servizio Erogato", "Codice Prenotazione",
-                 "Tipo Prenotazione", "Data", "Ora", "Stato")
-MONTHS_IT = ("gennaio", "febbraio", "marzo", "aprile", "maggio", "giugno", "luglio",
-             "agosto", "settembre", "ottobre", "novembre", "dicembre")
-
-
-class ReservationReadError(ValueError):
-    """Only adapter-owned reason codes; never include DOM text or browser errors."""
-
-    def __init__(self, reason: str):
-        self.reason = reason
-        super().__init__(f"Italy reservation read rejected: {reason}")
-
-
-@dataclass(frozen=True, slots=True, repr=False)
-class ReservationDetail:
-    reference: str
-    office: str
-    service_name: str
-    booking_type: str
-    day: date
-    appointment_time: str
-    status_text: str
-    status_code: str
-    state: ReservationState
-
-
-@dataclass(frozen=True, slots=True, repr=False)
-class ReservationListRow:
-    reference: str
-    detail_url: str
-    office: str
-    service_name: str
-    day: date
-    appointment_time: str
-    status_text: str
-    state: ReservationState
-
-
-@dataclass(frozen=True, slots=True)
-class ReservationListing:
-    """Coverage of the loaded client data, NOT a fresh account-bound snapshot."""
-
-    rows: tuple[ReservationListRow, ...] = field(repr=False)
-    page_count: int
-    waitlist_count: int = 0
-
-
-_CONTEXT_JS = r"""
-const clean = s => String(s || '').replace(/\s+/g, ' ').trim();
-const fail = reason => ({error: reason});
-if (window.location.origin !== 'https://prenotami.esteri.it') return fail('wrong_page');
-if (document.readyState !== 'complete') return fail('not_ready');
-if (!document.querySelector('.app-menu')) return fail('authentication_missing');
-"""
-
-DETAIL_READ_SCRIPT = _CONTEXT_JS + r"""
-/* coordinate:ita-reservation-detail-readonly */
-if (!/^\/ReservationDetail\/Index\/[^/]+$/.test(window.location.pathname)) return fail('wrong_page');
-const headings = Array.from(document.querySelectorAll('h4'));
-const booking = headings.filter(e => clean(e.textContent) === 'Dati Prenotazione');
-const applicant = headings.filter(e => clean(e.textContent) === 'Dati Richiedente');
-if (booking.length !== 1 || applicant.length !== 1) return fail('section_ambiguous');
-const root = booking[0].parentElement;
-if (!root || !root.classList.contains('my-col-6') || root.contains(applicant[0])) return fail('unsafe_scope');
-const nameOf = e => clean(e.textContent).match(
-  /^\*?\s*(Servizio Consolare|Servizio Erogato|Codice Prenotazione|Tipo Prenotazione|Data|Ora|Stato)\s*:\s*$/)?.[1];
-const labels = Array.from(root.querySelectorAll('label')).filter(nameOf);
-if (labels.length !== 7 || new Set(labels.map(nameOf)).size !== 7) return fail('fields_ambiguous');
-const fields = {};
-for (const label of labels) {
-  const row = label.parentElement;
-  if (labels.filter(e => row.contains(e)).length !== 1) return fail('row_ambiguous');
-  const values = [];
-  for (const node of row.childNodes) {
-    if (node === label || node.nodeType === 8) continue;
-    // The observed values are text siblings or one b. Do not read nested
-    // forms, print payloads, applicant sections or arbitrary HTML as values.
-    if (node.nodeType !== 3 && !(node.nodeType === 1 && node.tagName === 'B' && node.children.length === 0))
-      return fail('value_structure_changed');
-    const value = clean(node.textContent);
-    if (value) values.push(value);
-  }
-  if (values.length !== 1 || values[0].length > 256) return fail('value_ambiguous');
-  fields[nameOf(label)] = values[0];
-}
-const codes = document.querySelectorAll('input#IDTipoStatoPrenotazione');
-if (codes.length !== 1 || codes[0].type !== 'hidden' || codes[0].name !== 'IDTipoStatoPrenotazione')
-  return fail('status_control_ambiguous');
-return {path: window.location.pathname, fields, statusCode: clean(codes[0].value)};
-"""
-
-LIST_READ_SCRIPT = _CONTEXT_JS + r"""
-/* coordinate:ita-reservation-list-readonly */
-if (window.location.pathname !== '/Reservation') return fail('wrong_page');
-const readDateCell = cell => {
-  // Observed shape: optional hidden element(s), one non-empty text sibling.
-  // Do not use the whole cell's textContent (includes hidden metadata), nor
-  // innerText (unrendered DataTables pages can fall back to textContent).
-  const nodes = Array.from(cell.childNodes), values = [];
-  if (nodes.length > 16) return null;
-  for (const node of nodes) {
-    if (node.nodeType === 8) continue;
-    if (node.nodeType === 3) {
-      const value = clean(node.textContent);
-      if (value) values.push(value);
-      continue;
-    }
-    if (node.nodeType !== 1) return null;
-    const style = window.getComputedStyle(node);
-    // Own inline/hidden markers remain checkable for detached client rows.
-    // visibility:hidden only proves a leaf hidden: descendants can override it.
-    const hidden = node.hidden === true || node.style.display === 'none' || style.display === 'none';
-    const hiddenLeaf = node.children.length === 0 &&
-      (node.style.visibility === 'hidden' || style.visibility === 'hidden');
-    if (!hidden && !hiddenLeaf) return null;
-    // Hidden metadata is excluded structurally; never parse or log its value.
-  }
-  return values.length === 1 ? values[0] : null;
-};
-const $ = window.jQuery;
-const ids = ['dataTableReservations', 'dataTableReservationsWL'];
-const tables = [];
-for (const id of ids) {
-  const matches = document.querySelectorAll('#' + id);
-  if (matches.length !== 1) return fail('table_ambiguous');
-  const table = matches[0];
-  const headers = Array.from(table.querySelectorAll('thead th')).map(e => clean(e.textContent));
-  if (!$?.fn?.dataTable?.isDataTable(table)) {
-    const empty = table.querySelectorAll('tbody tr').length === 0 && headers.length === 0 &&
-      !table.classList.contains('dataTable') && !table.closest('.dataTables_wrapper');
-    if (id !== ids[1] || !empty) return fail('not_ready');
-    tables.push({id, structuralEmpty: true});
-    continue;
-  }
-  // This getter is only used after isDataTable: it must never initialize a table.
-  const api = $(table).DataTable(), pageInfo = api.page.info();
-  const info = Object.fromEntries(['page', 'pages', 'start', 'end', 'length',
-    'recordsTotal', 'recordsDisplay', 'serverSide'].map(k => [k, pageInfo[k]]));
-  const count = api.rows().count();
-  if (!Number.isInteger(count) || count < 0 || count > 512) return fail('row_limit');
-  if (info.serverSide !== false || api.search() || api.columns().search().toArray().some(Boolean) ||
-      count !== info.recordsTotal || count !== info.recordsDisplay || api.rows({search: 'applied'}).count() !== count)
-    return fail('coverage_incomplete');
-  if (id === ids[1]) {
-    if (count !== 0) return fail('waitlist_schema_unverified');
-    tables.push({id, structuralEmpty: false, count, info});
-    continue;
-  }
-  const expected = ['Codice Prenotazione', 'Ufficio', 'Servizio', 'Data', 'Ora', 'Stato', 'Dati Richiedente'];
-  if (![7, 8].includes(headers.length) || expected.some((h, i) => headers[i] !== h) ||
-      (headers.length === 8 && headers[7] !== '')) return fail('headers_changed');
-  const nodes = api.rows().nodes().toArray();
-  if (nodes.length !== count) return fail('row_nodes_incomplete');
-  const rows = [];
-  for (const node of nodes) {
-    const cells = Array.from(node.children);
-    if (cells.length !== headers.length || cells.some(c => c.tagName !== 'TD')) return fail('cells_changed');
-    const links = cells[0].querySelectorAll('a[href]');
-    if (links.length !== 1) return fail('detail_link_ambiguous');
-    const date = readDateCell(cells[3]);
-    if (date === null) return fail('date_cell_structure_changed');
-    const row = {reference: clean(cells[0].textContent), detailUrl: links[0].href,
-      office: clean(cells[1].textContent), service: clean(cells[2].textContent),
-      date, time: clean(cells[4].textContent), status: clean(cells[5].textContent)};
-    if (Object.values(row).some(v => typeof v !== 'string' || !v || v.length > 256)) return fail('field_invalid');
-    rows.push(row);
-    // Do not access applicant cell 6 or unnamed cell 7.
-  }
-  tables.push({id, structuralEmpty: false, headers, count, info, rows});
-}
-return {path: window.location.pathname, tables};
-"""
-
-
-DATE_DIAGNOSTIC_SCRIPT = _CONTEXT_JS + r"""
-/* coordinate:ita-reservation-date-diagnostic-readonly */
-if (window.location.pathname !== '/Reservation') return fail('wrong_page');
-const tables = document.querySelectorAll('#dataTableReservations');
-if (tables.length !== 1) return fail('table_ambiguous');
-const table = tables[0], $ = window.jQuery;
-const headers = Array.from(table.querySelectorAll('thead th')).map(e => clean(e.textContent));
-const expected = ['Codice Prenotazione', 'Ufficio', 'Servizio', 'Data', 'Ora', 'Stato', 'Dati Richiedente'];
-if (![7,8].includes(headers.length) || expected.some((v,i) => headers[i] !== v) ||
-    (headers.length === 8 && headers[7] !== '') || !$?.fn?.dataTable?.isDataTable(table))
-    return fail('headers_changed');
-const nodes = $(table).DataTable().rows().nodes().toArray();
-if (nodes.length > 512) return fail('row_limit');
-const samples = [];
-for (const row of nodes.slice(0,3)) {
-  const cells = Array.from(row.children);
-  if (cells.length !== headers.length || cells.some(c => c.tagName !== 'TD')) return fail('cells_changed');
-  // Only the verified Data column. No reference, account, applicant, HTML or attributes.
-  const cell = cells[3], children = Array.from(cell.childNodes);
-  const text = clean(cell.textContent), rendered = clean(cell.innerText);
-  if (text.length > 256 || rendered.length > 256) return fail('field_invalid');
-  const parts = children.slice(0,6).map(n => {
-    const style = n.nodeType === 1 ? window.getComputedStyle(n) : null;
-    return {kind: n.nodeType === 3 ? 'text' : (n.nodeType === 1 &&
-      ['SPAN','B','I','BR'].includes(n.tagName) ? n.tagName.toLowerCase() : 'other'),
-      text: clean(n.textContent), hidden: !!style && (style.display === 'none' || style.visibility === 'hidden')};
-  });
-  samples.push({text, rendered, parts, partsTruncated: children.length > 6});
-}
-return {path: window.location.pathname, samples, rowsTruncated: nodes.length > 3};
-"""
-
-
-def _date_shape(value: object) -> dict:
-    """Only structural symbols and known month indexes; never emit raw field text."""
-    if not isinstance(value, str) or len(value) > 256:
-        raise ValueError()
-    normalized = " ".join(value.split())
-    shape = "".join("D" if c.isdecimal() else "L" if c.isalpha() else c if c in " /:.,-" else "?"
-                    for c in normalized[:96])
-    months = [i for i, month in enumerate(MONTHS_IT, 1)
-              if re.search(r"(?<![A-Za-z])" + month + r"(?![A-Za-z])", normalized, re.IGNORECASE)]
-    try:
-        _day(normalized)
-        accepted = True
-    except ReservationReadError:
-        accepted = False
-    return {"shape": shape, "length": len(normalized), "truncated": len(normalized) > 96,
-            "italianMonths": months, "acceptedByCurrentParser": accepted}
-
-
-def read_reservation_date_diagnostic(page: object) -> dict:
-    """One bounded extra read on a failed list parse, not an alternate parser.
-
-    The raw verified date-cell strings stay local; only allowlisted shapes leave
-    this function. A malformed diagnostic cannot leak arbitrary browser output.
-    """
-    try:
-        raw = _read_current(page, DATE_DIAGNOSTIC_SCRIPT, detail=False)
-        if (set(raw) != {"path", "samples", "rowsTruncated"} or
-                type(raw["rowsTruncated"]) is not bool or not isinstance(raw["samples"], list) or
-                len(raw["samples"]) > 3):
-            raise ValueError()
-        samples = []
-        for item in raw["samples"]:
-            if (not isinstance(item, dict) or set(item) != {"text", "rendered", "parts", "partsTruncated"} or
-                    type(item["partsTruncated"]) is not bool or not isinstance(item["parts"], list) or
-                    len(item["parts"]) > 6):
-                raise ValueError()
-            parts = []
-            for part in item["parts"]:
-                if (not isinstance(part, dict) or set(part) != {"kind", "text", "hidden"} or
-                        part["kind"] not in ("text", "span", "b", "i", "br", "other") or
-                        type(part["hidden"]) is not bool):
-                    raise ValueError()
-                parts.append({"kind": part["kind"], "hidden": part["hidden"], **_date_shape(part["text"])})
-            samples.append({"text": _date_shape(item["text"]), "rendered": _date_shape(item["rendered"]),
-                            "textEqualsRendered": item["text"] == item["rendered"],
-                            "parts": parts, "partsTruncated": item["partsTruncated"]})
-        return {"available": True, "samples": samples, "rowsTruncated": raw["rowsTruncated"]}
-    except Exception:
-        return {"available": False}
-
-
-def _text(value: object) -> str:
-    if (not isinstance(value, str) or not 0 < len(value) <= 256 or value != value.strip()
-            or any(ord(c) < 32 or ord(c) == 127 for c in value)):
-        raise ReservationReadError("field_invalid")
-    return value
-
-
-def _day(value: object) -> date:
-    value = _text(value)
-    match = re.fullmatch(r"([0-9]{1,2}) ([A-Za-z]+) ([0-9]{4})", value)
-    if match:
-        try:
-            return date(int(match[3]), MONTHS_IT.index(match[2].casefold()) + 1, int(match[1]))
-        except ValueError:
-            pass
-    raise ReservationReadError("date_unrecognized") from None
-
-
-def _appointment_time(value: object) -> str:
-    value = _text(value)
-    if re.fullmatch(r"(?:[01][0-9]|2[0-3]):[0-5][0-9]", value) is None:
-        raise ReservationReadError("time_unrecognized")
-    return value
-
-
-def _state(text: str, code: str | None = None) -> ReservationState:
-    # A list label is a candidate; a detail must also have its observed code.
-    # Never infer ACTIVE from "not cancelled" or from the numeric code alone.
-    if text.casefold() == "annullata" and code in (None, "3"):
-        return ReservationState.CANCELLED
-    if text.casefold() == "confermata" and code in (None, "2"):
-        return ReservationState.ACTIVE
-    return ReservationState.UNKNOWN
-
-
-def _detail_path(url: object) -> str:
-    try:
-        path, parsed = same_origin_path(url)
-        suffix = path.removeprefix(DETAIL_PREFIX)
-        if (not path.startswith(DETAIL_PREFIX) or not suffix or len(suffix) > 256
-                or any(c in suffix for c in "/\\%") or suffix in {".", ".."}
-                or parsed.query or parsed.fragment):
-            raise ValueError()
-        return path
-    except Exception:
-        raise ReservationReadError("detail_url_invalid") from None
-
-
-def parse_reservation_detail(raw: object) -> ReservationDetail:
-    if not isinstance(raw, dict) or set(raw) != {"path", "fields", "statusCode"}:
-        raise ReservationReadError("detail_schema_changed")
-    _detail_path("https://prenotami.esteri.it" + raw["path"] if isinstance(raw["path"], str) else None)
-    fields = raw["fields"]
-    if not isinstance(fields, dict) or set(fields) != set(DETAIL_LABELS):
-        raise ReservationReadError("fields_ambiguous")
-    values = {key: _text(value) for key, value in fields.items()}
-    code = raw["statusCode"]
-    if not isinstance(code, str) or not re.fullmatch(r"[0-9]{1,4}", code):
-        raise ReservationReadError("status_code_invalid")
-    return ReservationDetail(
-        values["Codice Prenotazione"], values["Servizio Consolare"], values["Servizio Erogato"],
-        values["Tipo Prenotazione"], _day(values["Data"]), _appointment_time(values["Ora"]),
-        values["Stato"], code, _state(values["Stato"], code),
-    )
-
-
-def _coverage(table: dict) -> tuple[int, int]:
-    info, count = table.get("info"), table.get("count")
-    if not isinstance(info, dict) or type(count) is not int or not 0 <= count <= MAX_PROTOCOL_ITEMS:
-        raise ReservationReadError("coverage_invalid")
-    keys = ("recordsTotal", "recordsDisplay", "page", "pages", "start", "end", "length")
-    if any(type(info.get(k)) is not int for k in keys) or info.get("serverSide") is not False:
-        raise ReservationReadError("coverage_invalid")
-    total, displayed, page, pages, start, end, length = (info[k] for k in keys)
-    if total != count or displayed != count or not 0 <= start <= end <= count:
-        raise ReservationReadError("coverage_incomplete")
-    expected_pages = (math.ceil(count / length) if length > 0 else 1) if count else 0
-    if (length not in (-1,) and length <= 0) or pages != expected_pages or not 0 <= page < max(1, pages):
-        raise ReservationReadError("pagination_invalid")
-    if start != (page * length if length > 0 else 0) or end != (min(start + length, count) if length > 0 else count):
-        raise ReservationReadError("pagination_invalid")
-    return count, pages
-
-
-def parse_reservation_listing(raw: object) -> ReservationListing:
-    if not isinstance(raw, dict) or set(raw) != {"path", "tables"} or raw["path"] != LIST_PATH:
-        raise ReservationReadError("list_schema_changed")
-    tables = raw["tables"]
-    if not isinstance(tables, list) or len(tables) != 2 or not all(isinstance(t, dict) for t in tables):
-        raise ReservationReadError("table_ambiguous")
-    main, waitlist = tables
-    if main.get("id") != "dataTableReservations" or waitlist.get("id") != "dataTableReservationsWL":
-        raise ReservationReadError("table_ambiguous")
-    if main.get("structuralEmpty") is not False or main.get("headers") not in (list(HEADERS), [*HEADERS, ""]):
-        raise ReservationReadError("headers_changed")
-    count, pages = _coverage(main)
-    if waitlist.get("structuralEmpty") is True:
-        if set(waitlist) != {"id", "structuralEmpty"}:
-            raise ReservationReadError("waitlist_ambiguous")
-    elif waitlist.get("structuralEmpty") is not False or _coverage(waitlist)[0] != 0:
-        raise ReservationReadError("waitlist_schema_unverified")
-    rows = main.get("rows")
-    if not isinstance(rows, list) or len(rows) != count:
-        raise ReservationReadError("row_nodes_incomplete")
-    result, references, destinations = [], set(), set()
-    for row in rows:
-        if not isinstance(row, dict) or set(row) != {"reference", "detailUrl", "office", "service", "date", "time", "status"}:
-            raise ReservationReadError("row_schema_changed")
-        values = {key: _text(value) for key, value in row.items()}
-        path = _detail_path(values["detailUrl"])
-        if values["reference"] in references or path in destinations:
-            raise ReservationReadError("duplicate_record")
-        references.add(values["reference"])
-        destinations.add(path)
-        result.append(ReservationListRow(values["reference"], values["detailUrl"], values["office"],
-                                        values["service"], _day(values["date"]), _appointment_time(values["time"]),
-                                        values["status"], _state(values["status"])))
-    return ReservationListing(tuple(result), pages)
-
-
-def _read_current(page: object, script: str, *, detail: bool) -> object:
-    try:
-        before_url, before_tab = page.url, page.tab_id
-        path, parsed = same_origin_path(before_url)
-        if parsed.query or parsed.fragment or (not detail and path != LIST_PATH):
-            raise ReservationReadError("wrong_page")
-        if detail:
-            _detail_path(before_url)
-        if not isinstance(before_tab, str) or not before_tab:
-            raise ReservationReadError("context_changed")
-        raw = page.run_js(script)
-        if page.url != before_url or page.tab_id != before_tab:
-            raise ReservationReadError("context_changed")
-        if not isinstance(raw, dict) or raw.get("path") != path:
-            reason = "not_ready" if isinstance(raw, dict) and raw == {"error": "not_ready"} else "page_read_rejected"
-            raise ReservationReadError(reason)
-        return raw
-    except ReservationReadError:
-        raise
-    except Exception:
-        raise ReservationReadError("browser_read_failed") from None
-
-
-def read_reservation_detail(page: object) -> ReservationDetail:
-    """Read the current detail page once. No URL, reference or PII is logged."""
-    return parse_reservation_detail(_read_current(page, DETAIL_READ_SCRIPT, detail=True))
-
-
-def read_reservation_listing(page: object, *, timeout: float = 5, poll_interval: float = 0.25) -> ReservationListing:
-    """Two stable reads within a bound, reusing the existing count tool pattern.
-
-Only not-ready states are polled; unsupported schemas/coverage fail closed.
-This checks the current page and never navigates, draws or clears filters.
-"""
-    if (any(type(v) not in (int, float) or not math.isfinite(v) or v <= 0 for v in (timeout, poll_interval))
-            or poll_interval > timeout or timeout > 60):
-        raise ReservationReadError("wait_config_invalid")
-    try:
-        binding = (page.url, page.tab_id)
-    except Exception:
-        raise ReservationReadError("browser_read_failed") from None
-    deadline, previous = time.monotonic() + timeout, None
-    while time.monotonic() < deadline:
-        try:
-            try:
-                context_matches = (page.url, page.tab_id) == binding
-            except Exception:
-                raise ReservationReadError("browser_read_failed") from None
-            if not context_matches:
-                raise ReservationReadError("context_changed")
-            current = parse_reservation_listing(_read_current(page, LIST_READ_SCRIPT, detail=False))
-        except ReservationReadError as error:
-            if error.reason != "not_ready":
-                raise
-            previous = None
-        else:
-            if current == previous:
-                return current
-            previous = current
-        time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))
-    raise ReservationReadError("stability_timeout")

+ 0 - 66
plugins/ita_turnstile.py

@@ -1,66 +0,0 @@
-"""Bounded Calendar-preparation interaction, composing the existing VFS helper.
-
-This adapter never declares success: Italy's next preflight must observe the
-actual response field AND an enabled AVANTI. No refresh, reset, token injection,
-OTP action, blanket DFS search, or final submission lives here.
-"""
-from __future__ import annotations
-
-import json
-
-from plugins.ita_calendar_query import CalendarGateError
-from plugins.ita_calendar_session import BookingPreflightStage
-from utils.cloudflare_bypass_for_scraping import CloudflareBypasser
-
-
-class ItalyTurnstileRecovery:
-    """One instance per Query/Book preparation; three attempts across stages."""
-
-    MAX_ATTEMPTS = 3
-    INITIAL_DELAY = 5
-    RETRY_INTERVAL = 10
-
-    def __init__(self, page, *, check_current):
-        self.page = page
-        self.check_current = check_current
-        self.attempts = 0
-        self._stage = None
-        self._next_attempt = self.INITIAL_DELAY
-        self._helper = None
-
-    def __call__(self, raw, *, stage, elapsed, remaining):
-        if not isinstance(stage, BookingPreflightStage):
-            raise CalendarGateError("Italy Turnstile interaction stage invalid")
-        if (not isinstance(raw, dict) or raw.get("pathMatches") is not True
-                or raw.get("formPresent") is not True or type(raw.get("turnstileCount")) is not int
-                or raw.get("turnstileCount") != 1):
-            raise CalendarGateError("Italy Turnstile interaction requires the verified booking form")
-        if raw.get("turnstileTokenPresent") is not False:
-            return  # Never touch a verified widget to fix an unrelated button.
-        if self._stage is not stage:
-            self._stage = stage
-            self._next_attempt = self.INITIAL_DELAY
-        if self.attempts >= self.MAX_ATTEMPTS or elapsed < self._next_attempt or remaining < 2:
-            return
-
-        self.check_current()
-        self.attempts += 1
-        self._next_attempt = elapsed + self.RETRY_INTERVAL
-        clicked = False
-        failed = False
-        try:
-            if self._helper is None:
-                # Reuse the exact helper used by VFS. Suppress its free-form
-                # browser exceptions; emit only fixed Italy metadata below.
-                self._helper = CloudflareBypasser(self.page, log=False)
-            # Do NOT use bypass(): its page-title success check would accept
-            # "Booking - Prenot@Mi" while the embedded widget is still pending.
-            clicked = self._helper.click_verification_button(is_dfs=False) is True
-        except Exception:
-            failed = True
-        self.check_current()
-        print("ITA_BOOK_TURNSTILE_INTERACTION=" + json.dumps({
-            "contract": "ita-book-preflight-v2", "stage": stage.value,
-            "attempt": self.attempts, "maxAttempts": self.MAX_ATTEMPTS,
-            "clicked": clicked, "helperFailed": failed,
-        }, sort_keys=True), flush=True)

+ 0 - 236
plugins/ita_workflow.py

@@ -1,236 +0,0 @@
-"""Compose Italy's verified site adapters behind the normal plugin interface.
-
-No scheduler, queue, or local test-gate dependency. Calendar preparation uses
-one explicit manual/cloud OTP provider for either role. Only applicant Book
-may enter the separately enabled final submission and receipt reconciliation.
-"""
-from __future__ import annotations
-
-import re
-import sys
-from time import monotonic
-from threading import Lock
-
-from plugins import ita_calendar_session as preparation
-from plugins.ita_calendar_book import wait_for_calendar_service
-from plugins.ita_calendar_query import CALENDAR_PATH, CalendarGateError, guard_calendar, listen_once, same_origin_path
-from plugins.ita_booking_final import FinalBookingAttempt, FinalOutcomeUnknown, NativeFinalSubmitter, VerifiedSubmission
-from plugins.ita_final_read_port import FinalReceiptReadPort
-from plugins.ita_protocol import ItaCapability
-from plugins.ita_otp import fetch_otp_from_cloud, utc_sent_at, validate_cloud_otp_environment
-from plugins.ita_turnstile import ItalyTurnstileRecovery
-from vs_types import BizLogicError, PermissionDeniedError
-
-
-# Reuse the existing preparation lock, including cloud reads: no competing OTP
-# requests inside this process. This does not coordinate other worker processes.
-_OTP_INPUT_LOCK = Lock()
-
-
-def prepare_calendar(plugin, route, *, role):
-    """One native OTP + AVANTI, using the same functions as the tested gate."""
-    if (role not in {"query", "book"} or route.capability is not ItaCapability.SINGLE_SCHENGEN_TOURISM
-            or route.calendar_scan is None):
-        raise BizLogicError("Italy Calendar preparation requires a single-tourism route")
-    cloud = plugin.free_config.get("otp_mode") == "cloud"
-    if cloud:
-        query_config = plugin.free_config.get("query_mode", "services_probe") == "calendar"
-        if ((role == "query") != query_config
-                or plugin._book_final_configuration_valid() is not True):
-            raise PermissionDeniedError("Italy automatic OTP requires a matching Query/Book role and valid final configuration")
-        validate_cloud_otp_environment(route.mail, plugin.config.account.username)
-    elif plugin.free_config.get("otp_mode") != "manual" or not sys.stdin.isatty():
-        raise PermissionDeniedError("Italy Calendar needs an attached terminal for manual OTP (ITA-OTP-01)")
-    page, generation = plugin.page, plugin.session_create_time
-    username = plugin.config.account.username.strip().casefold()
-    tab_id = page.tab_id
-    booking_path = plugin._booking_path(route)
-
-    def current(path):
-        if (plugin.page is not page or page.tab_id != tab_id or plugin.session_create_time != generation
-                or plugin.config.account.username.strip().casefold() != username
-                or same_origin_path(page.url)[0] != path):
-            raise CalendarGateError("Italy preparation Session or page changed")
-
-    def packet_current(packet):
-        if getattr(packet, "tab_id", None) != tab_id or getattr(packet, "is_failed", None) is not False:
-            raise CalendarGateError("Italy preparation response came from another tab or failed")
-
-    def click(selector):
-        current(booking_path)
-        plugin.mouse.human_click_ele(preparation._element_or_fail(page, selector))
-
-    # A failed partial preparation cannot resend OTP on every Query signal.
-    # A fresh login/session permits another operator-assisted attempt.
-    preparation_key = (generation, tab_id, route.routing_key)
-    with _OTP_INPUT_LOCK:
-        if getattr(plugin, "_manual_preparation_attempt", None) == preparation_key:
-            raise PermissionDeniedError("Italy preparation failed; restore the session before retrying")
-        current(booking_path)
-        script = preparation.guarded_preflight_script(route, booking_path)
-        check_form = lambda: current(booking_path)
-        # Both roles must pass the same form before entering Calendar. Reuse
-        # one bounded recovery across both stages; prepared scans skip this path.
-        recovery = ItalyTurnstileRecovery(page, check_current=check_form)
-        plugin._log(f"Italy {role} Calendar preparation: reusing bounded Turnstile recovery.")
-        preparation.wait_for_booking_preflight(page, script=script,
-                                              check_current=check_form, wait_action=recovery)
-        plugin._manual_preparation_attempt = preparation_key
-        sent_at, sent_monotonic = None, None
-
-        def send_otp():
-            nonlocal sent_at, sent_monotonic
-            if cloud:
-                validate_cloud_otp_environment(route.mail, username)
-                sent_at, sent_monotonic = utc_sent_at(), monotonic()
-            click("#otp-send")
-
-        def check_cloud_window():
-            if cloud and (sent_monotonic is None or
-                          not 0 <= monotonic() - sent_monotonic < route.mail.expiry_seconds):
-                raise CalendarGateError("Italy OTP local read window expired; no automatic resend")
-
-        packet = listen_once(page, target=preparation.OTP_PATH, method="GET", timeout=30,
-                             action=send_otp)
-        packet_current(packet)
-        preparation.validate_otp_packet(packet, service_id=route.service_id)
-        current(booking_path)
-        if cloud:
-            check_cloud_window()
-            plugin._log(f"Italy {role} OTP sent; waiting for the authorized mailbox (one read attempt).")
-            otp = fetch_otp_from_cloud(route.mail, recipient=username, sent_at=sent_at)
-        else:
-            plugin._log(f"Italy {role} OTP sent; enter the code in this terminal.")
-            otp = preparation._read_manual_otp()
-        try:
-            pattern = r"[0-9]{6}" if cloud else r"[0-9]{4,12}"
-            if not isinstance(otp, str) or re.fullmatch(pattern, otp) is None:
-                raise CalendarGateError("Italy OTP format rejected")
-            current(booking_path)
-            check_cloud_window()
-            try:
-                preparation._enter_otp(plugin, otp)
-            except Exception:
-                if cloud:
-                    # Browser transport exceptions may contain typed values.
-                    raise CalendarGateError("Italy automatic OTP DOM write verification failed") from None
-                raise
-            if cloud:
-                plugin._log("Italy automatic OTP DOM write verified; continuing to Calendar.")
-        finally:
-            del otp
-        preparation.wait_for_booking_preflight(
-            page, script=script, stage=preparation.BookingPreflightStage.AFTER_OTP_SEND,
-            check_current=check_form, wait_action=recovery,
-        )
-        check_cloud_window()
-        try:
-            page.set.auto_handle_alert(accept=True)
-            packet = listen_once(page, target=booking_path, method="POST", timeout=30,
-                                 action=lambda: click("#btnAvanti"))
-            packet_current(packet)
-            preparation._wait_for_calendar(page)
-            current(CALENDAR_PATH)
-            preparation.validate_avanti_packet(packet, booking_path=booking_path, final_page_url=page.url)
-        finally:
-            page.set.auto_handle_alert(on_off=False)
-        guard_calendar(page)
-        wait_for_calendar_service(page, session_is_current=lambda: current(CALENDAR_PATH) is None)
-        if role == "query":
-            plugin._record_calendar_query_prepared_route(route)
-        else:
-            plugin._record_calendar_book_prepared_route(route)
-        plugin._manual_preparation_attempt = None
-
-
-def prepare_query_if_needed(plugin, apt_type):
-    """Return a negative entry result, or prepare and let Query scan real dates."""
-    if same_origin_path(plugin.page.url)[0] == CALENDAR_PATH:
-        return None  # Existing Query continuity checks remain authoritative.
-    route = plugin._resolve_route(apt_type)
-    entry = plugin._query_once(apt_type, query_mode="services_probe")
-    if not entry.success:
-        return entry
-    plugin._clear_calendar_query_state()
-    prepare_calendar(plugin, route, role="query")
-    return None
-
-
-def book(plugin, slot_info, user_inputs):
-    """Applicant-owned Calendar → existing pre-final adapter → standard result."""
-    if plugin._book_final_configuration_valid() is not True:
-        raise PermissionDeniedError("Italy final submission configuration is invalid")
-    if not isinstance(user_inputs, dict) or not isinstance(user_inputs.get("username"), str):
-        raise BizLogicError("Italy Book requires the applicant username")
-    username = user_inputs["username"].strip().casefold()
-    if (not username or username != plugin.config.account.username.strip().casefold()
-            or plugin.free_config.get("query_mode", "services_probe") == "calendar"
-            or getattr(plugin, "_calendar_query_route_key", None) is not None):
-        raise BizLogicError("Italy Book requires a separate applicant Session, not a Query Session")
-    route = plugin._resolve_route(slot_info.apt_type)
-    attempt = getattr(plugin, "_production_final_attempt", None)
-    if attempt is not None and attempt.state not in {"blocked", "rejected"}:
-        # The same task may retry success reporting, but must never submit twice.
-        result = getattr(plugin, "_production_book_result", None)
-        if (attempt.state == "confirmed" and result is not None
-                and attempt.target.applicant == username and attempt.target.routing_key == route.routing_key):
-            return result
-        raise FinalOutcomeUnknown()
-
-    if same_origin_path(plugin.page.url)[0] != CALENDAR_PATH:
-        entry = plugin._book_discovery_or_prepared(slot_info, user_inputs)
-        if entry.label != "booking-form-ready-before-avanti":
-            return entry
-        prepare_calendar(plugin, route, role="book")
-    elif plugin._calendar_book_context_matches(route, username):
-        # Refresh inventory on the next signal after a definite negative result.
-        plugin._calendar_book_attempted = False
-    result = plugin._book_discovery_or_prepared(slot_info, user_inputs)
-    if plugin.last_booking_precommit is None or plugin.free_config.get("final_submit_enabled") is not True:
-        return result
-    return submit_final(plugin, route)
-
-
-def submit_final(plugin, route, *, request_audit: preparation.CalendarRequestAudit | None = None):
-    """Reuse native submission and attribution with one audit per page.
-
-    A caller observing the whole workflow may lend its live audit. Ownership
-    stays with that caller; standalone production calls own their audit as
-    before. Neither path replaces callbacks or interrupts request coverage.
-    """
-    port = FinalReceiptReadPort(plugin, route)
-    owns_audit = request_audit is None
-    audit = preparation.CalendarRequestAudit(plugin.page, include_time_slots=True) if owns_audit else request_audit
-    if owns_audit:
-        audit.start()
-    else:
-        audit.require_active_on(plugin.page)
-        if "timeSlotRequests" not in audit.snapshot():
-            raise CalendarGateError("Final request audit must include time slots")
-    try:
-        before = audit.settled_snapshot()
-
-        def submit():
-            native = NativeFinalSubmitter(plugin.page, port.target, port.session_is_current)
-            signal = native()
-            after = audit.settled_snapshot()
-            if (after["finalRequests"] - before["finalRequests"] == 1
-                    and all(after[key] == before[key] for key in before if key != "finalRequests")
-                    and isinstance(native.submitted_selection, VerifiedSubmission)):
-                port.record_submission(native.submitted_selection)
-            return signal
-
-        attempt = FinalBookingAttempt(port.target, read_reservations=port, submit_native=submit,
-                                      session_is_current=port.session_is_current)
-        plugin._production_final_attempt = attempt
-        result = attempt.execute(enabled=True)
-        plugin._production_book_result = result if result.success else None
-        return result
-    finally:
-        # A diagnostic teardown failure must not turn a verified success into a
-        # generic booking failure (and a second real booking on the next signal).
-        if owns_audit:
-            try:
-                audit.stop()
-            except Exception:
-                plugin._log("Italy passive request audit cleanup failed; session needs cleanup.")

+ 12 - 0
test/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[1] / "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]

+ 3 - 3
test/test_debug_ita_book.py

@@ -400,8 +400,8 @@ class DebugItaBookWorkflowTests(unittest.TestCase):
 
     def setUp(self):
         from tools import debug_ita_book as cli
-        from plugins import ita_calendar_book as calendar
-        from plugins import ita_calendar_session as session
+        from plugins import ita_plugin as calendar
+        from plugins import ita_plugin as session
         from test.test_debug_ita_calendar_gate import gate_env
         from test.test_ita_booking_final import target
         self.cli = cli
@@ -464,7 +464,7 @@ class DebugItaBookWorkflowTests(unittest.TestCase):
         self.assertIn('"finalRequests": 0', output)
 
     def test_receipt_failure_is_not_passed_or_retried(self):
-        from plugins.ita_booking_final import FinalBookingError
+        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:

+ 5 - 5
test/test_debug_ita_book_gate.py

@@ -10,8 +10,8 @@ from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
 
-from plugins import ita_calendar_book as calendar_book
-from plugins.ita_calendar_query import AVAILABILITY_PATH, CALENDAR_PATH
+from plugins import ita_plugin as calendar_book
+from plugins.ita_plugin import AVAILABILITY_PATH, CALENDAR_PATH
 from plugins.ita_plugin import BOOKING_FORM_DISCOVERY_SCRIPT, ItaPlugin
 from test import test_debug_ita_calendar_gate as prep_fixtures
 from test import test_debug_ita_production_query_gate as audit_fixtures
@@ -399,7 +399,7 @@ class BookGateFlowTests(unittest.TestCase):
 
     def test_real_final_core_wiring_and_unknown_result_keeps_fence_and_requires_review(self):
         from test.test_ita_final_read_port import Browser
-        from plugins.ita_booking_final import SubmissionSignal
+        from plugins.ita_plugin import SubmissionSignal
 
         class AuditedBrowser(Browser):
             def open_tab(self, **kwargs):
@@ -461,8 +461,8 @@ class BookGateFlowTests(unittest.TestCase):
     def test_final_gate_exports_verified_success_and_late_failures_cannot_pass(self):
         from test.test_ita_final_read_port import Browser
         from test.test_ita_booking_final import final_packet
-        from plugins.ita_booking_final import inspect_final_packet
-        from plugins.ita_reservation import MONTHS_IT
+        from plugins.ita_plugin import inspect_final_packet
+        from plugins.ita_plugin import MONTHS_IT
 
         class AuditedBrowser(Browser):
             def open_tab(self, **kwargs):

+ 6 - 6
test/test_debug_ita_calendar_gate.py

@@ -8,8 +8,8 @@ from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import patch
 
-from plugins.ita_calendar_query import CALENDAR_GUARD_SCRIPT
-from plugins.ita_protocol import InventoryState, resolve_route_config
+from plugins.ita_plugin import CALENDAR_GUARD_SCRIPT
+from plugins.ita_plugin import InventoryState, resolve_route_config
 from tools.debug_ita_calendar_gate import (
     BookingPreflightStage,
     CalendarGateError,
@@ -1205,16 +1205,16 @@ class ToolContractTests(unittest.TestCase):
         shared_path = (
             Path(__file__).resolve().parents[1]
             / "plugins"
-            / "ita_calendar_query.py"
+            / "ita_plugin.py"
         )
         plugin_path = tool_path.parents[1] / "plugins" / "ita_plugin.py"
-        protocol_path = tool_path.parents[1] / "plugins" / "ita_protocol.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_calendar_session.py").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_calendar_book.py").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]

+ 2 - 2
test/test_debug_ita_production_query_gate.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
 
-from plugins.ita_calendar_query import (
+from plugins.ita_plugin import (
     AVAILABILITY_PATH,
     CALENDAR_GUARD_SCRIPT,
     NEXT_MONTH_CONTROL_SCRIPT,
@@ -16,7 +16,7 @@ from plugins.ita_calendar_query import (
     CalendarQueryScanResult,
 )
 from plugins.ita_plugin import ItaPlugin
-from plugins.ita_protocol import CalendarDay, InventoryState
+from plugins.ita_plugin import CalendarDay, InventoryState
 from tools.debug_ita_calendar_gate import (
     OTP_PATH,
     CalendarGateMode,

+ 14 - 13
test/test_debug_ita_query_book.py

@@ -76,10 +76,10 @@ class ExistingFrameworkJointTests(unittest.TestCase):
             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_workflow.submit_final",
+        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_calendar_query.time.sleep"))
+        self.enterContext(patch("plugins.ita_plugin.time.sleep"))
 
         self.query_config = GroupConfig(
             identifier="offline-query", need_account=True, appointment_types=[self.apt],
@@ -399,9 +399,9 @@ class LocalHarnessTests(unittest.TestCase):
         # Factories still belong to the GCO. Substitute only browser creation.
         real_observe = local.observe_factory
 
-        def synthetic_factory(gco, role, stack, observed):
+        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)
+            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))
@@ -539,9 +539,9 @@ class LocalFinalTests(unittest.TestCase):
     """
 
     def setUp(self):
-        from plugins import ita_workflow
-        from plugins.ita_calendar_session import CalendarRequestAudit
-        from plugins.ita_booking_final import VerifiedSubmission, SubmissionSignal
+        from plugins import ita_plugin as ita_workflow
+        from plugins.ita_plugin import CalendarRequestAudit
+        from plugins.ita_plugin import VerifiedSubmission, SubmissionSignal
         from test.test_debug_ita_production_query_gate import FakeAuditPage, FakeDriver
         from test.test_ita_final_read_port import Browser
         from test.test_ita_reservation import confirmed_listing, confirmed_detail
@@ -586,8 +586,9 @@ class LocalFinalTests(unittest.TestCase):
 
         self.local.CalendarRequestAudit.side_effect = audit
         clock = itertools.count(0, 0.1)
-        self.enterContext(patch.object(ita_workflow.preparation, "time", SimpleNamespace(
-            monotonic=lambda: next(clock), sleep=lambda _seconds: None)))
+        self.enterContext(patch.object(ita_workflow, "time", SimpleNamespace(
+            monotonic=lambda: next(clock), sleep=lambda _seconds: None,
+            time=lambda: self.fixture.clock["now"])))
 
         def native_factory(page, target, current):
             self.native.submitted_selection = VerifiedSubmission(target)
@@ -674,7 +675,7 @@ class LocalFinalTests(unittest.TestCase):
         self.assertEqual(self.dispatches, 1)
 
     def test_unknown_response_with_verified_request_and_receipt_is_confirmed(self):
-        from plugins.ita_booking_final import SubmissionSignal
+        from plugins.ita_plugin import SubmissionSignal
         self.submit_signal = SubmissionSignal.UNKNOWN
         self.assertTrue(self.run_case()["passed"])
 
@@ -689,7 +690,7 @@ class LocalFinalTests(unittest.TestCase):
         self.assertNotIn("private-response", json.dumps(report))
 
     def test_restart_is_blocked_before_second_pool_allocation(self):
-        from plugins.ita_booking_final import FinalBookingError
+        from plugins.ita_plugin import FinalBookingError
         self.assertTrue(self.run_case()["passed"])
         with self.assertRaises(FinalBookingError):
             self.local.LocalFinalSubmission(self.applicant, self.control.route, root=self.tmp)
@@ -718,7 +719,7 @@ class LocalFinalCompositionTests(unittest.TestCase):
         return self.local.LocalFinalSubmission(applicant or self.applicant, route or self.route, root=self.tmp)
 
     def test_claim_reuses_exclusive_helper_and_blocks_restarts_and_routing_aliases(self):
-        from plugins.ita_booking_final import FinalBookingError
+        from plugins.ita_plugin import FinalBookingError
         control = self.control()
         self.local.claim_once(control.claim_path)
         for account, route in ((self.applicant, self.route),
@@ -738,7 +739,7 @@ class LocalFinalCompositionTests(unittest.TestCase):
         production.assert_not_called()
 
     def test_partial_claim_and_symlink_block_without_removal(self):
-        from plugins.ita_booking_final import FinalBookingError
+        from plugins.ita_plugin import FinalBookingError
         control = self.control()
         control.claim_path.parent.mkdir(parents=True)
         control.claim_path.touch()

+ 2 - 2
test/test_debug_ita_reservation.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
 
-from plugins.ita_reservation import DETAIL_READ_SCRIPT, LIST_READ_SCRIPT, DATE_DIAGNOSTIC_SCRIPT, ReservationReadError
+from plugins.ita_plugin import DETAIL_READ_SCRIPT, LIST_READ_SCRIPT, DATE_DIAGNOSTIC_SCRIPT, ReservationReadError
 from test.test_ita_reservation import detail, listing, confirmed_detail, confirmed_listing
 from test.test_debug_ita_production_query_gate import FakeDriver
 from tools import debug_ita_reservation as gate
@@ -84,7 +84,7 @@ class ReceiptGateTests(unittest.TestCase):
         # Reuse real request classification; only shorten the audit's settled window.
         self.stack.enter_context(patch.object(gate.CalendarRequestAudit, "settled_snapshot",
                                              gate.CalendarRequestAudit.snapshot))
-        self.stack.enter_context(patch("plugins.ita_reservation.time.sleep"))
+        self.stack.enter_context(patch("plugins.ita_plugin.time.sleep"))
 
     def run_gate(self, *, execute=True, env=None, **kwargs):
         output = StringIO()

+ 3 - 3
test/test_ita_booker_integration.py

@@ -9,8 +9,8 @@ import unittest
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
 
-from plugins import ita_workflow
-from plugins.ita_booking_final import FINAL_PATH, NATIVE_FINAL_SCRIPT
+from plugins import ita_plugin as ita_workflow
+from plugins.ita_plugin import FINAL_PATH, NATIVE_FINAL_SCRIPT
 from test import test_ita_calendar_book_flow as flow
 from test.test_ita_final_read_port import Browser
 from test.test_ita_plugin import OrderBookerGCO
@@ -88,7 +88,7 @@ class BookerIntegrationTests(unittest.TestCase):
             "otpRequests": 0, "avantiPosts": 0, "availabilityRequests": 0,
             "timeSlotRequests": 0, "finalRequests": self.page.final_count,
         }
-        self.enterContext(patch.object(ita_workflow.preparation, "CalendarRequestAudit", return_value=self.audit))
+        self.enterContext(patch.object(ita_workflow, "CalendarRequestAudit", return_value=self.audit))
         self.enterContext(flow.browser_navigation(self.page))
 
     def run_booker(self):

+ 13 - 8
test/test_ita_booking_final.py

@@ -14,12 +14,12 @@ from types import SimpleNamespace
 from unittest.mock import Mock
 from urllib.parse import urlencode
 
-from plugins.ita_booking_final import (
+from plugins.ita_plugin import (
     FINAL_PATH, NATIVE_FINAL_SCRIPT, FinalBookingAttempt, FinalBookingError,
     FinalOutcomeUnknown, FinalTarget, NativeFinalSubmitter, ReservationRecord,
     ReservationSnapshot, ReservationState, SubmissionSignal, classify_final_packet,
 )
-from plugins.ita_calendar_book import CalendarBookError, select_slot_before_final, verify_precommit_selection
+from plugins.ita_plugin import CalendarBookError, select_slot_before_final, verify_precommit_selection
 from test.test_ita_calendar_book import DAY, SERVICE, FakePage, packets
 
 
@@ -518,15 +518,20 @@ class ProductionBoundaryTests(unittest.TestCase):
             with self.subTest(value=value), self.assertRaises(BizLogicError):
                 plugin.set_config(SimpleNamespace(free_config={"final_submit_enabled": value}))
 
-    def test_no_production_or_prefinal_tool_imports_final_module(self):
+    def test_query_and_prefinal_tools_do_not_dispatch_final(self):
         root = Path(__file__).resolve().parents[1]
-        for name in ("plugins/ita_plugin.py", "tools/debug_ita_book_gate.py", "tools/debug_ita_calendar_gate.py"):
-            tree = ast.parse((root / name).read_text())
+        from test.ita_source_sections import section
+        sources = [section("calendar_query")]
+        sources += [(root / name).read_text() for name in (
+            "tools/debug_ita_book_gate.py", "tools/debug_ita_calendar_gate.py")]
+        for source in sources:
+            tree = ast.parse(source)
             for node in ast.walk(tree):
                 if isinstance(node, ast.ImportFrom):
-                    self.assertNotEqual(node.module, "plugins.ita_booking_final")
-                if isinstance(node, ast.Import):
-                    self.assertNotIn("plugins.ita_booking_final", [alias.name for alias in node.names])
+                    self.assertFalse({a.name for a in node.names} & {
+                        "submit_final", "FinalBookingAttempt", "NativeFinalSubmitter"})
+                if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+                    self.assertNotIn(node.func.id, {"submit_final", "FinalBookingAttempt", "NativeFinalSubmitter"})
 
 
 # Actual composed JavaScript in a synthetic DOM. Slot snapshot logic is covered

+ 5 - 5
test/test_ita_calendar_book.py

@@ -9,9 +9,9 @@ from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import patch
 
-from plugins import ita_calendar_book as book_calendar
+from plugins import ita_plugin as book_calendar
 
-from plugins.ita_calendar_book import (
+from plugins.ita_plugin import (
     RUNTIME_SERVICE_SCRIPT,
     SLOT_SELECTION_SCRIPT,
     TIME_SLOTS_PATH,
@@ -19,7 +19,7 @@ from plugins.ita_calendar_book import (
     parse_book_time_slots,
     select_slot_before_final,
 )
-from plugins.ita_calendar_query import AVAILABILITY_PATH, CALENDAR_GUARD_SCRIPT
+from plugins.ita_plugin import AVAILABILITY_PATH, CALENDAR_GUARD_SCRIPT
 from test.test_ita_protocol import availability_item, double_json, slot_item
 
 
@@ -417,8 +417,8 @@ class BookSelectionTests(unittest.TestCase):
                 self.assertEqual(page.events, [])
 
     def test_adapter_has_no_query_tool_network_or_final_action(self):
-        path = Path(__file__).resolve().parents[1] / "plugins/ita_calendar_book.py"
-        source = path.read_text()
+        from test.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))

+ 8 - 4
test/test_ita_calendar_book_flow.py

@@ -8,12 +8,12 @@ from contextlib import contextmanager
 from datetime import date, datetime
 from unittest.mock import Mock, patch
 
-from plugins import ita_calendar_book as book_calendar
-from plugins.ita_calendar_book import (
+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_calendar_query import AVAILABILITY_PATH, CalendarNextMonthUnavailableError
+from plugins.ita_plugin import AVAILABILITY_PATH, CalendarNextMonthUnavailableError
 from plugins.ita_plugin import (
     BOOKING_CALENDAR_PREFINAL_STOP_LABEL, BOOKING_RECHECK_NONE_AVAILABLE_LABEL, ItaPlugin,
 )
@@ -192,7 +192,11 @@ class FlowPage(FakePage):
 
 @contextmanager
 def browser_navigation(page):
-    with patch.object(book_calendar, "click_next_month", side_effect=lambda _page: page.next_month()), \
+    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
 

+ 14 - 14
test/test_ita_calendar_query.py

@@ -2,13 +2,13 @@ import json
 import unittest
 from unittest.mock import Mock, patch
 
-from plugins.ita_calendar_query import (
+from plugins.ita_plugin import (
     CalendarGateError,
     CalendarNextMonthUnavailableError,
     CalendarProbeResult,
     scan_until_first_available_month,
 )
-from plugins.ita_protocol import parse_calendar_availability
+from plugins.ita_plugin import parse_calendar_availability
 
 
 def double_json(items):
@@ -57,10 +57,10 @@ class CalendarProductionScanTests(unittest.TestCase):
         august = probe(2026, 8, [(20, 2, 1), (12, 1, 0)])
 
         with patch(
-            "plugins.ita_calendar_query.capture_initial_probe",
+            "plugins.ita_plugin.capture_initial_probe",
             return_value=august,
         ) as initial, patch(
-            "plugins.ita_calendar_query.capture_next_probe"
+            "plugins.ita_plugin.capture_next_probe"
         ) as next_probe:
             result = scan_until_first_available_month(
                 Mock(),
@@ -89,10 +89,10 @@ class CalendarProductionScanTests(unittest.TestCase):
         log = Mock()
 
         with patch(
-            "plugins.ita_calendar_query.capture_initial_probe",
+            "plugins.ita_plugin.capture_initial_probe",
             return_value=august,
         ), patch(
-            "plugins.ita_calendar_query.capture_next_probe",
+            "plugins.ita_plugin.capture_next_probe",
             side_effect=[september, october, november],
         ) as next_probe:
             result = scan_until_first_available_month(
@@ -122,10 +122,10 @@ class CalendarProductionScanTests(unittest.TestCase):
         ]
 
         with patch(
-            "plugins.ita_calendar_query.capture_initial_probe",
+            "plugins.ita_plugin.capture_initial_probe",
             return_value=months[0],
         ), patch(
-            "plugins.ita_calendar_query.capture_next_probe",
+            "plugins.ita_plugin.capture_next_probe",
             side_effect=months[1:],
         ) as next_probe:
             result = scan_until_first_available_month(
@@ -145,10 +145,10 @@ class CalendarProductionScanTests(unittest.TestCase):
         january = probe(2027, 1, [(4, 1, 0)])
 
         with patch(
-            "plugins.ita_calendar_query.capture_initial_probe",
+            "plugins.ita_plugin.capture_initial_probe",
             return_value=december,
         ), patch(
-            "plugins.ita_calendar_query.capture_next_probe",
+            "plugins.ita_plugin.capture_next_probe",
             return_value=january,
         ):
             result = scan_until_first_available_month(
@@ -167,10 +167,10 @@ class CalendarProductionScanTests(unittest.TestCase):
         october = probe(2026, 10, [(1, 1, 0)])
 
         with patch(
-            "plugins.ita_calendar_query.capture_initial_probe",
+            "plugins.ita_plugin.capture_initial_probe",
             return_value=august,
         ), patch(
-            "plugins.ita_calendar_query.capture_next_probe",
+            "plugins.ita_plugin.capture_next_probe",
             return_value=october,
         ):
             with self.assertRaisesRegex(
@@ -187,10 +187,10 @@ class CalendarProductionScanTests(unittest.TestCase):
         august = probe(2026, 8, [(1, 0, -1)])
 
         with patch(
-            "plugins.ita_calendar_query.capture_initial_probe",
+            "plugins.ita_plugin.capture_initial_probe",
             return_value=august,
         ), patch(
-            "plugins.ita_calendar_query.capture_next_probe",
+            "plugins.ita_plugin.capture_next_probe",
             side_effect=CalendarNextMonthUnavailableError("bounded"),
         ):
             with self.assertRaisesRegex(

+ 1 - 1
test/test_ita_calendar_soak.py

@@ -42,7 +42,7 @@ class CalendarSoakLifecycleTests(unittest.TestCase):
             stack.enter_context(patch.object(
                 CalendarRequestAudit, "settled_snapshot", CalendarRequestAudit.snapshot,
             ))
-            stack.enter_context(patch("plugins.ita_calendar_query.time.sleep", clock.sleep))
+            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),

+ 2 - 2
test/test_ita_final_attribution.py

@@ -11,11 +11,11 @@ from io import StringIO
 from pathlib import Path
 from unittest.mock import Mock, patch
 
-from plugins.ita_booking_final import (
+from plugins.ita_plugin import (
     FinalBookingAttempt, FinalBookingError, FinalOutcomeUnknown, NativeFinalSubmitter,
     ReservationState, SubmissionSignal, VerifiedSubmission, inspect_final_packet,
 )
-from plugins.ita_final_read_port import FinalReceiptReadPort
+from plugins.ita_plugin import FinalReceiptReadPort
 from test import test_ita_final_read_port as fixtures
 from test.test_ita_booking_final import final_packet, NativePage, target
 from test.test_ita_reservation import confirmed_detail, confirmed_listing

+ 1 - 1
test/test_ita_final_evidence.py

@@ -10,7 +10,7 @@ from io import StringIO
 from pathlib import Path
 from unittest.mock import Mock, patch
 
-from plugins.ita_booking_final import FinalBookingError, SubmissionSignal
+from plugins.ita_plugin import FinalBookingError, SubmissionSignal
 from test import test_ita_final_read_port as port_fixtures
 from test.test_ita_reservation import listing, detail
 from tools import ita_final_evidence as evidence

+ 7 - 7
test/test_ita_final_read_port.py

@@ -9,11 +9,11 @@ from pathlib import Path
 from types import MethodType, SimpleNamespace
 from unittest.mock import Mock, patch
 
-from plugins.ita_booking_final import FinalBookingAttempt, FinalBookingError, FinalOutcomeUnknown, SubmissionSignal
-from plugins.ita_final_read_port import FinalReceiptReadPort, LIST_URL, MAX_DETAIL_READS
+from plugins.ita_plugin import FinalBookingAttempt, FinalBookingError, FinalOutcomeUnknown, SubmissionSignal
+from plugins.ita_plugin import FinalReceiptReadPort, LIST_URL, MAX_DETAIL_READS
 from plugins.ita_plugin import ItaPlugin
-from plugins.ita_protocol import ItaCapability, ItaRouteConfig, CalendarScanConfig
-from plugins.ita_reservation import DETAIL_READ_SCRIPT, LIST_READ_SCRIPT
+from plugins.ita_plugin import ItaCapability, ItaRouteConfig, CalendarScanConfig
+from plugins.ita_plugin import DETAIL_READ_SCRIPT, LIST_READ_SCRIPT
 from test.test_ita_booking_final import target
 from test.test_ita_reservation import detail, listing
 
@@ -64,7 +64,7 @@ class Browser:
 
 class FinalReadPortTests(unittest.TestCase):
     def setUp(self):
-        self.sleeper = patch("plugins.ita_reservation.time.sleep").start()
+        self.sleeper = patch("plugins.ita_plugin.time.sleep").start()
         self.addCleanup(patch.stopall)
         self.browser = Browser()
         self.main = SimpleNamespace(browser=self.browser, tab_id="calendar-tab",
@@ -260,8 +260,8 @@ class FinalReadPortTests(unittest.TestCase):
             self.assertFalse(port._lock.locked())
 
     def test_read_port_has_no_booking_or_cookie_operations(self):
-        path = Path(__file__).resolve().parents[1] / "plugins/ita_final_read_port.py"
-        tree = ast.parse(path.read_text())
+        from test.ita_source_sections import section
+        tree = ast.parse(section("final_read_port"))
         for node in ast.walk(tree):
             if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
                 self.assertNotIn(node.func.attr, {"click", "submit", "input", "book", "query", "cookies", "quit"})

+ 3 - 3
test/test_ita_otp.py

@@ -5,9 +5,9 @@ from io import StringIO
 from unittest import TestCase
 from unittest.mock import Mock, patch
 
-from plugins import ita_otp as otp
-from plugins.ita_calendar_query import CalendarGateError
-from plugins.ita_protocol import OtpMailConfig, ItaProtocolError, parse_otp_body, resolve_route_config
+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
 
 

+ 2 - 2
test/test_ita_preflight.py

@@ -6,8 +6,8 @@ from types import SimpleNamespace
 from unittest import TestCase
 from unittest.mock import Mock, patch
 
-from plugins import ita_calendar_session as session
-from plugins import ita_turnstile as turnstile
+from plugins import ita_plugin as session
+from plugins import ita_plugin as turnstile
 from test.test_debug_ita_calendar_gate import booking_preflight_snapshot
 
 

+ 1 - 1
test/test_ita_protocol.py

@@ -4,7 +4,7 @@ import unittest
 from dataclasses import replace
 from datetime import date, time
 
-from plugins.ita_protocol import (
+from plugins.ita_plugin import (
     MAX_LOOKAHEAD_MONTHS,
     MAX_PROTOCOL_ITEMS,
     CalendarDay,

+ 2 - 2
test/test_ita_query_recovery.py

@@ -13,8 +13,8 @@ from unittest.mock import Mock, patch
 
 from DrissionPage.errors import PageDisconnectedError
 
-from plugins.ita_calendar_book import RUNTIME_SERVICE_SCRIPT
-from plugins.ita_calendar_query import (
+from plugins.ita_plugin import RUNTIME_SERVICE_SCRIPT
+from plugins.ita_plugin import (
     AVAILABILITY_PATH, CalendarAccessDeniedError, CalendarAuthenticationExpiredError,
     CalendarGateError, CalendarRateLimitedError, CalendarTransientError,
     parse_availability_packet,

+ 7 - 7
test/test_ita_reservation.py

@@ -11,8 +11,8 @@ from html.parser import HTMLParser
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
 
-from plugins.ita_booking_final import ReservationState
-from plugins.ita_reservation import (
+from plugins.ita_plugin import ReservationState
+from plugins.ita_plugin import (
     DETAIL_READ_SCRIPT, LIST_READ_SCRIPT, DATE_DIAGNOSTIC_SCRIPT, HEADERS, ReservationReadError,
     parse_reservation_detail, parse_reservation_listing,
     read_reservation_detail, read_reservation_listing, read_reservation_date_diagnostic,
@@ -116,7 +116,7 @@ class ReceiptParsingTests(unittest.TestCase):
                 self.assertNotIn(value, str(error.exception))
 
     def test_all_italian_months_parse_without_process_locale(self):
-        from plugins.ita_reservation import MONTHS_IT
+        from plugins.ita_plugin import MONTHS_IT
         for month, name in enumerate(MONTHS_IT, 1):
             raw = detail()
             raw["fields"]["Data"] = f"1 {name} 2027"
@@ -230,7 +230,7 @@ class BrowserReadTests(unittest.TestCase):
 
     def test_list_requires_two_stable_reads(self):
         page = self.page(listing())
-        with patch("plugins.ita_reservation.time.sleep"):
+        with patch("plugins.ita_plugin.time.sleep"):
             self.assertEqual(len(read_reservation_listing(page).rows), 1)
         self.assertEqual(page.run_js.call_count, 2)
         self.assertTrue(all(call.args == (LIST_READ_SCRIPT,) for call in page.run_js.call_args_list))
@@ -241,7 +241,7 @@ class BrowserReadTests(unittest.TestCase):
         changed["tables"][0]["rows"][0]["time"] = "10:30"
         page = self.page(original)
         page.run_js.side_effect = [original, {"error": "not_ready"}, changed, changed]
-        with patch("plugins.ita_reservation.time.sleep"):
+        with patch("plugins.ita_plugin.time.sleep"):
             self.assertEqual(read_reservation_listing(page).rows[0].appointment_time, "10:30")
         self.assertEqual(page.run_js.call_count, 4)
 
@@ -275,7 +275,7 @@ class BrowserReadTests(unittest.TestCase):
 
     def test_tab_changes_between_stability_reads_rejected(self):
         page = self.page(listing())
-        with patch("plugins.ita_reservation.time.sleep", side_effect=lambda _: setattr(page, "tab_id", "other")):
+        with patch("plugins.ita_plugin.time.sleep", side_effect=lambda _: setattr(page, "tab_id", "other")):
             with self.assertRaisesRegex(ReservationReadError, "context_changed"):
                 read_reservation_listing(page)
         self.assertEqual(page.run_js.call_count, 1)
@@ -289,7 +289,7 @@ class BrowserReadTests(unittest.TestCase):
 
     def test_unready_read_is_bounded(self):
         page = self.page({"error": "not_ready"})
-        with patch("plugins.ita_reservation.time.monotonic", side_effect=[0, 0, 0, 6]), patch("plugins.ita_reservation.time.sleep"):
+        with patch("plugins.ita_plugin.time.monotonic", side_effect=[0, 0, 0, 6]), patch("plugins.ita_plugin.time.sleep"):
             with self.assertRaisesRegex(ReservationReadError, "stability_timeout"):
                 read_reservation_listing(page)
         self.assertEqual(page.run_js.call_count, 1)

+ 254 - 0
test/test_ita_single_file.py

@@ -0,0 +1,254 @@
+"""Offline single-artifact install, factory loading, hot reload and move parity."""
+import ast
+import builtins
+from contextlib import ExitStack, redirect_stdout
+from dataclasses import asdict
+from datetime import date
+import hashlib
+from io import StringIO
+import json
+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_source_sections import section
+from test.test_ita_calendar_book import DAY, SERVICE, FakePage, packets
+from test.test_ita_protocol import live_route
+from tools import consolidate_ita_plugin as migration
+from tools import ita_query_book_local as local
+from utils import plugin_updater
+from vs_plg_factory import VSPlgFactory
+from vs_types import AppointmentType, BookingOutcomeUnknownError, VSQueryResult
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class NormalizeOriginal(ast.NodeTransformer):
+    """Independent structural check: only the explicitly allowed wiring edits."""
+    def __init__(self, module):
+        self.module = module
+        self.renames = migration.RENAMES.get(module, {})
+
+    def visit_ImportFrom(self, node):
+        if node.module == "__future__":
+            return None
+        if node.module and node.module.startswith("plugins.ita_"):
+            return [ast.Assign(targets=[ast.Name(id=a.asname, ctx=ast.Store())],
+                               value=ast.Name(id=a.name, ctx=ast.Load()))
+                    for a in node.names if a.asname]
+        if node.module == "plugins":
+            assert self.module == "ita_workflow"
+            return None
+        if self.module == "ita_protocol" and node.module == "datetime":
+            node.names[-1].asname = "datetime_time"
+        return node
+
+    def visit_Assign(self, node):
+        if any(isinstance(t, ast.Name) and t.id == "__all__" for t in node.targets):
+            return None
+        if any(isinstance(t, ast.Name) and t.id == "_OTP_INPUT_LOCK" for t in node.targets):
+            return ast.parse('import vs_plg as _ita_host\n'
+                             '_OTP_INPUT_LOCK = vars(_ita_host).setdefault("_coordinate_ita_otp_input_lock", Lock())').body
+        if (self.module == "ita_plugin" and any(isinstance(t, ast.Name) and t.id == "version" for t in node.targets)):
+            node.value = ast.Constant(value="1.0.1")
+        return self.generic_visit(node)
+
+    def visit_Name(self, node):
+        node.id = self.renames.get(node.id, node.id)
+        return node
+
+    def visit_FunctionDef(self, node):
+        node.name = self.renames.get(node.name, node.name)
+        return self.generic_visit(node)
+
+    def visit_Attribute(self, node):
+        if self.module == "ita_workflow" and isinstance(node.value, ast.Name) and node.value.id == "preparation":
+            return ast.Name(id=node.attr, ctx=node.ctx)
+        return self.generic_visit(node)
+
+
+class RelocationParityTests(unittest.TestCase):
+    def test_every_original_section_is_structurally_unchanged_except_wiring(self):
+        for module in migration.MODULES:
+            with self.subTest(module=module):
+                expected = NormalizeOriginal(module).visit(ast.parse(migration.original(module)))
+                actual = ast.parse(section(module.removeprefix("ita_")))
+                self.assertEqual(ast.dump(expected), ast.dump(actual))
+
+    def test_relocation_and_manifest_are_reproducible(self):
+        source, manifest = migration.assemble()
+        self.assertEqual(source, (ROOT / "plugins/ita_plugin.py").read_text())
+        self.assertEqual(manifest, json.loads((ROOT / "docs/ita-single-file-migration.json").read_text()))
+
+    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", "CalendarRequestAudit", "FinalReceiptReadPort", "FinalBookingAttempt",
+                     "parse_otp_body", "prepare_calendar", "recheck_calendar_before_final", "submit_final"):
+            self.assertEqual(runtime[name].__module__, "ita_plugin", name)
+        self.assertIs(runtime["BookingOutcomeUnknownError"], BookingOutcomeUnknownError)
+        self.assertIsInstance(runtime["FinalOutcomeUnknown"](), BookingOutcomeUnknownError)
+        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), book=Mock(return_value="loaded-book")):
+            self.assertIs(plugin.query(AppointmentType(routing_key="fixture")), negative)
+            self.assertEqual(plugin.book(negative, {"username": "fixture@example.test"}), "loaded-book")
+            runtime["prepare_query_if_needed"].assert_called_once()
+            runtime["book"].assert_called_once()
+
+    def test_local_final_fence_uses_instance_types_and_functions_after_cache_replacement(self):
+        plugin = self.create()
+        runtime = type(plugin).book.__globals__
+        plugin.page = FakePage()
+        plugin.page.quit = Mock()
+        availability, slots = packets()
+        approval = runtime["select_slot_before_final"](
+            plugin.page, target_day=DAY, availability_packet=availability, time_slots_packet=slots)
+        plugin.last_booking_precommit = approval
+        self.assertEqual(local.verify_plugin_selection(plugin), approval)
+        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(asdict(route), asdict(configured_route))
+        applicant = SimpleNamespace(username="applicant@example.test")
+        plugin.config = SimpleNamespace(account=applicant)
+        target = runtime["FinalTarget"](applicant.username, "fixture-session", "fixture-tab", key,
+                                        str(route.service_id), SERVICE, approval)
+        audit = Mock()
+        audit.settled_snapshot.return_value = {"finalRequests": 0}
+        observed = {"book": SimpleNamespace(plugin=plugin, audit=audit)}
+        control = local.LocalFinalSubmission(applicant, configured_route, root=self.directory / "claims")
+        native = Mock(return_value="synthetic-dispatch")
+        def production(actual_plugin, actual_route, *, request_audit):
+            self.assertIs(actual_plugin, plugin)
+            self.assertIs(actual_route, route)
+            self.assertIs(request_audit, audit)
+            return runtime["NativeFinalSubmitter"](plugin.page, target, lambda: True)()
+        self.create()  # The host overwrites sys.modules['ita_plugin'] for Query.
+        self.assertIsNot(sys.modules["ita_plugin"].ItaPlugin, type(plugin))
+        with patch.dict(runtime, NativeFinalSubmitter=Mock(return_value=native)):
+            self.assertEqual(control.submit(plugin, route, observed, production), "synthetic-dispatch")
+        self.assertTrue(control.claim_path.is_file())
+        self.assertTrue(control.possibly_submitted)
+        native.assert_called_once_with()
+        with self.assertRaises(local.LocalAcceptanceError):
+            control.submit(plugin, route, observed, production)
+        native.assert_called_once_with()
+
+    def test_local_observer_preserves_loaded_unknown_error_for_shared_booker(self):
+        plugin = self.create()
+        runtime = type(plugin).book.__globals__
+        observer = local.ObservedPlugin(plugin, "book")
+        plugin.book = Mock(side_effect=runtime["FinalOutcomeUnknown"]())
+        with self.assertRaises(BookingOutcomeUnknownError):
+            observer.book(VSQueryResult(), {})
+        self.assertEqual(observer.error, "FinalOutcomeUnknown")
+
+    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", "CalendarRequestAudit", "FinalOutcomeUnknown",
+                     "fetch_otp_from_cloud", "book", "submit_final"):
+            self.assertIsNot(new[name], old[name], name)
+        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)
+        self.assertIs(new["BookingOutcomeUnknownError"], old["BookingOutcomeUnknownError"])
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 13 - 12
test/test_ita_workflow.py

@@ -12,13 +12,14 @@ from types import MethodType, SimpleNamespace
 from unittest import TestCase
 from unittest.mock import Mock, patch
 
-from plugins import ita_workflow as workflow
-from plugins import ita_calendar_session as preparation
-from plugins.ita_booking_final import FinalOutcomeUnknown, SubmissionSignal, VerifiedSubmission
+from plugins import ita_plugin as workflow
+from plugins import ita_plugin as preparation
+from plugins.ita_plugin import FinalOutcomeUnknown, SubmissionSignal, VerifiedSubmission
 from plugins.ita_plugin import ItaPlugin
-from plugins import ita_otp
-from plugins import ita_turnstile
-from plugins.ita_protocol import OtpMailConfig
+from plugins import ita_plugin as ita_otp
+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 import test_ita_calendar_book_flow as flow
 from test.test_debug_ita_calendar_gate import booking_preflight_snapshot
 from test import test_ita_final_attribution as attribution
@@ -243,7 +244,7 @@ class CloudQueryPreparationTests(TestCase):
         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: ita_otp.fetch_otp_from_cloud(
+        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):
@@ -271,7 +272,7 @@ class CloudQueryPreparationTests(TestCase):
         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: ita_otp.fetch_otp_from_cloud(*args, **kwargs, api=client)
+        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)
@@ -324,7 +325,7 @@ class CloudQueryPreparationTests(TestCase):
     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: ita_otp.fetch_otp_from_cloud(
+        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()
@@ -651,7 +652,7 @@ class ProductionEntryTests(TestCase):
 
     def test_production_modules_never_import_debug_tools(self):
         root = Path(__file__).resolve().parents[1]
-        for filename in ("ita_workflow.py", "ita_calendar_session.py"):
+        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))
@@ -674,7 +675,7 @@ class FinalCompositionTests(TestCase):
             native = Mock(side_effect=lambda: (self.add_confirmed(), SubmissionSignal.UNKNOWN)[1])
             native.submitted_selection = VerifiedSubmission(target)
             return native
-        with patch.object(workflow.preparation, "CalendarRequestAudit", return_value=self.audit), \
+        with patch.object(workflow, "CalendarRequestAudit", return_value=self.audit), \
                 patch.object(workflow, "NativeFinalSubmitter", side_effect=native_factory) as factory:
             result = workflow.submit_final(self.plugin, self.route)
         self.assertEqual(factory.call_count, 1)
@@ -773,7 +774,7 @@ class RealFinalAuditTests(TestCase):
         self.browser.new_tab.assert_not_called()
 
     def test_existing_reservation_blocks_without_stopping_borrowed_audit(self):
-        from plugins.ita_booking_final import FinalBookingError
+        from plugins.ita_plugin import FinalBookingError
         self.audit.start()
         attribution.AttributionTests.add_confirmed(self)
         with self.assertRaises(FinalBookingError):

+ 1 - 1
test/test_plugin_tester_ita_config.py

@@ -11,7 +11,7 @@ from types import SimpleNamespace
 import unittest
 from unittest.mock import Mock, patch
 
-from plugins.ita_protocol import ItaCapability, resolve_route_config
+from plugins.ita_plugin import ItaCapability, resolve_route_config
 from sentinel import SentinelGCO
 from tools.plugin_tester import PluginTester
 from vs_types import GroupConfig

+ 204 - 0
tools/consolidate_ita_plugin.py

@@ -0,0 +1,204 @@
+"""One-off, auditable source relocation; NOT a build/runtime dependency.
+
+The committed single-file plugin becomes the source of truth after migration.
+Read the immutable pre-migration Git revision, preserve source text, and change
+only imports, module qualification and the three colliding private names.
+Run with --write once; without it, verify the initial migration is reproducible.
+Never run against a plugin with subsequent business edits expecting to keep them.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import hashlib
+import json
+from pathlib import Path
+import re
+import subprocess
+
+ROOT = Path(__file__).resolve().parents[1]
+SOURCE_REVISION = "62c2388"
+MODULES = (
+    "ita_protocol", "ita_calendar_query", "ita_calendar_book",
+    "ita_booking_final", "ita_reservation", "ita_final_read_port",
+    "ita_calendar_session", "ita_otp", "ita_turnstile", "ita_workflow",
+    "ita_plugin",
+)
+RENAMES = {
+    "ita_protocol": {"time": "datetime_time"},
+    "ita_booking_final": {"_text": "_final_text"},
+    "ita_reservation": {"_text": "_reservation_text"},
+    "ita_otp": {"_EMAIL_PATTERN": "_OTP_EMAIL_PATTERN"},
+}
+
+
+def original(module: str) -> str:
+    return subprocess.check_output(
+        ["git", "show", f"{SOURCE_REVISION}:plugins/{module}.py"],
+        cwd=ROOT, text=True,
+    )
+
+
+def relocate(module: str, source: str) -> str:
+    """Splice AST-located tokens; never reformat/rewrite a function or JS body."""
+    lines = source.splitlines(keepends=True)
+    offsets = [0]
+    for line in lines:
+        offsets.append(offsets[-1] + len(line))
+
+    def pos(line, byte_column):
+        return offsets[line - 1] + len(lines[line - 1].encode()[:byte_column].decode())
+
+    tree = ast.parse(source)
+    edits = []
+    removed = []
+    renames = RENAMES.get(module, {})
+
+    def replace(node, value):
+        edits.append((pos(node.lineno, node.col_offset),
+                      pos(node.end_lineno, node.end_col_offset), value))
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if node.module == "__future__":
+                replace(node, "")
+                removed.append(node)
+            elif node.module and node.module.startswith("plugins.ita_"):
+                # Retain existing private aliases, not a module object/cache.
+                aliases = [f"{a.asname} = {a.name}" for a in node.names if a.asname]
+                replace(node, "; ".join(aliases))
+                removed.append(node)
+            elif node.module == "plugins":
+                assert module == "ita_workflow" and len(node.names) == 1
+                assert node.names[0].asname == "preparation"
+                replace(node, "")
+                removed.append(node)
+            elif module == "ita_protocol" and node.module == "datetime":
+                replace(node, "from datetime import date, datetime, time as datetime_time")
+                removed.append(node)
+        elif isinstance(node, ast.Assign) and any(
+                isinstance(t, ast.Name) and t.id == "__all__" for t in node.targets):
+            replace(node, "")
+            removed.append(node)
+
+    for node in ast.walk(tree):
+        if any(parent.lineno <= getattr(node, "lineno", 0) <= parent.end_lineno for parent in removed):
+            continue
+        if isinstance(node, ast.Name) and node.id in renames:
+            replace(node, renames[node.id])
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name in renames:
+            start = pos(node.lineno, node.col_offset) + len("def ")
+            edits.append((start, start + len(node.name), renames[node.name]))
+        elif (module == "ita_workflow" and isinstance(node, ast.Attribute)
+              and isinstance(node.value, ast.Name) and node.value.id == "preparation"):
+            replace(node, node.attr)
+
+    last = len(source) + 1
+    for start, end, value in sorted(edits, reverse=True):
+        assert end <= last, "overlapping relocation edits"
+        source = source[:start] + value + source[end:]
+        last = start
+    ast.parse(source)
+    return source.strip() + "\n"
+
+
+def assemble() -> tuple[str, dict]:
+    parts = ['"""Prenot@Mi plugin: one uploadable runtime file.\n\n'
+             'Sections below were mechanically relocated from commit 62c2388.\n'
+             'Maintain this file directly; tools/consolidate_ita_plugin.py is an audit\n'
+             'of the initial move, not a build step. Shared host APIs remain shared.\n'
+             '"""\nfrom __future__ import annotations\n']
+    evidence = {"sourceRevision": SOURCE_REVISION, "target": "plugins/ita_plugin.py",
+                "integrationChanges": ["ItaPlugin.version: 1.0.0 -> 1.0.1", "trim Python-only trailing whitespace",
+                                       "retain process-wide OTP lock on the existing shared vs_plg host module"],
+                "sections": []}
+    for module in MODULES:
+        source = original(module)
+        moved = relocate(module, source)
+        if module == "ita_plugin":
+            assert moved.count('    version = "1.0.0"') == 1
+            moved = moved.replace('    version = "1.0.0"', '    version = "1.0.1"')
+        if module == "ita_workflow":
+            assert moved.count("_OTP_INPUT_LOCK = Lock()") == 1
+            moved = moved.replace("_OTP_INPUT_LOCK = Lock()", '''# The existing factory executes this file separately for each instance.
+# Keep only the primitive process-wide lock on the shared host module; never
+# cache plugin functions/classes there. setdefault preserves concurrent loads
+# and hot reloads without requiring another Italy file or a host code change.
+import vs_plg as _ita_host
+_OTP_INPUT_LOCK = vars(_ita_host).setdefault("_coordinate_ita_otp_input_lock", Lock())''')
+        # Keep literal values (including JavaScript) byte-for-byte intact.
+        literal_lines = {line for node in ast.walk(ast.parse(moved))
+                         if isinstance(node, ast.Constant) and isinstance(node.value, str)
+                         for line in range(node.lineno, node.end_lineno + 1)}
+        moved = "".join(line if number in literal_lines else line.rstrip() + "\n"
+                        for number, line in enumerate(moved.splitlines(keepends=True), 1))
+        parts.append(f"\n\n# {'=' * 76}\n# {module.removeprefix('ita_').upper()} (from plugins/{module}.py)\n# {'=' * 76}\n\n{moved}")
+        evidence["sections"].append({
+            "source": f"plugins/{module}.py",
+            "sourceSha256": hashlib.sha256(source.encode()).hexdigest(),
+            "relocatedSha256": hashlib.sha256(moved.encode()).hexdigest(),
+            "renames": RENAMES.get(module, {}),
+        })
+    result = "".join(parts)
+    ast.parse(result)
+    evidence["targetSha256"] = hashlib.sha256(result.encode()).hexdigest()
+    return result, evidence
+
+
+def retarget_consumers(source: str) -> str:
+    helpers = set(MODULES) - {"ita_plugin"}
+    # Preserve local aliases used by tests/tools, but they now refer to the
+    # single public module. No compatibility shims ship beside the plugin.
+    def imports(match):
+        module, alias = match.group(1), match.group(2)
+        if module not in helpers:
+            return match.group(0)
+        return "from plugins import ita_plugin as " + (alias or module)
+
+    source = re.sub(r"from plugins import (ita_\w+)(?: as (\w+))?", imports, source)
+    for module in helpers:
+        source = source.replace("plugins." + module, "plugins.ita_plugin")
+        source = source.replace(f'"{module}.py"', '"ita_plugin.py"')
+        source = source.replace(f'plugins/{module}.py', 'plugins/ita_plugin.py')
+    source = source.replace("ita_workflow.preparation", "ita_workflow")
+    source = source.replace("workflow.preparation", "workflow")
+    return source
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--write", action="store_true", help="apply the initial relocation (overwrites target)")
+    args = parser.parse_args()
+    source, manifest = assemble()
+    target = ROOT / "plugins/ita_plugin.py"
+    manifest_path = ROOT / "docs/ita-single-file-migration.json"
+    if not args.write:
+        if target.read_text() != source:
+            raise SystemExit("Target differs from initial relocation (may contain later integration edits).")
+        print("Italy initial relocation is reproducible")
+        return
+    # Refuse to overwrite an existing consolidated file or local source edits.
+    for module in MODULES:
+        path = ROOT / f"plugins/{module}.py"
+        if not path.exists() or path.read_text() != original(module):
+            raise SystemExit(f"Refusing to replace modified/missing source: {path.relative_to(ROOT)}")
+    target.write_text(source)
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n")
+    changed = []
+    for folder in ("test", "tools"):
+        for path in sorted((ROOT / folder).glob("*.py")):
+            if path.resolve() == Path(__file__).resolve():
+                continue
+            old = path.read_text()
+            new = retarget_consumers(old)
+            if new != old:
+                ast.parse(new)
+                path.write_text(new)
+                changed.append(str(path.relative_to(ROOT)))
+    for module in MODULES[:-1]:
+        (ROOT / f"plugins/{module}.py").unlink()
+    print(json.dumps({"relocatedModules": len(MODULES), "updatedConsumers": changed}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

+ 5 - 5
tools/debug_ita_book.py

@@ -189,9 +189,9 @@ def run_book_recheck_once(
     if production_workflow:
         config.free_config.update(query_mode="services_probe", otp_mode="manual", final_submit_enabled=False)
         if auto_otp:
-            from plugins.ita_otp import validate_cloud_otp_environment
-            from plugins.ita_protocol import ItaProtocolError, OtpMailConfig
-            from plugins.ita_calendar_query import CalendarGateError
+            from plugins.ita_plugin import validate_cloud_otp_environment
+            from plugins.ita_plugin import ItaProtocolError, OtpMailConfig
+            from plugins.ita_plugin import CalendarGateError
             try:
                 mail = OtpMailConfig(env.get("ITA_OTP_AUTHORIZATION_EMAIL", ""))
                 validate_cloud_otp_environment(mail, username)
@@ -220,7 +220,7 @@ def run_book_recheck_once(
     try:
         plugin.create_session()
         if production_workflow:
-            from plugins.ita_calendar_session import CalendarRequestAudit
+            from plugins.ita_plugin import CalendarRequestAudit
             audit = CalendarRequestAudit(plugin.page, include_time_slots=True)
             audit.start()
         if arm:
@@ -270,7 +270,7 @@ def run_book_recheck_once(
             result = plugin.book(trigger, user_inputs={"username": username} if production_workflow else {})
 
             if production_workflow:
-                from plugins.ita_calendar_book import read_calendar_service, verify_precommit_selection
+                from plugins.ita_plugin import read_calendar_service, verify_precommit_selection
                 counts = audit.settled_snapshot()
                 if counts["finalRequests"] != 0:
                     raise BizLogicError("Book workflow observed an unexpected final request; do not rerun")

+ 11 - 11
tools/debug_ita_book_gate.py

@@ -27,9 +27,9 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
 if str(REPO_ROOT) not in sys.path:
     sys.path.insert(0, str(REPO_ROOT))
 
-from plugins import ita_calendar_book as calendar_book
-from plugins.ita_final_read_port import FinalReceiptReadPort
-from plugins.ita_calendar_query import CALENDAR_PATH, guard_calendar, same_origin_path
+from plugins import ita_plugin as calendar_book
+from plugins.ita_plugin import FinalReceiptReadPort
+from plugins.ita_plugin import CALENDAR_PATH, guard_calendar, same_origin_path
 from plugins.ita_plugin import (
     BOOKING_CALENDAR_PREFINAL_STOP_LABEL,
     BOOKING_FORM_DISCOVERY_STOP_LABEL,
@@ -38,7 +38,7 @@ from plugins.ita_plugin import (
     SERVICES_PROBE_QUERY_MODE,
     ItaPlugin,
 )
-from plugins.ita_protocol import ItaRouteConfig, PrecommitApproval, resolve_route_config
+from plugins.ita_plugin import ItaRouteConfig, PrecommitApproval, resolve_route_config
 from tools import debug_ita_calendar_gate as preparation
 from tools import ita_final_evidence as final_evidence
 from tools.debug_ita_query import DEBUG_ROUTE_ENV_NAMES, _popup_text_for_log, resolve_debug_route
@@ -52,14 +52,14 @@ BOOK_GATE_CONTRACT = "book-final-attribution-v9"
 CALENDAR_READY_TIMEOUT_SECONDS = 5
 BOOK_GATE_SOURCE_PATHS = (
     Path(__file__), Path(preparation.__file__),
-    REPO_ROOT / "plugins" / "ita_calendar_session.py",
     REPO_ROOT / "plugins" / "ita_plugin.py",
-    REPO_ROOT / "plugins" / "ita_calendar_book.py",
-    REPO_ROOT / "plugins" / "ita_calendar_query.py",
-    REPO_ROOT / "plugins" / "ita_protocol.py",
-    REPO_ROOT / "plugins" / "ita_final_read_port.py",
-    REPO_ROOT / "plugins" / "ita_reservation.py",
-    REPO_ROOT / "plugins" / "ita_booking_final.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
     REPO_ROOT / "tools" / "debug_ita_query.py",
     REPO_ROOT / "tools" / "debug_ita_session.py",
     REPO_ROOT / "tools" / "ita_final_evidence.py",

+ 8 - 8
tools/debug_ita_calendar_gate.py

@@ -35,8 +35,8 @@ from plugins.ita_plugin import (
     SERVICES_PROBE_QUERY_MODE,
     ItaPlugin,
 )
-from plugins import ita_calendar_session as calendar_session
-from plugins.ita_calendar_query import (
+from plugins import ita_plugin as calendar_session
+from plugins.ita_plugin import (
     AVAILABILITY_PATH,
     CALENDAR_PATH,
     NEXT_MONTH_CONTROL_SCRIPT,
@@ -56,7 +56,7 @@ from plugins.ita_calendar_query import (
     same_origin_path as _same_origin_path,
     validate_next_month_snapshot,
 )
-from plugins.ita_protocol import (
+from plugins.ita_plugin import (
     ItaProtocolError,
     ItaRouteConfig,
     resolve_route_config,
@@ -82,11 +82,11 @@ OTP_PATH = "/BookingCalendar/GenerateOTP"
 QCAL_TOOL_CONTRACT_VERSION = "qcal1-calendar-soak-v11"
 QCAL_TOOL_SOURCE_PATHS = (
     Path(__file__),
-    REPO_ROOT / "plugins" / "ita_calendar_session.py",
-    REPO_ROOT / "plugins" / "ita_calendar_query.py",
     REPO_ROOT / "plugins" / "ita_plugin.py",
-    REPO_ROOT / "plugins" / "ita_protocol.py",
-    REPO_ROOT / "plugins" / "ita_calendar_book.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
+    REPO_ROOT / "plugins" / "ita_plugin.py",
     REPO_ROOT / "tools" / "debug_ita_soak.py",
     REPO_ROOT / "toolkit" / "backoff.py",
 )
@@ -205,7 +205,7 @@ return {
 """
 
 
-from plugins.ita_calendar_session import (
+from plugins.ita_plugin import (
     BookingPreflightStage,
     CalendarRequestAudit,
     validate_otp_packet,

+ 6 - 6
tools/debug_ita_reservation.py

@@ -25,10 +25,10 @@ REPO_ROOT = Path(__file__).resolve().parents[1]
 if str(REPO_ROOT) not in sys.path:
     sys.path.insert(0, str(REPO_ROOT))
 
-from plugins.ita_booking_final import ReservationState
-from plugins.ita_calendar_query import same_origin_path
+from plugins.ita_plugin import ReservationState
+from plugins.ita_plugin import same_origin_path
 from plugins.ita_plugin import ItaPlugin, SERVICES_PROBE_QUERY_MODE
-from plugins.ita_reservation import (
+from plugins.ita_plugin import (
     ReservationReadError, read_reservation_detail, read_reservation_listing,
     read_reservation_date_diagnostic,
 )
@@ -62,9 +62,9 @@ class ReceiptGateError(ValueError):
 def source_fingerprint() -> str:
     digest = hashlib.sha256()
     for name in (
-        "tools/debug_ita_reservation.py", "plugins/ita_reservation.py",
-        "plugins/ita_booking_final.py", "plugins/ita_plugin.py", "plugins/ita_protocol.py",
-        "plugins/ita_calendar_query.py", "plugins/ita_calendar_book.py",
+        "tools/debug_ita_reservation.py", "plugins/ita_plugin.py",
+        "plugins/ita_plugin.py", "plugins/ita_plugin.py", "plugins/ita_plugin.py",
+        "plugins/ita_plugin.py", "plugins/ita_plugin.py",
         "tools/debug_ita_session.py", "tools/debug_ita_calendar_gate.py",
     ):
         digest.update(name.encode())

+ 1 - 1
tools/debug_ita_soak.py

@@ -45,7 +45,7 @@ from tools.debug_ita_session import (
     DebugConfigurationError,
     resolve_chrome_path,
 )
-from plugins.ita_calendar_query import CalendarGateError, guard_calendar
+from plugins.ita_plugin import CalendarGateError, guard_calendar
 from toolkit.backoff import ExponentialBackoff
 from vs_types import BizLogicError, PermissionDeniedError, RateLimiteddError, SessionExpiredOrInvalidError
 

+ 3 - 3
tools/ita_final_evidence.py

@@ -12,12 +12,12 @@ import json
 import os
 from pathlib import Path
 
-from plugins.ita_booking_final import (
+from plugins.ita_plugin import (
     FinalBookingAttempt, FinalBookingError, FinalOutcomeUnknown, NativeFinalSubmitter,
     ReservationState, SubmissionSignal, VerifiedSubmission,
 )
-from plugins.ita_calendar_book import verify_precommit_selection
-from plugins.ita_final_read_port import FinalReceiptReadPort, _cancelled_record
+from plugins.ita_plugin import verify_precommit_selection
+from plugins.ita_plugin import FinalReceiptReadPort, _cancelled_record
 from tools.ita_local_handoff import ITA_LOCAL_HANDOFF_ROOT, _ensure_private_directory
 
 

+ 65 - 22
tools/ita_query_book_local.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 from contextlib import ExitStack, contextmanager
 import copy
+from dataclasses import asdict, is_dataclass
 import hashlib
 import json
 import os
@@ -28,23 +29,21 @@ import redis
 import configure
 from booker import OrderBookerGCO
 from sentinel import SentinelGCO
-from plugins.ita_calendar_book import book_date_preferences, read_calendar_service, verify_precommit_selection
-from plugins.ita_calendar_session import CalendarRequestAudit
-from plugins.ita_otp import validate_cloud_otp_environment, validate_cloud_otp_logging
+from plugins.ita_plugin import book_date_preferences
+from plugins.ita_plugin import CalendarRequestAudit
+from plugins.ita_plugin import validate_cloud_otp_environment, validate_cloud_otp_logging
 from plugins.ita_plugin import (
     BOOKING_CALENDAR_PREFINAL_STOP_LABEL, BOOKING_RECHECK_NONE_AVAILABLE_LABEL,
     PERSISTENT_BROWSER_PROFILE_KEY,
 )
-from plugins.ita_protocol import ItaCapability, resolve_route_config
-from plugins.ita_booking_final import FinalBookingError, FinalOutcomeUnknown
-from plugins import ita_workflow
+from plugins.ita_plugin import ItaCapability, resolve_route_config
 from tools.ita_final_evidence import claim_once, require_unused_claim
 from tools.ita_local_handoff import ITA_LOCAL_HANDOFF_ROOT
 from toolkit.vs_cloud_api import VSCloudApi
 from tools.debug_ita_session import _get_credentials, resolve_chrome_path
 from tools.plugin_tester import PluginTester
 from utils.local_account import load_local_account
-from vs_types import AvailabilityStatus, GroupConfig, VSAccount
+from vs_types import AvailabilityStatus, BookingOutcomeUnknownError, GroupConfig, VSAccount
 
 
 CONTRACT = "existing-framework-local-prefinal-v1"
@@ -60,6 +59,34 @@ def emit(event, **fields):
     print("ITA_QUERY_BOOK_" + event + "=" + json.dumps(fields, sort_keys=True), flush=True)
 
 
+def runtime_namespace(plugin):
+    """The factory may replace sys.modules['ita_plugin'] for another instance.
+
+    Resolve through this instance's class, not a canonical import or the latest
+    module cache. Diagnostic hooks must instrument the code actually executing.
+    """
+    return type(plugin).book.__globals__
+
+
+def verify_plugin_selection(plugin):
+    runtime = runtime_namespace(plugin)
+    return runtime["verify_precommit_selection"](
+        plugin.page, runtime_service=runtime["read_calendar_service"](plugin.page),
+        approval=plugin.last_booking_precommit,
+    )
+
+
+@contextmanager
+def replace_runtime_symbol(namespace, name, value):
+    """Restore only the instrumented function, not other live module state."""
+    original = namespace[name]
+    namespace[name] = value
+    try:
+        yield
+    finally:
+        namespace[name] = original
+
+
 def load_settings(args):
     validate_cloud_otp_logging()
     if configure.TEST_ACCOUNT:
@@ -128,14 +155,16 @@ class LocalFinalSubmission:
         require_unused_claim(self.claim_path)  # Before browser/pool allocation.
 
     def submit(self, plugin, route, observed, production_submit):
-        if (self.used or route != self.route or observed.get("book") is None
+        same_route = route == self.route or (
+            is_dataclass(route) and is_dataclass(self.route) and asdict(route) == asdict(self.route))
+        if (self.used or not same_route or observed.get("book") is None
                 or observed["book"].plugin is not plugin
                 or plugin.config.account.username.strip().casefold() != self.username):
             raise LocalAcceptanceError("final_applicant_or_route_changed")
         self.used = True
         require_unused_claim(self.claim_path)
         approval = plugin.last_booking_precommit
-        verify_precommit_selection(plugin.page, runtime_service=read_calendar_service(plugin.page), approval=approval)
+        verify_plugin_selection(plugin)
         slot = approval.candidate
         self.selection = {"selectionVerified": True, "selectedDate": slot.day.isoformat(), "selectedTime": slot.time_label}
         emit("FINAL_TARGET", **self.selection, routingKey=route.routing_key, serviceId=route.service_id,
@@ -143,7 +172,8 @@ class LocalFinalSubmission:
 
         # Only wrap native dispatch. The production core FIRST reads a fresh
         # receipt baseline and rejects active/waitlist/unknown history.
-        native_factory = ita_workflow.NativeFinalSubmitter
+        runtime = runtime_namespace(plugin)
+        native_factory = runtime["NativeFinalSubmitter"]
         owner = self
 
         class FencedNative:
@@ -162,18 +192,18 @@ class LocalFinalSubmission:
                 for item in observed.values():
                     if item.audit.settled_snapshot()["finalRequests"] != 0:
                         raise LocalAcceptanceError("unexpected_final_request_do_not_rerun")
-                verify_precommit_selection(plugin.page, runtime_service=read_calendar_service(plugin.page), approval=approval)
+                verify_plugin_selection(plugin)
                 claim_once(owner.claim_path)
                 owner.possibly_submitted = True
                 emit("FINAL_DISPATCH", automaticRetry=False, possiblySubmitted=True)
                 return self.native()
 
-        with patch.object(ita_workflow, "NativeFinalSubmitter", FencedNative):
+        with replace_runtime_symbol(runtime, "NativeFinalSubmitter", FencedNative):
             try:
                 # This observer already owns the page's passive callback.
                 # Lend it to production final; keep coverage through cleanup.
                 return production_submit(plugin, route, request_audit=observed["book"].audit)
-            except FinalBookingError:
+            except runtime["FinalBookingError"]:
                 self.failure_reason = "receipt_baseline_or_final_context_rejected"
                 raise
 
@@ -330,7 +360,7 @@ class ObservedPlugin:
             return self.result
         except Exception as exc:
             self.error = type(exc).__name__
-            if isinstance(exc, FinalOutcomeUnknown):
+            if isinstance(exc, BookingOutcomeUnknownError):
                 raise  # Preserve the native Booker's pause-on-unknown branch.
             raise LocalAcceptanceError(self.role + "_operation_failed") from None
 
@@ -348,7 +378,7 @@ class ObservedPlugin:
         self.cleanup_ok = True
 
 
-def observe_factory(gco, role, stack, observed):
+def observe_factory(gco, role, stack, observed, on_created=None):
     factory_create = gco.m_factory.create
     cfg = gco.m_cfg.plugin_config
     gco.m_factory.register_plugin(cfg.plugin_name, str(ROOT / "plugins/ita_plugin.py"), "ItaPlugin")
@@ -356,6 +386,8 @@ def observe_factory(gco, role, stack, observed):
     def create(*args):
         instance = ObservedPlugin(factory_create(*args), role)
         observed[role] = instance
+        if on_created is not None:
+            on_created(instance.plugin)
         return instance
 
     stack.enter_context(patch.object(gco.m_factory, "create", side_effect=create))
@@ -393,10 +425,21 @@ def run_framework_once(query_group, book_group, route, cloud, redis_config, *, f
         # implementation methods, signal serialization, filtering or TTL.
         for cls in (SentinelGCO, OrderBookerGCO):
             stack.enter_context(patch.dict(cls.__init__.__globals__, {"VSCloudApi": boundary}))
-        production_submit = ita_workflow.submit_final
-        stack.enter_context(patch.object(ita_workflow, "submit_final", side_effect=(
-            lambda plugin, actual_route: final_control.submit(plugin, actual_route, observed, production_submit)
-        ) if final_control else LocalAcceptanceError("final_submission_forbidden")))
+        instrumented = set()
+
+        def instrument_final(plugin):
+            runtime = runtime_namespace(plugin)
+            if id(runtime) in instrumented:
+                return  # Offline fixtures can share a module; real factories need not.
+            production_submit = runtime["submit_final"]
+
+            def submit(actual_plugin, actual_route):
+                if final_control is None:
+                    raise LocalAcceptanceError("final_submission_forbidden")
+                return final_control.submit(actual_plugin, actual_route, observed, production_submit)
+
+            stack.enter_context(replace_runtime_symbol(runtime, "submit_final", submit))
+            instrumented.add(id(runtime))
         sentinel = SentinelGCO(query_group, redis_config, framework_log)
         booker = OrderBookerGCO(book_group, redis_config, framework_log)
         # Block reporting BEFORE the shared asynchronous executor can enqueue
@@ -419,8 +462,8 @@ def run_framework_once(query_group, book_group, route, cloud, redis_config, *, f
             cloud.update_vas_task = local_pause
             stack.callback(cloud.__dict__.pop, "update_vas_task", None)
         gc_objects.extend((sentinel, booker))
-        observe_factory(sentinel, "query", stack, observed)
-        observe_factory(booker, "book", stack, observed)
+        observe_factory(sentinel, "query", stack, observed, on_created=instrument_final)
+        observe_factory(booker, "book", stack, observed, on_created=instrument_final)
         signal_key = sentinel._get_redis_key(route.routing_key)
         published_digest = None
         original_setex, original_get = sentinel.redis_client.setex, booker.redis_client.get
@@ -504,7 +547,7 @@ def run_framework_once(query_group, book_group, route, cloud, redis_config, *, f
                 elif (book.result is not None and book.result.success is False
                       and book.result.label == BOOKING_CALENDAR_PREFINAL_STOP_LABEL):
                     approval = book.last_booking_precommit
-                    verify_precommit_selection(book.page, runtime_service=read_calendar_service(book.page), approval=approval)
+                    verify_plugin_selection(book.plugin)
                     report.update(selectionVerified=True, selectedDate=approval.candidate.day.isoformat(),
                                   selectedTime=approval.candidate.time_label, outcome="pre_final")
                 elif book.result is not None and book.result.success:

Some files were not shown because too many files changed in this diff