yvv/decision
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Sprint 3 : protocoles de vote et boite a outils

Browse Source 
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
2026-02-28 13:29:31 +01:00
parent 2bdc731639
commit cede2a585f
25 changed files with 3964 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
docs/content/dev/3.api-reference.md
View File

@@ -48,13 +48,17 @@ Tous les endpoints sont prefixes par `/api/v1`. L'API est auto-documentee via Op
## Votes (`/api/v1/votes`)
| Methode | Endpoint | Description | Auth |
| ------- | --------------------------- | -------------------------------------------- | ---- |
| POST | `/sessions` | Creer une session de vote | Oui |
| GET | `/sessions/{id}` | Obtenir une session de vote | Non |
| POST | `/sessions/{id}/vote` | Soumettre un vote (signe) | Oui |
| GET | `/sessions/{id}/votes` | Lister les votes d'une session | Non |
| GET | `/sessions/{id}/result` | Calculer et retourner le resultat courant | Non |
| Methode | Endpoint | Description | Auth |
| ------- | ------------------------------- | -------------------------------------------- | ---- |
| POST | `/sessions` | Creer une session de vote | Oui |
| GET | `/sessions` | Lister les sessions de vote (filtres: status, protocol_id, decision_id) | Non |
| GET | `/sessions/{id}` | Obtenir une session de vote | Non |
| POST | `/sessions/{id}/vote` | Soumettre un vote (signe) | Oui |
| GET | `/sessions/{id}/votes` | Lister les votes d'une session | Non |
| GET | `/sessions/{id}/result` | Calculer et retourner le resultat courant | Non |
| POST | `/sessions/{id}/close` | Cloturer la session et calculer le resultat final | Oui |
| GET | `/sessions/{id}/threshold` | Obtenir le detail du calcul de seuil (formule, parametres, valeurs intermediaires) | Non |
| POST | `/sessions/{id}/tally` | Forcer un recomptage des votes et recalcul du seuil | Oui |
## Mandats (`/api/v1/mandates`)
@@ -70,13 +74,17 @@ Tous les endpoints sont prefixes par `/api/v1`. L'API est auto-documentee via Op
## Protocoles (`/api/v1/protocols`)
| Methode | Endpoint | Description | Auth |
| ------- | --------------- | -------------------------------------------------- | ---- |
| GET | `/` | Lister les protocoles de vote | Non |
| POST | `/` | Creer un protocole de vote | Oui |
| GET | `/{id}` | Obtenir un protocole avec sa configuration formule | Non |
| GET | `/formulas` | Lister les configurations de formules | Non |
| POST | `/formulas` | Creer une configuration de formule | Oui |
| Methode | Endpoint | Description | Auth |
| ------- | ------------------- | -------------------------------------------------- | ---- |
| GET | `/` | Lister les protocoles de vote | Non |
| POST | `/` | Creer un protocole de vote | Oui |
| GET | `/{id}` | Obtenir un protocole avec sa configuration formule | Non |
| PUT | `/{id}` | Mettre a jour un protocole (meta-gouvernance) | Oui |
| GET | `/formulas` | Lister les configurations de formules | Non |
| POST | `/formulas` | Creer une configuration de formule | Oui |
| GET | `/formulas/{id}` | Obtenir une configuration de formule par son ID | Non |
| PUT | `/formulas/{id}` | Mettre a jour une configuration de formule (meta-gouvernance) | Oui |
| POST | `/simulate` | Simuler le calcul d'une formule avec des parametres arbitraires | Non |
## Sanctuaire (`/api/v1/sanctuary`)
@@ -221,6 +229,225 @@ Retourne toutes les entrees du sanctuaire liees a une entite source (document, d
**Reponse** : `200 OK` avec une liste de `SanctuaryEntryOut`.
## Details des endpoints Sprint 3
### `GET /api/v1/votes/sessions` -- Lister les sessions de vote
Retourne la liste des sessions de vote avec pagination et filtres optionnels.
**Parametres de requete** :
| Parametre | Type | Description |
| ------------- | ------ | ---------------------------------------------- |
| `status` | string | Filtrer par statut (`open`, `closed`, `draft`) |
| `protocol_id` | uuid | Filtrer par protocole de vote |
| `decision_id` | uuid | Filtrer par decision associee |
| `skip` | int | Offset de pagination (defaut 0) |
| `limit` | int | Nombre max de resultats (defaut 50, max 200) |
**Reponse** : `200 OK` avec une liste de `VoteSessionOut`.
---
### `POST /api/v1/votes/sessions/{id}/close` -- Cloturer une session
Cloture une session de vote ouverte et calcule le resultat final. Le calcul inclut la formule WoT, les criteres Smith et TechComm le cas echeant. La session passe au statut `closed` et le resultat est fige.
**Preconditions** :
- La session doit etre au statut `open`.
- L'utilisateur doit etre le createur de la session ou un membre du Comite Technique.
**Reponse** :
```json
{
"session_id": "uuid",
"status": "closed",
"closed_at": "2026-02-28T12:00:00Z",
"result": {
"votes_for": 97,
"votes_against": 23,
"total_votes": 120,
"wot_size": 7224,
"threshold": 94,
"adopted": true,
"smith_threshold": 2,
"smith_votes_for": 5,
"smith_met": true,
"techcomm_threshold": null,
"techcomm_votes_for": null,
"techcomm_met": null
}
}
```
---
### `GET /api/v1/votes/sessions/{id}/threshold` -- Detail du calcul de seuil
Retourne le detail complet du calcul de seuil pour une session de vote, incluant les valeurs intermediaires de la formule. Utile pour la transparence et le debug.
**Reponse** :
```json
{
"session_id": "uuid",
"formula_config_id": "uuid",
"mode_params": "D30M50B.1G.2",
"parameters": {
"constant_base": 0.0,
"base_exponent": 0.1,
"majority_pct": 50,
"gradient_exponent": 0.2,
"smith_exponent": null,
"techcomm_exponent": null
},
"inputs": {
"wot_size": 7224,
"total_votes": 120,
"smith_wot_size": 20,
"techcomm_size": 5
},
"computation": {
"base_term": 7.943e-08,
"participation_ratio": 0.0166,
"participation_ratio_powered": 0.4217,
"inertia_factor": 0.7892,
"effective_threshold": 94.70,
"threshold_ceiled": 95,
"threshold_final": 94
},
"criteria": {
"smith_threshold": null,
"techcomm_threshold": null
}
}
```
---
### `POST /api/v1/votes/sessions/{id}/tally` -- Forcer un recomptage
Force le recalcul du decompte des votes et du seuil pour une session. Utile si des votes ont ete invalides manuellement ou si la taille WoT a ete corrigee.
**Preconditions** :
- L'utilisateur doit etre le createur de la session ou un membre du Comite Technique.
**Corps de la requete** (optionnel) :
```json
{
"wot_size_override": 7250,
"smith_wot_size_override": null,
"techcomm_size_override": null
}
```
Si aucun corps n'est fourni, les tailles sont reprises du snapshot initial.
**Reponse** : `200 OK` avec le meme format que le resultat de cloture.
---
### `PUT /api/v1/protocols/{id}` -- Mettre a jour un protocole
Met a jour un protocole de vote existant. Les modifications de protocoles actifs (utilises par des sessions ouvertes) sont soumises a **meta-gouvernance** : une session de vote doit d'abord valider la modification.
**Corps de la requete** (champs optionnels) :
```json
{
"name": "Nouveau nom du protocole",
"description": "Description mise a jour",
"vote_type": "nuanced",
"duration_days": 60,
"formula_config_id": "uuid-de-la-nouvelle-formule"
}
```
**Reponse** : `200 OK` avec le protocole mis a jour (`ProtocolOut`).
**Code 409** : Si le protocole est utilise par une session ouverte et qu'aucune validation meta-gouvernance n'est fournie.
---
### `GET /api/v1/protocols/formulas/{id}` -- Obtenir une formule
Retourne une configuration de formule par son identifiant, incluant tous les parametres et le `mode_params` encode.
**Reponse** : `200 OK` avec un `FormulaConfigOut`.
---
### `PUT /api/v1/protocols/formulas/{id}` -- Mettre a jour une formule
Met a jour une configuration de formule existante. Comme pour les protocoles, les formules actives sont protegees par la meta-gouvernance.
**Corps de la requete** (champs optionnels) :
```json
{
"name": "Configuration amendee",
"majority_pct": 66,
"base_exponent": 0.05,
"gradient_exponent": 0.3,
"constant_base": 0.0,
"smith_exponent": 0.1,
"techcomm_exponent": 0.1,
"ratio_multiplier": null,
"is_ratio_mode": false
}
```
Le champ `mode_params` est recalcule automatiquement a partir des valeurs fournies.
**Reponse** : `200 OK` avec la formule mise a jour (`FormulaConfigOut`).
**Code 409** : Si la formule est liee a un protocole actif sans validation meta-gouvernance.
---
### `POST /api/v1/protocols/simulate` -- Simuler une formule
Simule le calcul de seuil d'une formule avec des parametres arbitraires, sans creer ni modifier aucune donnee. Endpoint ouvert (pas d'authentification requise) pour permettre l'experimentation.
**Corps de la requete** :
```json
{
"wot_size": 7224,
"total_votes": 120,
"majority_pct": 50,
"base_exponent": 0.1,
"gradient_exponent": 0.2,
"constant_base": 0.0,
"smith_wot_size": 20,
"smith_exponent": 0.1,
"techcomm_size": 5,
"techcomm_exponent": 0.1,
"votes_for": 97
}
```
**Reponse** :
```json
{
"threshold": 94,
"inertia_factor": 0.7892,
"participation_ratio": 0.0166,
"base_term": 7.943e-08,
"smith_threshold": 2,
"techcomm_threshold": 2,
"adopted": true,
"details": {
"wot_threshold_met": true,
"smith_met": true,
"techcomm_met": true
}
}
```
## Pagination
Les endpoints de liste acceptent les parametres `skip` (offset, defaut 0) et `limit` (max 200, defaut 50).

