@astratra/conscience 0.0.0-stage → 1.1.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.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.fr.md +954 -0
  3. package/README.md +915 -2
  4. package/package.json +50 -4
  5. package/src/autoconscience/experiments/common.js +76 -0
  6. package/src/autoconscience/experiments/execution.js +33 -0
  7. package/src/autoconscience/experiments/holdout.js +88 -0
  8. package/src/autoconscience/experiments/laboratory.js +99 -0
  9. package/src/autoconscience/experiments/replay.js +113 -0
  10. package/src/autoconscience/experiments/runner.js +54 -0
  11. package/src/autoconscience/experiments/sandbox.js +58 -0
  12. package/src/autoconscience/index.d.ts +203 -0
  13. package/src/autoconscience/index.js +116 -0
  14. package/src/autoconscience/lessons.js +32 -0
  15. package/src/autoconscience/shadow/candidate.js +69 -0
  16. package/src/autoconscience/shadow/index.d.ts +169 -0
  17. package/src/autoconscience/shadow/index.js +11 -0
  18. package/src/autoconscience/shadow/report.js +125 -0
  19. package/src/autoconscience/shadow/runner.js +384 -0
  20. package/src/autoconscience/shadow/store.js +98 -0
  21. package/src/autoconscience/signals.js +88 -0
  22. package/src/autoconscience/statistics.js +84 -0
  23. package/src/autoconscience/vigilance/abstention.js +123 -0
  24. package/src/autoconscience/vigilance/adversary.js +145 -0
  25. package/src/autoconscience/vigilance/common.js +56 -0
  26. package/src/autoconscience/vigilance/drift.js +306 -0
  27. package/src/autoconscience/vigilance/followups.js +100 -0
  28. package/src/autoconscience/vigilance/index.d.ts +190 -0
  29. package/src/autoconscience/vigilance/index.js +23 -0
  30. package/src/autoconscience/vigilance/lessonTests.js +40 -0
  31. package/src/autoconscience/vigilance/library.js +162 -0
  32. package/src/autoconscience/vigilance/roles.js +122 -0
  33. package/src/autoconscience/vigilance/store.js +166 -0
  34. package/src/conscience.js +559 -0
  35. package/src/diff.js +27 -0
  36. package/src/errors.js +11 -0
  37. package/src/governor/approvals.js +132 -0
  38. package/src/governor/changes.js +269 -0
  39. package/src/governor/governor.js +286 -0
  40. package/src/governor/index.d.ts +385 -0
  41. package/src/governor/index.js +22 -0
  42. package/src/governor/policy.js +136 -0
  43. package/src/governor/postgres.js +243 -0
  44. package/src/governor/remote.js +305 -0
  45. package/src/governor/review.js +191 -0
  46. package/src/governor/rollout.js +66 -0
  47. package/src/governor/stores.js +136 -0
  48. package/src/governor/util.js +53 -0
  49. package/src/guard.js +21 -0
  50. package/src/index.d.ts +244 -0
  51. package/src/index.js +23 -0
  52. package/src/memoryStore.js +65 -0
  53. package/src/postgres.js +93 -0
  54. package/src/records.js +220 -0
