blun-king-cli 9.1.597 → 9.1.600

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

@@ -25,6 +25,56 @@ from typing import Any, Callable, Iterator, Mapping
 
 
 SCHEMA_VERSION = 1
+CAPABILITY_BINDING_SCHEMA = (
+    "blun.cms-source-delivery-runtime-capability-binding.v2"
+)
+LEGACY_CAPABILITY_BINDING_SCHEMA = (
+    "blun.cms-source-delivery-runtime-capability-binding.v1"
+)
+CAPABILITY_BINDING_TABLE = "cms_source_delivery_runtime_capability_binding"
+CAPABILITY_DATABASE_ROLE = "source_delivery"
+CAPABILITY_BINDING_SQL = (
+    "CREATE TABLE cms_source_delivery_runtime_capability_binding ("
+    "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), "
+    "schema TEXT NOT NULL CHECK (schema = "
+    "'blun.cms-source-delivery-runtime-capability-binding.v2'), "
+    "database_role TEXT NOT NULL CHECK (database_role = 'source_delivery'), "
+    "delivery_capabilities_sha256 TEXT NOT NULL, "
+    "runtime_capabilities_sha256 TEXT NOT NULL, "
+    "commercial_rendering_registry_sha256 TEXT NOT NULL, "
+    "terminal_receiver_capabilities_sha256 TEXT NOT NULL, "
+    "binding_sha256 TEXT NOT NULL)"
+)
+LEGACY_CAPABILITY_BINDING_SQL = (
+    "CREATE TABLE cms_source_delivery_runtime_capability_binding ("
+    "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), "
+    "schema TEXT NOT NULL CHECK (schema = "
+    "'blun.cms-source-delivery-runtime-capability-binding.v1'), "
+    "database_role TEXT NOT NULL CHECK (database_role = 'source_delivery'), "
+    "delivery_capabilities_sha256 TEXT NOT NULL, "
+    "runtime_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),
+    ("delivery_capabilities_sha256", "TEXT", 1, 0),
+    ("runtime_capabilities_sha256", "TEXT", 1, 0),
+    ("commercial_rendering_registry_sha256", "TEXT", 1, 0),
+    ("terminal_receiver_capabilities_sha256", "TEXT", 1, 0),
+    ("binding_sha256", "TEXT", 1, 0),
+)
+LEGACY_CAPABILITY_BINDING_COLUMNS = (
+    ("singleton", "INTEGER", 0, 1),
+    ("schema", "TEXT", 1, 0),
+    ("database_role", "TEXT", 1, 0),
+    ("delivery_capabilities_sha256", "TEXT", 1, 0),
+    ("runtime_capabilities_sha256", "TEXT", 1, 0),
+    ("commercial_rendering_registry_sha256", "TEXT", 1, 0),
+    ("binding_sha256", "TEXT", 1, 0),
+)
 MAX_ATTEMPTS = 20
 MAX_LEASE_SECONDS = 86_400.0
 MAX_DELAY_SECONDS = 86_400.0
@@ -54,6 +104,59 @@ def _load_module(name: str, path: Path):
     return module
 
 
