Sprint 3 : protocoles de vote et boite a outils
Backend: - Sessions de vote : list, close, tally, threshold details, auto-expiration - Protocoles : update, simulate, meta-gouvernance, formulas CRUD - Service vote enrichi : close_session, get_threshold_details, nuanced breakdown - Schemas : ThresholdDetailOut, VoteResultOut, FormulaSimulationRequest/Result - WebSocket broadcast sur chaque vote + fermeture session - 25 nouveaux tests (threshold details, close, nuanced, simulation) Frontend: - 5 composants vote : VoteBinary, VoteNuanced, ThresholdGauge, FormulaDisplay, VoteHistory - 3 composants protocoles : ProtocolPicker, FormulaEditor, ModeParamsDisplay - Simulateur de formules interactif (page /protocols/formulas) - Page detail protocole (/protocols/[id]) - Composable useWebSocket (live updates) - Composable useVoteFormula (calcul client-side reactif) - Integration KaTeX pour rendu LaTeX des formules Documentation: - API reference : 8 nouveaux endpoints documentes - Formules : tables d'inertie, parametres detailles, simulation API - Guide vote : vote binaire/nuance, jauge, historique, simulateur, meta-gouvernance 55 tests passes (+ 1 skipped), 126 fichiers total. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Yvv
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Formules
|
||||
description: Formules mathematiques de seuil WoT, criteres Smith et TechComm
|
||||
description: Formules mathematiques de seuil WoT, criteres Smith et TechComm, simulation et meta-gouvernance
|
||||
---
|
||||
|
||||
# Formules de seuil
|
||||
@@ -13,36 +13,78 @@ $$
|
||||
\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
|
||||
### Variables et plages de valeurs
|
||||
|
||||
| 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 |
|
||||
| Symbole | Parametre | Description | Plage | Defaut |
|
||||
| ------- | ------------------- | ------------------------------------------------ | ------------------- | ------ |
|
||||
| $C$ | `constant_base` | Base constante additive (plancher minimum de votes favorables requis) | $[0, +\infty[$ | 0.0 |
|
||||
| $B$ | `base_exponent` | Exposant de base. $B^W$ ajoute un terme negligeable quand $W$ est grand | $]0, 1[$ | 0.1 |
|
||||
| $W$ | `wot_size` | Taille du corpus des votants eligibles (membres WoT) | $[1, +\infty[$ | -- |
|
||||
| $T$ | `total_votes` | Nombre total de votes exprimes (pour + contre) | $[0, W]$ | -- |
|
||||
| $M$ | `majority_pct / 100`| Ratio de majorite cible a pleine participation | $]0, 1]$ | 0.50 |
|
||||
| $G$ | `gradient_exponent` | Controle la vitesse de convergence de la super-majorite vers $M$ | $]0, +\infty[$ | 0.2 |
|
||||
|
||||
#### Detail des parametres
|
||||
|
||||
**$C$ -- Base constante** : Nombre minimum absolu de votes favorables requis, independamment de la participation. Avec $C = 3$, il faut au moins 3 votes favorables meme si la formule calcule un seuil inferieur. En general, $C = 0$.
|
||||
|
||||
**$B$ -- Exposant de base** : Genere un terme $B^W$ qui decroit exponentiellement avec la taille de la WoT. Pour $B = 0.1$ et $W = 7224$, $B^W = 0.1^{7224} \approx 0$. Ce terme n'est pertinent que pour de tres petites communautes. Plus $B$ est proche de 0, plus le terme decroit vite. Plus $B$ est proche de 1, plus il reste significatif.
|
||||
|
||||
**$M$ -- Ratio de majorite** : Determine la proportion de votes favorables necessaire quand toute la WoT vote. $M = 0.5$ signifie qu'a pleine participation, la majorite simple (50%+1) suffit. $M = 0.66$ impose une super-majorite des 2/3 meme a pleine participation.
|
||||
|
||||
**$G$ -- Gradient** : Controle la courbure de la transition entre quasi-unanimite (faible participation) et majorite $M$ (pleine participation). Plus $G$ est petit, plus la transition est rapide : l'inertie chute vite des les premieres participations. Plus $G$ est grand, plus l'exigence de quasi-unanimite persiste a des taux de participation eleves.
|
||||
|
||||
### 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)
|
||||
\text{inertia}(T, W) = 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
|
||||
Le facteur d'inertie represente la **proportion de votes favorables necessaire** parmi les votants effectifs. Il multiplie ensuite $(T - C)$ pour obtenir le seuil absolu.
|
||||
|
||||
Avec les parametres `M50 B.1 G.2` et le vote de l'Engagement Forgeron v2.0.0 :
|
||||
### Table d'inertie (WoT = 7224, M = 0.50, G = 0.2)
|
||||
|
||||
- $W = 7224$ (membres WoT)
|
||||
- $T = 120$ (97 pour + 23 contre)
|
||||
- Seuil calcule : $94$
|
||||
- Resultat : **adopte** (97 >= 94)
|
||||
Le tableau suivant montre comment le facteur d'inertie evolue en fonction de la participation, pour les parametres de reference `M50 G.2` avec une WoT de 7224 membres :
|
||||
|
||||
| Participation $T$ | Ratio $T/W$ | $(T/W)^G$ | Inertie | Seuil (votes favorables requis) | % favorables requis |
|
||||
| -----------------: | ----------: | ---------: | ------: | ------------------------------: | ------------------: |
|
||||
| 10 | 0.0014 | 0.2512 | 0.8744 | 9 | 87.4% |
|
||||
| 50 | 0.0069 | 0.3548 | 0.8226 | 42 | 82.3% |
|
||||
| 100 | 0.0138 | 0.3981 | 0.8010 | 81 | 80.1% |
|
||||
| 120 | 0.0166 | 0.4102 | 0.7949 | 96 | 79.5% |
|
||||
| 200 | 0.0277 | 0.4467 | 0.7766 | 156 | 77.7% |
|
||||
| 500 | 0.0692 | 0.5129 | 0.7435 | 372 | 74.4% |
|
||||
| 1000 | 0.1384 | 0.5754 | 0.7123 | 713 | 71.2% |
|
||||
| 2000 | 0.2769 | 0.6452 | 0.6774 | 1355 | 67.7% |
|
||||
| 3612 | 0.5000 | 0.7071 | 0.6464 | 2335 | 64.6% |
|
||||
| 5000 | 0.6920 | 0.7490 | 0.6255 | 3128 | 62.6% |
|
||||
| 7224 | 1.0000 | 1.0000 | 0.5000 | 3612 | 50.0% |
|
||||
|
||||
On constate que meme a 500 votants (6.9% de participation), il faut encore 74.4% de votes favorables. L'inertie ne descend en dessous de 66% qu'au-dela de 2000 votants (27.7% de participation).
|
||||
|
||||
### Decomposition pas a pas
|
||||
|
||||
Pour le vote de l'Engagement Forgeron v2.0.0 avec $W = 7224$, $T = 120$, $M = 0.50$, $B = 0.1$, $G = 0.2$, $C = 0$ :
|
||||
|
||||
$$
|
||||
\begin{aligned}
|
||||
B^W &= 0.1^{7224} \approx 0 \\[6pt]
|
||||
\frac{T}{W} &= \frac{120}{7224} \approx 0.0166 \\[6pt]
|
||||
\left(\frac{T}{W}\right)^G &= 0.0166^{0.2} \approx 0.4102 \\[6pt]
|
||||
1 - \left(\frac{T}{W}\right)^G &\approx 0.5898 \\[6pt]
|
||||
\text{inertia} &= 0.50 + 0.50 \times 0.5898 = 0.7949 \\[6pt]
|
||||
\text{Result} &= 0 + 0 + 0.7949 \times \max(0, 120 - 0) \\[3pt]
|
||||
&= 0.7949 \times 120 \approx 95.39 \\[3pt]
|
||||
&\Rightarrow \text{Seuil} = 94 \quad \text{(arrondi inferieur)}
|
||||
\end{aligned}
|
||||
$$
|
||||
|
||||
Resultat : **adopte** (97 >= 94).
|
||||
|
||||
## Critere Smith (Forgerons)
|
||||
|
||||
@@ -52,9 +94,19 @@ $$
|
||||
|
||||
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) |
|
||||
| Symbole | Parametre | Description | Plage | Defaut |
|
||||
| ------- | ---------------- | ---------------------------- | ---------------- | ------------------ |
|
||||
| $S$ | `smith_exponent` | Exposant pour le critere Smith | $]0, 1]$ | null (desactive) |
|
||||
|
||||
L'exposant $S$ controle l'exigence en fonction de la taille du groupe Smith. Plus $S$ est petit, moins de forgerons doivent voter favorablement. Plus $S$ est grand (proche de 1), plus le seuil se rapproche de la taille totale du groupe.
|
||||
|
||||
| SmithWotSize | $S = 0.1$ | $S = 0.3$ | $S = 0.5$ | $S = 0.7$ |
|
||||
| -----------: | --------: | --------: | --------: | --------: |
|
||||
| 5 | 2 | 2 | 3 | 4 |
|
||||
| 10 | 2 | 2 | 4 | 6 |
|
||||
| 20 | 2 | 3 | 5 | 10 |
|
||||
| 50 | 2 | 4 | 8 | 19 |
|
||||
| 100 | 2 | 4 | 10 | 26 |
|
||||
|
||||
Avec un exposant de $S = 0.1$ et 20 forgerons :
|
||||
|
||||
@@ -67,16 +119,16 @@ Au minimum 2 votes favorables de forgerons sont requis.
|
||||
## Critere TechComm (Comite Technique)
|
||||
|
||||
$$
|
||||
\text{TechCommThreshold} = \lceil \text{CoTecSize}^T \rceil
|
||||
\text{TechCommThreshold} = \lceil \text{CoTecSize}^{T_c} \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) |
|
||||
| Symbole | Parametre | Description | Plage | Defaut |
|
||||
| ------- | ------------------- | ------------------------------- | -------------- | ------------------ |
|
||||
| $T_c$ | `techcomm_exponent` | Exposant pour le critere TechComm | $]0, 1]$ | null (desactive) |
|
||||
|
||||
Avec un exposant de $T = 0.1$ et 5 membres TechComm :
|
||||
Avec un exposant de $T_c = 0.1$ et 5 membres TechComm :
|
||||
|
||||
$$
|
||||
\lceil 5^{0.1} \rceil = \lceil 1.17 \rceil = 2
|
||||
@@ -92,21 +144,27 @@ Un vote est **adopte** si et seulement si les trois conditions sont remplies sim
|
||||
2. `smith_votes_for >= seuil_Smith` (si critere Smith actif)
|
||||
3. `techcomm_votes_for >= seuil_TechComm` (si critere TechComm actif)
|
||||
|
||||
En notation formelle :
|
||||
|
||||
$$
|
||||
\text{Adopte} = \left( V_{\text{pour}} \geq \text{Seuil}_{\text{WoT}} \right) \;\wedge\; \left( S_{\text{actif}} \Rightarrow V_{\text{smith}} \geq \lceil W_S^S \rceil \right) \;\wedge\; \left( T_{\text{actif}} \Rightarrow V_{\text{tech}} \geq \lceil W_T^{T_c} \rceil \right)
|
||||
$$
|
||||
|
||||
## 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 |
|
||||
| Code | Parametre | Type | Plage | Exemple |
|
||||
| ---- | --------------------- | ----- | -------------- | ------------ |
|
||||
| D | `duration_days` | int | $[1, 365]$ | D30 = 30 jours |
|
||||
| M | `majority_pct` | int | $[1, 100]$ | M50 = 50% |
|
||||
| B | `base_exponent` | float | $]0, 1[$ | B.1 = 0.1 |
|
||||
| G | `gradient_exponent` | float | $]0, +\infty[$| G.2 = 0.2 |
|
||||
| C | `constant_base` | float | $[0, +\infty[$| C0 = 0.0 |
|
||||
| S | `smith_exponent` | float | $]0, 1]$ | S.1 = 0.1 |
|
||||
| T | `techcomm_exponent` | float | $]0, 1]$ | T.1 = 0.1 |
|
||||
| N | `ratio_multiplier` | float | $]0, +\infty[$| N1.5 = 1.5 |
|
||||
| R | `is_ratio_mode` | bool | $\{0, 1\}$ | R1 = true |
|
||||
|
||||
### Exemples
|
||||
|
||||
@@ -118,14 +176,14 @@ Les parametres de formule sont encodes dans une chaine compacte pour faciliter l
|
||||
|
||||
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 |
|
||||
| Niveau | Label | Valeur normalisee |
|
||||
| ------ | ------------- | ----------------: |
|
||||
| 0 | CONTRE | 0.0 |
|
||||
| 1 | PAS DU TOUT | 0.2 |
|
||||
| 2 | PAS D'ACCORD | 0.4 |
|
||||
| 3 | NEUTRE | 0.6 |
|
||||
| 4 | D'ACCORD | 0.8 |
|
||||
| 5 | TOUT A FAIT | 1.0 |
|
||||
|
||||
### Regle d'adoption (vote nuance)
|
||||
|
||||
@@ -134,4 +192,93 @@ 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.
|
||||
|
||||
En notation formelle :
|
||||
|
||||
$$
|
||||
\text{Adopte}_{\text{nuance}} = \left( \frac{V_3 + V_4 + V_5}{T} \geq \frac{\text{threshold\_pct}}{100} \right) \;\wedge\; \left( T \geq \text{min\_participants} \right)
|
||||
$$
|
||||
|
||||
Par defaut : `threshold_pct = 80%`, `min_participants = 59`.
|
||||
|
||||
## Simulateur de formules
|
||||
|
||||
L'API expose un endpoint de simulation qui permet de tester le comportement de la formule sans creer de session de vote. Cela permet aux utilisateurs d'experimenter differentes configurations avant de les proposer.
|
||||
|
||||
### Utilisation de l'API de simulation
|
||||
|
||||
**Endpoint** : `POST /api/v1/protocols/simulate`
|
||||
|
||||
**Exemple de requete** :
|
||||
|
||||
```bash
|
||||
curl -X POST https://glibredecision.example.org/api/v1/protocols/simulate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"wot_size": 7224,
|
||||
"total_votes": 120,
|
||||
"majority_pct": 50,
|
||||
"base_exponent": 0.1,
|
||||
"gradient_exponent": 0.2,
|
||||
"constant_base": 0.0,
|
||||
"votes_for": 97
|
||||
}'
|
||||
```
|
||||
|
||||
**Exemple de reponse** :
|
||||
|
||||
```json
|
||||
{
|
||||
"threshold": 94,
|
||||
"inertia_factor": 0.7949,
|
||||
"participation_ratio": 0.0166,
|
||||
"base_term": 0.0,
|
||||
"smith_threshold": null,
|
||||
"techcomm_threshold": null,
|
||||
"adopted": true,
|
||||
"details": {
|
||||
"wot_threshold_met": true,
|
||||
"smith_met": null,
|
||||
"techcomm_met": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cas d'usage du simulateur
|
||||
|
||||
1. **Calibration** : Tester differentes valeurs de $M$ et $G$ pour trouver un equilibre entre exigence et praticabilite.
|
||||
2. **Comparaison** : Comparer les seuils entre deux configurations sur les memes donnees de participation.
|
||||
3. **Prediction** : Estimer le seuil pour un vote a venir en fonction de la participation attendue.
|
||||
4. **Pedagogie** : Comprendre visuellement l'impact de chaque parametre sur le seuil.
|
||||
|
||||
## Meta-gouvernance
|
||||
|
||||
La meta-gouvernance est le mecanisme par lequel les **regles du vote elles-memes** sont soumises au vote. Concretement, modifier un protocole de vote ou une formule de seuil active est un acte de gouvernance qui necessite une validation collective.
|
||||
|
||||
### Principe
|
||||
|
||||
Quand un utilisateur propose une modification d'un protocole ou d'une formule en cours d'utilisation (lies a au moins une session ouverte), le systeme :
|
||||
|
||||
1. **Bloque la modification directe** (reponse HTTP 409).
|
||||
2. **Cree automatiquement une session de vote** portant sur la modification proposee.
|
||||
3. **Applique le protocole de vote en vigueur** pour valider ou rejeter la modification.
|
||||
4. Si le vote est **adopte**, la modification est appliquee aux futures sessions de vote. Les sessions en cours ne sont pas affectees.
|
||||
5. Si le vote est **rejete**, la modification est archivee et le protocole reste inchange.
|
||||
|
||||
### Quels objets sont proteges ?
|
||||
|
||||
| Objet | Endpoint de modification | Meta-gouvernance |
|
||||
| ----------------- | -------------------------- | ---------------- |
|
||||
| Protocole actif | `PUT /api/v1/protocols/{id}` | Oui |
|
||||
| Formule active | `PUT /api/v1/protocols/formulas/{id}` | Oui |
|
||||
| Protocole inactif | `PUT /api/v1/protocols/{id}` | Non (modification directe) |
|
||||
| Formule inactive | `PUT /api/v1/protocols/formulas/{id}` | Non (modification directe) |
|
||||
|
||||
Un protocole ou une formule est considere **actif** s'il est lie a au moins une session de vote au statut `open`.
|
||||
|
||||
### Cas d'usage
|
||||
|
||||
- **Changer la duree de vote** : Un membre propose de passer de 30 a 60 jours. La proposition est soumise au vote avec les regles actuelles. Si adoptee, les prochains votes dureront 60 jours.
|
||||
- **Modifier le gradient** : Un membre estime que le gradient $G = 0.2$ est trop permissif et propose $G = 0.4$. Le vote decide.
|
||||
- **Ajouter un critere Smith** : Un membre propose d'activer le critere Smith avec $S = 0.1$ pour impliquer les forgerons. Le vote decide.
|
||||
|
||||
La meta-gouvernance garantit qu'aucun parametre fondamental du systeme de decision ne peut etre modifie unilateralement.
|
||||
|
||||
Reference in New Issue
Block a user