Mhamed Halhoul
All projects

Case file 02 Rules as evidence

Hujja

Pre-alpha · contract implementation

An open-source rules-as-code project for Shariah stock screening, designed to preserve per-standard verdicts, source references, and visible uncertainty.

View repository
01

Overview

A verdict should expose the rule that produced it.

Hujja is being developed around a narrow problem: stock-screening standards differ in thresholds, denominators, averaging windows, and activity rules. Collapsing them into one opaque answer hides those differences.

The project instead models rules as versioned, auditable definitions and targets one verdict per standard, with the relevant facts, rule identifiers, review status, and source evidence kept alongside the outcome.

02

Model

Separate standards. Explicit uncertainty.

  • Compliant
  • Non-compliant
  • Doubtful

DOUBTFUL is modeled as a first-class status for ambiguous or mixed cases that require qualified human review—not as a hidden failure.

03

Published state

The contract layer comes first.

The current repository is pre-alpha. It publishes a versioned DJIM rule definition, JSON Schema, fact modeling, and validation. The loader and screening execution engine are not yet implemented.

Published

Definitions and contracts

Schema, rule structure, fact model, validation, and evidence-oriented output design.

Not yet implemented

Loader and execution

The repository does not yet provide a working end-to-end stock-screening engine.

04

Design principles

Auditability is a data-model concern.

  1. 01

    One verdict per standard

    Different methodologies remain separate rather than being merged into a single answer.

  2. 02

    Rules carry provenance

    Definitions are versioned and linked to the official source material they encode.

  3. 03

    Review status stays visible

    Unreviewed rules remain labeled as such in the target output.

  4. 04

    Public-domain inputs

    The project’s stated data policy centers on SEC EDGAR/XBRL and excludes licensed market-data feeds from the repository.

05

Boundaries

Important Informational software

Not a fatwa. Not investment advice.

Hujja is presented for informational and educational purposes. It does not issue religious rulings and does not provide investment, legal, accounting, or tax advice. It does not make personalized recommendations.

Any screening result depends on the encoded methodology and the accuracy and timeliness of public filings. Decisions require qualified professional guidance.

06

Current tools

Technologies in the pre-alpha repository.

  • PythonCore language
  • JSON SchemaRule contracts
  • DataclassesFact modeling
  • Validation suiteContract checks
  • Versioned JSONRule definitions
  • Apache-2.0License