cmpnd 0.32.0__tar.gz → 0.33.0__tar.gz

{cmpnd-0.32.0 → cmpnd-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.32.0
+Version: 0.33.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.32.0 → cmpnd-0.33.0}/cmpnd/callback.py

@@ -708,16 +708,16 @@ class _ModuleMixin(_CallbackBase):
             if span_type == models.SpanType.RLM:
                 trace.streaming = True
             self._streaming_traces[str(trace.trace_id)] = trace.streaming
+            trace.seal_start()
 
             # Emit an in_progress start row for EVERY root trace, not
             # just streaming/RLM ones, so a non-RLM program is visible the moment
             # it starts (`traces list --status in_progress`, a lookupable id)
             # instead of only appearing at finalize. `trace.streaming` still
             # governs per-span vs batch export below — only the start emission is
-            # generalized. The batch finalize upserts this same row (serve
-            # traceUpsertSQL, ON CONFLICT org_id,trace_id,start_time), and the
-            # exporter coalesces a start with its batch trace in one flush, so a
-            # fast trace pays a single insert, not two.
+            # generalized. The start and full body identify the same logical
+            # trace, with independent completion and annotation reports. The
+            # exporter coalesces them when the full body preserves every fact.
             if self._stream_trace_starts:
                 exp = self._current_exporter()
                 if exp:
@@ -953,6 +953,7 @@ class _ModuleMixin(_CallbackBase):
                             f"Trace collected for eval: tokens={trace.total_tokens}, cost={trace.total_cost:.4f}"
                         )
 
+                trace.seal_completion()
                 exp = self._current_exporter()
                 if exp:
                     if trace.streaming:
@@ -1542,6 +1543,9 @@ class _LMMixin(_CallbackBase):
         trace.total_tokens = span.total_tokens or 0
         trace.total_cost = span.cost or 0.0
         trace.span_count = 1
+        trace.root_span_type = span.span_type.value
+        trace.seal_start()
+        trace.seal_completion()
 
         exp = self._current_exporter()
         if exp:

{cmpnd-0.32.0 → cmpnd-0.33.0}/cmpnd/cli/commands/traces.py

@@ -8,6 +8,8 @@ import time
 from argparse import ArgumentParser, ArgumentTypeError, _SubParsersAction
 from typing import Any
 
+from cmpnd_ingest.trace_facts import MetadataFact, StringMapChange
+
 from ... import _timespec
 from .. import api_client, deprecation, pagination, trace_render
 
