blun-king-cli 9.1.597 → 9.1.600

package/standard-skills/translate-native/integrations/website_localization_cms_source_runtime.py

@@ -2,13 +2,16 @@
 """Owned, durable runtime for the source side of the CMS localization API.
 
 The composition root validates the complete service configuration before it
-opens three private SQLite databases. One runtime belongs to one process and
-serializes every local state transition. Separate processes may safely open
-the same files because the underlying outboxes and monitor use durable leases.
+opens three private SQLite databases. An explicit production preflight can
+also verify both CMS capability pins before persistence and durably bind the
+verified pair plus each database role. One runtime belongs to one process and
+serializes every local state transition. Separate processes may safely open the
+same files because the underlying outboxes and monitor use durable leases.
 """
 
 from __future__ import annotations
 
+import hashlib
 import importlib.util
 import math
 import os
@@ -42,6 +45,30 @@ _HTTP = _load_module(
 )
 
 
+CAPABILITY_BINDING_SCHEMA = "blun.cms-source-runtime-capability-binding.v1"
+CAPABILITY_BINDING_TABLE = "cms_source_runtime_capability_binding"
+CAPABILITY_DATABASE_ROLES = ("changes", "removals", "lifecycle")
+CAPABILITY_BINDING_SQL = (
+    "CREATE TABLE cms_source_runtime_capability_binding ("
+    "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), "
+    "schema TEXT NOT NULL CHECK ("
+    "schema = 'blun.cms-source-runtime-capability-binding.v1'), "
+    "database_role TEXT NOT NULL CHECK ("
+    "database_role IN ('changes', 'removals', 'lifecycle')), "
+    "capabilities_sha256 TEXT NOT NULL, "
+    "commercial_rendering_registry_sha256 TEXT NOT NULL, "
+    "binding_sha256 TEXT NOT NULL)"
+)
+CAPABILITY_BINDING_COLUMNS = (
+    ("singleton", "INTEGER", 0, 1),
+    ("schema", "TEXT", 1, 0),
+    ("database_role", "TEXT", 1, 0),
+    ("capabilities_sha256", "TEXT", 1, 0),
+    ("commercial_rendering_registry_sha256", "TEXT", 1, 0),
+    ("binding_sha256", "TEXT", 1, 0),
+)
+
+
 class DurableCMSSourceRuntimeBlocked(RuntimeError):
     """Stable runtime failure that contains no path, credential, or content."""
 
