# Letter Tally Pipeline — Phase 2A

This workspace builds per-verse Arabic letter tally matrices from normalized Quran sources.

## Reproducibility Contract

- Source inputs are normalized files matching `*_normalized.csv` or `*_normalized.xlsx`.
- CSV is preferred when both CSV and XLSX exist for the same source stem.
- Input discovery is recursive by default.
- Generated outputs are rebuilt from source files.
- The output schema is deterministic under the documented runtime and dependencies.

## Setup

From the workspace root:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install -r requirements.txt
```

## Run

Run the full Phase 2A pipeline:

```powershell
python run_pipeline.py
```

Clean rebuild:

```powershell
python run_pipeline.py --clean
```

## Verify Reproducibility

Run:

```powershell
.\verify_repro.ps1
```

Expected result:

```text
[OK] Reproducibility verification passed.
[OK] Fresh rebuild succeeded and text outputs are deterministic.
```

## Outputs

```text
out/
  csv/
  json/
  excel/
  txt/
  audit/
```

Per normalized source:

```text
out/csv/<slug>_LETTER_MATRIX.csv
out/json/<slug>_LETTER_MATRIX.json
out/excel/<slug>_LETTER_MATRIX.xlsx
```

Grand summary:

```text
out/txt/GRAND_SUMMARY.txt
```

Audit outputs:

```text
out/audit/workspace_registry.csv
out/audit/workspace_hash_manifest.sha256
out/audit/workspace_validation_report.txt
```

## Scripts

- `letter_tally_engine.py`
- `workspace_registry_hash_audit.py`
- `run_pipeline.py`
- `verify_repro.ps1`

## Notes

This phase performs letter tally only. It does not normalize source text and does not compute higher-order metrics.
