# Baloot Rulebook (كتيّب قوانين البلوت) — the canonical source

**The booklet itself now lives in the repo: [`docs/baloot-rules-booklet.tex`](baloot-rules-booklet.tex).**

This is the rulebook this implementation is written against. Until
2026-08-02 it existed only outside the repo — the engine cited it by page
number (`بند التوريق ص7`, `بند السوا ص15`, …) but no session could actually
*read* it and had to trust a secondhand summary. Now the primary source is
here, and every one of those citations is checkable.

---

## 1. Precedence — the booklet wins

When sources disagree about a Baloot rule, this is the order:

1. **A recorded project ruling** — a decision taken where the booklet is silent,
   written down in `docs/baloot-rules-audit.md` (or the notes) with its
   reasoning. These are few and each one is dated; see §1a.
2. **This booklet** — `docs/baloot-rules-booklet.tex`.
3. **The official federation regulation** (اللائحة العامة للعبة البلوت) — the
   2026-07-20 alignment pass in `docs/baloot-rules-audit.md`.
4. **Community sources** (pagat, Jawaker, Arabic Wikipedia, …) — the original
   2026-07-09 audit. Weakest; several were later retired.

> «the booklet supersedes the federation لائحة wherever the two disagree»
> — `src/game/bidding.ts`, header

`docs/baloot-rules-audit.md` remains the **history** (what changed, when, and
why). This file is the **law**. If the audit doc and the booklet conflict, the
booklet is right and the audit doc is stale — fix the audit doc.

### 1a. Rulings where the booklet is SILENT

The booklet does not cover everything. Where it is silent, the gap is filled by
a recorded ruling — level 1 in the order above — written down here so a later
reader does not mistake settled behaviour for a bug.

If you believe one of these rulings is wrong, open an issue quoting the booklet
clause you are reading it against. The engine's tests encode these decisions, so
changing one is a test change as much as a code change.

**Silence is not a rule.** A clause that is narrow («على أكة») or absent
(round-2 «قبلك») must not be widened into a blanket ban or a blanket
permission. That exact misreading removed the round-1 Hokum flip on 2026-07-21
and had to be undone in `4baee2c` seven months later.

| Question | Booklet | Ruling | Date |
|---|---|---|---|
| Does «قبلك» exist in **round 2**? | **Silent.** The only «قبلك» clause is ص9 and it says «اشترى آخر لاعب صن **بالأول**» — round 1. Nothing anywhere states a round-2 Sun is final either. | **No — round 1 only.** A round-2 Sun concludes the auction outright. Asked directly twice; kept both times. | 2026-08-01, reaffirmed 2026-08-02 |
| Can a first Hokum be flipped to Sun? | ص10 bars it **on an أكة only**. | **Yes on any non-Ace floor**; the Ace is the only bar. A flip yields a plain Sun and opens «قبلك». | 2026-08-02 (`4baee2c`) |

Enforced in `src/game/bidding.ts` — both rulings carry the same note at their
implementation site.

## 2. Citation convention — `ص<N>` maps to a real page

The `.tex` carries the booklet's own pagination as comment markers:

```tex
% ================= p.7 =================
\balootsection{بند التوريق}
```

So an existing code comment like:

```ts
* التوريق (Tawreeq) — بند التوريق، كتيّب قوانين البلوت ص7.
```

points at `% p.7` in the `.tex`. Every `ص<N>` citation currently in the engine
was verified against these markers on 2026-08-02 — they all match.

**When you implement or change a Baloot rule, keep this up:** cite the بند and
its page, and quote the booklet clause verbatim in the comment or the test
name. That is why the 2026-07-21 alignment is still auditable a year later.

## 3. Page map

