clue-python-sdk-core 0.0.1__py3-none-any.whl

clue_python_sdk_core/adapters.py

@@ -0,0 +1,2177 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import uuid
+from collections.abc import Mapping, Sequence
+from datetime import datetime, timezone
+from pathlib import Path
+from traceback import extract_tb
+
+from .contracts import (
+	APPLICATION_LOG_SUMMARY_EVENT,
+	BACKEND_ERROR_EVENT,
+	BACKEND_MUTATION_KINDS,
+	BACKEND_RUNTIME_LANGUAGE,
+	BACKEND_SDK_SCHEMA_VERSION,
+	BACKEND_SDK_TYPE,
+	BACKEND_SDK_VERSION,
+	BACKEND_STATUS_FAILED,
+	BACKEND_STATUS_FINISHED,
+	BACKEND_STATUS_OBSERVED,
+	BACKEND_STATUS_STARTED,
+	CACHE_OPERATION_SUMMARY_EVENT,
+	CUSTOM_EVENT_ACCOUNT_ASSOCIATED,
+	CUSTOM_EVENT_EMITTED,
+	CUSTOM_EVENT_IDENTITY_IDENTIFIED,
+	CUSTOM_EVENT_IDENTITY_LOGGED_OUT,
+	DEPENDENCY_SUMMARY_EVENT,
+	DOMAIN_COMMAND_EVENT_BY_STATUS,
+	EVENT_CATEGORY_CUSTOM,
+	EVENT_CATEGORY_DOMAIN_COMMAND,
+	EVENT_CATEGORY_ERROR,
+	EVENT_CATEGORY_JOB,
+	EVENT_CATEGORY_OUTBOUND_REQUEST,
+	EVENT_CATEGORY_REQUEST,
+	EVENT_CATEGORY_REPOSITORY_MUTATION,
+	EVENT_CATEGORY_STATE_TRANSITION,
+	EVENT_CATEGORY_TOOL_CALL,
+	JOB_EVENT_BY_STATUS,
+	OUTBOUND_REQUEST_EVENT_FAILED,
+	OUTBOUND_REQUEST_EVENT_FINISHED,
+	OUTBOUND_REQUEST_EVENT_STARTED,
+	QUEUE_LIFECYCLE_SUMMARY_EVENT,
+	REPOSITORY_MUTATION_EVENT_BY_STATUS,
+	REPOSITORY_MUTATION_SUMMARY_EVENT,
+	REQUEST_EVENT_FAILED,
+	REQUEST_EVENT_FINISHED,
+	REQUEST_EVENT_STARTED,
+	SDK_COLLECTION_MODE_STANDARD,
+	SDK_DIAGNOSTIC_EVENT,
+	STATE_TRANSITION_EVENT_BY_STATUS,
+	SURFACE_TYPE_API,
+	SURFACE_TYPE_JOB,
+	SURFACE_TYPE_SERVICE,
+	TOOL_CALL_EVENT_BY_STATUS,
+)
+from .http_extraction import (
+	_extract_query,
+	_extract_request_headers,
+	_extract_response_headers,
+	_normalize_headers,
+	_request_body,
+	_response_body,
+	_safe_urlsplit,
+	_to_json_value,
+	to_path_template,
+)
+from .otel_bridge import merge_current_otel_span_context
+from .parameter_snapshot import (
+	_build_request_parameter_snapshot,
+	_build_response_parameter_snapshot,
+)
+from .privacy import JsonValue, build_mask_token, is_denied_key, safe_sanitize_object
+
+
+def _string_or_none(value: object) -> str | None:
+	return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+MAX_SCHEMA_FIELD_PATHS = 100
+
+
+def _normalize_schema_token(value: object) -> str | None:
+	if not isinstance(value, str):
+		return None
+	token = value.strip().lower()
+	if not token:
+		return None
+	normalized = "".join(
+		char if char.isalnum() or char in {"_", "-", ".", ":"} else "_"
+		for char in token
+	)
+	normalized = "_".join(part for part in normalized.split("_") if part)
+	if not normalized or len(normalized) > 96:
+		return None
+	return normalized
+
+
+def _shape_type(value: object) -> str:
+	if value is None:
+		return "null"
+	if isinstance(value, bool):
+		return "boolean"
+	if isinstance(value, (int, float)):
+		return "number"
+	if isinstance(value, str):
+		return "string"
+	if isinstance(value, Mapping):
+		return "object"
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		return "array"
+	return type(value).__name__
+
+
+def _schema_shape(
+	value: object,
+	*,
+	denied_keys: Sequence[str],
+	path: str,
+	field_paths: list[str],
+	depth: int = 0,
+) -> JsonValue:
+	if depth > 8:
+		return {"type": "max_depth"}
+
+	if isinstance(value, Mapping):
+		shape: dict[str, JsonValue] = {}
+		forbidden_count = 0
+		for key, child in sorted(value.items(), key=lambda entry: str(entry[0])):
+			key_text = str(key)
+			if is_denied_key(key_text, denied_keys):
+				forbidden_count += 1
+				continue
+			child_path = f"{path}.{key_text}" if path else key_text
+			if len(field_paths) < MAX_SCHEMA_FIELD_PATHS:
+				field_paths.append(child_path)
+			shape[key_text] = _schema_shape(
+				child,
+				denied_keys=denied_keys,
+				path=child_path,
+				field_paths=field_paths,
+				depth=depth + 1,
+			)
+		if forbidden_count > 0:
+			shape["__forbidden__"] = {
+				"type": "forbidden",
+				"count": forbidden_count,
+			}
+		return {"type": "object", "fields": shape}
+
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		items = list(value)
+		if not items:
+			return {"type": "array", "items": "empty"}
+		if len(field_paths) < MAX_SCHEMA_FIELD_PATHS and path:
+			field_paths.append(f"{path}[]")
+		return {
+			"type": "array",
+			"items": _schema_shape(
+				items[0],
+				denied_keys=denied_keys,
+				path=f"{path}[]",
+				field_paths=field_paths,
+				depth=depth + 1,
+			),
+		}
+
+	return {"type": _shape_type(value)}
+
+
+def _build_schema_evidence(
+	value: object | None,
+	*,
+	denied_keys: Sequence[str],
+) -> dict[str, JsonValue]:
+	if value is None:
+		return {
+			"schema_hash": None,
+			"field_paths": [],
+			"shape_size": 0,
+		}
+
+	field_paths: list[str] = []
+	shape = _schema_shape(
+		value,
+		denied_keys=denied_keys,
+		path="",
+		field_paths=field_paths,
+	)
+	shape_json = json.dumps(shape, sort_keys=True, separators=(",", ":"))
+	schema_hash = f"sha256:{hashlib.sha256(shape_json.encode('utf-8')).hexdigest()}"
+	return {
+		"schema_hash": schema_hash,
+		"field_paths": sorted(dict.fromkeys(field_paths)),
+		"shape_size": len(set(field_paths)),
+	}
+
+
+def _count_capture_modes(value: JsonValue) -> dict[str, int]:
+	counts = {
+		"masked_value_count": 0,
+		"forbidden_value_count": 0,
+		"truncated_value_count": 0,
+		"allowed_value_count": 0,
+	}
+
+	def walk(current: JsonValue) -> None:
+		if isinstance(current, Mapping):
+			capture_mode = current.get("capture_mode")
+			if capture_mode == "masked_fingerprint":
+				counts["masked_value_count"] += 1
+				return
+			if capture_mode == "forbidden":
+				counts["forbidden_value_count"] += 1
+				return
+			if capture_mode == "truncated":
+				counts["truncated_value_count"] += 1
+				return
+			if capture_mode == "allowed_plaintext":
+				counts["allowed_value_count"] += 1
+				return
+			for child in current.values():
+				walk(child)
+			return
+		if isinstance(current, list):
+			for child in current:
+				walk(child)
+
+	walk(value)
+	return counts
+
+
+def _bucket_remaining(value: object) -> str | None:
+	try:
+		remaining = int(str(value))
+	except (TypeError, ValueError):
+		return None
+	if remaining <= 0:
+		return "0"
+	if remaining <= 10:
+		return "1_10"
+	if remaining <= 100:
+		return "11_100"
+	if remaining <= 1000:
+		return "101_1000"
+	return "1000_plus"
+
+
+def _bucket_reset_after_ms(headers: Mapping[str, JsonValue]) -> str | None:
+	retry_after = headers.get("retry-after") or headers.get("Retry-After")
+	if retry_after is None:
+		return None
+	try:
+		reset_after_ms = int(float(str(retry_after)) * 1000)
+	except (TypeError, ValueError):
+		return None
+	if reset_after_ms <= 1000:
+		return "lte_1s"
+	if reset_after_ms <= 10000:
+		return "lte_10s"
+	if reset_after_ms <= 60000:
+		return "lte_60s"
+	if reset_after_ms <= 300000:
+		return "lte_5m"
+	return "gt_5m"
+
+
+def _extract_error_code_candidate(value: object | None) -> str | None:
+	if isinstance(value, Mapping):
+		for key in ("code", "error_code", "type", "error"):
+			candidate = _normalize_schema_token(value.get(key))
+			if candidate:
+				return candidate
+		errors = value.get("errors") or value.get("detail") or value.get("extensions")
+		if isinstance(errors, Sequence) and not isinstance(errors, (str, bytes, bytearray)):
+			for entry in errors:
+				candidate = _extract_error_code_candidate(entry)
+				if candidate:
+					return candidate
+		if isinstance(errors, Mapping):
+			return _extract_error_code_candidate(errors)
+	return _normalize_schema_token(value)
+
+
+def _extract_validation_evidence(value: object | None) -> dict[str, JsonValue]:
+	field_paths: list[str] = []
+	reason_codes: list[str] = []
+	error_count = 0
+
+	def add_field_path(parts: object) -> None:
+		if isinstance(parts, Sequence) and not isinstance(parts, (str, bytes, bytearray)):
+			path = ".".join(str(part) for part in parts if str(part).strip())
+		else:
+			path = str(parts).strip()
+		if path and len(field_paths) < MAX_SCHEMA_FIELD_PATHS:
+			field_paths.append(path)
+
+	def walk(current: object) -> None:
+		nonlocal error_count
+		if isinstance(current, Mapping):
+			loc = current.get("loc") or current.get("path") or current.get("field")
+			if loc is not None:
+				add_field_path(loc)
+			reason = (
+				_normalize_schema_token(current.get("type"))
+				or _normalize_schema_token(current.get("code"))
+				or _normalize_schema_token(current.get("reason"))
+			)
+			if reason:
+				reason_codes.append(reason)
+			if loc is not None or reason is not None:
+				error_count += 1
+			for key in ("errors", "detail"):
+				child = current.get(key)
+				if child is not None and child is not current:
+					walk(child)
+			return
+		if isinstance(current, Sequence) and not isinstance(current, (str, bytes, bytearray)):
+			for entry in current:
+				walk(entry)
+
+	walk(value)
+	return {
+		"field_paths": sorted(dict.fromkeys(field_paths)),
+		"validation_reason_codes": sorted(dict.fromkeys(reason_codes)),
+		"error_count": error_count,
+	}
+
+
+def _derive_outcome_evidence(
+	*,
+	status_code: int,
+	response_body: object | None,
+	headers: Mapping[str, JsonValue],
+) -> dict[str, JsonValue]:
+	error_code_candidate = _extract_error_code_candidate(response_body)
+	validation = _extract_validation_evidence(response_body)
+	outcome_class = "success"
+	decision_type: str | None = None
+	decision_result: str | None = None
+	reason_code = error_code_candidate
+
+	if status_code == 401:
+		outcome_class = "auth_denied"
+		decision_type = "auth"
+		decision_result = "denied"
+		reason_code = reason_code or "unauthorized"
+	elif status_code == 403:
+		outcome_class = "permission_denied"
+		decision_type = "permission"
+		decision_result = "denied"
+		reason_code = reason_code or "forbidden"
+	elif status_code == 409:
+		outcome_class = "conflict"
+		decision_type = "validation"
+		decision_result = "blocked"
+		reason_code = reason_code or "conflict"
+	elif status_code == 422:
+		outcome_class = "validation_error"
+		decision_type = "validation"
+		decision_result = "blocked"
+		reason_code = (
+			str(validation["validation_reason_codes"][0])
+			if isinstance(validation["validation_reason_codes"], list)
+			and validation["validation_reason_codes"]
+			else reason_code or "validation_error"
+		)
+	elif status_code == 429:
+		outcome_class = "rate_limited"
+		decision_type = "rate_limit"
+		decision_result = "blocked"
+		reason_code = reason_code or "rate_limited"
+	elif status_code == 404:
+		outcome_class = "not_found"
+		reason_code = reason_code or "not_found"
+	elif status_code >= 500:
+		outcome_class = "server_error"
+		decision_result = "failed"
+		reason_code = reason_code or "server_error"
+	elif status_code >= 400:
+		outcome_class = "client_error"
+		decision_result = "failed"
+		reason_code = reason_code or "client_error"
+
+	if reason_code and "quota" in reason_code:
+		outcome_class = "quota_exceeded"
+		decision_type = "quota"
+		decision_result = "blocked"
+
+	return {
+		"outcome_class": outcome_class,
+		"decision_type": decision_type,
+		"decision_result": decision_result,
+		"reason_code": reason_code,
+		"error_code_candidate": error_code_candidate,
+		"field_paths": validation["field_paths"],
+		"validation_reason_codes": validation["validation_reason_codes"],
+		"error_count": validation["error_count"],
+		"limit_name": _normalize_schema_token(
+			headers.get("x-ratelimit-limit")
+			or headers.get("x-rate-limit")
+			or headers.get("x-quota-limit")
+		),
+		"remaining_bucket": _bucket_remaining(
+			headers.get("x-ratelimit-remaining")
+			or headers.get("x-rate-limit-remaining")
+			or headers.get("x-quota-remaining")
+		),
+		"reset_after_ms_bucket": _bucket_reset_after_ms(headers),
+	}
+
+
+def build_subject_profile(
+	traits: Mapping[str, object] | None,
+) -> dict[str, JsonValue] | None:
+	if traits is None:
+		return None
+
+	display_name = _string_or_none(
+		traits.get("display_name") or traits.get("displayName")
+	)
+	avatar_url = _string_or_none(traits.get("avatar_url") or traits.get("avatarUrl"))
+	email = _string_or_none(
+		traits.get("email") or traits.get("email_address") or traits.get("emailAddress")
+	)
+	role = _string_or_none(traits.get("role"))
+	plan = _string_or_none(traits.get("plan"))
+
+	if all(value is None for value in (display_name, avatar_url, email, role, plan)):
+		return None
+
+	return {
+		"display_name": display_name,
+		"avatar_url": avatar_url,
+		"email": email,
+		"role": role,
+		"plan": plan,
+	}
+
+
+def _workspace_id_from_traits(traits: Mapping[str, object] | None) -> str | None:
+	if traits is None:
+		return None
+	return _string_or_none(traits.get("workspace_id") or traits.get("workspaceId"))
+
+
+def _visible_trait_keys(
+	traits: Mapping[str, object] | None,
+	denied_keys: Sequence[str],
+) -> list[str]:
+	return sorted(
+		str(key)
+		for key in (traits or {}).keys()
+		if not is_denied_key(str(key), denied_keys)
+	)
+
+
+def _duration_root_field(status: str, duration_ms: int | None) -> dict[str, int]:
+	if status == BACKEND_STATUS_STARTED:
+		return {}
+	if duration_ms is None:
+		raise ValueError("duration_ms is required for finished and failed events")
+	return {"duration_ms": duration_ms}
+
+
+def _masked_identifier(value: object | None) -> dict[str, JsonValue] | None:
+	if value is None:
+		return None
+	return build_mask_token("masked", value)
+
+
+def _internal_flow_context(
+	*,
+	context: Mapping[str, JsonValue],
+	span_id: str | None,
+	parent_span_id: str | None,
+	expected_otel_span_kind: str | None = None,
+) -> dict[str, JsonValue]:
+	event_context = merge_current_otel_span_context(
+		context,
+		expected_kind=expected_otel_span_kind,
+	)
+	current_span_id = _context_string(event_context, "span_id")
+	current_parent_span_id = _context_string(event_context, "parent_span_id")
+	resolved_parent_span_id = (
+		parent_span_id
+		or current_span_id
+		or current_parent_span_id
+	)
+	if resolved_parent_span_id is None:
+		raise ValueError("parent_span_id is required for internal flow events")
+	event_context["parent_span_id"] = resolved_parent_span_id
+	event_context["span_id"] = span_id or uuid.uuid4().hex[:16]
+	if _context_string(event_context, "trace_id") is None:
+		event_context["trace_id"] = uuid.uuid4().hex
+	return event_context
+
+
+def _now_iso() -> str:
+	return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def build_backend_context(
+	*,
+	service_name: str,
+	environment: str,
+	service_key: str | None = None,
+	producer_id: str | None = None,
+	tenant_id: str | None = None,
+	anonymous_id: str | None = None,
+	user_id: str | None = None,
+	account_id: str | None = None,
+	user_profile: Mapping[str, object] | None = None,
+	account_profile: Mapping[str, object] | None = None,
+	workspace_id: str | None = None,
+	session_id: str | None = None,
+	tab_id: str | None = None,
+	trace_id: str | None = None,
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+	request_id: str | None = None,
+	request_span_id: str | None = None,
+	interaction_id: str | None = None,
+	backend_release: str | None = None,
+	feature_flags: Sequence[str] = (),
+	experiment_variant: str | None = None,
+	runtime_language: str = BACKEND_RUNTIME_LANGUAGE,
+	sdk_collection_mode: str = SDK_COLLECTION_MODE_STANDARD,
+) -> dict[str, JsonValue]:
+	return {
+		"tenant_id": tenant_id,
+		"anonymous_id": anonymous_id,
+		"user_id": user_id,
+		"account_id": account_id,
+		"user_profile": build_subject_profile(user_profile),
+		"account_profile": build_subject_profile(account_profile),
+		"workspace_id": workspace_id,
+		"session_id": session_id,
+		"tab_id": tab_id,
+		"trace_id": trace_id,
+		"span_id": span_id,
+		"parent_span_id": parent_span_id,
+		"request_id": request_id,
+		"request_span_id": request_span_id,
+		"interaction_id": interaction_id,
+		"environment": environment,
+		"backend_release": backend_release,
+		"feature_flags": list(feature_flags),
+		"experiment_variant": experiment_variant,
+		"service_name": service_name,
+		"service_key": service_key or service_name,
+		"producer_id": producer_id or service_name,
+		"runtime_language": runtime_language,
+		"sdk_collection_mode": (
+			sdk_collection_mode
+			if sdk_collection_mode in {"standard", "diagnostic"}
+			else SDK_COLLECTION_MODE_STANDARD
+		),
+	}
+
+
+def _context_string(
+	context: Mapping[str, JsonValue],
+	key: str,
+) -> str | None:
+	value = context.get(key)
+	return value if isinstance(value, str) and value else None
+
+
+def _ensure_event_context(
+	context: Mapping[str, JsonValue],
+) -> dict[str, JsonValue]:
+	event_context = dict(context)
+	if _context_string(event_context, "trace_id") is None:
+		event_context["trace_id"] = uuid.uuid4().hex
+	if _context_string(event_context, "span_id") is None:
+		event_context["span_id"] = uuid.uuid4().hex[:16]
+	return event_context
+
+
+def _shared_event_identity(
+	*,
+	event_context: Mapping[str, JsonValue],
+	event_category: str,
+	event_name: str,
+) -> str | None:
+	request_span_id = _context_string(event_context, "request_span_id")
+	if event_category == EVENT_CATEGORY_REQUEST and request_span_id is not None:
+		return f"request:{request_span_id}:{event_name}"
+
+	trace_id = _context_string(event_context, "trace_id")
+	span_id = _context_string(event_context, "span_id")
+	if event_category in {
+		EVENT_CATEGORY_OUTBOUND_REQUEST,
+		EVENT_CATEGORY_JOB,
+		EVENT_CATEGORY_TOOL_CALL,
+		EVENT_CATEGORY_DOMAIN_COMMAND,
+		EVENT_CATEGORY_REPOSITORY_MUTATION,
+		EVENT_CATEGORY_STATE_TRANSITION,
+	} and trace_id is not None and span_id is not None:
+		return f"span:{event_category}:{trace_id}:{span_id}:{event_name}"
+
+	return None
+
+
+def _request_boundary_context(
+	*,
+	context: Mapping[str, JsonValue],
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+	request_span_id: str | None = None,
+	expected_otel_span_kind: str | None = None,
+) -> dict[str, JsonValue]:
+	event_context = _ensure_event_context(
+		merge_current_otel_span_context(
+			context,
+			expected_kind=expected_otel_span_kind,
+			use_otel_request_span_id=True,
+		)
+	)
+	if span_id is not None:
+		event_context["span_id"] = span_id
+	if parent_span_id is not None:
+		event_context["parent_span_id"] = parent_span_id
+	resolved_request_span_id = (
+		request_span_id or _context_string(event_context, "request_span_id")
+	)
+	event_context["request_span_id"] = (
+		resolved_request_span_id or f"rsp_{uuid.uuid4()}"
+	)
+	return event_context
+
+
+def _base_event(
+	*,
+	context: Mapping[str, JsonValue],
+	event_name: str,
+	event_category: str,
+	status: str,
+	surface_type: str,
+	privacy_level: str,
+	masking_state: str,
+	allowed_value_keys: Sequence[str],
+	custom_event_name: str | None = None,
+	root_fields: Mapping[str, JsonValue] | None = None,
+	properties: Mapping[str, JsonValue] | None = None,
+	metrics: Mapping[str, int | float] | None = None,
+) -> dict[str, JsonValue]:
+	occurred_at = _now_iso()
+	event_context = _ensure_event_context(context)
+	shared_event_identity = _shared_event_identity(
+		event_context=event_context,
+		event_category=event_category,
+		event_name=event_name,
+	)
+	event = {
+		"event_id": str(uuid.uuid4()),
+		"shared_event_identity": shared_event_identity,
+		"producer_id": event_context.get("producer_id"),
+		"event_name": event_name,
+		"custom_event_name": custom_event_name,
+		"event_category": event_category,
+		"event_source": "backend_sdk",
+		"event_version": 1,
+		"occurred_at": occurred_at,
+		"ingested_at": occurred_at,
+		"tenant_id": event_context.get("tenant_id"),
+		"anonymous_id": event_context.get("anonymous_id"),
+		"user_id": event_context.get("user_id"),
+		"account_id": event_context.get("account_id"),
+		"workspace_id": event_context.get("workspace_id"),
+		"session_id": event_context.get("session_id"),
+		"tab_id": event_context.get("tab_id"),
+		"trace_id": event_context.get("trace_id"),
+		"span_id": event_context.get("span_id"),
+		"parent_span_id": event_context.get("parent_span_id"),
+		"request_id": event_context.get("request_id"),
+		"request_span_id": event_context.get("request_span_id"),
+		"interaction_id": event_context.get("interaction_id"),
+		"service_name": event_context.get("service_name"),
+		"service_key": event_context.get("service_key"),
+		"runtime_language": event_context.get(
+			"runtime_language",
+			BACKEND_RUNTIME_LANGUAGE,
+		),
+		"status": status,
+		"sdk_collection_mode": event_context.get(
+			"sdk_collection_mode",
+			SDK_COLLECTION_MODE_STANDARD,
+		),
+		"surface_type": surface_type,
+		"environment": event_context.get("environment"),
+		"backend_release": event_context.get("backend_release"),
+		"feature_flags": list(event_context.get("feature_flags", [])),
+		"experiment_variant": event_context.get("experiment_variant"),
+		"privacy_level": privacy_level,
+		"masking_state": masking_state,
+		"allowed_value_keys": list(allowed_value_keys),
+		"properties": dict(properties or {}),
+		"metrics": dict(metrics or {}),
+	}
+	if event_context.get("user_profile") is not None:
+		event["user_profile"] = event_context.get("user_profile")
+	if event_context.get("account_profile") is not None:
+		event["account_profile"] = event_context.get("account_profile")
+	if root_fields:
+		event.update(dict(root_fields))
+	return event
+
+
+def _build_request_metadata(
+	*,
+	context: Mapping[str, JsonValue],
+	method: str,
+	host: str,
+	path: str,
+	path_template: str,
+	protocol: str | None,
+	query: Mapping[str, JsonValue],
+	headers: Mapping[str, JsonValue],
+	timeout_ms: int | None = None,
+	retry_count: int | None = None,
+) -> dict[str, JsonValue]:
+	return {
+		"service_name": _context_string(context, "service_name"),
+		"span_id": _context_string(context, "span_id"),
+		"parent_span_id": _context_string(context, "parent_span_id"),
+		"request_span_id": _context_string(context, "request_span_id"),
+		"interaction_id": _context_string(context, "interaction_id"),
+		"method": method,
+		"host": host,
+		"path": path,
+		"path_template": path_template,
+		"protocol": protocol,
+		"query_masked": bool(query),
+		"timeout_ms": timeout_ms,
+		"retry_count": retry_count,
+		"header_names": sorted(headers.keys()),
+	}
+
+
+def _build_response_metadata(
+	*,
+	context: Mapping[str, JsonValue],
+	method: str,
+	host: str,
+	path: str,
+	path_template: str,
+	protocol: str | None,
+	status_code: int,
+	duration_ms: int | None,
+	headers: Mapping[str, JsonValue],
+) -> dict[str, JsonValue]:
+	return {
+		"service_name": _context_string(context, "service_name"),
+		"span_id": _context_string(context, "span_id"),
+		"parent_span_id": _context_string(context, "parent_span_id"),
+		"request_span_id": _context_string(context, "request_span_id"),
+		"interaction_id": _context_string(context, "interaction_id"),
+		"method": method,
+		"host": host,
+		"path": path,
+		"path_template": path_template,
+		"protocol": protocol,
+		"status_code": status_code,
+		"duration_ms": duration_ms,
+		"header_names": sorted(headers.keys()),
+	}
+
+
+def _route_operation_source_key(method: str, path_template: str) -> str:
+	return f"route.{method.upper()}.{path_template}"
+
+
+def build_request_started_event(
+	request: object,
+	*,
+	context: Mapping[str, JsonValue],
+	handler_name: str | None = None,
+	allowed_value_paths: Sequence[str] = (),
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	event_context = _request_boundary_context(
+		context=context,
+		expected_otel_span_kind="SERVER",
+	)
+	headers = _extract_request_headers(request)
+	raw_path = "/"
+	if hasattr(request, "get_full_path") and callable(getattr(request, "get_full_path")):
+		raw_path = str(request.get_full_path())
+	elif hasattr(request, "path"):
+		raw_path = str(getattr(request, "path"))
+	scheme, host, path, parsed_query = _safe_urlsplit(raw_path)
+	query = _extract_query(getattr(request, "GET", None)) or parsed_query
+	body = _request_body(request)
+	method = str(getattr(request, "method", "GET")).upper() if getattr(request, "method", None) else "GET"
+	resolver_match = getattr(request, "resolver_match", None)
+	path_template = getattr(resolver_match, "route", None) or to_path_template(path)
+	operation_source_key = _route_operation_source_key(method, path_template)
+	request_parameters_snapshot, allowed_value_keys, privacy_level, masking_state = (
+		_build_request_parameter_snapshot(
+			query=query,
+			body=body,
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	request_schema_source: dict[str, JsonValue] = {}
+	if query:
+		request_schema_source["query"] = dict(query)
+	if body is not None:
+		request_schema_source["body"] = body
+	request_schema_evidence = _build_schema_evidence(
+		request_schema_source if request_schema_source else None,
+		denied_keys=denied_keys,
+	)
+	request_capture_counts = _count_capture_modes(request_parameters_snapshot)
+	event = _base_event(
+		context=event_context,
+		event_name=REQUEST_EVENT_STARTED,
+		event_category=EVENT_CATEGORY_REQUEST,
+		status=BACKEND_STATUS_STARTED,
+		surface_type=SURFACE_TYPE_API,
+		privacy_level=privacy_level,
+		masking_state=masking_state,
+		allowed_value_keys=allowed_value_keys,
+		root_fields={
+			"handler_name": handler_name,
+			"method": method,
+			"path_template": path_template,
+			"operation_source_type": "route",
+			"operation_source_key": operation_source_key,
+			"attempt_status": BACKEND_STATUS_STARTED,
+			"request_schema_hash": request_schema_evidence["schema_hash"],
+			"request_shape_size": request_schema_evidence["shape_size"],
+			"masked_value_count": request_capture_counts["masked_value_count"],
+			"forbidden_value_count": request_capture_counts["forbidden_value_count"],
+			"truncated_value_count": request_capture_counts["truncated_value_count"],
+		},
+		properties={
+			"service_name": event_context.get("service_name"),
+			"service_key": event_context.get("service_key"),
+			"handler_name": handler_name,
+			"method": method,
+			"path_template": path_template,
+			"operation_source_type": "route",
+			"operation_source_key": operation_source_key,
+			"attempt_status": BACKEND_STATUS_STARTED,
+			"request_schema_hash": request_schema_evidence["schema_hash"],
+			"request_field_paths": request_schema_evidence["field_paths"],
+			"request_shape_size": request_schema_evidence["shape_size"],
+			"masked_value_count": request_capture_counts["masked_value_count"],
+			"forbidden_value_count": request_capture_counts["forbidden_value_count"],
+			"truncated_value_count": request_capture_counts["truncated_value_count"],
+		},
+	)
+	event["request_metadata"] = _build_request_metadata(
+		context=event_context,
+		method=method,
+		host=host or str(headers.get("host", "") or ""),
+		path=path,
+		path_template=path_template,
+		protocol=scheme or getattr(request, "scheme", None),
+		query=query,
+		headers=headers,
+	)
+	event["request_parameters_snapshot_json"] = request_parameters_snapshot
+	return event
+
+
+def build_request_finished_event(
+	request: object,
+	response: object,
+	*,
+	context: Mapping[str, JsonValue],
+	handler_name: str | None = None,
+	duration_ms: int,
+	allowed_value_paths: Sequence[str] = (),
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	event_context = _request_boundary_context(
+		context=context,
+		expected_otel_span_kind="SERVER",
+	)
+	headers = _extract_response_headers(response)
+	raw_path = "/"
+	if hasattr(request, "get_full_path") and callable(getattr(request, "get_full_path")):
+		raw_path = str(request.get_full_path())
+	elif hasattr(request, "path"):
+		raw_path = str(getattr(request, "path"))
+	_, _, path, _ = _safe_urlsplit(raw_path)
+	method = str(getattr(request, "method", "GET")).upper() if getattr(request, "method", None) else "GET"
+	resolver_match = getattr(request, "resolver_match", None)
+	path_template = getattr(resolver_match, "route", None) or to_path_template(path)
+	operation_source_key = _route_operation_source_key(method, path_template)
+	status_code = int(getattr(response, "status_code", 200))
+	request_headers = _extract_request_headers(request)
+	request_query = _extract_query(getattr(request, "GET", None))
+	request_body = _request_body(request)
+	request_parameters_snapshot, request_allowed_value_keys, request_privacy_level, request_masking_state = (
+		_build_request_parameter_snapshot(
+			query=request_query,
+			body=request_body,
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	response_body = _response_body(response)
+	response_parameters_snapshot, response_allowed_value_keys, response_privacy_level, response_masking_state = (
+		_build_response_parameter_snapshot(
+			body=response_body,
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	request_schema_source: dict[str, JsonValue] = {}
+	if request_query:
+		request_schema_source["query"] = dict(request_query)
+	if request_body is not None:
+		request_schema_source["body"] = request_body
+	request_schema_evidence = _build_schema_evidence(
+		request_schema_source if request_schema_source else None,
+		denied_keys=denied_keys,
+	)
+	response_schema_evidence = _build_schema_evidence(
+		response_body,
+		denied_keys=denied_keys,
+	)
+	request_capture_counts = _count_capture_modes(request_parameters_snapshot)
+	response_capture_counts = _count_capture_modes(response_parameters_snapshot)
+	capture_counts = {
+		key: request_capture_counts[key] + response_capture_counts[key]
+		for key in request_capture_counts
+	}
+	outcome_evidence = _derive_outcome_evidence(
+		status_code=status_code,
+		response_body=response_body,
+		headers=headers,
+	)
+	allowed_value_keys = sorted(
+		dict.fromkeys([*request_allowed_value_keys, *response_allowed_value_keys])
+	)
+	duration_root_field = _duration_root_field(BACKEND_STATUS_FINISHED, duration_ms)
+	event = _base_event(
+		context=event_context,
+		event_name=REQUEST_EVENT_FINISHED,
+		event_category=EVENT_CATEGORY_REQUEST,
+		status=BACKEND_STATUS_FINISHED,
+		surface_type=SURFACE_TYPE_API,
+		privacy_level=
+			"allowlisted"
+			if request_privacy_level == "allowlisted"
+			or response_privacy_level == "allowlisted"
+			else "default_masked",
+		masking_state=
+			"partially_unmasked"
+			if request_masking_state == "partially_unmasked"
+			or response_masking_state == "partially_unmasked"
+			else "masked",
+		allowed_value_keys=allowed_value_keys,
+		root_fields={
+			"handler_name": handler_name,
+			"method": method,
+			"path_template": path_template,
+			"operation_source_type": "route",
+			"operation_source_key": operation_source_key,
+			"attempt_status": BACKEND_STATUS_FINISHED,
+			"validation_field_paths": outcome_evidence["field_paths"],
+			"status_code": status_code,
+			**duration_root_field,
+			"outcome_class": outcome_evidence["outcome_class"],
+			"decision_type": outcome_evidence["decision_type"],
+			"decision_result": outcome_evidence["decision_result"],
+			"reason_code": outcome_evidence["reason_code"],
+			"request_schema_hash": request_schema_evidence["schema_hash"],
+			"response_schema_hash": response_schema_evidence["schema_hash"],
+			"request_shape_size": request_schema_evidence["shape_size"],
+			"response_shape_size": response_schema_evidence["shape_size"],
+			"masked_value_count": capture_counts["masked_value_count"],
+			"forbidden_value_count": capture_counts["forbidden_value_count"],
+			"truncated_value_count": capture_counts["truncated_value_count"],
+		},
+		properties={
+			"service_name": event_context.get("service_name"),
+			"service_key": event_context.get("service_key"),
+			"handler_name": handler_name,
+			"method": method,
+			"path_template": path_template,
+			"operation_source_type": "route",
+			"operation_source_key": operation_source_key,
+			"attempt_status": BACKEND_STATUS_FINISHED,
+			"outcome_class": outcome_evidence["outcome_class"],
+			"decision_type": outcome_evidence["decision_type"],
+			"decision_result": outcome_evidence["decision_result"],
+			"reason_code": outcome_evidence["reason_code"],
+			"error_code_candidate": outcome_evidence["error_code_candidate"],
+			"field_paths": outcome_evidence["field_paths"],
+			"validation_reason_codes": outcome_evidence["validation_reason_codes"],
+			"error_count": outcome_evidence["error_count"],
+			"limit_name": outcome_evidence["limit_name"],
+			"remaining_bucket": outcome_evidence["remaining_bucket"],
+			"reset_after_ms_bucket": outcome_evidence["reset_after_ms_bucket"],
+			"request_schema_hash": request_schema_evidence["schema_hash"],
+			"response_schema_hash": response_schema_evidence["schema_hash"],
+			"request_field_paths": request_schema_evidence["field_paths"],
+			"response_field_paths": response_schema_evidence["field_paths"],
+			"request_shape_size": request_schema_evidence["shape_size"],
+			"response_shape_size": response_schema_evidence["shape_size"],
+			"masked_value_count": capture_counts["masked_value_count"],
+			"forbidden_value_count": capture_counts["forbidden_value_count"],
+			"truncated_value_count": capture_counts["truncated_value_count"],
+		},
+		metrics={
+			"status_code": status_code,
+			**duration_root_field,
+			"error_count": int(outcome_evidence["error_count"]),
+			"request_shape_size": int(request_schema_evidence["shape_size"]),
+			"response_shape_size": int(response_schema_evidence["shape_size"]),
+		},
+	)
+	event["request_metadata"] = _build_request_metadata(
+		context=event_context,
+		method=method,
+		host=str(request_headers.get("host", "") or ""),
+		path=path,
+		path_template=path_template,
+		protocol=getattr(request, "scheme", None),
+		query=request_query,
+		headers=request_headers,
+	)
+	event["request_parameters_snapshot_json"] = request_parameters_snapshot
+	event["response_metadata"] = _build_response_metadata(
+		context=event_context,
+		method=method,
+		host=str(headers.get("host", "") or ""),
+		path=path,
+		path_template=path_template,
+		protocol=getattr(request, "scheme", None),
+		status_code=status_code,
+		duration_ms=duration_root_field["duration_ms"],
+		headers=headers,
+	)
+	event["response_parameters_snapshot_json"] = response_parameters_snapshot
+	return event
+
+
+def build_request_failed_event(
+	request: object,
+	*,
+	context: Mapping[str, JsonValue],
+	handler_name: str | None = None,
+	status_code: int = 500,
+	duration_ms: int,
+	response: object | None = None,
+	allowed_value_paths: Sequence[str] = (),
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	event_context = _request_boundary_context(
+		context=context,
+		expected_otel_span_kind="SERVER",
+	)
+	headers = _extract_response_headers(response) if response is not None else {}
+	raw_path = "/"
+	if hasattr(request, "get_full_path") and callable(getattr(request, "get_full_path")):
+		raw_path = str(request.get_full_path())
+	elif hasattr(request, "path"):
+		raw_path = str(getattr(request, "path"))
+	_, _, path, _ = _safe_urlsplit(raw_path)
+	method = str(getattr(request, "method", "GET")).upper() if getattr(request, "method", None) else "GET"
+	resolver_match = getattr(request, "resolver_match", None)
+	path_template = getattr(resolver_match, "route", None) or to_path_template(path)
+	operation_source_key = _route_operation_source_key(method, path_template)
+	request_headers = _extract_request_headers(request)
+	request_query = _extract_query(getattr(request, "GET", None))
+	request_body = _request_body(request)
+	request_parameters_snapshot, request_allowed_value_keys, request_privacy_level, request_masking_state = (
+		_build_request_parameter_snapshot(
+			query=request_query,
+			body=request_body,
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	response_body = _response_body(response)
+	response_parameters_snapshot, response_allowed_value_keys, response_privacy_level, response_masking_state = (
+		_build_response_parameter_snapshot(
+			body=response_body,
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	request_schema_source: dict[str, JsonValue] = {}
+	if request_query:
+		request_schema_source["query"] = dict(request_query)
+	if request_body is not None:
+		request_schema_source["body"] = request_body
+	request_schema_evidence = _build_schema_evidence(
+		request_schema_source if request_schema_source else None,
+		denied_keys=denied_keys,
+	)
+	response_schema_evidence = _build_schema_evidence(
+		response_body,
+		denied_keys=denied_keys,
+	)
+	request_capture_counts = _count_capture_modes(request_parameters_snapshot)
+	response_capture_counts = _count_capture_modes(response_parameters_snapshot)
+	capture_counts = {
+		key: request_capture_counts[key] + response_capture_counts[key]
+		for key in request_capture_counts
+	}
+	outcome_evidence = _derive_outcome_evidence(
+		status_code=status_code,
+		response_body=response_body,
+		headers=headers,
+	)
+	allowed_value_keys = sorted(
+		dict.fromkeys([*request_allowed_value_keys, *response_allowed_value_keys])
+	)
+	duration_root_field = _duration_root_field(BACKEND_STATUS_FAILED, duration_ms)
+	event = _base_event(
+		context=event_context,
+		event_name=REQUEST_EVENT_FAILED,
+		event_category=EVENT_CATEGORY_REQUEST,
+		status=BACKEND_STATUS_FAILED,
+		surface_type=SURFACE_TYPE_API,
+		privacy_level=
+			"allowlisted"
+			if request_privacy_level == "allowlisted"
+			or response_privacy_level == "allowlisted"
+			else "default_masked",
+		masking_state=
+			"partially_unmasked"
+			if request_masking_state == "partially_unmasked"
+			or response_masking_state == "partially_unmasked"
+			else "masked",
+		allowed_value_keys=allowed_value_keys,
+		root_fields={
+			"handler_name": handler_name,
+			"method": method,
+			"path_template": path_template,
+			"operation_source_type": "route",
+			"operation_source_key": operation_source_key,
+			"attempt_status": BACKEND_STATUS_FAILED,
+			"validation_field_paths": outcome_evidence["field_paths"],
+			"status_code": status_code,
+			**duration_root_field,
+			"outcome_class": outcome_evidence["outcome_class"],
+			"decision_type": outcome_evidence["decision_type"],
+			"decision_result": outcome_evidence["decision_result"],
+			"reason_code": outcome_evidence["reason_code"],
+			"request_schema_hash": request_schema_evidence["schema_hash"],
+			"response_schema_hash": response_schema_evidence["schema_hash"],
+			"request_shape_size": request_schema_evidence["shape_size"],
+			"response_shape_size": response_schema_evidence["shape_size"],
+			"masked_value_count": capture_counts["masked_value_count"],
+			"forbidden_value_count": capture_counts["forbidden_value_count"],
+			"truncated_value_count": capture_counts["truncated_value_count"],
+		},
+		properties={
+			"service_name": event_context.get("service_name"),
+			"service_key": event_context.get("service_key"),
+			"handler_name": handler_name,
+			"method": method,
+			"path_template": path_template,
+			"operation_source_type": "route",
+			"operation_source_key": operation_source_key,
+			"attempt_status": BACKEND_STATUS_FAILED,
+			"outcome_class": outcome_evidence["outcome_class"],
+			"decision_type": outcome_evidence["decision_type"],
+			"decision_result": outcome_evidence["decision_result"],
+			"reason_code": outcome_evidence["reason_code"],
+			"error_code_candidate": outcome_evidence["error_code_candidate"],
+			"field_paths": outcome_evidence["field_paths"],
+			"validation_reason_codes": outcome_evidence["validation_reason_codes"],
+			"error_count": outcome_evidence["error_count"],
+			"limit_name": outcome_evidence["limit_name"],
+			"remaining_bucket": outcome_evidence["remaining_bucket"],
+			"reset_after_ms_bucket": outcome_evidence["reset_after_ms_bucket"],
+			"request_schema_hash": request_schema_evidence["schema_hash"],
+			"response_schema_hash": response_schema_evidence["schema_hash"],
+			"request_field_paths": request_schema_evidence["field_paths"],
+			"response_field_paths": response_schema_evidence["field_paths"],
+			"request_shape_size": request_schema_evidence["shape_size"],
+			"response_shape_size": response_schema_evidence["shape_size"],
+			"masked_value_count": capture_counts["masked_value_count"],
+			"forbidden_value_count": capture_counts["forbidden_value_count"],
+			"truncated_value_count": capture_counts["truncated_value_count"],
+		},
+		metrics={
+			"status_code": status_code,
+			**duration_root_field,
+			"error_count": int(outcome_evidence["error_count"]),
+			"request_shape_size": int(request_schema_evidence["shape_size"]),
+			"response_shape_size": int(response_schema_evidence["shape_size"]),
+		},
+	)
+	event["request_metadata"] = _build_request_metadata(
+		context=event_context,
+		method=method,
+		host=str(request_headers.get("host", "") or ""),
+		path=path,
+		path_template=path_template,
+		protocol=getattr(request, "scheme", None),
+		query=request_query,
+		headers=request_headers,
+	)
+	event["request_parameters_snapshot_json"] = request_parameters_snapshot
+	event["response_metadata"] = _build_response_metadata(
+		context=event_context,
+		method=method,
+		host=str(headers.get("host", "") or ""),
+		path=path,
+		path_template=path_template,
+		protocol=getattr(request, "scheme", None),
+		status_code=status_code,
+		duration_ms=duration_root_field["duration_ms"],
+		headers=headers,
+	)
+	event["response_parameters_snapshot_json"] = response_parameters_snapshot
+	return event
+
+
+def build_outbound_request_started_event(
+	*,
+	context: Mapping[str, JsonValue],
+	method: str,
+	url: str,
+	request_body: object = None,
+	request_headers: Mapping[str, object] | None = None,
+	timeout_ms: int | None = None,
+	retry_count: int | None = None,
+	allowed_value_paths: Sequence[str] = (),
+	denied_keys: Sequence[str] = (),
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+	request_span_id: str | None = None,
+) -> dict[str, JsonValue]:
+	scheme, host, path, query = _safe_urlsplit(url)
+	path_template = to_path_template(path)
+	headers = _normalize_headers(request_headers or {})
+	request_parameters_snapshot, allowed_value_keys, privacy_level, masking_state = (
+		_build_request_parameter_snapshot(
+			query=query,
+			body=_to_json_value(request_body),
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	event_context = _request_boundary_context(
+		context=context,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+		request_span_id=request_span_id,
+		expected_otel_span_kind="CLIENT",
+	)
+
+	event = _base_event(
+		context=event_context,
+		event_name=OUTBOUND_REQUEST_EVENT_STARTED,
+		event_category=EVENT_CATEGORY_OUTBOUND_REQUEST,
+		status=BACKEND_STATUS_STARTED,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level=privacy_level,
+		masking_state=masking_state,
+		allowed_value_keys=allowed_value_keys,
+		root_fields={
+			"method": method.upper(),
+			"path_template": path_template,
+			"target_service": host or None,
+		},
+		properties={
+			"service_name": event_context.get("service_name"),
+			"target_service": host or None,
+			"method": method.upper(),
+			"path_template": path_template,
+			"failure_type": None,
+		},
+	)
+	event["request_metadata"] = _build_request_metadata(
+		context=event_context,
+		method=method.upper(),
+		host=host,
+		path=path,
+		path_template=path_template,
+		protocol=scheme or None,
+		query=query,
+		headers=headers,
+		timeout_ms=timeout_ms,
+		retry_count=retry_count,
+	)
+	event["request_parameters_snapshot_json"] = request_parameters_snapshot
+	return event
+
+
+def build_outbound_request_finished_event(
+	*,
+	context: Mapping[str, JsonValue],
+	method: str,
+	url: str,
+	status_code: int,
+	duration_ms: int,
+	request_body: object = None,
+	request_headers: Mapping[str, object] | None = None,
+	response_body: object = None,
+	response_headers: Mapping[str, object] | None = None,
+	allowed_value_paths: Sequence[str] = (),
+	denied_keys: Sequence[str] = (),
+	timeout_ms: int | None = None,
+	retry_count: int | None = None,
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+	request_span_id: str | None = None,
+) -> dict[str, JsonValue]:
+	scheme, host, path, query = _safe_urlsplit(url)
+	path_template = to_path_template(path)
+	request_header_record = _normalize_headers(request_headers or {})
+	headers = _normalize_headers(response_headers or {})
+	request_parameters_snapshot, request_allowed_value_keys, request_privacy_level, request_masking_state = (
+		_build_request_parameter_snapshot(
+			query=query,
+			body=_to_json_value(request_body),
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	response_parameters_snapshot, response_allowed_value_keys, response_privacy_level, response_masking_state = (
+		_build_response_parameter_snapshot(
+			body=_to_json_value(response_body),
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	allowed_value_keys = sorted(
+		dict.fromkeys([*request_allowed_value_keys, *response_allowed_value_keys])
+	)
+	event_context = _request_boundary_context(
+		context=context,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+		request_span_id=request_span_id,
+		expected_otel_span_kind="CLIENT",
+	)
+	duration_root_field = _duration_root_field(BACKEND_STATUS_FINISHED, duration_ms)
+
+	event = _base_event(
+		context=event_context,
+		event_name=OUTBOUND_REQUEST_EVENT_FINISHED,
+		event_category=EVENT_CATEGORY_OUTBOUND_REQUEST,
+		status=BACKEND_STATUS_FINISHED,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level=
+			"allowlisted"
+			if request_privacy_level == "allowlisted"
+			or response_privacy_level == "allowlisted"
+			else "default_masked",
+		masking_state=
+			"partially_unmasked"
+			if request_masking_state == "partially_unmasked"
+			or response_masking_state == "partially_unmasked"
+			else "masked",
+		allowed_value_keys=allowed_value_keys,
+		root_fields={
+			"method": method.upper(),
+			"path_template": path_template,
+			"target_service": host or None,
+			"status_code": status_code,
+			**duration_root_field,
+		},
+		properties={
+			"service_name": event_context.get("service_name"),
+			"target_service": host or None,
+			"method": method.upper(),
+			"path_template": path_template,
+			"failure_type": None,
+		},
+		metrics={
+			"status_code": status_code,
+			**duration_root_field,
+		},
+	)
+	event["request_metadata"] = _build_request_metadata(
+		context=event_context,
+		method=method.upper(),
+		host=host,
+		path=path,
+		path_template=path_template,
+		protocol=scheme or None,
+		query=query,
+		headers=request_header_record,
+		timeout_ms=timeout_ms,
+		retry_count=retry_count,
+	)
+	event["request_parameters_snapshot_json"] = request_parameters_snapshot
+	event["response_metadata"] = _build_response_metadata(
+		context=event_context,
+		method=method.upper(),
+		host=host,
+		path=path,
+		path_template=path_template,
+		protocol=scheme or None,
+		status_code=status_code,
+		duration_ms=duration_root_field["duration_ms"],
+		headers=headers,
+	)
+	event["response_parameters_snapshot_json"] = response_parameters_snapshot
+	return event
+
+
+def build_outbound_request_failed_event(
+	*,
+	context: Mapping[str, JsonValue],
+	method: str,
+	url: str,
+	failure_type: str,
+	duration_ms: int,
+	status_code: int,
+	request_body: object = None,
+	request_headers: Mapping[str, object] | None = None,
+	response_body: object = None,
+	response_headers: Mapping[str, object] | None = None,
+	allowed_value_paths: Sequence[str] = (),
+	denied_keys: Sequence[str] = (),
+	timeout_ms: int | None = None,
+	retry_count: int | None = None,
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+	request_span_id: str | None = None,
+) -> dict[str, JsonValue]:
+	scheme, host, path, query = _safe_urlsplit(url)
+	path_template = to_path_template(path)
+	request_header_record = _normalize_headers(request_headers or {})
+	response_header_record = _normalize_headers(response_headers or {})
+	request_parameters_snapshot, request_allowed_value_keys, request_privacy_level, request_masking_state = (
+		_build_request_parameter_snapshot(
+			query=query,
+			body=_to_json_value(request_body),
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	response_parameters_snapshot, response_allowed_value_keys, response_privacy_level, response_masking_state = (
+		_build_response_parameter_snapshot(
+			body=_to_json_value(response_body),
+			allowed_value_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+		)
+	)
+	allowed_value_keys = sorted(
+		dict.fromkeys([*request_allowed_value_keys, *response_allowed_value_keys])
+	)
+	event_context = _request_boundary_context(
+		context=context,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+		request_span_id=request_span_id,
+		expected_otel_span_kind="CLIENT",
+	)
+	duration_root_field = _duration_root_field(BACKEND_STATUS_FAILED, duration_ms)
+	event = _base_event(
+		context=event_context,
+		event_name=OUTBOUND_REQUEST_EVENT_FAILED,
+		event_category=EVENT_CATEGORY_OUTBOUND_REQUEST,
+		status=BACKEND_STATUS_FAILED,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level=
+			"allowlisted"
+			if request_privacy_level == "allowlisted"
+			or response_privacy_level == "allowlisted"
+			else "default_masked",
+		masking_state=
+			"partially_unmasked"
+			if request_masking_state == "partially_unmasked"
+			or response_masking_state == "partially_unmasked"
+			else "masked",
+		allowed_value_keys=allowed_value_keys,
+		root_fields={
+			"method": method.upper(),
+			"path_template": path_template,
+			"target_service": host or None,
+			"failure_type": failure_type,
+			"status_code": status_code,
+			**duration_root_field,
+		},
+		properties={
+			"service_name": event_context.get("service_name"),
+			"target_service": host or None,
+			"method": method.upper(),
+			"path_template": path_template,
+			"failure_type": failure_type,
+		},
+		metrics={
+			"status_code": status_code,
+			**duration_root_field,
+		},
+	)
+	event["request_metadata"] = _build_request_metadata(
+		context=event_context,
+		method=method.upper(),
+		host=host,
+		path=path,
+		path_template=path_template,
+		protocol=scheme or None,
+		query=query,
+		headers=request_header_record,
+		timeout_ms=timeout_ms,
+		retry_count=retry_count,
+	)
+	event["request_parameters_snapshot_json"] = request_parameters_snapshot
+	event["response_metadata"] = _build_response_metadata(
+		context=event_context,
+		method=method.upper(),
+		host=host,
+		path=path,
+		path_template=path_template,
+		protocol=scheme or None,
+		status_code=status_code,
+		duration_ms=duration_root_field["duration_ms"],
+		headers=response_header_record,
+	)
+	event["response_parameters_snapshot_json"] = response_parameters_snapshot
+	return event
+
+
+def build_backend_error_event(
+	*,
+	context: Mapping[str, JsonValue],
+	handler_name: str | None,
+	failure_type: str,
+	error_class: str,
+	message: str | None = None,
+	exception: BaseException | None = None,
+) -> dict[str, JsonValue]:
+	message_for_fingerprint = message or error_class
+	error_fingerprint = "err_" + hashlib.sha256(
+		f"{error_class}:{message_for_fingerprint}".encode("utf-8"),
+	).hexdigest()[:16]
+	stack_summary = extract_tb(exception.__traceback__) if exception is not None else []
+	stack_signature = "|".join(
+		f"{Path(frame.filename).name}:{frame.name}" for frame in stack_summary[-8:]
+	)
+	stack_fingerprint = (
+		"stk_" + hashlib.sha256(stack_signature.encode("utf-8")).hexdigest()[:16]
+		if stack_signature
+		else None
+	)
+	top_frame = stack_summary[-1] if stack_summary else None
+	top_frame_module = (
+		f"{Path(top_frame.filename).stem}:{top_frame.name}"
+		if top_frame is not None
+		else None
+	)
+
+	return _base_event(
+		context=context,
+		event_name=BACKEND_ERROR_EVENT,
+		event_category=EVENT_CATEGORY_ERROR,
+		status=BACKEND_STATUS_FAILED,
+		surface_type=SURFACE_TYPE_API,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		root_fields={
+			"handler_name": handler_name,
+			"failure_type": failure_type,
+			"error_class": error_class,
+			"message_masked": build_mask_token("masked", message or error_class),
+			"error_fingerprint": error_fingerprint,
+			"stack_fingerprint": stack_fingerprint,
+			"top_frame_module": top_frame_module,
+			"stack_frame_count": len(stack_summary),
+		},
+		properties={
+			"service_name": context.get("service_name"),
+			"handler_name": handler_name,
+			"failure_type": failure_type,
+			"error_class": error_class,
+			"message_masked": build_mask_token("masked", message or error_class),
+			"error_fingerprint": error_fingerprint,
+			"stack_fingerprint": stack_fingerprint,
+			"top_frame_module": top_frame_module,
+			"stack_frame_count": len(stack_summary),
+		},
+	)
+
+
+def build_celery_job_event(
+	*,
+	context: Mapping[str, JsonValue],
+	status: str,
+	task_name: str,
+	task_id: str | None = None,
+	queue_name: str | None = None,
+	duration_ms: int | None = None,
+	failure_reason: str | None = None,
+	correlation_id: str | None = None,
+	message_id_masked: str | None = None,
+	parent_request_span_id: str | None = None,
+	delay_ms: int | None = None,
+	attempt_count: int | None = None,
+	max_attempts: int | None = None,
+	failure_type: str | None = None,
+	dlq_reason: str | None = None,
+	detail_reason: str | None = None,
+) -> dict[str, JsonValue]:
+	event_context = merge_current_otel_span_context(
+		context,
+		expected_kind="CONSUMER",
+	)
+	event_name = JOB_EVENT_BY_STATUS[status]
+	failure_reason_masked = (
+		build_mask_token("masked", failure_reason)
+		if status == BACKEND_STATUS_FAILED and failure_reason is not None
+		else None
+	)
+	properties: dict[str, JsonValue] = {
+		"service_name": context.get("service_name"),
+		"job_id": task_id,
+		"job_type": task_name,
+		"queue_name": queue_name,
+		"message_operation": "consume",
+		"messaging_system": "celery",
+		"message_type": task_name,
+		"destination_name": queue_name,
+		"message_id_masked": message_id_masked,
+		"correlation_id": correlation_id,
+		"parent_request_span_id": parent_request_span_id,
+		"delay_ms": delay_ms,
+		"attempt_count": attempt_count,
+		"max_attempts": max_attempts,
+		"failure_type": failure_type,
+		"dlq_reason": dlq_reason,
+		"detail_reason": detail_reason,
+	}
+	metrics = {"duration_ms": duration_ms} if duration_ms is not None else {}
+	if delay_ms is not None:
+		metrics["delay_ms"] = delay_ms
+	if attempt_count is not None:
+		metrics["attempt_count"] = attempt_count
+	root_fields: dict[str, JsonValue] = {
+		"job_id": task_id,
+		"job_type": task_name,
+		"queue_name": queue_name,
+		"message_operation": "consume",
+		"messaging_system": "celery",
+		"message_type": task_name,
+		"destination_name": queue_name,
+		"message_id_masked": message_id_masked,
+		"correlation_id": correlation_id,
+		"parent_request_span_id": parent_request_span_id,
+		"delay_ms": delay_ms,
+		"attempt_count": attempt_count,
+		"max_attempts": max_attempts,
+		"failure_type": failure_type,
+		"dlq_reason": dlq_reason,
+		"detail_reason": detail_reason,
+	}
+	if status in {BACKEND_STATUS_FINISHED, BACKEND_STATUS_FAILED}:
+		duration_root_fields = _duration_root_field(status, duration_ms)
+		root_fields.update(duration_root_fields)
+		metrics.update(duration_root_fields)
+	if status == BACKEND_STATUS_FAILED:
+		root_fields["failure_reason_masked"] = failure_reason_masked
+		properties["failure_reason_masked"] = failure_reason_masked
+	return _base_event(
+		context=event_context,
+		event_name=event_name,
+		event_category=EVENT_CATEGORY_JOB,
+		status=status,
+		surface_type=SURFACE_TYPE_JOB,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		root_fields=root_fields,
+		properties=properties,
+		metrics=metrics,
+	)
+
+
+def build_tool_call_event(
+	*,
+	context: Mapping[str, JsonValue],
+	status: str,
+	tool_provider: str,
+	tool_name: str,
+	tool_call_id: str | None = None,
+	tool_schema_hash: str | None = None,
+	validation_field_paths: Sequence[str] = (),
+	duration_ms: int | None = None,
+	failure_type: str | None = None,
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+) -> dict[str, JsonValue]:
+	event_context = _internal_flow_context(
+		context=context,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+		expected_otel_span_kind="INTERNAL",
+	)
+	normalized_provider = _string_or_none(tool_provider)
+	normalized_name = _string_or_none(tool_name)
+	if normalized_provider is None:
+		raise ValueError("tool_provider is required")
+	if normalized_name is None:
+		raise ValueError("tool_name is required")
+	operation_source_key = f"tool.{normalized_provider}.{normalized_name}"
+	outcome_class, reason_code = _tool_call_outcome(
+		status=status,
+		failure_type=failure_type,
+	)
+	root_fields: dict[str, JsonValue] = {
+		"tool_provider": normalized_provider,
+		"tool_name": normalized_name,
+		"tool_call_id": _string_or_none(tool_call_id),
+		"tool_schema_hash": _string_or_none(tool_schema_hash),
+		"operation_source_type": "tool_call",
+		"operation_source_key": operation_source_key,
+		"attempt_status": status,
+		"validation_field_paths": list(validation_field_paths),
+	}
+	if outcome_class is not None:
+		root_fields["outcome_class"] = outcome_class
+	if reason_code is not None:
+		root_fields["reason_code"] = reason_code
+	if _string_or_none(failure_type) is not None:
+		root_fields["failure_type"] = _string_or_none(failure_type)
+	root_fields.update(_duration_root_field(status, duration_ms))
+	properties = {
+		"service_name": event_context.get("service_name"),
+		"service_key": event_context.get("service_key"),
+		"tool_provider": normalized_provider,
+		"tool_name": normalized_name,
+		"tool_schema_hash": _string_or_none(tool_schema_hash),
+		"operation_source_type": "tool_call",
+		"operation_source_key": operation_source_key,
+		"attempt_status": status,
+		"validation_field_paths": list(validation_field_paths),
+	}
+	if outcome_class is not None:
+		properties["outcome_class"] = outcome_class
+	if reason_code is not None:
+		properties["reason_code"] = reason_code
+	if _string_or_none(failure_type) is not None:
+		properties["failure_type"] = _string_or_none(failure_type)
+	return _base_event(
+		context=event_context,
+		event_name=TOOL_CALL_EVENT_BY_STATUS[status],
+		event_category=EVENT_CATEGORY_TOOL_CALL,
+		status=status,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		root_fields=root_fields,
+		properties=properties,
+		metrics=_duration_root_field(status, duration_ms),
+	)
+
+
+def _tool_call_outcome(
+	*,
+	status: str,
+	failure_type: str | None,
+) -> tuple[str | None, str | None]:
+	if status == BACKEND_STATUS_FINISHED:
+		return "success", None
+
+	if status != BACKEND_STATUS_FAILED:
+		return None, None
+
+	normalized_failure_type = _string_or_none(failure_type)
+	if normalized_failure_type in {"validation", "validation_error", "schema_validation"}:
+		return "validation_error", normalized_failure_type
+	if normalized_failure_type in {
+		"permission_denied",
+		"auth_denied",
+		"not_found",
+		"conflict",
+		"rate_limited",
+	}:
+		return normalized_failure_type, normalized_failure_type
+	return "server_error", normalized_failure_type
+
+
+def build_domain_command_event(
+	*,
+	context: Mapping[str, JsonValue],
+	status: str,
+	command_key: str,
+	command_label: str | None = None,
+	duration_ms: int | None = None,
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+) -> dict[str, JsonValue]:
+	event_context = _internal_flow_context(
+		context=context,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+		expected_otel_span_kind="INTERNAL",
+	)
+	root_fields: dict[str, JsonValue] = {
+		"command_key": command_key,
+		"command_label": command_label,
+	}
+	root_fields.update(_duration_root_field(status, duration_ms))
+	return _base_event(
+		context=event_context,
+		event_name=DOMAIN_COMMAND_EVENT_BY_STATUS[status],
+		event_category=EVENT_CATEGORY_DOMAIN_COMMAND,
+		status=status,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		root_fields=root_fields,
+		properties={
+			"service_name": event_context.get("service_name"),
+			"command_key": command_key,
+			"command_label": command_label,
+		},
+		metrics=_duration_root_field(status, duration_ms),
+	)
+
+
+def build_repository_mutation_event(
+	*,
+	context: Mapping[str, JsonValue],
+	status: str,
+	mutation_key: str,
+	mutation_kind: str,
+	repository_name: str | None = None,
+	changed_fields_schema: Sequence[str] = (),
+	entity_id: object | None = None,
+	duration_ms: int | None = None,
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+) -> dict[str, JsonValue]:
+	if mutation_kind not in BACKEND_MUTATION_KINDS:
+		allowed_values = ", ".join(BACKEND_MUTATION_KINDS)
+		raise ValueError(f"mutation_kind must be one of: {allowed_values}")
+	event_context = _internal_flow_context(
+		context=context,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+		expected_otel_span_kind="CLIENT",
+	)
+	root_fields: dict[str, JsonValue] = {
+		"mutation_key": mutation_key,
+		"mutation_kind": mutation_kind,
+		"repository_name": repository_name,
+		"changed_fields_schema": list(changed_fields_schema),
+		"entity_id_masked": _masked_identifier(entity_id),
+	}
+	root_fields.update(_duration_root_field(status, duration_ms))
+	return _base_event(
+		context=event_context,
+		event_name=REPOSITORY_MUTATION_EVENT_BY_STATUS[status],
+		event_category=EVENT_CATEGORY_REPOSITORY_MUTATION,
+		status=status,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		root_fields=root_fields,
+		properties={
+			"service_name": event_context.get("service_name"),
+			"mutation_key": mutation_key,
+			"mutation_kind": mutation_kind,
+			"repository_name": repository_name,
+			"changed_fields_schema": list(changed_fields_schema),
+		},
+		metrics=_duration_root_field(status, duration_ms),
+	)
+
+
+def build_state_transition_event(
+	*,
+	context: Mapping[str, JsonValue],
+	status: str,
+	transition_key: str,
+	from_state: str,
+	to_state: str,
+	transition_axis: str | None = None,
+	entity_id: object | None = None,
+	duration_ms: int | None = None,
+	span_id: str | None = None,
+	parent_span_id: str | None = None,
+) -> dict[str, JsonValue]:
+	event_context = _internal_flow_context(
+		context=context,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+		expected_otel_span_kind="INTERNAL",
+	)
+	root_fields: dict[str, JsonValue] = {
+		"transition_key": transition_key,
+		"from_state": from_state,
+		"to_state": to_state,
+		"transition_axis": transition_axis,
+		"entity_id_masked": _masked_identifier(entity_id),
+	}
+	root_fields.update(_duration_root_field(status, duration_ms))
+	return _base_event(
+		context=event_context,
+		event_name=STATE_TRANSITION_EVENT_BY_STATUS[status],
+		event_category=EVENT_CATEGORY_STATE_TRANSITION,
+		status=status,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		root_fields=root_fields,
+		properties={
+			"service_name": event_context.get("service_name"),
+			"transition_key": transition_key,
+			"from_state": from_state,
+			"to_state": to_state,
+			"transition_axis": transition_axis,
+		},
+		metrics=_duration_root_field(status, duration_ms),
+	)
+
+
+def _sanitize_properties(
+	properties: Mapping[str, object] | None,
+	denied_keys: Sequence[str],
+) -> dict[str, JsonValue]:
+	if properties is None:
+		return {}
+	sanitized = safe_sanitize_object(properties, denied_keys)
+	if not isinstance(sanitized, dict):
+		return {}
+	result = dict(sanitized)
+	result.pop("custom_event_name", None)
+	result.pop("customEventName", None)
+	return result
+
+
+def _sanitize_metrics(metrics: Mapping[str, object] | None) -> dict[str, int | float]:
+	if metrics is None:
+		return {}
+	result: dict[str, int | float] = {}
+	for key, value in metrics.items():
+		if isinstance(value, bool):
+			continue
+		if isinstance(value, (int, float)) and math.isfinite(value):
+			result[str(key)] = value
+	return result
+
+
+def build_custom_event(
+	*,
+	context: Mapping[str, JsonValue],
+	event_name: str,
+	properties: Mapping[str, object] | None = None,
+	metrics: Mapping[str, object] | None = None,
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	custom_event_name = event_name.strip()
+	if not custom_event_name:
+		raise ValueError("event_name is required")
+
+	return _base_event(
+		context=context,
+		event_name=CUSTOM_EVENT_EMITTED,
+		custom_event_name=custom_event_name,
+		event_category=EVENT_CATEGORY_CUSTOM,
+		status=BACKEND_STATUS_OBSERVED,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		properties=_sanitize_properties(properties, denied_keys),
+		metrics=_sanitize_metrics(metrics),
+	)
+
+
+def _summary_event_category(event_name: str) -> str:
+	if event_name == REPOSITORY_MUTATION_SUMMARY_EVENT:
+		return EVENT_CATEGORY_REPOSITORY_MUTATION
+	if event_name == QUEUE_LIFECYCLE_SUMMARY_EVENT:
+		return EVENT_CATEGORY_JOB
+	if event_name == SDK_DIAGNOSTIC_EVENT:
+		return EVENT_CATEGORY_CUSTOM
+	return EVENT_CATEGORY_OUTBOUND_REQUEST
+
+
+def build_summary_event(
+	*,
+	context: Mapping[str, JsonValue],
+	event_name: str,
+	collector_name: str,
+	aggregation_kind: str,
+	summary_window_ms: int,
+	summary_count: int,
+	dropped_count: int = 0,
+	sample_rate: float = 1.0,
+	budget_window_ms: int | None = None,
+	rate_limit_key: str | None = None,
+	properties: Mapping[str, object] | None = None,
+	metrics: Mapping[str, object] | None = None,
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	if event_name not in {
+		REPOSITORY_MUTATION_SUMMARY_EVENT,
+		QUEUE_LIFECYCLE_SUMMARY_EVENT,
+		DEPENDENCY_SUMMARY_EVENT,
+		CACHE_OPERATION_SUMMARY_EVENT,
+		APPLICATION_LOG_SUMMARY_EVENT,
+		SDK_DIAGNOSTIC_EVENT,
+	}:
+		raise ValueError("event_name must be a backend summary event")
+
+	summary_metrics: dict[str, object] = {
+		"summary_count": max(0, int(summary_count)),
+		"dropped_count": max(0, int(dropped_count)),
+		"sample_rate": max(0.0, min(1.0, float(sample_rate))),
+	}
+	if metrics is not None:
+		summary_metrics.update(dict(metrics))
+
+	return _base_event(
+		context=context,
+		event_name=event_name,
+		event_category=_summary_event_category(event_name),
+		status=BACKEND_STATUS_OBSERVED,
+		surface_type=SURFACE_TYPE_SERVICE,
+		privacy_level="default_masked",
+		masking_state="masked",
+		allowed_value_keys=[],
+		root_fields={
+			"collector_name": collector_name,
+			"aggregation_kind": aggregation_kind,
+			"summary_window_ms": max(0, int(summary_window_ms)),
+			"summary_count": max(0, int(summary_count)),
+			"dropped_count": max(0, int(dropped_count)),
+			"sample_rate": max(0.0, min(1.0, float(sample_rate))),
+			"budget_window_ms": (
+				max(0, int(budget_window_ms))
+				if budget_window_ms is not None
+				else None
+			),
+			"rate_limit_key": _string_or_none(rate_limit_key),
+		},
+		properties=_sanitize_properties(properties, denied_keys),
+		metrics=_sanitize_metrics(summary_metrics),
+	)
+
+
+def build_sdk_diagnostic_event(
+	*,
+	context: Mapping[str, JsonValue],
+	metrics: Mapping[str, object],
+	capture_disabled_reason: str | None = None,
+	instrumentation_active: Mapping[str, object] | None = None,
+	last_flush_status: str | None = None,
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	properties: dict[str, object] = {}
+	if capture_disabled_reason is not None:
+		properties["capture_disabled_reason"] = capture_disabled_reason
+	if instrumentation_active is not None:
+		properties["instrumentation_active"] = dict(instrumentation_active)
+	if last_flush_status is not None:
+		properties["last_flush_status"] = last_flush_status
+
+	return build_summary_event(
+		context=context,
+		event_name=SDK_DIAGNOSTIC_EVENT,
+		collector_name="sdk_internal",
+		aggregation_kind="diagnostic",
+		summary_window_ms=0,
+		summary_count=1,
+		properties=properties,
+		metrics=metrics,
+		denied_keys=denied_keys,
+	)
+
+
+def build_identity_identified_event(
+	*,
+	context: Mapping[str, JsonValue],
+	user_id: str,
+	traits: Mapping[str, object] | None = None,
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	event_context = dict(context)
+	event_context["user_id"] = user_id
+	event_context["user_profile"] = build_subject_profile(traits)
+	return build_custom_event(
+		context=event_context,
+		event_name=CUSTOM_EVENT_IDENTITY_IDENTIFIED,
+		properties={
+			"backend_scope": "identity",
+			"identity_action": "identify",
+			"profile_keys": _visible_trait_keys(traits, denied_keys),
+		},
+		metrics={"count": 1},
+		denied_keys=denied_keys,
+	)
+
+
+def build_account_associated_event(
+	*,
+	context: Mapping[str, JsonValue],
+	account_id: str,
+	traits: Mapping[str, object] | None = None,
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	event_context = dict(context)
+	event_context["account_id"] = account_id
+	event_context["account_profile"] = build_subject_profile(traits)
+	workspace_id = _workspace_id_from_traits(traits)
+	if workspace_id is not None:
+		event_context["workspace_id"] = workspace_id
+	return build_custom_event(
+		context=event_context,
+		event_name=CUSTOM_EVENT_ACCOUNT_ASSOCIATED,
+		properties={
+			"backend_scope": "account",
+			"account_action": "associate",
+			"profile_keys": _visible_trait_keys(traits, denied_keys),
+		},
+		metrics={"count": 1},
+		denied_keys=denied_keys,
+	)
+
+
+def build_identity_logged_out_event(
+	*,
+	context: Mapping[str, JsonValue],
+	reason: str | None = None,
+	denied_keys: Sequence[str] = (),
+) -> dict[str, JsonValue]:
+	properties: dict[str, object] = {
+		"backend_scope": "identity",
+		"identity_action": "logout",
+	}
+	if reason is not None:
+		properties["reason"] = reason
+	return build_custom_event(
+		context=context,
+		event_name=CUSTOM_EVENT_IDENTITY_LOGGED_OUT,
+		properties=properties,
+		metrics={"count": 1},
+		denied_keys=denied_keys,
+	)
+
+
+def build_backend_envelope(
+	*,
+	project_key: str,
+	environment: str,
+	events: Sequence[Mapping[str, JsonValue]],
+	producer_id: str | None = None,
+	api_key: str | None = None,
+	batch_id: str | None = None,
+	idempotency_key: str | None = None,
+	sent_at: str | None = None,
+) -> dict[str, JsonValue]:
+	envelope: dict[str, JsonValue] = {
+		"project_key": project_key,
+		"environment": environment,
+		"producer_id": producer_id,
+		"sdk_type": BACKEND_SDK_TYPE,
+		"sdk_version": BACKEND_SDK_VERSION,
+		"schema_version": BACKEND_SDK_SCHEMA_VERSION,
+		"sent_at": sent_at or _now_iso(),
+		"events": [dict(event) for event in events],
+	}
+	if api_key is not None:
+		envelope["api_key"] = api_key
+	if batch_id is not None:
+		envelope["batch_id"] = batch_id
+	if idempotency_key is not None:
+		envelope["idempotency_key"] = idempotency_key
+	return envelope