Diagnostics reference

When a spec violates a rule, the engine raises a coded diagnostic with a message and a citation. An error blocks codegen — no contract is emitted; a warning is advisory. Citations are flagged for scholarly verification ([scholar-verify]), never asserted as fatwa.

Diagnostic shape

Every diagnostic is the same structure, emitted as JSON by --json (or pretty-printed otherwise):

{
  "severity": "error",            // error → blocks codegen (exit 1); warning → advisory
  "code": "RIBA-1",
  "message": "capital_guarantee returns capital whole regardless of outcome — riba.",
  "citation": "al-Baqarah 2:275 · AAOIFI SS No. 12   [scholar-verify]",
  "span": { "start": 412, "end": 437, "line": 38, "col": 5 }
}

span is the byte range (and resolved line/col) of the offending token — the LSP underlines exactly that, not the whole block. Codes are stable identifiers; the prose message may evolve.

$ deducible check specs/riba_disguised.fiqh
✗ RIBA-1   38:5   capital_guarantee … — riba.   al-Baqarah 2:275 · AAOIFI SS No. 12
✗ RISK-1   37:5   loss must follow ownership.   al-ghunm bi-l-ghurm
✗ GHARAR-1 31:7   valuation source unspecified (majhūl).
   3 errors · no contract emitted
$ echo $?
1

Core (riba, risk, gharar)

Code	Principle	Citation
`RIBA-1`	A guaranteed return of capital regardless of outcome is riba.	al-Baqarah 2:275 · AAOIFI SS No. 12
`RIBA-2`	A fixed, risk-free increase on the financed amount is riba.	al-Baqarah 2:275
`RISK-1`	Loss must follow ownership (al-ghunm bi-l-ghurm).	AAOIFI SS No. 12
`GHARAR-1`	The valuation source is unspecified (majhūl).	Ṣaḥīḥ Muslim (sale of gharar)
`INV-1`	A required invariant for this instrument is missing.	rule-base

Oracle / consensus

Code	Meaning
`ORACLE-1`	`quorum` must be ≤ `committee`.
`ORACLE-2…5`	`gharar_bound_bps` must be in (0, 10000); committee/quorum well-formed.

Composition (composite contracts)

Code	Meaning	Citation
`INAH-1`	bayʿ al-ʿīnah: 2-cycle returning the asset to origin with a deferred differential.	Abū Dāwūd (ʿīnah)
`INAH-2`	organized tawarruq: ≥3-cycle ring back to the financier.	OIC Res. 179 (19/5), 2009
`INAH-3`	round-trip with no net transfer (warning).	AAOIFI SS No. 30

Charge (zakat)

Code	Meaning	Citation
`ZAKAT-1`	Rate must equal 250 bps (1/40).	al-Tawbah 9:103
`ZAKAT-2`	ḥawl must be lunar (ḥijrī).	Abū Dāwūd (Samurah b. Jundub)
`ZAKAT-3`	niṣāb must be positive.	AAOIFI SS No. 35
`ZAKAT-4`	Beneficiary must resolve to a party.	—

Contingency (jawa’ih, faraid)

Code	Meaning	Citation
`CONT-1`	jāʾiḥah must abate, not defer (no penalty).	waḍʿ al-jawāʾiḥ
`CONT-2`	Death triggers farāʾiḍ, not discretion.	al-Nisāʾ 4:11–12, 176
`CONT-3`	farāʾiḍ dissolution requires an arbiter.	—

Capacity (ahliyyah — gateway)

Code	Meaning
`AHL-MINOR`	Party lacks bulūgh / capacity.
`AHL-SAFIH`	Party under interdiction (ḥajr on the prodigal).
`AHL-TAFLIS`	Party is bankrupt.
`AHL-KYC` / `AHL-AML`	Statutory identity / sanctions failure.

Common-law regime

Code	Doctrine	Authority
`CONSID-1`	Consideration must be present.	Currie v Misa (1875)
`CERTAINTY-1/2`	Terms must be certain.	Scammell v Ouston (1941)
`PENALTY-1`	No penalty clause (genuine pre-estimate only).	Cavendish v Makdessi (2015)
`DISPUTE-1`	A dispute-resolution remedy is required.	—
`REGIME-1`	Class/regime mismatch.	—