| Page | Section |
|---|---|
| cover | title + contents blurb |
| p.1 | تمهيد اللعبة — 4 players, 32 cards, 4 زات, 152 to win |
| p.2 | قوانين البلوت العامة + حالات وإجراءات |
| p.3 | قوانين البلوت العامة — حالات وإجراءات (cont.) |
| p.4 | بند القص |
| p.5 | بند التوزيع |
| p.6 | بند التوزيع — حالات وإجراءات (cont.) |
| p.7 | بند التوريق |
| p.8 | بند المشتريات (صن · أشكل · حكم أول · حكم ثاني) |
| p.9 | الصن + حالات وإجراءات |
| p.10 | الحكم الأول والثاني |
| p.11 | الحكم الأول والثاني — حالات وإجراءات (cont.) |
| p.12 | الأشكل |
| p.13 | بند المشاريع |
| p.14 | بند المشاريع — حالات وإجراءات (cont.) |
| p.15 | بند السوا |
| p.16 | بند الكبوت |
| p.17 | بند الأبناط + تحويل الأبناط إلى نقاط + قيم المشاريع |
| p.18 | بند الدبل / بند دبل الصن |
| p.19 | بند دبل الحكم الأول والثاني |
| p.20 | طريقة حساب الدبلات (دبل 16+16 · ثري · فور · قهوة 152) |
| p.21 | بند قوانين التسجيل / القيد |
| p.22–23 | بند خرافات البلوت — myths, each with the correction |
| p.24–25 | شرح مصطلحات البلوت الأساسية — glossary |

## 4. Where the booklet is implemented

A starting point, not an exhaustive index — grep for `كتيّب` or `ص<N>` to find
every citation.

| Booklet section | Primary code |
|---|---|
| p.2 مشترى فاصل (tie at 152+) | `src/game/scoring.ts` → `resolveMatchOver` |
| p.7 بند التوريق | `src/game/tawreeq.ts` |
| p.8–9 المشتريات · الصن · «قبلك» chain | `src/game/bidding.ts` |
| p.10–11 الحكم الأول والثاني (no Ace flip) | `src/game/bidding.ts` |
| p.12 الأشكل | `src/game/bidding.ts` |
| p.13 بند المشاريع · البلوت blocked by مية شيبان/بنات | `src/game/baloot.ts`, `src/game/projectResolution.ts`, `src/game/projectSelection.ts` |
| p.15 بند السوا | `src/game/sawa.ts`, `src/lib/baloot-engine-v2.ts` → `checkSawa` |
| p.16 بند الكبوت | `src/game/scoring.ts` |
| p.17 بند الأبناط | `src/game/buntCalculator.ts`, `src/game/scoring.ts` |
| p.18–20 الدبل / الثري / الفور / القهوة | `src/game/doubling.ts`, `src/game/scoring.ts` → `resolveScore` |

Shared engine: `src/lib/baloot-engine-v2.ts` (re-exported into the edge bundle
through `src/lib/baloot/serverEngine.ts` — solo and online must not drift).

Booklet-derived tests: `src/game/__tests__/bookletRules.test.ts`, plus
`bidding.test.ts`, `handScoring.test.ts`, `dealAfterDoubling.test.ts`.

**p.22–23 خرافات are free negative tests.** Each myth is a thing the engine
must *not* do (e.g. «الكبوت المقلوب يُسجَّل 88» — it is 44 either way; «المية
المتشابهة أكبر من المتسلسلة» — sequence beats same-rank). Worth mining.

## 5. Not yet mirrored in Python

`ml/baloot_engine/` is a separate port used for bot training and is **behind**
the TS engine (see the end of `docs/baloot-rules-audit.md`). Aligning the
Python side to this booklet is outstanding work — mirror it before any new
training run.

## 6. Compiling it (optional)

The `.tex` is the source of truth as *text* — you do not need to build it to
read it. To produce the PDF:

```bash
xelatex docs/baloot-rules-booklet.tex   # run twice for table widths
```

Requires XeLaTeX with `polyglossia` + `bidi` and the **Amiri** Arabic font.
Neither the app build nor CI touches this file.