@@ -240,6 +267,204 @@ def _preflight_service(
             connection.close()
 
 
+def _sha256(value: Any) -> str | None:
+    if (
+        isinstance(value, str)
+        and len(value) == 64
+        and all(character in "0123456789abcdef" for character in value)
+    ):
+        return value
+    return None
+
+
+def _preflight_capabilities(client: Any) -> tuple[str, str]:
+    """Verify both deployment pins through one bounded capability request."""
+
+    try:
+        capabilities_sha256 = _sha256(
+            getattr(client, "capabilities_sha256", None),
+        )
+        rendering_sha256 = _sha256(
+            getattr(client, "commercial_rendering_registry_sha256", None),
+        )
+        capabilities = getattr(client, "capabilities", None)
+    except Exception as error:
+        raise _blocked("source_runtime.capability_preflight_failed") from error
+    if (
+        capabilities_sha256 is None
+        or rendering_sha256 is None
+        or not callable(capabilities)
+    ):
+        raise _blocked("source_runtime.capability_pins_required")
+    try:
+        response = capabilities()
+    except Exception as error:
+        if getattr(error, "code", None) in {
+            "capabilities_pin_mismatch",
+            "commercial_rendering_registry_pin_mismatch",
+        }:
+            raise _blocked("source_runtime.capability_pin_mismatch") from error
+        raise _blocked("source_runtime.capability_preflight_failed") from error
+    try:
+        capability_payload = response["capabilities"]
+        client_type = _SERVICE._DISPATCH._CLIENT.CMSLocalizationHTTPClient
+        valid = (
+            isinstance(response, Mapping)
+            and client_type._valid_capabilities(response)
+            and capability_payload["sha256"] == capabilities_sha256
+            and capability_payload["commercial_rendering_registry"]["sha256"]
+            == rendering_sha256
+        )
+    except Exception:
+        valid = False
+    if not valid:
+        raise _blocked("source_runtime.capability_preflight_failed")
+    return capabilities_sha256, rendering_sha256
+
+
+def _capability_binding_row(
+    role: str,
+    binding: tuple[str, str],
+) -> tuple[Any, ...]:
+    capabilities_sha256, rendering_sha256 = binding
+    digest = hashlib.sha256("\x00".join((
+        CAPABILITY_BINDING_SCHEMA,
+        role,
+        capabilities_sha256,
+        rendering_sha256,
+    )).encode("utf-8")).hexdigest()
+    return (
+        1,
+        CAPABILITY_BINDING_SCHEMA,
+        role,
+        capabilities_sha256,
+        rendering_sha256,
+        digest,
+    )
+
+
+def _capability_table_exists(connection: sqlite3.Connection) -> bool:
+    rows = connection.execute(
+        "SELECT type, name, tbl_name, sql FROM sqlite_master WHERE name = ?",
+        (CAPABILITY_BINDING_TABLE,),
+    ).fetchall()
+    if not rows:
+        return False
+    if len(rows) != 1 or tuple(rows[0]) != (
+        "table",
+        CAPABILITY_BINDING_TABLE,
+        CAPABILITY_BINDING_TABLE,
+        CAPABILITY_BINDING_SQL,
+    ):
+        raise _blocked("source_runtime.capability_database_invalid")
+    return True
+
+
+def _validate_capability_database(
+    connection: sqlite3.Connection,
+    role: str,
+    binding: tuple[str, str],
+) -> None:
+    try:
+        if not _capability_table_exists(connection):
+            raise _blocked("source_runtime.capability_database_unbound")
+        columns = tuple(
+            (row[1], row[2], row[3], row[5])
+            for row in connection.execute(
+                f"PRAGMA table_info({CAPABILITY_BINDING_TABLE})"
+            ).fetchall()
+        )
+        rows = connection.execute(
+            f"SELECT singleton, schema, database_role, capabilities_sha256, "
+            f"commercial_rendering_registry_sha256, binding_sha256 "
+            f"FROM {CAPABILITY_BINDING_TABLE}"
+        ).fetchall()
+    except DurableCMSSourceRuntimeBlocked:
+        raise
+    except sqlite3.Error as error:
+        raise _blocked("source_runtime.capability_database_invalid") from error
+    if columns != CAPABILITY_BINDING_COLUMNS or len(rows) != 1:
+        raise _blocked("source_runtime.capability_database_invalid")
+    if tuple(rows[0]) != _capability_binding_row(role, binding):
+        raise _blocked("source_runtime.capability_database_mismatch")
+
+
+def _unbound_database_has_work(connection: sqlite3.Connection) -> bool:
+    try:
+        tables = connection.execute(
+            "SELECT name FROM sqlite_master "
+            "WHERE type = 'table' AND name LIKE 'cms_source_%' "
+            "AND name <> ? ORDER BY name",
+            (CAPABILITY_BINDING_TABLE,),
+        ).fetchall()
+        for (name,) in tables:
+            if (
+                not isinstance(name, str)
+                or not name.startswith("cms_source_")
+                or any(
+                    character not in "abcdefghijklmnopqrstuvwxyz_"
+                    for character in name
+                )
+            ):
+                raise _blocked("source_runtime.capability_database_invalid")
+            if name.endswith("_meta"):
+                continue
+            if connection.execute(
+                f'SELECT 1 FROM "{name}" LIMIT 1'
+            ).fetchone() is not None:
+                return True
+    except DurableCMSSourceRuntimeBlocked:
+        raise
+    except sqlite3.Error as error:
+        raise _blocked("source_runtime.capability_database_invalid") from error
+    return False
+
+
+def _precheck_capability_databases(
+    connections: tuple[sqlite3.Connection, ...],
+    binding: tuple[str, str],
+) -> None:
+    for role, connection in zip(CAPABILITY_DATABASE_ROLES, connections):
+        try:
+            exists = _capability_table_exists(connection)
+        except sqlite3.Error as error:
+            raise _blocked(
+                "source_runtime.capability_database_invalid",
+            ) from error
+        if exists:
+            _validate_capability_database(connection, role, binding)
+        elif _unbound_database_has_work(connection):
+            raise _blocked("source_runtime.capability_database_unbound")
+
+
+def _bind_capability_databases(
+    connections: tuple[sqlite3.Connection, ...],
+    binding: tuple[str, str],
+) -> None:
+    for role, connection in zip(CAPABILITY_DATABASE_ROLES, connections):
+        try:
+            connection.execute("BEGIN IMMEDIATE")
+            if not _capability_table_exists(connection):
+                connection.execute(CAPABILITY_BINDING_SQL)
+            connection.execute(
+                f"INSERT OR IGNORE INTO {CAPABILITY_BINDING_TABLE} VALUES "
+                "(?, ?, ?, ?, ?, ?)",
+                _capability_binding_row(role, binding),
+            )
+            _validate_capability_database(connection, role, binding)
+            connection.commit()
+        except DurableCMSSourceRuntimeBlocked:
+            if connection.in_transaction:
+                connection.rollback()
+            raise
+        except sqlite3.Error as error:
+            if connection.in_transaction:
+                connection.rollback()
+            raise _blocked(
+                "source_runtime.capability_database_invalid",
+            ) from error
+
+
 class DurableCMSSourceRuntime:
     """One process-owned and thread-safe source-CMS service runtime."""
 
@@ -249,10 +474,12 @@ class DurableCMSSourceRuntime:
         guards: tuple[Callable[[], None], Callable[[], None], Callable[[], None]],
         service: Any,
         http_authenticator: Callable[[dict[str, Any]], Any] | None,
+        capability_binding: tuple[str, str] | None,
     ):
         self._connections = connections
         self._guards = guards
         self._service = service