@@ -288,7 +290,11 @@ def handle_update(client: api_client.ApiClient, args: Any) -> Any:
     it exists for: stamping a correlation id that only became known after the
     run, without disturbing whatever the program recorded at the time.
     """
-    return client.patch(f"/api/v1/traces/{args.id}/metadata", json={"metadata": dict(args.metadata)})
+    metadata = dict(args.metadata)
+    fact = MetadataFact(metadata=StringMapChange(set_items=tuple(sorted(metadata.items()))))
+    return client.patch(
+        f"/api/v1/traces/{args.id}/metadata", json={"metadata": metadata, "metadata_fact": fact.to_dict()}
+    )
 
 
 def handle_delete(client: api_client.ApiClient, args: Any) -> Any:

{cmpnd-0.32.0 → cmpnd-0.33.0}/cmpnd/models.py

@@ -11,6 +11,8 @@ from enum import Enum
 from typing import Any
 from uuid import UUID, uuid4
 
+from cmpnd_ingest.trace_facts import CompletionFact, MetadataFact, StartedFact, StringMapChange
+
 from . import identity, imaging
 
 # U+0000 (NUL) and lone UTF-16 surrogates are valid JSON, and valid in a Python
@@ -910,93 +912,161 @@ class TraceBuilder:
     # Snapshot project_tags at construction time to avoid reconfigure races in async export
     project_tags: list[str] | None = field(default_factory=configuration._current_project_tags)
 
+    _started_fact: StartedFact | None = field(default=None, init=False, repr=False)
+    _completion_fact: CompletionFact | None = field(default=None, init=False, repr=False)
+    _metadata_facts: list[MetadataFact] = field(default_factory=list, init=False, repr=False)
+    _sealed_tags: dict[str, str] = field(default_factory=dict, init=False, repr=False)
+    _sealed_metadata: dict[str, str] = field(default_factory=dict, init=False, repr=False)
+    _sealed_project_tags: tuple[str, ...] = field(default=(), init=False, repr=False)
+
+    def seal_start(self) -> None:
+        """Retain the first creation snapshot and its independent annotations."""
+        if self._started_fact is None:
+            self._started_fact = StartedFact.from_payload(self.to_start_dict())
+            self.seal_metadata()
+
+    def seal_metadata(self) -> None:
+        """Seal changes since the previous annotation report, including removals."""
+        tags: dict[str, str] = _safe_serialize(self.tags)
+        metadata: dict[str, str] = _safe_serialize(self.metadata)
+        projects = tuple(self.project_tags or ())
+        tag_change = StringMapChange.between(self._sealed_tags, tags)
+        metadata_change = StringMapChange.between(self._sealed_metadata, metadata)
+        project_change = projects if projects != self._sealed_project_tags else None
+        if tag_change is not None or metadata_change is not None or project_change is not None:
+            self._metadata_facts.append(MetadataFact(tag_change, metadata_change, project_change))
+        self._sealed_tags, self._sealed_metadata, self._sealed_project_tags = tags, metadata, projects
+
+    def seal_completion(self) -> None:
+        """Seal one new completion report; serialization reuses it unchanged."""
+        if self.end_time is None:
+            raise ValueError("a completion report requires end_time")
+        self.seal_start()
+        assert self._started_fact is not None
+        start = datetime.fromisoformat(self._started_fact.start_time) if self._started_fact.start_time else None
+        duration = self.end_time - start if start else None
+        duration_ns = (
+            (duration.days * 86400 + duration.seconds) * 1_000_000_000 + duration.microseconds * 1000
+            if duration is not None
+            else 0
+        )
+        self._completion_fact = CompletionFact(
+            producer_sequence=self._completion_fact.producer_sequence + 1 if self._completion_fact else 1,
+            end_time=self.end_time.isoformat(),
+            status=self.status.value,
+            error_message=_strip_unstorable(self.error_message or ""),
+            duration_ns=duration_ns,
+        )
+        self.seal_metadata()
+
+    def _with_facts(self, payload: dict[str, Any], *, completion: bool = False, started: bool = True) -> dict[str, Any]:
+        if self._started_fact is not None:
+            creation = self._started_fact.creation_dict()
+            payload.update(creation if started else {key: value for key, value in creation.items() if key in payload})
+            if started:
+                payload["started_fact"] = self._started_fact.to_dict()
+        if completion and self._completion_fact is not None:
+            payload["completion_fact"] = self._completion_fact.to_dict()
+        if self._started_fact is not None or self._completion_fact is not None or self._metadata_facts:
+            payload["metadata_facts"] = [fact.to_dict() for fact in self._metadata_facts]
+        return payload
+
     def to_api_dict(self) -> dict[str, Any]:
         """Convert to API-compatible dictionary."""
-        return {
-            "trace_id": str(self.trace_id),
-            "start_time": self.start_time.isoformat() if self.start_time else None,
-            "end_time": self.end_time.isoformat() if self.end_time else None,
-            "status": self.status.value,
-            "error_message": _strip_unstorable_opt(self.error_message),
-            "program_name": self.program_name,
-            "program_version": self.program_version,
-            "signature_name": self.signature_name,
-            "signature_input_fields": self.signature_input_fields,
-            "signature_output_fields": self.signature_output_fields,
-            "signature_input_field_types": self.signature_input_field_types,
-            "signature_output_field_types": self.signature_output_field_types,
-            "signature_input_field_schemas": self.signature_input_field_schemas,
-            "signature_output_field_schemas": self.signature_output_field_schemas,
-            "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
-            "signature_summary": self.signature_summary,
-            # The server forwards this blob verbatim into a jsonb column, and its
-            # program registration is best-effort (a rejection is only logged), so
-            # an un-storable code point here would silently lose the whole
-            # component list. Scrub at the source — the only place that can.
-            "component_signatures": _safe_serialize(self.component_signatures),
-            "compiled_from_run_id": self.compiled_from_run_id,
-            "demo_ids": self.demo_ids,
-            "request_preview": (self.request_preview or "")[:500],
-            "response_preview": (self.response_preview or "")[:500],
-            "eval_run_id": str(self.eval_run_id) if self.eval_run_id else None,
-            "optimization_run_id": (str(self.optimization_run_id) if self.optimization_run_id else None),
-            "adapter_type": self.adapter_type,
-            "tags": _safe_serialize(self.tags),
-            "metadata": _safe_serialize(self.metadata),
-            "project": self.project_tags[0] if self.project_tags else None,
-            "project_tags": self.project_tags if self.project_tags else [],
-            "spans": [s.to_api_dict() for s in self._batch_spans] if self._batch_spans else [],
-        }
+        return self._with_facts(
+            {
+                "trace_id": str(self.trace_id),
+                "start_time": self.start_time.isoformat() if self.start_time else None,
+                "end_time": self.end_time.isoformat() if self.end_time else None,
+                "status": self.status.value,
+                "error_message": _strip_unstorable_opt(self.error_message),
+                "program_name": self.program_name,
+                "program_version": self.program_version,
+                "signature_name": self.signature_name,
+                "signature_input_fields": self.signature_input_fields,
+                "signature_output_fields": self.signature_output_fields,
+                "signature_input_field_types": self.signature_input_field_types,
+                "signature_output_field_types": self.signature_output_field_types,
+                "signature_input_field_schemas": self.signature_input_field_schemas,
+                "signature_output_field_schemas": self.signature_output_field_schemas,
+                "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
+                "signature_summary": self.signature_summary,
+                # The server forwards this blob verbatim into a jsonb column, and its
+                # program registration is best-effort (a rejection is only logged), so
+                # an un-storable code point here would silently lose the whole
+                # component list. Scrub at the source — the only place that can.
+                "component_signatures": _safe_serialize(self.component_signatures),
+                "compiled_from_run_id": self.compiled_from_run_id,
+                "demo_ids": self.demo_ids,
+                "request_preview": (self.request_preview or "")[:500],
+                "response_preview": (self.response_preview or "")[:500],
+                "eval_run_id": str(self.eval_run_id) if self.eval_run_id else None,
+                "optimization_run_id": (str(self.optimization_run_id) if self.optimization_run_id else None),
+                "adapter_type": self.adapter_type,
+                "tags": _safe_serialize(self.tags),
+                "metadata": _safe_serialize(self.metadata),
+                "project": self.project_tags[0] if self.project_tags else None,
+                "project_tags": self.project_tags if self.project_tags else [],
+                "spans": [s.to_api_dict() for s in self._batch_spans] if self._batch_spans else [],
+            },
+            completion=True,
+        )
 
     def to_start_dict(self) -> dict[str, Any]:
         """Lightweight payload for trace identity, signature and run attribution."""
-        return {
-            "start_time": self.start_time.isoformat() if self.start_time else None,
-            "program_name": self.program_name,
-            "program_version": self.program_version,
-            "signature_name": self.signature_name,
-            "signature_input_fields": self.signature_input_fields,
-            "signature_output_fields": self.signature_output_fields,
-            "signature_input_field_types": self.signature_input_field_types,
-            "signature_output_field_types": self.signature_output_field_types,
-            "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
-            "signature_summary": self.signature_summary,
-            "component_signatures": _safe_serialize(self.component_signatures),
-            "root_span_type": self.root_span_type,
-            "compiled_from_run_id": self.compiled_from_run_id,
-            "project": self.project_tags[0] if self.project_tags else None,
-            "project_tags": self.project_tags if self.project_tags else [],
-            # Known at start (the callback attaches them in _create_trace), so
-            # the start row carries them from the first send instead of the
-            # finalize row re-attributing them later.
-            "eval_run_id": str(self.eval_run_id) if self.eval_run_id else None,
-            "optimization_run_id": (str(self.optimization_run_id) if self.optimization_run_id else None),
-        }
+        return self._with_facts(
+            {
+                "start_time": self.start_time.isoformat() if self.start_time else None,
+                "program_name": self.program_name,
+                "program_version": self.program_version,
+                "signature_name": self.signature_name,
+                "signature_input_fields": self.signature_input_fields,
+                "signature_output_fields": self.signature_output_fields,
+                "signature_input_field_types": self.signature_input_field_types,
+                "signature_output_field_types": self.signature_output_field_types,
+                "program_signature_hash": identity.format_signature_hash(self.program_signature_hash),
+                "signature_summary": self.signature_summary,
+                "component_signatures": _safe_serialize(self.component_signatures),
+                "root_span_type": self.root_span_type,
+                "compiled_from_run_id": self.compiled_from_run_id,
+                "project": self.project_tags[0] if self.project_tags else None,
+                "project_tags": self.project_tags if self.project_tags else [],
+                # Known at start (the callback attaches them in _create_trace), so
+                # the start row carries them from the first send instead of the
+                # finalize row re-attributing them later.
+                "eval_run_id": str(self.eval_run_id) if self.eval_run_id else None,
+                "optimization_run_id": (str(self.optimization_run_id) if self.optimization_run_id else None),
+            }
+        )
 
     def to_finalize_dict(self) -> dict[str, Any]:
         """Payload for trace finalization — timing, metrics, previews."""
-        return {
-            "start_time": self.start_time.isoformat() if self.start_time else None,
-            "end_time": self.end_time.isoformat() if self.end_time else None,
-            "status": self.status.value,
-            "error_message": _strip_unstorable_opt(self.error_message),
-            "request_preview": (self.request_preview or "")[:500],
-            "response_preview": (self.response_preview or "")[:500],
-            "total_tokens": self.total_tokens,
-            "prompt_tokens": self.prompt_tokens,
-            "completion_tokens": self.completion_tokens,
-            "total_cost": self.total_cost,
-            "span_count": self.span_count,
-            "adapter_type": self.adapter_type,
-            "compiled_from_run_id": self.compiled_from_run_id,
-            "demo_ids": self.demo_ids,
-            "eval_run_id": str(self.eval_run_id) if self.eval_run_id else None,
-            "optimization_run_id": (str(self.optimization_run_id) if self.optimization_run_id else None),
-            "tags": _safe_serialize(self.tags),
-            "metadata": _safe_serialize(self.metadata),
-            "project": self.project_tags[0] if self.project_tags else None,
-            "project_tags": self.project_tags if self.project_tags else [],
-        }
+        return self._with_facts(
+            {
+                "start_time": self.start_time.isoformat() if self.start_time else None,
+                "end_time": self.end_time.isoformat() if self.end_time else None,
+                "status": self.status.value,
+                "error_message": _strip_unstorable_opt(self.error_message),
+                "request_preview": (self.request_preview or "")[:500],
+                "response_preview": (self.response_preview or "")[:500],
+                "total_tokens": self.total_tokens,
+                "prompt_tokens": self.prompt_tokens,
+                "completion_tokens": self.completion_tokens,
+                "total_cost": self.total_cost,
+                "span_count": self.span_count,
+                "adapter_type": self.adapter_type,
+                "compiled_from_run_id": self.compiled_from_run_id,
+                "demo_ids": self.demo_ids,
+                "eval_run_id": str(self.eval_run_id) if self.eval_run_id else None,
+                "optimization_run_id": (str(self.optimization_run_id) if self.optimization_run_id else None),
+                "tags": _safe_serialize(self.tags),
+                "metadata": _safe_serialize(self.metadata),
+                "project": self.project_tags[0] if self.project_tags else None,
+                "project_tags": self.project_tags if self.project_tags else [],
+            },
+            completion=True,
+            started=False,
+        )
 
 
 class EvalRunStatus(str, Enum):

{cmpnd-0.32.0 → cmpnd-0.33.0}/docs/sdk-instrumentation.md

@@ -583,10 +583,26 @@ Its first payload carries the optimization id, plus the active eval id for a
 metric call. A reflection call outside evaluation has no eval id. Manual
 decorators and `start_span` create spans rather than another automatic trace.
 
+The callback seals `started_fact` after it sets the root type, before the
+module executes. It keeps that snapshot even when start emission is disabled.
+The completion callback seals one independently identified `completion_fact`
+with a positive producer sequence. Repeated serialization and HTTP retries
+reuse both objects. A standalone optimizer LM trace seals its creation and
+completion before its first export. The late adapter type stays in the flat
+compatibility fields and ended adapter spans.
+
+Each metadata change gets its own `metadata_facts` entry with explicit map
+assignments and removals. The callback seals initial annotations at creation
+and later changes at completion. Every modern body includes the array, even
+when it is empty, so a retry cannot reapply its flat metadata view as a legacy
+mutation. A streaming finalize carries completion and metadata facts. A full
+body also carries its original started fact. `cmpnd traces update` sends one
+independent `metadata_fact` alongside its existing metadata PATCH envelope.
+
 Two things keep the extra start cheap and correct:
 
-- **Upsert, not duplicate.** The batch finalize (`export_trace`) and the start write the same row: serve's `traceUpsertSQL` keys `ON CONFLICT (org_id, trace_id, start_time)`, and the SDK's `start_time` is immutable across a trace's life, so the batch overwrites the `in_progress` row with the final status. A trace that never finalizes (crash / cancel) correctly stays `in_progress`.
-- **Coalescing.** When a trace's `trace_start` and its full batch `trace` land in the **same** flush, `_flush_batch` drops the redundant `/start` POST (the batch upserts the final row directly), so a fast trace pays one insert, not two. A start whose finalize lands in a later flush still ships — that visibility is the point. Set `stream_trace_starts=False` to opt out entirely (traces then reappear only at finalize, the pre-CMP-257 behavior).
+- **Shared identity.** The start and full body identify the same logical trace and retain the same creation fields. Independent completion reports update its lifecycle without changing the started fact. A trace without a completion report keeps its open execution state until the server infers abandonment.
+- **Coalescing.** When a trace's start and full body land in the same flush, the exporter suppresses the start only if the full body preserves its sealed start and every independent metadata fact. A start in an earlier flush still ships. Set `stream_trace_starts=False` to emit the full body only at completion.
 
 ---
 

{cmpnd-0.32.0 → cmpnd-0.33.0}/ingest/README.md

@@ -44,12 +44,26 @@ Nothing nominal. `BatchExporter` takes a config and record objects described by
 satisfy them by shape, and so may any other producer's records. That is the
 import boundary: the transport knows how to ship a record, not how one is built.
 
-A producer whose records are **already in wire shape** — plain dicts from a guest, or
+A producer whose records are **already in wire shape** — plain dicts from a kernel, or
 from its own record writer — wraps them in `bodies.py`: `TraceBody`, `SpanBody`,
 `OptimizationRunBody` satisfy those same protocols over a dict it hands over. One place
 holds that mapping, so a third producer does not re-derive it from the transport's
 internals.
 
+## Sealing trace facts before delivery
+
+The exporter snapshots a trace when it enters the queue. `TraceBody` also isolates
+nested values at construction and returns fresh copies, so a caller's later edits
+cannot change a pending request or its replay identity. Existing structural records
+and flat legacy payloads remain accepted.
+
+Producers can use `trace_facts.py` without DSPy or HTTP imports. `StartedFact` seals
+creation fields. `CompletionFact` identifies one report with a positive producer
+sequence and a duration in nanoseconds. `MetadataFact` carries independent string-map
+assignments and removals or a project-tag replacement. Serializers reuse these values
+without minting another ID. A start POST is coalesced into a full body only when that
+body retains its identified started and metadata evidence.
+
 ## Writing a run to an id you were handed
 
 `export_optimization_start` reserves an id and then writes the record to it, which is

{cmpnd-0.32.0 → cmpnd-0.33.0}/ingest/cmpnd_ingest/bodies.py

@@ -1,45 +1,35 @@
-"""Records a producer already holds in wire shape, made shippable.
-
-`protocols.py` asks a producer for *objects*: something with `to_api_dict()`,
-`to_start_dict()`, a `trace_id`. The SDK has them, because it builds a trace and a run
-from a live `dspy.Module` and serializes at the end. A second producer often does not: the
-wasm worker's GEPA child receives finished trace dicts from a guest and writes its run
-record as a dict in the shape the contract specifies
-(`search-process/cmpnd_search_process/run_record.py`). It holds the body, not the
-object that built one.
-
-**These are adapters, not a second protocol.** Widening `protocols.py` to `dict | Record`
-was the alternative, and it was rejected: every member the transport reads would grow a
-branch, the SDK's typed path would start paying for a shape it never has, and a producer
-whose records are neither — the third one the contract anticipates — would still be
-outside. A structural `Protocol` is already the widest possible door; what was missing was
-a body-shaped key for it, in one place, so a third producer does not re-derive the mapping
-from the transport's internals.
-
-Each class wraps **one** body and answers every serialization the matching protocol
-declares with it. That is deliberate rather than lax: a producer holding a dict knows
-which of the contract's routes that dict is a body for, and pairs it with the matching
-`export_*` call. The transport asks for exactly one serialization per call, so the pairing
-is what decides which — the same freedom, and the same responsibility, a producer has when
-it writes its own record class.
-
-Every serialization returns a **shallow copy**, because the transport writes into what it
-is given: it stamps the run id into a run body, and `_flush_batch` splices buffered spans
-into a trace body. A producer's dict is its own.
+"""Adapters expose already serialized bodies through the producer protocols.
+
+Each adapter answers the serialization methods for one body. The producer pairs it
+with the matching export call, so independent workers can send wire records without
+importing DSPy. The transport does not create another protocol for dictionary bodies.
+
+TraceBody seals nested values at construction and returns independent copies. A queued
+trace and its replay identities survive later changes to the producer's input or a
+returned serialization. Other adapters copy their outer dictionary before transport
+stamping, and optimization bodies keep the producer's delivery acknowledgement callback.
 """
 
 from __future__ import annotations
 
 from collections.abc import Callable
