@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.
- package/LICENSE +21 -0
- package/README.fr.md +954 -0
- package/README.md +915 -2
- package/package.json +50 -4
- package/src/autoconscience/experiments/common.js +76 -0
- package/src/autoconscience/experiments/execution.js +33 -0
- package/src/autoconscience/experiments/holdout.js +88 -0
- package/src/autoconscience/experiments/laboratory.js +99 -0
- package/src/autoconscience/experiments/replay.js +113 -0
- package/src/autoconscience/experiments/runner.js +54 -0
- package/src/autoconscience/experiments/sandbox.js +58 -0
- package/src/autoconscience/index.d.ts +203 -0
- package/src/autoconscience/index.js +116 -0
- package/src/autoconscience/lessons.js +32 -0
- package/src/autoconscience/shadow/candidate.js +69 -0
- package/src/autoconscience/shadow/index.d.ts +169 -0
- package/src/autoconscience/shadow/index.js +11 -0
- package/src/autoconscience/shadow/report.js +125 -0
- package/src/autoconscience/shadow/runner.js +384 -0
- package/src/autoconscience/shadow/store.js +98 -0
- package/src/autoconscience/signals.js +88 -0
- package/src/autoconscience/statistics.js +84 -0
- package/src/autoconscience/vigilance/abstention.js +123 -0
- package/src/autoconscience/vigilance/adversary.js +145 -0
- package/src/autoconscience/vigilance/common.js +56 -0
- package/src/autoconscience/vigilance/drift.js +306 -0
- package/src/autoconscience/vigilance/followups.js +100 -0
- package/src/autoconscience/vigilance/index.d.ts +190 -0
- package/src/autoconscience/vigilance/index.js +23 -0
- package/src/autoconscience/vigilance/lessonTests.js +40 -0
- package/src/autoconscience/vigilance/library.js +162 -0
- package/src/autoconscience/vigilance/roles.js +122 -0
- package/src/autoconscience/vigilance/store.js +166 -0
- package/src/conscience.js +559 -0
- package/src/diff.js +27 -0
- package/src/errors.js +11 -0
- package/src/governor/approvals.js +132 -0
- package/src/governor/changes.js +269 -0
- package/src/governor/governor.js +286 -0
- package/src/governor/index.d.ts +385 -0
- package/src/governor/index.js +22 -0
- package/src/governor/policy.js +136 -0
- package/src/governor/postgres.js +243 -0
- package/src/governor/remote.js +305 -0
- package/src/governor/review.js +191 -0
- package/src/governor/rollout.js +66 -0
- package/src/governor/stores.js +136 -0
- package/src/governor/util.js +53 -0
- package/src/guard.js +21 -0
- package/src/index.d.ts +244 -0
- package/src/index.js +23 -0
- package/src/memoryStore.js +65 -0
- package/src/postgres.js +93 -0
- 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.
|