+        self._capability_binding = capability_binding
         self._lock = threading.RLock()
         self._closed = False
         self._owner_pid = os.getpid()
@@ -288,11 +515,46 @@ class DurableCMSSourceRuntime:
         for guard in self._guards:
             guard()
 
+    def _guard_capability_binding(self) -> None:
+        if self._capability_binding is None:
+            return
+        expected_capabilities, expected_rendering = self._capability_binding
+        try:
+            current_capabilities = _sha256(getattr(
+                self._service.client,
+                "capabilities_sha256",
+                None,
+            ))
+            current_rendering = _sha256(getattr(
+                self._service.client,
+                "commercial_rendering_registry_sha256",
+                None,
+            ))
+        except Exception as error:
+            raise _blocked(
+                "source_runtime.capability_binding_changed",
+            ) from error
+        if (
+            current_capabilities != expected_capabilities
+            or current_rendering != expected_rendering
+        ):
+            raise _blocked("source_runtime.capability_binding_changed")
+        for role, connection in zip(
+            CAPABILITY_DATABASE_ROLES,
+            self._connections,
+        ):
+            _validate_capability_database(
+                connection,
+                role,
+                self._capability_binding,
+            )
+
     def _call(self, name: str, *args: Any, **kwargs: Any) -> Any:
         self._assert_owner()
         with self._lock:
             if self._closed:
                 raise _blocked("source_runtime.closed")
+            self._guard_capability_binding()
             self._guard_databases()
             try:
                 result = getattr(self._service, name)(*args, **kwargs)
@@ -321,6 +583,31 @@ class DurableCMSSourceRuntime:
     def health(self) -> Any:
         return self._call("health")
 
