openbox-sdk-python 0.2.0__py3-none-any.whl

openbox_core/serialization.py

@@ -0,0 +1,129 @@
+"""Byte/transform-only JSON serialization.
+
+This module knows NOTHING about events or spans — evaluate-body assembly
+(``span_count``, compat-noise removal) is owned by ``wire/evaluate_payload.py``.
+It owns exactly:
+
+- ``to_json_safe`` — dataclass/enum/datetime-tolerant JSON coercion
+- ``serialize_body`` — the EXACT bytes that are signed and transmitted
+- ``truncate_string`` / ``apply_redaction`` — pre-signing transforms
+- ``rfc3339_now`` — wall-clock helper (this module is NOT sandbox-pure)
+
+Wall-clock lives here (not in contracts) so pure modules stay deterministic.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+__all__ = [
+    "to_json_safe",
+    "serialize_body",
+    "truncate_string",
+    "apply_redaction",
+    "rfc3339_now",
+    "REDACTED_PLACEHOLDER",
+]
+
+REDACTED_PLACEHOLDER = "[REDACTED]"
+
+
+def rfc3339_now() -> str:
+    """Current UTC time, RFC3339 with millisecond precision and trailing ``Z``.
+
+    Event-payload timestamp format — distinct from the request-*signing*
+    timestamp which keeps ``+00:00`` (see ``identity.py``).
+    """
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def to_json_safe(obj: Any, exclude_none: bool = True) -> Any:
+    """Recursively coerce ``obj`` into JSON-serializable primitives.
+
+    Handles dataclasses (as dicts), Enums (``.value``), datetimes (RFC3339),
+    sets/tuples (lists), and dict keys via ``str()``. Unknown objects fall back
+    to ``str(obj)`` — governance telemetry must never crash the host app over
+    an exotic payload type.
+    """
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return obj
+    if isinstance(obj, Enum):
+        return to_json_safe(obj.value, exclude_none)
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return to_json_safe(dataclasses.asdict(obj), exclude_none)
+    if isinstance(obj, datetime):
+        if obj.tzinfo is None:
+            obj = obj.replace(tzinfo=UTC)
+        return obj.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+    if isinstance(obj, dict):
+        return {
+            str(k): to_json_safe(v, exclude_none)
+            for k, v in obj.items()
+            if not (exclude_none and v is None)
+        }
+    if isinstance(obj, (list, tuple, set, frozenset)):
+        return [to_json_safe(v, exclude_none) for v in obj]
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", errors="replace")
+    return str(obj)
+
+
+def serialize_body(payload: dict | None) -> bytes:
+    """Serialize a payload to the EXACT bytes that will be transmitted.
+
+    - ``None`` -> ``b""`` (body hash becomes the empty-body SHA-256).
+    - Compact separators (no spaces) and a single serialization pass so the
+      bytes we hash are identical to the bytes we send. Re-serializing with
+      ``json=`` elsewhere would break Core's body-hash verification.
+    """
+    if payload is None:
+        return b""
+    return json.dumps(payload, separators=(",", ":")).encode("utf-8")
+
+
+def truncate_string(value: str, max_size: int | None) -> tuple[str, bool]:
+    """Truncate ``value`` to ``max_size`` chars. Returns (value, truncated?).
+
+    ``None``/non-positive ``max_size`` disables truncation. Applied BEFORE
+    signing — the signed bytes are the truncated bytes.
+    """
+    if not max_size or max_size <= 0 or len(value) <= max_size:
+        return value, False
+    return value[:max_size], True
+
+
+def apply_redaction(
+    obj: Any,
+    redact_keys: frozenset[str] | set[str],
+    replacement: str = REDACTED_PLACEHOLDER,
+) -> tuple[Any, list[str]]:
+    """Replace values of case-insensitive key matches anywhere in ``obj``.
+
+    Returns ``(redacted_copy, changed_paths)`` — the paths identify what
+    changed so callers can attach diagnostics. Applied BEFORE signing.
+    """
+    if not redact_keys:
+        return obj, []
+    lowered = {k.lower() for k in redact_keys}
+    changed: list[str] = []
+
+    def _walk(node: Any, path: str) -> Any:
+        if isinstance(node, dict):
+            out = {}
+            for k, v in node.items():
+                child_path = f"{path}.{k}" if path else str(k)
+                if isinstance(k, str) and k.lower() in lowered:
+                    out[k] = replacement
+                    changed.append(child_path)
+                else:
+                    out[k] = _walk(v, child_path)
+            return out
+        if isinstance(node, (list, tuple)):
+            return [_walk(v, f"{path}[{i}]") for i, v in enumerate(node)]
+        return node
+
+    return _walk(obj, ""), changed

openbox_core/validation/__init__.py

@@ -0,0 +1,3 @@
+"""Strict-gate validation rules and diagnostics."""
+
+__all__: list[str] = []

openbox_core/validation/diagnostics.py

@@ -0,0 +1,60 @@
+"""Structured diagnostic records attached to evaluation results.
+
+Diagnostics are the NON-FAIL half of validation: they record best-effort
+degradations (missing semantic attributes, compat-noise removal, redaction)
+without rejecting anything. Strict failures raise ContractError instead —
+there is no diagnostic for a contract violation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+__all__ = [
+    "DiagnosticLevel",
+    "Diagnostic",
+    "SPAN_ATTR_MISSING",
+    "COMPAT_NOISE_REMOVED",
+    "ATTR_REDACTED",
+    "ATTR_TRUNCATED",
+    "HOOK_SKIPPED_NO_CONTEXT",
+]
+
+# Diagnostic codes (stable machine identifiers)
+SPAN_ATTR_MISSING = "SPAN_ATTR_MISSING"
+COMPAT_NOISE_REMOVED = "COMPAT_NOISE_REMOVED"
+ATTR_REDACTED = "ATTR_REDACTED"
+ATTR_TRUNCATED = "ATTR_TRUNCATED"
+HOOK_SKIPPED_NO_CONTEXT = "HOOK_SKIPPED_NO_CONTEXT"
+
+
+class DiagnosticLevel(str, Enum):
+    INFO = "INFO"
+    WARNING = "WARNING"
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One structured diagnostic record.
+
+    Attributes:
+        level: Severity (INFO/WARNING) — never an error (errors raise).
+        code: Stable machine code (e.g. ``SPAN_ATTR_MISSING``).
+        message: Human-readable summary.
+        detail: Structured context (what changed, which key, which span).
+    """
+
+    level: DiagnosticLevel
+    code: str
+    message: str
+    detail: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "level": self.level.value,
+            "code": self.code,
+            "message": self.message,
+            "detail": dict(self.detail),
+        }

openbox_core/validation/event_rules.py

@@ -0,0 +1,164 @@
+"""Strict contract failures — raise ContractError BEFORE any network send.
+
+The gate is ALWAYS strict for OpenBox event contracts and runtime invariants;
+there is no OBSERVE/SANITIZE/STRICT mode and no way to downgrade these to
+diagnostics. Fail-open applies only to network errors, never here.
+
+Strict failure list:
+- malformed lifecycle event envelope
+- hook event has ``hook_trigger=false`` (span-bearing but not marked hook)
+- hook event uses the wrong wire event type
+- ``preflight()`` receives completed-stage spans
+- ``completed()`` receives started-stage spans
+- ``ActivityCompleted`` contains non-empty hook span payloads
+- instrumentation produced an impossible/malformed hook event
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..contracts.events import EventEnvelope, EventKind, EventType, classify_event
+from ..errors import ContractError
+
+__all__ = [
+    "span_stage",
+    "check_lifecycle_envelope",
+    "check_hook_envelope",
+    "check_stage",
+]
+
+# Payload fields every workflow-scoped lifecycle event must carry.
+_REQUIRED_WORKFLOW_FIELDS = ("workflow_id", "run_id", "workflow_type")
+_REQUIRED_HANDOFF_FIELDS = ("from_agent_did", "multi_agent_session_id")
+
+
+def span_stage(span: Any) -> str | None:
+    """Extract the stage from a span payload.
+
+    Spans are flat-only: the stage lives at the top level. Enum values normalize
+    via ``.value``.
+    """
+    if isinstance(span, dict):
+        stage: Any = span.get("stage")
+    else:
+        stage = getattr(span, "stage", None)
+    value = getattr(stage, "value", stage)
+    return value if isinstance(value, str) else None
+
+
+def _require_fields(event: EventEnvelope, fields: tuple[str, ...], what: str) -> None:
+    missing = [f for f in fields if not event.payload.get(f)]
+    if missing:
+        raise ContractError(
+            f"Malformed {what} envelope: missing required fields {missing}",
+            code="ENVELOPE_MISSING_FIELDS",
+            detail={"missing": missing, "event_type": event.event_type.value},
+        )
+
+
+def check_lifecycle_envelope(event: EventEnvelope) -> None:
+    """Strict checks for non-hook envelopes (lifecycle/signal/handoff)."""
+    if not isinstance(event.event_type, EventType):
+        raise ContractError(
+            f"Malformed envelope: event_type must be an EventType, got {type(event.event_type).__name__}",
+            code="ENVELOPE_BAD_EVENT_TYPE",
+        )
+
+    kind = classify_event(event)
+    if kind is EventKind.HOOK:
+        raise ContractError(
+            "check_lifecycle_envelope received a hook event — route hook events "
+            "through preflight()/completed()",
+            code="HOOK_ON_LIFECYCLE_PATH",
+        )
+
+    # A span-bearing envelope that is not marked as a hook is malformed:
+    # either it IS a hook (then hook_trigger must be true) or spans are noise.
+    if event.spans:
+        if event.event_type is EventType.ACTIVITY_COMPLETED:
+            raise ContractError(
+                "ActivityCompleted must not carry non-empty hook spans — completed "
+                "telemetry routes through completed() with completed-stage spans",
+                code="ACTIVITY_COMPLETED_WITH_SPANS",
+                detail={"span_count": len(event.spans)},
+            )
+        raise ContractError(
+            f"{event.event_type.value} carries spans but hook_trigger=false — "
+            "span-bearing evaluations must be hook events",
+            code="HOOK_TRIGGER_FALSE",
+            detail={"span_count": len(event.spans)},
+        )
+
+    if kind is EventKind.HANDOFF:
+        _require_fields(event, _REQUIRED_HANDOFF_FIELDS, "handoff")
+        return
+    _require_fields(event, _REQUIRED_WORKFLOW_FIELDS, "lifecycle")
+    if kind is EventKind.SIGNAL and not event.payload.get("signal_name"):
+        raise ContractError(
+            "Malformed signal envelope: missing signal_name",
+            code="ENVELOPE_MISSING_FIELDS",
+            detail={"missing": ["signal_name"]},
+        )
+
+
+def check_hook_envelope(event: EventEnvelope) -> None:
+    """Strict checks for hook (span-bearing) envelopes."""
+    if not event.hook_trigger:
+        raise ContractError(
+            "Hook evaluation requires hook_trigger=true",
+            code="HOOK_TRIGGER_FALSE",
+        )
+    if event.event_type is not EventType.ACTIVITY_STARTED:
+        raise ContractError(
+            f"Hook events must use wire event type ActivityStarted, got "
+            f"{event.event_type.value}",
+            code="HOOK_WRONG_WIRE_TYPE",
+            detail={"event_type": event.event_type.value},
+        )
+    if not event.spans:
+        raise ContractError(
+            "Hook event carries no spans — instrumentation produced an impossible "
+            "hook event",
+            code="HOOK_EMPTY_SPANS",
+        )
+    if not event.activity_id or not event.activity_type:
+        raise ContractError(
+            "Hook event is not attached to a bound activity (activity_id and "
+            "activity_type are required)",
+            code="HOOK_UNBOUND_ACTIVITY",
+            detail={
+                "activity_id": event.activity_id,
+                "activity_type": event.activity_type,
+            },
+        )
+    for index, span in enumerate(event.spans):
+        if isinstance(span, dict):
+            forbidden = sorted({"otel", "openbox", "data"} & set(span))
+            if forbidden:
+                raise ContractError(
+                    "Hook spans must be flat Core SpanData dicts — nested/debug "
+                    f"keys are not allowed at spans[{index}]: {forbidden}",
+                    code="HOOK_SPAN_NOT_FLAT",
+                    detail={"index": index, "forbidden": forbidden},
+                )
+
+
+def check_stage(event: EventEnvelope, expected_stage: str) -> None:
+    """Reject stage-mismatched spans (preflight=started, completed=completed)."""
+    for index, span in enumerate(event.spans):
+        stage = span_stage(span)
+        if stage is None:
+            raise ContractError(
+                f"Hook span[{index}] has no stage — instrumentation produced a "
+                "malformed hook span",
+                code="HOOK_SPAN_NO_STAGE",
+                detail={"index": index},
+            )
+        if stage != expected_stage:
+            raise ContractError(
+                f"{expected_stage}-stage evaluation received a {stage}-stage span "
+                f"at spans[{index}]",
+                code="HOOK_STAGE_MISMATCH",
+                detail={"index": index, "expected": expected_stage, "actual": stage},
+            )