+from copy import deepcopy
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, init=False)
 class TraceBody:
     """A trace a producer already holds as the body of one of the trace routes."""
 
-    payload: dict[str, Any]
+    _payload: dict[str, Any]
+
+    def __init__(self, payload: dict[str, Any]) -> None:
+        object.__setattr__(self, "_payload", deepcopy(payload))
+
+    @property
+    def payload(self) -> dict[str, Any]:
+        return deepcopy(self._payload)
 
     @property
     def trace_id(self) -> str:
@@ -50,16 +40,16 @@ class TraceBody:
         post needs no such member: it addresses `/traces`, and the id it is keyed on is
         the one in the body.)
         """
-        return str(self.payload["trace_id"])
+        return str(self._payload["trace_id"])
 
     def to_api_dict(self) -> dict[str, Any]:
-        return dict(self.payload)
+        return deepcopy(self._payload)
 
     def to_start_dict(self) -> dict[str, Any]:
-        return dict(self.payload)
+        return deepcopy(self._payload)
 
     def to_finalize_dict(self) -> dict[str, Any]:
-        return dict(self.payload)
+        return deepcopy(self._payload)
 
 
 @dataclass(frozen=True)

{cmpnd-0.32.0 → cmpnd-0.33.0}/ingest/cmpnd_ingest/exporter_http.py

@@ -33,7 +33,7 @@ from typing import Any, cast
 import httpx
 
 from . import request_log, retry
-from .bodies import EncodedTraceBody
+from .bodies import EncodedTraceBody, TraceBody
 from .protocols import (
     EvalRunRecord,
     ExporterConfig,
@@ -557,7 +557,7 @@ class BatchExporter:
 
     def export_trace(self, trace: TraceRecord) -> None:
         """Queue a trace for export (non-blocking)."""
-        self._enqueue(ExportItem("trace", trace, time.time()))
+        self._enqueue(ExportItem("trace", TraceBody(trace.to_api_dict()), time.time()))
 
     def export_encoded_trace(self, trace: EncodedTraceBody) -> None:
         """Queue a compressed finished trace for export (non-blocking).
