Make OTLP a lossless wire in both directions

[Exelord]

The OTel exporter now describes a run completely, and vx Cloud accepts
OTLP as an ingest path — so the standard wire carries everything, feeds
the dashboard, and is enough for anyone else to build their own analytics
on.

The design call

OTLP became the export plus a receiver, not core's internal contract.
Making it the contract would hardcode a vendor spec into core — the
coupling the provider-neutral directive removed — and the two audiences
differ: a tracing backend wants spans, cloud wants a lossless, idempotent,
atomic per-run record. One shape serving both means the lossy one wins.
So TelemetryRecord stays core's contract, @vzn/vx-otel stays the only
place OTel is named, and cloud grew a receiver.

What the exporter was dropping

Measured by diffing what cloud's ingest writes against what the mapper
emitted:

• workspaceId / workspaceName — the multi-workspace routing key. A
  backend could describe a run but not say which workspace it belonged to.
• defaultBranch — the trunk-vs-branch trust axis.
• outputFp — the entire cross-machine hermeticity signal. A
  --verify=fingerprint divergence was invisible over OTel.
• Wallclock offsets, every run tally, and rerun-failed's own exitCode
  (a receiver knew the re-run failed but not with what).
• Task logs, which had nowhere to go but a vx-specific endpoint — the half
  a developer actually opens when a build goes red.

Encoding decisions that are not aesthetic

• Nanosecond offsets ride as OTLP int64 strings. 9007199254740993 is
  the first integer a JS number cannot hold, and a receiver derives a task's
  dedup key from it.
• Run start/end also ride as millisecond attributes even though the span
  carries times, because the span's are unix-nanos (epoch-ms × 1e6 is past
  MAX_SAFE_INTEGER) and those two values are a storage partition key.
  Losing precision there is a row in the wrong partition, not a rounding error.
• Verify path lists became JSON arrays. A comma is a legal byte in a
  filename and these are the actionable half of a verdict, so a split path
  names a file that does not exist. vx.requested_tasks deliberately stays
  comma-joined — read by humans far more often than parsed — and that is
  written down as a stated limit, not a guarantee.
• The fingerprint's per-file map may legally not survive. It is the
  largest attribute and a limiting collector truncates it first. Detection
  keys on the fixed-width tree digest, so that costs a diff its detail,
  never its verdict.

Logs

One record per task, not per chunk: a build writes output in thousands
of tiny pieces, so a record each would multiply the payload to deliver the
same bytes and force every receiver to reassemble them before showing
anything. Records link to their task span by trace and span id.

On by default once an endpoint is configured (the cloud sink's convention),
with the standard OTEL_LOGS_EXPORTER=none honoured so a pipeline already
configured that way does not start receiving build logs because it upgraded
vx. With the signal off the sink stops declaring task.log in wants, so
core never projects a chunk and the run pays nothing.

TaskLogBuffer moved into core rather than being reimplemented: the
otel sink needs the identical bounds and retention rules, and a second copy
of those rules is how two sinks come to disagree about which task's output
survived. Cloud keeps one import path via a re-export shim, so no call site
moved.

The receiver

POST /v1/otlp/v1/{traces,logs} decodes into the same records the native
endpoints take and calls the same Analytics.ingest* — one store, one set
of read queries, no second schema. The existing
(started_at, run_id, project, task) idempotency covers a retried OTLP
batch for free, which matters because OTLP exporters retry and carry no
dedup semantics of their own.

Two things OTLP cannot say for itself:

• No run boundary. The vx.run root span is required — it is the span
  that ends last — so a payload without one is a 400 rather than a
  half-stored run.
• Collectors may drop spans. Tallies are recomputed from the spans that
  arrived, via the same function the native path uses, so a partial batch
  yields a header consistent with the rows it stored instead of a count that
  outruns them.

The decoder repeats the exporter's attribute keys on purpose: cloud takes no
runtime dependency on the exporter, and a wire only one package can write is
not much of a wire. The copy is guarded differentially — the tests drive
the real OtelSink and assert the decode reproduces the record that went in.

Deliberately not done

/v1/ingest is not replaced. Its per-run transaction, its incremental task
rows (what makes run detail fill in live) and the catalog push have no OTLP
analogue, and a config snapshot is not an observation. Both wires are
documented, with the OTLP caveats stated rather than papered over.

Verification

Mutation-checked rather than assumed: renaming vx.task.hash in the
encoder fails exactly 2 of the receiver's 12 tests (restore → 12/0);
dropping defaultBranch from the encoder fails exactly 1 of vx-otel's 34
(restore → 34/0). A completeness pin on the RunContextRecord field set
means a new telemetry field fails until someone decides how it maps.

One existing test was repinned honestly: the sink used to assert wants
never contains task.log — true when it had nowhere to send them; it now
asserts the refusal is conditional, with the logs-off arm still pinned so
the zero-cost property cannot regress.

No CACHE_VERSION / schema / migration / wire bump.
TELEMETRY_SCHEMA_VERSION stays 2 — no contract field was added; the
exporter was simply not carrying fields that already existed.

Gates from the root: fmt/lint 0, core 2631 / 0 (23 skip = sandbox),
cloud 1280 / 0 across 58 suites (38 skip = the browser suites, which
need playwright + a built ui/dist this container lacks), vx-otel
43 / 0, docs site 168 pages with a zero-broken-link crawl over both
edited pages.

🤖 Generated with Claude Code

https://claude.ai/code/session_019x8vExRpvPDkvwcDZ7wKDE

---

Generated by Claude Code