# Quranic Initial PIPELINE — Phase 2B (14 Initial Engine)

The Quranic Initial PIPELINE analyzes the 29 suras containing Huruf Muqatta'at (disconnected initials) and generates per-mushaf initial-letter datasets from normalized Quran source files.

This phase forms the Initials Engine used throughout the Criterion project and is frozen under deterministic reproducibility requirements.

---

## Purpose

This engine:

* Reads normalized mushaf XLSX files.
* Identifies all verses belonging to the 29 initialed suras.
* Extracts the initials associated with each sura.
* Produces structured JSON, CSV, XLSX, and flat-file outputs.
* Generates workspace registry, SHA256 manifest, and validation reports.
* Supports deterministic rebuild verification.

---

## Requirements

* Python 3.10+
* openpyxl==3.1.5

---

## Setup

### Windows

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

### Linux / macOS

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

---

## Inputs

The workspace root contains normalized mushaf files.

Supported formats:

```text
*_normalized.xlsx
*_normalized.csv
```

Examples:

```text
Hafs(Basra)_normalized.xlsx
Warsh(Mecca)_normalized.xlsx
The_Criterion_normalized.xlsx
```

---

## Engine Execution

Run the Initial Engine directly:

```bash
python 14_initial_engine.py
```

Optional explicit input:

```bash
python 14_initial_engine.py --input Hafs_normalized.xlsx
```

---

## Pipeline Orchestration

Run the complete Phase 2B workflow:

```bash
python run_pipeline.py
```

Pipeline stages:

1. Execute 14_initial_engine.py
2. Generate output datasets
3. Generate workspace registry
4. Generate SHA256 manifest
5. Generate validation report

---

## Reproducibility Verification

Verify deterministic rebuild behavior:

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

Verification performs:

1. Clean rebuild
2. Second rebuild
3. Registry regeneration
4. Hash comparison
5. Canonical output verification

Pass condition:

```text
[OK] Reproducibility verification passed.
[OK] Fresh rebuild succeeded, naming contract holds,
and canonical Phase 2B outputs are deterministic.
```

---

## Outputs

Generated under:

```text
14_initial_engine_outputs/
```

Structure:

```text
14_initial_engine_outputs/
├── json/
├── csv/
├── excel/
├── audit/
├── 14_initial_engine_flat.txt
├── 14_initial_engine_flat.csv
└── 14_initial_engine_flat.xlsx
```

---

## Audit Artifacts

Generated under:

```text
14_initial_engine_outputs/audit/
```

Files:

```text
workspace_registry.csv
workspace_hash_manifest.sha256
workspace_validation_report.txt
```

Purpose:

* Registry of tracked files
* SHA256 integrity manifest
* Workspace validation summary

---

## Deterministic Reproducibility Policy

Canonical reproducibility is established when repeated executions produce identical canonical outputs.

Canonical artifacts:

```text
JSON
CSV
TXT
```

XLSX files are generated and tracked for integrity visibility but are not treated as canonical deterministic artifacts.

---

## Covered Suras

The engine processes all 29 Quranic suras containing Huruf Muqatta'at:

```text
2   الم
3   الم
7   المص
10  الر
11  الر
12  الر
13  المر
14  الر
15  الر
19  كهيعص
20  طه
26  طسم
27  طس
28  طسم
29  الم
30  الم
31  الم
32  الم
36  يس
38  ص
40  حم
41  حم
42  حمعسق
43  حم
44  حم
45  حم
46  حم
50  ق
68  ن
```

---

## Frozen Status

Phase: 2B

Current status:

```text
Engine Execution          PASS
Registry Audit            PASS
Hash Manifest             PASS
Validation Report         PASS
Reproducibility Audit     PASS
```

Phase 2B is frozen for seven-reader production use.

Any future modification requires regeneration of:

* Output datasets
* Registry
* Hash manifest
* Validation report
* Reproducibility verification
