HTTP API

The server runs on Cloudflare Workers and is available at https://faraid-server.siddiqmutarjim.workers.dev/.

Run locally: pnpm --filter @faraid/server dev → http://localhost:8787

Interactive docs (Scalar UI): GET /docs
OpenAPI spec: GET /openapi.json

Core computation

`POST /solve`

Standard flat inheritance computation.

curl -X POST /solve \
  -H 'content-type: application/json' \
  -d '{
    "heirs": [
      { "type": "Husband",  "count": 1 },
      { "type": "Daughter", "count": 2 },
      { "type": "Mother",   "count": 1 }
    ],
    "config": { "useDelta": true }
  }'

Request: SolveSchema

{
  heirs:   HeirInput[]       // min 1
  config?: MadhhabConfig     // optional; default SHAFII
}

Response 200: SolverResult

{
  base:      string           // BigInt as string (asl al-mas'ala)
  shares:    AnnotatedShare[]
  excluded:  ExcludedHeirInfo[]
  phenomena: string[]         // named math phenomena that fired
  config?:   MadhhabConfig
}

Response 422: validation error

`POST /explain`

Same as /solve but includes a full per-phase trace for debugging and shabaka (inheritance table) generation.

Response 200: ExplainResult — extends SolverResult with:

{
  trace: {
    phase0: { excluded, survivors }
    phase1: { hasDescendant, hasMaleDescendant, ... }
    phase2: { blocked, survivors }
    phase3: { assignments }
    phase4: { method, fardSum }
    phase5: { base, asl }
    shabaka: { originalBase, finalBase, rows }
  }
}

Chain of deaths (Munāsakhat)

`POST /chain`

Flat Munāsakhat: manually specify each heir set per death step.

{
  "primaryHeirs": [{ "type": "Son", "count": 2 }, { "type": "Wife", "count": 1 }],
  "deaths": [
    {
      "dying": "Son",
      "heirs": [{ "type": "Son", "count": 1 }, { "type": "Wife", "count": 1 }]
    }
  ]
}

`POST /chain/dag`

Recommended. DAG-based Munāsakhat with automatic heir re-expression.

The engine automatically re-expresses each heir’s kinship vector relative to each sub-deceased — e.g. John’s brothers become “Sons” relative to John’s mother. No manual translation needed.

{
  "spec": {
    "dag": {
      "nodes": [
        { "id": "Ahmad", "gender": 1 },
        { "id": "Zayd",  "gender": 1 },
        { "id": "Hind",  "gender": 0 }
      ],
      "edges": [
        { "from": "Ahmad", "to": "Zayd" },
        { "from": "Ahmad", "to": "Hind" }
      ],
      "deceased": "Ahmad"
    },
    "spouses": [{ "id": "Maryam", "gender": 0 }]
  },
  "deceasedSequence": ["Ahmad", "Zayd"],
  "includeTable": true
}

Optional flags:

includeTable: true — returns structured MunasakhatGrid for the classical hanging table
includeHtml: true — returns a self-contained CSS Grid HTML fragment

Missing heir (Mafqūd)

`POST /mafqud`

Computes guaranteed minimum shares when one or more heirs’ status (alive/dead) is unknown. Evaluates all 2ⁿ scenarios; assigns each known heir their minimum; holds the remainder in suspension (mawqūf).

{
  "heirs":   [{ "type": "Mother", "count": 1 }, { "type": "Son", "count": 1 }],
  "missing": ["Son"],
  "config":  {}
}

Response 200:

{
  base:      string     // common base across all scenarios
  heirs:     MafqudAnnotatedHeir[]
  suspended: string     // mawqūf fraction
  scenarios: number     // 2^n
}

Dhawī al-Arḥām

`POST /dha`

Extended relatives (heirs whose chain of eligibility passes through a female intermediary, c=0). Method (Tanzīl or Qarāba) determined by config.dharhamMethod.

{
  "dhaHeirs": [{ "type": "Grandson", "count": 1 }],
  "spouse":   { "type": "Wife", "count": 1 },
  "config":   { "dharhamMethod": "tanzil" }
}

Questionnaire (interactive heir identification)

`POST /questionnaire`

Start a new elimination session. Returns initial state.

{ "deceasedGender": 1, "config": {} }

`POST /questionnaire/advance`

Record one yes/no answer and return updated state. Repeat until state.done === true, then use state.finalHeirs with /solve.

{
  "state":    "<opaque state from previous response>",
  "heirType": "Son",
  "isPresent": true
}

`POST /questionnaire/count/start`

Begin count adjudication for confirmed heir types (e.g. after questionnaire completion).

`POST /questionnaire/count/advance`

Record count for state.nextType. Validates against Islamic count constraints (Wife max=4, Husband=1, etc.).

System

`GET /health`

Returns { "status": "ok" } with HTTP 200.

`GET /openapi.json`

Full OpenAPI 3 spec auto-generated from route handlers and @faraid/domain Zod schemas.

`GET /docs`

Scalar interactive API explorer.

MadhhabConfig

All endpoints accept an optional config object. All fields are optional; defaults correspond to the Shāfiʿī school.

interface MadhhabConfig {
  // Original 6 fields
  useDelta:                  boolean  // default: true (Jumhūr/Shāfiʿī)
  grandfatherEqualsFather:   boolean  // default: false (PATH_B)
  grandmotherImmuneToFather: boolean  // default: false
  spouseParticipatesInRadd:  boolean  // default: false
  dharhamMethod:             'tanzil' | 'qaraba'              // default: 'tanzil'
  awlMethod:                 'proportional' | 'ibn_abbas_priority' // default: 'proportional'

  // D16–D18 extension toggles (findings/10)
  hamlScenarioSet?:          'jumhur_6' | 'hanafi_2'
  khunthaAggregation?:       'shafii_min' | 'maliki_mean' | 'hanafi_pick' | 'hanbali_split'
  gharqaMutualInheritance?:  boolean
}

Presets: SHAFII, HANAFI, HANBALI, MALIKI — all exported from @faraid/domain.

HeirType enum

All 27 recognized heir types:

type HeirType =
  // Spouses
  | 'Husband' | 'Wife'
  // Descendants d=1
  | 'Son' | 'Daughter'
  // Descendants d=2
  | 'Grandson' | 'Granddaughter'
  // Ascendants d=1
  | 'Father' | 'Mother'
  // Ascendants d=2
  | 'GrandfatherPaternal' | 'GrandmotherPaternal' | 'GrandmotherMaternal'
  // Siblings (q=1 Full, q=2 Paternal, q=3 Maternal)
  | 'BrotherFull' | 'SisterFull'
  | 'BrotherPaternal' | 'SisterPaternal'
  | 'BrotherMaternal' | 'SisterMaternal'
  // Nephews
  | 'NephewFull' | 'NephewPaternal'
  // Uncles
  | 'UnclePaternalFull' | 'UnclePaternal'
  // Cousins
  | 'CousinFull' | 'CousinPaternal'
  // Extended
  | 'PaternalCousinsGrandson'
  // Walā (patronage)
  | 'WalaPatron'