---
title: "Methodology: hand-computed worked examples"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Methodology: hand-computed worked examples}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

Every computation in `cer` is verifiable with pen and paper. This
vignette walks through the three formula functions.

## 1. Safeguard declining baseline

### Formula

\[
B_t \;=\; B_{2023\text{-}24} \times (1 - 0.049)^{t - 2023}
\]

Source: Safeguard Mechanism (Crediting) Amendment Act 2023.

### Hand calculation

Aluminium smelting 2023-24 default baseline = 1.650 t CO2e per
tonne aluminium. For FY 2029-30 (t = 2029):

\[
B_{2029\text{-}30} = 1.650 \times (1 - 0.049)^6 = 1.650 \times 0.738 = 1.218
\]

### Package output

```{r}
traj <- cer_safeguard_baseline_trajectory("Aluminium smelting",
                                           from_year = 2023,
                                           to_year = 2029)
traj
```

Row for 2029: baseline ~= 1.218. Matches.

### Sanity check at base year

```{r}
traj[traj$year == 2023, ]
```

Decline factor = 1.000; baseline = 1.650. Identity holds.

## 2. QCMR reconciliation

### Formula

\[
\pi \;=\; \frac{V - R}{R}
\]

where V is the live-fetched aggregate and R the QCMR reference.

### Hand calculation

ACCU cumulative issuances at end of 2024-Q4 per QCMR = 185,000,000.
Suppose a user's fetch shows 184,200,000 (0.43 per cent low).

\[
\pi = \frac{184{,}200{,}000 - 185{,}000{,}000}{185{,}000{,}000}
     = \frac{-800{,}000}{185{,}000{,}000} = -0.00432 = -0.432\%
\]

### Package output

```{r}
cer_reconcile(value   = 184200000,
              quarter = "2024-Q4",
              measure = "accu_cumulative_issuances")
```

At -0.43 per cent the reconciliation falls within the default
2 per cent warning threshold; no warning fires.

## 3. SHA-256 integrity

### Specification

SHA-256 as defined in NIST FIPS 180-4. Empty-string digest:

```
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

### Verification

```{r}
f <- tempfile()
file.create(f)
cer_sha256(f)
```

Matches the NIST reference.

## Summary

| Function | Formula | Verified |
|---|---|---|
| `cer_safeguard_baseline_trajectory` | B_t = B_0 * (1 - 0.049)^n | Yes |
| `cer_reconcile` | (V - R) / R | Yes |
| `cer_sha256` | NIST FIPS 180-4 | Yes |

Any disagreement between a hand calculation and the package output
is a bug; please file an issue.