+def _capability_binding_row(
+    delivery_capabilities_sha256: str,
+    runtime_capabilities_sha256: str,
+    commercial_rendering_registry_sha256: str,
+    terminal_receiver_capabilities_sha256: str,
+) -> tuple[Any, ...]:
+    """Return the one canonical durable generation-binding row."""
+
+    binding_hash = hashlib.sha256("\x00".join((
+        CAPABILITY_BINDING_SCHEMA,
+        CAPABILITY_DATABASE_ROLE,
+        delivery_capabilities_sha256,
+        runtime_capabilities_sha256,
+        commercial_rendering_registry_sha256,
+        terminal_receiver_capabilities_sha256,
+    )).encode("utf-8")).hexdigest()
+    return (
+        1,
+        CAPABILITY_BINDING_SCHEMA,
+        CAPABILITY_DATABASE_ROLE,
+        delivery_capabilities_sha256,
+        runtime_capabilities_sha256,
+        commercial_rendering_registry_sha256,
+        terminal_receiver_capabilities_sha256,
+        binding_hash,
+    )
+
+
+def _legacy_capability_binding_row(
+    delivery_capabilities_sha256: str,
+    runtime_capabilities_sha256: str,
+    commercial_rendering_registry_sha256: str,
+) -> tuple[Any, ...]:
+    """Return the exact prior binding accepted only for an empty migration."""
+
+    binding_hash = hashlib.sha256("\x00".join((
+        LEGACY_CAPABILITY_BINDING_SCHEMA,
+        CAPABILITY_DATABASE_ROLE,
+        delivery_capabilities_sha256,
+        runtime_capabilities_sha256,
+        commercial_rendering_registry_sha256,
+    )).encode("utf-8")).hexdigest()
+    return (
+        1,
+        LEGACY_CAPABILITY_BINDING_SCHEMA,
+        CAPABILITY_DATABASE_ROLE,
+        delivery_capabilities_sha256,
+        runtime_capabilities_sha256,
+        commercial_rendering_registry_sha256,
+        binding_hash,
+    )
+
+
 _ROOT = Path(__file__).resolve().parents[1]
 _CLIENT = _load_module(
     "blun_website_localization_cms_source_delivery_client",
@@ -278,11 +381,38 @@ class DurableCMSSourceDeliveryOutbox:
         if not callable(clock):
             raise TypeError("clock must be callable")
         digest = getattr(client, "expected_capabilities_sha256", None)
+        legacy_digest = getattr(
+            client, "legacy_expected_capabilities_sha256", digest,
+        )
+        runtime_digest = getattr(
+            client, "expected_runtime_capabilities_sha256", None,
+        )
+        rendering_digest = getattr(
+            client, "expected_commercial_rendering_registry_sha256", None,
+        )
+        terminal_receiver_digest = getattr(
+            client, "expected_terminal_receiver_capabilities_sha256", None,
+        )
         if (
             not callable(getattr(client, "submit_change", None))
             or not callable(getattr(client, "submit_removal", None))
             or not isinstance(digest, str)
             or SHA256.fullmatch(digest) is None
+            or not isinstance(legacy_digest, str)
+            or SHA256.fullmatch(legacy_digest) is None
+            or len({
+                runtime_digest is None,
+                rendering_digest is None,
+                terminal_receiver_digest is None,
+            }) != 1
+            or runtime_digest is not None and (
+                not isinstance(runtime_digest, str)
+                or SHA256.fullmatch(runtime_digest) is None
+                or not isinstance(rendering_digest, str)
+                or SHA256.fullmatch(rendering_digest) is None
+                or not isinstance(terminal_receiver_digest, str)
+                or SHA256.fullmatch(terminal_receiver_digest) is None
+            )
         ):
             raise TypeError("client must provide the pinned source operations")
         timeout = getattr(client, "timeout", None)
@@ -297,6 +427,10 @@ class DurableCMSSourceDeliveryOutbox:
         self.connection.row_factory = sqlite3.Row
         self.client = client
         self.capabilities_sha256 = digest
+        self.legacy_capabilities_sha256 = legacy_digest
+        self.runtime_capabilities_sha256 = runtime_digest
+        self.commercial_rendering_registry_sha256 = rendering_digest
+        self.terminal_receiver_capabilities_sha256 = terminal_receiver_digest
         self.timeout = float(timeout)
         self.clock = clock
         self.base_delay_seconds = _duration(
@@ -311,6 +445,157 @@ class DurableCMSSourceDeliveryOutbox:
             raise CMSSourceDeliveryBlocked("source_delivery.delay_invalid")
         self._initialize()
 
+    def _capability_binding_row(self) -> tuple[Any, ...]:
+        if (
+            self.runtime_capabilities_sha256 is None
+            or self.commercial_rendering_registry_sha256 is None
+        ):
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_binding_required"
+            )
+        return _capability_binding_row(
+            self.capabilities_sha256,
+            self.runtime_capabilities_sha256,
+            self.commercial_rendering_registry_sha256,
+            self.terminal_receiver_capabilities_sha256,
+        )
+
+    def _capability_table_state(self) -> str:
+        try:
+            rows = self.connection.execute(
+                "SELECT type, name, tbl_name, sql FROM sqlite_master "
+                "WHERE name = ?",
+                (CAPABILITY_BINDING_TABLE,),
+            ).fetchall()
+        except sqlite3.Error as error:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_invalid"
+            ) from error
+        if not rows:
+            return "missing"
+        if len(rows) != 1:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_invalid"
+            )
+        row = tuple(rows[0])
+        current = (
+            "table", CAPABILITY_BINDING_TABLE,
+            CAPABILITY_BINDING_TABLE, CAPABILITY_BINDING_SQL,
+        )
+        legacy = (
+            "table", CAPABILITY_BINDING_TABLE,
+            CAPABILITY_BINDING_TABLE, LEGACY_CAPABILITY_BINDING_SQL,
+        )
+        if row == current:
+            return "current"
+        if row == legacy:
+            return "legacy"
+        raise CMSSourceDeliveryBlocked(
+            "source_delivery.capability_database_invalid"
+        )
+
+    def _validate_legacy_capability_database(self) -> None:
+        try:
+            columns = tuple(
+                (row[1], row[2], row[3], row[5])
+                for row in self.connection.execute(
+                    f"PRAGMA table_info({CAPABILITY_BINDING_TABLE})"
+                ).fetchall()
+            )
+            rows = self.connection.execute(
+                f"SELECT singleton, schema, database_role, "
+                f"delivery_capabilities_sha256, "
+                f"runtime_capabilities_sha256, "
+                f"commercial_rendering_registry_sha256, binding_sha256 "
+                f"FROM {CAPABILITY_BINDING_TABLE}"
+            ).fetchall()
+        except sqlite3.Error as error:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_invalid"
+            ) from error
+        expected = _legacy_capability_binding_row(
+            self.legacy_capabilities_sha256,
+            self.runtime_capabilities_sha256,
+            self.commercial_rendering_registry_sha256,
+        )
+        if (
+            columns != LEGACY_CAPABILITY_BINDING_COLUMNS
+            or len(rows) != 1
+            or tuple(rows[0]) != expected
+        ):
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_mismatch"
+            )
+
+    def _validate_capability_database(self) -> None:
+        configured = self.runtime_capabilities_sha256 is not None
+        state = self._capability_table_state()
+        if state == "missing":
+            if configured:
+                raise CMSSourceDeliveryBlocked(
+                    "source_delivery.capability_database_unbound"
+                )
+            return
+        if state != "current":
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_unbound"
+            )
+        if not configured:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_binding_required"
+            )
+        try:
+            columns = tuple(
+                (row[1], row[2], row[3], row[5])
+                for row in self.connection.execute(
+                    f"PRAGMA table_info({CAPABILITY_BINDING_TABLE})"
+                ).fetchall()
+            )
+            rows = self.connection.execute(
+                f"SELECT singleton, schema, database_role, "
+                f"delivery_capabilities_sha256, "
+                f"runtime_capabilities_sha256, "
+                f"commercial_rendering_registry_sha256, "
+                f"terminal_receiver_capabilities_sha256, binding_sha256 "
+                f"FROM {CAPABILITY_BINDING_TABLE}"
+            ).fetchall()
+        except sqlite3.Error as error:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_invalid"
+            ) from error
+        if columns != CAPABILITY_BINDING_COLUMNS or len(rows) != 1:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_invalid"
+            )
+        if tuple(rows[0]) != self._capability_binding_row():
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_database_mismatch"
+            )
+
+    def _guard_capability_binding(self) -> None:
+        if self.runtime_capabilities_sha256 is not None and (
+            getattr(
+                self.client, "expected_runtime_capabilities_sha256", None,
+            ) != self.runtime_capabilities_sha256
+            or getattr(
+                self.client,
+                "expected_commercial_rendering_registry_sha256",
+                None,
+            ) != self.commercial_rendering_registry_sha256
+            or getattr(
+                self.client, "expected_capabilities_sha256", None,
+            ) != self.capabilities_sha256
+            or getattr(
+                self.client,
+                "expected_terminal_receiver_capabilities_sha256",
+                None,
+            ) != self.terminal_receiver_capabilities_sha256
+        ):
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.capability_binding_changed"
+            )
+        self._validate_capability_database()
+
     def _now(self, value: float | int | None = None) -> float:
         try:
             supplied = self.clock() if value is None else value
