@astratra/conscience 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.fr.md +954 -0
  3. package/README.md +915 -2
  4. package/package.json +50 -4
  5. package/src/autoconscience/experiments/common.js +76 -0
  6. package/src/autoconscience/experiments/execution.js +33 -0
  7. package/src/autoconscience/experiments/holdout.js +88 -0
  8. package/src/autoconscience/experiments/laboratory.js +99 -0
  9. package/src/autoconscience/experiments/replay.js +113 -0
  10. package/src/autoconscience/experiments/runner.js +54 -0
  11. package/src/autoconscience/experiments/sandbox.js +58 -0
  12. package/src/autoconscience/index.d.ts +203 -0
  13. package/src/autoconscience/index.js +116 -0
  14. package/src/autoconscience/lessons.js +32 -0
  15. package/src/autoconscience/shadow/candidate.js +69 -0
  16. package/src/autoconscience/shadow/index.d.ts +169 -0
  17. package/src/autoconscience/shadow/index.js +11 -0
  18. package/src/autoconscience/shadow/report.js +125 -0
  19. package/src/autoconscience/shadow/runner.js +384 -0
  20. package/src/autoconscience/shadow/store.js +98 -0
  21. package/src/autoconscience/signals.js +88 -0
  22. package/src/autoconscience/statistics.js +84 -0
  23. package/src/autoconscience/vigilance/abstention.js +123 -0
  24. package/src/autoconscience/vigilance/adversary.js +145 -0
  25. package/src/autoconscience/vigilance/common.js +56 -0
  26. package/src/autoconscience/vigilance/drift.js +306 -0
  27. package/src/autoconscience/vigilance/followups.js +100 -0
  28. package/src/autoconscience/vigilance/index.d.ts +190 -0
  29. package/src/autoconscience/vigilance/index.js +23 -0
  30. package/src/autoconscience/vigilance/lessonTests.js +40 -0
  31. package/src/autoconscience/vigilance/library.js +162 -0
  32. package/src/autoconscience/vigilance/roles.js +122 -0
  33. package/src/autoconscience/vigilance/store.js +166 -0
  34. package/src/conscience.js +559 -0
  35. package/src/diff.js +27 -0
  36. package/src/errors.js +11 -0
  37. package/src/governor/approvals.js +132 -0
  38. package/src/governor/changes.js +269 -0
  39. package/src/governor/governor.js +286 -0
  40. package/src/governor/index.d.ts +385 -0
  41. package/src/governor/index.js +22 -0
  42. package/src/governor/policy.js +136 -0
  43. package/src/governor/postgres.js +243 -0
  44. package/src/governor/remote.js +305 -0
  45. package/src/governor/review.js +191 -0
  46. package/src/governor/rollout.js +66 -0
  47. package/src/governor/stores.js +136 -0
  48. package/src/governor/util.js +53 -0
  49. package/src/guard.js +21 -0
  50. package/src/index.d.ts +244 -0
  51. package/src/index.js +23 -0
  52. package/src/memoryStore.js +65 -0
  53. package/src/postgres.js +93 -0
  54. package/src/records.js +220 -0