+    def capability_binding(self) -> dict[str, Any]:
+        """Return the content-free startup capability verification state."""
+
+        self._assert_owner()
+        with self._lock:
+            if self._closed:
+                raise _blocked("source_runtime.closed")
+            self._guard_capability_binding()
+            if self._capability_binding is None:
+                return {
+                    "schema": "blun.cms-source-capability-binding.v2",
+                    "status": "not_configured",
+                    "capabilities_sha256": None,
+                    "commercial_rendering_registry_sha256": None,
+                    "database_roles": [],
+                }
+            capabilities_sha256, rendering_sha256 = self._capability_binding
+            return {
+                "schema": "blun.cms-source-capability-binding.v2",
+                "status": "verified",
+                "capabilities_sha256": capabilities_sha256,
+                "commercial_rendering_registry_sha256": rendering_sha256,
+                "database_roles": list(CAPABILITY_DATABASE_ROLES),
+            }
+
     @staticmethod
     def _loop_delays(
         active_delay_seconds: float | int,
@@ -402,6 +689,7 @@ class DurableCMSSourceRuntime:
                 return
             if self._worker_state in {"stopping", "failed"}:
                 raise _blocked("source_runtime.worker_blocked")
+            self._guard_capability_binding()
             self._guard_databases()
             stop = threading.Event()
             thread = threading.Thread(
@@ -554,6 +842,7 @@ def open_durable_cms_source(
     lifecycle_worker_id: str,
     terminal_notifier: Callable[[Mapping[str, Any]], Any] | None = None,
     terminal_status_reader: Callable[[str, str], Any] | None = None,
+    terminal_receiver_capabilities_sha256: str | None = None,
     notification_worker_id: str | None = None,
     http_authenticator: Callable[[dict[str, Any]], Any] | None = None,
     clock: Callable[[], float | int] = time.time,
@@ -576,21 +865,33 @@ def open_durable_cms_source(
     terminal_processing_poll_interval_seconds: float | int = 30,
     terminal_processing_base_delay_seconds: float | int = 5,
     terminal_processing_max_delay_seconds: float | int = 300,
+    capability_preflight: bool = False,
 ) -> DurableCMSSourceRuntime:
-    """Validate and open the complete durable source-side CMS worker."""
+    """Validate and open the complete durable source-side CMS worker.
+
+    Set ``capability_preflight`` to require both client deployment pins and one
+    successful, exact capability read before any persistent database exists.
+    """
 
     paths = tuple(_database_path(value) for value in (
         change_database, removal_database, lifecycle_database,
     ))
     timeout = _sqlite_timeout(sqlite_timeout_seconds)
+    if not isinstance(capability_preflight, bool):
+        raise _blocked("source_runtime.capability_preflight_invalid")
     if http_authenticator is not None and not callable(http_authenticator):
         raise _blocked("source_runtime.http_authenticator_invalid")
+    if http_authenticator is not None and not capability_preflight:
+        raise _blocked("source_runtime.capability_preflight_required")
     service_options = {
         "change_worker_id": change_worker_id,
         "removal_worker_id": removal_worker_id,
         "lifecycle_worker_id": lifecycle_worker_id,
         "terminal_notifier": terminal_notifier,
         "terminal_status_reader": terminal_status_reader,
+        "terminal_receiver_capabilities_sha256": (
+            terminal_receiver_capabilities_sha256
+        ),
         "notification_worker_id": notification_worker_id,
         "clock": clock,
         "change_lease_seconds": change_lease_seconds,
@@ -620,6 +921,9 @@ def open_durable_cms_source(
     }
     _preflight_service(client, service_options)
     _validate_paths(paths)
+    capability_binding = (
+        _preflight_capabilities(client) if capability_preflight else None
+    )
     guards = tuple(_prepare_database_file(path) for path in paths)
     connections: list[sqlite3.Connection] = []
     try:
@@ -632,11 +936,21 @@ def open_durable_cms_source(
             ))
         for guard in guards:
             guard()
+        if capability_binding is not None:
+            _precheck_capability_databases(
+                tuple(connections),
+                capability_binding,
+            )
         service = _SERVICE.CMSLocalizationSourceService(
             *connections,
             client,
             **service_options,
         )
+        if capability_binding is not None:
+            _bind_capability_databases(
+                tuple(connections),
+                capability_binding,
+            )
         for guard in guards:
             guard()
     except Exception as error:
@@ -650,6 +964,7 @@ def open_durable_cms_source(
         raise _blocked("source_runtime.initialization_failed") from error
     return DurableCMSSourceRuntime(
         tuple(connections), guards, service, http_authenticator,
+        capability_binding,
     )
 
 

package/standard-skills/translate-native/integrations/website_localization_cms_source_service.py

@@ -23,8 +23,8 @@ from typing import Any, Callable, Mapping
 
 
 SCHEMA = "blun.cms-source-service-tick.v1"
-HEALTH_SCHEMA = "blun.cms-source-service-health.v3"
-STATUS_SCHEMA = "blun.cms-source-service-status.v3"
+HEALTH_SCHEMA = "blun.cms-source-service-health.v4"
+STATUS_SCHEMA = "blun.cms-source-service-status.v4"
 TOKEN = re.compile(r"^[A-Za-z0-9_.:-]{1,256}$")
 ERROR_CODE = re.compile(r"^[a-z][a-z0-9_.-]{0,127}$")
 
@@ -96,6 +96,7 @@ class CMSSourceServiceHealth:
     lifecycle: Mapping[str, Any]
     notifications: Mapping[str, Any]
     terminal_processing: Mapping[str, Any]
+    terminal_receiver_capabilities_sha256: str | None
     error_code: str | None = None
 
     def as_payload(self) -> dict[str, Any]:
@@ -114,6 +115,9 @@ class CMSSourceServiceHealth:
             "lifecycle": dict(self.lifecycle),
             "notifications": dict(self.notifications),
             "terminal_processing": dict(self.terminal_processing),
+            "terminal_receiver_capabilities_sha256": (
+                self.terminal_receiver_capabilities_sha256
+            ),
             "error_code": self.error_code,
         }
 
@@ -147,6 +151,7 @@ class CMSSourceServiceStatus:
     notification_attempts: int
     notification_max_attempts: int | None
     notification_error_code: str | None
+    terminal_receiver_capabilities_sha256: str | None
     terminal_processing_state: str
     terminal_processing_poll_attempts: int
     terminal_processing_failures: int
@@ -186,6 +191,9 @@ class CMSSourceServiceStatus:
             "notification_attempts": self.notification_attempts,
             "notification_max_attempts": self.notification_max_attempts,
             "notification_error_code": self.notification_error_code,
+            "terminal_receiver_capabilities_sha256": (
+                self.terminal_receiver_capabilities_sha256
+            ),
             "terminal_processing_state": self.terminal_processing_state,
             "terminal_processing_poll_attempts": (
                 self.terminal_processing_poll_attempts
@@ -263,6 +271,7 @@ class CMSLocalizationSourceService:
         lifecycle_worker_id: str,
         terminal_notifier: Callable[[Mapping[str, Any]], Any] | None = None,
         terminal_status_reader: Callable[[str, str], Any] | None = None,
+        terminal_receiver_capabilities_sha256: str | None = None,
         notification_worker_id: str | None = None,
         clock: Callable[[], float | int] = time.time,
         change_lease_seconds: float | int = 600,
@@ -305,6 +314,33 @@ class CMSLocalizationSourceService:
             terminal_notifier is None or not callable(terminal_status_reader)
         ):
             raise CMSSourceServiceBlocked("source_service.processing_monitor_invalid")
+        discovered_receiver_capabilities = None
+        if terminal_status_reader is not None:
+            try:
+                discovered_receiver_capabilities = getattr(
+                    terminal_notifier, "expected_capabilities_sha256", None,
+                )
+            except Exception as error:
+                raise CMSSourceServiceBlocked(
+                    "source_service.processing_capabilities_invalid"
+                ) from error
+            if terminal_receiver_capabilities_sha256 is None:
+                terminal_receiver_capabilities_sha256 = (
+                    discovered_receiver_capabilities
+                )
+            if (
+                not _PROCESSING._sha(terminal_receiver_capabilities_sha256)
+                or discovered_receiver_capabilities is not None
+                and discovered_receiver_capabilities
+                != terminal_receiver_capabilities_sha256
+            ):
+                raise CMSSourceServiceBlocked(
+                    "source_service.processing_capabilities_invalid"
+                )
+        elif terminal_receiver_capabilities_sha256 is not None:
+            raise CMSSourceServiceBlocked(
+                "source_service.processing_capabilities_invalid"
+            )
         if not callable(clock):
             raise CMSSourceServiceBlocked("source_service.clock_invalid")
         timeout = getattr(client, "timeout", None)
@@ -379,6 +415,13 @@ class CMSLocalizationSourceService:
         self.client = client
         self.terminal_notifier = terminal_notifier
         self.terminal_status_reader = terminal_status_reader
+        self.terminal_receiver_capabilities_sha256 = (
+            terminal_receiver_capabilities_sha256
+        )
+        self.terminal_receiver_capabilities_exposed = (
+            terminal_status_reader is not None
+            and discovered_receiver_capabilities is not None
+        )
 
         # All configuration is validated before the first schema write.
         for value, code in (
@@ -436,6 +479,7 @@ class CMSLocalizationSourceService:
             if terminal_status_reader is None
             else _PROCESSING.DurableTerminalProcessingMonitor(
                 lifecycle_connection,
+                terminal_receiver_capabilities_sha256,
                 poll_interval_seconds=terminal_processing_poll_interval_seconds,
                 base_delay_seconds=terminal_processing_base_delay_seconds,
                 max_delay_seconds=terminal_processing_max_delay_seconds,
@@ -459,6 +503,24 @@ class CMSLocalizationSourceService:
             raise CMSSourceServiceBlocked("source_service.clock_invalid")
         return float(value)
 
+    def _guard_terminal_receiver_capabilities(self) -> None:
+        if self.terminal_processing is None:
+            return
+        try:
+            current = getattr(
+                self.terminal_notifier, "expected_capabilities_sha256", None,
+            )
+        except Exception as error:
+            raise CMSSourceServiceBlocked(
+                "source_service.processing_capabilities_changed"
+            ) from error
+        if self.terminal_receiver_capabilities_exposed and (
+            current != self.terminal_receiver_capabilities_sha256
+        ):
+            raise CMSSourceServiceBlocked(
+                "source_service.processing_capabilities_changed"
+            )
+
     def enqueue_change(
         self,
         change: Mapping[str, Any],
@@ -481,6 +543,7 @@ class CMSLocalizationSourceService:
 
     def status(self, event_id: str, site_id: str) -> CMSSourceServiceStatus:
         """Return a content-free snapshot without repairing or leasing work."""
+        self._guard_terminal_receiver_capabilities()
         event_id = _identifier(event_id, "source_service.status_invalid")
         site_id = _identifier(site_id, "source_service.status_invalid")
         now = self._now()
@@ -629,6 +692,9 @@ class CMSLocalizationSourceService:
             notification_error_code=(
                 None if notification is None else notification.last_error_code
             ),
+            terminal_receiver_capabilities_sha256=(
+                self.terminal_receiver_capabilities_sha256
+            ),
             terminal_processing_state=terminal_processing_state,
             terminal_processing_poll_attempts=(
                 0 if terminal_processing is None
@@ -820,6 +886,7 @@ class CMSLocalizationSourceService:
     def run_once(self) -> CMSSourceTickOutcome:
         """Advance at most one external operation and one local handoff."""
         try:
+            self._guard_terminal_receiver_capabilities()
             now = self._now()
         except Exception as error:
             return self._outcome(
@@ -1037,6 +1104,7 @@ class CMSLocalizationSourceService:
 
     def health(self) -> CMSSourceServiceHealth:
         try:
+            self._guard_terminal_receiver_capabilities()
             now = self._now()
             changes = _health_payload(self.changes.health(now=now))
             removals = _health_payload(self.removals.health(now=now))
@@ -1080,6 +1148,7 @@ class CMSLocalizationSourceService:
                 {},
                 {},
                 {},
+                self.terminal_receiver_capabilities_sha256,
                 _safe_code(error, "source_service.health_blocked"),
             )
         blocked = any(
@@ -1121,5 +1190,6 @@ class CMSLocalizationSourceService:
             lifecycle,
             notifications,
             terminal_processing,
+            self.terminal_receiver_capabilities_sha256,
             error_code,
         )

package/standard-skills/translate-native/integrations/website_localization_cms_terminal_notification_http.py

@@ -18,6 +18,7 @@ from typing import Any, Callable, Mapping, Protocol
 NOTIFICATION_SCHEMA = "blun.cms-source-terminal-notification.v1"
 ACK_SCHEMA = "blun.cms-source-terminal-notification-ack.v1"
 AUTH_SCHEMA = "blun.cms-source-terminal-notification-http-auth.v1"
+CAPABILITIES_PRECONDITION_HEADER = "X-Localization-Capabilities-SHA256"
 MAX_BODY_BYTES = 16_384
 MAX_RESPONSE_BYTES = 8_192
 MAX_ENDPOINT_LENGTH = 2_048
@@ -35,6 +36,7 @@ RESERVED_HEADERS = {
     "idempotency-key", "transfer-encoding",
     "x-localization-terminal-notification-id",
     "x-localization-terminal-notification-sha256",
+    "x-localization-capabilities-sha256",
 }
 NOTIFICATION_FIELDS = {
     "schema", "notification_id", "event_id", "site_id", "plan_id",
@@ -326,6 +328,7 @@ class HTTPTerminalNotifierAdapter:
     def __init__(
         self,
         endpoint: str,
+        expected_capabilities_sha256: str,
         authentication_headers: Callable[
             [Mapping[str, Any]], Mapping[str, str]
         ],
@@ -339,6 +342,11 @@ class HTTPTerminalNotifierAdapter:
         self.endpoint, self.origin, self.path = _endpoint(
             endpoint, allow_loopback_http,
         )
+        if (
+            not isinstance(expected_capabilities_sha256, str)
+            or SHA256.fullmatch(expected_capabilities_sha256) is None
+        ):
+            raise ValueError("expected capability digest is invalid")
         if not callable(authentication_headers):
             raise TypeError("authentication_headers must be callable")
         if (
@@ -349,6 +357,7 @@ class HTTPTerminalNotifierAdapter:
         ):
             raise ValueError("timeout is outside the supported range")
         self.authentication_headers = authentication_headers
+        self.expected_capabilities_sha256 = expected_capabilities_sha256
         self.transport = URLTransport() if transport is None else transport
         if not callable(getattr(self.transport, "post", None)):
             raise TypeError("transport must provide post")
@@ -368,6 +377,7 @@ class HTTPTerminalNotifierAdapter:
             "event_id": payload["event_id"],
             "site_id": payload["site_id"],
             "body_sha256": body_sha256,
+            "capabilities_sha256": self.expected_capabilities_sha256,
         }
         headers = _authentication_headers(
             self.authentication_headers, authentication,
@@ -378,6 +388,9 @@ class HTTPTerminalNotifierAdapter:
             "Idempotency-Key": payload["notification_id"],
             "X-Localization-Terminal-Notification-Id": payload["notification_id"],
             "X-Localization-Terminal-Notification-Sha256": body_sha256,
+            CAPABILITIES_PRECONDITION_HEADER: (
+                self.expected_capabilities_sha256
+            ),
         })
         try:
             result = self.transport.post(