@@ -381,6 +666,33 @@ class DurableCMSSourceDeliveryOutbox:
                     status, next_attempt_at, created_at, operation, request_id
                 )
             """)
+            if self.runtime_capabilities_sha256 is not None:
+                state = self._capability_table_state()
+                has_work = self.connection.execute(
+                    "SELECT 1 FROM cms_source_delivery_outbox LIMIT 1"
+                ).fetchone()
+                if state == "missing":
+                    if has_work is not None:
+                        raise CMSSourceDeliveryBlocked(
+                            "source_delivery.capability_database_unbound"
+                        )
+                    self.connection.execute(CAPABILITY_BINDING_SQL)
+                elif state == "legacy":
+                    if has_work is not None:
+                        raise CMSSourceDeliveryBlocked(
+                            "source_delivery.capability_database_unbound"
+                        )
+                    self._validate_legacy_capability_database()
+                    self.connection.execute(
+                        f"DROP TABLE {CAPABILITY_BINDING_TABLE}"
+                    )
+                    self.connection.execute(CAPABILITY_BINDING_SQL)
+                self.connection.execute(
+                    f"INSERT OR IGNORE INTO {CAPABILITY_BINDING_TABLE} "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    self._capability_binding_row(),
+                )
+            self._guard_capability_binding()
         self._validate_schema()
 
     def _validate_schema(self) -> None:
@@ -404,6 +716,54 @@ class DurableCMSSourceDeliveryOutbox:
             or columns != _COLUMNS
         ):
             raise CMSSourceDeliveryBlocked("source_delivery.schema_altered")
+        self._guard_capability_binding()
+
+    def capability_binding(self) -> dict[str, Any]:
+        """Return the content-free durable generation bound to this outbox."""
+
+        self._validate_schema()
+        if self.runtime_capabilities_sha256 is None:
+            return {
+                "schema": CAPABILITY_BINDING_SCHEMA,
+                "status": "not_configured",
+                "database_role": CAPABILITY_DATABASE_ROLE,
+                "delivery_capabilities_sha256": self.capabilities_sha256,
+                "runtime_capabilities_sha256": None,
+                "commercial_rendering_registry_sha256": None,
+                "terminal_receiver_capabilities_sha256": None,
+                "binding_sha256": None,
+            }
+        row = self._capability_binding_row()
+        return {
+            "schema": row[1],
+            "status": "verified",
+            "database_role": row[2],
+            "delivery_capabilities_sha256": row[3],
+            "runtime_capabilities_sha256": row[4],
+            "commercial_rendering_registry_sha256": row[5],
+            "terminal_receiver_capabilities_sha256": row[6],
+            "binding_sha256": row[7],
+        }
+
+    def _verified_source_binding(self, value: Any) -> dict[str, Any]:
+        try:
+            binding = _CLIENT._HTTP._capability_binding_payload(value)
+        except Exception:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.source_capability_binding_invalid"
+            ) from None
+        if (
+            self.runtime_capabilities_sha256 is None
+            or self.commercial_rendering_registry_sha256 is None
+            or binding["capabilities_sha256"]
+            != self.runtime_capabilities_sha256
+            or binding["commercial_rendering_registry_sha256"]
+            != self.commercial_rendering_registry_sha256
+        ):
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.source_capability_binding_invalid"
+            )
+        return binding
 
     def enqueue_change(
         self,
@@ -622,6 +982,164 @@ class DurableCMSSourceDeliveryOutbox:
             response_sha256=row["response_sha256"],
         )
 
+    def source_status(
+        self,
+        event_id: str,
+        site_id: str,
+        payload_sha256: str,
+    ) -> Mapping[str, Any]:
+        """Read downstream lifecycle only for an exact accepted submission."""
+
+        self._validate_schema()
+        event_id = _token(event_id, "source_delivery.status_invalid")
+        site_id = _token(site_id, "source_delivery.status_invalid")
+        payload_sha256 = _sha256(
+            payload_sha256, "source_delivery.status_invalid",
+        )
+        rows = self.connection.execute("""
+            SELECT * FROM cms_source_delivery_outbox
+            WHERE event_id = ? AND site_id = ? AND payload_sha256 = ?
+            ORDER BY created_at, operation, request_id
+        """, (event_id, site_id, payload_sha256)).fetchall()
+        if not rows:
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.status_not_found"
+            )
+        for row in rows:
+            self._validated_row(row)
+        if len(rows) != 1 or rows[0]["status"] != "succeeded":
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.source_status_unavailable"
+            )
+        client_status = getattr(self.client, "status", None)
+        if not callable(client_status):
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.client_failure"
+            )
+        try:
+            response = client_status(event_id, site_id)
+            if (
+                not isinstance(response, Mapping)
+                or set(response)
+                != {
+                    "schema", "status", "capabilities_sha256",
+                    "capability_binding",
+                }
+                or response.get("schema")
+                != _CLIENT._HTTP.STATUS_RESPONSE_SCHEMA
+                or response.get("capabilities_sha256")
+                != self.capabilities_sha256
+            ):
+                raise ValueError
+            normalized = _CLIENT._HTTP._source_status_payload(
+                _CLIENT._PayloadView(response["status"]),
+                expected_event_id=event_id,
+                expected_site_id=site_id,
+            )
+            if normalized != response["status"]:
+                raise ValueError
+            binding = self._verified_source_binding(
+                response["capability_binding"]
+            )
+        except Exception as error:
+            if getattr(error, "cms_source_client_failure", False) is True:
+                raise
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.source_status_invalid"
+            ) from None
+        return {
+            "schema": response["schema"],
+            "status": dict(normalized),
+            "capabilities_sha256": response["capabilities_sha256"],
+            "capability_binding": binding,
+        }
+
+    def source_readiness(self) -> Mapping[str, Any]:
+        """Read the pinned source-service readiness without changing work."""
+
+        self._validate_schema()
+        client_readiness = getattr(self.client, "readiness", None)
+        if not callable(client_readiness):
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.client_failure"
+            )
+        try:
+            response = client_readiness()
+            if (
+                not isinstance(response, Mapping)
+                or set(response)
+                != {
+                    "schema", "readiness", "capabilities_sha256",
+                    "capability_binding",
+                }
+                or response.get("schema")
+                != _CLIENT._HTTP.READINESS_RESPONSE_SCHEMA
+                or response.get("capabilities_sha256")
+                != self.capabilities_sha256
+            ):
+                raise ValueError
+            normalized = _CLIENT._HTTP._readiness_payload(
+                response["readiness"]
+            )
+            if normalized != response["readiness"]:
+                raise ValueError
+            binding = self._verified_source_binding(
+                response["capability_binding"]
+            )
+        except Exception as error:
+            if getattr(error, "cms_source_client_failure", False) is True:
+                raise
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.source_readiness_invalid"
+            ) from None
+        return {
+            "schema": response["schema"],
+            "readiness": dict(normalized),
+            "capabilities_sha256": response["capabilities_sha256"],
+            "capability_binding": binding,
+        }
+
+    def source_health(self) -> Mapping[str, Any]:
+        """Read the pinned source-service queue health without changing work."""
+
+        self._validate_schema()
+        client_health = getattr(self.client, "health", None)
+        if not callable(client_health):
+            raise CMSSourceDeliveryBlocked("source_delivery.client_failure")
+        try:
+            response = client_health()
+            if (
+                not isinstance(response, Mapping)
+                or set(response) != {
+                    "schema", "health", "capabilities_sha256",
+                    "capability_binding",
+                }
+                or response.get("schema") != _CLIENT._HTTP.HEALTH_RESPONSE_SCHEMA
+                or response.get("capabilities_sha256")
+                != self.capabilities_sha256
+            ):
+                raise ValueError
+            normalized = _CLIENT._HTTP._health_payload(
+                _CLIENT._PayloadView(response["health"])
+            )
+            if normalized != response["health"]:
+                raise ValueError
+            binding = self._verified_source_binding(
+                response["capability_binding"]
+            )
+        except Exception as error:
+            if getattr(error, "cms_source_client_failure", False) is True:
+                raise
+            raise CMSSourceDeliveryBlocked(
+                "source_delivery.source_health_invalid"
+            ) from None
+        return {
+            "schema": response["schema"],
+            "health": normalized,
+            "capabilities_sha256": response["capabilities_sha256"],
+            "capability_binding": binding,
+        }
+
     def claim(
         self,
         worker_id: str,
@@ -771,12 +1289,15 @@ class DurableCMSSourceDeliveryOutbox:
             if claim.operation == "change"
             else _CLIENT._HTTP.REMOVAL_RESPONSE_SCHEMA
         )
+        expected_fields = {
+            "schema", "operation", "request_id", "event_id",
+            "payload_sha256", "status", "attempts", "max_attempts",
+            "capabilities_sha256",
+        }
+        if self.runtime_capabilities_sha256 is not None:
+            expected_fields.add("capability_binding")
         if (
-            set(response) != {
-                "schema", "operation", "request_id", "event_id",
-                "payload_sha256", "status", "attempts", "max_attempts",
-                "capabilities_sha256",
-            }
+            set(response) != expected_fields
             or response.get("schema") != expected_schema
             or response.get("operation") != claim.operation
             or response.get("request_id") != claim.request_id
@@ -791,6 +1312,8 @@ class DurableCMSSourceDeliveryOutbox:
             or response.get("max_attempts") != claim.source_max_attempts
         ):
             raise CMSSourceDeliveryBlocked("source_delivery.response_invalid")
+        if self.runtime_capabilities_sha256 is not None:
+            self._verified_source_binding(response["capability_binding"])
         return response_json
 
     def complete(