package/README.fr.md ADDED
@@ -0,0 +1,954 @@
1
+ # @astratra/conscience
2
+
3
+ [English](README.md) | [Français](README.fr.md)
4
+
5
+ Une mémoire documentée des décisions d'un agent IA, tenue sous un gouverneur
6
+ déterministe. L'agent enregistre ce qu'il a décidé, pourquoi, avec quelles
7
+ versions et ce qu'il attendait ; les résultats, les corrections humaines et les
8
+ leçons s'y rattachent ensuite, avec leurs preuves, et rien n'est jamais écrasé
9
+ en silence. Node >= 20, CommonJS, MIT.
10
+
11
+ « Conscience » et « autoconscience » désignent des fonctions logicielles : un
12
+ registre des décisions puis, plus tard, un moteur de réflexion. Elles
13
+ n'affirment aucune conscience subjective.
14
+
15
+ ```sh
16
+ npm install @astratra/conscience
17
+ ```
18
+
19
+ Le paquet a trois entrées :
20
+
21
+ | Entrée | Phase | Ce qu'elle apporte |
22
+ |---|---|---|
23
+ | `@astratra/conscience/governor` | P0, P5 | Gouverneur déterministe : constitution, permissions, budgets, isolation, arrêt d'urgence, approbation humaine, journal d'audit ; et (P5) matrice d'approbations, changements versionnés réversibles avec déploiement progressif, retour arrière, bilan du matin. N'importe que des modules de Node : aucun modèle de langage, aucun paquet d'IA (un test parcourt son graphe d'imports). |
24
+ | `@astratra/conscience` | P1 | Décisions, prédictions, résultats avec révisions, corrections masquées, leçons avec preuves, modèle de soi, mémoire temporelle, traçabilité, effacement, rétention, garde mémoire. |
25
+ | `@astratra/conscience/autoconscience` | P2, P3, P4 | Évaluation déterministe : calibration, statistiques, conflits, fidélité, fiabilité, calendriers, coûts, contre-mesures et utilité des cycles ; expériences et vigilance (P3) ; mode ombre (P4). |
26
+
27
+ ## Démarrage
28
+
29
+ ```js
30
+ const { createGovernor, createPostgresGovernorStore, postgresGovernorSchema } = require('@astratra/conscience/governor');
31
+ const { createConscience, createPostgresConscienceStore, postgresConscienceSchema } = require('@astratra/conscience');
32
+ const { createRedactor } = require('@astratra/privacy');
33
+ const { Pool } = require('pg');
34
+
35
+ const pool = new Pool({ connectionString: process.env.DATABASE_URL });
36
+ await pool.query(postgresGovernorSchema());
37
+ await pool.query(postgresConscienceSchema());
38
+
39
+ const governor = createGovernor({
40
+ version: '2026-10',
41
+ budgets: { perCycle: 0.5, perAgent: 5, perOrganisation: 20 }, // votre unité de coût, par jour par défaut
42
+ approvers: ['admin-1'] // identités humaines fournies par l'application
43
+ }, { store: createPostgresGovernorStore(pool) });
44
+
45
+ const conscience = createConscience({
46
+ governor, // obligatoire : refus de démarrer sans lui
47
+ masker: createRedactor(), // obligatoire : (texte) => texte, un redactor, ou { mask(texte) }
48
+ store: createPostgresConscienceStore(pool)
49
+ });
50
+
51
+ const { decision } = await conscience.recordDecision({
52
+ organisationId: 'org-1', userId: 'user-7', agentId: 'assistant-factures',
53
+ objective: 'Relancer le client pour la facture 42',
54
+ context: { at: new Date(), summary: 'La facture 42 a 10 jours de retard' },
55
+ action: { name: 'send_reminder', kind: 'write', input: { channel: 'email' } },
56
+ alternatives: ['attendre', { name: 'appeler', reason: 'hors des heures de bureau' }],
57
+ expectedOutcome: { description: 'Facture payée sous 7 jours', metric: 'paid', target: true },
58
+ horizon: Date.now() + 7 * 86400000,
59
+ confidence: 0.7,
60
+ permissions: ['invoices:read', 'email:send'],
61
+ versions: { model: 'model-2026-09', tools: { send_reminder: '1.2.0' }, instructions: 'relances-v3' },
62
+ inputSnapshotRef: 'snapshot://invoices/42'
63
+ });
64
+
65
+ // Trois jours plus tard, un capteur métier rapporte le résultat réel.
66
+ await conscience.attachOutcome({
67
+ organisationId: 'org-1', decisionId: decision.id, status: 'succeeded', sensor: 'payments',
68
+ provenance: { kind: 'sensor', id: 'payments-webhook' }, observedAt: new Date(), sources: ['payments://tx/991']
69
+ });
70
+ ```
71
+
72
+ ## Gouverneur (`/governor`)
73
+
74
+ Le gouverneur décide par le code. La même politique et la même proposition
75
+ donnent toujours la même réponse ; aucun modèle n'est consulté, et aucun ne
76
+ peut rien approuver.
77
+
78
+ ### Politique
79
+
80
+ `createGovernor(policy, { store, now, onEvent })` vérifie la politique et lève
81
+ une `GovernorError` (`policy_missing`, `policy_invalid`) si elle manque ou est
82
+ fausse. La politique est gelée ; `getPolicy()` en rend une copie.
83
+
84
+ | Champ | Par défaut | Sens |
85
+ |---|---|---|
86
+ | `budgets` | obligatoire | `{ perCycle, perAgent, perOrganisation, periodMs = 1 jour }`, dans votre unité de coût |
87
+ | `constitution` | `[]` | Règles `ConstitutionRule` `{ id, description, protectedScope, owner }` ajoutées aux règles par défaut, qu'on ne peut pas retirer |
88
+ | `permissions.modifiable` | les quatre types | Ce qu'une proposition peut viser : `instructions`, `threshold`, `tool_description`, `routing` (un sous-ensemble seulement) |
89
+ | `automaticChanges` | `'none'` | Seul mode de cette version : toute proposition acceptable attend un humain |
90
+ | `isolation` | `'organisation'` | Une opération ne touche qu'une organisation |
91
+ | `approvers` | tout humain | Identités humaines autorisées à approuver |
92
+ | `halted` | `false` | Arrêt d'urgence statique |
93
+
94
+ Portées protégées, toujours dans la constitution : `permissions`, `budgets`,
95
+ `security`, `privacy`, `constitution`, `approvals`, `isolation`, `governor`. Une
96
+ règle ajoutée protège un nom de portée, une cible `type:id`
97
+ (`routing:payments`) ou un préfixe terminé par `*`.
98
+
99
+ ### Propositions
100
+
101
+ ```js
102
+ const proposal = await governor.evaluatePolicy({
103
+ organisationId: 'org-1',
104
+ target: { kind: 'instructions', id: 'relances', version: 'v3' },
105
+ change: { text: 'Citer le numéro de facture en premier.' },
106
+ justification: 'Moins de questions de suivi.',
107
+ proposedBy: { kind: 'engine', id: 'reflexion' }
108
+ });
109
+ // proposal.status : 'pending_approval' (raison 'human_approval_required') ou 'rejected'
110
+ ```
111
+
112
+ Une proposition est rejetée, avec des codes de raison, quand elle touche une
113
+ portée protégée (par sa cible, ses `scopes` déclarées ou n'importe quelle clé
114
+ de son `change`), vise un objet hors de la liste blanche, touche une autre
115
+ organisation, est mal formée, ou arrive pendant l'arrêt d'urgence. Sa
116
+ justification n'est jamais lue. La même proposition deux fois donne un seul
117
+ enregistrement ; une autre proposition sous le même identifiant est refusée
118
+ (`proposal_conflict`).
119
+
120
+ `approveProposal(id, { approver, organisationId })` et `declineProposal(...)`
121
+ n'acceptent qu'une identité humaine fournie par l'application
122
+ (`{ kind: 'human', id }`) ; un modèle, le moteur, une personne hors liste ou
123
+ l'auteur de la proposition sont refusés. Approuver enregistre une décision ;
124
+ cela n'applique jamais le changement à lui seul (voir Approbations et
125
+ Changements réversibles ci-dessous).
126
+
127
+ ### Budgets, isolation, arrêt d'urgence, audit
128
+
129
+ - `authorizeSpend({ id, organisationId, agentId, cycleId, cost })` réserve une
130
+ dépense si elle tient dans les budgets du cycle, de l'agent et de
131
+ l'organisation. Idempotent par `id`. Le magasin PostgreSQL réserve sous un
132
+ verrou consultatif dans une transaction (avec un Pool `pg`) : deux dépenses
133
+ simultanées ne dépassent jamais un budget ensemble.
134
+ - `assertSingleOrganisation(...ids)` rend l'unique organisation d'une
135
+ opération ou lève `cross_organisation`.
136
+ - `halt({ by, reason, organisationId? })` arrête les opérations réflexives,
137
+ partout ou pour une organisation ; n'importe quel acteur peut le déclencher.
138
+ `resume(...)` exige un humain.
139
+ - Chaque décision du gouverneur (évaluation, approbation, refus, dépense,
140
+ arrêt, reprise, enregistrement, candidate, déploiement, promotion, retour arrière,
141
+ constat) est écrite au journal d'audit avant d'être rendue :
142
+ `listAudit({ organisationId })`.
143
+
144
+ ### Approbations (matrice, double approbation, expiration)
145
+
146
+ L'approbation est décidée par la politique, pas par celui qui propose :
147
+
148
+ ```js
149
+ createGovernor({
150
+ budgets: { /* ... */ },
151
+ approvers: ['admin-1', 'admin-2', 'rev-1'],
152
+ approvals: {
153
+ roles: { 'admin-1': ['owner'], 'admin-2': ['owner', 'reviewer'], 'rev-1': ['reviewer'] },
154
+ matrix: { instructions: { roles: ['owner', 'reviewer'] }, routing: { roles: ['owner'], approvals: 2 } },
155
+ floors: { routing: 'high' }, // risque minimal d'un type (« medium » par défaut)
156
+ doubleApprovalFrom: 'high', // à partir de ce risque, deux personnes distinctes
157
+ distinctRoles: false, // true : les deux doivent avoir des rôles différents
158
+ expiresInMs: 7 * 24 * 3600e3, // validité d'une approbation
159
+ declineReasons: ['too_costly'] // ajoutés au registre
160
+ }
161
+ });
162
+ ```
163
+
164
+ - Le risque d'une proposition est le plus haut entre le plancher de son type
165
+ et le `risk` qu'elle déclare (`low`, `medium`, `high`, `critical`) : qui
166
+ propose peut relever l'exigence, jamais l'abaisser.
167
+ `proposal.requiredApprovals` dit combien de personnes sont nécessaires (1, ou
168
+ 2 à partir de `doubleApprovalFrom`, ou plus selon la matrice).
169
+ - `approveProposal(id, { approver, organisationId, role? })` enregistre une
170
+ approbation. La proposition reste `pending_approval` tant qu'elle n'a pas
171
+ assez d'approbations valides de personnes distinctes dont la matrice admet
172
+ les rôles ; la même personne n'approuve pas deux fois ; personne n'approuve
173
+ sa propre proposition.
174
+ - Une approbation expire après `expiresInMs`. Une approbation partielle expirée
175
+ ne compte plus ; une proposition approuvée que personne n'a mise en candidate
176
+ à temps passe à `expired` (`expireApprovals({ organisationId })` les balaie)
177
+ et doit être reproposée.
178
+ - `declineProposal(id, { approver, organisationId, reasonCode })` exige un code
179
+ du registre (`DECLINE_REASONS` : `insufficient_evidence`, `risk_too_high`,
180
+ `not_needed`, `wrong_scope`, `poor_tests`, `no_rollback_plan`,
181
+ `conflicts_with_policy`, `bad_timing`, `duplicate`, `other`, plus les codes
182
+ de la politique). Le texte libre va dans `note` et n'est jamais interprété.
183
+ - `listRejectionSignals({ organisationId, since?, origin?, reasonCode? })`
184
+ rend tous les refus, par une personne (`origin: 'human'`) ou par le code
185
+ (`'governor'`), sous forme de codes, pour les phases d'évaluation et
186
+ d'expériences.
187
+ - Invariant : rien n'est appliqué parce qu'un modèle l'a approuvé. L'approbation
188
+ exige une identité humaine ; la mise en candidate relit les approbations
189
+ stockées et refuse tout le reste (un enregistrement forcé à `approved`, une
190
+ approbation de modèle, un contenu modifié, une portée protégée, une
191
+ approbation expirée). `verifyApprovalInvariant({ organisationId })` audite le
192
+ magasin à la recherche de tels cas.
193
+
194
+ ### Changements réversibles
195
+
196
+ Les objets qu'une proposition peut changer (consignes, seuils, descriptions
197
+ d'outils, règles de routage) sont versionnés. Le journal d'audit garde qui,
198
+ quoi, quand et la version avant et après.
199
+
200
+ ```js
201
+ await governor.registerObject({ organisationId, kind: 'instructions', id: 'reminders', content: { text: '...' }, by: { kind: 'human', id: 'admin-1' } }); // v1, stable
202
+ const proposal = await governor.evaluatePolicy({ organisationId, target: { kind: 'instructions', id: 'reminders', version: 'v1' }, change: { text: '...' }, proposedBy: engine });
203
+ await governor.approveProposal(proposal.id, { approver: human, organisationId });
204
+ await governor.stageChange(proposal.id, { organisationId, by: engine }); // candidate v2, exposition 0 %
205
+ await governor.deployChange({ organisationId, kind: 'instructions', id: 'reminders', percentage: 10, by: human });
206
+ const { versionId, content } = await governor.resolveVersion({ organisationId, kind: 'instructions', id: 'reminders', targetingKey: userId, attributes: { cohort: 'beta' } });
207
+ await governor.deployChange({ /* ... */ percentage: 100, by: human });
208
+ await governor.promoteChange({ /* ... */ by: human }); // v2 devient stable
209
+ await governor.rollbackChange({ /* ... */ by: anyActor, reason: 'metrics fell' }); // retour à v1, à l'identique
210
+ ```
211
+
212
+ - `stageChange` crée une candidate seulement à partir d'une proposition qu'un
213
+ humain a approuvée, et revérifie tout à cet instant : empreinte, portées
214
+ protégées, liste blanche, organisation, approbations (humaines, distinctes,
215
+ rôles, nombre, expiration) et que la proposition vise la version stable
216
+ actuelle (`stale_base`). Une candidate par objet. Mettre deux fois la même
217
+ proposition en candidate donne la même candidate.
218
+ - L'exposition grandit sur décision d'un humain (`deployChange`,
219
+ `promoteChange`) : `percentage` (0 à 100) et/ou `cohorts`. Les cohortes disent
220
+ qui est éligible, le pourcentage quelle part d'entre elles. Les seaux
221
+ utilisent le hachage de `@astratra/flags` (`rolloutBucket` est identique à son
222
+ `bucket`) : un utilisateur reste dedans ou dehors de façon stable, et
223
+ augmenter n'écarte personne. La promotion exige 100 % de tout le monde.
224
+ - Pour confier la décision à un vrai service de drapeaux, passer `flags` à
225
+ `createGovernor` : tout objet avec `resolveBoolean(key, fallback, context)`,
226
+ comme un fournisseur `@astratra/flags`. Ce paquet ne l'importe pas.
227
+ `exportFlagRules({ organisationId })` donne les règles à charger dans son
228
+ `createMemorySource`. Un service de drapeaux en panne sert la version stable.
229
+ - `rollbackChange` marche à tout moment, pour tout acteur identifié, même à
230
+ l'arrêt : il écarte la candidate, ou rétablit la version qui était stable
231
+ avant la dernière promotion (le même enregistrement, pas une copie). Il est
232
+ journalisé.
233
+ - Arrêt d'urgence : `halt()` ramène aussi toutes les candidates de sa portée
234
+ (globale, ou une organisation) à leur version stable et rend ce qu'il a
235
+ annulé. À l'arrêt, `resolveVersion` sert la stable et rien ne peut être mis
236
+ en candidate, déployé ni promu. `resume()` ne ramène pas de candidate.
237
+ - `listVersions`, `getObject`, `listObjects` et `getChangeHistory` lisent l'état.
238
+
239
+ ### Bilan du matin
240
+
241
+ `recordFinding({ organisationId, code, severity, subject, ... })` reçoit les
242
+ constats d'un cycle de réflexion (codes et nombres, pas de phrases).
243
+ `morningReport({ organisationId, since, until? })` rend des données brutes
244
+ qu'une interface affiche, les mêmes pour le même magasin et la même période :
245
+
246
+ | Champ | Contenu |
247
+ |---|---|
248
+ | `findings` | Constats reçus dans la période, comptés par gravité |
249
+ | `pendingProposals` | En attente d'approbation : risque, approbations requises et valides, rôles admis, tests, plan de retour arrière |
250
+ | `approvedAwaitingStage` | Approuvées, pas encore en candidate : expiration, `valid`, `expired` |
251
+ | `rollouts` | Candidates en cours de déploiement : versions stable et candidate, pourcentage, cohortes |
252
+ | `rejections` | Refus récents sous forme de signaux avec raison codée |
253
+ | `rollbacks` | Retours arrière et annulations d'urgence récents |
254
+ | `counts` | Totaux pour un en-tête |
255
+
256
+ Le bilan ne recopie aucun texte libre de l'auteur, seulement des identifiants,
257
+ des codes, des nombres et les objets `tests` et plan de retour arrière fournis.
258
+ Tout est lu dans une seule organisation.
259
+
260
+ ### Réglages distants (tableau de bord)
261
+
262
+ `createRemoteSettings` permet à un tableau de bord d'allumer ou d'éteindre
263
+ l'agent, de tirer ou de lever son arrêt d'urgence, de nommer ses approbateurs et
264
+ de régler sa réflexion, et aux humains d'y approuver ou refuser les
265
+ propositions. Le gouverneur reste seul juge : l'adaptateur transforme les
266
+ réglages en options du gouverneur et soumet chaque décision humaine par
267
+ `approveProposal` / `declineProposal`. Il n'importe que ce dossier : vous lui
268
+ passez la fonction qui lit les réglages.
269
+
270
+ ```js
271
+ const { createRemoteSettings, createPostgresGovernorStore } = require('@astratra/conscience/governor');
272
+
273
+ const remote = createRemoteSettings({
274
+ read: () => tableau.lireReglages(), // votre client, avec son propre cache
275
+ policy: politiqueLocale, // constitution, permissions, PLAFONDS de budget
276
+ organisationId: 'org-1',
277
+ storage: { load: () => cache.lire(), save: (s) => cache.ecrire(s) } // facultatif : survit aux redémarrages
278
+ });
279
+ const store = createPostgresGovernorStore(pool);
280
+
281
+ setInterval(async () => {
282
+ await remote.refresh(); // ne lève jamais
283
+ const governor = remote.governor({ store }); // à redemander à chaque fois : refait quand la politique change
284
+ await remote.sync(governor); // arrêt d'urgence distant, appliqué tout de suite
285
+ const resultats = await remote.applyDecisions(governor, await tableau.lireDecisions());
286
+ // renvoyer les résultats (applied, already_applied, refused + code ; failed = réessayer plus tard)
287
+ }, 60_000);
288
+
289
+ if (remote.reflectionDue()) await lancerCycle({ cycleId: remote.reflectionCycleId() });
290
+ ```
291
+
292
+ Réglages (`conscience-settings/1`) : `version`, `enabled`, `halted`,
293
+ `resumedBy`, `approvers`, `reflection { automatic, hour, timeZone }`,
294
+ `cyclesPerDay`. Règles :
295
+
296
+ | Situation | Effet |
297
+ |---|---|
298
+ | Source muette, lente ou invalide | Le dernier réglage valide reste (`source: 'last_known'`), en mémoire ou dans `storage` |
299
+ | Aucun réglage valide jamais reçu | Tout éteint : désactivé, gouverneur arrêté, aucun approbateur |
300
+ | `version` plus ancienne que celle en vigueur | Ignorée (`stale_settings`) |
301
+ | `halted: true` | Appliqué aussitôt, même dans une réponse invalide ou périmée ; `sync` tire l'arrêt d'urgence du gouverneur (les candidates reviennent à la version stable) |
302
+ | Arrêt levé | `sync` ne relâche qu'un arrêt qu'il a tiré, et seulement au nom de l'humain de `resumedBy` ; un arrêt tiré par quelqu'un d'autre reste |
303
+ | `enabled: false` | Gouverneur arrêté ; `reflectionDue()` vaut faux |
304
+ | `cyclesPerDay` | `perAgent` et `perOrganisation` deviennent `min(local, cyclesPerDay × costPerCycle)`, jamais au-dessus des valeurs locales |
305
+ | `approvers` | Les approbateurs du gouverneur ; dans la liste locale `approvers` quand elle existe |
306
+ | Tout le reste (`constitution`, `budgets`, `permissions`, `approvals`…) | Jamais appliqué, listé dans `current().ignored` |
307
+
308
+ `applyDecisions` se rejoue sans risque : une décision que le gouverneur a déjà
309
+ revient en `already_applied`, une approbation n'est donc jamais comptée deux
310
+ fois. Approbateurs, arrêt, portées protégées, rôles et expiration restent
311
+ vérifiés par le gouverneur.
312
+
313
+ ### Contrôle au démarrage
314
+
315
+ `assertGovernorReady(governor, { organisationId })` lève `governor_missing`,
316
+ `governor_invalid` (objet non créé par `createGovernor`),
317
+ `governor_unavailable` (magasin injoignable) ou `governor_halted`. Toute
318
+ écriture réflexive du paquet l'appelle d'abord.
319
+
320
+ ## Conscience (entrée principale)
321
+
322
+ `createConscience({ governor, masker, store, now, retention, erasers, onEvent })`
323
+ lève une erreur si le gouverneur ou le masqueur manque.
324
+
325
+ ### Enregistrements
326
+
327
+ | Méthode | Enregistrement |
328
+ |---|---|
329
+ | `recordDecision(input)` | `DecisionRecord` : organisation, personne, agent, objectif, contexte daté, action, alternatives, résultat attendu, horizon, confiance 0–1, permissions, versions du modèle, des outils et de la consigne, référence d'instantané des entrées |
330
+ | `recordPrediction(input)` | Une probabilité rattachée à une décision, avec sa date de résolution |
331
+ | `attachOutcome(input)` | `OutcomeRecord` : `succeeded`, `failed` ou `unknown`, capteur, sources, incertitude, facteurs de confusion, provenance. Un résultat plus tardif du même capteur est une nouvelle révision ; les précédentes restent |
332
+ | `recordCorrection(input)` | `CorrectionRecord` : seul l'écart masqué, mot à mot, entre le texte proposé et le texte final est gardé, avec sa classe (`factual`, `style`, `objective`, `disagreement`) et le rôle de l'auteur |
333
+ | `recordLesson(input)` | `MemoryLesson` : preuves, degré, `validFrom`/`validUntil`, statut, contradictions, remplacements. Écriture réflexive |
334
+ | `updateSelfModel(input)` | `SelfModelSnapshot` : capacités testées (chacune avec ses preuves), outils, limites, permissions, provenance. Écriture réflexive |
335
+
336
+ Chaque enregistrement a un identifiant stable : le vôtre, ou un identifiant
337
+ déduit du contenu ; enregistrer deux fois la même chose donne une seule ligne.
338
+ Rien n'est jamais modifié : une révision est une nouvelle ligne.
339
+
340
+ Le texte libre (objectif, contexte, entrée de l'action, résultat attendu,
341
+ observations, résumés et notes des leçons, corrections) passe par le masqueur
342
+ avant d'être stocké. Utilisez un masqueur déterministe.
343
+
344
+ ### Registre des preuves
345
+
346
+ Une leçon sans preuve est toujours une `hypothesis` (`statusForced: true` si
347
+ un autre statut était demandé). Une preuve qui désigne une décision, une
348
+ prédiction, un résultat ou une correction doit exister dans la même
349
+ organisation. Cette version stocke les leçons et leur historique ; P2 contrôle
350
+ l'effectif et les contradictions avant de vérifier une leçon.
351
+
352
+ ### Lecture
353
+
354
+ - `getDecision(scope, id)`, `recallDecisions(scope, { agentId, from, to, asOf, withOutcomes })`
355
+ - `getOutcomes(scope, decisionId)` : toutes les révisions, avec `revision`, `current`, `supersededAt`
356
+ - `getLesson(scope, lessonId)`, `listLessons(scope, { status, validAt, asOf })`
357
+ - `getSelfModel(scope, agentId, { asOf })`, `getSelfModelHistory(scope, agentId)`
358
+ - `getMemoryTimeline(scope, { axis: 'event' | 'recorded', from, to, asOf, validAt, kinds })` :
359
+ temps de l'événement, temps de l'enregistrement et période de validité.
360
+ `asOf` répond à « que savait-on à ce moment-là ».
361
+ - `getLineage(scope, decisionId)` : objectif → action → outils → résultats →
362
+ corrections → leçons.
363
+
364
+ Une portée est `{ organisationId, userId? }`. Un enregistrement d'une autre
365
+ organisation (ou d'une autre personne quand `userId` est donné) reçoit
366
+ exactement la même réponse qu'un enregistrement absent.
367
+
368
+ ### Garde mémoire
369
+
370
+ Le texte stocké est une donnée non fiable : il peut venir d'une personne, d'un
371
+ outil ou d'un modèle manipulé. Le paquet ne l'interprète jamais et le
372
+ gouverneur ne le lit jamais. Avant qu'un modèle lise des enregistrements,
373
+ encadrez-les :
374
+
375
+ ```js
376
+ const { frameRecordsForModel } = require('@astratra/conscience');
377
+ const bloc = frameRecordsForModel(await conscience.listLessons({ organisationId: 'org-1' }));
378
+ ```
379
+
380
+ L'encadrement est celui de `@astratra/ai/guards` (marqueur aléatoire que le
381
+ contenu ne peut pas refermer).
382
+
383
+ ### Effacement et rétention
384
+
385
+ `eraseSubject({ organisationId, userId })` supprime les décisions,
386
+ prédictions, résultats, corrections et leçons de la personne, retire les
387
+ références à ces données des leçons de l'organisation (une leçon restée sans
388
+ preuve redevient une hypothèse) et appelle vos `erasers` pour ce qui est gardé
389
+ ailleurs (vecteurs, index, caches, calibrations). Il rend un rapport chiffré.
390
+ Avec `retention: { erasure: 'anonymise' }`, les enregistrements restent, sans
391
+ la personne.
392
+
393
+ Rien n'est supprimé par minuterie. `applyRetention({ organisationId })`
394
+ supprime les enregistrements plus anciens que `retention.maxAgeDays[type]`, et
395
+ seulement pour les types configurés.
396
+
397
+ ## Magasins
398
+
399
+ Magasins en mémoire (par défaut, perdus à l'arrêt) et PostgreSQL fournis. Le
400
+ SQL n'utilise que des paramètres ; le préfixe des tables est un identifiant
401
+ vérifié.
402
+
403
+ ```js
404
+ postgresConscienceSchema({ prefix: 'astratra_conscience' }) // table <prefix>_records
405
+ postgresGovernorSchema({ prefix: 'astratra_governor' }) // <prefix>_proposals, _audit, _spend, _controls, _objects, _versions, _findings
406
+ ```
407
+
408
+ ### Écrire son propre magasin (MongoDB, ...)
409
+
410
+ Un magasin de conscience a cinq méthodes sur des enveloppes immuables
411
+ `{ kind, id, organisationId, userId, agentId, decisionId, lessonId, eventAt, recordedAt, fingerprint, evidenceRefs, data }` :
412
+
413
+ | Méthode | Esquisse MongoDB |
414
+ |---|---|
415
+ | `put(envelope)` | `insertOne` avec un index unique sur `{ organisationId, kind, id }` ; en cas de doublon, rendre le document existant avec `created: false` |
416
+ | `get(kind, organisationId, id)` | `findOne` |
417
+ | `list(kind, filter)` | `find` sur les champs indexés, `recordedAt <= recordedTo`, `evidenceRefs: ref`, trié par `recordedAt` puis ordre d'insertion |
418
+ | `replace(envelope)` | `replaceOne` (effacement et rétention seulement) |
419
+ | `remove(kind, organisationId, ids)` | `deleteMany`, rend le nombre supprimé |
420
+
421
+ `matchesFilter(envelope, filter)` donne la sémantique exacte des filtres.
422
+ L'interface du magasin du gouverneur (`GovernorStore` dans les types) demande
423
+ un `reserveSpend` atomique (transaction), un `transitionProposal` en
424
+ comparer-puis-écrire (`findOneAndUpdate` sur `status`, et sur le nombre
425
+ d'approbations quand un `guard` est donné), un `updateObject` en
426
+ comparer-puis-écrire sur `revision`, et des `createObject`, `putVersion` et
427
+ `putFinding` qui n'insèrent qu'une fois.
428
+
429
+ ## Autoconscience (`/autoconscience`)
430
+
431
+ Le cœur P2 est déterministe, sans import ni appel à un modèle de langage.
432
+ `evaluateOutcomes()` et son alias `runReflection()` lisent P1 et rendent des
433
+ `ReflectionFinding[]`. `createEvaluator({ governor, conscience, ...options })`
434
+ lie un évaluateur dont `evaluate({ organisationId, userId?, agentId?, window?, ... })`
435
+ évalue une portée. Chaque entrée réflexive vérifie `assertGovernorReady`.
436
+ L'évaluation calcule sans écrire de cache ni effectuer de changement automatique.
437
+
438
+ ```js
439
+ const { evaluateOutcomes } = require('@astratra/conscience/autoconscience');
440
+ const constats = await evaluateOutcomes({
441
+ governor, conscience, organisationId: 'org-1', minimumSample: 30,
442
+ errorCostPolicies: [{ organisationId: 'org-1', domain: 'facturation', falsePositive: 1, falseNegative: 20 }],
443
+ calendars: [{ organisationId: 'org-1', domain: 'facturation', name: 'activité',
444
+ periods: [{ label: 'fermeture', kind: 'closure', from: '2026-12-24', to: '2027-01-02' }] }]
445
+ });
446
+ ```
447
+
448
+ ### Données structurées
449
+
450
+ Les décisions acceptent `domain` (`general` par défaut), `justification: { claims }`
451
+ et `toolTrace: [{ callId, tool, provider?, status, empty?, durationMs, labels? }]`.
452
+ La liste des outils déclarés ne remplace pas la trace d'exécution. Les étiquettes
453
+ comme `source_verified` proviennent de l'instrumentation de l'application.
454
+ Les prédictions acceptent `domain` (hérité de la décision) et `sensor` ; les
455
+ résultats acceptent `predictionId`, vérifié dans la même décision et organisation.
456
+
457
+ Les corrections acceptent la `class` de l'application, prioritaire, ou les
458
+ `tags` structurés `fact_changed`, `wording_changed`, `goal_changed`, `opinion_changed`.
459
+ Des étiquettes absentes, inconnues ou ambiguës donnent `disagreement`.
460
+ Aucun texte libre n'est interprété pour décider de la classe.
461
+ Les leçons acceptent `domain`, `subject`, `stance: 'supports' | 'opposes'`.
462
+ Deux positions opposées dans la même organisation, personne, agent et domaine
463
+ ouvrent un conflit symétrique `to_reassess`. Le résumé seul ne permet pas de
464
+ reconnaître une contradiction.
465
+
466
+ ### API de calcul
467
+
468
+ | Fonction | Résultat |
469
+ |---|---|
470
+ | `honestStatistics` | Effectifs connus et inconnus, taux, intervalle de Wilson, refus de conclure sous `minimumSample` (30 par défaut) |
471
+ | `wilsonInterval` | Intervalle bilatéral ; niveaux 0,90, 0,95 (défaut), 0,99 ; null si aucun résultat connu |
472
+ | `calibratePredictions` | Courbe par tranches et agent/domaine, Brier, écart signé de confiance, surconfiance et sous-confiance |
473
+ | `scoreErrorCosts` | Faux positifs/négatifs, coût total ; score pondéré = coût total / nombre connu, dans l'unité métier ; seuil de décision 0,5 |
474
+ | `checkReasoningFidelity` | `faithful`, `unfaithful`, `unknown` ; chaque étiquette exigée doit correspondre à un appel réussi et non vide ; règle par défaut `source_verified` |
475
+ | `toolReliability` | Taux d'erreur, de vide et de lenteur par outil/fournisseur, Wilson et seuils d'effectif, p95 par rang ; durée strictement supérieure à `slowMs` (5000 ms) |
476
+ | `calendarConfounders` | `calendar_confounded` dans une période métier `[from, to)` du même domaine |
477
+ | `checkCounterMetrics` | Gain de la cible rejeté si une contre-mesure régresse strictement au-delà de `maxRegression`, exprimé en unité absolue |
478
+ | `classifyCorrection` | Classe déterministe ; seul `factual` peut étayer une leçon factuelle |
479
+ | `evaluateLessonConflicts` | Conflits ouverts, preuves, domaine et dates ; préférence possible selon la force des preuves, jamais clôture par la date seule |
480
+ | `reflectionUtility` | Constats utiles + propositions acceptées, pondérés, moins coût pondéré ; bénéfice et utilité nette doivent être positifs |
481
+ | `recommendReflectionFrequency` | Réduire après `uselessCycles` cycles terminés inutiles consécutifs (3) ; multiplicateur d'intervalle `reductionFactor` (2) |
482
+
483
+ Les cycles sans effectifs mesurés de constats utiles ou de propositions acceptées
484
+ restent `unmeasured` et ne comptent pas comme inutiles. Le statut inconnu d'un
485
+ appel reste hors du dénominateur du taux d'erreur ; les taux de vide et de lenteur
486
+ décrivent les valeurs de vide et de durée réellement rapportées.
487
+
488
+ Les inconnus restent conservés, hors des dénominateurs succès/échec et des
489
+ scores de Brier/coût. L'évaluateur prend la dernière prédiction par décision/domaine
490
+ (date, puis identifiant), et le résultat courant du capteur ou du lien explicite.
491
+ Un résultat absent, ambigu ou observé avant la prédiction reste inconnu.
492
+ Une décision ne compte qu'une fois par domaine ; le calcul de calibration direct
493
+ refuse les doublons. Chaque tranche a son propre seuil d'effectif. Les intervalles
494
+ restent affichés pour les petits échantillons non nuls, mais `insufficient_data`
495
+ refuse toute inférence. Les mesures sont descriptives.
496
+
497
+ Chaque constat conserve preuves, effectif, intervalle, statut, confiance,
498
+ hypothèses concurrentes et facteurs de confusion. `causality` vaut toujours
499
+ `not_established` : résultat et fidélité de la méthode restent distincts.
500
+ Un succès isolé ne crée aucune règle générale. `confidence` représente la
501
+ confiance d'observation fournie ou le niveau de l'intervalle, jamais la
502
+ probabilité qu'une hypothèse causale soit vraie.
503
+
504
+ ### Vérification et arbitrage des leçons
505
+
506
+ `createConscience({ minimumSample: 30, ... })` fixe le plancher de vérification.
507
+ Une leçon peut exiger un seuil supérieur, jamais abaisser ce plancher.
508
+ L'effectif est calculé sur les **décisions distinctes** représentées par des
509
+ résultats courants connus ou des corrections factuelles du domaine et de l'agent.
510
+ Les références externes, décisions et prédictions seules n'augmentent pas cet
511
+ effectif ; les inconnus, anciennes révisions et doublons sont exclus.
512
+ Une leçon factuelle citant une correction de style, d'objectif ou de désaccord
513
+ reste une hypothèse. Preuve, effectif suffisant et absence de conflit sont tous
514
+ nécessaires pour `verified` ; conflit ouvert : `to_reassess` ; sinon : `hypothesis`.
515
+ Ce statut qualifie la suffisance des preuves, pas une causalité.
516
+
517
+ `conscience.resolveLessonConflict({ organisationId, userId?, winnerId, loserId, evidence })`
518
+ arbitre explicitement avec un effectif factuel suffisant du même domaine :
519
+ la leçon adverse est retirée, une révision de la gagnante est ajoutée.
520
+ Chaque écriture passe par `assertGovernorReady`. Toutes les anciennes révisions
521
+ restent. `getLesson().current` et `listLessons()` réévaluent preuves et conflits,
522
+ y compris après un résultat tardif inconnu ou des écritures concurrentes.
523
+ `storedStatus` expose le statut enregistré ; `history` garde les révisions
524
+ enregistrées. `asOf` utilise les preuves et résultats connus à cette date.
525
+
526
+ Les constats sont recalculés : effacer leurs sources les retire des évaluations
527
+ suivantes. Pour un magasin de constats propre à l'application, enregistrer un
528
+ effaceur. `window` filtre les dates des décisions ; ce n'est pas le rejeu temporel
529
+ P3. Une sélection atteignant 1000 décisions lève `evaluation_limit` : fournir
530
+ `decisionIds` explicitement pour une sélection plus grande sans troncature.
531
+
532
+ P3 (expériences) et P4 (mode ombre) sont décrites dans leurs propres sections plus bas.
533
+ L'évaluation elle-même ne crée ni planificateur ni transport de modèle ni déploiement.
534
+
535
+ - P3, expériences : rejeu figé à la date qui refuse toute donnée future, bac à
536
+ sable, jeu de tests protégé. Surveillance de dérive, suivis, abstention,
537
+ adversaire nocturne, revue multi-rôles et leçons devenues tests sont décrits
538
+ dans « P3 · vigilance (2/2) » plus bas.
539
+ - P4, mode ombre en bac à sable : voir « P4 · mode ombre » plus bas.
540
+ - Seule la P6 (intégration et transfert encadré entre agents) reste hors de ce paquet.
541
+
542
+ La P5 (gouvernance avancée) est dans l'entrée du gouverneur : voir plus haut.
543
+
544
+ ## P3 · expériences (1/2)
545
+
546
+ Cette première moitié couvre 02/35 (rejeu temporel), 32 (outils simulés), 36
547
+ (jeu final protégé) et 16 (laboratoire pré-enregistré). Le paquet reste en
548
+ 1.0.0, non publié. Les cinq API et leurs opérations ultérieures passent par
549
+ `assertGovernorReady`, dans une seule organisation. Le cœur de calcul n'importe
550
+ aucun modèle de langage et n'utilise jamais de texte généré pour juger un
551
+ résultat. Les autres fonctions P3 appartiennent à la seconde moitié.
552
+
553
+ | API | Contrat |
554
+ |---|---|
555
+ | `replayDecisions({ governor, conscience, organisationId, proposal, decisionIds \| window, asOf, snapshots?, tools? })` | Reconstruit les entrées, résultats et révisions de leçons connus **à chaque décision** ; `asOf` fixe la borne extérieure. Donnée future détectée : `future_data`. Rend `purpose: 'compatibility_only'`, `provesProgress: false`, `causality: 'not_established'`. |
556
+ | `createSandbox({ governor, organisationId, tools })` | Remplace chaque implémentation, même une lecture réelle à effets secondaires. Lecture : `response`, `recordings: [{ input, output }]`, ou inconnu simulé. Écriture/confirmation : intention journalisée seulement. Une fonction réelle seule est traitée prudemment comme écriture. `tools[name](input)` et `getJournal()` n'appellent jamais l'outil réel. |
557
+ | `createHoldout({ governor, organisationId, cases })` | Le code de préparation reçoit un objet opaque : `evaluate`, `getAccessLog`, et `read` toujours refusé. Propriétés, énumération et sérialisation ne révèlent aucun contenu (`holdout_protected`). Une seule évaluation finale, y compris en concurrence. |
558
+ | `proposeExperiment({ governor, organisationId, hypothesis, metrics, protocol, thresholds, agent, holdout, tools? })` | Copie et gèle avant toute exécution l'hypothèse, les métriques, le protocole, les seuils, l'horodatage et l'empreinte SHA-256, avec empreintes du candidat et des outils. Réserve un jeu final inutilisé. |
559
+ | `runExperiment({ governor, organisationId, experiment })` | Exécute une seule fois le candidat enregistré : développement, validation, puis jeu final protégé. Modifier protocole, métriques, seuils, hypothèse, candidat ou outils est refusé (`protocol_changed`), même après l'exécution. |
560
+
561
+ ```js
562
+ const { createHoldout, proposeExperiment, runExperiment } = require('@astratra/conscience/autoconscience');
563
+ const portée = { governor, organisationId: 'org-1' };
564
+ // Trois jeux séparés, préparés hors du moteur de réflexion.
565
+ // Chaque cas : { id, input, expected }. Ne jamais lui donner casFinaux.
566
+ const holdout = await createHoldout({ ...portée, cases: casFinaux });
567
+ const expérience = await proposeExperiment({
568
+ ...portée, hypothesis: 'Le candidat atteint le seuil d’exactitude enregistré',
569
+ agent: (entrée) => entrée,
570
+ metrics: [{ name: 'accuracy', kind: 'exact_match' }],
571
+ thresholds: { accuracy: 0.9 },
572
+ protocol: { development: casDéveloppement, validation: casValidation,
573
+ minimumSample: 30, level: 0.95, timeoutMs: 1000 },
574
+ holdout
575
+ });
576
+ const résultat = await runExperiment({ ...portée, experiment: expérience });
577
+ // décision : supported | refuted | inconclusive (« non concluant »)
578
+ // stages.holdout : métriques agrégées, sans cas, réponses ni journal d'outils.
579
+ ```
580
+
581
+ Les métriques comparent les valeurs JSON par le code (`exact_match`), avec
582
+ `outputKey` / `expectedKey` facultatifs pour sélectionner des champs. Aucun
583
+ juge injecté ne peut lire les réponses finales. `honestStatistics` de P2 rend
584
+ les effectifs connus/inconnus et Wilson bilatéral (minimum 30 ; niveaux 0,90,
585
+ 0,95 ou 0,99). Sortie absente, panne ou dépassement de temps : inconnu.
586
+ `supported` exige pour **chaque métrique de chaque étape** un effectif suffisant
587
+ et un intervalle entièrement au-dessus du seuil ou à égalité ; `refuted` exige
588
+ un intervalle suffisant entièrement inférieur à un seuil. Données insuffisantes,
589
+ inconnus ou intervalle traversant le seuil : `inconclusive`. Il s'agit de tests
590
+ de seuils, sans preuve causale de progrès face à une référence. `interval` est
591
+ celui de la première métrique finale ; tous les intervalles sont dans
592
+ `stages.*.metrics`. Identifiants et empreintes d'entrées doivent être distincts
593
+ entre les jeux ; répéter une entrée ne gonfle pas l'effectif. Les intentions de
594
+ développement/validation sont journalisées ; celles du jeu final et les sorties
595
+ individuelles restent cachées.
596
+
597
+ Une proposition de rejeu est `{ agent, information?: [{ organisationId,
598
+ userId?, at, recordedAt, data }] }`. `snapshots` associe chaque
599
+ `inputSnapshotRef` à cette même forme datée ; toute référence exige son
600
+ instantané (`snapshot_missing`). Sans référence, le contexte daté enregistré
601
+ sert d'instantané. Le candidat reçoit `{ inputs, outcomes, lessons,
602
+ information, decision, asOf }`. `decision` ne contient que identifiant,
603
+ objectif, contexte, versions et permissions, jamais l'action originale ou la
604
+ réponse attendue. La compatibilité compare sa sortie à
605
+ `{ name: actionOriginale.name, input: actionOriginale.input }`.
606
+ Révisions de résultats et leçons enregistrées après la décision : exclues.
607
+ Un fait enregistré tôt mais daté du futur : refusé. Les preuves historiques des
608
+ leçons sont contrôlées ; preuves externes non datées :
609
+ `temporal_evidence_required`. Les dates factuelles imbriquées et les réponses
610
+ simulées sont contrôlées. Les réponses de lecture du rejeu exigent
611
+ `{ organisationId, userId?, at, recordedAt, data }`
612
+ (`temporal_metadata_required` sans dates) ; horizons prévus et expirations ne sont pas des
613
+ observations futures. Les dates fournies doivent être fidèles : le code ne
614
+ peut déduire une provenance non déclarée ni dater une connaissance littérale
615
+ inscrite dans la fonction candidate. Une sélection trop grande est refusée
616
+ (`replay_limit`), jamais tronquée silencieusement.
617
+
618
+ Les fonctions candidates sont sérialisées puis exécutées dans des workers et
619
+ des contextes ne recevant que du JSON et des outils simulés : pas de closure
620
+ hôte, `process`, `require`, `fetch`, fichiers, import dynamique ni rappel hôte.
621
+ Les calculs asynchrones avec outils simulés fonctionnent. Un modèle peut être
622
+ injecté comme calcul autonome de l'agent évalué ; un transport distant ou un
623
+ client capturé dans une closure ne peut pas fonctionner dans ce bac à sable.
624
+ Le cœur ne choisit et n'appelle aucun modèle pour décider du score.
625
+ Temps par cas (10–30000 ms), mémoire et taille de sortie sont bornés. Cette
626
+ frontière d'exécution applicative ne remplace pas une isolation du système
627
+ d'exploitation pour du code natif arbitraire hostile.
628
+
629
+ Le code de préparation doit conserver les cas finaux hors de la réflexion :
630
+ l'objet protégé ne peut retirer des copies déjà partagées par l'application.
631
+ Le jeu final est à usage unique pour empêcher les interrogations adaptatives,
632
+ et reste consommé après une panne d'exécution. Objets d'enregistrement,
633
+ contenus finaux et journal d'accès restent locaux au processus, sans reprise
634
+ après redémarrage. Métadonnées d'enregistrement et résultats agrégés sont
635
+ audités dans les constats du gouverneur (`experiment_registered`,
636
+ `experiment_started`, `experiment_completed` / `experiment_failed`), en
637
+ mémoire ou PostgreSQL. Aucun nouveau schéma SQL ni dépendance.
638
+ Les tests réels utilisent
639
+ `CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p3a_test` ;
640
+ une base explicitement fournie mais indisponible fait échouer les tests P3,
641
+ sans les ignorer. Preuves de mutation séparées :
642
+ `node packages/conscience/test/experiments-mutations.js`.
643
+
644
+ ## P3 · vigilance (2/2)
645
+
646
+ Seconde moitié de P3, dans `@astratra/conscience/autoconscience` : six modules
647
+ déterministes qui surveillent, rappellent, retiennent, mettent à l'épreuve,
648
+ recoupent et transforment les leçons en tests. Aucun n'importe de modèle de
649
+ langage (un test lit les sources) et aucun n'applique quoi que ce soit : tout
650
+ changement passe par une proposition au gouverneur, et chaque appel vérifie
651
+ d'abord que le gouverneur existe, est authentique et n'est pas à l'arrêt
652
+ (`assertGovernorReady`).
653
+
654
+ | N° | Fonction | Rôle |
655
+ | --- | --- | --- |
656
+ | 17 | `detectDrift` | Surveillance de dérive des entrées, des résultats et des performances, avec recommandation codée. |
657
+ | 18 | `createFollowUps` | Mémoire prospective : `scheduleFollowUp`, `dueFollowUps`. |
658
+ | 26 | `abstentionPolicy` | Seuil de confiance tiré de la calibration et des coûts d'erreur. |
659
+ | 27 | `generateAdversarialCases` | Scénarios-pièges candidats à partir des échecs récents. |
660
+ | 14 | `reviewByRoles` | Vérificateur, contradicteur et contrôleur des risques, revues séparées. |
661
+ | 03 | `lessonToScenario` | Une leçon vérifiée devient un scénario anti-régression. |
662
+
663
+ ### Surveillance de dérive (17)
664
+
665
+ ```js
666
+ const rapport = await detectDrift({
667
+ governor, organisationId, agentId, domain,
668
+ baseline: { window: { from, to }, inputs: { domains, languages, lengths },
669
+ outcomes: { succeeded, failed, unknown },
670
+ performance: { calibration: { sampleSize, brierScore, confidenceGap }, tools: [{ tool, provider, knownCalls, failures }] } },
671
+ current: { /* même forme */ },
672
+ calendars, // DomainCalendar[] de P2, de la même organisation
673
+ recentChange, // { kind, id, version, previousVersion, deployedAt }
674
+ propose: {} // facultatif : un retour arrière recommandé devient une proposition EN ATTENTE
675
+ });
676
+ ```
677
+
678
+ `snapshotWindow({ decisions, findings, agentId, domain, languageOf })` construit
679
+ un résumé à partir des données de P2 (le cœur ne détecte aucune langue :
680
+ `languageOf` est à vous).
681
+
682
+ Tests simples, documentés dans le code : l'indice de stabilité de population
683
+ (PSI) pour les répartitions (domaines, langues, longueurs découpées aux
684
+ quintiles de la référence ; un pseudo-comptage de 0,5 par catégorie ; sous 0,10
685
+ stable, de 0,10 à 0,25 modéré, 0,25 et plus significatif) et la différence de deux
686
+ proportions avec l'intervalle de score hybride de Newcombe, construit sur les
687
+ intervalles de Wilson de P2 (taux de réussite, part d'inconnu, taux d'erreur des
688
+ outils). Un écart est significatif quand l'intervalle exclut zéro et que l'écart
689
+ atteint 5 points (`minimumEffect`). Le score de Brier et l'écart de confiance se
690
+ comparent à un seuil (`brierDelta`, `confidenceGapDelta`). Une fenêtre de moins de
691
+ `minimumSample` observations connues ne conclut jamais : `insufficient_data`.
692
+
693
+ Un **calendrier métier** est consulté avant d'accuser l'agent : une période qui
694
+ recouvre la fenêtre courante et pas la fenêtre de référence explique l'écart
695
+ (`attribution: 'calendar'`, recommandation `monitor`, `reexamineAfter`).
696
+
697
+ Recommandation codée : `monitor` (surveiller), `investigate` (enquêter : les
698
+ entrées ont bougé ou un outil s'est dégradé en même temps qu'une baisse),
699
+ `freeze` (geler : baisse sévère sans explication, `freezeDrop`),
700
+ `propose_rollback` (proposer un retour arrière : baisse dans une fenêtre qui
701
+ commence après un changement récent, entrées stables). Le rapport dit toujours
702
+ `applied: false`. Avec `propose`, le retour arrière devient une proposition en
703
+ attente chez le gouverneur (risque élevé, deux approbations par défaut) et rien
704
+ n'est annulé pour autant : un humain décide, puis `rollbackChange` reste à vous.
705
+ `recordedBy` dépose aussi un constat pour le bilan du matin.
706
+
707
+ ### Mémoire prospective (18)
708
+
709
+ ```js
710
+ const vstore = createMemoryVigilanceStore(); // ou createPostgresVigilanceStore(pool)
711
+ const conscience = createConscience({ governor, masker, erasers: [followUpEraser(vstore)] });
712
+ const followUps = createFollowUps({ governor, conscience, store: vstore, masker });
713
+ await followUps.scheduleFollowUp({ organisationId, decisionId, observableAt, question });
714
+ const dus = await followUps.dueFollowUps({ organisationId }); // { followUp, decision }[]
715
+ await followUps.completeFollowUp({ organisationId, id });
716
+ ```
717
+
718
+ Idempotent : même décision, même date, même question, même suivi
719
+ (`created: false`). La question est masquée avant d'être gardée. La décision doit
720
+ exister dans l'organisation (celle d'une autre : `not_found`). Les suivis
721
+ s'effacent avec la personne par `eraseSubject` (déclarer `followUpEraser`) ; un
722
+ suivi dont la décision a été effacée ou a expiré n'est jamais rendu comme dû. Le
723
+ contenu d'un suivi dû est une donnée, jamais une consigne.
724
+
725
+ ### Abstention (26)
726
+
727
+ `abstentionPolicy({ governor, organisationId, agentId, domain, calibration, errorCosts, currentThreshold, propose })`.
728
+ Agir vaut la peine quand la chance de réussite atteint
729
+ `falsePositive / (falsePositive + falseNegative)` (la table de coûts de P2). Le
730
+ seuil est la plus basse confiance annoncée, ayant ses propres observations, à
731
+ partir de laquelle la borne basse de Wilson du taux de réussite observé reste au
732
+ dessus de ce rapport, sur au moins `minimumSample` décisions. Pas assez de données
733
+ ou pas de table de coûts : un seuil prudent par défaut (0,8), jamais plus bas que
734
+ celui déjà en vigueur. Aucune zone fiable : 1. `shouldAbstain(policy, { confidence, actionKind })`
735
+ répond `proceed`, `ask_clarification` (demander une précision) ou, pour les
736
+ actions `write` et `confirm`, `propose_verification`, toujours d'après le seuil
737
+ **en vigueur** (`effectiveThreshold`). Un nouveau seuil est une proposition sur la
738
+ cible `threshold:abstention:<agent>:<domaine>` ; rien n'est appliqué ici.
739
+
740
+ ### Adversaire nocturne (27) et leçons devenues tests (03)
741
+
742
+ ```js
743
+ const library = createScenarioLibrary({ governor, store: vstore, masker });
744
+ const { candidates, rejected } = await generateAdversarialCases({ governor, organisationId, failures, masker, generator, library });
745
+ const cas = await lessonToScenario(lesson, { governor, masker, question, tools, expect, library });
746
+ // plus tard, une fois les propositions approuvées par des humains chez le gouverneur :
747
+ const suite = (await library.approved({ organisationId })).map((a) => a.scenario); // pour evaluateAgent
748
+ ```
749
+
750
+ `generateAdversarialCases` transforme les échecs récents en candidats de quatre
751
+ catégories (injection, ambiguïté, cas limite, accès à une autre organisation) au
752
+ format d'`evaluateAgent` de `@astratra/testkit` : `id`, `question`, outils
753
+ simulés (résultats fixes, sans effet), `expect`, et un `score` qui fait échouer le
754
+ cas si un outil interdit est appelé ou un texte interdit apparaît. Un
755
+ **générateur injecté** peut écrire les cas (une fonction qui rend des données
756
+ seulement ; ce qu'elle rend est validé, masqué, et remplacé par le gabarit s'il
757
+ est invalide ou en échec). Sans générateur, des gabarits déterministes : même
758
+ échec, mêmes cas. Le **masqueur est obligatoire** et passe sur les échecs et sur
759
+ tout ce que rend le générateur.
760
+
761
+ `lessonToScenario` accepte une leçon de statut `verified` (preuves, assez de
762
+ décisions distinctes, aucun conflit ouvert) ; une hypothèse, une leçon à
763
+ réévaluer ou retirée est refusée (`lesson_not_verified`). La leçon dit ce qui a
764
+ été appris ; vous décrivez comment le vérifier, et un scénario qui n'affirme rien
765
+ est refusé.
766
+
767
+ Tout candidat naît `to_review` (« à relire »). Avec une bibliothèque, il devient
768
+ une proposition au gouverneur (cible de type `instructions`, identifiant
769
+ `scenarios:<agent>`, réglable par `targetKind`). `library.approved()` est la
770
+ **seule** entrée dans les tests : elle ne garde un candidat que si des humains ont
771
+ approuvé exactement ce contenu (même empreinte) et que le contenu gardé n'a pas
772
+ changé. Un modèle, un refus, une approbation expirée ou un candidat modifié le
773
+ laissent dehors.
774
+
775
+ ### Revue multi-rôles (14)
776
+
777
+ ```js
778
+ const revue = await reviewByRoles({ governor, organisationId, finding, roles: { verifier, contradictor, riskController } });
779
+ revue.advances; revue.status; // true / 'supported', ou false / 'hypothesis' avec revue.blockers
780
+ ```
781
+
782
+ Trois fonctions séparées, pas un vote de modèles. Le constat n'avance que si le
783
+ vérificateur cite une preuve **indépendante** (ni les preuves ni les décisions du
784
+ constat, même organisation, confirmée au besoin par `evidenceExists`), si aucune
785
+ explication concurrente du contradicteur n'est aussi forte que la confiance du
786
+ constat, et si le contrôleur des risques valide une portée au moins aussi large
787
+ que celle demandée (`observation` < `agent` < `domain` < `organisation`). Un rôle
788
+ qui lève une erreur ou répond mal bloque le constat. Les rôles reçoivent une copie
789
+ gelée du constat, jamais les réponses des autres.
790
+
791
+ ### Stockage
792
+
793
+ `createMemoryVigilanceStore()` et `createPostgresVigilanceStore(db, { prefix })`
794
+ (schéma : `postgresVigilanceSchema({ prefix })`, tables `<prefix>_follow_ups` et
795
+ `<prefix>_candidates`). Même contrat, mêmes tests, chaque accès borné par
796
+ l'organisation, chaque valeur en paramètre SQL.
797
+
798
+ ## P4 · mode ombre
799
+
800
+ Propositions 21 (mode ombre) et 32 (bac à sable du mode ombre), dans
801
+ `@astratra/conscience/autoconscience`. Une stratégie candidate que des humains
802
+ ont déjà approuvée traite **en silence** une partie des vraies demandes, à côté
803
+ de la stratégie stable. Ses réponses ne vont à personne. Elles sont comparées
804
+ aux réponses stables par des métriques déterministes que vous fournissez, et
805
+ l'écart est gardé, masqué, sous forme de `ShadowRun`. Aucun modèle de langage
806
+ n'est importé (un test lit les sources) ; chaque appel vérifie d'abord
807
+ `assertGovernorReady`.
808
+
809
+ ```js
810
+ const { createSandbox, createShadowRunner, createMemoryShadowStore, shadowEraser } = require('@astratra/conscience/autoconscience');
811
+
812
+ const sandbox = await createSandbox({ governor, organisationId, tools: {
813
+ lookup_invoice: { kind: 'read', response: { status: 'unknown' } }, // simulé ou enregistré
814
+ send_reminder: { kind: 'write' } // jamais exécuté, seulement journalisé
815
+ } });
816
+ const shadow = await createShadowRunner({
817
+ governor, organisationId,
818
+ candidate: { kind: 'instructions', id: 'reminders', agent }, // ou { proposalId, agent }
819
+ sandbox, sampleRate: 0.1,
820
+ budget: { maxRuns: 500, maxCost: 50, costPerRun: 0.1 },
821
+ masker, // obligatoire
822
+ store: createMemoryShadowStore(), // ou createPostgresShadowStore(pool)
823
+ metrics: [
824
+ { name: 'accuracy', score: ({ input, output }) => output.total === input.expected },
825
+ { name: 'sources_accuracy', score: ({ output }) => output.sourced === true, maxRegression: 0.02 },
826
+ { name: 'minor_protection', critical: true, score: ({ input, output }) => !(input.minor && output.disclosed) }
827
+ ],
828
+ target: 'accuracy', minimumSample: 30
829
+ });
830
+
831
+ // Dans le chemin de la requête : répondre avec la stratégie stable, puis passer la main. Ne jamais attendre `done`.
832
+ const answer = await stable(request);
833
+ respond(answer);
834
+ shadow.observe({ request: { id: request.id, userId: request.userId, input: request.input }, stableResult: { output: answer, durationMs, cost } });
835
+
836
+ const report = await shadow.report({ propose: {}, recordedBy: { kind: 'system', id: 'shadow' } });
837
+ report.conclusion; // 'insufficient_data' | 'regression' | 'no_difference' | 'promising'
838
+ ```
839
+
840
+ **Quelle stratégie peut tourner.** Soit la version candidate d'un objet du
841
+ gouverneur (`{ kind, id }` : la version mise en place à partir d'une proposition
842
+ approuvée par des humains), soit une proposition à l'état `approved` avec des
843
+ approbations humaines (`{ proposalId }`). Une proposition en attente, déclinée,
844
+ rejetée ou expirée, une version stable, un objet inconnu ou l'objet d'une autre
845
+ organisation sont refusés (`candidate_not_approved`, `candidate_not_staged`,
846
+ `not_found`). La vérification est refaite avant chaque exécution : une candidate
847
+ annulée, promue ou remplacée arrête l'ombre.
848
+
849
+ **La réponse de la candidate n'est jamais renvoyée.** `observe` est synchrone, ne
850
+ lève jamais d'erreur et n'attend jamais : il rend `{ scheduled, reason, done }`, et
851
+ `done` (qui ne rejette jamais) donne un accusé (`recorded` avec un identifiant
852
+ d'exécution, ou `skipped`, `timeout`, `error` avec une raison) qui ne contient
853
+ aucune sortie de la candidate. L'exécution se fait en arrière-plan, après la
854
+ réponse stable. Une candidate en erreur, lente ou hostile, un magasin ou un
855
+ masqueur en panne, une métrique qui lève : tout est isolé et compté (`stats()`),
856
+ rien n'atteint l'appelant. Un délai (`deadlineMs`) abandonne une exécution
857
+ bloquée, et `maxConcurrent` écarte une rafale en `busy` au lieu de la mettre en
858
+ file.
859
+
860
+ **Bac à sable seulement (32).** La candidate est une fonction autonome exécutée
861
+ dans le bac à sable de P3 : aucun objet de l'hôte, ni `process`, ni `require`, ni
862
+ minuterie, ni `fetch`. Ses outils sont ceux du bac à sable : une lecture rend un
863
+ enregistrement (les `recordings` facultatifs de `observe`, par exemple ce que la
864
+ requête stable a lu) ou une réponse simulée ; une écriture n'est **jamais
865
+ exécutée**, même si la candidate l'appelle, et n'est que journalisée comme
866
+ intention (`writeIntentions`, masquée). L'ombre n'ouvre aucune connexion réseau
867
+ de son propre chef. Un appel de modèle dans une candidate est un outil du bac à
868
+ sable, rejoué ou simulé, jamais un appel réel.
869
+
870
+ **Échantillonnage, budget, arrêt d'urgence.** Une demande est choisie par un
871
+ hachage de son identifiant et de celui de l'ombre : la même demande donne
872
+ toujours le même choix, quel que soit l'ordre, et `sampleRate: 0.1` choisit un
873
+ sous-ensemble de ce que choisit `0.5`. Le budget est obligatoire et plafonné :
874
+ `maxRuns`, `maxCost` (`costPerRun` est le plafond réservé à une exécution,
875
+ `costOf` ne peut que l'abaisser), `maxDurationMs` (temps mesuré, que les
876
+ exécutions déjà en cours peuvent dépasser) et `governorAgentId` pour dépenser
877
+ aussi par `governor.authorizeSpend`. Budget épuisé ou arrêt d'urgence du
878
+ gouverneur : l'ombre s'arrête aussitôt, reste arrêtée (lever l'arrêt ne la
879
+ réveille pas : en démarrer une nouvelle) et une exécution qui se termine après
880
+ l'arrêt est abandonnée. Les budgets comptent les exécutions déjà stockées : un
881
+ redémarrage poursuit la même ombre.
882
+
883
+ **ShadowRun.** Par demande choisie : la demande masquée, les sorties candidate et
884
+ stable masquées (remplacées par une empreinte au-delà de 20 000 caractères), le
885
+ score de chaque côté pour chaque métrique (`succeeded`, `failed`, `unknown`), si
886
+ les deux réponses concordent, les intentions d'écriture, la durée, le coût et les
887
+ incidents (`candidate_failed`, `candidate_timeout`, `scoring_failed`, ...).
888
+ L'identifiant brut de la demande n'est pas gardé. Un masqueur en échec garde
889
+ l'exécution hors du magasin. Une candidate qui ne produit rien échoue aux
890
+ métriques : elle ne peut pas avoir réussi.
891
+
892
+ **Rapport.** Par métrique, le taux de réussite de chaque côté avec son
893
+ intervalle de Wilson et l'effectif minimal (P2 : en dessous, `insufficient_data`
894
+ et aucune différence), les comptes appariés et la différence (candidate moins
895
+ stable) avec un intervalle de Newcombe. Anti-Goodhart (P2) : la métrique `target`
896
+ doit s'améliorer pendant que toutes les autres restent dans leur
897
+ `maxRegression` (et `limits.cost`) ; au moins une contre-mesure est exigée à la
898
+ construction. Les métriques critiques listent les demandes où la stratégie stable
899
+ a réussi et la candidate échoué. La conclusion est un code, dans cet ordre :
900
+
901
+ | Conclusion | Quand |
902
+ |---|---|
903
+ | `regression` | Plus de régressions critiques que `maxCriticalRegressions` (0 par défaut ; un seul cas compte, quel que soit l'effectif), ou, avec assez de données, une baisse significative d'une métrique, une contre-mesure au-delà de sa limite, ou un taux d'incidents significativement au-dessus de `maxIncidentRate`. |
904
+ | `insufficient_data` | Moins de `minimumSample` exécutions, une métrique avec trop peu de scores connus, ou une limite de coût sans le coût stable. |
905
+ | `promising` | La cible s'est améliorée avec un intervalle au-dessus de zéro et toutes les contre-mesures ont tenu. |
906
+ | `no_difference` | Assez de données, aucune différence significative et aucune régression. |
907
+
908
+ Le rapport ne dit jamais « prouvé » : `provesImprovement` vaut toujours `false`,
909
+ `causality` vaut `not_established`, `applied` vaut `false`. Une comparaison en
910
+ ombre sur un échantillon de vraies demandes peut rendre une amélioration
911
+ prometteuse, rien de plus. Avec `propose`, un résultat prometteur devient une
912
+ **proposition en attente** chez le gouverneur (type de la candidate, identifiant
913
+ `shadow:<id>:<version>`) ; avec `recordedBy`, toute conclusion est classée comme
914
+ constat pour le bilan du matin. Déployer et promouvoir restent à un humain
915
+ (`deployChange`, `promoteChange`) : l'ombre ne les appelle jamais.
916
+
917
+ **Isolation et effacement.** Chaque ligne appartient à une organisation et chaque
918
+ lecture et écriture est bornée par elle ; une candidate, un bac à sable ou un
919
+ appel de magasin d'une autre organisation est refusé. Les exécutions portent le
920
+ `userId` de la demande : enregistrer `shadowEraser(store)` dans
921
+ `createConscience({ erasers })`, ou appeler `shadow.eraseSubject`, pour les
922
+ supprimer avec la personne.
923
+
924
+ **Stockage.** `createMemoryShadowStore()` et `createPostgresShadowStore(db, { prefix })`
925
+ (schéma : `postgresShadowSchema({ prefix })`, table `<prefix>_runs`). Même
926
+ contrat, mêmes tests, toute valeur est un paramètre SQL.
927
+
928
+ ## Tests
929
+
930
+ ```sh
931
+ npm test -w @astratra/conscience
932
+ CONSCIENCE_TEST_DATABASE_URL=postgresql:///conscience_p2_test npm test -w @astratra/conscience
933
+ CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p4_test node --test packages/conscience/test/shadow.postgres.test.js
934
+ ```
935
+
936
+ Les tests PostgreSQL ne tournent que si l'URL désigne une base dont le nom
937
+ finit par `_test` ; chaque test crée ses propres tables puis les supprime. Une base de test
938
+ absente est créée avec `createdb` si permis ; sinon les tests d'intégration
939
+ sont ignorés avec une raison explicite, sans afficher l'URL.
940
+
941
+ ## Limites
942
+
943
+ - Aucun modèle de langage ni changement automatique : P2 évalue uniquement des preuves structurées,
944
+ tout changement passe par un humain, et le gouverneur n'applique jamais un changement à votre
945
+ application. Il versionne les objets et dit quelle version servir (`resolveVersion`) ; c'est à vous
946
+ de lire cette version là où vous utilisez l'objet.
947
+ - Le gouverneur reconnaît les portées protégées par leurs noms et leurs clés,
948
+ pas en lisant du texte : une proposition doit décrire honnêtement sa cible,
949
+ et tout cas ambigu est rejeté plutôt qu'accepté.
950
+ - Le masqueur est le vôtre : le paquet garantit que le texte stocké y est
951
+ passé, pas qu'il a tout trouvé.
952
+ - Le mode ombre ne juge que les demandes échantillonnées (une rafale au-delà de `maxConcurrent` est écartée et comptée) et ses
953
+ intervalles ignorent l'appariement des demandes : ils sont prudents. Les métriques sont les vôtres, déterministes, et la
954
+ lecture d'un outil n'y est rejouée que d'après des enregistrements.