---
title: "Validation evidence atlas and software-paper reporting"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Validation evidence atlas and software-paper reporting}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(eyeprocess)
```

The evidence atlas links claims to executed outputs, tables, figures, hashes, provenance, and limitations while preserving the distinction between software behavior and substantive validity.

```{r}
claims <- eyeprocess_validation_claim_matrix(
  c("C1","C2"),
  c("Scenario expansion is deterministic", "Exact engines are not silently substituted"),
  c("E1","E2"), c("test","engine-contract"), c("supported","qualified")
)
atlas <- eyeprocess_validation_evidence_atlas(claims, recovery = data.frame(id="demo"))
atlas
```

`freeze_eyeprocess_validation_atlas()` creates an integrity-checked snapshot. `write_eyeprocess_validation_report()` emits a compact Markdown report suitable for archival review. Paper-ready table helpers convert recovery, SBC, stress, reliability, negative-control, IRT precision, and external-engine status into compact data frames.

<!-- BEGIN EYEPROCESS ARTICLE VISUALS ATLAS -->

## Visual evidence atlas

The next views show how declared claims and evidence are represented before and after freezing. They describe evidence organisation and provenance, not substantive construct validity.

```{r m2-visual-atlas, fig.width=7, fig.height=4.5, fig.align='center', fig.cap='Illustrative validation-evidence atlas linking a declared software claim to recorded evidence.'}
viz_claims <- eyeprocess::eyeprocess_validation_claim_matrix(
  'C1',
  'software behaviour is reproducible',
  'E1',
  'test',
  'supported'
)

viz_atlas <- eyeprocess::eyeprocess_validation_evidence_atlas(
  viz_claims,
  recovery = data.frame(x = 1)
)

stopifnot(
  inherits(viz_atlas, 'eye_validation_evidence_atlas')
)

plot(viz_atlas)
```

```{r m2-visual-atlas-freeze, fig.width=7, fig.height=4.5, fig.align='center', fig.cap='Frozen form of the illustrative validation-evidence atlas.'}
viz_atlas_freeze <- eyeprocess::freeze_eyeprocess_validation_atlas(
  viz_atlas
)

stopifnot(
  eyeprocess::verify_eyeprocess_validation_atlas(
    viz_atlas_freeze
  )
)

plot(viz_atlas_freeze)
```
<!-- END EYEPROCESS ARTICLE VISUALS ATLAS -->