rasad-sim 0.1.0__tar.gz

rasad_sim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Aly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rasad_sim-0.1.0/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: rasad-sim
+Version: 0.1.0
+Summary: Measure how much of a stochastic simulation's result is a property of the model and how much is the random seed.
+Author: Ahmed Aly
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ahmedaly0904-bit64/rasad
+Project-URL: Source, https://github.com/ahmedaly0904-bit64/rasad
+Project-URL: Issues, https://github.com/ahmedaly0904-bit64/rasad/issues
+Keywords: simulation,reproducibility,agent-based-modeling,uncertainty-quantification,monte-carlo,sensitivity-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: plotly>=5.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: mesa>=3.5; extra == "examples"
+Requires-Dist: networkx>=3.0; extra == "examples"
+Requires-Dist: pandas>=2.0; extra == "examples"
+Requires-Dist: simpy>=4.1; extra == "examples"
+Dynamic: license-file
+
+# Rasad · رَصَد
+
+**Measure how much of your simulation's result is a property of the model, and how much is the random seed.**
+
+Stochastic simulations are usually reported without error bars. A paper says *"the civilisation
+collapsed in year 240"* and never answers two questions:
+
+1. If the random seed changes, is it still year 240?
+2. Is this a property of the model, or an accident of one run?
+
+Rasad answers both by measurement.
+
+---
+
+## Why this exists
+
+This tool was not designed in the abstract. It was built because another project needed it.
+
+**Omran** is a simulation of Ibn Khaldun's theory of *asabiyyah*. Ibn Khaldun (1332–1406) was
+a historian who argued in the *Muqaddimah* that civilisations rise and fall on a single
+force: **asabiyyah**, the cohesion that lets a group act as one. A group with strong
+cohesion overtakes a settled, comfortable one; then comfort erodes its own cohesion over
+generations, and it is overtaken in turn. The cycle repeats. He called the study of this
+*ʿilm al-ʿumran* — the science of human social organisation — which is where the project
+takes its name.
+
+Omran models that computationally: nations on a grid, populations that grow and starve,
+ideas that spread between neighbours like an infection, wars along contested borders. Run it
+and you get numbers — a final population, a count of wars, a year the collapse happened.
+
+The problem was that nobody knew whether those numbers meant anything.
+
+Change the random seed and they change. Was a collapse in year 240 a property of the model,
+or an accident of one run? There was no way to answer without measuring, and no tool that
+measured it — the frameworks that do sensitivity analysis are built for engineering and
+physics models, and the agent-based modelling field is repeatedly criticised for publishing
+results without error bars.
+
+So Rasad was written to answer that question, under one hard constraint: **it must not touch
+Omran.** It observes from the outside and modifies nothing, the way an instrument measures a
+specimen without altering it. That constraint shaped the architecture — and it is why Rasad
+works on any simulation, not just the one it was written for.
+
+What it found is in [`FINDINGS.md`](FINDINGS.md), and it was not what anyone expected.
+
+---
+
+## Install
+
+```bash
+pip install rasad-sim
+```
+
+The distribution is `rasad-sim` because `rasad` collides with an existing name on
+PyPI. The import is unaffected:
+
+```python
+import rasad
+```
+
+Python 3.12+ · numpy · plotly
+
+## Use
+
+Describe your simulation as one function:
+
+```python
+def run(params: dict, seed: int) -> dict:
+    """One run. A number is a final result; a list of numbers is a time series."""
+    ...
+```
+
+Then:
+
+```python
+import rasad
+
+report = rasad.measure(run, params={"growth": 0.03}, runs=100)
+print(report.summary())
+report.plot().write_html("divergence.html")
+```
+
+You get, for every output: mean, standard deviation, a 90% interval, and a variability class —
+**low**, **moderate**, or **high** — plus a curve showing how far the runs drift
+apart over time.
+
+---
+
+## What it found in practice
+
+### A simulation that could not reproduce itself
+
+Applied to [Omran](https://github.com/ahmedaly0904-bit64/Omran), an agent-based model of
+Ibn Khaldun's theory of *asabiyyah*, **without modifying a line of it**:
+
+```
+final_total_population: mean 4,649.39 | cv 0.2841 | p05-p95 [2,704.75, 6,774.30] | high
+survivors:              mean 1.14     | cv 0.3059 | p05-p95 [1.00, 2.00]        | high
+total_wars:             mean 13.44    | cv 0.3986 | p05-p95 [6.00, 22.10]       | high
+total_famines:          mean 0.00     | cv 0.0000 | p05-p95 [0.00, 0.00]        | low
+```
+
+No numeric output of the model had low variability. Worse, the measurement exposed something the author
+did not know: **the same seed produced different results in different processes.**
+
+Six runs with seed `1`, thirty simulated years:
+
+```
+1428 · 1428 · 1512 · 1426 · 1426 · 1512
+```
+
+Comparing the population curve year by year located the split: the runs are **identical for
+nineteen years**, then diverge at year twenty by **one individual** — which becomes hundreds
+by year one hundred. That is error propagation, measured.
+
+This was then confirmed with Rasad out of the path entirely: Omran's own `main.py` carries a
+hard-coded `random.seed(42)`, and running that file directly eight times gave **four distinct
+results**.
+
+Full write-up: [`FINDINGS.md`](FINDINGS.md)
+
+### Aggregates can be stable while their parts are noise
+
+On a [SimPy](https://simpy.readthedocs.io) machine-shop simulation
+([`examples/simpy_machine_shop.py`](examples/simpy_machine_shop.py)):
+
+| Output | cv | Verdict |
+|---|---|---|
+| total parts produced | 0.014 | **low** |
+| best machine · worst machine | 0.017 | **low** |
+| **gap between best and worst** | **0.31** | **high** |
+
+The shop's total output is stable. The gap between machines is pure noise. Anyone looking at
+one run and saying *"machine 7 is underperforming, investigate it"* is chasing a random seed.
+
+**Averages hide fragility.** That alone is a reason to measure what you publish.
+
+---
+
+## Verified against simulations it was not written for
+
+| Framework | Models | Result |
+|---|---|---|
+| [Mesa](https://github.com/projectmesa/mesa) | Schelling, WolfSheep, Boltzmann | works; WolfSheep's sheep population has high variability (cv 2.95 — usually extinct, occasionally not) |
+| [SimPy](https://simpy.readthedocs.io) | machine shop | works; see above |
+| [EoN](https://epidemicsonnetworks.readthedocs.io) | SIR on a network | works; epidemic duration has high variability (7.5 → 14.7) |
+| [Omran](https://github.com/ahmedaly0904-bit64/Omran) | asabiyyah model | works; see above |
+
+Examples: [`examples/`](examples/)
+
+A control worth stating: the SimPy and Mesa examples reproduce byte-identically across
+separate processes. That establishes that Omran's non-reproducibility is a bug in Omran,
+and that Rasad's own pipeline is deterministic.
+
+---
+
+## The class is a convention. The numbers are the result.
+
+The default cutoffs — 0.05 and 0.20 — **are a choice, not a theory**. An output at cv 0.21
+reads *high*; raise the cutoff to 0.25 and the same data reads *moderate*.
+
+So every report prints the thresholds it used and labels them as a convention:
+
+```
+thresholds (a convention, not a rule): low < 0.0500 <= moderate <= 0.2000 < high
+```
+
+And they belong to the caller:
+
+```python
+rasad.measure(run, params={}, runs=100,
+              thresholds={"low": 0.01, "moderate": 0.05})
+```
+
+**The real result is the interval.** `p05-p95 [7.46, 14.74]` says the duration may double,
+without needing a word on top of it.
+
+---
+
+## Limitations
+
+- **Only the seed varies.** Parameters are held fixed, so *"which parameter drives the
+  result?"* is not answered yet. Sensitivity analysis is the next version.
+- **Execution is sequential.** No parallelism.
+- **One value per output name per run.** A model whose keys change between runs is rejected.
+
+Accepted outputs: Python numbers, numpy scalars, 1-D numeric numpy arrays, lists and tuples.
+**Booleans are always rejected** — alone or inside a list — because an average of ones and
+zeros means nothing.
+
+---
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest tests -v
+```
+
+73 tests · 97% line coverage · 357 of 452 mutants killed · linted with ruff
+
+The coverage figure is the weakest of the three. Mutation testing is what showed why:
+`validate_thresholds` was fully covered and still accepted two equal cutoffs, because
+no test passed the one input that separates `<` from `<=`.
+
+The statistics are tested against models whose answers are known analytically: a constant
+must give a standard deviation of exactly zero; a random walk's divergence must grow as the
+square root of time. Those tests caught real bugs — including a collapsed axis that would
+have produced plausible, meaningless numbers.
+
+## Notes on the implementation
+
+Three analyses of the code, in Arabic:
+
+- [فئات المدخلات](docs/input-classes.md) — the five input classes `summarize()` actually
+  distinguishes, each with the test that covers it, and why branch order decides which class
+  a list falls into.
+- [كم تشغيلة تكفي؟](docs/how-many-runs.md) — the standard error of the mean applied to Omran:
+  100 runs pin the mean to 2.8%, and reaching 1% costs 784.
+- [حدود الوحدات](docs/module-boundaries.md) — the deletion test applied to each of Rasad's own
+  modules, separating splits forced by something that happened from splits made on a guess.
+
+---
+
+## بالعربية
+
+**رَصَد** أداة تقيس صلابة نتائج المحاكاة: أيُّ المخرجات خاصيةٌ في النموذج، وأيُّها أثرٌ للبذرة العشوائية.
+
+تُنشر نتائج المحاكاة العشوائية غالبًا بلا حدود خطأ. يُقال «انهارت الحضارة في السنة ٢٤٠» دون
+الإجابة على سؤالين: هل يظل الرقم ٢٤٠ لو تغيّرت البذرة؟ وهل هذه خاصية في النموذج أم صدفة في
+تشغيلة واحدة؟ يجيب رَصَد عنهما بالقياس لا بالتقدير.
+
+يوصّف المستخدم محاكاته بدالةٍ واحدة تستقبل المعاملات والبذرة وترجّع قاموس مخرجات. يشغّلها
+رَصَد مرارًا ببذورٍ مختلفة، ثم يعرض لكل مخرَج متوسطه وانحرافه ومدى تسعين بالمئة وتصنيفًا لتغايره —
+**low** أو **moderate** أو **high** — مع منحنى يبيّن اتساع التباعد بين التشغيلات عبر الزمن.
+
+طُبِّق على أربعة مشاريع لم يُكتب لأجلها، فكشف في أحدها — محاكاة لنظرية العصبية عند ابن خلدون —
+أنها **لا تعيد إنتاج نتائجها بالبذرة نفسها**: تشغيلتان متطابقتان تفترقان عند السنة العشرين
+بفارق فردٍ واحد، يصير مئاتٍ بحلول السنة المئة. وهذا انتشار الخطأ في صورته المقيسة.
+
+### لماذا كُتب
+
+لم تُصمَّم هذه الأداة في الفراغ، بل كُتبت لأن مشروعًا آخر احتاجها.
+
+**عُمران** محاكاةٌ لنظرية العصبية عند ابن خلدون (١٣٣٢–١٤٠٦)، الذي رأى في *المقدمة* أن الحضارات
+تنهض وتسقط بقوةٍ واحدة: **العصبية**، أي التماسك الذي يجعل الجماعة تفعل كأنها واحد. جماعةٌ
+عصبيتها قوية تغلب جماعةً مستقرةً مترفة، ثم يُفسد الترف عصبيتها هي عبر الأجيال، فتُغلَب بدورها.
+وسمّى ابن خلدون دراسة ذلك **علم العمران**، ومنه أخذ المشروع اسمه.
+
+يحاكي عُمران هذا حاسوبيًّا: دولٌ على شبكة، وسكانٌ ينمون ويجوعون، وأفكارٌ تنتقل بين الجيران
+كالعدوى، وحروبٌ على الحدود المتنازعة. تشغّله فتخرج لك أرقام — سكانٌ في النهاية، وعدد حروب،
+وسنةٌ وقع فيها الانهيار.
+
+والمشكلة أن أحدًا لم يكن يعرف: هل لهذه الأرقام معنى؟ غيّر البذرة العشوائية تتغيّر. فهل الانهيار
+في السنة ٢٤٠ خاصيةٌ في النموذج أم صدفةُ تشغيلةٍ واحدة؟ لا سبيل إلى الجواب إلا بالقياس، ولم تكن
+هناك أداةٌ تقيسه.
+
+فكُتب رَصَد لهذا السؤال، بقيدٍ واحدٍ صارم: **ألّا يمسّ عُمران**. يراقبه من خارجه ولا يعدّل فيه
+حرفًا، كما يقيس المِجهر عيّنةً دون أن يغيّرها. وهذا القيد هو الذي شكّل بنية الأداة — وهو سبب
+عملها على أي محاكاة، لا على التي كُتبت لأجلها وحدها.
+
+### التصنيف
+
+وحدود التصنيف الافتراضية اصطلاحٌ لا قاعدة، ولذلك يعلنها كل تقرير ويتركها بيد المستخدم.
+**النتيجة الحقيقية هي المدى**، لا التصنيف الذي يعلوه.
+
+---
+
+## How this was built — full disclosure
+
+Most of the code here was written by AI models under explicit delegation and human review.
+
+| Stage | Owner |
+|---|---|
+| Specification and architecture | Ahmed, in dialogue with Claude (Opus 5) |
+| **Test authoring** | Written into each task brief **before** implementation; the implementer was forbidden from altering a character |
+| Implementation | DeepSeek V4 Flash, via `opencode` + AgentRouter — seven tasks |
+| Review gates | Claude (Opus 5): every diff read, tests run independently of the implementer's claim |
+| Decisions and merges | Ahmed — every commit after review |
+
+**The ordering is what matters, not the tooling: the tests came first and were the
+specification.** The model was never asked to write code and then write the thing that proves
+it correct. It was given a written contract and held to it.
+
+What the gates actually caught: a dead condition in a type check, a deprecated import, a
+missing return annotation, unreadable number formatting. **No logic error got through** —
+credit to the tests, not to the model.
+
+And what none of them caught: an output that was constantly zero was classified as *high* variability
+when it was the most stable number in the report. Neither the reference models nor the review
+found it — **the real data did, on the first run against Omran.**
+
+That is the boundary. Tests prove the arithmetic is right; only real data reveals the case
+nobody thought to write a test for.
+
+---
+
+## License
+
+MIT

rasad_sim-0.1.0/README.md

@@ -0,0 +1,301 @@
+# Rasad · رَصَد
+
+**Measure how much of your simulation's result is a property of the model, and how much is the random seed.**
+
+Stochastic simulations are usually reported without error bars. A paper says *"the civilisation
+collapsed in year 240"* and never answers two questions:
+
+1. If the random seed changes, is it still year 240?
+2. Is this a property of the model, or an accident of one run?
+
+Rasad answers both by measurement.
+
+---
+
+## Why this exists
+
+This tool was not designed in the abstract. It was built because another project needed it.
+
+**Omran** is a simulation of Ibn Khaldun's theory of *asabiyyah*. Ibn Khaldun (1332–1406) was
+a historian who argued in the *Muqaddimah* that civilisations rise and fall on a single
+force: **asabiyyah**, the cohesion that lets a group act as one. A group with strong
+cohesion overtakes a settled, comfortable one; then comfort erodes its own cohesion over
+generations, and it is overtaken in turn. The cycle repeats. He called the study of this
+*ʿilm al-ʿumran* — the science of human social organisation — which is where the project
+takes its name.
+
+Omran models that computationally: nations on a grid, populations that grow and starve,
+ideas that spread between neighbours like an infection, wars along contested borders. Run it
+and you get numbers — a final population, a count of wars, a year the collapse happened.
+
+The problem was that nobody knew whether those numbers meant anything.
+
+Change the random seed and they change. Was a collapse in year 240 a property of the model,
+or an accident of one run? There was no way to answer without measuring, and no tool that
+measured it — the frameworks that do sensitivity analysis are built for engineering and
+physics models, and the agent-based modelling field is repeatedly criticised for publishing
+results without error bars.
+
+So Rasad was written to answer that question, under one hard constraint: **it must not touch
+Omran.** It observes from the outside and modifies nothing, the way an instrument measures a
+specimen without altering it. That constraint shaped the architecture — and it is why Rasad
+works on any simulation, not just the one it was written for.
+
+What it found is in [`FINDINGS.md`](FINDINGS.md), and it was not what anyone expected.
+
+---
+
+## Install
+
+```bash
+pip install rasad-sim
+```
+
+The distribution is `rasad-sim` because `rasad` collides with an existing name on
+PyPI. The import is unaffected:
+
+```python
+import rasad
+```
+
+Python 3.12+ · numpy · plotly
+
+## Use
+
+Describe your simulation as one function:
+
+```python
+def run(params: dict, seed: int) -> dict:
+    """One run. A number is a final result; a list of numbers is a time series."""
+    ...
+```
+
+Then:
+
+```python
+import rasad
+
+report = rasad.measure(run, params={"growth": 0.03}, runs=100)
+print(report.summary())
+report.plot().write_html("divergence.html")
+```
+
+You get, for every output: mean, standard deviation, a 90% interval, and a variability class —
+**low**, **moderate**, or **high** — plus a curve showing how far the runs drift
+apart over time.
+
+---
+
+## What it found in practice
+
+### A simulation that could not reproduce itself
+
+Applied to [Omran](https://github.com/ahmedaly0904-bit64/Omran), an agent-based model of
+Ibn Khaldun's theory of *asabiyyah*, **without modifying a line of it**:
+
+```
+final_total_population: mean 4,649.39 | cv 0.2841 | p05-p95 [2,704.75, 6,774.30] | high
+survivors:              mean 1.14     | cv 0.3059 | p05-p95 [1.00, 2.00]        | high
+total_wars:             mean 13.44    | cv 0.3986 | p05-p95 [6.00, 22.10]       | high
+total_famines:          mean 0.00     | cv 0.0000 | p05-p95 [0.00, 0.00]        | low
+```
+
+No numeric output of the model had low variability. Worse, the measurement exposed something the author
+did not know: **the same seed produced different results in different processes.**
+
+Six runs with seed `1`, thirty simulated years:
+
+```
+1428 · 1428 · 1512 · 1426 · 1426 · 1512
+```
+
+Comparing the population curve year by year located the split: the runs are **identical for
+nineteen years**, then diverge at year twenty by **one individual** — which becomes hundreds
+by year one hundred. That is error propagation, measured.
+
+This was then confirmed with Rasad out of the path entirely: Omran's own `main.py` carries a
+hard-coded `random.seed(42)`, and running that file directly eight times gave **four distinct
+results**.
+
+Full write-up: [`FINDINGS.md`](FINDINGS.md)
+
+### Aggregates can be stable while their parts are noise
+
+On a [SimPy](https://simpy.readthedocs.io) machine-shop simulation
+([`examples/simpy_machine_shop.py`](examples/simpy_machine_shop.py)):
+
+| Output | cv | Verdict |
+|---|---|---|
+| total parts produced | 0.014 | **low** |
+| best machine · worst machine | 0.017 | **low** |
+| **gap between best and worst** | **0.31** | **high** |
+
+The shop's total output is stable. The gap between machines is pure noise. Anyone looking at
+one run and saying *"machine 7 is underperforming, investigate it"* is chasing a random seed.
+
+**Averages hide fragility.** That alone is a reason to measure what you publish.
+
+---
+
+## Verified against simulations it was not written for
+
+| Framework | Models | Result |
+|---|---|---|
+| [Mesa](https://github.com/projectmesa/mesa) | Schelling, WolfSheep, Boltzmann | works; WolfSheep's sheep population has high variability (cv 2.95 — usually extinct, occasionally not) |
+| [SimPy](https://simpy.readthedocs.io) | machine shop | works; see above |
+| [EoN](https://epidemicsonnetworks.readthedocs.io) | SIR on a network | works; epidemic duration has high variability (7.5 → 14.7) |
+| [Omran](https://github.com/ahmedaly0904-bit64/Omran) | asabiyyah model | works; see above |
+
+Examples: [`examples/`](examples/)
+
+A control worth stating: the SimPy and Mesa examples reproduce byte-identically across
+separate processes. That establishes that Omran's non-reproducibility is a bug in Omran,
+and that Rasad's own pipeline is deterministic.
+
+---
+
+## The class is a convention. The numbers are the result.
+
+The default cutoffs — 0.05 and 0.20 — **are a choice, not a theory**. An output at cv 0.21
+reads *high*; raise the cutoff to 0.25 and the same data reads *moderate*.
+
+So every report prints the thresholds it used and labels them as a convention:
+
+```
+thresholds (a convention, not a rule): low < 0.0500 <= moderate <= 0.2000 < high
+```
+
+And they belong to the caller:
+
+```python
+rasad.measure(run, params={}, runs=100,
+              thresholds={"low": 0.01, "moderate": 0.05})
+```
+
+**The real result is the interval.** `p05-p95 [7.46, 14.74]` says the duration may double,
+without needing a word on top of it.
+
+---
+
+## Limitations
+
+- **Only the seed varies.** Parameters are held fixed, so *"which parameter drives the
+  result?"* is not answered yet. Sensitivity analysis is the next version.
+- **Execution is sequential.** No parallelism.
+- **One value per output name per run.** A model whose keys change between runs is rejected.
+
+Accepted outputs: Python numbers, numpy scalars, 1-D numeric numpy arrays, lists and tuples.
+**Booleans are always rejected** — alone or inside a list — because an average of ones and
+zeros means nothing.
+
+---
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest tests -v
+```
+
+73 tests · 97% line coverage · 357 of 452 mutants killed · linted with ruff
+
+The coverage figure is the weakest of the three. Mutation testing is what showed why:
+`validate_thresholds` was fully covered and still accepted two equal cutoffs, because
+no test passed the one input that separates `<` from `<=`.
+
+The statistics are tested against models whose answers are known analytically: a constant
+must give a standard deviation of exactly zero; a random walk's divergence must grow as the
+square root of time. Those tests caught real bugs — including a collapsed axis that would
+have produced plausible, meaningless numbers.
+
+## Notes on the implementation
+
+Three analyses of the code, in Arabic:
+
+- [فئات المدخلات](docs/input-classes.md) — the five input classes `summarize()` actually
+  distinguishes, each with the test that covers it, and why branch order decides which class
+  a list falls into.
+- [كم تشغيلة تكفي؟](docs/how-many-runs.md) — the standard error of the mean applied to Omran:
+  100 runs pin the mean to 2.8%, and reaching 1% costs 784.
+- [حدود الوحدات](docs/module-boundaries.md) — the deletion test applied to each of Rasad's own
+  modules, separating splits forced by something that happened from splits made on a guess.
+
+---
+
+## بالعربية
+
+**رَصَد** أداة تقيس صلابة نتائج المحاكاة: أيُّ المخرجات خاصيةٌ في النموذج، وأيُّها أثرٌ للبذرة العشوائية.
+
+تُنشر نتائج المحاكاة العشوائية غالبًا بلا حدود خطأ. يُقال «انهارت الحضارة في السنة ٢٤٠» دون
+الإجابة على سؤالين: هل يظل الرقم ٢٤٠ لو تغيّرت البذرة؟ وهل هذه خاصية في النموذج أم صدفة في
+تشغيلة واحدة؟ يجيب رَصَد عنهما بالقياس لا بالتقدير.
+
+يوصّف المستخدم محاكاته بدالةٍ واحدة تستقبل المعاملات والبذرة وترجّع قاموس مخرجات. يشغّلها
+رَصَد مرارًا ببذورٍ مختلفة، ثم يعرض لكل مخرَج متوسطه وانحرافه ومدى تسعين بالمئة وتصنيفًا لتغايره —
+**low** أو **moderate** أو **high** — مع منحنى يبيّن اتساع التباعد بين التشغيلات عبر الزمن.
+
+طُبِّق على أربعة مشاريع لم يُكتب لأجلها، فكشف في أحدها — محاكاة لنظرية العصبية عند ابن خلدون —
+أنها **لا تعيد إنتاج نتائجها بالبذرة نفسها**: تشغيلتان متطابقتان تفترقان عند السنة العشرين
+بفارق فردٍ واحد، يصير مئاتٍ بحلول السنة المئة. وهذا انتشار الخطأ في صورته المقيسة.
+
+### لماذا كُتب
+
+لم تُصمَّم هذه الأداة في الفراغ، بل كُتبت لأن مشروعًا آخر احتاجها.
+
+**عُمران** محاكاةٌ لنظرية العصبية عند ابن خلدون (١٣٣٢–١٤٠٦)، الذي رأى في *المقدمة* أن الحضارات
+تنهض وتسقط بقوةٍ واحدة: **العصبية**، أي التماسك الذي يجعل الجماعة تفعل كأنها واحد. جماعةٌ
+عصبيتها قوية تغلب جماعةً مستقرةً مترفة، ثم يُفسد الترف عصبيتها هي عبر الأجيال، فتُغلَب بدورها.
+وسمّى ابن خلدون دراسة ذلك **علم العمران**، ومنه أخذ المشروع اسمه.
+
+يحاكي عُمران هذا حاسوبيًّا: دولٌ على شبكة، وسكانٌ ينمون ويجوعون، وأفكارٌ تنتقل بين الجيران
+كالعدوى، وحروبٌ على الحدود المتنازعة. تشغّله فتخرج لك أرقام — سكانٌ في النهاية، وعدد حروب،
+وسنةٌ وقع فيها الانهيار.
+
+والمشكلة أن أحدًا لم يكن يعرف: هل لهذه الأرقام معنى؟ غيّر البذرة العشوائية تتغيّر. فهل الانهيار
+في السنة ٢٤٠ خاصيةٌ في النموذج أم صدفةُ تشغيلةٍ واحدة؟ لا سبيل إلى الجواب إلا بالقياس، ولم تكن
+هناك أداةٌ تقيسه.
+
+فكُتب رَصَد لهذا السؤال، بقيدٍ واحدٍ صارم: **ألّا يمسّ عُمران**. يراقبه من خارجه ولا يعدّل فيه
+حرفًا، كما يقيس المِجهر عيّنةً دون أن يغيّرها. وهذا القيد هو الذي شكّل بنية الأداة — وهو سبب
+عملها على أي محاكاة، لا على التي كُتبت لأجلها وحدها.
+
+### التصنيف
+
+وحدود التصنيف الافتراضية اصطلاحٌ لا قاعدة، ولذلك يعلنها كل تقرير ويتركها بيد المستخدم.
+**النتيجة الحقيقية هي المدى**، لا التصنيف الذي يعلوه.
+
+---
+
+## How this was built — full disclosure
+
+Most of the code here was written by AI models under explicit delegation and human review.
+
+| Stage | Owner |
+|---|---|
+| Specification and architecture | Ahmed, in dialogue with Claude (Opus 5) |
+| **Test authoring** | Written into each task brief **before** implementation; the implementer was forbidden from altering a character |
+| Implementation | DeepSeek V4 Flash, via `opencode` + AgentRouter — seven tasks |
+| Review gates | Claude (Opus 5): every diff read, tests run independently of the implementer's claim |
+| Decisions and merges | Ahmed — every commit after review |
+
+**The ordering is what matters, not the tooling: the tests came first and were the
+specification.** The model was never asked to write code and then write the thing that proves
+it correct. It was given a written contract and held to it.
+
+What the gates actually caught: a dead condition in a type check, a deprecated import, a
+missing return annotation, unreadable number formatting. **No logic error got through** —
+credit to the tests, not to the model.
+
+And what none of them caught: an output that was constantly zero was classified as *high* variability
+when it was the most stable number in the report. Neither the reference models nor the review
+found it — **the real data did, on the first run against Omran.**
+
+That is the boundary. Tests prove the arithmetic is right; only real data reveals the case
+nobody thought to write a test for.
+
+---
+
+## License
+
+MIT