nl2data-semantic-catalog-postgres 0.1.0__py3-none-any.whl

nl2data_semantic_catalog_postgres/__init__.py

@@ -0,0 +1,18 @@
+"""Optional durable PostgreSQL semantic catalog for nl2data-core.
+
+This package implements the core :class:`SemanticSnapshotCatalog` boundary
+with durable PostgreSQL storage for metadata snapshots, reviewed proposal
+sets, immutable Semantic Model Bundle publications, active pointers, and
+bounded lifecycle evidence.  It is optional: importing ``nl2data`` or
+``nl2data_core`` never requires PostgreSQL or psycopg, and the psycopg
+driver is loaded lazily only when a catalog is constructed from a DSN.
+
+The catalog persists only bounded canonical envelopes - never credentials,
+DSNs, raw prompts, raw queries/results, native driver objects, or
+unrestricted source values - and revalidates fingerprints, tenant/source
+scope, schema versions, and compatibility on every read and activation.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

nl2data_semantic_catalog_postgres/client.py

@@ -0,0 +1,139 @@
+"""Lazy optional psycopg driver boundary for the semantic catalog.
+
+The ``psycopg``/``psycopg_pool`` packages are loaded only inside this module
+through :func:`importlib.import_module`, so importing ``nl2data``,
+``nl2data_core``, or the catalog module never imports a database driver.
+The catalog accepts an injected pool (fake or host-managed) or a DSN; the
+DSN path is constructed here with bounded connect/command timeouts and a
+bounded pool, and DSNs are never included in errors.  Driver errors are
+classified by class name first (so injected fake clients work without the
+driver installed) and by the real driver only when present.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.util import find_spec
+from typing import Any, cast
+
+from .errors import SemanticCatalogError, SemanticCatalogErrorCode
+
+
+def driver_available() -> bool:
+    """Whether the optional ``psycopg`` driver (and pool) is installed."""
+    return find_spec("psycopg") is not None and find_spec("psycopg_pool") is not None
+
+
+def build_pool(
+    dsn: str,
+    *,
+    pool_size: int,
+    connect_timeout_seconds: float,
+    command_timeout_seconds: float,
+    acquire_timeout_seconds: float,
+    schema: str,
+) -> Any:
+    """Lazily import the driver and build a bounded PostgreSQL connection pool.
+
+    Every checkout is pinned to the configured schema namespace through the
+    connection ``options`` so all unqualified table names resolve inside the
+    deployment's own schema.  Raises a normalized ``CATALOG_UNAVAILABLE``
+    error when the driver is missing or the pool cannot be constructed; the
+    DSN and any driver exception text are never included in the error.
+    """
+    if not driver_available():
+        raise SemanticCatalogError(
+            SemanticCatalogErrorCode.CATALOG_UNAVAILABLE,
+            "the psycopg driver is not installed; install the "
+            "'nl2data-semantic-catalog-postgres' package",
+            details={"cause_type": "ImportError"},
+        )
+    try:
+        pool_module = cast(Any, import_module("psycopg_pool"))
+        driver = cast(Any, import_module("psycopg"))
+        pool = pool_module.ConnectionPool(
+            dsn,
+            min_size=1,
+            max_size=pool_size,
+            open=True,
+            timeout=acquire_timeout_seconds,
+            kwargs={
+                "connect_timeout": connect_timeout_seconds,
+                "options": f"-c search_path={schema}",
+                "row_factory": driver.rows.dict_row,
+            },
+        )
+    except SemanticCatalogError:
+        raise
+    except Exception as error:
+        raise SemanticCatalogError(
+            SemanticCatalogErrorCode.CATALOG_UNAVAILABLE,
+            "the PostgreSQL connection pool could not be constructed",
+            details={"cause_type": type(error).__name__},
+        ) from error
+    return pool
+
+
+def is_connect_error(error: BaseException) -> bool:
+    """Whether the exception signals a lost or unavailable connection."""
+    if error.__class__.__name__ in {
+        "OperationalError",
+        "InterfaceError",
+        "ConnectionError",
+        "PoolTimeout",
+        "PoolClosed",
+    }:
+        return True
+    try:
+        pool_module = cast(Any, import_module("psycopg_pool"))
+        if isinstance(error, pool_module.PoolTimeout):
+            return True
+    except ImportError:
+        pass
+    try:
+        exceptions = cast(Any, import_module("psycopg"))
+    except ImportError:
+        return False
+    return isinstance(
+        error, (exceptions.OperationalError, exceptions.InterfaceError)
+    )
+
+
+def is_timeout_error(error: BaseException) -> bool:
+    """Whether the exception signals a query canceled by its timeout."""
+    if error.__class__.__name__ in {
+        "TimeoutError",
+        "QueryCanceledError",
+        "QueryCanceled",
+        "Timeout",
+    }:
+        return True
+    try:
+        exceptions = cast(Any, import_module("psycopg.errors"))
+    except ImportError:
+        return False
+    return isinstance(error, exceptions.QueryCanceled)
+
+
+def is_duplicate_key_error(error: BaseException) -> bool:
+    """Whether the exception signals a unique-key violation."""
+    if error.__class__.__name__ in {"UniqueViolation", "IntegrityError"}:
+        return True
+    try:
+        exceptions = cast(Any, import_module("psycopg.errors"))
+    except ImportError:
+        return False
+    return isinstance(error, exceptions.UniqueViolation)
+
+
+def is_serialization_error(error: BaseException) -> bool:
+    """Whether the exception signals a retryable transaction conflict."""
+    if error.__class__.__name__ in {"SerializationFailure", "DeadlockDetected"}:
+        return True
+    try:
+        exceptions = cast(Any, import_module("psycopg.errors"))
+    except ImportError:
+        return False
+    return isinstance(
+        error, (exceptions.SerializationFailure, exceptions.DeadlockDetected)
+    )