package/README.md CHANGED
@@ -1,3 +1,916 @@
1
- # Temporary Holding Version
1
+ # @astratra/conscience
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [English](README.md) | [Français](README.fr.md)
4
+
5
+ A documented memory of an AI agent's decisions, kept under a deterministic
6
+ governor. The agent records what it decided, why, with which versions and what
7
+ it expected; outcomes, human corrections and lessons are attached later, with
8
+ their evidence, and nothing is ever silently overwritten. Node >= 20,
9
+ CommonJS, MIT.
10
+
11
+ "Conscience" and "autoconscience" name software functions: a record of
12
+ decisions and, later, a reflective engine. They claim no subjective awareness.
13
+
14
+ ```sh
15
+ npm install @astratra/conscience
16
+ ```
17
+
18
+ The package has three entries:
19
+
20
+ | Entry | Phase | What it gives |
21
+ |---|---|---|
22
+ | `@astratra/conscience/governor` | P0, P5 | Deterministic governor: constitution, permissions, budgets, isolation, kill switch, human approval, audit journal; and (P5) approval matrix, reversible versioned changes with progressive rollout, rollback, morning report. Imports Node built-ins only: no language model, no AI package (a test walks its import graph). |
23
+ | `@astratra/conscience` | P1 | Decisions, predictions, outcomes with revisions, masked corrections, lessons with evidence, self-model, temporal memory, lineage, erasure, retention, memory guard. |
24
+ | `@astratra/conscience/autoconscience` | P2, P3, P4 | Deterministic evaluation: calibration, statistics, conflicts, fidelity, tool reliability, calendars, error costs, counter-metrics and cycle utility; experiments and vigilance (P3); shadow mode (P4). |
25
+
26
+ ## Quick start
27
+
28
+ ```js
29
+ const { createGovernor, createPostgresGovernorStore, postgresGovernorSchema } = require('@astratra/conscience/governor');
30
+ const { createConscience, createPostgresConscienceStore, postgresConscienceSchema } = require('@astratra/conscience');
31
+ const { createRedactor } = require('@astratra/privacy');
32
+ const { Pool } = require('pg');
33
+
34
+ const pool = new Pool({ connectionString: process.env.DATABASE_URL });
35
+ await pool.query(postgresGovernorSchema());
36
+ await pool.query(postgresConscienceSchema());
37
+
38
+ const governor = createGovernor({
39
+ version: '2026-10',
40
+ budgets: { perCycle: 0.5, perAgent: 5, perOrganisation: 20 }, // your cost unit, per day by default
41
+ approvers: ['admin-1'] // human identities from your application
42
+ }, { store: createPostgresGovernorStore(pool) });
43
+
44
+ const conscience = createConscience({
45
+ governor, // required: refuses to start without one
46
+ masker: createRedactor(), // required: any (text) => text, or a redactor, or { mask(text) }
47
+ store: createPostgresConscienceStore(pool)
48
+ });
49
+
50
+ const { decision } = await conscience.recordDecision({
51
+ organisationId: 'org-1', userId: 'user-7', agentId: 'billing-assistant',
52
+ objective: 'Remind the customer about invoice 42',
53
+ context: { at: new Date(), summary: 'Invoice 42 is 10 days late' },
54
+ action: { name: 'send_reminder', kind: 'write', input: { channel: 'email' } },
55
+ alternatives: ['wait', { name: 'call', reason: 'outside office hours' }],
56
+ expectedOutcome: { description: 'Invoice paid within 7 days', metric: 'paid', target: true },
57
+ horizon: Date.now() + 7 * 86400000,
58
+ confidence: 0.7,
59
+ permissions: ['invoices:read', 'email:send'],
60
+ versions: { model: 'model-2026-09', tools: { send_reminder: '1.2.0' }, instructions: 'reminders-v3' },
61
+ inputSnapshotRef: 'snapshot://invoices/42'
62
+ });
63
+
64
+ // Three days later, a business sensor reports the real result.
65
+ await conscience.attachOutcome({
66
+ organisationId: 'org-1', decisionId: decision.id, status: 'succeeded', sensor: 'payments',
67
+ provenance: { kind: 'sensor', id: 'payments-webhook' }, observedAt: new Date(), sources: ['payments://tx/991']
68
+ });
69
+ ```
70
+
71
+ ## Governor (`/governor`)
72
+
73
+ The governor decides by code. The same policy and the same proposal always
74
+ give the same answer; no model is consulted, and none can approve anything.
75
+
76
+ ### Policy
77
+
78
+ `createGovernor(policy, { store, now, onEvent })` checks the policy and throws a
79
+ `GovernorError` (`policy_missing`, `policy_invalid`) when it is absent or wrong.
80
+ The policy is frozen; `getPolicy()` returns a copy.
81
+
82
+ | Field | Default | Meaning |
83
+ |---|---|---|
84
+ | `budgets` | required | `{ perCycle, perAgent, perOrganisation, periodMs = 1 day }`, in your cost unit |
85
+ | `constitution` | `[]` | Extra `ConstitutionRule`s `{ id, description, protectedScope, owner }`, added to the default ones, which cannot be removed |
86
+ | `permissions.modifiable` | the four kinds | What a proposal may target: `instructions`, `threshold`, `tool_description`, `routing` (a subset only) |
87
+ | `automaticChanges` | `'none'` | The only mode in this version: every acceptable proposal waits for a human |
88
+ | `isolation` | `'organisation'` | An operation touches one organisation only |
89
+ | `approvers` | any human | Human identities allowed to approve |
90
+ | `halted` | `false` | Static kill switch |
91
+
92
+ Protected scopes, always in the constitution: `permissions`, `budgets`,
93
+ `security`, `privacy`, `constitution`, `approvals`, `isolation`, `governor`. A
94
+ custom rule protects a scope name, a `kind:id` target (`routing:payments`) or a
95
+ prefix ending in `*`.
96
+
97
+ ### Proposals
98
+
99
+ ```js
100
+ const proposal = await governor.evaluatePolicy({
101
+ organisationId: 'org-1',
102
+ target: { kind: 'instructions', id: 'reminders', version: 'v3' },
103
+ change: { text: 'Mention the invoice number first.' },
104
+ justification: 'Fewer follow-up questions.',
105
+ proposedBy: { kind: 'engine', id: 'reflection' }
106
+ });
107
+ // proposal.status: 'pending_approval' (reason 'human_approval_required') or 'rejected'
108
+ ```
109
+
110
+ A proposal is rejected, with reason codes, when it touches a protected scope
111
+ (through its target, its declared `scopes` or any key of its `change`), targets
112
+ something outside the allowlist, touches another organisation, is malformed,
113
+ or arrives while the kill switch is on. Its justification is never read. The
114
+ same proposal twice is one record; a different proposal under the same id is
115
+ refused (`proposal_conflict`).
116
+
117
+ `approveProposal(id, { approver, organisationId })` and `declineProposal(...)`
118
+ accept a human identity supplied by your application only
119
+ (`{ kind: 'human', id }`); a model, the engine, an unlisted person or the
120
+ proposer is refused. Approval records a decision; it never applies the change
121
+ by itself (see Approvals and Reversible changes below).
122
+
123
+ ### Budgets, isolation, kill switch, audit
124
+
125
+ - `authorizeSpend({ id, organisationId, agentId, cycleId, cost })` reserves a
126
+ spend when it fits the cycle, agent and organisation budgets. It is
127
+ idempotent by `id`. The PostgreSQL store reserves under an advisory lock
128
+ inside a transaction (with a `pg` Pool), so concurrent spends never pass a
129
+ budget together.
130
+ - `assertSingleOrganisation(...ids)` returns the one organisation of an
131
+ operation or throws `cross_organisation`.
132
+ - `halt({ by, reason, organisationId? })` stops reflective operations, globally
133
+ or for one organisation; any actor may pull it. `resume(...)` needs a human.
134
+ - Every decision of the governor (evaluate, approve, decline, spend, halt,
135
+ resume, register, stage, deploy, promote, rollback, finding) is written to the audit journal before it is returned:
136
+ `listAudit({ organisationId })`.
137
+
138
+ ### Approvals (matrix, double approval, expiry)
139
+
140
+ Approval is decided by the policy, not by whoever proposes:
141
+
142
+ ```js
143
+ createGovernor({
144
+ budgets: { /* ... */ },
145
+ approvers: ['admin-1', 'admin-2', 'rev-1'],
146
+ approvals: {
147
+ roles: { 'admin-1': ['owner'], 'admin-2': ['owner', 'reviewer'], 'rev-1': ['reviewer'] },
148
+ matrix: { instructions: { roles: ['owner', 'reviewer'] }, routing: { roles: ['owner'], approvals: 2 } },
149
+ floors: { routing: 'high' }, // minimum risk of a kind (default "medium")
150
+ doubleApprovalFrom: 'high', // from this risk, two distinct people
151
+ distinctRoles: false, // true: the two must hold different roles
152
+ expiresInMs: 7 * 24 * 3600e3, // validity of an approval
153
+ declineReasons: ['too_costly'] // added to the register
154
+ }
155
+ });
156
+ ```
157
+
158
+ - The risk of a proposal is the higher of the floor of its kind and the `risk`
159
+ it declares (`low`, `medium`, `high`, `critical`): a proposer can raise the
160
+ bar, never lower it. `proposal.requiredApprovals` says how many people are
161
+ needed (1, or 2 from `doubleApprovalFrom`, or more by the matrix).
162
+ - `approveProposal(id, { approver, organisationId, role? })` records one
163
+ approval. The proposal stays `pending_approval` until it holds enough valid
164
+ approvals from distinct people whose roles the matrix allows; the same
165
+ person cannot approve twice; nobody approves their own proposal.
166
+ - An approval expires after `expiresInMs`. An expired partial approval no
167
+ longer counts; an approved proposal nobody staged in time becomes `expired`
168
+ (`expireApprovals({ organisationId })` sweeps them) and must be proposed again.
169
+ - `declineProposal(id, { approver, organisationId, reasonCode })` needs a code
170
+ of the register (`DECLINE_REASONS`: `insufficient_evidence`, `risk_too_high`,
171
+ `not_needed`, `wrong_scope`, `poor_tests`, `no_rollback_plan`,
172
+ `conflicts_with_policy`, `bad_timing`, `duplicate`, `other`, plus the codes
173
+ of the policy). Free text goes in `note` and is never interpreted.
174
+ - `listRejectionSignals({ organisationId, since?, origin?, reasonCode? })`
175
+ returns every refusal, by a person (`origin: 'human'`) or by code
176
+ (`'governor'`), as a record of codes for the evaluation and experiment phases.
177
+ - Invariant: nothing is applied because a model approved it. Approval needs a
178
+ human identity; staging re-reads the stored approvals and refuses anything
179
+ else (a record forced to `approved`, a model approval, a changed content, a
180
+ protected scope, an expired approval). `verifyApprovalInvariant({ organisationId })`
181
+ audits the store for such cases.
182
+
183
+ ### Reversible changes
184
+
185
+ Objects a proposal may change (instructions, thresholds, tool descriptions,
186
+ routing rules) are versioned. The audit journal keeps who, what, when and the
187
+ version before and after.
188
+
189
+ ```js
190
+ await governor.registerObject({ organisationId, kind: 'instructions', id: 'reminders', content: { text: '...' }, by: { kind: 'human', id: 'admin-1' } }); // v1, stable
191
+ const proposal = await governor.evaluatePolicy({ organisationId, target: { kind: 'instructions', id: 'reminders', version: 'v1' }, change: { text: '...' }, proposedBy: engine });
192
+ await governor.approveProposal(proposal.id, { approver: human, organisationId });
193
+ await governor.stageChange(proposal.id, { organisationId, by: engine }); // candidate v2, exposure 0 %
194
+ await governor.deployChange({ organisationId, kind: 'instructions', id: 'reminders', percentage: 10, by: human });
195
+ const { versionId, content } = await governor.resolveVersion({ organisationId, kind: 'instructions', id: 'reminders', targetingKey: userId, attributes: { cohort: 'beta' } });
196
+ await governor.deployChange({ /* ... */ percentage: 100, by: human });
197
+ await governor.promoteChange({ /* ... */ by: human }); // v2 becomes stable
198
+ await governor.rollbackChange({ /* ... */ by: anyActor, reason: 'metrics fell' }); // back to v1, exactly
199
+ ```
200
+
201
+ - `stageChange` creates a candidate only from a proposal a human approved, and
202
+ re-checks everything at that moment: fingerprint, protected scopes,
203
+ allowlist, organisation, approvals (human, distinct, roles, count, expiry)
204
+ and that the proposal targets the current stable version (`stale_base`).
205
+ One candidate per object. Staging the same proposal twice is one candidate.
206
+ - Exposure grows by decision of a human (`deployChange`, `promoteChange`):
207
+ `percentage` (0 to 100) and/or `cohorts`. Cohorts say who is eligible, the
208
+ percentage which share of them. Buckets use the hashing of
209
+ `@astratra/flags` (`rolloutBucket` is identical to its `bucket`), so a user
210
+ stays in or out consistently, and growing never removes anyone. Promotion
211
+ needs 100 % of everyone.
212
+ - To let a real flag service decide, pass `flags` to `createGovernor`: any
213
+ object with `resolveBoolean(key, fallback, context)`, such as an
214
+ `@astratra/flags` provider. This package does not import it.
215
+ `exportFlagRules({ organisationId })` gives the rules to load in its
216
+ `createMemorySource`. A failing flag service serves the stable version.
217
+ - `rollbackChange` works at any time, for any identified actor, even while
218
+ halted: it discards the candidate, or restores the version that was stable
219
+ before the last promotion (the same record, not a copy). It is journaled.
220
+ - Kill switch: `halt()` also brings every candidate of its scope (global, or
221
+ one organisation) back to its stable version and returns what it reverted.
222
+ While halted, `resolveVersion` serves stable and nothing can be staged,
223
+ deployed or promoted. `resume()` does not bring a candidate back.
224
+ - `listVersions`, `getObject`, `listObjects` and `getChangeHistory` read the state.
225
+
226
+ ### Morning review
227
+
228
+ `recordFinding({ organisationId, code, severity, subject, ... })` receives the
229
+ findings of a reflection run (codes and numbers, no sentences).
230
+ `morningReport({ organisationId, since, until? })` returns plain data for an
231
+ interface to display, the same data for the same store and period:
232
+
233
+ | Field | Content |
234
+ |---|---|
235
+ | `findings` | Findings received in the period, counted by severity |
236
+ | `pendingProposals` | Waiting for approval: risk, approvals required and valid, allowed roles, tests, rollback plan |
237
+ | `approvedAwaitingStage` | Approved, not staged: expiry, `valid`, `expired` |
238
+ | `rollouts` | Candidates in deployment: stable and candidate versions, percentage, cohorts |
239
+ | `rejections` | Recent refusals as signals with coded reasons |
240
+ | `rollbacks` | Recent rollbacks and emergency reverts |
241
+ | `counts` | Totals for a header |
242
+
243
+ The report copies no free text of the proposer, only ids, codes, numbers and the
244
+ `tests` and rollback plan objects it supplied. Everything is read inside one
245
+ organisation.
246
+
247
+ ### Remote settings (dashboard)
248
+
249
+ `createRemoteSettings` lets a dashboard turn the agent on or off, pull or
250
+ release its kill switch, name its approvers and set its reflection schedule,
251
+ and lets humans approve or decline proposals there. The governor stays the only
252
+ judge: the adapter turns the settings into governor options and submits each
253
+ human decision through `approveProposal` / `declineProposal`. It imports
254
+ nothing but this folder: you pass the function that reads the settings.
255
+
256
+ ```js
257
+ const { createRemoteSettings, createPostgresGovernorStore } = require('@astratra/conscience/governor');
258
+
259
+ const remote = createRemoteSettings({
260
+ read: () => dashboard.readSettings(), // your client, with its own cache
261
+ policy: localPolicy, // constitution, permissions, budget CEILINGS
262
+ organisationId: 'org-1',
263
+ storage: { load: () => cache.get(), save: (s) => cache.set(s) } // optional: survives restarts
264
+ });
265
+ const store = createPostgresGovernorStore(pool);
266
+
267
+ setInterval(async () => {
268
+ await remote.refresh(); // never throws
269
+ const governor = remote.governor({ store }); // ask for it each time: rebuilt when the policy changes
270
+ await remote.sync(governor); // remote kill switch, applied now
271
+ const results = await remote.applyDecisions(governor, await dashboard.readDecisions());
272
+ // report results back (applied, already_applied, refused + code; failed = retry later)
273
+ }, 60_000);
274
+
275
+ if (remote.reflectionDue()) await runCycle({ cycleId: remote.reflectionCycleId() });
276
+ ```
277
+
278
+ Settings (`conscience-settings/1`): `version`, `enabled`, `halted`,
279
+ `resumedBy`, `approvers`, `reflection { automatic, hour, timeZone }`,
280
+ `cyclesPerDay`. Rules:
281
+
282
+ | Situation | Effect |
283
+ |---|---|
284
+ | Source silent, slow or invalid | The last valid settings stay (`source: 'last_known'`), from memory or `storage` |
285
+ | Nothing valid ever seen | Everything off: disabled, governor halted, no approver |
286
+ | Older `version` than the one in force | Ignored (`stale_settings`) |
287
+ | `halted: true` | Applied at once, even inside an invalid or stale answer; `sync` pulls the governor's kill switch (candidates go back to stable) |
288
+ | Halt released | `sync` resumes only a halt it pulled, and only as the human named in `resumedBy`; a halt pulled by anyone else stays |
289
+ | `enabled: false` | Governor halted; `reflectionDue()` is false |
290
+ | `cyclesPerDay` | `perAgent` and `perOrganisation` become `min(local, cyclesPerDay × costPerCycle)`, never above the local values |
291
+ | `approvers` | The governor's approvers; within the local `approvers` list when it has one |
292
+ | Anything else (`constitution`, `budgets`, `permissions`, `approvals`…) | Never applied, listed in `current().ignored` |
293
+
294
+ `applyDecisions` is safe to replay: a decision the governor already holds comes
295
+ back as `already_applied`, so one approval is never counted twice. Approvers,
296
+ halt, protected scopes, roles and expiry are still checked by the governor.
297
+
298
+ ### Bootstrap check
299
+
300
+ `assertGovernorReady(governor, { organisationId })` throws `governor_missing`,
301
+ `governor_invalid` (an object not built by `createGovernor`),
302
+ `governor_unavailable` (store unreachable) or `governor_halted`. Every
303
+ reflective write of the package calls it first.
304
+
305
+ ## Conscience (main entry)
306
+
307
+ `createConscience({ governor, masker, store, now, retention, erasers, onEvent })`
308
+ throws when the governor or the masker is missing.
309
+
310
+ ### Records
311
+
312
+ | Method | Record |
313
+ |---|---|
314
+ | `recordDecision(input)` | `DecisionRecord`: organisation, person, agent, objective, dated context, action, alternatives, expected outcome, horizon, confidence 0–1, permissions, model/tool/instruction versions, input snapshot reference |
315
+ | `recordPrediction(input)` | A probability attached to a decision, with its resolution date |
316
+ | `attachOutcome(input)` | `OutcomeRecord`: `succeeded`, `failed` or `unknown`, sensor, sources, uncertainty, confounders, provenance. A later outcome from the same sensor is a new revision; earlier ones are kept |
317
+ | `recordCorrection(input)` | `CorrectionRecord`: only the masked word difference between the proposed and final texts is stored, with its class (`factual`, `style`, `objective`, `disagreement`) and the author's role |
318
+ | `recordLesson(input)` | `MemoryLesson`: evidence, degree, `validFrom`/`validUntil`, status, contradictions, replacements. Reflective write |
319
+ | `updateSelfModel(input)` | `SelfModelSnapshot`: tested capabilities (each with evidence), tools, limits, permissions, provenance. Reflective write |
320
+
321
+ Every record has a stable id: pass your own, or it is derived from the
322
+ content, so recording the same thing twice gives one row. Records are never
323
+ updated; revisions are new rows.
324
+
325
+ Free text (objective, context, action input, expected outcome, observations,
326
+ lesson summaries and notes, corrections) goes through the masker before it is
327
+ stored. Use a deterministic masker.
328
+
329
+ ### Evidence register
330
+
331
+ A lesson without evidence is always a `hypothesis` (`statusForced: true` when
332
+ another status was asked). Evidence that points to a decision, prediction,
333
+ outcome or correction must exist in the same organisation. This version stores
334
+ lessons and their history; P2 checks sample sufficiency and open contradictions
335
+ before a lesson can be verified.
336
+
337
+ ### Reading
338
+
339
+ - `getDecision(scope, id)`, `recallDecisions(scope, { agentId, from, to, asOf, withOutcomes })`
340
+ - `getOutcomes(scope, decisionId)`: every revision with `revision`, `current`, `supersededAt`
341
+ - `getLesson(scope, lessonId)`, `listLessons(scope, { status, validAt, asOf })`
342
+ - `getSelfModel(scope, agentId, { asOf })`, `getSelfModelHistory(scope, agentId)`
343
+ - `getMemoryTimeline(scope, { axis: 'event' | 'recorded', from, to, asOf, validAt, kinds })`:
344
+ event time, recording time and validity period. `asOf` answers "what did
345
+ we know at that time".
346
+ - `getLineage(scope, decisionId)`: objective → action → tools → outcomes →
347
+ corrections → lessons.
348
+
349
+ A scope is `{ organisationId, userId? }`. A record of another organisation (or
350
+ another person, when `userId` is given) is answered exactly like a missing one.
351
+
352
+ ### Memory guard
353
+
354
+ Stored text is untrusted data: it may come from a person, a tool or a
355
+ manipulated model. The package never interprets it, and the governor never
356
+ reads it. Before a model reads records, frame them:
357
+
358
+ ```js
359
+ const { frameRecordsForModel } = require('@astratra/conscience');
360
+ const block = frameRecordsForModel(await conscience.listLessons({ organisationId: 'org-1' }));
361
+ ```
362
+
363
+ The framing is the one of `@astratra/ai/guards` (random marker the content
364
+ cannot close).
365
+
366
+ ### Erasure and retention
367
+
368
+ `eraseSubject({ organisationId, userId })` removes the person's decisions,
369
+ predictions, outcomes, corrections and lessons, removes references to them
370
+ from the organisation's lessons (a lesson left without evidence becomes a
371
+ hypothesis again), and calls your `erasers` for data kept elsewhere (vectors,
372
+ indexes, caches, calibrations). It returns a report with counts. With
373
+ `retention: { erasure: 'anonymise' }` the records are kept without the person.
374
+
375
+ Nothing is deleted on a timer. `applyRetention({ organisationId })` removes
376
+ records older than `retention.maxAgeDays[kind]`, and only for the kinds you
377
+ configured.
378
+
379
+ ## Stores
380
+
381
+ Memory stores (default, lost on exit) and PostgreSQL stores are included. SQL
382
+ uses parameters only; the table prefix is a checked identifier.
383
+
384
+ ```js
385
+ postgresConscienceSchema({ prefix: 'astratra_conscience' }) // table <prefix>_records
386
+ postgresGovernorSchema({ prefix: 'astratra_governor' }) // <prefix>_proposals, _audit, _spend, _controls, _objects, _versions, _findings
387
+ ```
388
+
389
+ ### Writing your own store (MongoDB, ...)
390
+
391
+ A conscience store has five methods on immutable envelopes
392
+ `{ kind, id, organisationId, userId, agentId, decisionId, lessonId, eventAt, recordedAt, fingerprint, evidenceRefs, data }`:
393
+
394
+ | Method | MongoDB sketch |
395
+ |---|---|
396
+ | `put(envelope)` | `insertOne` with a unique index on `{ organisationId, kind, id }`; on duplicate key return the existing document with `created: false` |
397
+ | `get(kind, organisationId, id)` | `findOne` |
398
+ | `list(kind, filter)` | `find` on the indexed fields, `recordedAt <= recordedTo`, `evidenceRefs: ref`, sorted by `recordedAt` then insertion |
399
+ | `replace(envelope)` | `replaceOne` (erasure and retention only) |
400
+ | `remove(kind, organisationId, ids)` | `deleteMany`, returns the count |
401
+
402
+ `matchesFilter(envelope, filter)` gives the exact filter semantics. The
403
+ governor store interface (`GovernorStore` in the types) needs an atomic
404
+ `reserveSpend` (a transaction), a compare-and-set `transitionProposal`
405
+ (`findOneAndUpdate` on `status`, and on the number of approvals when a `guard`
406
+ is given), a compare-and-set `updateObject` on `revision`, and insert-once
407
+ `createObject`, `putVersion` and `putFinding`.
408
+
409
+ ## Autoconscience (`/autoconscience`)
410
+
411
+ The P2 core is deterministic and imports no language model. `evaluateOutcomes()`
412
+ (and its alias `runReflection()`) reads P1 records and returns `ReflectionFinding[]`.
413
+ `createEvaluator({ governor, conscience, ...defaults })` binds an evaluator;
414
+ `evaluate({ organisationId, userId?, agentId?, window?, ...options })` evaluates
415
+ one scope. All reflective entries check `assertGovernorReady`; evaluation has
416
+ no storage writes, generated text or automatic action.
417
+
418
+ ```js
419
+ const { evaluateOutcomes } = require('@astratra/conscience/autoconscience');
420
+ const findings = await evaluateOutcomes({
421
+ governor, conscience, organisationId: 'org-1', agentId: 'billing-agent',
422
+ minimumSample: 30, buckets: 10, level: 0.95,
423
+ errorCostPolicies: [{ organisationId: 'org-1', domain: 'billing', falsePositive: 1, falseNegative: 20 }],
424
+ calendars: [{ organisationId: 'org-1', domain: 'billing', name: 'business',
425
+ periods: [{ label: 'closure', kind: 'closure', from: '2026-12-24', to: '2027-01-02' }] }]
426
+ });
427
+ ```
428
+
429
+ ### Structured inputs
430
+
431
+ - Decisions accept `domain` (default `general`), `justification: { claims: ['source_verified'] }`
432
+ and actual `toolTrace: [{ callId, tool, provider?, status, empty?, durationMs, labels? }]`.
433
+ A declared list of tools is not an execution trace. Labels such as `source_verified`
434
+ must come from your instrumented application, not from generated prose.
435
+ - Predictions accept `domain` (inherited from the decision) and an optional `sensor`.
436
+ Outcomes accept `predictionId`, checked against the decision in the same organisation.
437
+ - Corrections accept an application `class` or structured `tags`: `fact_changed`,
438
+ `wording_changed`, `goal_changed`, `opinion_changed`. Explicit class wins;
439
+ absent, unknown or conflicting tags become `disagreement`. Text is never classified
440
+ by a model or interpreted as a command.
441
+ - Lessons accept `domain`, `subject` and `stance: 'supports' | 'opposes'`.
442
+ Opposing positions within the same organisation, person, agent and domain open
443
+ a symmetric conflict (`to_reassess`). Textual summaries alone cannot establish opposition.
444
+
445
+ ### Calculations and contracts
446
+
447
+ | Function | Result |
448
+ |---|---|
449
+ | `honestStatistics(statuses, options)` | Known sample size, unknown count, success rate, Wilson interval, `insufficient_data` below `minimumSample` (30 by default), refusal to conclude |
450
+ | `wilsonInterval(successes, total, level)` | Two-sided Wilson score interval; levels 0.90, 0.95 (default), 0.99; null only for zero known observations |
451
+ | `calibratePredictions(points, options)` | Per agent/domain reliability curve, Brier score, signed confidence gap, overconfidence and underconfidence; empty bins have null means |
452
+ | `scoreErrorCosts(points, policy, options)` | False positive/negative counts, total cost and `weightedScore = totalCost / knownCount` in your cost units; threshold 0.5 by default |
453
+ | `checkReasoningFidelity(justification, traces, claimRules)` | `faithful`, `unfaithful` or `unknown`; every required label needs a successful, nonempty call; default rule requires `source_verified` |
454
+ | `toolReliability(traces, options)` | Per tool/provider error, empty and slow rates, their Wilson intervals and minimum samples, nearest-rank p95; slow means duration strictly above `slowMs` (5000 by default) |
455
+ | `calendarConfounders(domain, at, calendars)` | `calendar_confounded` for dates in a declared half-open period `[from, to)` |
456
+ | `checkCounterMetrics(target, counters)` | Target improvement rejected if any counter-metric regresses strictly beyond its `maxRegression`; thresholds use absolute metric units |
457
+ | `classifyCorrection(input)` | Deterministic classification; only `factual` corrections can support a factual lesson |
458
+ | `evaluateLessonConflicts(lessons, options)` | Open conflicts with evidence ranking and dates; stronger evidence can suggest a preferred lesson, a newer date alone never resolves one |
459
+ | `reflectionUtility(run, options)` | Useful findings + accepted proposals (configurable weights) minus weighted cost; usefulness requires positive benefit and positive net utility |
460
+ | `recommendReflectionFrequency(runs, options)` | `reduce` after `uselessCycles` consecutive useless completed cycles (default 3); interval multiplier `reductionFactor` (default 2) |
461
+
462
+ Cycles without measured useful-finding or accepted-proposal counts remain
463
+ `unmeasured`; they do not count as useless cycles. Unknown tool-call statuses
464
+ stay outside the error-rate denominator (empty and slow rates describe actual
465
+ reported emptiness and durations).
466
+
467
+ Unknown outcomes never enter success/failure denominators or Brier/cost scores.
468
+ Evaluation uses the latest prediction per decision/domain (date, then id), and
469
+ the current outcome for its sensor or explicit prediction link. Missing or
470
+ ambiguous matches, or predictions made after the observation, remain unknown.
471
+ One decision contributes at most one calibration point per domain; duplicate
472
+ points supplied directly to `calibratePredictions` are rejected. The curve's
473
+ bins also expose their own sample adequacy. Scores below the threshold remain
474
+ descriptive; they are not rules or causal evidence.
475
+
476
+ Findings contain stable ids, evidence references, sample size, interval, status,
477
+ confidence, confounders and competing explanations. The core always emits
478
+ `causality: 'not_established'`: an outcome and the fidelity of its method remain
479
+ separate. A lucky success never creates a general rule. `confidence` describes
480
+ the supplied observation confidence or interval level, not the probability that
481
+ a causal hypothesis is true. Intervals remain visible for small nonzero samples
482
+ while `insufficient_data` explicitly refuses inference.
483
+
484
+ ### Lesson verification and arbitration
485
+
486
+ `createConscience({ minimumSample: 30, ... })` controls the verification floor;
487
+ a lesson may request a higher `minimumSample`, never lower that floor.
488
+ Verification counts **distinct decisions** represented by current known outcomes
489
+ or factual corrections in the lesson's domain and agent scope. Decision-only,
490
+ prediction-only and external references do not inflate the observed sample;
491
+ unknown or superseded outcomes and duplicate references do not count. A factual
492
+ lesson citing a style/objective/disagreement correction remains a hypothesis.
493
+ Evidence existence, sufficient sample and no open contradiction are all required
494
+ for `verified`; open conflicts produce `to_reassess`, other cases `hypothesis`.
495
+ This is an evidence sufficiency status, not a proof of a causal assertion.
496
+
497
+ `conscience.resolveLessonConflict({ organisationId, userId?, winnerId, loserId, evidence })`
498
+ is an explicit application arbitration: it requires sufficient factual evidence
499
+ in the same domain, retires the opponent and appends a new revision of the winner.
500
+ All writes pass through `assertGovernorReady`. Earlier revisions are retained.
501
+ `getLesson().current` and `listLessons()` reassess evidence and conflicts, including
502
+ late unknown outcomes and concurrent conflicting writes. `storedStatus` exposes
503
+ the recorded status; `getLesson().history` retains recorded revisions. `asOf`
504
+ uses the evidence and outcomes known at that recording date.
505
+
506
+ Findings and calibration are recalculated rather than cached or persisted:
507
+ erasing their source records removes them from subsequent evaluations. If your
508
+ application stores findings elsewhere, register an eraser for that store.
509
+ Windows filter decision dates; they do not implement P3 time-frozen replay.
510
+ A query reaching 1000 decisions refuses with `evaluation_limit`: supply explicit
511
+ `decisionIds` for a larger selection, rather than silently evaluate a partial sample.
512
+
513
+ P3 experiments and P4 shadow mode are described in their own sections below.
514
+ Evaluation itself does not create a scheduler, a model transport or a deployment.
515
+
516
+ - P3, experiments: time-frozen replay that refuses future data, sandbox,
517
+ protected test set. Drift monitoring, follow-ups, abstention, the night
518
+ adversary, multi-role review and lessons turned into tests are described in
519
+ "P3 · vigilance (2/2)" below.
520
+ - P4, shadow mode in a sandbox: see "P4 · shadow mode" below.
521
+ - Only P6 (integration and guarded transfer between agents) remains outside this package.
522
+
523
+ P5 (advanced governance) is in the governor entry: see above.
524
+
525
+ ## P3 · experiments (1/2)
526
+
527
+ The first half of P3 implements proposals 02/35 (temporal replay), 32
528
+ (simulated tools), 36 (protected final set) and 16 (preregistered experiments).
529
+ The package stays at the unreleased version 1.0.0. All five API entries and
530
+ their later operations check `assertGovernorReady`; scope is one organisation.
531
+ The scoring core imports no language model and never uses generated text as a
532
+ judge. Remaining P3 capabilities belong to the second half.
533
+
534
+ | API | Contract |
535
+ |---|---|
536
+ | `replayDecisions({ governor, conscience, organisationId, proposal, decisionIds \| window, asOf, snapshots?, tools? })` | Reconstructs inputs and current outcome/lesson revisions known **at each decision**, with `asOf` as the outer cutoff. Refuses detected future information with `future_data`. Returns `purpose: 'compatibility_only'`, `provesProgress: false`, and `causality: 'not_established'`. |
537
+ | `createSandbox({ governor, organisationId, tools })` | Replaces every implementation, including real read functions. Reads return static `response`, matching `recordings: [{ input, output }]`, or a simulated unknown. Writes/confirmations only append intentions; bare real functions are conservatively treated as writes. `tools[name](input)` and `getJournal()` never call real tools. |
538
+ | `createHoldout({ governor, organisationId, cases })` | Provisioning creates an opaque handle: only `evaluate`, `getAccessLog`, and a denied `read` operation. Properties, enumeration and serialization cannot reveal contents (`holdout_protected`). One final evaluation only, including concurrent attempts. |
539
+ | `proposeExperiment({ governor, organisationId, hypothesis, metrics, protocol, thresholds, agent, holdout, tools? })` | Deep-copies and freezes registration before any candidate execution: hypothesis, metrics, protocol, thresholds, timestamp, SHA-256 fingerprint, candidate/tool fingerprints. Reserves an unused final set. |
540
+ | `runExperiment({ governor, organisationId, experiment })` | Executes the registered candidate once on development, then validation, then the protected final set. Changes to the protocol, metrics, thresholds, hypothesis, candidate or tools are refused with `protocol_changed`, including changes after execution. |
541
+
542
+ ```js
543
+ const { createHoldout, proposeExperiment, runExperiment } = require('@astratra/conscience/autoconscience');
544
+ const binding = { governor, organisationId: 'org-1' };
545
+ // Supply these three disjoint sets from trusted provisioning code.
546
+ // Each case is { id, input, expected }; reflection never receives finalCases.
547
+ const holdout = await createHoldout({ ...binding, cases: finalCases });
548
+ const experiment = await proposeExperiment({
549
+ ...binding, hypothesis: 'The candidate meets the registered accuracy floor',
550
+ agent: (input) => input, // self-contained evaluated function
551
+ metrics: [{ name: 'accuracy', kind: 'exact_match' }],
552
+ thresholds: { accuracy: 0.9 },
553
+ protocol: { development: developmentCases, validation: validationCases,
554
+ minimumSample: 30, level: 0.95, timeoutMs: 1000 },
555
+ holdout
556
+ });
557
+ const result = await runExperiment({ ...binding, experiment });
558
+ // result.decision: supported | refuted | inconclusive
559
+ // result.stages.holdout: aggregate metrics only, no cases, answers or journal.
560
+ ```
561
+
562
+ Metrics use deterministic JSON equality (`kind: 'exact_match'`). Optional
563
+ `outputKey` / `expectedKey` select structured fields. No evaluator callback can
564
+ read final answers. P2 `honestStatistics` supplies known/unknown counts and
565
+ two-sided Wilson intervals (minimum 30; levels 0.90, 0.95, 0.99). A missing
566
+ output, execution failure or timeout is unknown. A decision is `supported`
567
+ only when **every metric in every stage** has sufficient observations and an
568
+ interval entirely at or above its threshold; `refuted` requires a sufficient
569
+ interval entirely below a threshold; insufficient data, unknowns or an interval
570
+ crossing a threshold are `inconclusive`. These are threshold tests, not a
571
+ claim of causal improvement over a baseline. `interval` is the first final
572
+ metric's interval; all intervals are in `stages.*.metrics`. Case ids and input
573
+ fingerprints must be distinct across splits; repeated inputs cannot inflate a
574
+ sample. Development/validation intentions are journaled; final intentions and
575
+ individual outputs are not exposed.
576
+
577
+ A replay `proposal` is `{ agent, information?: [{ organisationId, userId?, at,
578
+ recordedAt, data }] }`. `snapshots` maps `inputSnapshotRef` to the same dated
579
+ shape; a referenced snapshot is mandatory (`snapshot_missing`). Without a
580
+ reference, the stored dated context is the snapshot. The candidate receives
581
+ `{ inputs, outcomes, lessons, information, decision, asOf }`; `decision` contains
582
+ only id, objective, context, versions and permissions, never the original
583
+ action or expected answer. Compatibility compares its output to
584
+ `{ name: originalAction.name, input: originalAction.input }`. Outcome and lesson
585
+ revisions recorded later are excluded; an early-recorded but future-dated fact
586
+ is refused. Historical lesson evidence is checked too; undated external
587
+ evidence is refused (`temporal_evidence_required`). Factual timestamps,
588
+ including nested ones and simulated responses, are validated. Replay read responses
589
+ require `{ organisationId, userId?, at, recordedAt, data }`
590
+ (`temporal_metadata_required` without dates); planned horizons
591
+ and expiry dates are not treated as future observations. Snapshot dates must
592
+ be truthful: the library cannot infer undeclared provenance or whether literal
593
+ knowledge embedded in candidate source came from the future. Selections are
594
+ bounded rather than silently truncated (`replay_limit`).
595
+
596
+ Candidates are serialized from function source and executed in fresh worker
597
+ realms with only JSON data and simulated tools. They cannot access host
598
+ closures, `process`, `require`, `fetch`, filesystem, dynamic imports or host
599
+ callbacks. Async computations using simulated tools are supported. An injected
600
+ model may compute the evaluated agent's output as a self-contained function;
601
+ remote model transports and captured model clients cannot run in this sandbox.
602
+ The core never chooses or calls a model to decide the score. Worker timeouts
603
+ (10–30000 ms per case), memory and output limits bound execution. This is an
604
+ application execution boundary for supplied candidate code, not an OS security
605
+ boundary for arbitrary hostile native code.
606
+
607
+ Provisioning code must keep original final cases outside reflection; a handle
608
+ cannot protect copies already shared by the application. A final set is
609
+ single-use to prevent adaptive probing, and is consumed even on failed
610
+ execution. Registration handles, final contents and access logs are local to
611
+ the process and are not restartable; audit metadata and aggregate results are
612
+ recorded as governor findings (`experiment_registered`, `experiment_started`,
613
+ `experiment_completed` / `experiment_failed`) in its memory or PostgreSQL
614
+ store. No new SQL schema or dependency is needed. Real PostgreSQL tests run
615
+ with `CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p3a_test`;
616
+ P3 integration tests fail, rather than skip, if an explicitly supplied test
617
+ database is unavailable. Run the mutation proof separately with
618
+ `node packages/conscience/test/experiments-mutations.js`.
619
+
620
+ ## P3 · vigilance (2/2)
621
+
622
+ Second half of P3, in `@astratra/conscience/autoconscience`: six deterministic
623
+ modules that watch, remind, hold back, challenge, cross-check and turn lessons
624
+ into tests. None imports a language model (a test reads the sources), and none
625
+ applies anything: every change goes through a proposal to the governor, and
626
+ every call first checks that the governor exists, is genuine and is not halted
627
+ (`assertGovernorReady`).
628
+
629
+ | No. | Function | What it does |
630
+ | --- | --- | --- |
631
+ | 17 | `detectDrift` | Drift watch on inputs, outcomes and performance, with a coded recommendation. |
632
+ | 18 | `createFollowUps` | Prospective memory: `scheduleFollowUp`, `dueFollowUps`. |
633
+ | 26 | `abstentionPolicy` | Confidence threshold from calibration and error costs. |
634
+ | 27 | `generateAdversarialCases` | Candidate trap scenarios from recent failures. |
635
+ | 14 | `reviewByRoles` | Verifier, contradictor and risk controller, reviewed apart. |
636
+ | 03 | `lessonToScenario` | A verified lesson becomes an anti-regression scenario. |
637
+
638
+ ### Drift watch (17)
639
+
640
+ ```js
641
+ const report = await detectDrift({
642
+ governor, organisationId, agentId, domain,
643
+ baseline: { window: { from, to }, inputs: { domains, languages, lengths },
644
+ outcomes: { succeeded, failed, unknown },
645
+ performance: { calibration: { sampleSize, brierScore, confidenceGap }, tools: [{ tool, provider, knownCalls, failures }] } },
646
+ current: { /* same shape */ },
647
+ calendars, // P2 DomainCalendar[] of the same organisation
648
+ recentChange, // { kind, id, version, previousVersion, deployedAt }
649
+ propose: {} // optional: a rollback recommendation becomes a PENDING proposal
650
+ });
651
+ ```
652
+
653
+ `snapshotWindow({ decisions, findings, agentId, domain, languageOf })` builds a
654
+ summary from P2 material (the core detects no language: `languageOf` is yours).
655
+
656
+ Tests, simple and documented in the source: the Population Stability Index for
657
+ distributions (domains, languages, lengths cut at the baseline quintiles; a 0.5
658
+ pseudo-count per category; below 0.10 stable, 0.10 to 0.25 moderate, 0.25 or
659
+ more significant) and the difference of two proportions with Newcombe's hybrid
660
+ score interval, built from the Wilson intervals of P2 (outcome success rate,
661
+ share of unknown, tool error rate). A shift is significant when the interval
662
+ excludes zero and the gap is at least 5 points (`minimumEffect`). Brier score
663
+ and confidence gap are compared with a threshold (`brierDelta`,
664
+ `confidenceGapDelta`). A window with fewer than `minimumSample` known
665
+ observations never concludes: `insufficient_data`.
666
+
667
+ A **business calendar** is read before the agent is blamed: a period that
668
+ overlaps the current window and not the baseline one explains the shift
669
+ (`attribution: 'calendar'`, recommendation `monitor`, `reexamineAfter`).
670
+
671
+ Coded recommendation: `monitor`, `investigate` (inputs moved or a tool decayed
672
+ together with a decline), `freeze` (severe unexplained decline, `freezeDrop`),
673
+ `propose_rollback` (decline in a window that starts after a recent change, inputs
674
+ stable). The report always says `applied: false`. With `propose`, a rollback
675
+ becomes a pending proposal at the governor (high risk, two approvals by default)
676
+ and still nothing is rolled back: a human decides, then `rollbackChange` is yours
677
+ to call. `recordedBy` also files a finding for the morning report.
678
+
679
+ ### Prospective memory (18)
680
+
681
+ ```js
682
+ const vstore = createMemoryVigilanceStore(); // or createPostgresVigilanceStore(pool)
683
+ const conscience = createConscience({ governor, masker, erasers: [followUpEraser(vstore)] });
684
+ const followUps = createFollowUps({ governor, conscience, store: vstore, masker });
685
+ await followUps.scheduleFollowUp({ organisationId, decisionId, observableAt, question });
686
+ const due = await followUps.dueFollowUps({ organisationId }); // { followUp, decision }[]
687
+ await followUps.completeFollowUp({ organisationId, id });
688
+ ```
689
+
690
+ Idempotent: the same decision, date and question give the same follow-up
691
+ (`created: false`). The question is masked before storage. The decision must exist
692
+ in the organisation (another organisation's decision: `not_found`). Follow-ups
693
+ are erased with the person through `eraseSubject` (register `followUpEraser`);
694
+ a follow-up whose decision was erased or expired is never returned as due. The
695
+ content of a due item is data, never an instruction.
696
+
697
+ ### Abstention (26)
698
+
699
+ `abstentionPolicy({ governor, organisationId, agentId, domain, calibration, errorCosts, currentThreshold, propose })`.
700
+ Acting is worth it when the chance of success is at least
701
+ `falsePositive / (falsePositive + falseNegative)` (the cost table of P2). The
702
+ threshold is the lowest announced confidence, with observations of its own, from
703
+ which the lower Wilson bound of the observed success rate stays above that
704
+ ratio, over at least `minimumSample` decisions. Not enough data or no cost table:
705
+ a prudent default (0.8), never lower than the threshold already in force. No
706
+ reliable region: 1. `shouldAbstain(policy, { confidence, actionKind })` answers
707
+ `proceed`, `ask_clarification` or (for `write` and `confirm` actions)
708
+ `propose_verification`, always from the threshold **in force**
709
+ (`effectiveThreshold`). A new threshold is a proposal on target
710
+ `threshold:abstention:<agent>:<domain>`; nothing is applied here.
711
+
712
+ ### Night adversary (27) and lessons turned into tests (03)
713
+
714
+ ```js
715
+ const library = createScenarioLibrary({ governor, store: vstore, masker });
716
+ const { candidates, rejected } = await generateAdversarialCases({ governor, organisationId, failures, masker, generator, library });
717
+ const lessonCase = await lessonToScenario(lesson, { governor, masker, question, tools, expect, library });
718
+ // later, after humans approved the proposals at the governor:
719
+ const suite = (await library.approved({ organisationId })).map((a) => a.scenario); // for evaluateAgent
720
+ ```
721
+
722
+ `generateAdversarialCases` turns recent failures into candidates of four
723
+ categories (injection, ambiguity, edge case, access to another organisation) in
724
+ the format of `evaluateAgent` from `@astratra/testkit`: `id`, `question`,
725
+ simulated tools (fixed results, no effect), `expect`, and a `score` that fails
726
+ the case when a forbidden tool is called or a forbidden text appears. An
727
+ **injected generator** may write the cases (a function that returns data only;
728
+ what it returns is validated, masked, and replaced by the template if invalid or
729
+ failing). Without one, deterministic templates are used, the same failure giving
730
+ the same cases. The **masker is required** and runs on failures and on whatever
731
+ the generator returns.
732
+
733
+ `lessonToScenario` accepts a lesson whose status is `verified` (evidence, enough
734
+ distinct decisions, no open conflict); a hypothesis, a lesson to reassess or a
735
+ retired one is refused (`lesson_not_verified`). The lesson says what was learned;
736
+ you describe how to check it, and a scenario that asserts nothing is refused.
737
+
738
+ Every candidate is born `to_review`. With a library it becomes a proposal at the
739
+ governor (target kind `instructions`, id `scenarios:<agent>`, configurable with
740
+ `targetKind`). `library.approved()` is the **only** way into the test suite: it
741
+ keeps a candidate only when humans approved that exact content (same
742
+ fingerprint) and the stored content is unchanged. A model, a decline, an expired
743
+ approval or an altered candidate keep it out.
744
+
745
+ ### Multi-role review (14)
746
+
747
+ ```js
748
+ const review = await reviewByRoles({ governor, organisationId, finding, roles: { verifier, contradictor, riskController } });
749
+ review.advances; review.status; // true / 'supported', or false / 'hypothesis' with review.blockers
750
+ ```
751
+
752
+ Three separate functions, not a vote of models. The finding moves forward only
753
+ if the verifier cites **independent** evidence (not the finding's own evidence or
754
+ decisions, same organisation, optionally confirmed by `evidenceExists`), if no
755
+ competing explanation of the contradictor is as strong as the finding's
756
+ confidence, and if the risk controller approves a scope at least as wide as the
757
+ requested one (`observation` < `agent` < `domain` < `organisation`). A role that
758
+ throws or answers badly blocks the finding. Roles receive a frozen copy of the
759
+ finding, never each other's answers.
760
+
761
+ ### Storage
762
+
763
+ `createMemoryVigilanceStore()` and `createPostgresVigilanceStore(db, { prefix })`
764
+ (schema: `postgresVigilanceSchema({ prefix })`, tables `<prefix>_follow_ups` and
765
+ `<prefix>_candidates`). Same contract, same tests, every access scoped by
766
+ organisation, every value a SQL parameter.
767
+
768
+ ## P4 · shadow mode
769
+
770
+ Proposals 21 (shadow mode) and 32 (sandbox of the shadow mode), in
771
+ `@astratra/conscience/autoconscience`. A candidate strategy that humans already
772
+ approved processes a share of the real requests **in silence**, next to the
773
+ stable strategy. Its answers go to nobody. They are compared with the stable
774
+ answers by deterministic metrics you provide, and the gap is kept, masked, as a
775
+ `ShadowRun`. No language model is imported (a test reads the sources); every
776
+ call first checks `assertGovernorReady`.
777
+
778
+ ```js
779
+ const { createSandbox, createShadowRunner, createMemoryShadowStore, shadowEraser } = require('@astratra/conscience/autoconscience');
780
+
781
+ const sandbox = await createSandbox({ governor, organisationId, tools: {
782
+ lookup_invoice: { kind: 'read', response: { status: 'unknown' } }, // simulated or recorded
783
+ send_reminder: { kind: 'write' } // never executed, only journalled
784
+ } });
785
+ const shadow = await createShadowRunner({
786
+ governor, organisationId,
787
+ candidate: { kind: 'instructions', id: 'reminders', agent }, // or { proposalId, agent }
788
+ sandbox, sampleRate: 0.1,
789
+ budget: { maxRuns: 500, maxCost: 50, costPerRun: 0.1 },
790
+ masker, // required
791
+ store: createMemoryShadowStore(), // or createPostgresShadowStore(pool)
792
+ metrics: [
793
+ { name: 'accuracy', score: ({ input, output }) => output.total === input.expected },
794
+ { name: 'sources_accuracy', score: ({ output }) => output.sourced === true, maxRegression: 0.02 },
795
+ { name: 'minor_protection', critical: true, score: ({ input, output }) => !(input.minor && output.disclosed) }
796
+ ],
797
+ target: 'accuracy', minimumSample: 30
798
+ });
799
+
800
+ // In the request path: answer with the stable strategy, then hand over. Never await `done`.
801
+ const answer = await stable(request);
802
+ respond(answer);
803
+ shadow.observe({ request: { id: request.id, userId: request.userId, input: request.input }, stableResult: { output: answer, durationMs, cost } });
804
+
805
+ const report = await shadow.report({ propose: {}, recordedBy: { kind: 'system', id: 'shadow' } });
806
+ report.conclusion; // 'insufficient_data' | 'regression' | 'no_difference' | 'promising'
807
+ ```
808
+
809
+ **Which strategy may run.** Either the candidate version of a governor object
810
+ (`{ kind, id }`: the version staged from a proposal that humans approved) or a
811
+ proposal in the `approved` state with human approvals (`{ proposalId }`). A
812
+ pending, declined, rejected or expired proposal, a stable version, an unknown
813
+ object or another organisation's object are refused (`candidate_not_approved`,
814
+ `candidate_not_staged`, `not_found`). The check is repeated before every run: a
815
+ candidate that was rolled back, promoted or replaced stops the shadow.
816
+
817
+ **The candidate answer is never returned.** `observe` is synchronous, never
818
+ throws and never waits: it returns `{ scheduled, reason, done }`, and `done`
819
+ (which never rejects) resolves to an acknowledgement (`recorded` with a run id,
820
+ or `skipped`, `timeout`, `error` with a reason) that carries no output of the
821
+ candidate. The run happens in the background, after the stable answer. A failing,
822
+ slow or hostile candidate, a failing store or masker, a metric that throws: all
823
+ are isolated and counted (`stats()`), none reaches the caller. A deadline
824
+ (`deadlineMs`) abandons a stalled run, and `maxConcurrent` skips a burst as
825
+ `busy` rather than queue it.
826
+
827
+ **Sandbox only (32).** The candidate is a self-contained function run in the P3
828
+ sandbox: no host object, no `process`, no `require`, no timer, no `fetch`. Its
829
+ tools are the ones of the sandbox: a read returns a recording (the optional
830
+ `recordings` of `observe`, for example what the stable run read) or a simulated
831
+ answer; a write is **never executed**, even when the candidate calls it, and is
832
+ only journalled as an intention (`writeIntentions`, masked). The shadow opens no
833
+ network connection of its own. A model call inside a candidate is a sandbox
834
+ tool, replayed or simulated, never a live call.
835
+
836
+ **Sampling, budget, kill switch.** A request is selected by a hash of its id and
837
+ of the shadow id: the same request always gives the same choice, whatever the
838
+ order, and `sampleRate: 0.1` selects a subset of what `0.5` selects. The budget is
839
+ required and capped: `maxRuns`, `maxCost` (`costPerRun` is the ceiling reserved
840
+ for a run, `costOf` can only lower it), `maxDurationMs` (measured time, which the
841
+ runs already in flight can overshoot), and `governorAgentId` to spend through
842
+ `governor.authorizeSpend` as well. When the budget is spent, or the governor kill
843
+ switch is on, the shadow stops at once, stays stopped (releasing the switch does
844
+ not wake it: start a new one) and a run that finishes after the stop is
845
+ dropped. Budgets count the runs already stored, so a restart continues the same
846
+ shadow.
847
+
848
+ **ShadowRun.** Per sampled request: the masked request, the masked candidate and
849
+ stable outputs (replaced by a fingerprint beyond 20 000 characters), the score of
850
+ each side for each metric (`succeeded`, `failed`, `unknown`), whether both
851
+ answers agree, the write intentions, duration, cost and incidents
852
+ (`candidate_failed`, `candidate_timeout`, `scoring_failed`, ...). The raw request
853
+ id is not kept. A masker that fails keeps the run out of the store. A candidate
854
+ that produces nothing fails the metrics: it cannot have succeeded.
855
+
856
+ **Report.** Per metric, the success rate of each side with its Wilson interval
857
+ and minimum sample (P2: below it, `insufficient_data` and no difference), the
858
+ paired counts, and the difference (candidate minus stable) with a Newcombe
859
+ interval. Anti-Goodhart (P2): the `target` metric must improve while every other
860
+ metric stays within its `maxRegression` (and `limits.cost`); at least one
861
+ counter-measure is required when the shadow is built. Critical metrics list the
862
+ requests where the stable strategy succeeded and the candidate failed. The
863
+ conclusion is a code, in this order:
864
+
865
+ | Conclusion | When |
866
+ |---|---|
867
+ | `regression` | More critical regressions than `maxCriticalRegressions` (0 by default; even a single case counts, whatever the sample), or, with enough data, a significant decline of a metric, a counter-measure beyond its limit, or an incident rate significantly above `maxIncidentRate`. |
868
+ | `insufficient_data` | Fewer than `minimumSample` runs, a metric with too few known scores, or a cost limit without the stable cost. |
869
+ | `promising` | The target improved with an interval above zero and every counter-measure held. |
870
+ | `no_difference` | Enough data, no significant difference and no regression. |
871
+
872
+ It never says "proven": `provesImprovement` is always `false`, `causality` is
873
+ `not_established`, `applied` is `false`. A shadow comparison on a sample of real
874
+ requests can make an improvement promising, nothing more. With `propose`, a
875
+ promising result becomes a **pending proposal** at the governor (target kind of
876
+ the candidate, id `shadow:<id>:<version>`); with `recordedBy` any conclusion is
877
+ filed as a finding for the morning report. Deploying and promoting stay with a
878
+ human (`deployChange`, `promoteChange`): the shadow never calls them.
879
+
880
+ **Isolation and erasure.** Every row belongs to one organisation and every read
881
+ and write is scoped by it; a candidate, a sandbox or a store call of another
882
+ organisation is refused. Runs carry the `userId` of the request: register
883
+ `shadowEraser(store)` in `createConscience({ erasers })`, or call
884
+ `shadow.eraseSubject`, to delete them with the person.
885
+
886
+ **Storage.** `createMemoryShadowStore()` and `createPostgresShadowStore(db, { prefix })`
887
+ (schema: `postgresShadowSchema({ prefix })`, table `<prefix>_runs`). Same
888
+ contract, same tests, every value a SQL parameter.
889
+
890
+ ## Tests
891
+
892
+ ```sh
893
+ npm test -w @astratra/conscience
894
+ CONSCIENCE_TEST_DATABASE_URL=postgresql:///conscience_p2_test npm test -w @astratra/conscience
895
+ CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p4_test node --test packages/conscience/test/shadow.postgres.test.js
896
+ ```
897
+
898
+ PostgreSQL tests run only when the URL names a database ending in `_test`;
899
+ each test creates its own tables and drops them. A missing test database is
900
+ created with `createdb` when permitted; an unavailable database skips integration
901
+ tests with an explicit reason, without exposing the URL.
902
+
903
+ ## Limits
904
+
905
+ - No language model and no automatic change: P2 evaluates structured evidence only, every change
906
+ needs a human, and the governor never applies a change to your application by itself. It versions
907
+ the objects and tells you which version to serve (`resolveVersion`); you read that version where
908
+ you use the object.
909
+ - The governor recognises protected scopes by names and keys, not by reading
910
+ text: a proposal must describe its target honestly, and anything ambiguous
911
+ is rejected rather than allowed.
912
+ - The masker is yours: the package guarantees that stored text went through
913
+ it, not that it found everything.
914
+ - Shadow mode only judges the sampled requests (a burst beyond `maxConcurrent` is skipped and counted) and its intervals ignore
915
+ the pairing of requests: they are conservative. Metrics are yours and deterministic, and a tool read is only replayed from
916
+ recordings.