235
docs/content/dev/5.formulas.md
View File

@@ -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.

222
docs/content/user/5.voting.md
View File

@@ -30,17 +30,225 @@ Chaque votant exprime son opinion sur une echelle a 6 niveaux :
Le vote est adopte si les niveaux positifs (3, 4, 5) representent au moins 80% des votes et qu'un nombre minimum de participants est atteint.
## Comment voter
## Comment voter -- Vote binaire
1. Rendez-vous sur une session de vote ouverte (via la section **Votes** ou la page d'une decision).
2. Choisissez votre vote (pour/contre en binaire, ou un niveau en nuance).
3. Ajoutez un commentaire optionnel pour expliquer votre choix.
4. **Signez votre vote** : la plateforme vous demande de signer un payload avec votre cle privee Ed25519.
5. Soumettez. Votre vote est enregistre avec la signature cryptographique.
### Etape par etape
1. **Acceder a la session de vote** : Rendez-vous dans la section **Votes** depuis le menu principal, ou accedez directement a la page d'une decision en cours. Les sessions ouvertes sont signalees par un badge vert "En cours".
2. **Consulter le sujet** : Lisez attentivement le document ou la decision soumise au vote. Le texte complet est affiche au-dessus du panneau de vote. Vous pouvez deployer chaque article pour consulter le detail.
3. **Choisir votre vote** : Le panneau de vote affiche deux boutons :
- **Pour** (bouton vert) : Vous approuvez la proposition.
- **Contre** (bouton rouge) : Vous rejetez la proposition.
4. **Ajouter un commentaire** (optionnel) : Un champ de texte sous les boutons vous permet d'expliquer votre choix. Le commentaire est public et visible par tous les membres.
5. **Signer votre vote** : Apres avoir clique sur votre choix, la plateforme genere un payload contenant votre vote, l'identifiant de la session et un horodatage. Votre extension de cle ou votre portefeuille Duniter vous demande de **signer ce payload** avec votre cle privee Ed25519.
6. **Confirmer la soumission** : Une fois la signature effectuee, cliquez sur **Soumettre**. Un message de confirmation apparait avec le resume de votre vote.
### Modifier son vote
Vous pouvez modifier votre vote tant que la session est ouverte. L'ancien vote est desactive (conserve pour l'audit) et remplace par le nouveau.
Tant que la session est ouverte, vous pouvez changer votre vote :
1. Retournez sur la page de la session de vote.
2. Votre vote actuel est affiche avec un badge "Votre vote".
3. Cliquez sur **Modifier mon vote**.
4. Selectionnez votre nouveau choix et signez a nouveau.
5. L'ancien vote est desactive (conserve dans l'historique pour audit) et remplace par le nouveau.
## Comment voter -- Vote nuance
### Etape par etape
1. **Acceder a la session** : Meme procedure que pour le vote binaire. Les sessions de vote nuance sont identifiees par un badge "Nuance" en plus du badge de statut.
2. **Consulter le sujet** : Lisez le document ou la decision soumise au vote.
3. **Choisir votre niveau** : Le panneau de vote nuance affiche une echelle a 6 niveaux sous forme de curseur ou de boutons :
| Niveau | Label | Signification |
| -----: | ------------- | ---------------------------------------------------------- |
| 0 | CONTRE | Opposition totale et ferme |
| 1 | PAS DU TOUT | Desaccord fort, points essentiels non remplis |
| 2 | PAS D'ACCORD | Desaccord modere, des reserves importantes |
| 3 | NEUTRE | Ni pour ni contre, ou acceptation sans enthousiasme |
| 4 | D'ACCORD | Approbation avec eventuellement des reserves mineures |
| 5 | TOUT A FAIT | Approbation totale et enthousiaste |
Les niveaux 3, 4 et 5 sont comptes comme **positifs**. Les niveaux 0, 1 et 2 sont comptes comme **negatifs**.
4. **Ajouter un commentaire** (optionnel) : Particulierement utile pour les niveaux intermediaires (1, 2, 3, 4), afin d'expliquer vos reserves ou vos attentes.
5. **Signer et soumettre** : Meme procedure que pour le vote binaire.
### Quand utiliser le vote nuance ?
Le vote nuance est recommande pour :
- Les textes longs comportant de nombreux articles (les votants peuvent exprimer un accord partiel).
- Les decisions ou la nuance est importante (budget, parametre technique).
- Les cas ou il est utile de mesurer le degre d'adhesion, pas seulement le resultat binaire.
## Comprendre la jauge de seuil
La page de chaque session de vote affiche une **jauge de seuil** qui represente visuellement l'etat du vote en temps reel.
### Elements de la jauge
```
[|||||||||||||||||||||||||||-----] 97 / 94 Adopte
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^
Votes Pour (vert) Seuil requis (trait vertical)
```
| Element | Description |
| --------------------------- | ------------------------------------------------------------ |
| **Barre verte** | Nombre de votes favorables actuels |
| **Barre rouge** | Nombre de votes defavorables actuels |
| **Trait vertical** | Position du seuil requis (calcule par la formule d'inertie) |
| **Compteur numerique** | `votes_pour / seuil` affiche a droite de la jauge |
| **Badge de resultat** | "Adopte" (vert) ou "Non atteint" (gris) ou "Rejete" (rouge) |
| **Pourcentage de participation** | `total_votes / wot_size` affiche sous la jauge |
### Comportement dynamique
La jauge se **met a jour en temps reel** : a chaque nouveau vote soumis, la barre et le seuil sont recalcules instantanement. Le seuil peut augmenter legerement a mesure que de nouveaux votes arrivent (car la participation $T$ change, ce qui modifie le facteur d'inertie). Le resultat affiche est donc toujours provisoire tant que la session est ouverte.
### Detail du calcul
En cliquant sur le bouton **Voir le detail** sous la jauge, une modale s'ouvre avec :
- Les parametres de la formule utilises (`mode_params`).
- Les valeurs intermediaires du calcul (ratio de participation, facteur d'inertie, etc.).
- Les criteres Smith et TechComm si applicables.
- Un lien vers le simulateur de formules pour experimenter d'autres scenarios.
## Mises a jour en temps reel
Glibredecision utilise une connexion **WebSocket** pour diffuser les mises a jour de vote en temps reel a tous les utilisateurs qui consultent une session de vote.
### Ce qui est mis a jour en direct
| Evenement | Effet sur l'interface |
| ---------------------------- | ---------------------------------------------------- |
| Nouveau vote soumis | La jauge de seuil est recalculee et reaffichee |
| Vote modifie | La jauge reflette le changement immediatement |
| Session cloturee | Le badge passe a "Cloture" et le resultat final s'affiche |
| Critere Smith/TechComm atteint | L'indicateur de critere passe au vert |
### Indicateur de connexion
Un petit indicateur en bas a droite de la page de vote affiche l'etat de la connexion temps reel :
- **Point vert** : Connexion active, mises a jour en direct.
- **Point orange** : Reconnexion en cours.
- **Point rouge** : Connexion perdue. Les donnees affichees peuvent etre obsoletes. Rechargez la page.
## Historique des votes
### Consulter ses propres votes
1. Cliquez sur votre avatar ou votre adresse Duniter dans la barre de navigation.
2. Selectionnez **Mon historique de votes**.
3. La liste affiche tous vos votes passes, avec pour chacun :
- Le titre de la session / decision.
- Votre choix (Pour/Contre ou niveau nuance).
- La date et l'heure du vote.
- Le resultat final de la session (Adopte/Rejete) si cloturee.
### Consulter les votes d'une session
Sur la page d'une session de vote, l'onglet **Votes** affiche la liste de tous les votes soumis :
- L'adresse Duniter du votant.
- Le choix exprime.
- Le commentaire (s'il y en a un).
- L'horodatage.
- Un lien pour verifier la signature Ed25519.
Les votes sont publics et verifiables par tous. Il n'y a pas de vote secret dans Glibredecision : la transparence est un principe fondamental.
## Simulateur de formules
Le simulateur de formules vous permet de tester le comportement du seuil d'adoption avec differentes configurations, sans creer de session de vote.
### Acceder au simulateur
1. Depuis le menu principal, selectionnez **Outils** puis **Simulateur de formules**.
2. Vous pouvez aussi y acceder depuis le detail du calcul de seuil d'une session de vote (bouton **Ouvrir le simulateur**).
### Utiliser le simulateur
Le simulateur presente un formulaire avec les parametres ajustables :
| Parametre | Description | Curseur/Champ |
| ----------------------- | ---------------------------------------------- | ------------- |
| Taille WoT ($W$) | Nombre de membres eligibles | Curseur |
| Total votes ($T$) | Nombre de votes exprimes | Curseur |
| Majorite ($M$) | Pourcentage de majorite cible | Curseur |
| Base ($B$) | Exposant de base | Champ |
| Gradient ($G$) | Vitesse de convergence | Curseur |
| Base constante ($C$) | Plancher minimum de votes | Champ |
| Votes Pour | Nombre de votes favorables (pour tester l'adoption) | Curseur |
En ajustant les curseurs, le resultat se met a jour en temps reel :
- Le **seuil calcule** est affiche.
- Un graphique montre la courbe du seuil en fonction de la participation.
- Le resultat **Adopte** / **Rejete** s'affiche en fonction des votes pour saisis.
### Exemple de scenario
Vous souhaitez comparer deux configurations pour un vote attendu avec environ 200 participants sur une WoT de 7224 :
1. Configuration actuelle `M50 G.2` : Seuil = 156 (77.7% requis).
2. Configuration proposee `M50 G.4` : Seuil = 171 (85.5% requis).
Le simulateur montre visuellement l'impact : avec un gradient plus eleve, l'exigence est sensiblement plus forte a faible participation.
## Meta-gouvernance : voter sur les regles du vote
La meta-gouvernance est la capacite de **modifier les regles du systeme de vote en utilisant le systeme de vote lui-meme**. C'est le mecanisme par lequel la communaute garde le controle sur les parametres fondamentaux de la prise de decision.
### Qu'est-ce qui peut etre modifie par meta-gouvernance ?
| Element modifiable | Exemple de modification |
| ------------------------------- | ---------------------------------------------------------- |
| Duree de vote | Passer de 30 jours a 60 jours |
| Majorite cible ($M$) | Passer de 50% a 66% (super-majorite) |
| Gradient ($G$) | Augmenter de 0.2 a 0.4 (plus exigeant a faible participation) |
| Critere Smith | Activer ou desactiver, changer l'exposant |
| Critere TechComm | Activer ou desactiver, changer l'exposant |
| Type de vote | Passer d'un vote binaire a un vote nuance |
### Comment ca fonctionne ?
1. **Proposition** : Un membre propose une modification d'un protocole ou d'une formule via l'interface (bouton **Proposer une modification** sur la page du protocole).
2. **Verification** : Le systeme detecte que le protocole ou la formule est **actif** (lie a au moins une session de vote ouverte).
3. **Creation automatique d'un vote** : Une session de vote est automatiquement creee pour valider ou rejeter la modification. Cette session utilise les **regles actuelles** (pas les regles proposees).
4. **Vote de la communaute** : Les membres votent sur la proposition de modification selon les regles en vigueur.
5. **Application conditionnelle** :
- Si le vote est **adopte** : les nouvelles regles s'appliquent aux futures sessions de vote. Les sessions en cours ne sont pas affectees.
- Si le vote est **rejete** : le protocole reste inchange.
### Exemple concret
Un membre estime que le gradient $G = 0.2$ est trop permissif et propose de passer a $G = 0.4$ :
1. Il se rend sur la page du protocole actif et clique sur **Proposer une modification**.
2. Il modifie la valeur du gradient de 0.2 a 0.4 dans le formulaire.
3. Il soumet la proposition. Le systeme cree une session de vote intitulee "Modification du gradient de seuil : G.2 vers G.4".
4. Les membres votent pendant 30 jours (duree du protocole actuel).
5. Avec 97 votes pour et 23 contre sur une WoT de 7224, le seuil calcule est de 94. Le vote est adopte (97 >= 94).
6. Le gradient passe a 0.4 pour toutes les futures sessions de vote.
### Pourquoi la meta-gouvernance est importante
- **Aucun parametre n'est grave dans le marbre** : la communaute peut toujours adapter les regles.
- **Protection contre les modifications unilaterales** : personne ne peut changer les regles seul.
- **Transparence** : toute modification de regle est tracable et soumise au vote.
- **Coherence** : les regles de modification sont les memes que les regles de decision (le systeme s'applique a lui-meme).
## Comprendre les resultats