nl2data_semantic_catalog_postgres/config.py

@@ -0,0 +1,136 @@
+"""Validated bounds for the optional PostgreSQL semantic catalog.
+
+The configuration carries only behavior bounds and safe secret *references* -
+never connection strings, DSNs, or credentials.  The host injects the actual
+DSN into the catalog constructor from its own secret management; a dumped or
+logged configuration therefore cannot leak PostgreSQL endpoints or secrets.
+Every bound is validated at construction so an unsafe namespace, pool,
+timeout, retention, envelope limit, or schema version fails before any client
+is built, and an unsupported schema version fails closed.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .schema import SUPPORTED_SCHEMA_VERSION
+
+#: Schema namespace: bounded identifier so every derived table name stays safe.
+_SCHEMA_PATTERN = r"^[A-Za-z][A-Za-z0-9_]{0,63}$"
+
+#: Secret reference: a bounded host-side name (environment variable, vault
+#: key, ...) - never the secret value itself.
+_SECRET_REF_PATTERN = r"^[A-Za-z0-9_][A-Za-z0-9_\-\.]{0,127}$"
+
+#: Hard limits for the validated bounds below.
+_MAX_POOL_SIZE = 64
+_MAX_CONNECT_TIMEOUT_SECONDS = 30.0
+_MAX_COMMAND_TIMEOUT_SECONDS = 120.0
+_MAX_ACQUIRE_TIMEOUT_SECONDS = 60.0
+_MAX_SNAPSHOT_RETENTION_SECONDS = 31_536_000.0  # one year
+_MAX_EVENT_RETENTION_SECONDS = 31_536_000.0  # one year
+_MAX_CLEANUP_BATCH = 10_000
+_MAX_MAX_ENVELOPE_BYTES = 16 * 1024 * 1024
+_MIN_MAX_ENVELOPE_BYTES = 4 * 1024
+_MAX_MAX_PAYLOAD_BYTES = 8 * 1024 * 1024
+_MIN_MAX_PAYLOAD_BYTES = 1 * 1024
+_MAX_BUNDLE_HISTORY = 10_000
+_MAX_ACTIVE_POINTERS_PER_SCOPE = 1_024
+
+
+class SemanticCatalogConfig(BaseModel):
+    """Immutable bounded configuration for one durable catalog.
+
+    ``namespace`` is required and must be unique per application and
+    environment: it names the PostgreSQL schema that owns every catalog table,
+    so two deployments sharing one database service never observe each
+    other's records.  ``dsn_secret_ref`` names the host-managed secret that
+    holds the DSN at construction time; the config itself never carries the
+    DSN.  All other fields bound the catalog's work so a pathological pool,
+    timeout, retention policy, envelope limit, or history depth can never
+    produce unbounded behavior.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    #: PostgreSQL schema owning all catalog records (never a raw tenant id).
+    namespace: str = Field(pattern=_SCHEMA_PATTERN)
+    #: Host-side name of the secret holding the DSN (never the DSN itself).
+    dsn_secret_ref: str | None = Field(default=None, pattern=_SECRET_REF_PATTERN)
+    #: Bounded connection pool size of the lazy psycopg pool.
+    pool_size: int = Field(default=5, ge=1, le=_MAX_POOL_SIZE)
+    #: Bounded connect timeout for lazy pool connections (seconds).
+    connect_timeout_seconds: float = Field(
+        default=5.0, ge=0.1, le=_MAX_CONNECT_TIMEOUT_SECONDS
+    )
+    #: Bounded per-command timeout for every statement (seconds).
+    command_timeout_seconds: float = Field(
+        default=10.0, ge=0.1, le=_MAX_COMMAND_TIMEOUT_SECONDS
+    )
+    #: Bounded pool checkout timeout (seconds).
+    pool_acquire_timeout_seconds: float = Field(
+        default=5.0, ge=0.1, le=_MAX_ACQUIRE_TIMEOUT_SECONDS
+    )
+    #: Maximum schema version this catalog operates on; newer schemas reject.
+    schema_version: int = Field(
+        default=SUPPORTED_SCHEMA_VERSION, ge=1, le=SUPPORTED_SCHEMA_VERSION
+    )
+    #: Default retention applied when a snapshot registration omits one.
+    snapshot_retention_seconds: float = Field(
+        default=604_800.0, ge=60.0, le=_MAX_SNAPSHOT_RETENTION_SECONDS
+    )
+    #: Lifecycle events older than this are removed by bounded cleanup.
+    event_retention_seconds: float = Field(
+        default=604_800.0, ge=60.0, le=_MAX_EVENT_RETENTION_SECONDS
+    )
+    #: Audit-evidence entries older than this age out unless their bundle
+    #: fingerprint belongs to a non-retired published version (or another
+    #: protected entry references them as a predecessor).
+    audit_retention_seconds: float = Field(
+        default=604_800.0, ge=60.0, le=_MAX_EVENT_RETENTION_SECONDS
+    )
+    #: Maximum records removed by one bounded cleanup pass.
+    cleanup_batch_size: int = Field(default=500, ge=1, le=_MAX_CLEANUP_BATCH)
+    #: Hard upper bound for one persisted envelope (bytes).
+    max_envelope_bytes: int = Field(
+        default=1_048_576, ge=_MIN_MAX_ENVELOPE_BYTES, le=_MAX_MAX_ENVELOPE_BYTES
+    )
+    #: Hard upper bound for the canonical payload inside one envelope (bytes).
+    max_payload_bytes: int = Field(
+        default=524_288, ge=_MIN_MAX_PAYLOAD_BYTES, le=_MAX_MAX_PAYLOAD_BYTES
+    )
+    #: Maximum immutable Bundle versions retained per Bundle id.
+    max_bundle_history: int = Field(default=100, ge=1, le=_MAX_BUNDLE_HISTORY)
+    #: Maximum active Bundle pointers per tenant scope.
+    max_active_pointers_per_scope: int = Field(
+        default=256, ge=1, le=_MAX_ACTIVE_POINTERS_PER_SCOPE
+    )
+
+    @model_validator(mode="after")
+    def _consistent_envelope_bounds(self) -> SemanticCatalogConfig:
+        if self.max_payload_bytes > self.max_envelope_bytes:
+            raise ValueError(
+                "max_payload_bytes must not exceed max_envelope_bytes"
+            )
+        return self
+
+    def safe_payload(self) -> dict[str, object]:
+        """Diagnostics dump: bounds and references only, never secrets."""
+        return {
+            "namespace": self.namespace,
+            "dsn_secret_ref": self.dsn_secret_ref,
+            "pool_size": self.pool_size,
+            "connect_timeout_seconds": self.connect_timeout_seconds,
+            "command_timeout_seconds": self.command_timeout_seconds,
+            "pool_acquire_timeout_seconds": self.pool_acquire_timeout_seconds,
+            "schema_version": self.schema_version,
+            "snapshot_retention_seconds": self.snapshot_retention_seconds,
+            "event_retention_seconds": self.event_retention_seconds,
+            "audit_retention_seconds": self.audit_retention_seconds,
+            "cleanup_batch_size": self.cleanup_batch_size,
+            "max_envelope_bytes": self.max_envelope_bytes,
+            "max_payload_bytes": self.max_payload_bytes,
+            "max_bundle_history": self.max_bundle_history,
+            "max_active_pointers_per_scope": self.max_active_pointers_per_scope,
+        }
+

