Sprint 1 : scaffolding complet de Glibredecision
Plateforme de decisions collectives pour Duniter/G1. Backend FastAPI async + PostgreSQL (14 tables, 8 routers, 6 services, moteur de vote avec formule d'inertie WoT/Smith/TechComm). Frontend Nuxt 4 + Nuxt UI v3 + Pinia (9 pages, 5 stores). Infrastructure Docker + Woodpecker CI + Traefik. Documentation technique et utilisateur (15 fichiers). Seed : Licence G1, Engagement Forgeron v2.0.0, 4 protocoles de vote. 30 tests unitaires (formules, mode params, vote nuance) -- tous verts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yvv
137
docs/content/dev/5.formulas.md
Normal file
137
docs/content/dev/5.formulas.md
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: Formules
|
||||
description: Formules mathematiques de seuil WoT, criteres Smith et TechComm
|
||||
---
|
||||
|
||||
# Formules de seuil
|
||||
|
||||
Glibredecision utilise un systeme de formules mathematiques pour determiner les seuils d'adoption des votes. Le mecanisme central est la **formule d'inertie WoT** qui impose une quasi-unanimite en cas de faible participation et converge vers une majorite simple a participation elevee.
|
||||
|
||||
## Formule principale -- Seuil WoT
|
||||
|
||||
$$
|
||||
\text{Result} = C + B^W + \left( M + (1 - M) \cdot \left(1 - \left(\frac{T}{W}\right)^G \right) \right) \cdot \max(0,\; T - C)
|
||||
$$
|
||||
|
||||
### Variables
|
||||
|
||||
| Symbole | Parametre | Description | Defaut |
|
||||
| ------- | ------------------- | ------------------------------------------------ | ------ |
|
||||
| $C$ | `constant_base` | Base constante additive (plancher) | 0.0 |
|
||||
| $B$ | `base_exponent` | Exposant de base. $B^W$ devient negligeable quand $W$ est grand ($0 < B < 1$) | 0.1 |
|
||||
| $W$ | `wot_size` | Taille du corpus des votants eligibles (membres WoT) | -- |
|
||||
| $T$ | `total_votes` | Nombre total de votes exprimes (pour + contre) | -- |
|
||||
| $M$ | `majority_pct / 100`| Ratio de majorite. 0.5 = majorite simple a pleine participation | 50 |
|
||||
| $G$ | `gradient_exponent` | Controle la vitesse de convergence de la super-majorite vers $M$ | 0.2 |
|
||||
|
||||
### Mecanisme d'inertie
|
||||
|
||||
Le coeur de la formule est le facteur d'inertie :
|
||||
|
||||
$$
|
||||
\text{inertia} = M + (1 - M) \cdot \left(1 - \left(\frac{T}{W}\right)^G \right)
|
||||
$$
|
||||
|
||||
- Quand la **participation est faible** ($T \ll W$) : le ratio $T/W$ est petit, $(T/W)^G$ est proche de 0, donc l'inertie tend vers $M + (1-M) = 1$. Il faut quasiment l'unanimite.
|
||||
- Quand la **participation est elevee** ($T \to W$) : le ratio $T/W$ tend vers 1, $(T/W)^G$ tend vers 1, donc l'inertie tend vers $M$. La majorite simple suffit.
|
||||
|
||||
### Exemple de reference
|
||||
|
||||
Avec les parametres `M50 B.1 G.2` et le vote de l'Engagement Forgeron v2.0.0 :
|
||||
|
||||
- $W = 7224$ (membres WoT)
|
||||
- $T = 120$ (97 pour + 23 contre)
|
||||
- Seuil calcule : $94$
|
||||
- Resultat : **adopte** (97 >= 94)
|
||||
|
||||
## Critere Smith (Forgerons)
|
||||
|
||||
$$
|
||||
\text{SmithThreshold} = \lceil \text{SmithWotSize}^S \rceil
|
||||
$$
|
||||
|
||||
Le critere Smith exige un nombre minimum de votes favorables de la part des membres Smith (forgerons) pour que certaines decisions soient valides.
|
||||
|
||||
| Symbole | Parametre | Description | Defaut |
|
||||
| ------- | ---------------- | ---------------------------- | ------ |
|
||||
| $S$ | `smith_exponent` | Exposant pour le critere Smith | null (desactive) |
|
||||
|
||||
Avec un exposant de $S = 0.1$ et 20 forgerons :
|
||||
|
||||
$$
|
||||
\lceil 20^{0.1} \rceil = \lceil 1.35 \rceil = 2
|
||||
$$
|
||||
|
||||
Au minimum 2 votes favorables de forgerons sont requis.
|
||||
|
||||
## Critere TechComm (Comite Technique)
|
||||
|
||||
$$
|
||||
\text{TechCommThreshold} = \lceil \text{CoTecSize}^T \rceil
|
||||
$$
|
||||
|
||||
Le critere TechComm fonctionne de maniere identique au critere Smith mais pour les membres du Comite Technique.
|
||||
|
||||
| Symbole | Parametre | Description | Defaut |
|
||||
| ------- | ------------------- | ------------------------------- | ------ |
|
||||
| $T$ | `techcomm_exponent` | Exposant pour le critere TechComm | null (desactive) |
|
||||
|
||||
Avec un exposant de $T = 0.1$ et 5 membres TechComm :
|
||||
|
||||
$$
|
||||
\lceil 5^{0.1} \rceil = \lceil 1.17 \rceil = 2
|
||||
$$
|
||||
|
||||
Au minimum 2 votes favorables de membres TechComm sont requis.
|
||||
|
||||
## Resultat final
|
||||
|
||||
Un vote est **adopte** si et seulement si les trois conditions sont remplies simultanement :
|
||||
|
||||
1. `votes_for >= seuil_WoT` (formule principale)
|
||||
2. `smith_votes_for >= seuil_Smith` (si critere Smith actif)
|
||||
3. `techcomm_votes_for >= seuil_TechComm` (si critere TechComm actif)
|
||||
|
||||
## Parametres de mode (mode_params)
|
||||
|
||||
Les parametres de formule sont encodes dans une chaine compacte pour faciliter la lecture et le partage. Format : une lettre majuscule suivie d'une valeur numerique.
|
||||
|
||||
| Code | Parametre | Type | Exemple |
|
||||
| ---- | --------------------- | ----- | ------------ |
|
||||
| D | `duration_days` | int | D30 = 30 jours |
|
||||
| M | `majority_pct` | int | M50 = 50% |
|
||||
| B | `base_exponent` | float | B.1 = 0.1 |
|
||||
| G | `gradient_exponent` | float | G.2 = 0.2 |
|
||||
| C | `constant_base` | float | C0 = 0.0 |
|
||||
| S | `smith_exponent` | float | S.1 = 0.1 |
|
||||
| T | `techcomm_exponent` | float | T.1 = 0.1 |
|
||||
| N | `ratio_multiplier` | float | N1.5 = 1.5 |
|
||||
| R | `is_ratio_mode` | bool | R1 = true |
|
||||
|
||||
### Exemples
|
||||
|
||||
- `"D30M50B.1G.2"` -- 30 jours, majorite 50%, base 0.1, gradient 0.2
|
||||
- `"D30M50B.1G.2S.1T.1"` -- Idem avec critere Smith (0.1) et TechComm (0.1)
|
||||
- `"D60M66B.05G.3"` -- 60 jours, majorite 66%, base 0.05, gradient 0.3
|
||||
|
||||
## Vote nuance
|
||||
|
||||
En plus du vote binaire (pour/contre), Glibredecision supporte un vote nuance a 6 niveaux :
|
||||
|
||||
| Niveau | Label |
|
||||
| ------ | ------------- |
|
||||
| 0 | CONTRE |
|
||||
| 1 | PAS DU TOUT |
|
||||
| 2 | PAS D'ACCORD |
|
||||
| 3 | NEUTRE |
|
||||
| 4 | D'ACCORD |
|
||||
| 5 | TOUT A FAIT |
|
||||
|
||||
### Regle d'adoption (vote nuance)
|
||||
|
||||
Un vote nuance est adopte si :
|
||||
|
||||
1. Le nombre de votes aux niveaux 3, 4 et 5 (positifs) represente au moins `threshold_pct`% du total des votes.
|
||||
2. Le nombre minimum de participants (`min_participants`) est atteint.
|
||||
|
||||
Par defaut : `threshold_pct = 80%`, `min_participants = 59`.
|
||||
Reference in New Issue
Block a user