# Your first snapshot

PipeWhy captures versioned data and compares it with explicit coverage and lineage context.
The library currently provides validated flat integer tables, label dictionaries,
typed normalization, reference fingerprints, immutable local snapshots and historical
comparison with explicit uncertainty. The CLI supports help/version, `scan`, `diff`,
`lineage`, `why`, `report integrity` and `export`. Scan captures an explicitly configured fixture
version into a verified local snapshot; the Enron connector also scans a pinned
public dataset revision,
with text or JSON receipts and explicit partial/unavailable read coverage.

From this checkout, after `poetry sync --extras cpu`:

```powershell
poetry run pipewhy scan fixture --config examples/local-fixture.toml --source-version baseline-v1 --retain value --format json
```

The example config resolves its paths relative to `examples/`, stores snapshots in
the ignored `.artifacts/local-snapshots` directory, and uses repository fixtures.
An installed wheel requires an explicitly supplied external fixture directory;
test data is not bundled. `mutation-v1` changes B and `missing-v1` injects a failed C
read. A complete scan exits 0; partial/unavailable scans emit their receipt and exit
4. Operational failures go to stderr and exit 3; argument errors exit 2. Capture
times do not establish operation timing or a physical cause. See the [CLI contract](../development/architecture.rst) for the command and exit-code contract.

For a repeatable run that keeps the three snapshots, incident registry, text/JSON
reports, checksummed CSV and DOT graph, use PowerShell 7 from this checkout:

```powershell
./examples/run-local-slice.ps1 -OutputDirectory .artifacts/my-local-slice -Backend reference
```

Choose a new output directory for each run. Use `-Backend cpu` after installing
the CPU extra, or `-Backend cuda` after installing the CUDA extra on a qualified
GPU host. `-Backend auto` selects the available host backend for this fixture.
The script checks expected exit
codes, including detected changes (1) and missing observations (4), and writes
results through the CLI so CSV checksums cover the exact exported bytes. It uses
the explicitly selected repository fixture; this is a local demonstration. See
the [qualification record](../development/architecture.rst) for the independent oracle and limitations.

`diff BEFORE AFTER --store DIRECTORY --format json` compares captured snapshots;
exit 1 reports detected changes and exit 4 reports required unavailable/incomparable
data. `lineage SNAPSHOT --store DIRECTORY --artifact-id 1 --all-depths --format json`
reads saved declarations and evidence. Both support bounded cursor pages, exact
captured ID/name/path selectors and text/JSON/CSV output; lineage also supports DOT.
CSV requires its checksum-bound metadata companion. Read commands work with offline
sources and do not create a missing store. A selected view retains wider-scope
qualifiers, while its exit code evaluates required selected data before pagination.

`why BEFORE AFTER --store DIRECTORY --incident-window-ns 1000000000 --incident-clock fixture-demo --format json`
combines captured changes, qualified copy/transform conditions, incident evidence
and potential impact. Use value retention when scanning to support transform checks.
The explicit policy clock does not provide missing observation timing; earliest
ordering stays unknown for this fixture. Results are transient unless
`--save-registry NEW_SNAPSHOT_ID` is supplied. Reuse the saved policy/state with
`--registry-snapshot ID`; exact repeated evidence does not increase incident counts.
`--support-limit` bounds condition details while full selected-condition totals still
determine the exit code. Historic registry references outside the supplied capture
pair remain explicitly unexplained.


