@mostajs/ro-pla 0.2.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,121 @@
1
1
  # CHANGELOG
2
2
 
3
+ ## [0.4.0] — 2026-11-22
4
+
5
+ ### Ajouté — délai de calcul du branch & bound
6
+
7
+ Sur un PLNE dont la borne ne se referme pas (un besoin non couvrable : une équipe trop courte),
8
+ le branch & bound explorait tout son budget de nœuds — des minutes — et l'appelant n'avait que le
9
+ choix de l'arrêter de l'extérieur en perdant ce qui avait été trouvé. Il accepte désormais un délai
10
+ et rend la meilleure solution trouvée, son statut et l'écart à la borne (contrat inspiré de CP-SAT,
11
+ HiGHS, CBC et Gurobi).
12
+
13
+ - **`timeoutMs`** (déclaré dans `SolveOptions` depuis la 0.1, jamais lu jusqu'ici) : honoré par
14
+ `branch-and-bound`, contrôlé entre deux nœuds (dépassement ≤ une relaxation).
15
+ - **`anytime: true`** : le même contrat pour le seul budget `maxNodes`.
16
+ - **`now`** : horloge injectable (ms, défaut `Date.now`).
17
+ - Dans ce mode « au fil de l'eau », `status` vaut `optimal` (prouvé), **`feasible`** (meilleure
18
+ solution trouvée à la limite, non prouvée), **`unknown`** (limite atteinte sans solution entière,
19
+ rien de prouvé), `infeasible` ou `unbounded` (prouvés) ; et le champ **`search`** donne
20
+ `{ complete, stoppedBy: 'time' | 'nodes' | null, nodes, elapsedMs, bound, gap }`, avec
21
+ `gap` = |bound − objective| / |objective|.
22
+ - Types : `MilpStatus`, `MilpSearch` ; `MilpSolution` devient une interface (statut élargi,
23
+ `search?`). `LpSolution` et les autres dialectes ne changent pas.
24
+
25
+ ### Inchangé — sans délai
26
+
27
+ Sans `timeoutMs` ni `anytime`, le résultat est celui de la 0.3.0 au champ près (essai T-RO-112,
28
+ sur des résultats enregistrés avec la 0.3.0). Cela comprend un **défaut connu, conservé pour la
29
+ compatibilité** : budget `maxNodes` atteint, la 0.3.0 répond `optimal` si un entier a été trouvé,
30
+ `infeasible` sinon — sans preuve dans les deux cas. Passer `anytime: true` pour un statut honnête.
31
+
32
+ ### Interne
33
+
34
+ Le parcours en profondeur passe d'une récursion à une pile explicite, dans le même ordre (branche
35
+ `x ≤ ⌊v⌋` d'abord) : plus de limite de profondeur de pile, et la borne des nœuds ouverts se lit à
36
+ l'arrêt.
37
+
38
+ ## [0.3.0] — 2026-11-15
39
+
40
+ ### Corrigé — la famille seule ne suffisait pas à choisir le dialecte
41
+
42
+ Dans sept familles sur douze, plusieurs dialectes partagent un `kind` sans résoudre un problème de
43
+ même forme. `solve({kind})` retenait toujours le premier exact enregistré : onze dialectes étaient
44
+ inatteignables sans être nommés, et la plupart des formes « étrangères » plantaient. **Deux rendaient
45
+ une réponse fausse et muette** : une forme `forecast` servie par `monte-carlo` (moyenne 0, variance
46
+ 0) et une forme `bin-packing` ou `list-scheduling` servie par `critical-path` (durée 0, chemin
47
+ critique vide).
48
+
49
+ Désormais chaque dialecte déclare sa **forme** (`shape` : champs obligatoires, contrôle
50
+ complémentaire facultatif) et `solve` sans dialecte nommé ne garde que les dialectes dont la forme
51
+ correspond. Appels qui **changent de comportement** :
52
+
53
+ | appel sans dialecte nommé | 0.2.2 | 0.3.0 |
54
+ |---|---|---|
55
+ | `flow`, forme `shortest-path` ou `max-flow` | plantage dans `min-cost-flow` | le bon dialecte |
56
+ | `assignment`, forme `matching` ou `stable-matching` | plantage dans `hungarian` | le bon dialecte |
57
+ | `milp`, forme `knapsack` | plantage dans `branch-and-bound` | `knapsack` |
58
+ | `lp`, forme `lagrangian` | plantage dans `simplex` | `lagrangian` |
59
+ | `metaheuristic`, forme `tabu` ou `genetic` | plantage dans `anneal` | le bon dialecte |
60
+ | `simulation`, forme `forecast` | **réponse fausse** de `monte-carlo` | `forecast` |
61
+ | `scheduling`, forme `bin-packing` ou `list-scheduling` | **réponse fausse** de `critical-path` | le bon dialecte |
62
+ | problème sans `kind` | plantage dans `hungarian` | erreur `RO_PLA_NO_KIND` |
63
+ | forme inconnue de la famille | plantage | erreur `RO_PLA_NO_SHAPE` (candidats, champs attendus) |
64
+ | forme ambiguë (ex. arêtes à `weight` ET `capacity`, avec `sink`) | plantage ou réponse au hasard | erreur `RO_PLA_AMBIGUOUS_SHAPE` |
65
+
66
+ **Aucun appel qui fonctionnait ne change de dialecte** : la forme historique de chaque famille va
67
+ au dialecte historique. Un dialecte **nommé** est servi comme avant, sans contrôle de forme. Un
68
+ dialecte tiers sans forme déclarée est réputé accepter toute sa famille.
69
+
70
+ ### Corrigé — le tri de sélection fait ce que son commentaire annonce
71
+
72
+ Il ne triait que sur l'exactitude. Ordre codé et écrit : forme acceptée ; exact d'abord ; plus petite
73
+ `maxSize` qui couvre la taille mesurée ; bornes « à établir » ; bornes dépassées ; ordre
74
+ d'enregistrement. Aucun choix d'aujourd'hui ne change (aucune famille intégrée n'a deux exacts de
75
+ même forme). La fonction de tri reste interne et n'est pas exportée.
76
+
77
+ ### Corrigé — `mmc`
78
+
79
+ - λ = 0 : attente moyenne 0, et non `NaN`.
80
+ - Nombre de serveurs non entier : refusé (`RangeError`), au lieu de métriques sans avertissement.
81
+ - `solve` sans `c` ni `target` : évalue toujours c = 1, mais le dit dans `solvedBy.notes`.
82
+
83
+ ### Ajouté
84
+
85
+ - **`solvedBy`** sur le résultat de `solve` (dialecte nommé ou non), un seul champ :
86
+ `{ dialect, kind, exact, online, reason, criterion, size, maxSize, beyondDeclaredSize, notes }`.
87
+ Le résultat est une copie ; la solution du dialecte n'est pas modifiée. Un dialecte synchrone
88
+ reste synchrone. **Les fonctions directes (`hungarian`, `simplex`, `mmc`…) ne changent pas.**
89
+ Une solution produite avant la 0.3.0 et rejouée depuis une mémoire n'a pas ce champ.
90
+ - **`beyondDeclaredSize`** : vrai, faux, ou `null` (« à établir »). Mesure de taille déclarée par
91
+ `hungarian` (ordre de la matrice), `simplex` (variables), `branch-and-bound` (variables entières),
92
+ `markov` (états) ; « à établir » pour `min-cost-flow` et `mdp`. Rien n'est refusé : simplex à 600
93
+ variables reste `optimal`, et le dit.
94
+ - **`checkSize(dialecte | nom, problème)`** : taille, borne, dépassement, sans résoudre.
95
+ - **`maxSize: null`** explicite sur les 17 dialectes sans borne ; le type admet `null`.
96
+ - **`acceptsShape`**, **`SolverSelectionError`** (champ `code`), types `ProblemShape`, `SolvedBy`,
97
+ `SolvedByReason`, `SolvedByCriterion`, `SizeCheck` ; contrat `shape`, `size`, `sizeUnit`, `notes`.
98
+ - **`LICENSE`** (AGPL-3.0-or-later) : cité dans `files`, il manquait au paquet.
99
+ - Tables de dialectes du README et de `llms.txt` **engendrées depuis le registre**, et comparées à
100
+ lui par un essai.
101
+ - Essai du **paquet packé** : installé dans un projet vierge, importé en Node brut sans chargeur,
102
+ exports égaux au barrel, aucun import relatif sans `.js`, `LICENSE` présent.
103
+
104
+ ### Modifié
105
+
106
+ - `tsconfig` : `module` et `moduleResolution` en `NodeNext`. Le compilateur refuse désormais tout
107
+ import relatif sans extension. `dist/` émis identique à l'octet.
108
+ - `llms.txt` : version juste, `pickBest` retiré (il n'a jamais été exporté), sélection par forme,
109
+ `solvedBy`, condition `import` seule, feuille de route périmée retirée.
110
+
111
+ ### Non fait, et dit
112
+
113
+ - **Les bornes `maxSize` ne sont pas mesurées** : la 0.3.0 les rend opposables, elle ne les valide pas.
114
+ - **Erlang C n'est pas confrontée à une table publiée.** L'essai sourcé existe et se déclare EN
115
+ ATTENTE tant que la source manque ; la formule est vérifiée par la récurrence d'Erlang B et la loi
116
+ de Little (cohérence interne, pas conformité).
117
+ - Mesure de taille de `min-cost-flow` et `mdp` : à établir.
118
+
3
119
  ## [0.2.2] — 2026-09-06
4
120
 
5
121
  ### Corrigé — `llms.txt`, qui est PUBLIÉ, annonçait 11 dialectes et la version 0.1.0
@@ -22,15 +138,10 @@ Corrigé, et deux avertissements ajoutés pour le lecteur-machine :
22
138
  - **`solve({kind})` ne dit pas quel dialecte a été retenu** — pour savoir si un résultat est prouvé,
23
139
  il faut lire `getSolver(nom).capabilities.exact`.
24
140
 
25
- ### Ajouté — les 13 livrables §9 manquants (4 → 17)
141
+ ### Nommé — quatre défauts, renvoyés à la 0.3.0
26
142
 
27
- `#1` état de l'art · `#2` audit · `#3` plan de développement · `#3.bis` image OBJECTIF · `#5` plan de
28
- suivi · `#8` SEO et article · `#9` plan de publication · `#10` présentation · `#11` diapositives
29
- commerciales · `#12` documentation technique · `#13` diapositives développement · `#14` image
30
- RÉSULTAT · `#15` revue de sécurité · `#16` DPIA. Rendus PDF et PPTX par `@mostajs/doc-export`.
31
-
32
- **Aucune ligne de code du module n'a été modifiée.** Ce lot NOMME et MESURE quatre défauts, il ne les
33
- corrige pas — ils entrent au jalon 0.3.0, et rien ne sera codé avant validation.
143
+ **Aucune ligne de code du module n'a été modifiée.** Quatre défauts ont été nommés et mesurés, sans
144
+ être corrigés — ils entrent au jalon 0.3.0.
34
145
 
35
146
  - **A — `maxSize` déclarée, jamais appliquée.** Mesuré : `simplex` déclare 200 et rend `optimal` à
36
147
  200, 300 et 600 variables, avec les mêmes champs, sans un mot. Le danger n'est pas le plantage,
@@ -39,27 +150,15 @@ corrige pas — ils entrent au jalon 0.3.0, et rien ne sera codé avant validati
39
150
  plus petit `maxSize` couvrant » ; le code ne trie que sur `exact`. Sans conséquence aujourd'hui,
40
151
  faux dès le premier `kind` servi par deux dialectes exacts de bornes différentes.
41
152
  - **C — la sélection ne rend pas son motif.** `solve({kind})` ne dit pas quel dialecte a produit le
42
- résultat. Ce n'est pas qu'un défaut d'ergonomie : le port modeleur d'`assistant-pilote` ne peut
43
- déclarer ni `probleme` ni `explication` sur ce module, et c'est aussi une pièce de conformité —
44
- face à « pourquoi moi », l'appelant ne peut pas nommer l'algorithme employé.
45
- - **D — `00-CATALOGUE-ALGOS.md` se disait « source unique de vérité » et donnait 4 dialectes sur 23.**
46
- Vérifié une fois le 13/06, cru trois mois sur la foi de son titre. Sa §1 est désormais engendrée
47
- depuis `listSolvers()`, et le poste 5 du jalon 0.3.0 la fera engendrer automatiquement.
48
-
49
- ### Suspendu — la diffusion de l'article #17
50
-
51
- `docs/articles/17bis-VERIFICATION-SOURCES.md` établit, source par source, ce qui est vérifié. Bilan :
52
- **deux références internes fausses sur trois** — « les 11 dialectes » et un chemin qui pointe vers
53
- `mosta-ro-pla/docs/` alors que le fichier est dans `mosta-ro-pla-eca/docs/` — et **aucune référence
54
- externe vérifiée**, dont un nom d'auteur douteux et onze outils nommés sans qu'aucun n'ait été
55
- essayé.
56
-
57
- ⚠️ Le plus grave n'est pas la bibliographie : **la formule d'Erlang C du dialecte `mmc` n'a jamais
58
- été confrontée à une source externe.** Les essais vérifient sa cohérence interne, pas sa conformité
59
- à la théorie. Un article qui enseigne le dimensionnement de guichets sur une formule non validée fait
60
- plus de dégâts qu'une bibliographie approximative — le lecteur applique le résultat.
61
- `ARTICLE-SEO-RO-PLA.md` peut être diffusé : il ne cite aucune source externe et ne s'appuie que sur
62
- des mesures reproductibles.
153
+ résultat. Ce n'est pas qu'un défaut d'ergonomie : c'est aussi une pièce de conformité — face à
154
+ « pourquoi moi », l'appelant ne peut pas nommer l'algorithme employé.
155
+ - **D — le catalogue des algorithmes se disait « source unique de vérité » et donnait 4 dialectes
156
+ sur 23.** Recopié à la main, il s'était périmé sans bruit ; la 0.3.0 le fait engendrer.
157
+
158
+ ### Signalé — Erlang C
159
+
160
+ ⚠️ **La formule d'Erlang C du dialecte `mmc` n'a jamais été confrontée à une source externe.** Les
161
+ essais vérifient sa cohérence interne, pas sa conformité à la théorie.
63
162
 
64
163
  ## [0.2.1] — 2026-09-06
65
164
 
@@ -106,9 +205,6 @@ Dantzig-Wolfe, Benders, PSO, ACO, GRASP, NSGA-II en propre, réseaux de neurones
106
205
  événements discrets, contraintes cumulative, dualité/sensibilité. Tous annoncés dans la feuille de
107
206
  route d'origine, aucun présent. Un module qui laisse croire coûte plus cher qu'un module qui manque.
108
207
 
109
- L'état des livrables DEVRULES §9 y est dit sans arrangement : **4 présents sur 17**, et l'article
110
- existant attend une vérification de ses sources avant diffusion.
111
-
112
208
  > Le paquet npm n'embarque ni `examples/` ni les sources : `files` reste limité à `dist/`.
113
209
 
114
210
  ## [0.2.0] — 2026-08-09
@@ -146,5 +242,5 @@ graine égale** — sans quoi `@mostajs/skill-library` ne pourrait juger aucune
146
242
  courte : l'appelant croyait tenir une prévision saisonnière. Refus motivé si la méthode est
147
243
  demandée explicitement, `note` explicite en mode automatique.
148
244
 
149
- 108 tests verts. Plan Dev+Test dans qatrax : 24 exigences, 24 réalisations, 49 tests.
245
+ 108 tests verts.
150
246
 
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ @mostajs/ro-pla
2
+ Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
3
+
4
+ SPDX-License-Identifier: AGPL-3.0-or-later
5
+
6
+ This program is free software: you can redistribute it and/or modify
7
+ it under the terms of the GNU Affero General Public License as published by
8
+ the Free Software Foundation, either version 3 of the License, or
9
+ (at your option) any later version.
10
+
11
+ This program is distributed in the hope that it will be useful,
12
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
13
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
+ GNU Affero General Public License for more details.
15
+
16
+ You should have received a copy of the GNU Affero General Public License
17
+ along with this program. If not, see <https://www.gnu.org/licenses/>.
18
+
19
+ The complete text of the GNU Affero General Public License version 3 is
20
+ available at the URL above and must accompany any distribution of this
21
+ software.
package/README.md CHANGED
@@ -1,31 +1,40 @@
1
1
  # @mostajs/ro-pla
2
2
 
3
3
  **Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
4
- **Statut** : **0.2.1** — 23 dialectes, 111 essais verts, `examples/` exécutables.
4
+ **Statut** : **0.4.0** — 23 dialectes, sélection par forme, `solvedBy`, branch & bound à délai de calcul, `examples/` exécutables.
5
5
 
6
6
  **Programmation linéaire & recherche opérationnelle** pour l'écosystème `@mostajs/*`. Une question
7
- métier se pose à un **registre**, qui choisit le dialecte : on nomme une **famille** de problèmes,
8
- jamais un algorithme.
7
+ métier se pose à un **registre**, qui choisit le dialecte dans la **famille** du problème (`kind`),
8
+ d'après la **forme** du problème ; ou l'on nomme l'algorithme.
9
9
 
10
10
  ```js
11
- import { solve, getSolver, binPacking } from '@mostajs/ro-pla';
11
+ import { solve, getSolver, checkSize, binPacking } from '@mostajs/ro-pla';
12
12
 
13
- // La question nomme la FAMILLE — le registre choisit l'algorithme.
14
- solve({ kind: 'assignment', cost: [[4, 1], [2, 3]] }); // → hongrois, { total: 3 }
15
- solve({ kind: 'csp', variables: ['X', 'Y'], domains: [[1, 2], [1, 2]],
16
- constraints: [{ type: 'allDifferent', vars: [0, 1] }] }); // → backtracking
13
+ // La question nomme la FAMILLE ; la FORME du problème désigne le dialecte.
14
+ const r = solve({ kind: 'assignment', cost: [[4, 1], [2, 3]] }); // → hongrois, total 3
15
+ r.solvedBy; // { dialect: 'hungarian', kind: 'assignment', exact: true, reason: 'only-shape-match',
16
+ // size: 2, maxSize: 1000, beyondDeclaredSize: false, … }
17
17
 
18
- // Ou l'on appelle un dialecte directement, quand on sait ce qu'on veut.
18
+ solve({ kind: 'flow', edges: [{ from: 'a', to: 'b', weight: 2 }], source: 'a' }); // → shortest-path
19
+
20
+ // Nommer le dialecte reste la voie sûre : aucun contrôle de forme.
21
+ solve(probleme, { dialect: 'max-flow' });
22
+
23
+ // Ou l'on appelle un dialecte directement (sans `solvedBy`, forme inchangée).
19
24
  binPacking({ kind: 'scheduling', items, bins, strategy: 'both' });
20
25
 
21
- // Les capacités d'un dialecte se LISENT avant de s'en servir.
22
- getSolver('hungarian').capabilities; // { exact: true, online: true, maxSize: 1000 }
26
+ // Les capacités et la borne se LISENT avant de s'en servir.
27
+ getSolver('hungarian').capabilities; // { exact: true, online: true, maxSize: 1000 }
28
+ checkSize('simplex', { kind: 'lp', c, A, b }); // { size, maxSize: 200, beyondDeclaredSize }
23
29
  ```
24
30
 
25
31
  ## Les 23 dialectes, par famille
26
32
 
27
- `~` marque un dialecte **approché** : il ne prétend pas à l'optimum, et rend de quoi juger sur
28
- pièces (borne inférieure, écart, cause d'échec). **15 exacts, 8 approchés.**
33
+ Table engendrée depuis le registre (`node scripts/catalogue.mjs --write`) ; un essai échoue si elle
34
+ diverge du code.
35
+
36
+ <!-- engendre:familles:debut -->
37
+ **23 dialectes, 12 familles : 15 exacts, 8 approchés.** `~` marque un dialecte approché.
29
38
 
30
39
  | `kind` | dialectes |
31
40
  |---|---|
@@ -33,14 +42,55 @@ pièces (borne inférieure, écart, cause d'échec). **15 exacts, 8 approchés.*
33
42
  | `lp` | simplex · lagrangian `~` |
34
43
  | `milp` | branch-and-bound · knapsack |
35
44
  | `flow` | min-cost-flow · shortest-path · max-flow |
45
+ | `queue` | mmc |
46
+ | `markov` | markov |
47
+ | `decision` | mdp |
36
48
  | `csp` | backtrack-csp |
37
- | `scheduling` | critical-path · bin-packing `~` · list-scheduling `~` |
38
- | `queue` | mmc (files M/M/c, formules d'Erlang, dimensionnement) |
39
- | `markov` | markov (stationnaire, régime transitoire, absorption) |
40
- | `decision` | mdp (itération de la valeur) |
41
49
  | `metaheuristic` | anneal `~` · tabu `~` · genetic `~` |
42
- | `multiobjective` | pareto (fronts, rangs, tri par non-domination façon NSGA-II — **exact** : il énumère le front, il ne le devine pas) |
43
50
  | `simulation` | monte-carlo `~` · forecast `~` |
51
+ | `scheduling` | critical-path · bin-packing `~` · list-scheduling `~` |
52
+ | `multiobjective` | pareto |
53
+ <!-- engendre:familles:fin -->
54
+
55
+ ## Sélection : famille, puis forme (0.3.0)
56
+
57
+ - Sans dialecte nommé, `solve` garde dans la famille les dialectes dont la **forme** correspond :
58
+ chacun déclare ses champs obligatoires (`shape.fields`) et parfois un contrôle complémentaire
59
+ (arêtes à `weight` → `shortest-path`, à `capacity` → `max-flow`).
60
+ - Plusieurs candidats : **exact** d'abord, puis la plus petite borne qui **couvre** la taille, puis
61
+ les bornes « à établir », puis les bornes dépassées ; l'ordre d'enregistrement départage.
62
+ - Aucune forme reconnue, forme ambiguë, problème sans `kind` : **erreur explicite**
63
+ (`SolverSelectionError`, champ `code`), qui nomme les candidats et les champs attendus. En 0.2.x,
64
+ ces appels plantaient — ou rendaient une réponse fausse sans le dire.
65
+ - `solvedBy` dit **qui** a répondu et **pourquoi** (`reason`, `criterion`). Il peut manquer sur une
66
+ solution produite avant la 0.3.0 et rejouée depuis une mémoire.
67
+ - **Les bornes `maxSize` ne sont pas mesurées.** Elles sont déclaratives : un problème au-delà est
68
+ résolu quand même, et `solvedBy.beyondDeclaredSize` le dit. `null` = « à établir ».
69
+ - **Erlang C (`mmc`) n'est pas encore confrontée à une table publiée** : elle est vérifiée par la
70
+ récurrence d'Erlang B et la loi de Little, ce qui établit sa cohérence, pas sa conformité.
71
+ - Paquet ESM seul (condition `import`).
72
+
73
+ ## Délai de calcul du branch & bound (0.4.0)
74
+
75
+ Un PLNE peut ne jamais refermer sa borne (besoin non couvrable : une équipe trop courte, un
76
+ entrepôt trop petit). Plutôt que de couper le calcul de l'extérieur et de tout perdre, on donne un
77
+ délai : le solveur rend la **meilleure solution trouvée**, dit si elle est **prouvée**, pourquoi il
78
+ s'est arrêté, et **l'écart à la borne** — comme CP-SAT, HiGHS, CBC ou Gurobi.
79
+
80
+ ```js
81
+ const r = solve(probleme, { dialect: 'branch-and-bound', timeoutMs: 20_000 });
82
+ r.status; // 'optimal' (prouvé) | 'feasible' (meilleure trouvée) | 'unknown' (aucune) | 'infeasible' | 'unbounded'
83
+ r.search; // { complete: false, stoppedBy: 'time', nodes: 571, elapsedMs: 20012, bound: 15, gap: 0.0714 }
84
+ ```
85
+
86
+ - `timeoutMs` (ms) : contrôlé entre deux nœuds ; le dépassement réel vaut au plus une relaxation.
87
+ - `anytime: true` : même contrat pour le seul budget `maxNodes` (statut honnête, champ `search`).
88
+ - `now` : horloge injectable (ms, défaut `Date.now`) — essais déterministes.
89
+ - `search.bound` : meilleure valeur encore possible (≥ objectif en max, ≤ en min) ; `search.gap` =
90
+ \|bound − objective\| / \|objective\| ; 0 si prouvé ; `null` sans solution.
91
+ - **Sans `timeoutMs` ni `anytime`, rien ne change** par rapport à la 0.3.0 (pas de `search`) — y
92
+ compris le défaut historique : budget `maxNodes` atteint, la 0.3.0 répond `optimal` sans preuve.
93
+ Pour un statut honnête, passer `anytime: true`.
44
94
 
45
95
  ## Ce que ce module ne fait PAS
46
96
 
@@ -66,22 +116,15 @@ optimise l'objectif ? », « quel est l'état stationnaire ? ». Responsabilité
66
116
 
67
117
  ```bash
68
118
  npm run build # tsc → dist/ (non versionné)
69
- npm test # 111 essais sur 17 fichiers, via @mostajs/mjs-unit
119
+ npm test # suite @mostajs/mjs-unit, dont le paquet packé chargé en Node brut
70
120
  npm run report # preuve HTML
71
121
  npm run examples # 24 exemples exécutables
122
+ node scripts/catalogue.mjs --write # réengendre les tables de dialectes
72
123
  ```
73
124
 
74
125
  `examples/` est groupé par métier — restaurant, université, réseau, métaheuristiques — et chaque
75
- exemple **se vérifie lui-même** : il se termine par des assertions qui échouent bruyamment. Ce n'est
76
- pas de la décoration : les deux derniers défauts de `bin-packing` sont sortis de l'écriture d'un
77
- exemple, pas d'une relecture. Le test qui existait prouvait qu'une restriction `allowedBins` était
78
- *respectée* — jamais qu'elle était servie **en concurrence**, et c'est par là que le défaut passait.
79
-
80
- ## Livrables (DEVRULES §9)
126
+ exemple **se vérifie lui-même** : il se termine par des assertions qui échouent bruyamment.
81
127
 
82
- **Présents** : `docs/00-CATALOGUE-ALGOS.md`, `docs/03-PLAN-DEV-DIALECTES-LOT-2.md`,
83
- `docs/DEVTEST-PLAN.ro-pla.json` (#4), `docs/articles/17-ARTICLE-ALGOS-RO-FILE-ATTENTE.md` (#17).
128
+ ## Licence
84
129
 
85
- **Manquants** : les treize autres, dont l'état de l'art (#1) et l'audit (#2). Ce module a été bâti
86
- avant que les 17 livrables ne soient tenus systématiquement ; ils restent à rédiger, et l'article
87
- existant attend une vérification de ses sources avant diffusion.
130
+ AGPL-3.0-or-later — voir `LICENSE`.
@@ -37,7 +37,8 @@ export function anneal(problem) {
37
37
  export const annealDialect = {
38
38
  name: 'anneal',
39
39
  kind: 'metaheuristic',
40
- capabilities: { exact: false, online: false },
40
+ shape: { fields: ['initial', 'energy', 'neighbor'] },
41
+ capabilities: { exact: false, online: false, maxSize: null },
41
42
  solve(problem) {
42
43
  return anneal(problem);
43
44
  },
@@ -119,8 +119,9 @@ export function binPacking(problem) {
119
119
  export const binPackingDialect = {
120
120
  name: 'bin-packing',
121
121
  kind: 'scheduling',
122
+ shape: { fields: ['items', 'bins'] },
122
123
  // NP-difficile : heuristique assumée. La borne inférieure rendue dit la distance à l'optimum.
123
- capabilities: { exact: false, online: false },
124
+ capabilities: { exact: false, online: false, maxSize: null },
124
125
  solve(problem) {
125
126
  return binPacking(problem);
126
127
  },
@@ -105,7 +105,8 @@ export function criticalPath(problem) {
105
105
  export const criticalPathDialect = {
106
106
  name: 'critical-path',
107
107
  kind: 'scheduling',
108
- capabilities: { exact: true, online: false },
108
+ shape: { fields: ['activities'] },
109
+ capabilities: { exact: true, online: false, maxSize: null },
109
110
  solve(problem) {
110
111
  return criticalPath(problem);
111
112
  },
@@ -39,7 +39,8 @@ export function solveCsp(variables, domains, constraints) {
39
39
  export const cspDialect = {
40
40
  name: 'backtrack-csp',
41
41
  kind: 'csp',
42
- capabilities: { exact: true, online: false },
42
+ shape: { fields: ['variables', 'domains', 'constraints'] },
43
+ capabilities: { exact: true, online: false, maxSize: null },
43
44
  solve(problem) {
44
45
  return solveCsp(problem.variables, problem.domains, problem.constraints);
45
46
  },
@@ -110,7 +110,8 @@ export function forecast(problem) {
110
110
  export const forecastDialect = {
111
111
  name: 'forecast',
112
112
  kind: 'simulation',
113
- capabilities: { exact: false, online: true },
113
+ shape: { fields: ['series', 'horizon'] },
114
+ capabilities: { exact: false, online: true, maxSize: null },
114
115
  solve(problem) { return forecast(problem); },
115
116
  };
116
117
  //# sourceMappingURL=forecast.js.map
@@ -86,7 +86,8 @@ export function genetic(problem) {
86
86
  export const geneticDialect = {
87
87
  name: 'genetic',
88
88
  kind: 'metaheuristic',
89
- capabilities: { exact: false, online: false },
89
+ shape: { fields: ['population', 'fitness', 'crossover', 'mutate'] },
90
+ capabilities: { exact: false, online: false, maxSize: null },
90
91
  solve(problem) { return genetic(problem); },
91
92
  };
92
93
  //# sourceMappingURL=genetic.js.map
@@ -71,7 +71,11 @@ export function hungarian(cost) {
71
71
  export const hungarianDialect = {
72
72
  name: 'hungarian',
73
73
  kind: 'assignment',
74
+ shape: { fields: ['cost'] },
74
75
  capabilities: { exact: true, online: true, maxSize: 1000 },
76
+ // Taille : ordre de la matrice des coûts (unité de `maxSize`).
77
+ size: (p) => (Array.isArray(p?.cost) ? p.cost.length : null),
78
+ sizeUnit: "ordre de la matrice des coûts",
75
79
  solve(problem) {
76
80
  return hungarian(problem.cost);
77
81
  },
@@ -95,9 +95,10 @@ export function knapsack(problem) {
95
95
  export const knapsackDialect = {
96
96
  name: 'knapsack',
97
97
  kind: 'milp',
98
+ shape: { fields: ['items', 'capacity'] },
98
99
  // EXACT : la programmation dynamique rend l'optimum, contrairement à toute heuristique de
99
100
  // remplissage. Le prix est la mémoire, gardée par `maxCells`.
100
- capabilities: { exact: true, online: false },
101
+ capabilities: { exact: true, online: false, maxSize: null },
101
102
  solve(problem) { return knapsack(problem); },
102
103
  };
103
104
  //# sourceMappingURL=knapsack.js.map
@@ -43,7 +43,8 @@ export function lagrangian(problem) {
43
43
  export const lagrangianDialect = {
44
44
  name: 'lagrangian',
45
45
  kind: 'lp',
46
- capabilities: { exact: false, online: false },
46
+ shape: { fields: ['c', 'linkingA', 'linkingB', 'subA', 'subB'] },
47
+ capabilities: { exact: false, online: false, maxSize: null },
47
48
  solve(problem) {
48
49
  return lagrangian(problem);
49
50
  },
@@ -143,7 +143,8 @@ export function listScheduling(problem) {
143
143
  export const listSchedulingDialect = {
144
144
  name: 'list-scheduling',
145
145
  kind: 'scheduling',
146
- capabilities: { exact: false, online: false },
146
+ shape: { fields: ['tasks', 'capacities'] },
147
+ capabilities: { exact: false, online: false, maxSize: null },
147
148
  solve(problem) {
148
149
  return listScheduling(problem);
149
150
  },
@@ -111,7 +111,11 @@ export function markovAbsorbing(P) {
111
111
  export const markovDialect = {
112
112
  name: 'markov',
113
113
  kind: 'markov',
114
+ shape: { fields: ['P'] },
114
115
  capabilities: { exact: true, online: true, maxSize: 500 },
116
+ // Taille : nombre d'états (unité de `maxSize`).
117
+ size: (p) => (Array.isArray(p?.P) ? p.P.length : null),
118
+ sizeUnit: "nombre d'états",
115
119
  solve(problem) {
116
120
  const P = problem.P;
117
121
  const query = problem.query ?? 'stationary';
@@ -142,8 +142,9 @@ export function matching(problem) {
142
142
  export const matchingDialect = {
143
143
  name: 'matching',
144
144
  kind: 'assignment',
145
+ shape: { fields: ['edges'], test: (p) => Array.isArray(p.edges) && p.edges.every((e) => Array.isArray(e) || (e != null && 'a' in e && 'b' in e)), testLabel: 'arêtes non orientées [a, b] ou { a, b }' },
145
146
  // EXACT : Blossom rend un couplage de cardinalité MAXIMALE, y compris sur cycles impairs.
146
- capabilities: { exact: true, online: false },
147
+ capabilities: { exact: true, online: false, maxSize: null },
147
148
  solve(problem) { return matching(problem); },
148
149
  };
149
150
  //# sourceMappingURL=matching.js.map
@@ -98,7 +98,8 @@ export function maxFlow(problem) {
98
98
  export const maxFlowDialect = {
99
99
  name: 'max-flow',
100
100
  kind: 'flow',
101
- capabilities: { exact: true, online: false },
101
+ shape: { fields: ['edges', 'source', 'sink'], test: (p) => Array.isArray(p.edges) && p.edges.every((e) => e != null && typeof e.capacity === 'number'), testLabel: 'chaque arête porte une `capacity` numérique' },
102
+ capabilities: { exact: true, online: false, maxSize: null },
102
103
  solve(problem) { return maxFlow(problem); },
103
104
  };
104
105
  //# sourceMappingURL=max-flow.js.map
@@ -51,7 +51,10 @@ export function valueIteration(transition, reward, gamma, epsilon = 1e-9, maxIte
51
51
  export const mdpDialect = {
52
52
  name: 'mdp',
53
53
  kind: 'decision',
54
+ shape: { fields: ['transition', 'reward', 'gamma'] },
54
55
  capabilities: { exact: true, online: false, maxSize: 10000 },
56
+ // Mesure de taille « à établir » (états, ou états × actions ?) : la borne reste déclarée, son
57
+ // dépassement n'est pas jugé tant que l'unité n'est pas fixée.
55
58
  solve(problem) {
56
59
  return valueIteration(problem.transition, problem.reward, problem.gamma, problem.epsilon, problem.maxIter);
57
60
  },
@@ -5,11 +5,20 @@
5
5
  * Programmation linéaire en nombres entiers (mixte) par SÉPARATION & ÉVALUATION :
6
6
  * on résout la relaxation continue via le dialecte `simplex`, puis on BRANCHE sur
7
7
  * une variable fractionnaire (x ≤ ⌊v⌋ | x ≥ ⌈v⌉) en élaguant les nœuds dont la
8
- * borne ne peut battre l'incumbent. Exact ; bornable par `maxNodes` (anti-explosion).
8
+ * borne ne peut battre l'incumbent. Exact ; bornable par `maxNodes` (anti-explosion) et, depuis la
9
+ * 0.4.0, par un délai `timeoutMs` qui rend la meilleure solution trouvée et l'écart à la borne.
9
10
  */
10
- import type { LpSolution, MilpProblem, SolveOptions, SolverDialect } from '../types.js';
11
- /** Résout un PLNE/MIP par branch & bound (relaxation LP = simplexe). */
12
- export declare function branchAndBound(problem: MilpProblem, opts?: SolveOptions): LpSolution;
11
+ import type { MilpProblem, MilpSolution, SolveOptions, SolverDialect } from '../types.js';
12
+ /**
13
+ * Résout un PLNE/MIP par branch & bound (relaxation LP = simplexe), en profondeur d'abord
14
+ * (branche `x ≤ ⌊v⌋` avant `x ≥ ⌈v⌉`).
15
+ *
16
+ * Mode « au fil de l'eau » (0.4.0), dès que `opts.timeoutMs` est donné ou `opts.anytime` vrai :
17
+ * arrêt au délai ou au budget de nœuds avec la MEILLEURE solution trouvée, statut honnête
18
+ * (`optimal` prouvé, `feasible`, `unknown`, `infeasible`, `unbounded`) et compte rendu `search`
19
+ * (nœuds, durée, borne, écart). Sinon : le résultat de la 0.3.0, au champ près.
20
+ */
21
+ export declare function branchAndBound(problem: MilpProblem, opts?: SolveOptions): MilpSolution;
13
22
  /** Dialecte de solveur exposant le branch & bound (PLNE/MIP). */
14
- export declare const milpDialect: SolverDialect<MilpProblem, LpSolution>;
23
+ export declare const milpDialect: SolverDialect<MilpProblem, MilpSolution>;
15
24
  //# sourceMappingURL=milp.d.ts.map