@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 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.1.0",
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 };