@@ -594,11 +594,13 @@ class BatchExporter:
 
     def export_trace_start(self, trace: TraceRecord) -> None:
         """Queue a trace start for export (non-blocking)."""
-        self._enqueue(ExportItem("trace_start", trace, time.time()))
+        body = {**trace.to_start_dict(), "trace_id": str(trace.trace_id)}
+        self._enqueue(ExportItem("trace_start", TraceBody(body), time.time()))
 
     def export_trace_finalize(self, trace: TraceRecord) -> None:
         """Queue a trace finalization for export (non-blocking)."""
-        self._enqueue(ExportItem("trace_finalize", trace, time.time()))
+        body = {**trace.to_finalize_dict(), "trace_id": str(trace.trace_id)}
+        self._enqueue(ExportItem("trace_finalize", TraceBody(body), time.time()))
 
     def export_optimization_start(self, optimization_run: OptimizationRunRecord) -> str:
         """Create the optimization record server-side and return the
@@ -1197,8 +1199,20 @@ class BatchExporter:
         # whose finalize lands in a LATER flush still ships, which is the whole
         # point: the trace is visible while it runs.
         if trace_starts and traces_to_send:
-            batched_ids = {str(t.get("trace_id")) for t in traces_to_send}
-            trace_starts = [pair for pair in trace_starts if pair[0] not in batched_ids]
+
+            def start_is_in_body(trace_id: str, start: dict[str, Any]) -> bool:
+                for full in traces_to_send:
+                    if str(full.get("trace_id")) != trace_id:
+                        continue
+                    if not all(fact in full.get("metadata_facts", []) for fact in start.get("metadata_facts", [])):
+                        continue
+                    if "started_fact" not in start:
+                        return True
+                    if full.get("started_fact") == start["started_fact"]:
+                        return True
+                return False
+
+            trace_starts = [pair for pair in trace_starts if not start_is_in_body(*pair)]
 
         # A span is sent exactly once. When its trace ships in this same flush it
         # rides that trace's body and is taken off the spans route; otherwise the