Skip to main content

Report Immutability

A CTRF report becomes an immutable artifact when it is written, published, uploaded, or otherwise made available to consumers.

Implementations may freely assemble and transform a document before it is emitted. After emission, consumers and post-processing tools should treat that document as a fixed snapshot rather than modifying it in place.

Why Reports Are Immutable​

Immutability provides:

  • auditable test results
  • reproducible analysis
  • stable caching and artifact storage
  • compatibility with hashing, signing, and deduplication
  • a clear distinction between raw and derived results

Producing Derived Reports​

Post-processing an emitted report produces a new CTRF document. This includes operations such as:

  • merging shard reports
  • filtering tests
  • adding metadata
  • computing insights
  • converting or normalizing report content

When reportId is used, the derived document receives a new value. The source document and its reportId continue to identify the original artifact.

runId has a different purpose: it identifies the logical test run. A derived document may retain the same runId when it still represents that run. Tools should not preserve or invent a common runId when the inputs do not represent one logical run.

OperationreportIdrunId
Retransmit the exact unchanged artifactKeep the same valueKeep the same value
Merge shards from one logical runAssign a new valuePreserve the shared value
Filter or enrich an emitted reportAssign a new valuePreserve it when the document still represents the same run
Combine documents without one shared logical runAssign a new valueDo not claim a shared run identity

All identity fields are optional. These rules describe how to handle them when they are present.

Example​

Three shard documents can share one runId while each has a distinct reportId:

runId: nightly-e2e-2026-08-15
├── shard 1 reportId: 11111111-1111-4111-8111-111111111111
├── shard 2 reportId: 22222222-2222-4222-8222-222222222222
└── shard 3 reportId: 33333333-3333-4333-8333-333333333333

Merging those artifacts creates another document. It receives a new reportId, retains the shared runId, and leaves the three source artifacts unchanged.

See Root Object for the identity fields and the ctrf merge API for the JavaScript implementation.