openbox_core/validation/registry.py

@@ -0,0 +1,31 @@
+"""Validation dispatch — route an envelope to its rule set, aggregate diagnostics.
+
+Strict failures raise ContractError (before any send); the return value is the
+list of non-fail diagnostics collected along the way.
+"""
+
+from __future__ import annotations
+
+from ..contracts.events import EventEnvelope
+from .diagnostics import Diagnostic
+from .event_rules import check_hook_envelope, check_lifecycle_envelope, check_stage
+
+__all__ = ["validate_lifecycle", "validate_hook"]
+
+
+def validate_lifecycle(event: EventEnvelope) -> list[Diagnostic]:
+    """Validate a lifecycle/signal/handoff envelope. Raises ContractError on
+    violation; returns diagnostics (none today — reserved for future rules)."""
+    check_lifecycle_envelope(event)
+    return []
+
+
+def validate_hook(event: EventEnvelope, expected_stage: str) -> list[Diagnostic]:
+    """Validate a hook envelope for the given stage ("started"/"completed").
+
+    ``check_hook_envelope``'s first rule rejects ``hook_trigger=false``, which
+    also covers non-HOOK envelopes routed here by mistake.
+    """
+    check_hook_envelope(event)
+    check_stage(event, expected_stage)
+    return []

openbox_core/validation/span_normalization.py

