Report Formats

Describe coverage, shape coverage, and propagation outputs as machine-readable artifacts.

Abstract

Blackbox writes several report formats from the same run. This page explains which file belongs to which stage, what each file is for, and how stable each output is.

Audience

People who need to consume, parse, archive, or compare the artifacts Blackbox produces.

Artifact Family

Reporter token	Artifact	Format	Purpose
`json`	`omcdc-propagation.json`	JSON	Machine-readable OMC/DC propagation report.
`markdown`	`omcdc-propagation.md`	Markdown	Human-readable OMC/DC report for reviews and editor inspection.
`html`	`omcdc.html`	HTML	Interactive OMC/DC report with branch-level inspection.
`catalog-json`	`coverage.json`	JSON	Effect catalog coverage summary.
`shape-json`	`shape-coverage.json`	JSON	Boundary-shape coverage summary.
`junit`	`omcdc.junit.xml`	XML	CI-facing test-result view of OMC/DC verdicts.

Stability Notes

coverage.json and shape-coverage.json are compact summaries and are the safest starting point for automation.
omcdc-propagation.json is machine-readable but carries detailed branch and verdict data that may evolve while the alpha engine evolves.
Markdown and HTML reports are review artifacts. They are meant to be read, attached, and linked, not parsed as stable APIs.
omcdc.junit.xml is designed for CI systems that already understand JUnit XML.
Per-test span and V8 files are diagnostic inputs, not public report formats.

What Each Artifact Is For

`omcdc-propagation.json`

Contains endpoints, branch coordinates, true-arm test IDs, false-arm test IDs, not-observed test IDs, verdicts, hints, and observed effect shapes. Use it when an agent or tool needs to understand why a branch is propagating, masked, or still a gap.

`omcdc-propagation.md`

Contains the same OMC/DC story in a reviewable form: endpoint sections, verdict counts, branch tables, hints, and oracle data per branch. Use it when a reviewer needs to understand the result without opening the interactive report.

`omcdc.html`

The interactive OMC/DC report. Use it when a developer needs to inspect branches, hints, source snippets when available, and the relationship between decisions and observed effects.

`coverage.json`

Summarizes effect catalog entry coverage. It answers whether catalog entries were seen, satisfied, failed, or uncovered.

The shape is based on:

catalog: service name, entry count, and catalog API version.
totals: seen, satisfied, failed, and uncovered counts.
perEntry: per-catalog-entry state, run count, pass count, and failure count.

`shape-coverage.json`

Summarizes effect shapes, not whole catalog entries. It answers whether declared or inline boundary shapes were asserted and observed.

Shape states are:

asserted: declared in the catalog and named by a matcher.
unasserted: declared in the catalog but never named by a matcher.
inline: named by a matcher but not declared in the catalog.

`omcdc.junit.xml`

Maps OMC/DC verdicts into CI test-result vocabulary:

OMC/DC verdict	JUnit mapping
`propagating`	pass
`masking-candidate`	failure
`coverage-gap`	skipped
`undecidable`	pass with `system-out`
`multi-arm`	pass with `system-out`
`unsupported-mcdc`	pass with `system-out`

Artifact Delivery

Reporters render artifacts. Sinks deliver them.

That separation matters: the same proof can become files, stdout output, GitHub Actions annotations, or CI test results without changing the evidence or the coverage model.

The GitHub Actions sink reads omcdc-propagation.json and emits workflow annotations for actionable verdicts:

masking-candidate becomes a warning.
coverage-gap becomes a notice.
Other verdicts are silent.

Practical Reading Order

Start with the filename.
Check whether the output is JSON, Markdown, HTML, or XML.
Check whether it is intended for humans or automation.
Use the related concept pages if you need the model behind it.

Figure Placeholder

Caption: The artifact family Blackbox emits for review and automation.

Slot: 