> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Read Result Data in a Report

> Declare result reads with AnalysisSample and NiceEval's official opaque projectors from niceeval/report.

A Record is an opaque, portable directory under `.niceeval/record/` that can be copied or put in Git.
Application code does not read its internal structure, write its files, or import a Record reader or writer.
The internal hosts for `niceeval show` and `niceeval view` select Runs and run projections.

To inspect results in a terminal or browser, see [Viewing Results](/docs/tutorials/viewing-results).
To define pages and calculations, see [Report Components API](/docs/reference/report-components).

## Report callbacks receive `AnalysisSample`

Calculation, Page, and PageFamily callbacks receive a pure `AnalysisSample`.
It holds every expected slot in the framework established by selection and its complete denominator, with no path, reader, file handle, or deferred I/O.
`--run` uses each named Run's complete expected slots; `project-current` materializes only slots whose identities still match the current target:

| State          | Meaning                                                         |
| -------------- | --------------------------------------------------------------- |
| `included`     | A valid Member points to one exact Attempt.                     |
| `not-recorded` | The expected slot has no Member.                                |
| `core-invalid` | The Member, Attempt, or core reference cannot be read reliably. |
| `excluded`     | The host explicitly excluded this item from an existing Sample. |

Authors can import the needed Sample and identity types from `niceeval/report`.
They can also apply pure `narrowAnalysisSample` to an existing Sample.
Those values cannot restore Record I/O.

## Declare data with an official projector

Report authors choose an opaque projector supplied by NiceEval, then declare how it aligns with a Sample:

```ts theme={null}
import {
  attemptSlotProjection,
  selectedRunProjection,
  evaluationsProjector,
  verdictProjector,
} from "niceeval/report";

const verdicts = attemptSlotProjection(verdictProjector);
const evaluations = selectedRunProjection(evaluationsProjector);
```

`attemptSlotProjection` creates one entry for every slot.
`attemptOriginRunProjection` also creates one entry per slot, but uses the Attempt's origin Run.
`selectedRunProjection` creates one entry for every selected Run.

Authors cannot define raw Attachment families or projectors, receive payload or blob capabilities, or call the projection runtime directly.
When a Report needs a new durable fact, NiceEval must supply a higher-level projector or a future Eval, Experiment, or Plugin capability.

## Projection results remain exhaustive

The first two slot projections preserve `excluded`, `not-recorded`, `core-invalid`, and `attachment-result`.
An attachment result then expresses:

| State                   | Meaning                                                      |
| ----------------------- | ------------------------------------------------------------ |
| `available`             | The official projector formed a typed value.                 |
| `unavailable`           | The owner did not request this fact.                         |
| `migration-required`    | The current value requires `niceeval migrate`.               |
| `migration-unavailable` | Historical facts cannot form the current value without loss. |
| `unsupported`           | The current NiceEval does not recognize this fact version.   |
| `invalid`               | Recorded data cannot be interpreted reliably.                |

These are Report-visible data states. They do not change the Sample's Core state.
I/O, permissions, reader Scope, and raw schema errors remain inside the host.
Public authors receive only self-contained values and structured Report problems.

## Related pages

* [Architecture Overview](/docs/explanation/overview): Learn why a Record is an opaque product asset.
* [Viewing Results](/docs/tutorials/viewing-results): Select results with `show` and `view`.
* [Report Components API](/docs/reference/report-components): Consume `ProjectedSample` and create a Report.