@@ -0,0 +1,107 @@
+"""Non-fail span diagnostics — best-effort degradations that never reject.
+
+Missing semantic attributes, compatibility noise, and privacy transforms are
+DIAGNOSTICS, not failures. Only malformed envelopes/stages/bindings are strict
+(see event_rules.py). Semantic gaps never reject or drop a span.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .diagnostics import (
+    ATTR_REDACTED,
+    ATTR_TRUNCATED,
+    COMPAT_NOISE_REMOVED,
+    SPAN_ATTR_MISSING,
+    Diagnostic,
+    DiagnosticLevel,
+)
+
+__all__ = [
+    "strip_compat_noise",
+    "semantic_gap_diagnostics",
+    "redaction_diagnostics",
+    "truncation_diagnostic",
+    "SEMANTIC_FIELDS_BY_HOOK_TYPE",
+]
+
+# Best-effort semantic fields per hook type — absence is an INFO diagnostic.
+SEMANTIC_FIELDS_BY_HOOK_TYPE: dict[str, tuple[str, ...]] = {
+    "http_request": ("http_method", "http_url"),
+    "db_query": ("db_system", "db_statement"),
+    "file_operation": ("file_path", "file_operation"),
+    "function_call": ("function", "module"),
+}
+
+
+def strip_compat_noise(payload: dict[str, Any]) -> tuple[dict[str, Any], list[Diagnostic]]:
+    """Remove ``spans=[]``/``span_count=0`` from a lifecycle wire payload.
+
+    Core ignores these empty fields, but they are contract noise. Removal is
+    recorded as a diagnostic — it is NOT a configurable mode. Non-empty spans
+    are not touched here (they are a strict failure upstream).
+    """
+    diagnostics: list[Diagnostic] = []
+    removed: list[str] = []
+    cleaned = dict(payload)
+    if "spans" in cleaned and cleaned["spans"] == []:
+        del cleaned["spans"]
+        removed.append("spans")
+    if "span_count" in cleaned and cleaned["span_count"] == 0:
+        del cleaned["span_count"]
+        removed.append("span_count")
+    if removed:
+        diagnostics.append(
+            Diagnostic(
+                level=DiagnosticLevel.INFO,
+                code=COMPAT_NOISE_REMOVED,
+                message=f"Removed compatibility noise before send: {removed}",
+                detail={"removed": removed},
+            )
+        )
+    return cleaned, diagnostics
+
+
+def semantic_gap_diagnostics(
+    span_wire: dict[str, Any], hook_type: str | None
+) -> list[Diagnostic]:
+    """INFO diagnostics for missing best-effort semantic fields.
+
+    The span is still sent — semantic gaps NEVER reject a span.
+    """
+    fields = SEMANTIC_FIELDS_BY_HOOK_TYPE.get(hook_type or "", ())
+    return [
+        Diagnostic(
+            level=DiagnosticLevel.INFO,
+            code=SPAN_ATTR_MISSING,
+            message=f"Best-effort semantic attribute missing: {field_name}",
+            detail={"hook_type": hook_type, "field": field_name},
+        )
+        for field_name in fields
+        if span_wire.get(field_name) is None
+    ]
+
+
+def redaction_diagnostics(changed_paths: list[str]) -> list[Diagnostic]:
+    """Diagnostics identifying exactly what redaction changed."""
+    if not changed_paths:
+        return []
+    return [
+        Diagnostic(
+            level=DiagnosticLevel.INFO,
+            code=ATTR_REDACTED,
+            message=f"Redacted {len(changed_paths)} value(s) before send",
+            detail={"paths": list(changed_paths)},
+        )
+    ]
+
+
+def truncation_diagnostic(field_name: str, original_size: int, max_size: int) -> Diagnostic:
+    """Diagnostic identifying a truncated value."""
+    return Diagnostic(
+        level=DiagnosticLevel.INFO,
+        code=ATTR_TRUNCATED,
+        message=f"Truncated {field_name} from {original_size} to {max_size} chars",
+        detail={"field": field_name, "original_size": original_size, "max_size": max_size},
+    )

openbox_core/wire/__init__.py

@@ -0,0 +1,3 @@
+"""Wire-format serializers targeting the current OpenBox Core API contracts."""
+
+__all__: list[str] = []

openbox_core/wire/core_span.py

@@ -0,0 +1,130 @@
+"""to_core_span_data — normalize flat Core ``SpanData`` wire spans.
+
+Wire rules:
+
+- Ids are HEX STRINGS: span_id 16, trace_id 32, parent_span_id 16 chars.
+  Raw integer OTel ids must never be sent.
+- Timestamps are epoch NANOSECONDS.
+- started-stage spans emit EXPLICIT ``end_time: null`` and
+  ``duration_ns: null`` (never omitted, never ``end_time == start_time``);
+  Core's non-pointer ``EndTime int64`` unmarshals null -> 0.
+- The COMMON root fields (span_id, trace_id, parent_span_id, name, kind,
+  stage, start_time, end_time, duration_ns, attributes, status, events,
+  hook_type, error) are ALWAYS present — null-valued when absent, never
+  omitted — matching the flat hook contract.
+- Each hook family's own root fields (http_*/db_*/file_*/function) are ALSO
+  always present for that family (null when the wrapper/attributes did not
+  supply them). ``attributes`` carries OTel-native attributes ONLY.
+- Semantic HTTP/DB/file/function fields are best-effort from OTel attributes
+  during ``contracts.otel_spans.from_otel_span``; absence is a diagnostic,
+  NEVER a rejection.
+- ``semantic_type`` is NEVER set here — Core computes it.
+- Hook spans are FLAT in memory and on the wire: no ``data`` blob and no nested
+  ``{"otel", "openbox"}`` envelope.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..config import PrivacyConfig
+from ..contracts.otel_spans import _ROOT_FIELDS_BY_HOOK_TYPE
+from ..serialization import apply_redaction, truncate_string
+from ..validation.diagnostics import Diagnostic
+from ..validation.span_normalization import (
+    redaction_diagnostics,
+    semantic_gap_diagnostics,
+    truncation_diagnostic,
+)
+
+__all__ = ["to_core_span_data"]
+
+# Wrapper-supplied fields eligible for body truncation.
+_TRUNCATABLE_FIELDS = ("request_body", "response_body")
+
+_COMMON_DEFAULTS: dict[str, Any] = {
+    "span_id": "0" * 16,
+    "trace_id": "0" * 32,
+    "parent_span_id": None,
+    "name": "span",
+    "kind": "INTERNAL",
+    "start_time": None,
+    "end_time": None,
+    "duration_ns": None,
+    "attributes": {},
+    "status": {"code": "UNSET", "description": None},
+    "events": [],
+    "error": None,
+}
+
+
+def to_core_span_data(
+    span: dict[str, Any],
+    *,
+    privacy: PrivacyConfig | None = None,
+    include_otel_data: bool = False,
+) -> tuple[dict[str, Any], list[Diagnostic]]:
+    """Normalize one flat Core ``SpanData`` dict.
+
+    Returns ``(wire_span, diagnostics)``. Missing semantic attributes are
+    diagnostics, never failures; redaction/truncation is recorded.
+
+    ``include_otel_data`` is retained as a compatibility parameter but is now a
+    no-op: spans stay flat everywhere.
+    """
+    _ = include_otel_data
+    diagnostics: list[Diagnostic] = []
+    wire = dict(span)
+    # Never let nested/debug shapes leak forward.
+    wire.pop("otel", None)
+    wire.pop("openbox", None)
+    wire.pop("data", None)
+    wire.pop("metadata", None)
+
+    hook_type = wire.get("hook_type")
+    attributes = dict(wire.get("attributes") or {})
+    if privacy and privacy.redact_keys:
+        attributes, changed = apply_redaction(attributes, privacy.redact_keys)
+        diagnostics.extend(redaction_diagnostics([f"attributes.{p}" for p in changed]))
+    wire["attributes"] = attributes
+
+    for field_name in _TRUNCATABLE_FIELDS:
+        if field_name not in wire:
+            continue
+        value = wire.get(field_name)
+        if privacy and field_name in _TRUNCATABLE_FIELDS and isinstance(value, str):
+            truncated, was_truncated = truncate_string(value, privacy.max_body_size)
+            if was_truncated:
+                diagnostics.append(
+                    truncation_diagnostic(field_name, len(value), privacy.max_body_size)
+                )
+            value = truncated
+        wire[field_name] = value
+
+    for field_name, value in _COMMON_DEFAULTS.items():
+        if field_name in wire:
+            continue
+        if isinstance(value, dict):
+            wire[field_name] = dict(value)
+        elif isinstance(value, list):
+            wire[field_name] = list(value)
+        else:
+            wire[field_name] = value
+
+    # Guarantee every family-specific root key exists (explicit null if neither
+    # attributes nor the wrapper supplied it); the flat hook contract emits the
+    # full family key set, and Core's ``omitempty`` tolerates the nulls.
+    for field_name in _ROOT_FIELDS_BY_HOOK_TYPE.get(hook_type or "", ()):
+        wire.setdefault(field_name, None)
+
+    # OTel-owned HTTP spans are not always ended when the response hook fires,
+    # so ``end_time`` may be null even though a duration was measured.
+    # Reconstruct it from start_time + duration for completed spans.
+    if wire.get("stage") != "started" and wire.get("end_time") is None:
+        start_time = wire.get("start_time")
+        measured = wire.get("duration_ns")
+        if isinstance(start_time, int) and isinstance(measured, int):
+            wire["end_time"] = start_time + measured
+
+    diagnostics.extend(semantic_gap_diagnostics(wire, hook_type))
+    return wire, diagnostics

