Turbopack: bump trace format header to TRACEv1 (#99781)
## Summary
Bumps the trace file header from `TRACEv0` to `TRACEv1`, because the
stack below changed the row format incompatibly. Readers only accept the
current version and fail with a clear error on anything else. No v0
support is kept.
- `TRACE_HEADER`, `TRACE_HEADER_PREFIX` and `check_trace_header` live in
`turbopack-trace-utils` and are shared by the writer, the trace server
and `turbo-trace-size`.
- Trace server: format detection is now a small tested function. A
`TRACEv*` file with another version fails with `Unsupported trace file
version: expected TRACEv1, found TRACEv0`. That includes a file with
only the 7-byte header. The fallback that read header-less files as
Turbopack traces is gone, so unknown formats fail with an error. Next.js
JSON traces and heaptrack files are still detected. Empty or
partial-prefix files still wait for more data, because the server
follows traces while they're written.
- `turbo-trace-size` fails on missing or unsupported headers.
- `next internal upload-trace` checks for `TRACEv1` and reports an
unsupported version separately from a non-trace file.
- `contributing/turbopack/tracing.md` documents the format and
versioning.
Stack (on top of #99765):
1. #99777: `no-memory` flag
2. #99778: Merge allocation counters into Enter/Exit rows
3. #99779: Delta-encode allocation counters, skip unchanged ones
4. #99780: Omit Exit+Enter pairs with (almost) no gap
5. #99808: zstd flags
6. #99809: Delta-encoded timestamps
7. #99781: **This PR**: bump the trace header to `TRACEv1`
8. #99810: `upload-trace` accepts compressed traces
## Measurements (whole stack)
`next build` of `bench/heavy-npm-deps`, release native binding built
from source:
| | `1` raw | `1,zstd` | `turbo-tasks,zstd` |
| --- | --- | --- | --- |
| before (#99765) | 68.2 MiB | 21.4 MiB (zstd -3 offline) | |
| after #99780 | 22.8 MiB | 5.9 MiB | 26.8 MiB |
| after this stack | **20.1 MiB** | **4.5 MiB** | **21.1 MiB** |
The `before` zstd number comes from compressing the raw trace offline;
the writer couldn't write zstd before this stack.
## Verification
- **Tests:** `check_trace_header`, server format detection (old,
unknown, partial and header-only files), and `turbo-trace-size`
rejecting missing or old headers.
- **Captures:** traces from a locally built release binding (`1`,
`1,zstd`, `turbo-tasks,zstd`) start with `TRACEv1`, and
`turbo-trace-size` decodes them fully.
- The trace server loads them completely: 39,481 and 817,619 spans.
- Both tools reject a `TRACEv0` file with the error above.
<!-- NEXT_JS_LLM -->
<!-- fleet 4a52842b-f1a2-43cb-9779-3655caada6a0 -->
Co-authored-by: vercel-fleet-prod[bot] <318278635+vercel-fleet-prod[bot]@users.noreply.github.com>
Co-authored-by: Tobias Koppers <1365881+sokra@users.noreply.github.com>
