@astratra/conscience 0.0.0-stage → 1.0.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 (53) hide show
  1. package/LICENSE +21 -0
  2. package/README.fr.md +901 -0
  3. package/README.md +864 -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 +308 -0
  41. package/src/governor/index.js +20 -0
  42. package/src/governor/policy.js +136 -0
  43. package/src/governor/postgres.js +243 -0
  44. package/src/governor/review.js +191 -0
  45. package/src/governor/rollout.js +66 -0
  46. package/src/governor/stores.js +136 -0
  47. package/src/governor/util.js +53 -0
  48. package/src/guard.js +21 -0
  49. package/src/index.d.ts +244 -0
  50. package/src/index.js +23 -0
  51. package/src/memoryStore.js +65 -0
  52. package/src/postgres.js +93 -0
  53. package/src/records.js +220 -0
package/README.fr.md ADDED
@@ -0,0 +1,901 @@
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
+ ### Contrôle au démarrage
261
+
262
+ `assertGovernorReady(governor, { organisationId })` lève `governor_missing`,
263
+ `governor_invalid` (objet non créé par `createGovernor`),
264
+ `governor_unavailable` (magasin injoignable) ou `governor_halted`. Toute
265
+ écriture réflexive du paquet l'appelle d'abord.
266
+
267
+ ## Conscience (entrée principale)
268
+
269
+ `createConscience({ governor, masker, store, now, retention, erasers, onEvent })`
270
+ lève une erreur si le gouverneur ou le masqueur manque.
271
+
272
+ ### Enregistrements
273
+
274
+ | Méthode | Enregistrement |
275
+ |---|---|
276
+ | `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 |
277
+ | `recordPrediction(input)` | Une probabilité rattachée à une décision, avec sa date de résolution |
278
+ | `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 |
279
+ | `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 |
280
+ | `recordLesson(input)` | `MemoryLesson` : preuves, degré, `validFrom`/`validUntil`, statut, contradictions, remplacements. Écriture réflexive |
281
+ | `updateSelfModel(input)` | `SelfModelSnapshot` : capacités testées (chacune avec ses preuves), outils, limites, permissions, provenance. Écriture réflexive |
282
+
283
+ Chaque enregistrement a un identifiant stable : le vôtre, ou un identifiant
284
+ déduit du contenu ; enregistrer deux fois la même chose donne une seule ligne.
285
+ Rien n'est jamais modifié : une révision est une nouvelle ligne.
286
+
287
+ Le texte libre (objectif, contexte, entrée de l'action, résultat attendu,
288
+ observations, résumés et notes des leçons, corrections) passe par le masqueur
289
+ avant d'être stocké. Utilisez un masqueur déterministe.
290
+
291
+ ### Registre des preuves
292
+
293
+ Une leçon sans preuve est toujours une `hypothesis` (`statusForced: true` si
294
+ un autre statut était demandé). Une preuve qui désigne une décision, une
295
+ prédiction, un résultat ou une correction doit exister dans la même
296
+ organisation. Cette version stocke les leçons et leur historique ; P2 contrôle
297
+ l'effectif et les contradictions avant de vérifier une leçon.
298
+
299
+ ### Lecture
300
+
301
+ - `getDecision(scope, id)`, `recallDecisions(scope, { agentId, from, to, asOf, withOutcomes })`
302
+ - `getOutcomes(scope, decisionId)` : toutes les révisions, avec `revision`, `current`, `supersededAt`
303
+ - `getLesson(scope, lessonId)`, `listLessons(scope, { status, validAt, asOf })`
304
+ - `getSelfModel(scope, agentId, { asOf })`, `getSelfModelHistory(scope, agentId)`
305
+ - `getMemoryTimeline(scope, { axis: 'event' | 'recorded', from, to, asOf, validAt, kinds })` :
306
+ temps de l'événement, temps de l'enregistrement et période de validité.
307
+ `asOf` répond à « que savait-on à ce moment-là ».
308
+ - `getLineage(scope, decisionId)` : objectif → action → outils → résultats →
309
+ corrections → leçons.
310
+
311
+ Une portée est `{ organisationId, userId? }`. Un enregistrement d'une autre
312
+ organisation (ou d'une autre personne quand `userId` est donné) reçoit
313
+ exactement la même réponse qu'un enregistrement absent.
314
+
315
+ ### Garde mémoire
316
+
317
+ Le texte stocké est une donnée non fiable : il peut venir d'une personne, d'un
318
+ outil ou d'un modèle manipulé. Le paquet ne l'interprète jamais et le
319
+ gouverneur ne le lit jamais. Avant qu'un modèle lise des enregistrements,
320
+ encadrez-les :
321
+
322
+ ```js
323
+ const { frameRecordsForModel } = require('@astratra/conscience');
324
+ const bloc = frameRecordsForModel(await conscience.listLessons({ organisationId: 'org-1' }));
325
+ ```
326
+
327
+ L'encadrement est celui de `@astratra/ai/guards` (marqueur aléatoire que le
328
+ contenu ne peut pas refermer).
329
+
330
+ ### Effacement et rétention
331
+
332
+ `eraseSubject({ organisationId, userId })` supprime les décisions,
333
+ prédictions, résultats, corrections et leçons de la personne, retire les
334
+ références à ces données des leçons de l'organisation (une leçon restée sans
335
+ preuve redevient une hypothèse) et appelle vos `erasers` pour ce qui est gardé
336
+ ailleurs (vecteurs, index, caches, calibrations). Il rend un rapport chiffré.
337
+ Avec `retention: { erasure: 'anonymise' }`, les enregistrements restent, sans
338
+ la personne.
339
+
340
+ Rien n'est supprimé par minuterie. `applyRetention({ organisationId })`
341
+ supprime les enregistrements plus anciens que `retention.maxAgeDays[type]`, et
342
+ seulement pour les types configurés.
343
+
344
+ ## Magasins
345
+
346
+ Magasins en mémoire (par défaut, perdus à l'arrêt) et PostgreSQL fournis. Le
347
+ SQL n'utilise que des paramètres ; le préfixe des tables est un identifiant
348
+ vérifié.
349
+
350
+ ```js
351
+ postgresConscienceSchema({ prefix: 'astratra_conscience' }) // table <prefix>_records
352
+ postgresGovernorSchema({ prefix: 'astratra_governor' }) // <prefix>_proposals, _audit, _spend, _controls, _objects, _versions, _findings
353
+ ```
354
+
355
+ ### Écrire son propre magasin (MongoDB, ...)
356
+
357
+ Un magasin de conscience a cinq méthodes sur des enveloppes immuables
358
+ `{ kind, id, organisationId, userId, agentId, decisionId, lessonId, eventAt, recordedAt, fingerprint, evidenceRefs, data }` :
359
+
360
+ | Méthode | Esquisse MongoDB |
361
+ |---|---|
362
+ | `put(envelope)` | `insertOne` avec un index unique sur `{ organisationId, kind, id }` ; en cas de doublon, rendre le document existant avec `created: false` |
363
+ | `get(kind, organisationId, id)` | `findOne` |
364
+ | `list(kind, filter)` | `find` sur les champs indexés, `recordedAt <= recordedTo`, `evidenceRefs: ref`, trié par `recordedAt` puis ordre d'insertion |
365
+ | `replace(envelope)` | `replaceOne` (effacement et rétention seulement) |
366
+ | `remove(kind, organisationId, ids)` | `deleteMany`, rend le nombre supprimé |
367
+
368
+ `matchesFilter(envelope, filter)` donne la sémantique exacte des filtres.
369
+ L'interface du magasin du gouverneur (`GovernorStore` dans les types) demande
370
+ un `reserveSpend` atomique (transaction), un `transitionProposal` en
371
+ comparer-puis-écrire (`findOneAndUpdate` sur `status`, et sur le nombre
372
+ d'approbations quand un `guard` est donné), un `updateObject` en
373
+ comparer-puis-écrire sur `revision`, et des `createObject`, `putVersion` et
374
+ `putFinding` qui n'insèrent qu'une fois.
375
+
376
+ ## Autoconscience (`/autoconscience`)
377
+
378
+ Le cœur P2 est déterministe, sans import ni appel à un modèle de langage.
379
+ `evaluateOutcomes()` et son alias `runReflection()` lisent P1 et rendent des
380
+ `ReflectionFinding[]`. `createEvaluator({ governor, conscience, ...options })`
381
+ lie un évaluateur dont `evaluate({ organisationId, userId?, agentId?, window?, ... })`
382
+ évalue une portée. Chaque entrée réflexive vérifie `assertGovernorReady`.
383
+ L'évaluation calcule sans écrire de cache ni effectuer de changement automatique.
384
+
385
+ ```js
386
+ const { evaluateOutcomes } = require('@astratra/conscience/autoconscience');
387
+ const constats = await evaluateOutcomes({
388
+ governor, conscience, organisationId: 'org-1', minimumSample: 30,
389
+ errorCostPolicies: [{ organisationId: 'org-1', domain: 'facturation', falsePositive: 1, falseNegative: 20 }],
390
+ calendars: [{ organisationId: 'org-1', domain: 'facturation', name: 'activité',
391
+ periods: [{ label: 'fermeture', kind: 'closure', from: '2026-12-24', to: '2027-01-02' }] }]
392
+ });
393
+ ```
394
+
395
+ ### Données structurées
396
+
397
+ Les décisions acceptent `domain` (`general` par défaut), `justification: { claims }`
398
+ et `toolTrace: [{ callId, tool, provider?, status, empty?, durationMs, labels? }]`.
399
+ La liste des outils déclarés ne remplace pas la trace d'exécution. Les étiquettes
400
+ comme `source_verified` proviennent de l'instrumentation de l'application.
401
+ Les prédictions acceptent `domain` (hérité de la décision) et `sensor` ; les
402
+ résultats acceptent `predictionId`, vérifié dans la même décision et organisation.
403
+
404
+ Les corrections acceptent la `class` de l'application, prioritaire, ou les
405
+ `tags` structurés `fact_changed`, `wording_changed`, `goal_changed`, `opinion_changed`.
406
+ Des étiquettes absentes, inconnues ou ambiguës donnent `disagreement`.
407
+ Aucun texte libre n'est interprété pour décider de la classe.
408
+ Les leçons acceptent `domain`, `subject`, `stance: 'supports' | 'opposes'`.
409
+ Deux positions opposées dans la même organisation, personne, agent et domaine
410
+ ouvrent un conflit symétrique `to_reassess`. Le résumé seul ne permet pas de
411
+ reconnaître une contradiction.
412
+
413
+ ### API de calcul
414
+
415
+ | Fonction | Résultat |
416
+ |---|---|
417
+ | `honestStatistics` | Effectifs connus et inconnus, taux, intervalle de Wilson, refus de conclure sous `minimumSample` (30 par défaut) |
418
+ | `wilsonInterval` | Intervalle bilatéral ; niveaux 0,90, 0,95 (défaut), 0,99 ; null si aucun résultat connu |
419
+ | `calibratePredictions` | Courbe par tranches et agent/domaine, Brier, écart signé de confiance, surconfiance et sous-confiance |
420
+ | `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 |
421
+ | `checkReasoningFidelity` | `faithful`, `unfaithful`, `unknown` ; chaque étiquette exigée doit correspondre à un appel réussi et non vide ; règle par défaut `source_verified` |
422
+ | `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) |
423
+ | `calendarConfounders` | `calendar_confounded` dans une période métier `[from, to)` du même domaine |
424
+ | `checkCounterMetrics` | Gain de la cible rejeté si une contre-mesure régresse strictement au-delà de `maxRegression`, exprimé en unité absolue |
425
+ | `classifyCorrection` | Classe déterministe ; seul `factual` peut étayer une leçon factuelle |
426
+ | `evaluateLessonConflicts` | Conflits ouverts, preuves, domaine et dates ; préférence possible selon la force des preuves, jamais clôture par la date seule |
427
+ | `reflectionUtility` | Constats utiles + propositions acceptées, pondérés, moins coût pondéré ; bénéfice et utilité nette doivent être positifs |
428
+ | `recommendReflectionFrequency` | Réduire après `uselessCycles` cycles terminés inutiles consécutifs (3) ; multiplicateur d'intervalle `reductionFactor` (2) |
429
+
430
+ Les cycles sans effectifs mesurés de constats utiles ou de propositions acceptées
431
+ restent `unmeasured` et ne comptent pas comme inutiles. Le statut inconnu d'un
432
+ appel reste hors du dénominateur du taux d'erreur ; les taux de vide et de lenteur
433
+ décrivent les valeurs de vide et de durée réellement rapportées.
434
+
435
+ Les inconnus restent conservés, hors des dénominateurs succès/échec et des
436
+ scores de Brier/coût. L'évaluateur prend la dernière prédiction par décision/domaine
437
+ (date, puis identifiant), et le résultat courant du capteur ou du lien explicite.
438
+ Un résultat absent, ambigu ou observé avant la prédiction reste inconnu.
439
+ Une décision ne compte qu'une fois par domaine ; le calcul de calibration direct
440
+ refuse les doublons. Chaque tranche a son propre seuil d'effectif. Les intervalles
441
+ restent affichés pour les petits échantillons non nuls, mais `insufficient_data`
442
+ refuse toute inférence. Les mesures sont descriptives.
443
+
444
+ Chaque constat conserve preuves, effectif, intervalle, statut, confiance,
445
+ hypothèses concurrentes et facteurs de confusion. `causality` vaut toujours
446
+ `not_established` : résultat et fidélité de la méthode restent distincts.
447
+ Un succès isolé ne crée aucune règle générale. `confidence` représente la
448
+ confiance d'observation fournie ou le niveau de l'intervalle, jamais la
449
+ probabilité qu'une hypothèse causale soit vraie.
450
+
451
+ ### Vérification et arbitrage des leçons
452
+
453
+ `createConscience({ minimumSample: 30, ... })` fixe le plancher de vérification.
454
+ Une leçon peut exiger un seuil supérieur, jamais abaisser ce plancher.
455
+ L'effectif est calculé sur les **décisions distinctes** représentées par des
456
+ résultats courants connus ou des corrections factuelles du domaine et de l'agent.
457
+ Les références externes, décisions et prédictions seules n'augmentent pas cet
458
+ effectif ; les inconnus, anciennes révisions et doublons sont exclus.
459
+ Une leçon factuelle citant une correction de style, d'objectif ou de désaccord
460
+ reste une hypothèse. Preuve, effectif suffisant et absence de conflit sont tous
461
+ nécessaires pour `verified` ; conflit ouvert : `to_reassess` ; sinon : `hypothesis`.
462
+ Ce statut qualifie la suffisance des preuves, pas une causalité.
463
+
464
+ `conscience.resolveLessonConflict({ organisationId, userId?, winnerId, loserId, evidence })`
465
+ arbitre explicitement avec un effectif factuel suffisant du même domaine :
466
+ la leçon adverse est retirée, une révision de la gagnante est ajoutée.
467
+ Chaque écriture passe par `assertGovernorReady`. Toutes les anciennes révisions
468
+ restent. `getLesson().current` et `listLessons()` réévaluent preuves et conflits,
469
+ y compris après un résultat tardif inconnu ou des écritures concurrentes.
470
+ `storedStatus` expose le statut enregistré ; `history` garde les révisions
471
+ enregistrées. `asOf` utilise les preuves et résultats connus à cette date.
472
+
473
+ Les constats sont recalculés : effacer leurs sources les retire des évaluations
474
+ suivantes. Pour un magasin de constats propre à l'application, enregistrer un
475
+ effaceur. `window` filtre les dates des décisions ; ce n'est pas le rejeu temporel
476
+ P3. Une sélection atteignant 1000 décisions lève `evaluation_limit` : fournir
477
+ `decisionIds` explicitement pour une sélection plus grande sans troncature.
478
+
479
+ P3 (expériences) et P4 (mode ombre) sont décrites dans leurs propres sections plus bas.
480
+ L'évaluation elle-même ne crée ni planificateur ni transport de modèle ni déploiement.
481
+
482
+ - P3, expériences : rejeu figé à la date qui refuse toute donnée future, bac à
483
+ sable, jeu de tests protégé. Surveillance de dérive, suivis, abstention,
484
+ adversaire nocturne, revue multi-rôles et leçons devenues tests sont décrits
485
+ dans « P3 · vigilance (2/2) » plus bas.
486
+ - P4, mode ombre en bac à sable : voir « P4 · mode ombre » plus bas.
487
+ - Seule la P6 (intégration et transfert encadré entre agents) reste hors de ce paquet.
488
+
489
+ La P5 (gouvernance avancée) est dans l'entrée du gouverneur : voir plus haut.
490
+
491
+ ## P3 · expériences (1/2)
492
+
493
+ Cette première moitié couvre 02/35 (rejeu temporel), 32 (outils simulés), 36
494
+ (jeu final protégé) et 16 (laboratoire pré-enregistré). Le paquet reste en
495
+ 1.0.0, non publié. Les cinq API et leurs opérations ultérieures passent par
496
+ `assertGovernorReady`, dans une seule organisation. Le cœur de calcul n'importe
497
+ aucun modèle de langage et n'utilise jamais de texte généré pour juger un
498
+ résultat. Les autres fonctions P3 appartiennent à la seconde moitié.
499
+
500
+ | API | Contrat |
501
+ |---|---|
502
+ | `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'`. |
503
+ | `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. |
504
+ | `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. |
505
+ | `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é. |
506
+ | `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. |
507
+
508
+ ```js
509
+ const { createHoldout, proposeExperiment, runExperiment } = require('@astratra/conscience/autoconscience');
510
+ const portée = { governor, organisationId: 'org-1' };
511
+ // Trois jeux séparés, préparés hors du moteur de réflexion.
512
+ // Chaque cas : { id, input, expected }. Ne jamais lui donner casFinaux.
513
+ const holdout = await createHoldout({ ...portée, cases: casFinaux });
514
+ const expérience = await proposeExperiment({
515
+ ...portée, hypothesis: 'Le candidat atteint le seuil d’exactitude enregistré',
516
+ agent: (entrée) => entrée,
517
+ metrics: [{ name: 'accuracy', kind: 'exact_match' }],
518
+ thresholds: { accuracy: 0.9 },
519
+ protocol: { development: casDéveloppement, validation: casValidation,
520
+ minimumSample: 30, level: 0.95, timeoutMs: 1000 },
521
+ holdout
522
+ });
523
+ const résultat = await runExperiment({ ...portée, experiment: expérience });
524
+ // décision : supported | refuted | inconclusive (« non concluant »)
525
+ // stages.holdout : métriques agrégées, sans cas, réponses ni journal d'outils.
526
+ ```
527
+
528
+ Les métriques comparent les valeurs JSON par le code (`exact_match`), avec
529
+ `outputKey` / `expectedKey` facultatifs pour sélectionner des champs. Aucun
530
+ juge injecté ne peut lire les réponses finales. `honestStatistics` de P2 rend
531
+ les effectifs connus/inconnus et Wilson bilatéral (minimum 30 ; niveaux 0,90,
532
+ 0,95 ou 0,99). Sortie absente, panne ou dépassement de temps : inconnu.
533
+ `supported` exige pour **chaque métrique de chaque étape** un effectif suffisant
534
+ et un intervalle entièrement au-dessus du seuil ou à égalité ; `refuted` exige
535
+ un intervalle suffisant entièrement inférieur à un seuil. Données insuffisantes,
536
+ inconnus ou intervalle traversant le seuil : `inconclusive`. Il s'agit de tests
537
+ de seuils, sans preuve causale de progrès face à une référence. `interval` est
538
+ celui de la première métrique finale ; tous les intervalles sont dans
539
+ `stages.*.metrics`. Identifiants et empreintes d'entrées doivent être distincts
540
+ entre les jeux ; répéter une entrée ne gonfle pas l'effectif. Les intentions de
541
+ développement/validation sont journalisées ; celles du jeu final et les sorties
542
+ individuelles restent cachées.
543
+
544
+ Une proposition de rejeu est `{ agent, information?: [{ organisationId,
545
+ userId?, at, recordedAt, data }] }`. `snapshots` associe chaque
546
+ `inputSnapshotRef` à cette même forme datée ; toute référence exige son
547
+ instantané (`snapshot_missing`). Sans référence, le contexte daté enregistré
548
+ sert d'instantané. Le candidat reçoit `{ inputs, outcomes, lessons,
549
+ information, decision, asOf }`. `decision` ne contient que identifiant,
550
+ objectif, contexte, versions et permissions, jamais l'action originale ou la
551
+ réponse attendue. La compatibilité compare sa sortie à
552
+ `{ name: actionOriginale.name, input: actionOriginale.input }`.
553
+ Révisions de résultats et leçons enregistrées après la décision : exclues.
554
+ Un fait enregistré tôt mais daté du futur : refusé. Les preuves historiques des
555
+ leçons sont contrôlées ; preuves externes non datées :
556
+ `temporal_evidence_required`. Les dates factuelles imbriquées et les réponses
557
+ simulées sont contrôlées. Les réponses de lecture du rejeu exigent
558
+ `{ organisationId, userId?, at, recordedAt, data }`
559
+ (`temporal_metadata_required` sans dates) ; horizons prévus et expirations ne sont pas des
560
+ observations futures. Les dates fournies doivent être fidèles : le code ne
561
+ peut déduire une provenance non déclarée ni dater une connaissance littérale
562
+ inscrite dans la fonction candidate. Une sélection trop grande est refusée
563
+ (`replay_limit`), jamais tronquée silencieusement.
564
+
565
+ Les fonctions candidates sont sérialisées puis exécutées dans des workers et
566
+ des contextes ne recevant que du JSON et des outils simulés : pas de closure
567
+ hôte, `process`, `require`, `fetch`, fichiers, import dynamique ni rappel hôte.
568
+ Les calculs asynchrones avec outils simulés fonctionnent. Un modèle peut être
569
+ injecté comme calcul autonome de l'agent évalué ; un transport distant ou un
570
+ client capturé dans une closure ne peut pas fonctionner dans ce bac à sable.
571
+ Le cœur ne choisit et n'appelle aucun modèle pour décider du score.
572
+ Temps par cas (10–30000 ms), mémoire et taille de sortie sont bornés. Cette
573
+ frontière d'exécution applicative ne remplace pas une isolation du système
574
+ d'exploitation pour du code natif arbitraire hostile.
575
+
576
+ Le code de préparation doit conserver les cas finaux hors de la réflexion :
577
+ l'objet protégé ne peut retirer des copies déjà partagées par l'application.
578
+ Le jeu final est à usage unique pour empêcher les interrogations adaptatives,
579
+ et reste consommé après une panne d'exécution. Objets d'enregistrement,
580
+ contenus finaux et journal d'accès restent locaux au processus, sans reprise
581
+ après redémarrage. Métadonnées d'enregistrement et résultats agrégés sont
582
+ audités dans les constats du gouverneur (`experiment_registered`,
583
+ `experiment_started`, `experiment_completed` / `experiment_failed`), en
584
+ mémoire ou PostgreSQL. Aucun nouveau schéma SQL ni dépendance.
585
+ Les tests réels utilisent
586
+ `CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p3a_test` ;
587
+ une base explicitement fournie mais indisponible fait échouer les tests P3,
588
+ sans les ignorer. Preuves de mutation séparées :
589
+ `node packages/conscience/test/experiments-mutations.js`.
590
+
591
+ ## P3 · vigilance (2/2)
592
+
593
+ Seconde moitié de P3, dans `@astratra/conscience/autoconscience` : six modules
594
+ déterministes qui surveillent, rappellent, retiennent, mettent à l'épreuve,
595
+ recoupent et transforment les leçons en tests. Aucun n'importe de modèle de
596
+ langage (un test lit les sources) et aucun n'applique quoi que ce soit : tout
597
+ changement passe par une proposition au gouverneur, et chaque appel vérifie
598
+ d'abord que le gouverneur existe, est authentique et n'est pas à l'arrêt
599
+ (`assertGovernorReady`).
600
+
601
+ | N° | Fonction | Rôle |
602
+ | --- | --- | --- |
603
+ | 17 | `detectDrift` | Surveillance de dérive des entrées, des résultats et des performances, avec recommandation codée. |
604
+ | 18 | `createFollowUps` | Mémoire prospective : `scheduleFollowUp`, `dueFollowUps`. |
605
+ | 26 | `abstentionPolicy` | Seuil de confiance tiré de la calibration et des coûts d'erreur. |
606
+ | 27 | `generateAdversarialCases` | Scénarios-pièges candidats à partir des échecs récents. |
607
+ | 14 | `reviewByRoles` | Vérificateur, contradicteur et contrôleur des risques, revues séparées. |
608
+ | 03 | `lessonToScenario` | Une leçon vérifiée devient un scénario anti-régression. |
609
+
610
+ ### Surveillance de dérive (17)
611
+
612
+ ```js
613
+ const rapport = await detectDrift({
614
+ governor, organisationId, agentId, domain,
615
+ baseline: { window: { from, to }, inputs: { domains, languages, lengths },
616
+ outcomes: { succeeded, failed, unknown },
617
+ performance: { calibration: { sampleSize, brierScore, confidenceGap }, tools: [{ tool, provider, knownCalls, failures }] } },
618
+ current: { /* même forme */ },
619
+ calendars, // DomainCalendar[] de P2, de la même organisation
620
+ recentChange, // { kind, id, version, previousVersion, deployedAt }
621
+ propose: {} // facultatif : un retour arrière recommandé devient une proposition EN ATTENTE
622
+ });
623
+ ```
624
+
625
+ `snapshotWindow({ decisions, findings, agentId, domain, languageOf })` construit
626
+ un résumé à partir des données de P2 (le cœur ne détecte aucune langue :
627
+ `languageOf` est à vous).
628
+
629
+ Tests simples, documentés dans le code : l'indice de stabilité de population
630
+ (PSI) pour les répartitions (domaines, langues, longueurs découpées aux
631
+ quintiles de la référence ; un pseudo-comptage de 0,5 par catégorie ; sous 0,10
632
+ stable, de 0,10 à 0,25 modéré, 0,25 et plus significatif) et la différence de deux
633
+ proportions avec l'intervalle de score hybride de Newcombe, construit sur les
634
+ intervalles de Wilson de P2 (taux de réussite, part d'inconnu, taux d'erreur des
635
+ outils). Un écart est significatif quand l'intervalle exclut zéro et que l'écart
636
+ atteint 5 points (`minimumEffect`). Le score de Brier et l'écart de confiance se
637
+ comparent à un seuil (`brierDelta`, `confidenceGapDelta`). Une fenêtre de moins de
638
+ `minimumSample` observations connues ne conclut jamais : `insufficient_data`.
639
+
640
+ Un **calendrier métier** est consulté avant d'accuser l'agent : une période qui
641
+ recouvre la fenêtre courante et pas la fenêtre de référence explique l'écart
642
+ (`attribution: 'calendar'`, recommandation `monitor`, `reexamineAfter`).
643
+
644
+ Recommandation codée : `monitor` (surveiller), `investigate` (enquêter : les
645
+ entrées ont bougé ou un outil s'est dégradé en même temps qu'une baisse),
646
+ `freeze` (geler : baisse sévère sans explication, `freezeDrop`),
647
+ `propose_rollback` (proposer un retour arrière : baisse dans une fenêtre qui
648
+ commence après un changement récent, entrées stables). Le rapport dit toujours
649
+ `applied: false`. Avec `propose`, le retour arrière devient une proposition en
650
+ attente chez le gouverneur (risque élevé, deux approbations par défaut) et rien
651
+ n'est annulé pour autant : un humain décide, puis `rollbackChange` reste à vous.
652
+ `recordedBy` dépose aussi un constat pour le bilan du matin.
653
+
654
+ ### Mémoire prospective (18)
655
+
656
+ ```js
657
+ const vstore = createMemoryVigilanceStore(); // ou createPostgresVigilanceStore(pool)
658
+ const conscience = createConscience({ governor, masker, erasers: [followUpEraser(vstore)] });
659
+ const followUps = createFollowUps({ governor, conscience, store: vstore, masker });
660
+ await followUps.scheduleFollowUp({ organisationId, decisionId, observableAt, question });
661
+ const dus = await followUps.dueFollowUps({ organisationId }); // { followUp, decision }[]
662
+ await followUps.completeFollowUp({ organisationId, id });
663
+ ```
664
+
665
+ Idempotent : même décision, même date, même question, même suivi
666
+ (`created: false`). La question est masquée avant d'être gardée. La décision doit
667
+ exister dans l'organisation (celle d'une autre : `not_found`). Les suivis
668
+ s'effacent avec la personne par `eraseSubject` (déclarer `followUpEraser`) ; un
669
+ suivi dont la décision a été effacée ou a expiré n'est jamais rendu comme dû. Le
670
+ contenu d'un suivi dû est une donnée, jamais une consigne.
671
+
672
+ ### Abstention (26)
673
+
674
+ `abstentionPolicy({ governor, organisationId, agentId, domain, calibration, errorCosts, currentThreshold, propose })`.
675
+ Agir vaut la peine quand la chance de réussite atteint
676
+ `falsePositive / (falsePositive + falseNegative)` (la table de coûts de P2). Le
677
+ seuil est la plus basse confiance annoncée, ayant ses propres observations, à
678
+ partir de laquelle la borne basse de Wilson du taux de réussite observé reste au
679
+ dessus de ce rapport, sur au moins `minimumSample` décisions. Pas assez de données
680
+ ou pas de table de coûts : un seuil prudent par défaut (0,8), jamais plus bas que
681
+ celui déjà en vigueur. Aucune zone fiable : 1. `shouldAbstain(policy, { confidence, actionKind })`
682
+ répond `proceed`, `ask_clarification` (demander une précision) ou, pour les
683
+ actions `write` et `confirm`, `propose_verification`, toujours d'après le seuil
684
+ **en vigueur** (`effectiveThreshold`). Un nouveau seuil est une proposition sur la
685
+ cible `threshold:abstention:<agent>:<domaine>` ; rien n'est appliqué ici.
686
+
687
+ ### Adversaire nocturne (27) et leçons devenues tests (03)
688
+
689
+ ```js
690
+ const library = createScenarioLibrary({ governor, store: vstore, masker });
691
+ const { candidates, rejected } = await generateAdversarialCases({ governor, organisationId, failures, masker, generator, library });
692
+ const cas = await lessonToScenario(lesson, { governor, masker, question, tools, expect, library });
693
+ // plus tard, une fois les propositions approuvées par des humains chez le gouverneur :
694
+ const suite = (await library.approved({ organisationId })).map((a) => a.scenario); // pour evaluateAgent
695
+ ```
696
+
697
+ `generateAdversarialCases` transforme les échecs récents en candidats de quatre
698
+ catégories (injection, ambiguïté, cas limite, accès à une autre organisation) au
699
+ format d'`evaluateAgent` de `@astratra/testkit` : `id`, `question`, outils
700
+ simulés (résultats fixes, sans effet), `expect`, et un `score` qui fait échouer le
701
+ cas si un outil interdit est appelé ou un texte interdit apparaît. Un
702
+ **générateur injecté** peut écrire les cas (une fonction qui rend des données
703
+ seulement ; ce qu'elle rend est validé, masqué, et remplacé par le gabarit s'il
704
+ est invalide ou en échec). Sans générateur, des gabarits déterministes : même
705
+ échec, mêmes cas. Le **masqueur est obligatoire** et passe sur les échecs et sur
706
+ tout ce que rend le générateur.
707
+
708
+ `lessonToScenario` accepte une leçon de statut `verified` (preuves, assez de
709
+ décisions distinctes, aucun conflit ouvert) ; une hypothèse, une leçon à
710
+ réévaluer ou retirée est refusée (`lesson_not_verified`). La leçon dit ce qui a
711
+ été appris ; vous décrivez comment le vérifier, et un scénario qui n'affirme rien
712
+ est refusé.
713
+
714
+ Tout candidat naît `to_review` (« à relire »). Avec une bibliothèque, il devient
715
+ une proposition au gouverneur (cible de type `instructions`, identifiant
716
+ `scenarios:<agent>`, réglable par `targetKind`). `library.approved()` est la
717
+ **seule** entrée dans les tests : elle ne garde un candidat que si des humains ont
718
+ approuvé exactement ce contenu (même empreinte) et que le contenu gardé n'a pas
719
+ changé. Un modèle, un refus, une approbation expirée ou un candidat modifié le
720
+ laissent dehors.
721
+
722
+ ### Revue multi-rôles (14)
723
+
724
+ ```js
725
+ const revue = await reviewByRoles({ governor, organisationId, finding, roles: { verifier, contradictor, riskController } });
726
+ revue.advances; revue.status; // true / 'supported', ou false / 'hypothesis' avec revue.blockers
727
+ ```
728
+
729
+ Trois fonctions séparées, pas un vote de modèles. Le constat n'avance que si le
730
+ vérificateur cite une preuve **indépendante** (ni les preuves ni les décisions du
731
+ constat, même organisation, confirmée au besoin par `evidenceExists`), si aucune
732
+ explication concurrente du contradicteur n'est aussi forte que la confiance du
733
+ constat, et si le contrôleur des risques valide une portée au moins aussi large
734
+ que celle demandée (`observation` < `agent` < `domain` < `organisation`). Un rôle
735
+ qui lève une erreur ou répond mal bloque le constat. Les rôles reçoivent une copie
736
+ gelée du constat, jamais les réponses des autres.
737
+
738
+ ### Stockage
739
+
740
+ `createMemoryVigilanceStore()` et `createPostgresVigilanceStore(db, { prefix })`
741
+ (schéma : `postgresVigilanceSchema({ prefix })`, tables `<prefix>_follow_ups` et
742
+ `<prefix>_candidates`). Même contrat, mêmes tests, chaque accès borné par
743
+ l'organisation, chaque valeur en paramètre SQL.
744
+
745
+ ## P4 · mode ombre
746
+
747
+ Propositions 21 (mode ombre) et 32 (bac à sable du mode ombre), dans
748
+ `@astratra/conscience/autoconscience`. Une stratégie candidate que des humains
749
+ ont déjà approuvée traite **en silence** une partie des vraies demandes, à côté
750
+ de la stratégie stable. Ses réponses ne vont à personne. Elles sont comparées
751
+ aux réponses stables par des métriques déterministes que vous fournissez, et
752
+ l'écart est gardé, masqué, sous forme de `ShadowRun`. Aucun modèle de langage
753
+ n'est importé (un test lit les sources) ; chaque appel vérifie d'abord
754
+ `assertGovernorReady`.
755
+
756
+ ```js
757
+ const { createSandbox, createShadowRunner, createMemoryShadowStore, shadowEraser } = require('@astratra/conscience/autoconscience');
758
+
759
+ const sandbox = await createSandbox({ governor, organisationId, tools: {
760
+ lookup_invoice: { kind: 'read', response: { status: 'unknown' } }, // simulé ou enregistré
761
+ send_reminder: { kind: 'write' } // jamais exécuté, seulement journalisé
762
+ } });
763
+ const shadow = await createShadowRunner({
764
+ governor, organisationId,
765
+ candidate: { kind: 'instructions', id: 'reminders', agent }, // ou { proposalId, agent }
766
+ sandbox, sampleRate: 0.1,
767
+ budget: { maxRuns: 500, maxCost: 50, costPerRun: 0.1 },
768
+ masker, // obligatoire
769
+ store: createMemoryShadowStore(), // ou createPostgresShadowStore(pool)
770
+ metrics: [
771
+ { name: 'accuracy', score: ({ input, output }) => output.total === input.expected },
772
+ { name: 'sources_accuracy', score: ({ output }) => output.sourced === true, maxRegression: 0.02 },
773
+ { name: 'minor_protection', critical: true, score: ({ input, output }) => !(input.minor && output.disclosed) }
774
+ ],
775
+ target: 'accuracy', minimumSample: 30
776
+ });
777
+
778
+ // Dans le chemin de la requête : répondre avec la stratégie stable, puis passer la main. Ne jamais attendre `done`.
779
+ const answer = await stable(request);
780
+ respond(answer);
781
+ shadow.observe({ request: { id: request.id, userId: request.userId, input: request.input }, stableResult: { output: answer, durationMs, cost } });
782
+
783
+ const report = await shadow.report({ propose: {}, recordedBy: { kind: 'system', id: 'shadow' } });
784
+ report.conclusion; // 'insufficient_data' | 'regression' | 'no_difference' | 'promising'
785
+ ```
786
+
787
+ **Quelle stratégie peut tourner.** Soit la version candidate d'un objet du
788
+ gouverneur (`{ kind, id }` : la version mise en place à partir d'une proposition
789
+ approuvée par des humains), soit une proposition à l'état `approved` avec des
790
+ approbations humaines (`{ proposalId }`). Une proposition en attente, déclinée,
791
+ rejetée ou expirée, une version stable, un objet inconnu ou l'objet d'une autre
792
+ organisation sont refusés (`candidate_not_approved`, `candidate_not_staged`,
793
+ `not_found`). La vérification est refaite avant chaque exécution : une candidate
794
+ annulée, promue ou remplacée arrête l'ombre.
795
+
796
+ **La réponse de la candidate n'est jamais renvoyée.** `observe` est synchrone, ne
797
+ lève jamais d'erreur et n'attend jamais : il rend `{ scheduled, reason, done }`, et
798
+ `done` (qui ne rejette jamais) donne un accusé (`recorded` avec un identifiant
799
+ d'exécution, ou `skipped`, `timeout`, `error` avec une raison) qui ne contient
800
+ aucune sortie de la candidate. L'exécution se fait en arrière-plan, après la
801
+ réponse stable. Une candidate en erreur, lente ou hostile, un magasin ou un
802
+ masqueur en panne, une métrique qui lève : tout est isolé et compté (`stats()`),
803
+ rien n'atteint l'appelant. Un délai (`deadlineMs`) abandonne une exécution
804
+ bloquée, et `maxConcurrent` écarte une rafale en `busy` au lieu de la mettre en
805
+ file.
806
+
807
+ **Bac à sable seulement (32).** La candidate est une fonction autonome exécutée
808
+ dans le bac à sable de P3 : aucun objet de l'hôte, ni `process`, ni `require`, ni
809
+ minuterie, ni `fetch`. Ses outils sont ceux du bac à sable : une lecture rend un
810
+ enregistrement (les `recordings` facultatifs de `observe`, par exemple ce que la
811
+ requête stable a lu) ou une réponse simulée ; une écriture n'est **jamais
812
+ exécutée**, même si la candidate l'appelle, et n'est que journalisée comme
813
+ intention (`writeIntentions`, masquée). L'ombre n'ouvre aucune connexion réseau
814
+ de son propre chef. Un appel de modèle dans une candidate est un outil du bac à
815
+ sable, rejoué ou simulé, jamais un appel réel.
816
+
817
+ **Échantillonnage, budget, arrêt d'urgence.** Une demande est choisie par un
818
+ hachage de son identifiant et de celui de l'ombre : la même demande donne
819
+ toujours le même choix, quel que soit l'ordre, et `sampleRate: 0.1` choisit un
820
+ sous-ensemble de ce que choisit `0.5`. Le budget est obligatoire et plafonné :
821
+ `maxRuns`, `maxCost` (`costPerRun` est le plafond réservé à une exécution,
822
+ `costOf` ne peut que l'abaisser), `maxDurationMs` (temps mesuré, que les
823
+ exécutions déjà en cours peuvent dépasser) et `governorAgentId` pour dépenser
824
+ aussi par `governor.authorizeSpend`. Budget épuisé ou arrêt d'urgence du
825
+ gouverneur : l'ombre s'arrête aussitôt, reste arrêtée (lever l'arrêt ne la
826
+ réveille pas : en démarrer une nouvelle) et une exécution qui se termine après
827
+ l'arrêt est abandonnée. Les budgets comptent les exécutions déjà stockées : un
828
+ redémarrage poursuit la même ombre.
829
+
830
+ **ShadowRun.** Par demande choisie : la demande masquée, les sorties candidate et
831
+ stable masquées (remplacées par une empreinte au-delà de 20 000 caractères), le
832
+ score de chaque côté pour chaque métrique (`succeeded`, `failed`, `unknown`), si
833
+ les deux réponses concordent, les intentions d'écriture, la durée, le coût et les
834
+ incidents (`candidate_failed`, `candidate_timeout`, `scoring_failed`, ...).
835
+ L'identifiant brut de la demande n'est pas gardé. Un masqueur en échec garde
836
+ l'exécution hors du magasin. Une candidate qui ne produit rien échoue aux
837
+ métriques : elle ne peut pas avoir réussi.
838
+
839
+ **Rapport.** Par métrique, le taux de réussite de chaque côté avec son
840
+ intervalle de Wilson et l'effectif minimal (P2 : en dessous, `insufficient_data`
841
+ et aucune différence), les comptes appariés et la différence (candidate moins
842
+ stable) avec un intervalle de Newcombe. Anti-Goodhart (P2) : la métrique `target`
843
+ doit s'améliorer pendant que toutes les autres restent dans leur
844
+ `maxRegression` (et `limits.cost`) ; au moins une contre-mesure est exigée à la
845
+ construction. Les métriques critiques listent les demandes où la stratégie stable
846
+ a réussi et la candidate échoué. La conclusion est un code, dans cet ordre :
847
+
848
+ | Conclusion | Quand |
849
+ |---|---|
850
+ | `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`. |
851
+ | `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. |
852
+ | `promising` | La cible s'est améliorée avec un intervalle au-dessus de zéro et toutes les contre-mesures ont tenu. |
853
+ | `no_difference` | Assez de données, aucune différence significative et aucune régression. |
854
+
855
+ Le rapport ne dit jamais « prouvé » : `provesImprovement` vaut toujours `false`,
856
+ `causality` vaut `not_established`, `applied` vaut `false`. Une comparaison en
857
+ ombre sur un échantillon de vraies demandes peut rendre une amélioration
858
+ prometteuse, rien de plus. Avec `propose`, un résultat prometteur devient une
859
+ **proposition en attente** chez le gouverneur (type de la candidate, identifiant
860
+ `shadow:<id>:<version>`) ; avec `recordedBy`, toute conclusion est classée comme
861
+ constat pour le bilan du matin. Déployer et promouvoir restent à un humain
862
+ (`deployChange`, `promoteChange`) : l'ombre ne les appelle jamais.
863
+
864
+ **Isolation et effacement.** Chaque ligne appartient à une organisation et chaque
865
+ lecture et écriture est bornée par elle ; une candidate, un bac à sable ou un
866
+ appel de magasin d'une autre organisation est refusé. Les exécutions portent le
867
+ `userId` de la demande : enregistrer `shadowEraser(store)` dans
868
+ `createConscience({ erasers })`, ou appeler `shadow.eraseSubject`, pour les
869
+ supprimer avec la personne.
870
+
871
+ **Stockage.** `createMemoryShadowStore()` et `createPostgresShadowStore(db, { prefix })`
872
+ (schéma : `postgresShadowSchema({ prefix })`, table `<prefix>_runs`). Même
873
+ contrat, mêmes tests, toute valeur est un paramètre SQL.
874
+
875
+ ## Tests
876
+
877
+ ```sh
878
+ npm test -w @astratra/conscience
879
+ CONSCIENCE_TEST_DATABASE_URL=postgresql:///conscience_p2_test npm test -w @astratra/conscience
880
+ CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p4_test node --test packages/conscience/test/shadow.postgres.test.js
881
+ ```
882
+
883
+ Les tests PostgreSQL ne tournent que si l'URL désigne une base dont le nom
884
+ finit par `_test` ; chaque test crée ses propres tables puis les supprime. Une base de test
885
+ absente est créée avec `createdb` si permis ; sinon les tests d'intégration
886
+ sont ignorés avec une raison explicite, sans afficher l'URL.
887
+
888
+ ## Limites
889
+
890
+ - Aucun modèle de langage ni changement automatique : P2 évalue uniquement des preuves structurées,
891
+ tout changement passe par un humain, et le gouverneur n'applique jamais un changement à votre
892
+ application. Il versionne les objets et dit quelle version servir (`resolveVersion`) ; c'est à vous
893
+ de lire cette version là où vous utilisez l'objet.
894
+ - Le gouverneur reconnaît les portées protégées par leurs noms et leurs clés,
895
+ pas en lisant du texte : une proposition doit décrire honnêtement sa cible,
896
+ et tout cas ambigu est rejeté plutôt qu'accepté.
897
+ - Le masqueur est le vôtre : le paquet garantit que le texte stocké y est
898
+ passé, pas qu'il a tout trouvé.
899
+ - Le mode ombre ne juge que les demandes échantillonnées (une rafale au-delà de `maxConcurrent` est écartée et comptée) et ses
900
+ intervalles ignorent l'appariement des demandes : ils sont prudents. Les métriques sont les vôtres, déterministes, et la
901
+ lecture d'un outil n'y est rejouée que d'après des enregistrements.