@astratra/conscience 1.1.0 → 1.3.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/README.fr.md +165 -0
- package/README.md +162 -0
- package/package.json +11 -2
- package/src/governor/calendar.js +101 -0
- package/src/governor/index.d.ts +178 -1
- package/src/governor/index.js +8 -0
- package/src/governor/mongo.js +132 -0
- package/src/governor/mongoUtil.js +33 -0
- package/src/governor/toolBudgetPostgres.js +59 -0
- package/src/governor/tools.js +388 -0
- package/src/index.d.ts +3 -0
- package/src/index.js +3 -0
- package/src/mongo.js +52 -0
package/README.fr.md
CHANGED
|
@@ -141,6 +141,83 @@ Changements réversibles ci-dessous).
|
|
|
141
141
|
constat) est écrite au journal d'audit avant d'être rendue :
|
|
142
142
|
`listAudit({ organisationId })`.
|
|
143
143
|
|
|
144
|
+
### Politique d'outils, budget calendaire, arrêt d'urgence des outils (1.3.0)
|
|
145
|
+
|
|
146
|
+
Le reste du gouverneur décide des changements qu'un agent propose pour
|
|
147
|
+
lui-même. `createToolPolicy` décide d'**un appel d'un outil**, par code, hors
|
|
148
|
+
de tout modèle. Il ne sait pas ce que fait un outil : familles, niveaux,
|
|
149
|
+
plafonds et chaque mot rendu viennent de votre configuration.
|
|
150
|
+
|
|
151
|
+
```js
|
|
152
|
+
const { createToolPolicy, createPostgresGovernorStore, createPostgresToolBudgetStore,
|
|
153
|
+
postgresToolBudgetSchema } = require('@astratra/conscience/governor');
|
|
154
|
+
|
|
155
|
+
await pool.query(postgresToolBudgetSchema()); // une fois, idempotent
|
|
156
|
+
const policy = createToolPolicy({
|
|
157
|
+
store: createPostgresGovernorStore(pool), // journal d'audit + interrupteur
|
|
158
|
+
tools: [
|
|
159
|
+
{ name: 'lire_elements', family: 'catalogue', level: 'read', maxPerRun: 5 },
|
|
160
|
+
{ name: 'modifier_element', family: 'catalogue', level: 'controlled',
|
|
161
|
+
validate: (input) => Number.isInteger(input?.amount),
|
|
162
|
+
overThreshold: (input, settings) => input.amount > settings.maxAmount },
|
|
163
|
+
{ name: 'supprimer_element', family: 'catalogue', level: 'sensitive' }
|
|
164
|
+
],
|
|
165
|
+
// Lu avant CHAQUE appel (une ligne en base, un tableau de bord...). S'il échoue, l'appel est refusé.
|
|
166
|
+
settings: async ({ organisationId }) => ({ enabled: true, families: { catalogue: true }, budgetLimit: 15000, maxCallsPerRun: 12, maxAmount: 500 }),
|
|
167
|
+
budget: { period: 'month', timeZone: 'Europe/Paris', store: createPostgresToolBudgetStore(pool) },
|
|
168
|
+
emergency: { activateRoles: ['owner', 'support'], releaseRoles: ['owner'] }
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
const run = policy.createRun(); // compteurs d'une conversation / d'une tâche
|
|
172
|
+
const decision = await policy.decide({ tool: 'modifier_element', input: { amount: 40 }, run, actor: { kind: 'model', id: 'assistant' } });
|
|
173
|
+
// { allowed, decision: 'allowed' | 'pending' | 'refused', code, level, input, budget, auditId, ... }
|
|
174
|
+
|
|
175
|
+
const done = await policy.execute({ tool: 'lire_elements', input: {}, run }, (input, { signal }) => lireElements(input, { signal }));
|
|
176
|
+
// N'exécute que si l'appel est autorisé. done.executed, done.result, done.interrupted.
|
|
177
|
+
await policy.recordSpend({ id: 'appel-42', amount: 120 }); // unités entières (centimes), idempotent par id
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
- **Niveaux** (`TOOL_LEVELS`) : `read` s'exécute ; `controlled` s'exécute sauf au-delà
|
|
181
|
+
de son `overThreshold(input, settings)` ou si le tour a lu un contenu non fiable
|
|
182
|
+
(`run.markUntrusted()` ou `untrusted: true` sur l'appel) : il est alors `pending` ;
|
|
183
|
+
`sensitive` est toujours `pending`. La politique n'exécute jamais un appel en attente :
|
|
184
|
+
l'application le garde et une personne décide.
|
|
185
|
+
- **Codes de refus** (`TOOL_REASONS`) : `emergency_stop`, `disabled`, `unknown_tool`,
|
|
186
|
+
`family_disabled`, `invalid_input`, `budget_exceeded`, `cap_reached` (appels par tour
|
|
187
|
+
ou `maxPerRun` de l'outil), et `settings_unavailable` quand les réglages, l'interrupteur
|
|
188
|
+
ou le budget sont illisibles. Codes d'attente : `sensitive_tool`, `untrusted_context`,
|
|
189
|
+
`over_threshold`. Ordre : arrêt, désactivé, inconnu, famille, entrée, budget, plafonds,
|
|
190
|
+
niveau. Les appels demandés ensemble sont comptés tout de suite : ils ne passent pas
|
|
191
|
+
tous sous un plafond.
|
|
192
|
+
- **Vos mots** : `labels: { levels, decisions, codes }` renomme ce que vous recevez
|
|
193
|
+
(`{ decisions: { pending: 'en_attente' } }`) ; les outils déclarent alors leur niveau
|
|
194
|
+
avec votre mot.
|
|
195
|
+
- **Budget calendaire** (`createCalendarBudget`, utilisable seul) : consommation comptée
|
|
196
|
+
par `'month'` ou `'day'` (ou votre fonction) d'un fuseau horaire (`calendarPeriodKey`),
|
|
197
|
+
plafond et montants en unités entières, jamais en flottants (prenez une unité plus
|
|
198
|
+
petite pour les fractions de centime). `check()` est lu avant chaque appel et teste
|
|
199
|
+
aussi le `estimatedCost` de l'outil ; une consommation tombe dans la période de son
|
|
200
|
+
propre instant : un appel à 23 h 30 le 31 octobre à Paris compte pour octobre là-bas
|
|
201
|
+
et pour novembre en UTC. Magasins : mémoire (`createMemoryToolBudgetStore`),
|
|
202
|
+
PostgreSQL (`createPostgresToolBudgetStore` : une seule requête atomique et
|
|
203
|
+
idempotente, bigint), ou le vôtre `{ getSpent(scope, period), addSpend({ scope,
|
|
204
|
+
period, id, amount, at }) }` (idempotent par id). La portée est `organisationId`
|
|
205
|
+
par défaut. Le plafond est atteint quand `spent >= limit` ; la mesure se faisant après
|
|
206
|
+
l'appel, le dernier appel peut le dépasser.
|
|
207
|
+
- **Arrêt d'urgence** : `halt({ by, reason, organisationId? })` est lu avant chaque
|
|
208
|
+
appel et pendant l'exécution d'un outil. `execute()` donne à l'outil un `AbortSignal`
|
|
209
|
+
qui s'annule aussitôt pour un arrêt dans ce processus, et sous `pollMs` (1 s par défaut)
|
|
210
|
+
pour un arrêt tiré par un autre processus ; l'appel est aussi abandonné si l'outil
|
|
211
|
+
ignore le signal (`interrupted: true`). `activateRoles` le tirent (par défaut : toute
|
|
212
|
+
personne identifiée), `releaseRoles` le lèvent (par défaut : tout humain ; un acteur
|
|
213
|
+
`model` ou `engine` jamais). L'option `governor` fait aussi arrêter les outils par
|
|
214
|
+
l'interrupteur du gouverneur.
|
|
215
|
+
- **Audit** : chaque décision est écrite dans le journal du gouverneur avant d'être
|
|
216
|
+
rendue (`tool_decision` : qui, outil, famille, niveau, décision, motifs, empreinte de
|
|
217
|
+
l'entrée, jamais l'entrée brute), plus `tool_outcome`, `tool_halt`, `tool_resume` et
|
|
218
|
+
leurs refus. Si le journal ne peut pas être écrit, l'appel ne s'exécute pas.
|
|
219
|
+
`onEvent` reçoit les mêmes enregistrements.
|
|
220
|
+
|
|
144
221
|
### Approbations (matrice, double approbation, expiration)
|
|
145
222
|
|
|
146
223
|
L'approbation est décidée par la politique, pas par celui qui propose :
|
|
@@ -403,6 +480,7 @@ vérifié.
|
|
|
403
480
|
```js
|
|
404
481
|
postgresConscienceSchema({ prefix: 'astratra_conscience' }) // table <prefix>_records
|
|
405
482
|
postgresGovernorSchema({ prefix: 'astratra_governor' }) // <prefix>_proposals, _audit, _spend, _controls, _objects, _versions, _findings
|
|
483
|
+
postgresToolBudgetSchema({ prefix: 'astratra_tools' }) // <prefix>_budget_totals, _budget_entries (tool budget, 1.3.0)
|
|
406
484
|
```
|
|
407
485
|
|
|
408
486
|
### Écrire son propre magasin (MongoDB, ...)
|
|
@@ -925,6 +1003,93 @@ supprimer avec la personne.
|
|
|
925
1003
|
(schéma : `postgresShadowSchema({ prefix })`, table `<prefix>_runs`). Même
|
|
926
1004
|
contrat, mêmes tests, toute valeur est un paramètre SQL.
|
|
927
1005
|
|
|
1006
|
+
## Stockage MongoDB
|
|
1007
|
+
|
|
1008
|
+
Installer le pilote comme dépendance facultative seulement pour MongoDB :
|
|
1009
|
+
|
|
1010
|
+
```sh
|
|
1011
|
+
npm install mongodb
|
|
1012
|
+
```
|
|
1013
|
+
|
|
1014
|
+
Les deux magasins reçoivent un `Db` du pilote officiel. Ils n'importent jamais
|
|
1015
|
+
le pilote et n'ouvrent aucune connexion. Avec mongoose, attendre la connexion,
|
|
1016
|
+
puis fournir `connection.db` et, pour le gouverneur, `connection.getClient()`
|
|
1017
|
+
dans l'option `client`. Le pilote est une peerDependency optionnelle
|
|
1018
|
+
(`^6.0.0 || ^7.0.0`) ; mongoose n'est pas une dépendance.
|
|
1019
|
+
|
|
1020
|
+
```js
|
|
1021
|
+
const { MongoClient } = require('mongodb');
|
|
1022
|
+
const { createMongoGovernorStore, mongoGovernorIndexes, createGovernor } = require('@astratra/conscience/governor');
|
|
1023
|
+
const { createMongoConscienceStore, mongoConscienceIndexes, createConscience } = require('@astratra/conscience');
|
|
1024
|
+
|
|
1025
|
+
const client = new MongoClient(process.env.DATABASE_URL);
|
|
1026
|
+
await client.connect();
|
|
1027
|
+
const db = client.db();
|
|
1028
|
+
await mongoGovernorIndexes(db, { prefix: 'app_governor' });
|
|
1029
|
+
await mongoConscienceIndexes(db, { prefix: 'app_memory' });
|
|
1030
|
+
const governor = createGovernor({
|
|
1031
|
+
budgets: { perCycle: 1, perAgent: 5, perOrganisation: 20 }
|
|
1032
|
+
}, { store: createMongoGovernorStore(db, { prefix: 'app_governor', client }) });
|
|
1033
|
+
const conscience = createConscience({
|
|
1034
|
+
governor, masker: (texte) => masquerDansApplication(texte),
|
|
1035
|
+
store: createMongoConscienceStore(db, { prefix: 'app_memory' })
|
|
1036
|
+
});
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
Les fonctions d'index sont des migrations explicites et idempotentes, à appeler
|
|
1040
|
+
avant l'utilisation. Un préfixe contient lettres, chiffres et traits de
|
|
1041
|
+
soulignement, commence par une lettre ou un trait de soulignement, et ne dépasse
|
|
1042
|
+
pas 41 caractères. Valeurs par défaut : `astratra_governor` et
|
|
1043
|
+
`astratra_conscience`. Collections du gouverneur : suffixes `proposals`, `audit`,
|
|
1044
|
+
`spend`, `controls`, `objects`, `versions`, `findings`, `sequences`, `locks`.
|
|
1045
|
+
Mémoire des décisions : `records` et `sequences`.
|
|
1046
|
+
|
|
1047
|
+
L'identité est encodée dans l'index unique `_id` : organisation et identifiant,
|
|
1048
|
+
avec type et version si nécessaire. Une insertion rend le contenu existant sans
|
|
1049
|
+
le modifier. Les approbations comparent atomiquement statut et nombre
|
|
1050
|
+
d'approbations ; les objets comparent leur révision. Les identifiants d'audit
|
|
1051
|
+
sont uniques, avec un compteur persistant pour l'ordre. Les records ont aussi
|
|
1052
|
+
un compteur pour départager les dates égales ; le remplacement conserve l'ordre.
|
|
1053
|
+
Filtres, rétention et `conscience.eraseSubject()` suivent le contrat PostgreSQL,
|
|
1054
|
+
avec isolation des organisations et invalidation des preuves. L'effacement
|
|
1055
|
+
porte sur la mémoire des décisions ; la conservation de l'audit du gouverneur
|
|
1056
|
+
reste une politique de l'application, comme avec PostgreSQL.
|
|
1057
|
+
|
|
1058
|
+
**Les budgets atomiques nécessitent un replica set ou un cluster shardé**
|
|
1059
|
+
(MongoDB 4.2+, selon la compatibilité serveur du pilote). Chaque réservation
|
|
1060
|
+
modifie un verrou d'organisation dans une transaction avec lecture snapshot et
|
|
1061
|
+
écriture majority. Le pilote rejoue les transactions en conflit : deux dépenses
|
|
1062
|
+
concurrentes ne peuvent pas dépasser ensemble un plafond. Un serveur standalone
|
|
1063
|
+
fait échouer la dépense, sans repli non atomique. L'option `client`, si fournie,
|
|
1064
|
+
doit désigner le propriétaire de `db`. L'application ferme ses connexions ; le
|
|
1065
|
+
magasin ferme les sessions courtes qu'il crée pour réserver. Une opération
|
|
1066
|
+
complète du gouverneur n'est pas transactionnelle : état et audit restent des
|
|
1067
|
+
écritures séparées, comme dans l'implémentation PostgreSQL. Une erreur de base
|
|
1068
|
+
remonte sans autoriser de dépense. Les limites MongoDB de taille de document
|
|
1069
|
+
s'appliquent à chaque record.
|
|
1070
|
+
|
|
1071
|
+
Les mêmes suites de contrat du gouverneur, des approbations et changements, des
|
|
1072
|
+
records et de leur évaluation tournent avec un faux client et MongoDB réel :
|
|
1073
|
+
|
|
1074
|
+
```sh
|
|
1075
|
+
npm test -w @astratra/conscience
|
|
1076
|
+
MONGO_TEST_URL=mongodb://127.0.0.1:27017/conscience_test?replicaSet=rs0 npm test -w @astratra/conscience
|
|
1077
|
+
```
|
|
1078
|
+
|
|
1079
|
+
Sans `MONGO_TEST_URL`, les tests réels sont sautés avec une raison. Avec une URL,
|
|
1080
|
+
la connexion et le replica set ou cluster shardé doivent fonctionner : une erreur
|
|
1081
|
+
fait échouer la suite. Chaque test crée un préfixe aléatoire et supprime seulement
|
|
1082
|
+
ses collections, jamais la base. Un replica set local de `mongodb-memory-server`
|
|
1083
|
+
peut fournir cette URL. Les magasins de vigilance et de mode ombre conservent
|
|
1084
|
+
leurs adaptateurs actuels : ces deux magasins MongoDB couvrent le gouverneur et
|
|
1085
|
+
les records des décisions.
|
|
1086
|
+
|
|
1087
|
+
Vérification par mutations (trois régressions détectées puis restaurées) :
|
|
1088
|
+
|
|
1089
|
+
```sh
|
|
1090
|
+
node packages/conscience/test/mongo-mutations.js
|
|
1091
|
+
```
|
|
1092
|
+
|
|
928
1093
|
## Tests
|
|
929
1094
|
|
|
930
1095
|
```sh
|
package/README.md
CHANGED
|
@@ -135,6 +135,83 @@ by itself (see Approvals and Reversible changes below).
|
|
|
135
135
|
resume, register, stage, deploy, promote, rollback, finding) is written to the audit journal before it is returned:
|
|
136
136
|
`listAudit({ organisationId })`.
|
|
137
137
|
|
|
138
|
+
### Tool policy, calendar budget, tool kill switch (1.3.0)
|
|
139
|
+
|
|
140
|
+
The rest of the governor decides about changes an agent proposes to itself.
|
|
141
|
+
`createToolPolicy` decides about **one call of one tool**, by code, outside any
|
|
142
|
+
model. It knows nothing about what a tool does: families, levels, caps and
|
|
143
|
+
every word it returns come from your configuration.
|
|
144
|
+
|
|
145
|
+
```js
|
|
146
|
+
const { createToolPolicy, createPostgresGovernorStore, createPostgresToolBudgetStore,
|
|
147
|
+
postgresToolBudgetSchema } = require('@astratra/conscience/governor');
|
|
148
|
+
|
|
149
|
+
await pool.query(postgresToolBudgetSchema()); // once, idempotent
|
|
150
|
+
const policy = createToolPolicy({
|
|
151
|
+
store: createPostgresGovernorStore(pool), // audit journal + kill switch
|
|
152
|
+
tools: [
|
|
153
|
+
{ name: 'read_items', family: 'catalogue', level: 'read', maxPerRun: 5 },
|
|
154
|
+
{ name: 'update_item', family: 'catalogue', level: 'controlled',
|
|
155
|
+
validate: (input) => Number.isInteger(input?.amount),
|
|
156
|
+
overThreshold: (input, settings) => input.amount > settings.maxAmount },
|
|
157
|
+
{ name: 'delete_item', family: 'catalogue', level: 'sensitive' }
|
|
158
|
+
],
|
|
159
|
+
// Read before EVERY call (a database row, a dashboard...). If it throws, the call is refused.
|
|
160
|
+
settings: async ({ organisationId }) => ({ enabled: true, families: { catalogue: true }, budgetLimit: 15000, maxCallsPerRun: 12, maxAmount: 500 }),
|
|
161
|
+
budget: { period: 'month', timeZone: 'Europe/Paris', store: createPostgresToolBudgetStore(pool) },
|
|
162
|
+
emergency: { activateRoles: ['owner', 'support'], releaseRoles: ['owner'] }
|
|
163
|
+
});
|
|
164
|
+
|
|
165
|
+
const run = policy.createRun(); // counters of one conversation / task
|
|
166
|
+
const decision = await policy.decide({ tool: 'update_item', input: { amount: 40 }, run, actor: { kind: 'model', id: 'assistant' } });
|
|
167
|
+
// { allowed, decision: 'allowed' | 'pending' | 'refused', code, level, input, budget, auditId, ... }
|
|
168
|
+
|
|
169
|
+
const done = await policy.execute({ tool: 'read_items', input: {}, run }, (input, { signal }) => fetchItems(input, { signal }));
|
|
170
|
+
// Runs only when allowed. done.executed, done.result, done.interrupted.
|
|
171
|
+
await policy.recordSpend({ id: 'call-42', amount: 120 }); // whole units (cents), idempotent by id
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- **Levels** (`TOOL_LEVELS`): `read` runs; `controlled` runs unless it is over its
|
|
175
|
+
own `overThreshold(input, settings)`, or the run read untrusted content
|
|
176
|
+
(`run.markUntrusted()` or `untrusted: true` on the call), then it is `pending`;
|
|
177
|
+
`sensitive` is always `pending`. The policy never runs a pending call: the
|
|
178
|
+
application keeps it and a person decides.
|
|
179
|
+
- **Refusal codes** (`TOOL_REASONS`): `emergency_stop`, `disabled`,
|
|
180
|
+
`unknown_tool`, `family_disabled`, `invalid_input`, `budget_exceeded`,
|
|
181
|
+
`cap_reached` (calls per run, or `maxPerRun` of the tool), and
|
|
182
|
+
`settings_unavailable` when settings, kill switch or budget cannot be read.
|
|
183
|
+
Pending codes: `sensitive_tool`, `untrusted_context`, `over_threshold`.
|
|
184
|
+
Order: stop, disabled, unknown, family, input, budget, caps, level. Calls asked
|
|
185
|
+
together are counted at once, so they cannot all slip under a cap.
|
|
186
|
+
- **Your words**: `labels: { levels, decisions, codes }` renames what you get
|
|
187
|
+
back (`{ decisions: { pending: 'en_attente' } }`); tools then declare their
|
|
188
|
+
level in your word.
|
|
189
|
+
- **Calendar budget** (`createCalendarBudget`, also usable alone): consumption
|
|
190
|
+
counted per `'month'` or `'day'` (or your own function) of a time zone
|
|
191
|
+
(`calendarPeriodKey`), cap and amounts are whole units, never floats (use a
|
|
192
|
+
smaller unit for fractions of a cent). `check()` runs before each call and
|
|
193
|
+
also tests the tool's `estimatedCost`; a consumption lands in the period of
|
|
194
|
+
its own instant, so a call at 23:30 on 31 October in Paris counts for
|
|
195
|
+
October there and for November in UTC. Stores: memory
|
|
196
|
+
(`createMemoryToolBudgetStore`), PostgreSQL (`createPostgresToolBudgetStore`:
|
|
197
|
+
one atomic, idempotent statement, bigint), or your own `{ getSpent(scope,
|
|
198
|
+
period), addSpend({ scope, period, id, amount, at }) }` (idempotent by id).
|
|
199
|
+
The scope is `organisationId` by default. The cap is reached when
|
|
200
|
+
`spent >= limit`; with the measure after the call, the last call may pass it.
|
|
201
|
+
- **Emergency stop**: `halt({ by, reason, organisationId? })` is read before
|
|
202
|
+
each call and while a tool runs. `execute()` gives the tool an `AbortSignal`
|
|
203
|
+
that aborts at once on a stop in this process, and within `pollMs` (default
|
|
204
|
+
1 s) on a stop pulled by another process; the call is also abandoned if the
|
|
205
|
+
tool ignores the signal (`interrupted: true`). `activateRoles` pull it
|
|
206
|
+
(default: anyone with an id), `releaseRoles` lift it (default: any human; a
|
|
207
|
+
`model` or `engine` actor never can). A `governor` option makes the governor
|
|
208
|
+
kill switch stop the tools too.
|
|
209
|
+
- **Audit**: every decision is written to the governor journal before it is
|
|
210
|
+
returned (`tool_decision`: who, tool, family, level, decision, reasons, input
|
|
211
|
+
fingerprint, never the raw input), plus `tool_outcome`, `tool_halt`,
|
|
212
|
+
`tool_resume` and their refusals. If the journal cannot be written the call
|
|
213
|
+
does not run. `onEvent` receives the same records.
|
|
214
|
+
|
|
138
215
|
### Approvals (matrix, double approval, expiry)
|
|
139
216
|
|
|
140
217
|
Approval is decided by the policy, not by whoever proposes:
|
|
@@ -384,6 +461,7 @@ uses parameters only; the table prefix is a checked identifier.
|
|
|
384
461
|
```js
|
|
385
462
|
postgresConscienceSchema({ prefix: 'astratra_conscience' }) // table <prefix>_records
|
|
386
463
|
postgresGovernorSchema({ prefix: 'astratra_governor' }) // <prefix>_proposals, _audit, _spend, _controls, _objects, _versions, _findings
|
|
464
|
+
postgresToolBudgetSchema({ prefix: 'astratra_tools' }) // <prefix>_budget_totals, _budget_entries (tool budget, 1.3.0)
|
|
387
465
|
```
|
|
388
466
|
|
|
389
467
|
### Writing your own store (MongoDB, ...)
|
|
@@ -887,6 +965,90 @@ organisation is refused. Runs carry the `userId` of the request: register
|
|
|
887
965
|
(schema: `postgresShadowSchema({ prefix })`, table `<prefix>_runs`). Same
|
|
888
966
|
contract, same tests, every value a SQL parameter.
|
|
889
967
|
|
|
968
|
+
## MongoDB storage
|
|
969
|
+
|
|
970
|
+
Install the optional peer dependency only when using MongoDB:
|
|
971
|
+
|
|
972
|
+
```sh
|
|
973
|
+
npm install mongodb
|
|
974
|
+
```
|
|
975
|
+
|
|
976
|
+
Both stores accept a native driver `Db`. They never import the driver or open a
|
|
977
|
+
connection themselves. With mongoose, wait for the connection, then pass
|
|
978
|
+
`connection.db`; pass `connection.getClient()` as `client` for the governor.
|
|
979
|
+
The driver is an optional peer (`^6.0.0 || ^7.0.0`), with no mandatory runtime
|
|
980
|
+
installation and no mongoose dependency.
|
|
981
|
+
|
|
982
|
+
```js
|
|
983
|
+
const { MongoClient } = require('mongodb');
|
|
984
|
+
const { createMongoGovernorStore, mongoGovernorIndexes, createGovernor } = require('@astratra/conscience/governor');
|
|
985
|
+
const { createMongoConscienceStore, mongoConscienceIndexes, createConscience } = require('@astratra/conscience');
|
|
986
|
+
|
|
987
|
+
const client = new MongoClient(process.env.DATABASE_URL);
|
|
988
|
+
await client.connect();
|
|
989
|
+
const db = client.db();
|
|
990
|
+
await mongoGovernorIndexes(db, { prefix: 'app_governor' });
|
|
991
|
+
await mongoConscienceIndexes(db, { prefix: 'app_memory' });
|
|
992
|
+
const governor = createGovernor({
|
|
993
|
+
budgets: { perCycle: 1, perAgent: 5, perOrganisation: 20 }
|
|
994
|
+
}, { store: createMongoGovernorStore(db, { prefix: 'app_governor', client }) });
|
|
995
|
+
const conscience = createConscience({
|
|
996
|
+
governor, masker: (text) => maskInApplication(text),
|
|
997
|
+
store: createMongoConscienceStore(db, { prefix: 'app_memory' })
|
|
998
|
+
});
|
|
999
|
+
```
|
|
1000
|
+
|
|
1001
|
+
The index functions are explicit, idempotent migrations; call them before using
|
|
1002
|
+
the stores. Prefixes accept letters, digits and underscores, begin with a
|
|
1003
|
+
letter or underscore, and contain at most 41 characters. Defaults are
|
|
1004
|
+
`astratra_governor` and `astratra_conscience`. Governor collections have suffixes
|
|
1005
|
+
`proposals`, `audit`, `spend`, `controls`, `objects`, `versions`, `findings`,
|
|
1006
|
+
`sequences`, `locks`; decision memory uses `records` and `sequences`.
|
|
1007
|
+
|
|
1008
|
+
Identity is encoded in the unique `_id`: organisation plus record id (and kind
|
|
1009
|
+
or version where needed). Inserts return existing content unchanged; approval
|
|
1010
|
+
transitions compare status and approval count atomically, and object updates
|
|
1011
|
+
compare revision. Audit ids are unique and a persistent counter orders entries.
|
|
1012
|
+
Records use a persistent counter to order equal timestamps; replacement keeps
|
|
1013
|
+
that order. Filters, retention and `conscience.eraseSubject()` use the same
|
|
1014
|
+
contract as the PostgreSQL store, including organisation isolation and evidence
|
|
1015
|
+
invalidation. Erasure affects decision memory; governor audit retention remains
|
|
1016
|
+
application policy, as with PostgreSQL.
|
|
1017
|
+
|
|
1018
|
+
**Atomic spending requires a replica set or sharded cluster** (MongoDB 4.2+,
|
|
1019
|
+
subject to the driver's server compatibility). Each reservation updates an
|
|
1020
|
+
organisation lock inside a snapshot transaction, with majority write concern.
|
|
1021
|
+
Conflicting transactions retry through the driver, preventing two concurrent
|
|
1022
|
+
reservations from exceeding a budget. A standalone server fails spending; there
|
|
1023
|
+
is no unsafe fallback. Pass the client owning `db` if supplying `client`.
|
|
1024
|
+
Connections and sessions are caller-owned except the short-lived reservation
|
|
1025
|
+
sessions, which the store closes. The stores do not make an entire governor
|
|
1026
|
+
operation transactional: state and audit writes remain separate, as in the
|
|
1027
|
+
PostgreSQL implementation. Database errors propagate; they never authorize a
|
|
1028
|
+
spend. MongoDB's normal document size limits apply to individual records.
|
|
1029
|
+
|
|
1030
|
+
The shared governor, approval/change, conscience and evaluation contract suites
|
|
1031
|
+
run against a fake client and, optionally, real MongoDB:
|
|
1032
|
+
|
|
1033
|
+
```sh
|
|
1034
|
+
npm test -w @astratra/conscience
|
|
1035
|
+
MONGO_TEST_URL=mongodb://127.0.0.1:27017/conscience_test?replicaSet=rs0 npm test -w @astratra/conscience
|
|
1036
|
+
```
|
|
1037
|
+
|
|
1038
|
+
Without `MONGO_TEST_URL`, real MongoDB tests skip with a reason. A supplied URL
|
|
1039
|
+
must connect to a replica set or sharded cluster; connection or topology errors
|
|
1040
|
+
fail the suite. Tests create random collection prefixes and drop only their own
|
|
1041
|
+
collections, never the database. A local `mongodb-memory-server` replica set
|
|
1042
|
+
can supply the same URL. The vigilance and shadow stores retain their existing
|
|
1043
|
+
storage adapters; these two MongoDB stores cover the governor and decision
|
|
1044
|
+
records only.
|
|
1045
|
+
|
|
1046
|
+
Mutation checks (three regressions, each detected, then restored):
|
|
1047
|
+
|
|
1048
|
+
```sh
|
|
1049
|
+
node packages/conscience/test/mongo-mutations.js
|
|
1050
|
+
```
|
|
1051
|
+
|
|
890
1052
|
## Tests
|
|
891
1053
|
|
|
892
1054
|
```sh
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astratra/conscience",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.0",
|
|
4
4
|
"description": "Documented memory of an AI agent's decisions (outcomes, corrections, lessons with evidence, self-model, lineage, erasure) under a deterministic governor with no language model: constitution, permissions, budgets, isolation, kill switch, human approval.",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=20"
|
|
@@ -32,7 +32,8 @@
|
|
|
32
32
|
"@astratra/ai": "^1.8.0"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
|
-
"pg": "^8.13.1"
|
|
35
|
+
"pg": "^8.13.1",
|
|
36
|
+
"mongoose": "^8.24.2"
|
|
36
37
|
},
|
|
37
38
|
"exports": {
|
|
38
39
|
".": {
|
|
@@ -48,5 +49,13 @@
|
|
|
48
49
|
"default": "./src/autoconscience/index.js"
|
|
49
50
|
},
|
|
50
51
|
"./package.json": "./package.json"
|
|
52
|
+
},
|
|
53
|
+
"peerDependencies": {
|
|
54
|
+
"mongodb": "^6.0.0 || ^7.0.0"
|
|
55
|
+
},
|
|
56
|
+
"peerDependenciesMeta": {
|
|
57
|
+
"mongodb": {
|
|
58
|
+
"optional": true
|
|
59
|
+
}
|
|
51
60
|
}
|
|
52
61
|
}
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const { GovernorError, isNonEmptyString } = require('./util');
|
|
3
|
+
|
|
4
|
+
/*
|
|
5
|
+
* Calendar budget: consumption counted per calendar period (day or month) in a
|
|
6
|
+
* given time zone, with a cap in whole units of your choice (cents, tokens...).
|
|
7
|
+
* No floating point money: amounts and caps are safe integers.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
const PERIODS = Object.freeze(['day', 'month']);
|
|
11
|
+
const formatters = new Map();
|
|
12
|
+
|
|
13
|
+
function formatterFor(timeZone) {
|
|
14
|
+
let formatter = formatters.get(timeZone);
|
|
15
|
+
if (!formatter) {
|
|
16
|
+
try { formatter = new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }); } catch (_error) {
|
|
17
|
+
throw new GovernorError('budget_invalid', `Unknown time zone: ${timeZone}.`);
|
|
18
|
+
}
|
|
19
|
+
formatters.set(timeZone, formatter);
|
|
20
|
+
}
|
|
21
|
+
return formatter;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The calendar period of an instant, in a time zone: "2026-10" (month) or
|
|
26
|
+
* "2026-10-31" (day). `period` may also be a function (instant, timeZone) => key.
|
|
27
|
+
*/
|
|
28
|
+
function calendarPeriodKey(at, { period = 'month', timeZone = 'UTC' } = {}) {
|
|
29
|
+
const date = new Date(at instanceof Date ? at.getTime() : at);
|
|
30
|
+
if (Number.isNaN(date.getTime())) throw new GovernorError('budget_invalid', 'The instant of a budget period must be a valid date.');
|
|
31
|
+
if (typeof period === 'function') {
|
|
32
|
+
const key = period(date, timeZone);
|
|
33
|
+
if (!isNonEmptyString(key)) throw new GovernorError('budget_invalid', 'A custom period must return a non-empty string.');
|
|
34
|
+
return key;
|
|
35
|
+
}
|
|
36
|
+
if (!PERIODS.includes(period)) throw new GovernorError('budget_invalid', `period must be ${PERIODS.join(' or ')} or a function.`);
|
|
37
|
+
const parts = Object.fromEntries(formatterFor(timeZone).formatToParts(date).map((part) => [part.type, part.value]));
|
|
38
|
+
return period === 'month' ? `${parts.year}-${parts.month}` : `${parts.year}-${parts.month}-${parts.day}`;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const isAmount = (value) => Number.isSafeInteger(value) && value >= 0;
|
|
42
|
+
|
|
43
|
+
/** Budget store kept in memory: lost when the process exits. */
|
|
44
|
+
function createMemoryToolBudgetStore() {
|
|
45
|
+
const totals = new Map();
|
|
46
|
+
const entries = new Set();
|
|
47
|
+
const totalKey = (scope, period) => `${scope}\u0000${period}`;
|
|
48
|
+
return {
|
|
49
|
+
async getSpent(scope, period) { return totals.get(totalKey(scope, period)) ?? 0; },
|
|
50
|
+
/** Idempotent on (scope, id): a replay adds nothing. */
|
|
51
|
+
async addSpend({ scope, period, id, amount }) {
|
|
52
|
+
const entry = `${scope}\u0000${id}`;
|
|
53
|
+
const key = totalKey(scope, period);
|
|
54
|
+
if (entries.has(entry)) return { added: false, spent: totals.get(key) ?? 0 };
|
|
55
|
+
entries.add(entry);
|
|
56
|
+
totals.set(key, (totals.get(key) ?? 0) + amount);
|
|
57
|
+
return { added: true, spent: totals.get(key) };
|
|
58
|
+
}
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* Calendar budget over a store { getSpent(scope, period), addSpend({ scope,
|
|
64
|
+
* period, id, amount, at }) }. `limit` is the default cap; a call may pass its own.
|
|
65
|
+
*/
|
|
66
|
+
function createCalendarBudget(options = {}) {
|
|
67
|
+
const { period = 'month', timeZone = 'UTC', scope: defaultScope = 'default', limit: defaultLimit } = options;
|
|
68
|
+
const store = options.store ?? createMemoryToolBudgetStore();
|
|
69
|
+
for (const method of ['getSpent', 'addSpend']) {
|
|
70
|
+
if (typeof store[method] !== 'function') throw new GovernorError('budget_invalid', `The budget store is missing ${method}().`);
|
|
71
|
+
}
|
|
72
|
+
if (defaultLimit !== undefined && defaultLimit !== null && !isAmount(defaultLimit)) throw new GovernorError('budget_invalid', 'limit must be an integer >= 0.');
|
|
73
|
+
const now = options.now ?? Date.now;
|
|
74
|
+
calendarPeriodKey(now(), { period, timeZone }); // fails now, not at the first call, on a wrong period or time zone
|
|
75
|
+
|
|
76
|
+
const keyOf = (at) => calendarPeriodKey(at ?? now(), { period, timeZone });
|
|
77
|
+
|
|
78
|
+
/** Where the budget stands, and whether a call of `estimate` units still fits. Read before each call. */
|
|
79
|
+
async function check({ scope = defaultScope, limit = defaultLimit, estimate = 0, at } = {}) {
|
|
80
|
+
if (limit !== undefined && limit !== null && !isAmount(limit)) throw new GovernorError('budget_invalid', 'limit must be an integer >= 0.');
|
|
81
|
+
if (!isAmount(estimate)) throw new GovernorError('budget_invalid', 'estimate must be an integer >= 0.');
|
|
82
|
+
const key = keyOf(at);
|
|
83
|
+
const spent = await store.getSpent(scope, key);
|
|
84
|
+
if (limit === undefined || limit === null) return { allowed: true, exceeded: false, scope, period: key, spent, limit: null, remaining: null };
|
|
85
|
+
return { allowed: spent < limit && spent + estimate <= limit, exceeded: spent >= limit, scope, period: key, spent, limit, remaining: Math.max(0, limit - spent) };
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** Counts a consumption in the period of its instant. `id` makes the call safe to repeat. */
|
|
89
|
+
async function record({ scope = defaultScope, amount, id, at } = {}) {
|
|
90
|
+
if (!isAmount(amount)) throw new GovernorError('budget_invalid', 'amount must be an integer >= 0 (whole units, no fractions).');
|
|
91
|
+
if (!isNonEmptyString(id)) throw new GovernorError('budget_invalid', 'A consumption needs a stable id (idempotency).');
|
|
92
|
+
const instant = at ?? now();
|
|
93
|
+
const key = keyOf(instant);
|
|
94
|
+
const result = await store.addSpend({ scope, period: key, id, amount, at: new Date(instant).toISOString() });
|
|
95
|
+
return { added: result.added, scope, period: key, spent: result.spent };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
return Object.freeze({ check, record, periodKey: keyOf, period: typeof period === 'function' ? 'custom' : period, timeZone });
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
module.exports = { PERIODS, calendarPeriodKey, createMemoryToolBudgetStore, createCalendarBudget, isAmount };
|