debugbundle-python 2.0.0__tar.gz → 2.1.0__tar.gz

{debugbundle_python-2.0.0 → debugbundle_python-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debugbundle-python
-Version: 2.0.0
+Version: 2.1.0
 Summary: DebugBundle SDK for Python
 Author: DebugBundle
 License-Expression: Apache-2.0
@@ -43,6 +43,14 @@ Dynamic: license-file
 
 Python SDK for DebugBundle.
 
+After `make install-docker`, `make evidence-performance` compares identical
+exception/recovery calls with evidence disabled and enabled, including a full
+warning queue, with networking disabled. It reports capture timing separately from
+Python `tracemalloc` peak/live allocation measurements, verifies native causes and
+original-error priority, and checks existing retention ceilings. Setup and cleanup
+are excluded; traced allocations are Python-managed memory, not cumulative churn
+or total process RSS.
+
 ![PyPI](https://img.shields.io/pypi/v/debugbundle-python?label=pypi)
 ![CI](https://img.shields.io/github/actions/workflow/status/debugbundle/debugbundle-python/ci.yml?branch=main&label=ci)
 ![License](https://img.shields.io/badge/license-Apache--2.0-blue)
@@ -51,6 +59,94 @@ Use this package to capture Python backend exceptions, request metadata, structu
 
 Requires Python 3.10 or newer.
 
+## Evidence candidate (unreleased)
+
+The source candidate adds `capture_exception_evidence=True` and
+`capture_recovery_observations=False` installation options. Collection requires
+verified delivery/reader support, discovered on existing config/ACK traffic with
+`debugbundle_evidence=1`. No capture call performs discovery or adds polling.
+`evidence_capabilities` is an optional descriptor pin asserting the **entire**
+path, including local readers, relays and wrappers; later discovery can revoke it.
+Without proof, exception events retain their legacy shape. These additions are
+not available in the installed 2.0.1 release.
+
+Native cause, implicit context and Python 3.11+ exception-group evidence excludes
+locals, source excerpts, arbitrary renderers and application properties. Python
+3.10 has no native exception groups. Graphs retain at most eight nodes, depth
+four, five children and 32 frames per node; all optional exception additions fit
+32 KiB. Uncaught native capture bypasses `before_send` and uses two nodes, eight
+frames and a 4-KiB total including execution/reference metadata. The original
+sanitised stack remains separate.
+
+`with sdk.operation_context({"kind": "job", "name": "invoice.calculate",
+"limit_ms": 5000}):` supplies a fresh operation scope and monotonic elapsed time
+to synchronous or asynchronous work inside the block. Kinds are `request`,
+`command`, `job` and `unknown`. The limit is a known configured limit, not time
+remaining. Framework requests use their existing begin/end lifecycle. Completed
+owners revoke copied async context; reinitialisation/fork discard prior ownership.
+Application results and exceptions pass through the context manager unchanged.
+
+The existing background sender remains best-effort at immediate process exit.
+The uncaught hook collects bounded native evidence without waiting for transport;
+applications needing a delivery attempt use explicit `flush()` in a controlled
+shutdown window. This candidate does not add default crash-file persistence or
+synchronous capture transport.
+
+Pass a fresh UUID v4 `failure_ref` in exception/log/request context. A valid
+`evidence_scope` can specify a fresh page or operation UUID; an active operation
+provides the default. `capture_recovery({"failure_ref": failure_ref,
+"attempt_id": attempt_id, "state": "attempt_completed"})` records an explicit
+application observation. Optional fields are `evidence_scope`, technical
+`operation`, `status_code`, `duration_ms` and primitive `correlation` metadata.
+Page scopes require a nonblank session ID, including the valid string `"0"`.
+Only explicit `recovery_observed` claims semantic recovery; HTTP 200 and
+`attempt_completed` leave it unknown. The other states are `attempt_started`,
+`attempt_failed` and `failure_persisted`.
+
+Standalone recovery requires its local opt-in, `recovery_v1` support and server
+`capture_diagnostic_context`; minimal policy disables it. Privacy, sampling,
+resulting hook-event policy and queue limits still apply. Fifty failure windows,
+five attempts and twenty observations per failure share 64 KiB of tracker and
+pending-payload ownership, retained until ACK/drop even offline. Canonical hooks
+may change any allowed identity/type field; ownership follows the replacement.
+The complete closed envelope is checked against the vendored accepting Draft 7
+schema, followed by evidence semantics and mandatory privacy. Only native JSON
+containers/scalars are copied; custom serializers and container subclasses are
+never invoked by hook validation. Invalid or throwing hooks keep the protected
+original. Exhausted validation or an unfit valid replacement is withheld, so an
+application redaction cannot be undone by a budget fallback.
+
+Native HTTP requests select an ordered prefix by the actual compact UTF-8 JSON
+serializer and remain within the receiving 256-KiB limit. Unsent finalized tails
+stay charged and continue through the existing sender without repeating their
+hooks. Optional SDK evidence is reduced before withholding an unfit primary;
+explicit custom/local transports retain their established budgets. Browser
+relays measure after server identity/token expansion, split downstream requests
+and keep incomplete spools. A legacy custom success remains accepted but cannot
+mark a durable spool delivered; that requires complete canonical acknowledgements.
+Relay chunks share a five-second monotonic forwarding deadline, and spool markers
+are created exclusively with private permissions without following symlinks.
+
+Native HTTP ACK reads stop at 256 KiB and close the response. Requests ask for
+identity encoding; unexpected compressed ACKs are withheld. The five-second
+deadline is checked between streamed reads; HTTPX's synchronous per-read/connect/
+write timeouts remain advisory and an in-progress native read can overrun that
+deadline. Explicit custom transports/config fetchers retain their own timeout,
+allocation and cancellation responsibilities. No additional timer thread or
+inline capture transport is introduced.
+
+Browser relays and Django/Flask/FastAPI relay factories accept the same optional
+`evidence_capabilities` pin. They preserve closed DTOs, protected application
+context and server-owned credentials, and advertise only verified downstream
+support. Opted-in replies keep string `errors` and add indexed `evidence_errors`;
+partial batches return 202, while legacy partial responses retain 400. A durable
+spool accepts locally but is marked delivered only after a valid complete ACK.
+Malformed ACKs cannot grant proof. Only negotiated `invalid_event` rejection of
+an original exception can retry its stripped legacy form once; standalone
+context, policy and authentication rejections do not use this fallback.
+Framework relay adapters read at most the configured body limit plus one byte
+before parsing, and preserve the negotiation query/header through the handler.
+
 Version 2.0.0 protects capture callers with bounded, priority-aware background delivery. Review the [2.0 migration guide](MIGRATION-2.0.md) before upgrading from 1.x.
 
 ## Automatic capture and application filtering
@@ -357,3 +453,28 @@ CI validates Ruff, mypy, pytest, package build, event schema fixtures, and cover
 ## License
 
 Apache-2.0. See `LICENSE`.
+
+## Delivery acknowledgement and retry limits
+
+The built-in HTTP transport requires the canonical ingestion acknowledgement (`accepted`, `rejected`, and `errors`). Empty responses, unrelated JSON, malformed counts, or invalid rejection indices retain the full batch with backoff. Valid acknowledgements remove accepted and terminally rejected events and retry only the indexed retryable rejections; an all-rejected batch does not advance `lastEventAt`.
+
+File transports and explicitly supplied custom/legacy transports retain their documented bodyless success fallback. A custom transport that returns acknowledgement fields must return the complete canonical shape. Retry hints (delay seconds or HTTP dates) are bounded to five minutes and measured from response receipt, including partial/protocol acknowledgements and retryable server failures. Without a server hint, existing retry timing is preserved. Failures remain contained within the SDK's existing delivery path.
+
+## Probe checkpoint guidance
+
+Application instrumentation supplies probe labels and bounded data. Deploy a new
+checkpoint before activating it. Remote activation affects future matching calls
+when policy permits; it does not inject code or recover unretained measurements.
+Built-in runtime/error/device collectors keep their documented SDK settings.
+
+Use fixed labels and allowlisted technical states: `media.preview.checkpoint`
+(stage/input kind/attempt), `auth.session.checkpoint` (observed session presence
+and result), `job.dependency.checkpoint` (named dependency/attempt/result), or
+`cache.preview.checkpoint` (hit/miss/coarse age bucket). Omit customer identifiers,
+tokens/cookies, cache keys, URLs and raw payloads. HTTP 200 or attempt completion
+alone does not establish semantic recovery.
+
+Empty probe data means no matching retained observation for the selected sample
+window. It does not confirm activation delivery to every SDK or execution of a
+label. Check the deployed SDK/wrapper version, instrumentation, scope, expiry,
+policy, sampling and delivery receipts. See the [probe recipes](https://debugbundle.com/docs/probes#bounded-checkpoint-recipes).

{debugbundle_python-2.0.0 → debugbundle_python-2.1.0}/README.md

@@ -2,6 +2,14 @@
 
 Python SDK for DebugBundle.
 
+After `make install-docker`, `make evidence-performance` compares identical
+exception/recovery calls with evidence disabled and enabled, including a full
+warning queue, with networking disabled. It reports capture timing separately from
+Python `tracemalloc` peak/live allocation measurements, verifies native causes and
+original-error priority, and checks existing retention ceilings. Setup and cleanup
+are excluded; traced allocations are Python-managed memory, not cumulative churn
+or total process RSS.
+
 ![PyPI](https://img.shields.io/pypi/v/debugbundle-python?label=pypi)
 ![CI](https://img.shields.io/github/actions/workflow/status/debugbundle/debugbundle-python/ci.yml?branch=main&label=ci)
 ![License](https://img.shields.io/badge/license-Apache--2.0-blue)
@@ -10,6 +18,94 @@ Use this package to capture Python backend exceptions, request metadata, structu
 
 Requires Python 3.10 or newer.
 
+## Evidence candidate (unreleased)
+
+The source candidate adds `capture_exception_evidence=True` and
+`capture_recovery_observations=False` installation options. Collection requires
+verified delivery/reader support, discovered on existing config/ACK traffic with
+`debugbundle_evidence=1`. No capture call performs discovery or adds polling.
+`evidence_capabilities` is an optional descriptor pin asserting the **entire**
+path, including local readers, relays and wrappers; later discovery can revoke it.
+Without proof, exception events retain their legacy shape. These additions are
+not available in the installed 2.0.1 release.
+
+Native cause, implicit context and Python 3.11+ exception-group evidence excludes
+locals, source excerpts, arbitrary renderers and application properties. Python
+3.10 has no native exception groups. Graphs retain at most eight nodes, depth
+four, five children and 32 frames per node; all optional exception additions fit
+32 KiB. Uncaught native capture bypasses `before_send` and uses two nodes, eight
+frames and a 4-KiB total including execution/reference metadata. The original
+sanitised stack remains separate.
+
+`with sdk.operation_context({"kind": "job", "name": "invoice.calculate",
+"limit_ms": 5000}):` supplies a fresh operation scope and monotonic elapsed time
+to synchronous or asynchronous work inside the block. Kinds are `request`,
+`command`, `job` and `unknown`. The limit is a known configured limit, not time
+remaining. Framework requests use their existing begin/end lifecycle. Completed
+owners revoke copied async context; reinitialisation/fork discard prior ownership.
+Application results and exceptions pass through the context manager unchanged.
+
+The existing background sender remains best-effort at immediate process exit.
+The uncaught hook collects bounded native evidence without waiting for transport;
+applications needing a delivery attempt use explicit `flush()` in a controlled
+shutdown window. This candidate does not add default crash-file persistence or
+synchronous capture transport.
+
+Pass a fresh UUID v4 `failure_ref` in exception/log/request context. A valid
+`evidence_scope` can specify a fresh page or operation UUID; an active operation
+provides the default. `capture_recovery({"failure_ref": failure_ref,
+"attempt_id": attempt_id, "state": "attempt_completed"})` records an explicit
+application observation. Optional fields are `evidence_scope`, technical
+`operation`, `status_code`, `duration_ms` and primitive `correlation` metadata.
+Page scopes require a nonblank session ID, including the valid string `"0"`.
+Only explicit `recovery_observed` claims semantic recovery; HTTP 200 and
+`attempt_completed` leave it unknown. The other states are `attempt_started`,
+`attempt_failed` and `failure_persisted`.
+
+Standalone recovery requires its local opt-in, `recovery_v1` support and server
+`capture_diagnostic_context`; minimal policy disables it. Privacy, sampling,
+resulting hook-event policy and queue limits still apply. Fifty failure windows,
+five attempts and twenty observations per failure share 64 KiB of tracker and
+pending-payload ownership, retained until ACK/drop even offline. Canonical hooks
+may change any allowed identity/type field; ownership follows the replacement.
+The complete closed envelope is checked against the vendored accepting Draft 7
+schema, followed by evidence semantics and mandatory privacy. Only native JSON
+containers/scalars are copied; custom serializers and container subclasses are
+never invoked by hook validation. Invalid or throwing hooks keep the protected
+original. Exhausted validation or an unfit valid replacement is withheld, so an
+application redaction cannot be undone by a budget fallback.
+
+Native HTTP requests select an ordered prefix by the actual compact UTF-8 JSON
+serializer and remain within the receiving 256-KiB limit. Unsent finalized tails
+stay charged and continue through the existing sender without repeating their
+hooks. Optional SDK evidence is reduced before withholding an unfit primary;
+explicit custom/local transports retain their established budgets. Browser
+relays measure after server identity/token expansion, split downstream requests
+and keep incomplete spools. A legacy custom success remains accepted but cannot
+mark a durable spool delivered; that requires complete canonical acknowledgements.
+Relay chunks share a five-second monotonic forwarding deadline, and spool markers
+are created exclusively with private permissions without following symlinks.
+
+Native HTTP ACK reads stop at 256 KiB and close the response. Requests ask for
+identity encoding; unexpected compressed ACKs are withheld. The five-second
+deadline is checked between streamed reads; HTTPX's synchronous per-read/connect/
+write timeouts remain advisory and an in-progress native read can overrun that
+deadline. Explicit custom transports/config fetchers retain their own timeout,
+allocation and cancellation responsibilities. No additional timer thread or
+inline capture transport is introduced.
+
+Browser relays and Django/Flask/FastAPI relay factories accept the same optional
+`evidence_capabilities` pin. They preserve closed DTOs, protected application
+context and server-owned credentials, and advertise only verified downstream
+support. Opted-in replies keep string `errors` and add indexed `evidence_errors`;
+partial batches return 202, while legacy partial responses retain 400. A durable
+spool accepts locally but is marked delivered only after a valid complete ACK.
+Malformed ACKs cannot grant proof. Only negotiated `invalid_event` rejection of
+an original exception can retry its stripped legacy form once; standalone
+context, policy and authentication rejections do not use this fallback.
+Framework relay adapters read at most the configured body limit plus one byte
+before parsing, and preserve the negotiation query/header through the handler.
+
 Version 2.0.0 protects capture callers with bounded, priority-aware background delivery. Review the [2.0 migration guide](MIGRATION-2.0.md) before upgrading from 1.x.
 
 ## Automatic capture and application filtering
@@ -316,3 +412,28 @@ CI validates Ruff, mypy, pytest, package build, event schema fixtures, and cover
 ## License
 
 Apache-2.0. See `LICENSE`.
+
+## Delivery acknowledgement and retry limits
+
+The built-in HTTP transport requires the canonical ingestion acknowledgement (`accepted`, `rejected`, and `errors`). Empty responses, unrelated JSON, malformed counts, or invalid rejection indices retain the full batch with backoff. Valid acknowledgements remove accepted and terminally rejected events and retry only the indexed retryable rejections; an all-rejected batch does not advance `lastEventAt`.
+
+File transports and explicitly supplied custom/legacy transports retain their documented bodyless success fallback. A custom transport that returns acknowledgement fields must return the complete canonical shape. Retry hints (delay seconds or HTTP dates) are bounded to five minutes and measured from response receipt, including partial/protocol acknowledgements and retryable server failures. Without a server hint, existing retry timing is preserved. Failures remain contained within the SDK's existing delivery path.
+
+## Probe checkpoint guidance
+
+Application instrumentation supplies probe labels and bounded data. Deploy a new
+checkpoint before activating it. Remote activation affects future matching calls
+when policy permits; it does not inject code or recover unretained measurements.
+Built-in runtime/error/device collectors keep their documented SDK settings.
+
+Use fixed labels and allowlisted technical states: `media.preview.checkpoint`
+(stage/input kind/attempt), `auth.session.checkpoint` (observed session presence
+and result), `job.dependency.checkpoint` (named dependency/attempt/result), or
+`cache.preview.checkpoint` (hit/miss/coarse age bucket). Omit customer identifiers,
+tokens/cookies, cache keys, URLs and raw payloads. HTTP 200 or attempt completion
+alone does not establish semantic recovery.
+
+Empty probe data means no matching retained observation for the selected sample
+window. It does not confirm activation delivery to every SDK or execution of a
+label. Check the deployed SDK/wrapper version, instrumentation, scope, expiry,
+policy, sampling and delivery receipts. See the [probe recipes](https://debugbundle.com/docs/probes#bounded-checkpoint-recipes).

{debugbundle_python-2.0.0 → debugbundle_python-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "debugbundle-python"
-version = "2.0.0"
+version = "2.1.0"
 description = "DebugBundle SDK for Python"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -54,6 +54,9 @@ Issues = "https://github.com/debugbundle/debugbundle-python/issues"
 package-dir = {"" = "src"}
 include-package-data = true
 
+[tool.setuptools.package-data]
+debugbundle = ["event-envelope.schema.json", "py.typed"]
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

{debugbundle_python-2.0.0 → debugbundle_python-2.1.0}/src/debugbundle/__init__.py

@@ -33,6 +33,9 @@ def init(
     on_diagnostic: Callable[[dict[str, object]], None] | None = None,
     before_send: BeforeSendHook | None = None,
     probes_poll_interval: int = 60_000,
+    capture_exception_evidence: bool = True,
+    evidence_capabilities: object = None,
+    capture_recovery_observations: bool = False,
 ) -> None:
     _sdk.init(
         project_token=project_token,
@@ -52,6 +55,9 @@ def init(
         on_diagnostic=on_diagnostic,
         before_send=before_send,
         probes_poll_interval=probes_poll_interval,
+        capture_exception_evidence=capture_exception_evidence,
+        evidence_capabilities=evidence_capabilities,
+        capture_recovery_observations=capture_recovery_observations,
     )
 
 
@@ -63,6 +69,14 @@ def capture_error(error: BaseException, context: dict[str, object] | None = None
     _sdk.capture_error(error, context=context)
 
 
+def operation_context(options: object) -> Any:
+    return _sdk.operation_context(options)
+
+
+def capture_recovery(observation: object) -> None:
+    _sdk.capture_recovery(observation)
+
+
 def capture_log(message: str, level: str = "warning", context: dict[str, object] | None = None) -> None:
     _sdk.capture_log(message, level=level, context=context)
 
@@ -155,6 +169,7 @@ __all__ = [
     "capture_logging",
     "capture_message",
     "capture_request",
+    "capture_recovery",
     "create_django_relay_view",
     "create_fastapi_relay_handler",
     "create_flask_relay_handler",
@@ -164,5 +179,6 @@ __all__ = [
     "instrument_fastapi",
     "instrument_flask",
     "probe",
+    "operation_context",
     "set_context",
 ]

{debugbundle_python-2.0.0 → debugbundle_python-2.1.0}/src/debugbundle/acknowledgement.py

@@ -19,8 +19,10 @@ class AcknowledgementDecision:
     reason: str | None = None
 
 
-def decide_acknowledgement(body: object | None, batch_length: int) -> AcknowledgementDecision:
+def decide_acknowledgement(body: object | None, batch_length: int, required: bool = False) -> AcknowledgementDecision:
     if not isinstance(body, dict) or not any(key in body for key in ("accepted", "rejected", "errors")):
+        if required:
+            return AcknowledgementDecision(kind="protocol_failure", reason="missing_acknowledgement")
         return AcknowledgementDecision(kind="legacy")
 
     accepted = body.get("accepted")

debugbundle_python-2.1.0/src/debugbundle/before_send.py

@@ -0,0 +1,62 @@
+"""Canonical, owned hook results with explicit invalid and exhausted outcomes."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Callable
+from typing import cast
+
+from .canonical_event import EXHAUSTED, INVALID, ValidationBudgetExceeded, own_json, valid_owned_event
+from .evidence_wire import validate_evidence
+
+BeforeSendHook = Callable[[dict[str, object]], dict[str, object] | None]
+_MOBILE = ("@debugbundle/sdk-android", "@debugbundle/sdk-swift", "@debugbundle/sdk-react-native")
+
+
+def _normalized(event: object) -> object:
+    if type(event) is not dict:
+        return INVALID
+    owned = own_json(event)
+    if owned is INVALID or owned is EXHAUSTED:
+        return owned
+    try:
+        if not valid_owned_event(owned) or not validate_evidence(owned):
+            return INVALID
+        # The accepting Zod contract refines this condition outside JSON Schema.
+        if owned["event_type"] == "frontend_exception":
+            field = "device" if owned["sdk_name"] in _MOBILE else "browser"
+            if field not in owned["payload"] or type(owned["payload"][field]) is not dict:
+                return INVALID
+        return owned
+    except ValidationBudgetExceeded:
+        return EXHAUSTED
+    except Exception:
+        return INVALID
+
+
+def apply_before_send(
+    event: dict[str, object],
+    hook: BeforeSendHook | None,
+    emit_diagnostic: Callable[[str, str], None],
+) -> dict[str, object] | None:
+    if hook is None:
+        return event
+    try:
+        result = hook(copy.deepcopy(event))
+    except Exception:
+        emit_diagnostic("before_send_failed", "Python before_send hook failed")
+        return event
+    if result is None:
+        return None
+    checked = _normalized(result)
+    if checked is EXHAUSTED:
+        return None
+    if checked is INVALID:
+        emit_diagnostic("before_send_invalid_event", "Python before_send returned an invalid event")
+        return event
+    return cast(dict[str, object], checked)
+
+
+def _is_valid_event(event: object) -> bool:
+    result = _normalized(event)
+    return result is not INVALID and result is not EXHAUSTED

debugbundle_python-2.1.0/src/debugbundle/canonical_event.py

@@ -0,0 +1,202 @@
+"""Owned JSON and a closed interpreter for the vendored accepting Draft 7 schema.
+
+Only native containers/scalars are inspected. No application serializers, remote
+references or optional runtime dependencies participate in hook validation.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from .evidence_wire import _timestamp, _uuid
+
+MAX_OWNED_BYTES = 8 * 1024 * 1024
+INVALID = object()
+EXHAUSTED = object()
+
+
+class ValidationBudgetExceeded(Exception):
+    """Withhold hook output rather than restore content it may have removed."""
+
+
+def own_json(value: object) -> Any:
+    remaining = MAX_OWNED_BYTES
+    nodes = 4096
+
+    def copy(item: Any, depth: int) -> Any:
+        nonlocal remaining, nodes
+        nodes -= 1
+        if nodes < 0 or depth > 16 or remaining < 0:
+            raise ValidationBudgetExceeded
+        kind = type(item)
+        if item is None or kind is bool:
+            remaining -= 5
+            return item
+        if kind is str:
+            if len(item) > remaining:
+                raise ValidationBudgetExceeded
+            remaining -= len(item.encode("utf-8")) + 2
+            if remaining < 0:
+                raise ValidationBudgetExceeded
+            return item
+        if kind is int or kind is float:
+            # The accepting JavaScript number domain is finite IEEE-754.
+            if not -1.7976931348623157e308 <= item <= 1.7976931348623157e308 or not math.isfinite(item):
+                raise ValueError("non-finite number")
+            remaining -= 24
+            return item
+        if kind is list:
+            if len(item) > nodes:
+                raise ValidationBudgetExceeded
+            remaining -= 2 + len(item)
+            return [copy(child, depth + 1) for child in item]
+        if kind is dict:
+            if len(item) * 2 > nodes:
+                raise ValidationBudgetExceeded
+            remaining -= 2 + 2 * len(item)
+            result = {}
+            for key, child in item.items():
+                if type(key) is not str:
+                    raise ValueError("non-string key")
+                result[copy(key, depth + 1)] = copy(child, depth + 1)
+            return result
+        raise ValueError("non-native JSON value")
+
+    try:
+        return copy(value, 0)
+    except ValidationBudgetExceeded:
+        return EXHAUSTED
+    except (ValueError, UnicodeError, OverflowError):
+        return INVALID
+
+
+class CanonicalEventSchema:
+    KEYWORDS = frozenset(
+        "$schema $id $comment $ref type anyOf const enum properties required additionalProperties "
+        "items minimum maximum exclusiveMinimum minLength maxLength minItems maxItems format pattern".split()
+    )
+    TYPES = frozenset("null boolean number integer string array object".split())
+
+    def __init__(self, schema: dict[str, Any]) -> None:
+        self.root = schema
+        self.references: dict[str, Any] = {}
+        self.patterns: dict[str, re.Pattern[str]] = {}
+        self._compile(schema)
+
+    def _resolve(self, reference: str) -> Any:
+        if not reference.startswith("#/"):
+            raise ValueError("external schema ref")
+        if reference not in self.references:
+            node: Any = self.root
+            for part in reference[2:].split("/"):
+                key = part.replace("~1", "/").replace("~0", "~")
+                node = node[int(key)] if type(node) is list else node[key]
+            self.references[reference] = node
+        return self.references[reference]
+
+    def _compile(self, node: Any) -> None:
+        if type(node) is bool:
+            return
+        if not set(node).issubset(self.KEYWORDS):
+            raise ValueError("unsupported schema keyword")
+        kinds = node.get("type", [])
+        if not set([kinds] if type(kinds) is str else kinds).issubset(self.TYPES):
+            raise ValueError("unsupported schema type")
+        if node.get("format") not in (None, "uuid", "date-time"):
+            raise ValueError("unsupported schema format")
+        if "pattern" in node:
+            self.patterns[node["pattern"]] = re.compile(node["pattern"])
+        if "$ref" in node:
+            self._resolve(node["$ref"])
+        for child in node.get("properties", {}).values():
+            self._compile(child)
+        for child in node.get("anyOf", []):
+            self._compile(child)
+        for key in ("items", "additionalProperties"):
+            if key in node:
+                self._compile(node[key])
+
+    def accepts(self, value: Any) -> bool:
+        return self._check(self.root, value, [100_000], 0)
+
+    def _check(self, node: Any, value: Any, budget: list[int], depth: int) -> bool:
+        budget[0] -= 1
+        if depth > 64 or budget[0] < 0:
+            raise ValidationBudgetExceeded
+        if type(node) is bool:
+            return node
+        if "$ref" in node:
+            return self._check(self._resolve(node["$ref"]), value, budget, depth + 1)
+        if "anyOf" in node and not any(self._check(child, value, budget, depth + 1) for child in node["anyOf"]):
+            return False
+        if "type" in node:
+            kinds = node["type"] if type(node["type"]) is list else [node["type"]]
+            if not any(self._type(value, kind) for kind in kinds):
+                return False
+        if "const" in node and not self._equal(value, node["const"]):
+            return False
+        if "enum" in node and not any(self._equal(value, choice) for choice in node["enum"]):
+            return False
+        if type(value) is dict:
+            properties = node.get("properties", {})
+            return all(key in value for key in node.get("required", [])) and all(
+                self._check(properties.get(key, node.get("additionalProperties", True)), child, budget, depth + 1)
+                for key, child in value.items()
+            )
+        if type(value) is list:
+            return (
+                len(value) >= node.get("minItems", 0)
+                and len(value) <= node.get("maxItems", len(value))
+                and (
+                    "items" not in node or all(self._check(node["items"], child, budget, depth + 1) for child in value)
+                )
+            )
+        if type(value) is str:
+            length = len(value.encode("utf-16-le")) // 2  # Zod counts JavaScript UTF-16 code units.
+            return (
+                length >= node.get("minLength", 0)
+                and length <= node.get("maxLength", length)
+                and ("pattern" not in node or bool(self.patterns[node["pattern"]].search(value)))
+                and (node.get("format") != "uuid" or _uuid(value))
+                and (node.get("format") != "date-time" or _timestamp(value))
+            )
+        if type(value) is int or type(value) is float:
+            return (
+                ("minimum" not in node or value >= node["minimum"])
+                and ("maximum" not in node or value <= node["maximum"])
+                and ("exclusiveMinimum" not in node or value > node["exclusiveMinimum"])
+            )
+        return True
+
+    @staticmethod
+    def _equal(value: Any, choice: Any) -> bool:
+        return (
+            type(value) is type(choice)
+            and value == choice
+            or (type(value) in (int, float) and type(choice) in (int, float) and value == choice)
+        )
+
+    @staticmethod
+    def _type(value: Any, kind: str) -> bool:
+        if kind == "number" or kind == "integer":
+            return type(value) in (int, float) and (kind == "number" or value == math.floor(value))
+        return type(value) is {"null": type(None), "boolean": bool, "string": str, "array": list, "object": dict}[kind]
+
+
+@lru_cache(maxsize=1)
+def _engine() -> CanonicalEventSchema:
+    return CanonicalEventSchema(json.loads(Path(__file__).with_name("event-envelope.schema.json").read_text()))
+
+
+def valid_owned_event(value: dict[str, Any]) -> bool:
+    try:
+        return _engine().accepts(value)
+    except ValidationBudgetExceeded:
+        raise
+    except Exception:
+        return False

{debugbundle_python-2.0.0 → debugbundle_python-2.1.0}/src/debugbundle/config.py

@@ -22,6 +22,7 @@ class CapturePolicy:
     capture_probe_events: str
     immediate_client_error_statuses: tuple[int, ...]
     immediate_client_error_path_rules: tuple[ImmediateClientErrorPathRule, ...] = ()
+    capture_diagnostic_context: bool = True
 
 
 @dataclass(frozen=True)
@@ -61,6 +62,7 @@ MINIMAL_CAPTURE_POLICY = CapturePolicy(
     capture_probe_events="buffer_only",
     immediate_client_error_statuses=(),
     immediate_client_error_path_rules=(),
+    capture_diagnostic_context=False,
 )
 
 
@@ -147,6 +149,9 @@ def _parse_capture_policy(payload: object) -> CapturePolicy | None:
         return None
     if immediate_client_error_statuses is None or immediate_client_error_path_rules is None:
         return None
+    diagnostic = payload.get("capture_diagnostic_context", True)
+    if type(diagnostic) is not bool:
+        return None
 
     return CapturePolicy(
         preset=preset,
@@ -156,6 +161,7 @@ def _parse_capture_policy(payload: object) -> CapturePolicy | None:
         capture_probe_events=capture_probe_events,
         immediate_client_error_statuses=immediate_client_error_statuses,
         immediate_client_error_path_rules=immediate_client_error_path_rules,
+        capture_diagnostic_context=preset != "minimal" and diagnostic,
     )