Ayah-counting systems

This is the single most common source of silent bugs in Qur’an software. It costs nothing to get right at the start and is expensive to retrofit, because by then the wrong numbers are in your database.

The part that surprises most developers: the text does not change. Not a letter. Two scholars reading the identical text disagree only about where to put the numbered break between one verse and the next. So a "different count" is not different content — it is different punctuation of the same content.

That is why the bug is silent: the text renders correctly and the references point somewhere else.

Sūrat al-Ikhlāṣ makes it concrete. It is four ayat in First Madinan, Last Madinan, Basran and Kufan, and five in Makkan and Damascene. The entire question is whether lam yalid wa-lam yūlad is one ayah or two. Nothing is added and nothing is removed; a break moves.

The six systems

Two things in that table catch people out.

First and Last Madinan share a total of 6,214 — and they are still different systems. They place some of their boundaries in different places, and those differences cancel out in the sum. So you cannot identify a counting system by its total, and comparing totals is not a valid equality check.

The second trap: a total is not a muṣḥaf's ayah count

These two numbers sound like the same thing and are not:

• The published total of a counting system — an abstract scholarly position. Basran is 6,204.
• The number of numbered ayat in a particular printed muṣḥaf — what a publisher actually set in type.

They can disagree. The KFGQPC al-Sūsī muṣḥaf we ship prints 6,218 ayat, while the Basran system its qāriʾ is associated with totals 6,204. Both numbers are correct about different questions.

What to do instead

1. Never write a count as a literal

   Read it from the riwayah you loaded, because numbering systems differ (Quranic text, rule 5.2). Every dataset we publish carries its own totals, so the correct number is always already in memory.

   // wrong — correct only for Ḥafṣ
   for (let a = 1; a <= 6236; a++) { /* ... */ }
   
   // right — correct for whatever the user selected
   for (let a = 1; a <= mushaf.ayahCount; a++) { /* ... */ }
   

2. Store the system alongside every reference you persist

   A bookmark saved as 7:206 is not enough information to restore. Saved as { surah: 7, ayah: 206, counting: "kufi" } it can be translated into whatever the user is reading later — the ayah key is surah and ayah together (Engineering, rule 2.1).

   type StoredRef = { surah: number; ayah: number; counting: CountingSystem };
   

3. Translate references with Qiraat Ayah Map, not with arithmetic

   The offset between two systems is not constant across a surah: boundaries move independently, so there is no delta to add. Use the mapping, and name the riwayah and the numbering system explicitly (Engineering, rule 3.2) on both sides of it.

Where the six come from

They are not conventions someone chose. Each is a transmission with a named chain, and there are six because the muṣḥafs ʿUthmān sent to the garrison cities were six. Which chain stands behind each system, which reciters rely on it, and how well attested each individual boundary is are all set out in method and evidence.

How this data is made

Qiraat Ayah Map does not store six full copies of the Qur’an. It stores the boundary primitives, the places where the traditions agree and disagree about a break, and each system's numbering is derived from those. Rebuilding all six from the primitives reproduces every published total exactly, and the derived numbering ships with the package.