# Reports, checkpoints and bundle formats

Serialized `formatVersion: 1` is a data-format version, independent of repository package releases. Parsers reject unsupported versions and unknown/malformed contracts explicitly. Use supported parse/export APIs rather than assembling a guessed manifest.

## Portable bug report

`BugReport` retains stable identity, revision, timestamps, narrative, established/proposed expectation, actual behavior, hypotheses, reproduction steps, recorded interactions, evidence, optional executable reproduction and detached source context.

`parseBugReport` rejects duplicate identities, dangling references, invalid readiness claims and unsupported JSON data. `reviseBugReport` preserves identity/source snapshots while incrementing revision and invalidating verification. [Reports/evidence concepts](../concepts/reports-and-evidence.md) explains the distinctions.

## Test-run model and checkpoint

A run contains policy and results. Each result retains a test-definition snapshot, attempts and independent comments. The runner's authoritative `checkpoint.json` stores a validated `view`, section hierarchy, hook events, warnings/processing status, and an attachment index keyed by result/attempt/evidence identity.

Attachment paths are relative to the run directory under `raw-evidence/`. Bytes are stored before checkpoint references are published. Atomic replacement leaves the previous complete snapshot readable if interrupted. Raw output is private and not equivalent to a reviewed export.

Legacy `run.json`/`execution.json`/`attachments.json` output remains readable by `report` when model/view agree; it is not silently migrated. Legacy retries or incompatible definition revisions need a new run. [Canonical checkpoint detail](../../../integration/agent-testing.md#completion-retries-and-reporting) is authoritative.

## Reviewed portable bundle

`createReportBundle` returns reviewed relative files: `report.json`, a script-free semantic `index.html`, and optional generated `attachments/<n>.<ext>` paths. The manifest records reviewed/redacted/omitted/unavailable evidence without removed values. The host chooses transport and preserves the complete directory.

The viewer escapes report text, previews supported raster/video types and offers other attachments as downloads. It is a portable offline viewer, not the final interactive reporter. `importReportBundle` validates paths, references, byte lengths, versions and viewer consistency; extra/hidden files are rejected and imported bytes are copied. Scripts remain data.

Initial limits include 10 million JSON characters, 50 nesting levels, and 250 MB attachment bytes; export defaults limit individual attachments to 100 MB and can tighten limits. Byte-length consistency does not establish cryptographic authenticity or trust.

## Review and delivery

`prepareReportExport` prepares reviewed manifest/files without rendering a viewer. Bug and test-run exports share review preparation while retaining distinct models. Provider delivery uses that same boundary and returns report/export identity plus a host-provided receipt. A partial delivery preserves its created ticket reference rather than automatically retrying.

Read [canonical portable format and limits](../../../integration/portable-reports.md#sanitization-and-self-contained-export), [sanitization guide](../guides/export-and-sanitize-evidence.md), and [the illustrative artifact](../../examples/test-results.md).