nl2data_semantic_catalog_postgres/envelope.py

@@ -0,0 +1,327 @@
+"""Bounded canonical JSON envelopes for persisted catalog artifacts.
+
+Every artifact persisted by the catalog is wrapped in a versioned envelope::
+
+    {
+        "schema_version": 1,
+        "kind": "snapshot" | "proposal_set" | "bundle" |
+            "assembly_draft" | "accepted_assertion_manifest" |
+            "publish_audit",
+        "fingerprint": "sha256:<64 hex>",
+        "canonicalization_profile": "jcs-v1" | "legacy-deterministic-json-v1",
+        "payload": { ... canonical safe payload ... }
+    }
+
+The canonicalization profile records which canonical JSON algorithm produced
+the stored fingerprint, so reload can recompute and validate the identity
+under the same profile.  Records written before profile metadata existed
+ carry no profile member and are classified explicitly as the legacy
+profile; an unsupported declared profile fails closed.
+
+Encoding validates the payload *before* persistence: the payload must be a
+JSON-native mapping, byte-bounded, and its canonical fingerprint (under the
+declared profile) must equal the declared fingerprint, so an unsafe or
+inconsistent artifact is rejected before any row is written.  Decoding
+revalidates everything after a read: schema version (a newer envelope fails
+closed), kind, canonicalization profile, fingerprint, and byte bounds, so a
+tampered, truncated, or forward-incompatible row is never reinterpreted.
+All failures raise :class:`EnvelopeRejectedError` with a bounded safe
+reason code and message - never backend text or payload content.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import Any
+
+from nl2data_core.canonical import (
+    CANONICALIZATION_PROFILE_JCS,
+    CanonicalizationError,
+    canonical_json,
+    profile_fingerprint,
+    resolve_canonicalization_profile,
+    strict_canonical_json,
+)
+from pydantic import BaseModel, ConfigDict, Field
+
+#: The only envelope structure version this runtime understands.
+ENVELOPE_SCHEMA_VERSION = 1
+
+_FINGERPRINT_PATTERN = r"^sha256:[0-9a-f]{64}$"
+
+#: JSON-native scalar types accepted inside a safe payload.
+_JSON_SCALARS = (str, int, float, bool, type(None))
+
+#: Bounded reason codes carried by :class:`EnvelopeRejectedError`.
+_MALFORMED = "malformed"
+_UNSAFE_PAYLOAD = "unsafe_payload"
+_UNKNOWN_KIND = "unknown_kind"
+_KIND_MISMATCH = "kind_mismatch"
+_NEWER_SCHEMA = "newer_schema"
+_FINGERPRINT_MISMATCH = "fingerprint_mismatch"
+_OVERSIZED = "oversized"
+_INCOMPATIBLE_PROFILE = "incompatible_profile"
+
+#: Profile recorded on every newly encoded envelope.  Existing rows without
+#: profile metadata are classified as the legacy profile on reload.
+DEFAULT_CANONICALIZATION_PROFILE = CANONICALIZATION_PROFILE_JCS
+
+
+class ArtifactKind(StrEnum):
+    """Kinds of artifacts the catalog persists as envelopes."""
+
+    SNAPSHOT = "snapshot"
+    PROPOSAL_SET = "proposal_set"
+    BUNDLE = "bundle"
+    ASSEMBLY_DRAFT = "assembly_draft"
+    ACCEPTED_ASSERTION_MANIFEST = "accepted_assertion_manifest"
+    PUBLISH_AUDIT = "publish_audit"
+    VERIFICATION_SUITE_EVIDENCE = "verification_suite_evidence"
+    PUBLICATION_AUDIT_EVIDENCE = "publication_audit_evidence"
+    ASSEMBLY_AUDIT_EVIDENCE = "assembly_audit_evidence"
+
+
+class EnvelopeRejectedError(Exception):
+    """A persisted artifact failed safe envelope validation.
+
+    ``code`` is one of the bounded reason codes above; ``message`` is a
+    short safe description that never includes payload content or backend
+    text.  The catalog boundary normalizes this into its public error
+    vocabulary without leaking details.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def safe_payload(self) -> dict[str, str]:
+        return {"code": self.code, "message": self.message}
+
+
+def _assert_json_safe(value: Any, path: str) -> None:
+    """Reject any payload value that is not JSON-native and bounded."""
+    if isinstance(value, Mapping):
+        if len(value) > 65_536:
+            raise EnvelopeRejectedError(
+                _UNSAFE_PAYLOAD, "envelope payload mappings are unbounded"
+            )
+        for key, item in value.items():
+            if not isinstance(key, str) or not key or len(key) > 256:
+                raise EnvelopeRejectedError(
+                    _UNSAFE_PAYLOAD, "envelope payload keys must be bounded strings"
+                )
+            _assert_json_safe(item, f"{path}.{key}")
+        return
+    if isinstance(value, (list, tuple)):
+        if len(value) > 65_536:
+            raise EnvelopeRejectedError(
+                _UNSAFE_PAYLOAD, "envelope payload collections are unbounded"
+            )
+        for index, item in enumerate(value):
+            _assert_json_safe(item, f"{path}[{index}]")
+        return
+    if isinstance(value, _JSON_SCALARS):
+        if isinstance(value, str) and len(value) > 1_048_576:
+            raise EnvelopeRejectedError(
+                _UNSAFE_PAYLOAD, "envelope payload strings are unbounded"
+            )
+        if isinstance(value, float) and (value != value or value in (float("inf"), float("-inf"))):  # noqa: E501
+            raise EnvelopeRejectedError(
+                _UNSAFE_PAYLOAD, "envelope payload floats must be finite"
+            )
+        return
+    raise EnvelopeRejectedError(
+        _UNSAFE_PAYLOAD, "envelope payloads must be JSON-native values"
+    )
+
+
+def _utf8_bytes(text: str) -> int:
+    return len(text.encode("utf-8"))
+
+
+def _profile_canonical_json(profile: str, payload: Mapping[str, Any]) -> str:
+    """Canonical JSON text of a payload under an explicit profile."""
+    if profile == CANONICALIZATION_PROFILE_JCS:
+        return strict_canonical_json(payload)
+    return canonical_json(payload)
+
+
+def _profile_fingerprint_rejected(
+    profile: str, payload: Mapping[str, Any]
+) -> str:
+    """Profile fingerprint with encoder rejections mapped to safe errors.
+
+    The strict encoder raises :class:`CanonicalizationError` for values
+    ``_assert_json_safe`` cannot see (tuples, deeply prepared enums), and
+    the legacy encoder raises ``ValueError`` for NFC-colliding keys; both
+    must surface as :class:`EnvelopeRejectedError`, never as raw encoder
+    exceptions, so the catalog boundary stays fail-closed and normalized.
+    """
+    try:
+        return profile_fingerprint(profile, payload)
+    except (CanonicalizationError, ValueError) as error:
+        raise EnvelopeRejectedError(
+            _UNSAFE_PAYLOAD,
+            "envelope payload cannot be canonicalized under its profile",
+        ) from error
+
+
+def _profile_text_rejected(profile: str, payload: Mapping[str, Any]) -> str:
+    """Profile canonical text with encoder rejections mapped to safe errors."""
+    try:
+        return _profile_canonical_json(profile, payload)
+    except CanonicalizationError as error:
+        raise EnvelopeRejectedError(
+            _UNSAFE_PAYLOAD,
+            "envelope payload cannot be canonicalized under its profile",
+        ) from error
+
+
+def _classify_profile(recorded: Any) -> str:
+    """Classify a recorded canonicalization profile; unknown fails closed."""
+    if recorded is not None and not isinstance(recorded, str):
+        raise EnvelopeRejectedError(
+            _MALFORMED, "envelope canonicalization profile is invalid"
+        )
+    try:
+        return resolve_canonicalization_profile(recorded)
+    except CanonicalizationError:
+        raise EnvelopeRejectedError(
+            _INCOMPATIBLE_PROFILE,
+            "envelope declares an unsupported canonicalization profile",
+        ) from None
+
+
+def encode_envelope(
+    kind: ArtifactKind,
+    payload: Mapping[str, Any],
+    fingerprint: str,
+    *,
+    canonicalization_profile: str = DEFAULT_CANONICALIZATION_PROFILE,
+    max_envelope_bytes: int,
+    max_payload_bytes: int,
+) -> str:
+    """Encode one artifact as a validated, bounded canonical envelope.
+
+    Raises :class:`EnvelopeRejectedError` when the kind is unknown, the
+    profile is unsupported, the payload is not a bounded JSON-native
+    mapping, its canonical fingerprint (under the declared profile) does
+    not match ``fingerprint``, or either byte bound is exceeded.
+    """
+    profile = _classify_profile(canonicalization_profile)
+    if not isinstance(payload, Mapping):
+        raise EnvelopeRejectedError(
+            _UNSAFE_PAYLOAD, "envelope payloads must be mappings"
+        )
+    if re.fullmatch(_FINGERPRINT_PATTERN, fingerprint) is None:
+        raise EnvelopeRejectedError(
+            _FINGERPRINT_MISMATCH, "envelope fingerprint is malformed"
+        )
+    _assert_json_safe(payload, "payload")
+    if _profile_fingerprint_rejected(profile, payload) != fingerprint:
+        raise EnvelopeRejectedError(
+            _FINGERPRINT_MISMATCH,
+            "envelope fingerprint does not match the canonical payload",
+        )
+    payload_text = _profile_text_rejected(profile, payload)
+    if _utf8_bytes(payload_text) > max_payload_bytes:
+        raise EnvelopeRejectedError(_OVERSIZED, "envelope payload exceeds its bound")
+    envelope_text = strict_canonical_json(
+        {
+            "schema_version": ENVELOPE_SCHEMA_VERSION,
+            "kind": kind.value,
+            "fingerprint": fingerprint,
+            "canonicalization_profile": profile,
+            "payload": json.loads(payload_text),
+        }
+    )
+    if _utf8_bytes(envelope_text) > max_envelope_bytes:
+        raise EnvelopeRejectedError(_OVERSIZED, "envelope exceeds its bound")
+    return envelope_text
+
+
+class CatalogEnvelope(BaseModel):
+    """Validated envelope read back from the catalog."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    schema_version: int = Field(ge=1)
+    kind: ArtifactKind
+    fingerprint: str = Field(pattern=_FINGERPRINT_PATTERN)
+    canonicalization_profile: str
+    payload: dict[str, Any]
+
+
+def decode_envelope(
+    text: str,
+    *,
+    expected_kind: ArtifactKind,
+    supported_schema_version: int,
+    max_envelope_bytes: int,
+    max_payload_bytes: int,
+) -> CatalogEnvelope:
+    """Decode and fully revalidate one persisted envelope.
+
+    Raises :class:`EnvelopeRejectedError` on any malformed, oversized,
+    unknown-kind, newer-schema, kind-mismatched, incompatible-profile, or
+    fingerprint-mismatched envelope.  A newer schema version, an unknown
+    canonicalization profile, or a fingerprint mismatch fails closed: the
+    artifact is never returned to callers.
+    """
+    if not isinstance(text, str) or not text:
+        raise EnvelopeRejectedError(_MALFORMED, "envelope is empty or malformed")
+    if _utf8_bytes(text) > max_envelope_bytes:
+        raise EnvelopeRejectedError(_OVERSIZED, "envelope exceeds its bound")
+    try:
+        raw = json.loads(text)
+    except ValueError as exc:
+        raise EnvelopeRejectedError(_MALFORMED, "envelope is not valid JSON") from exc
+    if not isinstance(raw, Mapping):
+        raise EnvelopeRejectedError(_MALFORMED, "envelope is not valid JSON")
+    required_keys = {"schema_version", "kind", "fingerprint", "payload"}
+    optional_keys = {"canonicalization_profile"}
+    if set(raw) - optional_keys != required_keys:
+        raise EnvelopeRejectedError(_MALFORMED, "envelope structure is invalid")
+    schema_version = raw["schema_version"]
+    if (
+        not isinstance(schema_version, int)
+        or isinstance(schema_version, bool)
+        or schema_version < 1
+    ):
+        raise EnvelopeRejectedError(_MALFORMED, "envelope schema version is invalid")
+    if schema_version > supported_schema_version:
+        raise EnvelopeRejectedError(
+            _NEWER_SCHEMA, "envelope schema version is newer than supported"
+        )
+    kind_value = raw["kind"]
+    if not isinstance(kind_value, str) or kind_value not in ArtifactKind._value2member_map_:
+        raise EnvelopeRejectedError(_UNKNOWN_KIND, "envelope kind is unknown")
+    kind = ArtifactKind(kind_value)
+    if kind is not expected_kind:
+        raise EnvelopeRejectedError(_KIND_MISMATCH, "envelope kind does not match")
+    fingerprint = raw["fingerprint"]
+    if not isinstance(fingerprint, str) or re.fullmatch(_FINGERPRINT_PATTERN, fingerprint) is None:
+        raise EnvelopeRejectedError(_FINGERPRINT_MISMATCH, "envelope fingerprint is malformed")
+    payload = raw["payload"]
+    if not isinstance(payload, Mapping):
+        raise EnvelopeRejectedError(_MALFORMED, "envelope payload is invalid")
+    profile = _classify_profile(raw.get("canonicalization_profile"))
+    _assert_json_safe(payload, "payload")
+    if _utf8_bytes(_profile_text_rejected(profile, payload)) > max_payload_bytes:
+        raise EnvelopeRejectedError(_OVERSIZED, "envelope payload exceeds its bound")
+    if _profile_fingerprint_rejected(profile, payload) != fingerprint:
+        raise EnvelopeRejectedError(
+            _FINGERPRINT_MISMATCH,
+            "envelope fingerprint does not match the canonical payload",
+        )
+    return CatalogEnvelope(
+        schema_version=schema_version,
+        kind=kind,
+        fingerprint=fingerprint,
+        canonicalization_profile=profile,
+        payload=dict(payload),
+    )