openbox_core/wire/evaluate_payload.py

@@ -0,0 +1,56 @@
+"""build_evaluate_payload — the SINGLE owner of the evaluate request body.
+
+Assembles the exact ``/api/v1/governance/evaluate`` body for hook events:
+the ``EventEnvelope`` fields at the top level (``event_type=ActivityStarted``,
+``hook_trigger=true``, ``activity_id``/``activity_type``, ``timestamp``),
+``spans`` as a list of flat Core ``SpanData`` dicts, and ``span_count``.
+
+The strict gate injects this as its ``payload_builder`` — the gate never
+reimplements body assembly, and ``serialization.serialize_body`` (byte-only)
+then produces the signed bytes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..config import PrivacyConfig
+from ..contracts.events import EventEnvelope
+from ..validation.diagnostics import Diagnostic
+from .core_span import to_core_span_data
+
+__all__ = ["build_evaluate_payload", "make_payload_builder"]
+
+
+def build_evaluate_payload(
+    event: EventEnvelope,
+    *,
+    privacy: PrivacyConfig | None = None,
+) -> tuple[dict[str, Any], list[Diagnostic]]:
+    """Assemble the hook evaluate body from a validated hook envelope.
+
+    Spans are flat Core ``SpanData`` dicts in memory. The normalizer enforces
+    the final no-nested/no-data wire shape and applies privacy transforms.
+    """
+    diagnostics: list[Diagnostic] = []
+    wire_spans: list[dict[str, Any]] = []
+    for span in event.spans:
+        wire_span, span_diagnostics = to_core_span_data(
+            dict(span), privacy=privacy, include_otel_data=False
+        )
+        diagnostics.extend(span_diagnostics)
+        wire_spans.append(wire_span)
+
+    payload = event.to_payload_dict()
+    payload["spans"] = wire_spans
+    payload["span_count"] = len(wire_spans)
+    return payload, diagnostics
+
+
+def make_payload_builder(privacy: PrivacyConfig | None = None):
+    """Bind a privacy config into the gate's single-argument builder seam."""
+
+    def _builder(event: EventEnvelope) -> tuple[dict[str, Any], list[Diagnostic]]:
+        return build_evaluate_payload(event, privacy=privacy)
+
+    return _builder