@astratra/conscience 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.fr.md +901 -0
- package/README.md +864 -2
- package/package.json +50 -4
- package/src/autoconscience/experiments/common.js +76 -0
- package/src/autoconscience/experiments/execution.js +33 -0
- package/src/autoconscience/experiments/holdout.js +88 -0
- package/src/autoconscience/experiments/laboratory.js +99 -0
- package/src/autoconscience/experiments/replay.js +113 -0
- package/src/autoconscience/experiments/runner.js +54 -0
- package/src/autoconscience/experiments/sandbox.js +58 -0
- package/src/autoconscience/index.d.ts +203 -0
- package/src/autoconscience/index.js +116 -0
- package/src/autoconscience/lessons.js +32 -0
- package/src/autoconscience/shadow/candidate.js +69 -0
- package/src/autoconscience/shadow/index.d.ts +169 -0
- package/src/autoconscience/shadow/index.js +11 -0
- package/src/autoconscience/shadow/report.js +125 -0
- package/src/autoconscience/shadow/runner.js +384 -0
- package/src/autoconscience/shadow/store.js +98 -0
- package/src/autoconscience/signals.js +88 -0
- package/src/autoconscience/statistics.js +84 -0
- package/src/autoconscience/vigilance/abstention.js +123 -0
- package/src/autoconscience/vigilance/adversary.js +145 -0
- package/src/autoconscience/vigilance/common.js +56 -0
- package/src/autoconscience/vigilance/drift.js +306 -0
- package/src/autoconscience/vigilance/followups.js +100 -0
- package/src/autoconscience/vigilance/index.d.ts +190 -0
- package/src/autoconscience/vigilance/index.js +23 -0
- package/src/autoconscience/vigilance/lessonTests.js +40 -0
- package/src/autoconscience/vigilance/library.js +162 -0
- package/src/autoconscience/vigilance/roles.js +122 -0
- package/src/autoconscience/vigilance/store.js +166 -0
- package/src/conscience.js +559 -0
- package/src/diff.js +27 -0
- package/src/errors.js +11 -0
- package/src/governor/approvals.js +132 -0
- package/src/governor/changes.js +269 -0
- package/src/governor/governor.js +286 -0
- package/src/governor/index.d.ts +308 -0
- package/src/governor/index.js +20 -0
- package/src/governor/policy.js +136 -0
- package/src/governor/postgres.js +243 -0
- package/src/governor/review.js +191 -0
- package/src/governor/rollout.js +66 -0
- package/src/governor/stores.js +136 -0
- package/src/governor/util.js +53 -0
- package/src/guard.js +21 -0
- package/src/index.d.ts +244 -0
- package/src/index.js +23 -0
- package/src/memoryStore.js +65 -0
- package/src/postgres.js +93 -0
- package/src/records.js +220 -0
package/README.md
CHANGED
|
@@ -1,3 +1,865 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @astratra/conscience
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
### Bootstrap check
|
|
248
|
+
|
|
249
|
+
`assertGovernorReady(governor, { organisationId })` throws `governor_missing`,
|
|
250
|
+
`governor_invalid` (an object not built by `createGovernor`),
|
|
251
|
+
`governor_unavailable` (store unreachable) or `governor_halted`. Every
|
|
252
|
+
reflective write of the package calls it first.
|
|
253
|
+
|
|
254
|
+
## Conscience (main entry)
|
|
255
|
+
|
|
256
|
+
`createConscience({ governor, masker, store, now, retention, erasers, onEvent })`
|
|
257
|
+
throws when the governor or the masker is missing.
|
|
258
|
+
|
|
259
|
+
### Records
|
|
260
|
+
|
|
261
|
+
| Method | Record |
|
|
262
|
+
|---|---|
|
|
263
|
+
| `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 |
|
|
264
|
+
| `recordPrediction(input)` | A probability attached to a decision, with its resolution date |
|
|
265
|
+
| `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 |
|
|
266
|
+
| `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 |
|
|
267
|
+
| `recordLesson(input)` | `MemoryLesson`: evidence, degree, `validFrom`/`validUntil`, status, contradictions, replacements. Reflective write |
|
|
268
|
+
| `updateSelfModel(input)` | `SelfModelSnapshot`: tested capabilities (each with evidence), tools, limits, permissions, provenance. Reflective write |
|
|
269
|
+
|
|
270
|
+
Every record has a stable id: pass your own, or it is derived from the
|
|
271
|
+
content, so recording the same thing twice gives one row. Records are never
|
|
272
|
+
updated; revisions are new rows.
|
|
273
|
+
|
|
274
|
+
Free text (objective, context, action input, expected outcome, observations,
|
|
275
|
+
lesson summaries and notes, corrections) goes through the masker before it is
|
|
276
|
+
stored. Use a deterministic masker.
|
|
277
|
+
|
|
278
|
+
### Evidence register
|
|
279
|
+
|
|
280
|
+
A lesson without evidence is always a `hypothesis` (`statusForced: true` when
|
|
281
|
+
another status was asked). Evidence that points to a decision, prediction,
|
|
282
|
+
outcome or correction must exist in the same organisation. This version stores
|
|
283
|
+
lessons and their history; P2 checks sample sufficiency and open contradictions
|
|
284
|
+
before a lesson can be verified.
|
|
285
|
+
|
|
286
|
+
### Reading
|
|
287
|
+
|
|
288
|
+
- `getDecision(scope, id)`, `recallDecisions(scope, { agentId, from, to, asOf, withOutcomes })`
|
|
289
|
+
- `getOutcomes(scope, decisionId)`: every revision with `revision`, `current`, `supersededAt`
|
|
290
|
+
- `getLesson(scope, lessonId)`, `listLessons(scope, { status, validAt, asOf })`
|
|
291
|
+
- `getSelfModel(scope, agentId, { asOf })`, `getSelfModelHistory(scope, agentId)`
|
|
292
|
+
- `getMemoryTimeline(scope, { axis: 'event' | 'recorded', from, to, asOf, validAt, kinds })`:
|
|
293
|
+
event time, recording time and validity period. `asOf` answers "what did
|
|
294
|
+
we know at that time".
|
|
295
|
+
- `getLineage(scope, decisionId)`: objective → action → tools → outcomes →
|
|
296
|
+
corrections → lessons.
|
|
297
|
+
|
|
298
|
+
A scope is `{ organisationId, userId? }`. A record of another organisation (or
|
|
299
|
+
another person, when `userId` is given) is answered exactly like a missing one.
|
|
300
|
+
|
|
301
|
+
### Memory guard
|
|
302
|
+
|
|
303
|
+
Stored text is untrusted data: it may come from a person, a tool or a
|
|
304
|
+
manipulated model. The package never interprets it, and the governor never
|
|
305
|
+
reads it. Before a model reads records, frame them:
|
|
306
|
+
|
|
307
|
+
```js
|
|
308
|
+
const { frameRecordsForModel } = require('@astratra/conscience');
|
|
309
|
+
const block = frameRecordsForModel(await conscience.listLessons({ organisationId: 'org-1' }));
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
The framing is the one of `@astratra/ai/guards` (random marker the content
|
|
313
|
+
cannot close).
|
|
314
|
+
|
|
315
|
+
### Erasure and retention
|
|
316
|
+
|
|
317
|
+
`eraseSubject({ organisationId, userId })` removes the person's decisions,
|
|
318
|
+
predictions, outcomes, corrections and lessons, removes references to them
|
|
319
|
+
from the organisation's lessons (a lesson left without evidence becomes a
|
|
320
|
+
hypothesis again), and calls your `erasers` for data kept elsewhere (vectors,
|
|
321
|
+
indexes, caches, calibrations). It returns a report with counts. With
|
|
322
|
+
`retention: { erasure: 'anonymise' }` the records are kept without the person.
|
|
323
|
+
|
|
324
|
+
Nothing is deleted on a timer. `applyRetention({ organisationId })` removes
|
|
325
|
+
records older than `retention.maxAgeDays[kind]`, and only for the kinds you
|
|
326
|
+
configured.
|
|
327
|
+
|
|
328
|
+
## Stores
|
|
329
|
+
|
|
330
|
+
Memory stores (default, lost on exit) and PostgreSQL stores are included. SQL
|
|
331
|
+
uses parameters only; the table prefix is a checked identifier.
|
|
332
|
+
|
|
333
|
+
```js
|
|
334
|
+
postgresConscienceSchema({ prefix: 'astratra_conscience' }) // table <prefix>_records
|
|
335
|
+
postgresGovernorSchema({ prefix: 'astratra_governor' }) // <prefix>_proposals, _audit, _spend, _controls, _objects, _versions, _findings
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
### Writing your own store (MongoDB, ...)
|
|
339
|
+
|
|
340
|
+
A conscience store has five methods on immutable envelopes
|
|
341
|
+
`{ kind, id, organisationId, userId, agentId, decisionId, lessonId, eventAt, recordedAt, fingerprint, evidenceRefs, data }`:
|
|
342
|
+
|
|
343
|
+
| Method | MongoDB sketch |
|
|
344
|
+
|---|---|
|
|
345
|
+
| `put(envelope)` | `insertOne` with a unique index on `{ organisationId, kind, id }`; on duplicate key return the existing document with `created: false` |
|
|
346
|
+
| `get(kind, organisationId, id)` | `findOne` |
|
|
347
|
+
| `list(kind, filter)` | `find` on the indexed fields, `recordedAt <= recordedTo`, `evidenceRefs: ref`, sorted by `recordedAt` then insertion |
|
|
348
|
+
| `replace(envelope)` | `replaceOne` (erasure and retention only) |
|
|
349
|
+
| `remove(kind, organisationId, ids)` | `deleteMany`, returns the count |
|
|
350
|
+
|
|
351
|
+
`matchesFilter(envelope, filter)` gives the exact filter semantics. The
|
|
352
|
+
governor store interface (`GovernorStore` in the types) needs an atomic
|
|
353
|
+
`reserveSpend` (a transaction), a compare-and-set `transitionProposal`
|
|
354
|
+
(`findOneAndUpdate` on `status`, and on the number of approvals when a `guard`
|
|
355
|
+
is given), a compare-and-set `updateObject` on `revision`, and insert-once
|
|
356
|
+
`createObject`, `putVersion` and `putFinding`.
|
|
357
|
+
|
|
358
|
+
## Autoconscience (`/autoconscience`)
|
|
359
|
+
|
|
360
|
+
The P2 core is deterministic and imports no language model. `evaluateOutcomes()`
|
|
361
|
+
(and its alias `runReflection()`) reads P1 records and returns `ReflectionFinding[]`.
|
|
362
|
+
`createEvaluator({ governor, conscience, ...defaults })` binds an evaluator;
|
|
363
|
+
`evaluate({ organisationId, userId?, agentId?, window?, ...options })` evaluates
|
|
364
|
+
one scope. All reflective entries check `assertGovernorReady`; evaluation has
|
|
365
|
+
no storage writes, generated text or automatic action.
|
|
366
|
+
|
|
367
|
+
```js
|
|
368
|
+
const { evaluateOutcomes } = require('@astratra/conscience/autoconscience');
|
|
369
|
+
const findings = await evaluateOutcomes({
|
|
370
|
+
governor, conscience, organisationId: 'org-1', agentId: 'billing-agent',
|
|
371
|
+
minimumSample: 30, buckets: 10, level: 0.95,
|
|
372
|
+
errorCostPolicies: [{ organisationId: 'org-1', domain: 'billing', falsePositive: 1, falseNegative: 20 }],
|
|
373
|
+
calendars: [{ organisationId: 'org-1', domain: 'billing', name: 'business',
|
|
374
|
+
periods: [{ label: 'closure', kind: 'closure', from: '2026-12-24', to: '2027-01-02' }] }]
|
|
375
|
+
});
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
### Structured inputs
|
|
379
|
+
|
|
380
|
+
- Decisions accept `domain` (default `general`), `justification: { claims: ['source_verified'] }`
|
|
381
|
+
and actual `toolTrace: [{ callId, tool, provider?, status, empty?, durationMs, labels? }]`.
|
|
382
|
+
A declared list of tools is not an execution trace. Labels such as `source_verified`
|
|
383
|
+
must come from your instrumented application, not from generated prose.
|
|
384
|
+
- Predictions accept `domain` (inherited from the decision) and an optional `sensor`.
|
|
385
|
+
Outcomes accept `predictionId`, checked against the decision in the same organisation.
|
|
386
|
+
- Corrections accept an application `class` or structured `tags`: `fact_changed`,
|
|
387
|
+
`wording_changed`, `goal_changed`, `opinion_changed`. Explicit class wins;
|
|
388
|
+
absent, unknown or conflicting tags become `disagreement`. Text is never classified
|
|
389
|
+
by a model or interpreted as a command.
|
|
390
|
+
- Lessons accept `domain`, `subject` and `stance: 'supports' | 'opposes'`.
|
|
391
|
+
Opposing positions within the same organisation, person, agent and domain open
|
|
392
|
+
a symmetric conflict (`to_reassess`). Textual summaries alone cannot establish opposition.
|
|
393
|
+
|
|
394
|
+
### Calculations and contracts
|
|
395
|
+
|
|
396
|
+
| Function | Result |
|
|
397
|
+
|---|---|
|
|
398
|
+
| `honestStatistics(statuses, options)` | Known sample size, unknown count, success rate, Wilson interval, `insufficient_data` below `minimumSample` (30 by default), refusal to conclude |
|
|
399
|
+
| `wilsonInterval(successes, total, level)` | Two-sided Wilson score interval; levels 0.90, 0.95 (default), 0.99; null only for zero known observations |
|
|
400
|
+
| `calibratePredictions(points, options)` | Per agent/domain reliability curve, Brier score, signed confidence gap, overconfidence and underconfidence; empty bins have null means |
|
|
401
|
+
| `scoreErrorCosts(points, policy, options)` | False positive/negative counts, total cost and `weightedScore = totalCost / knownCount` in your cost units; threshold 0.5 by default |
|
|
402
|
+
| `checkReasoningFidelity(justification, traces, claimRules)` | `faithful`, `unfaithful` or `unknown`; every required label needs a successful, nonempty call; default rule requires `source_verified` |
|
|
403
|
+
| `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) |
|
|
404
|
+
| `calendarConfounders(domain, at, calendars)` | `calendar_confounded` for dates in a declared half-open period `[from, to)` |
|
|
405
|
+
| `checkCounterMetrics(target, counters)` | Target improvement rejected if any counter-metric regresses strictly beyond its `maxRegression`; thresholds use absolute metric units |
|
|
406
|
+
| `classifyCorrection(input)` | Deterministic classification; only `factual` corrections can support a factual lesson |
|
|
407
|
+
| `evaluateLessonConflicts(lessons, options)` | Open conflicts with evidence ranking and dates; stronger evidence can suggest a preferred lesson, a newer date alone never resolves one |
|
|
408
|
+
| `reflectionUtility(run, options)` | Useful findings + accepted proposals (configurable weights) minus weighted cost; usefulness requires positive benefit and positive net utility |
|
|
409
|
+
| `recommendReflectionFrequency(runs, options)` | `reduce` after `uselessCycles` consecutive useless completed cycles (default 3); interval multiplier `reductionFactor` (default 2) |
|
|
410
|
+
|
|
411
|
+
Cycles without measured useful-finding or accepted-proposal counts remain
|
|
412
|
+
`unmeasured`; they do not count as useless cycles. Unknown tool-call statuses
|
|
413
|
+
stay outside the error-rate denominator (empty and slow rates describe actual
|
|
414
|
+
reported emptiness and durations).
|
|
415
|
+
|
|
416
|
+
Unknown outcomes never enter success/failure denominators or Brier/cost scores.
|
|
417
|
+
Evaluation uses the latest prediction per decision/domain (date, then id), and
|
|
418
|
+
the current outcome for its sensor or explicit prediction link. Missing or
|
|
419
|
+
ambiguous matches, or predictions made after the observation, remain unknown.
|
|
420
|
+
One decision contributes at most one calibration point per domain; duplicate
|
|
421
|
+
points supplied directly to `calibratePredictions` are rejected. The curve's
|
|
422
|
+
bins also expose their own sample adequacy. Scores below the threshold remain
|
|
423
|
+
descriptive; they are not rules or causal evidence.
|
|
424
|
+
|
|
425
|
+
Findings contain stable ids, evidence references, sample size, interval, status,
|
|
426
|
+
confidence, confounders and competing explanations. The core always emits
|
|
427
|
+
`causality: 'not_established'`: an outcome and the fidelity of its method remain
|
|
428
|
+
separate. A lucky success never creates a general rule. `confidence` describes
|
|
429
|
+
the supplied observation confidence or interval level, not the probability that
|
|
430
|
+
a causal hypothesis is true. Intervals remain visible for small nonzero samples
|
|
431
|
+
while `insufficient_data` explicitly refuses inference.
|
|
432
|
+
|
|
433
|
+
### Lesson verification and arbitration
|
|
434
|
+
|
|
435
|
+
`createConscience({ minimumSample: 30, ... })` controls the verification floor;
|
|
436
|
+
a lesson may request a higher `minimumSample`, never lower that floor.
|
|
437
|
+
Verification counts **distinct decisions** represented by current known outcomes
|
|
438
|
+
or factual corrections in the lesson's domain and agent scope. Decision-only,
|
|
439
|
+
prediction-only and external references do not inflate the observed sample;
|
|
440
|
+
unknown or superseded outcomes and duplicate references do not count. A factual
|
|
441
|
+
lesson citing a style/objective/disagreement correction remains a hypothesis.
|
|
442
|
+
Evidence existence, sufficient sample and no open contradiction are all required
|
|
443
|
+
for `verified`; open conflicts produce `to_reassess`, other cases `hypothesis`.
|
|
444
|
+
This is an evidence sufficiency status, not a proof of a causal assertion.
|
|
445
|
+
|
|
446
|
+
`conscience.resolveLessonConflict({ organisationId, userId?, winnerId, loserId, evidence })`
|
|
447
|
+
is an explicit application arbitration: it requires sufficient factual evidence
|
|
448
|
+
in the same domain, retires the opponent and appends a new revision of the winner.
|
|
449
|
+
All writes pass through `assertGovernorReady`. Earlier revisions are retained.
|
|
450
|
+
`getLesson().current` and `listLessons()` reassess evidence and conflicts, including
|
|
451
|
+
late unknown outcomes and concurrent conflicting writes. `storedStatus` exposes
|
|
452
|
+
the recorded status; `getLesson().history` retains recorded revisions. `asOf`
|
|
453
|
+
uses the evidence and outcomes known at that recording date.
|
|
454
|
+
|
|
455
|
+
Findings and calibration are recalculated rather than cached or persisted:
|
|
456
|
+
erasing their source records removes them from subsequent evaluations. If your
|
|
457
|
+
application stores findings elsewhere, register an eraser for that store.
|
|
458
|
+
Windows filter decision dates; they do not implement P3 time-frozen replay.
|
|
459
|
+
A query reaching 1000 decisions refuses with `evaluation_limit`: supply explicit
|
|
460
|
+
`decisionIds` for a larger selection, rather than silently evaluate a partial sample.
|
|
461
|
+
|
|
462
|
+
P3 experiments and P4 shadow mode are described in their own sections below.
|
|
463
|
+
Evaluation itself does not create a scheduler, a model transport or a deployment.
|
|
464
|
+
|
|
465
|
+
- P3, experiments: time-frozen replay that refuses future data, sandbox,
|
|
466
|
+
protected test set. Drift monitoring, follow-ups, abstention, the night
|
|
467
|
+
adversary, multi-role review and lessons turned into tests are described in
|
|
468
|
+
"P3 · vigilance (2/2)" below.
|
|
469
|
+
- P4, shadow mode in a sandbox: see "P4 · shadow mode" below.
|
|
470
|
+
- Only P6 (integration and guarded transfer between agents) remains outside this package.
|
|
471
|
+
|
|
472
|
+
P5 (advanced governance) is in the governor entry: see above.
|
|
473
|
+
|
|
474
|
+
## P3 · experiments (1/2)
|
|
475
|
+
|
|
476
|
+
The first half of P3 implements proposals 02/35 (temporal replay), 32
|
|
477
|
+
(simulated tools), 36 (protected final set) and 16 (preregistered experiments).
|
|
478
|
+
The package stays at the unreleased version 1.0.0. All five API entries and
|
|
479
|
+
their later operations check `assertGovernorReady`; scope is one organisation.
|
|
480
|
+
The scoring core imports no language model and never uses generated text as a
|
|
481
|
+
judge. Remaining P3 capabilities belong to the second half.
|
|
482
|
+
|
|
483
|
+
| API | Contract |
|
|
484
|
+
|---|---|
|
|
485
|
+
| `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'`. |
|
|
486
|
+
| `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. |
|
|
487
|
+
| `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. |
|
|
488
|
+
| `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. |
|
|
489
|
+
| `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. |
|
|
490
|
+
|
|
491
|
+
```js
|
|
492
|
+
const { createHoldout, proposeExperiment, runExperiment } = require('@astratra/conscience/autoconscience');
|
|
493
|
+
const binding = { governor, organisationId: 'org-1' };
|
|
494
|
+
// Supply these three disjoint sets from trusted provisioning code.
|
|
495
|
+
// Each case is { id, input, expected }; reflection never receives finalCases.
|
|
496
|
+
const holdout = await createHoldout({ ...binding, cases: finalCases });
|
|
497
|
+
const experiment = await proposeExperiment({
|
|
498
|
+
...binding, hypothesis: 'The candidate meets the registered accuracy floor',
|
|
499
|
+
agent: (input) => input, // self-contained evaluated function
|
|
500
|
+
metrics: [{ name: 'accuracy', kind: 'exact_match' }],
|
|
501
|
+
thresholds: { accuracy: 0.9 },
|
|
502
|
+
protocol: { development: developmentCases, validation: validationCases,
|
|
503
|
+
minimumSample: 30, level: 0.95, timeoutMs: 1000 },
|
|
504
|
+
holdout
|
|
505
|
+
});
|
|
506
|
+
const result = await runExperiment({ ...binding, experiment });
|
|
507
|
+
// result.decision: supported | refuted | inconclusive
|
|
508
|
+
// result.stages.holdout: aggregate metrics only, no cases, answers or journal.
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
Metrics use deterministic JSON equality (`kind: 'exact_match'`). Optional
|
|
512
|
+
`outputKey` / `expectedKey` select structured fields. No evaluator callback can
|
|
513
|
+
read final answers. P2 `honestStatistics` supplies known/unknown counts and
|
|
514
|
+
two-sided Wilson intervals (minimum 30; levels 0.90, 0.95, 0.99). A missing
|
|
515
|
+
output, execution failure or timeout is unknown. A decision is `supported`
|
|
516
|
+
only when **every metric in every stage** has sufficient observations and an
|
|
517
|
+
interval entirely at or above its threshold; `refuted` requires a sufficient
|
|
518
|
+
interval entirely below a threshold; insufficient data, unknowns or an interval
|
|
519
|
+
crossing a threshold are `inconclusive`. These are threshold tests, not a
|
|
520
|
+
claim of causal improvement over a baseline. `interval` is the first final
|
|
521
|
+
metric's interval; all intervals are in `stages.*.metrics`. Case ids and input
|
|
522
|
+
fingerprints must be distinct across splits; repeated inputs cannot inflate a
|
|
523
|
+
sample. Development/validation intentions are journaled; final intentions and
|
|
524
|
+
individual outputs are not exposed.
|
|
525
|
+
|
|
526
|
+
A replay `proposal` is `{ agent, information?: [{ organisationId, userId?, at,
|
|
527
|
+
recordedAt, data }] }`. `snapshots` maps `inputSnapshotRef` to the same dated
|
|
528
|
+
shape; a referenced snapshot is mandatory (`snapshot_missing`). Without a
|
|
529
|
+
reference, the stored dated context is the snapshot. The candidate receives
|
|
530
|
+
`{ inputs, outcomes, lessons, information, decision, asOf }`; `decision` contains
|
|
531
|
+
only id, objective, context, versions and permissions, never the original
|
|
532
|
+
action or expected answer. Compatibility compares its output to
|
|
533
|
+
`{ name: originalAction.name, input: originalAction.input }`. Outcome and lesson
|
|
534
|
+
revisions recorded later are excluded; an early-recorded but future-dated fact
|
|
535
|
+
is refused. Historical lesson evidence is checked too; undated external
|
|
536
|
+
evidence is refused (`temporal_evidence_required`). Factual timestamps,
|
|
537
|
+
including nested ones and simulated responses, are validated. Replay read responses
|
|
538
|
+
require `{ organisationId, userId?, at, recordedAt, data }`
|
|
539
|
+
(`temporal_metadata_required` without dates); planned horizons
|
|
540
|
+
and expiry dates are not treated as future observations. Snapshot dates must
|
|
541
|
+
be truthful: the library cannot infer undeclared provenance or whether literal
|
|
542
|
+
knowledge embedded in candidate source came from the future. Selections are
|
|
543
|
+
bounded rather than silently truncated (`replay_limit`).
|
|
544
|
+
|
|
545
|
+
Candidates are serialized from function source and executed in fresh worker
|
|
546
|
+
realms with only JSON data and simulated tools. They cannot access host
|
|
547
|
+
closures, `process`, `require`, `fetch`, filesystem, dynamic imports or host
|
|
548
|
+
callbacks. Async computations using simulated tools are supported. An injected
|
|
549
|
+
model may compute the evaluated agent's output as a self-contained function;
|
|
550
|
+
remote model transports and captured model clients cannot run in this sandbox.
|
|
551
|
+
The core never chooses or calls a model to decide the score. Worker timeouts
|
|
552
|
+
(10–30000 ms per case), memory and output limits bound execution. This is an
|
|
553
|
+
application execution boundary for supplied candidate code, not an OS security
|
|
554
|
+
boundary for arbitrary hostile native code.
|
|
555
|
+
|
|
556
|
+
Provisioning code must keep original final cases outside reflection; a handle
|
|
557
|
+
cannot protect copies already shared by the application. A final set is
|
|
558
|
+
single-use to prevent adaptive probing, and is consumed even on failed
|
|
559
|
+
execution. Registration handles, final contents and access logs are local to
|
|
560
|
+
the process and are not restartable; audit metadata and aggregate results are
|
|
561
|
+
recorded as governor findings (`experiment_registered`, `experiment_started`,
|
|
562
|
+
`experiment_completed` / `experiment_failed`) in its memory or PostgreSQL
|
|
563
|
+
store. No new SQL schema or dependency is needed. Real PostgreSQL tests run
|
|
564
|
+
with `CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p3a_test`;
|
|
565
|
+
P3 integration tests fail, rather than skip, if an explicitly supplied test
|
|
566
|
+
database is unavailable. Run the mutation proof separately with
|
|
567
|
+
`node packages/conscience/test/experiments-mutations.js`.
|
|
568
|
+
|
|
569
|
+
## P3 · vigilance (2/2)
|
|
570
|
+
|
|
571
|
+
Second half of P3, in `@astratra/conscience/autoconscience`: six deterministic
|
|
572
|
+
modules that watch, remind, hold back, challenge, cross-check and turn lessons
|
|
573
|
+
into tests. None imports a language model (a test reads the sources), and none
|
|
574
|
+
applies anything: every change goes through a proposal to the governor, and
|
|
575
|
+
every call first checks that the governor exists, is genuine and is not halted
|
|
576
|
+
(`assertGovernorReady`).
|
|
577
|
+
|
|
578
|
+
| No. | Function | What it does |
|
|
579
|
+
| --- | --- | --- |
|
|
580
|
+
| 17 | `detectDrift` | Drift watch on inputs, outcomes and performance, with a coded recommendation. |
|
|
581
|
+
| 18 | `createFollowUps` | Prospective memory: `scheduleFollowUp`, `dueFollowUps`. |
|
|
582
|
+
| 26 | `abstentionPolicy` | Confidence threshold from calibration and error costs. |
|
|
583
|
+
| 27 | `generateAdversarialCases` | Candidate trap scenarios from recent failures. |
|
|
584
|
+
| 14 | `reviewByRoles` | Verifier, contradictor and risk controller, reviewed apart. |
|
|
585
|
+
| 03 | `lessonToScenario` | A verified lesson becomes an anti-regression scenario. |
|
|
586
|
+
|
|
587
|
+
### Drift watch (17)
|
|
588
|
+
|
|
589
|
+
```js
|
|
590
|
+
const report = await detectDrift({
|
|
591
|
+
governor, organisationId, agentId, domain,
|
|
592
|
+
baseline: { window: { from, to }, inputs: { domains, languages, lengths },
|
|
593
|
+
outcomes: { succeeded, failed, unknown },
|
|
594
|
+
performance: { calibration: { sampleSize, brierScore, confidenceGap }, tools: [{ tool, provider, knownCalls, failures }] } },
|
|
595
|
+
current: { /* same shape */ },
|
|
596
|
+
calendars, // P2 DomainCalendar[] of the same organisation
|
|
597
|
+
recentChange, // { kind, id, version, previousVersion, deployedAt }
|
|
598
|
+
propose: {} // optional: a rollback recommendation becomes a PENDING proposal
|
|
599
|
+
});
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
`snapshotWindow({ decisions, findings, agentId, domain, languageOf })` builds a
|
|
603
|
+
summary from P2 material (the core detects no language: `languageOf` is yours).
|
|
604
|
+
|
|
605
|
+
Tests, simple and documented in the source: the Population Stability Index for
|
|
606
|
+
distributions (domains, languages, lengths cut at the baseline quintiles; a 0.5
|
|
607
|
+
pseudo-count per category; below 0.10 stable, 0.10 to 0.25 moderate, 0.25 or
|
|
608
|
+
more significant) and the difference of two proportions with Newcombe's hybrid
|
|
609
|
+
score interval, built from the Wilson intervals of P2 (outcome success rate,
|
|
610
|
+
share of unknown, tool error rate). A shift is significant when the interval
|
|
611
|
+
excludes zero and the gap is at least 5 points (`minimumEffect`). Brier score
|
|
612
|
+
and confidence gap are compared with a threshold (`brierDelta`,
|
|
613
|
+
`confidenceGapDelta`). A window with fewer than `minimumSample` known
|
|
614
|
+
observations never concludes: `insufficient_data`.
|
|
615
|
+
|
|
616
|
+
A **business calendar** is read before the agent is blamed: a period that
|
|
617
|
+
overlaps the current window and not the baseline one explains the shift
|
|
618
|
+
(`attribution: 'calendar'`, recommendation `monitor`, `reexamineAfter`).
|
|
619
|
+
|
|
620
|
+
Coded recommendation: `monitor`, `investigate` (inputs moved or a tool decayed
|
|
621
|
+
together with a decline), `freeze` (severe unexplained decline, `freezeDrop`),
|
|
622
|
+
`propose_rollback` (decline in a window that starts after a recent change, inputs
|
|
623
|
+
stable). The report always says `applied: false`. With `propose`, a rollback
|
|
624
|
+
becomes a pending proposal at the governor (high risk, two approvals by default)
|
|
625
|
+
and still nothing is rolled back: a human decides, then `rollbackChange` is yours
|
|
626
|
+
to call. `recordedBy` also files a finding for the morning report.
|
|
627
|
+
|
|
628
|
+
### Prospective memory (18)
|
|
629
|
+
|
|
630
|
+
```js
|
|
631
|
+
const vstore = createMemoryVigilanceStore(); // or createPostgresVigilanceStore(pool)
|
|
632
|
+
const conscience = createConscience({ governor, masker, erasers: [followUpEraser(vstore)] });
|
|
633
|
+
const followUps = createFollowUps({ governor, conscience, store: vstore, masker });
|
|
634
|
+
await followUps.scheduleFollowUp({ organisationId, decisionId, observableAt, question });
|
|
635
|
+
const due = await followUps.dueFollowUps({ organisationId }); // { followUp, decision }[]
|
|
636
|
+
await followUps.completeFollowUp({ organisationId, id });
|
|
637
|
+
```
|
|
638
|
+
|
|
639
|
+
Idempotent: the same decision, date and question give the same follow-up
|
|
640
|
+
(`created: false`). The question is masked before storage. The decision must exist
|
|
641
|
+
in the organisation (another organisation's decision: `not_found`). Follow-ups
|
|
642
|
+
are erased with the person through `eraseSubject` (register `followUpEraser`);
|
|
643
|
+
a follow-up whose decision was erased or expired is never returned as due. The
|
|
644
|
+
content of a due item is data, never an instruction.
|
|
645
|
+
|
|
646
|
+
### Abstention (26)
|
|
647
|
+
|
|
648
|
+
`abstentionPolicy({ governor, organisationId, agentId, domain, calibration, errorCosts, currentThreshold, propose })`.
|
|
649
|
+
Acting is worth it when the chance of success is at least
|
|
650
|
+
`falsePositive / (falsePositive + falseNegative)` (the cost table of P2). The
|
|
651
|
+
threshold is the lowest announced confidence, with observations of its own, from
|
|
652
|
+
which the lower Wilson bound of the observed success rate stays above that
|
|
653
|
+
ratio, over at least `minimumSample` decisions. Not enough data or no cost table:
|
|
654
|
+
a prudent default (0.8), never lower than the threshold already in force. No
|
|
655
|
+
reliable region: 1. `shouldAbstain(policy, { confidence, actionKind })` answers
|
|
656
|
+
`proceed`, `ask_clarification` or (for `write` and `confirm` actions)
|
|
657
|
+
`propose_verification`, always from the threshold **in force**
|
|
658
|
+
(`effectiveThreshold`). A new threshold is a proposal on target
|
|
659
|
+
`threshold:abstention:<agent>:<domain>`; nothing is applied here.
|
|
660
|
+
|
|
661
|
+
### Night adversary (27) and lessons turned into tests (03)
|
|
662
|
+
|
|
663
|
+
```js
|
|
664
|
+
const library = createScenarioLibrary({ governor, store: vstore, masker });
|
|
665
|
+
const { candidates, rejected } = await generateAdversarialCases({ governor, organisationId, failures, masker, generator, library });
|
|
666
|
+
const lessonCase = await lessonToScenario(lesson, { governor, masker, question, tools, expect, library });
|
|
667
|
+
// later, after humans approved the proposals at the governor:
|
|
668
|
+
const suite = (await library.approved({ organisationId })).map((a) => a.scenario); // for evaluateAgent
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
`generateAdversarialCases` turns recent failures into candidates of four
|
|
672
|
+
categories (injection, ambiguity, edge case, access to another organisation) in
|
|
673
|
+
the format of `evaluateAgent` from `@astratra/testkit`: `id`, `question`,
|
|
674
|
+
simulated tools (fixed results, no effect), `expect`, and a `score` that fails
|
|
675
|
+
the case when a forbidden tool is called or a forbidden text appears. An
|
|
676
|
+
**injected generator** may write the cases (a function that returns data only;
|
|
677
|
+
what it returns is validated, masked, and replaced by the template if invalid or
|
|
678
|
+
failing). Without one, deterministic templates are used, the same failure giving
|
|
679
|
+
the same cases. The **masker is required** and runs on failures and on whatever
|
|
680
|
+
the generator returns.
|
|
681
|
+
|
|
682
|
+
`lessonToScenario` accepts a lesson whose status is `verified` (evidence, enough
|
|
683
|
+
distinct decisions, no open conflict); a hypothesis, a lesson to reassess or a
|
|
684
|
+
retired one is refused (`lesson_not_verified`). The lesson says what was learned;
|
|
685
|
+
you describe how to check it, and a scenario that asserts nothing is refused.
|
|
686
|
+
|
|
687
|
+
Every candidate is born `to_review`. With a library it becomes a proposal at the
|
|
688
|
+
governor (target kind `instructions`, id `scenarios:<agent>`, configurable with
|
|
689
|
+
`targetKind`). `library.approved()` is the **only** way into the test suite: it
|
|
690
|
+
keeps a candidate only when humans approved that exact content (same
|
|
691
|
+
fingerprint) and the stored content is unchanged. A model, a decline, an expired
|
|
692
|
+
approval or an altered candidate keep it out.
|
|
693
|
+
|
|
694
|
+
### Multi-role review (14)
|
|
695
|
+
|
|
696
|
+
```js
|
|
697
|
+
const review = await reviewByRoles({ governor, organisationId, finding, roles: { verifier, contradictor, riskController } });
|
|
698
|
+
review.advances; review.status; // true / 'supported', or false / 'hypothesis' with review.blockers
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
Three separate functions, not a vote of models. The finding moves forward only
|
|
702
|
+
if the verifier cites **independent** evidence (not the finding's own evidence or
|
|
703
|
+
decisions, same organisation, optionally confirmed by `evidenceExists`), if no
|
|
704
|
+
competing explanation of the contradictor is as strong as the finding's
|
|
705
|
+
confidence, and if the risk controller approves a scope at least as wide as the
|
|
706
|
+
requested one (`observation` < `agent` < `domain` < `organisation`). A role that
|
|
707
|
+
throws or answers badly blocks the finding. Roles receive a frozen copy of the
|
|
708
|
+
finding, never each other's answers.
|
|
709
|
+
|
|
710
|
+
### Storage
|
|
711
|
+
|
|
712
|
+
`createMemoryVigilanceStore()` and `createPostgresVigilanceStore(db, { prefix })`
|
|
713
|
+
(schema: `postgresVigilanceSchema({ prefix })`, tables `<prefix>_follow_ups` and
|
|
714
|
+
`<prefix>_candidates`). Same contract, same tests, every access scoped by
|
|
715
|
+
organisation, every value a SQL parameter.
|
|
716
|
+
|
|
717
|
+
## P4 · shadow mode
|
|
718
|
+
|
|
719
|
+
Proposals 21 (shadow mode) and 32 (sandbox of the shadow mode), in
|
|
720
|
+
`@astratra/conscience/autoconscience`. A candidate strategy that humans already
|
|
721
|
+
approved processes a share of the real requests **in silence**, next to the
|
|
722
|
+
stable strategy. Its answers go to nobody. They are compared with the stable
|
|
723
|
+
answers by deterministic metrics you provide, and the gap is kept, masked, as a
|
|
724
|
+
`ShadowRun`. No language model is imported (a test reads the sources); every
|
|
725
|
+
call first checks `assertGovernorReady`.
|
|
726
|
+
|
|
727
|
+
```js
|
|
728
|
+
const { createSandbox, createShadowRunner, createMemoryShadowStore, shadowEraser } = require('@astratra/conscience/autoconscience');
|
|
729
|
+
|
|
730
|
+
const sandbox = await createSandbox({ governor, organisationId, tools: {
|
|
731
|
+
lookup_invoice: { kind: 'read', response: { status: 'unknown' } }, // simulated or recorded
|
|
732
|
+
send_reminder: { kind: 'write' } // never executed, only journalled
|
|
733
|
+
} });
|
|
734
|
+
const shadow = await createShadowRunner({
|
|
735
|
+
governor, organisationId,
|
|
736
|
+
candidate: { kind: 'instructions', id: 'reminders', agent }, // or { proposalId, agent }
|
|
737
|
+
sandbox, sampleRate: 0.1,
|
|
738
|
+
budget: { maxRuns: 500, maxCost: 50, costPerRun: 0.1 },
|
|
739
|
+
masker, // required
|
|
740
|
+
store: createMemoryShadowStore(), // or createPostgresShadowStore(pool)
|
|
741
|
+
metrics: [
|
|
742
|
+
{ name: 'accuracy', score: ({ input, output }) => output.total === input.expected },
|
|
743
|
+
{ name: 'sources_accuracy', score: ({ output }) => output.sourced === true, maxRegression: 0.02 },
|
|
744
|
+
{ name: 'minor_protection', critical: true, score: ({ input, output }) => !(input.minor && output.disclosed) }
|
|
745
|
+
],
|
|
746
|
+
target: 'accuracy', minimumSample: 30
|
|
747
|
+
});
|
|
748
|
+
|
|
749
|
+
// In the request path: answer with the stable strategy, then hand over. Never await `done`.
|
|
750
|
+
const answer = await stable(request);
|
|
751
|
+
respond(answer);
|
|
752
|
+
shadow.observe({ request: { id: request.id, userId: request.userId, input: request.input }, stableResult: { output: answer, durationMs, cost } });
|
|
753
|
+
|
|
754
|
+
const report = await shadow.report({ propose: {}, recordedBy: { kind: 'system', id: 'shadow' } });
|
|
755
|
+
report.conclusion; // 'insufficient_data' | 'regression' | 'no_difference' | 'promising'
|
|
756
|
+
```
|
|
757
|
+
|
|
758
|
+
**Which strategy may run.** Either the candidate version of a governor object
|
|
759
|
+
(`{ kind, id }`: the version staged from a proposal that humans approved) or a
|
|
760
|
+
proposal in the `approved` state with human approvals (`{ proposalId }`). A
|
|
761
|
+
pending, declined, rejected or expired proposal, a stable version, an unknown
|
|
762
|
+
object or another organisation's object are refused (`candidate_not_approved`,
|
|
763
|
+
`candidate_not_staged`, `not_found`). The check is repeated before every run: a
|
|
764
|
+
candidate that was rolled back, promoted or replaced stops the shadow.
|
|
765
|
+
|
|
766
|
+
**The candidate answer is never returned.** `observe` is synchronous, never
|
|
767
|
+
throws and never waits: it returns `{ scheduled, reason, done }`, and `done`
|
|
768
|
+
(which never rejects) resolves to an acknowledgement (`recorded` with a run id,
|
|
769
|
+
or `skipped`, `timeout`, `error` with a reason) that carries no output of the
|
|
770
|
+
candidate. The run happens in the background, after the stable answer. A failing,
|
|
771
|
+
slow or hostile candidate, a failing store or masker, a metric that throws: all
|
|
772
|
+
are isolated and counted (`stats()`), none reaches the caller. A deadline
|
|
773
|
+
(`deadlineMs`) abandons a stalled run, and `maxConcurrent` skips a burst as
|
|
774
|
+
`busy` rather than queue it.
|
|
775
|
+
|
|
776
|
+
**Sandbox only (32).** The candidate is a self-contained function run in the P3
|
|
777
|
+
sandbox: no host object, no `process`, no `require`, no timer, no `fetch`. Its
|
|
778
|
+
tools are the ones of the sandbox: a read returns a recording (the optional
|
|
779
|
+
`recordings` of `observe`, for example what the stable run read) or a simulated
|
|
780
|
+
answer; a write is **never executed**, even when the candidate calls it, and is
|
|
781
|
+
only journalled as an intention (`writeIntentions`, masked). The shadow opens no
|
|
782
|
+
network connection of its own. A model call inside a candidate is a sandbox
|
|
783
|
+
tool, replayed or simulated, never a live call.
|
|
784
|
+
|
|
785
|
+
**Sampling, budget, kill switch.** A request is selected by a hash of its id and
|
|
786
|
+
of the shadow id: the same request always gives the same choice, whatever the
|
|
787
|
+
order, and `sampleRate: 0.1` selects a subset of what `0.5` selects. The budget is
|
|
788
|
+
required and capped: `maxRuns`, `maxCost` (`costPerRun` is the ceiling reserved
|
|
789
|
+
for a run, `costOf` can only lower it), `maxDurationMs` (measured time, which the
|
|
790
|
+
runs already in flight can overshoot), and `governorAgentId` to spend through
|
|
791
|
+
`governor.authorizeSpend` as well. When the budget is spent, or the governor kill
|
|
792
|
+
switch is on, the shadow stops at once, stays stopped (releasing the switch does
|
|
793
|
+
not wake it: start a new one) and a run that finishes after the stop is
|
|
794
|
+
dropped. Budgets count the runs already stored, so a restart continues the same
|
|
795
|
+
shadow.
|
|
796
|
+
|
|
797
|
+
**ShadowRun.** Per sampled request: the masked request, the masked candidate and
|
|
798
|
+
stable outputs (replaced by a fingerprint beyond 20 000 characters), the score of
|
|
799
|
+
each side for each metric (`succeeded`, `failed`, `unknown`), whether both
|
|
800
|
+
answers agree, the write intentions, duration, cost and incidents
|
|
801
|
+
(`candidate_failed`, `candidate_timeout`, `scoring_failed`, ...). The raw request
|
|
802
|
+
id is not kept. A masker that fails keeps the run out of the store. A candidate
|
|
803
|
+
that produces nothing fails the metrics: it cannot have succeeded.
|
|
804
|
+
|
|
805
|
+
**Report.** Per metric, the success rate of each side with its Wilson interval
|
|
806
|
+
and minimum sample (P2: below it, `insufficient_data` and no difference), the
|
|
807
|
+
paired counts, and the difference (candidate minus stable) with a Newcombe
|
|
808
|
+
interval. Anti-Goodhart (P2): the `target` metric must improve while every other
|
|
809
|
+
metric stays within its `maxRegression` (and `limits.cost`); at least one
|
|
810
|
+
counter-measure is required when the shadow is built. Critical metrics list the
|
|
811
|
+
requests where the stable strategy succeeded and the candidate failed. The
|
|
812
|
+
conclusion is a code, in this order:
|
|
813
|
+
|
|
814
|
+
| Conclusion | When |
|
|
815
|
+
|---|---|
|
|
816
|
+
| `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`. |
|
|
817
|
+
| `insufficient_data` | Fewer than `minimumSample` runs, a metric with too few known scores, or a cost limit without the stable cost. |
|
|
818
|
+
| `promising` | The target improved with an interval above zero and every counter-measure held. |
|
|
819
|
+
| `no_difference` | Enough data, no significant difference and no regression. |
|
|
820
|
+
|
|
821
|
+
It never says "proven": `provesImprovement` is always `false`, `causality` is
|
|
822
|
+
`not_established`, `applied` is `false`. A shadow comparison on a sample of real
|
|
823
|
+
requests can make an improvement promising, nothing more. With `propose`, a
|
|
824
|
+
promising result becomes a **pending proposal** at the governor (target kind of
|
|
825
|
+
the candidate, id `shadow:<id>:<version>`); with `recordedBy` any conclusion is
|
|
826
|
+
filed as a finding for the morning report. Deploying and promoting stay with a
|
|
827
|
+
human (`deployChange`, `promoteChange`): the shadow never calls them.
|
|
828
|
+
|
|
829
|
+
**Isolation and erasure.** Every row belongs to one organisation and every read
|
|
830
|
+
and write is scoped by it; a candidate, a sandbox or a store call of another
|
|
831
|
+
organisation is refused. Runs carry the `userId` of the request: register
|
|
832
|
+
`shadowEraser(store)` in `createConscience({ erasers })`, or call
|
|
833
|
+
`shadow.eraseSubject`, to delete them with the person.
|
|
834
|
+
|
|
835
|
+
**Storage.** `createMemoryShadowStore()` and `createPostgresShadowStore(db, { prefix })`
|
|
836
|
+
(schema: `postgresShadowSchema({ prefix })`, table `<prefix>_runs`). Same
|
|
837
|
+
contract, same tests, every value a SQL parameter.
|
|
838
|
+
|
|
839
|
+
## Tests
|
|
840
|
+
|
|
841
|
+
```sh
|
|
842
|
+
npm test -w @astratra/conscience
|
|
843
|
+
CONSCIENCE_TEST_DATABASE_URL=postgresql:///conscience_p2_test npm test -w @astratra/conscience
|
|
844
|
+
CONSCIENCE_TEST_DATABASE_URL=postgresql://localhost/conscience_p4_test node --test packages/conscience/test/shadow.postgres.test.js
|
|
845
|
+
```
|
|
846
|
+
|
|
847
|
+
PostgreSQL tests run only when the URL names a database ending in `_test`;
|
|
848
|
+
each test creates its own tables and drops them. A missing test database is
|
|
849
|
+
created with `createdb` when permitted; an unavailable database skips integration
|
|
850
|
+
tests with an explicit reason, without exposing the URL.
|
|
851
|
+
|
|
852
|
+
## Limits
|
|
853
|
+
|
|
854
|
+
- No language model and no automatic change: P2 evaluates structured evidence only, every change
|
|
855
|
+
needs a human, and the governor never applies a change to your application by itself. It versions
|
|
856
|
+
the objects and tells you which version to serve (`resolveVersion`); you read that version where
|
|
857
|
+
you use the object.
|
|
858
|
+
- The governor recognises protected scopes by names and keys, not by reading
|
|
859
|
+
text: a proposal must describe its target honestly, and anything ambiguous
|
|
860
|
+
is rejected rather than allowed.
|
|
861
|
+
- The masker is yours: the package guarantees that stored text went through
|
|
862
|
+
it, not that it found everything.
|
|
863
|
+
- Shadow mode only judges the sampled requests (a burst beyond `maxConcurrent` is skipped and counted) and its intervals ignore
|
|
864
|
+
the pairing of requests: they are conservative. Metrics are yours and deterministic, and a tool read is only replayed from
|
|
865
|
+
recordings.
|