@astratra/conscience 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.fr.md +954 -0
- package/README.md +915 -2
- package/package.json +50 -4
- package/src/autoconscience/experiments/common.js +76 -0
- package/src/autoconscience/experiments/execution.js +33 -0
- package/src/autoconscience/experiments/holdout.js +88 -0
- package/src/autoconscience/experiments/laboratory.js +99 -0
- package/src/autoconscience/experiments/replay.js +113 -0
- package/src/autoconscience/experiments/runner.js +54 -0
- package/src/autoconscience/experiments/sandbox.js +58 -0
- package/src/autoconscience/index.d.ts +203 -0
- package/src/autoconscience/index.js +116 -0
- package/src/autoconscience/lessons.js +32 -0
- package/src/autoconscience/shadow/candidate.js +69 -0
- package/src/autoconscience/shadow/index.d.ts +169 -0
- package/src/autoconscience/shadow/index.js +11 -0
- package/src/autoconscience/shadow/report.js +125 -0
- package/src/autoconscience/shadow/runner.js +384 -0
- package/src/autoconscience/shadow/store.js +98 -0
- package/src/autoconscience/signals.js +88 -0
- package/src/autoconscience/statistics.js +84 -0
- package/src/autoconscience/vigilance/abstention.js +123 -0
- package/src/autoconscience/vigilance/adversary.js +145 -0
- package/src/autoconscience/vigilance/common.js +56 -0
- package/src/autoconscience/vigilance/drift.js +306 -0
- package/src/autoconscience/vigilance/followups.js +100 -0
- package/src/autoconscience/vigilance/index.d.ts +190 -0
- package/src/autoconscience/vigilance/index.js +23 -0
- package/src/autoconscience/vigilance/lessonTests.js +40 -0
- package/src/autoconscience/vigilance/library.js +162 -0
- package/src/autoconscience/vigilance/roles.js +122 -0
- package/src/autoconscience/vigilance/store.js +166 -0
- package/src/conscience.js +559 -0
- package/src/diff.js +27 -0
- package/src/errors.js +11 -0
- package/src/governor/approvals.js +132 -0
- package/src/governor/changes.js +269 -0
- package/src/governor/governor.js +286 -0
- package/src/governor/index.d.ts +385 -0
- package/src/governor/index.js +22 -0
- package/src/governor/policy.js +136 -0
- package/src/governor/postgres.js +243 -0
- package/src/governor/remote.js +305 -0
- package/src/governor/review.js +191 -0
- package/src/governor/rollout.js +66 -0
- package/src/governor/stores.js +136 -0
- package/src/governor/util.js +53 -0
- package/src/guard.js +21 -0
- package/src/index.d.ts +244 -0
- package/src/index.js +23 -0
- package/src/memoryStore.js +65 -0
- package/src/postgres.js +93 -0
- package/src/records.js +220 -0
|
@@ -0,0 +1,559 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
const { ConscienceError } = require('./errors');
|
|
3
|
+
const { normalize, scopeOf, KINDS } = require('./records');
|
|
4
|
+
const { wordDelta } = require('./diff');
|
|
5
|
+
const { createMemoryConscienceStore } = require('./memoryStore');
|
|
6
|
+
const { assertGovernorReady, isGovernor } = require('./governor/governor');
|
|
7
|
+
const { fingerprintOf, copy, isNonEmptyString, GovernorError } = require('./governor/util');
|
|
8
|
+
|
|
9
|
+
const { oppositeLessons, assessedLessonStatus } = require('./autoconscience/lessons');
|
|
10
|
+
const { minimum } = require('./autoconscience/statistics');
|
|
11
|
+
const PAGE = 1000;
|
|
12
|
+
const ERASURE_MODES = Object.freeze(['delete', 'anonymise']);
|
|
13
|
+
const INTERNAL_EVIDENCE = Object.freeze(['decision', 'prediction', 'outcome', 'correction']);
|
|
14
|
+
|
|
15
|
+
function maskerOf(masker) {
|
|
16
|
+
if (typeof masker === 'function') return masker;
|
|
17
|
+
if (masker && typeof masker.redactString === 'function') return (text) => masker.redactString(text);
|
|
18
|
+
if (masker && typeof masker.mask === 'function') return (text) => masker.mask(text);
|
|
19
|
+
throw new ConscienceError('masker_required', 'A masker is required: a function (text) => masked text, a redactor of @astratra/privacy, or an object with mask(text).');
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function retentionOf(retention = {}) {
|
|
23
|
+
const erasure = retention.erasure ?? 'delete';
|
|
24
|
+
if (!ERASURE_MODES.includes(erasure)) throw new ConscienceError('invalid_input', 'retention.erasure must be "delete" or "anonymise".');
|
|
25
|
+
const maxAgeDays = { ...(retention.maxAgeDays ?? {}) };
|
|
26
|
+
for (const [kind, days] of Object.entries(maxAgeDays)) {
|
|
27
|
+
if (!KINDS.includes(kind)) throw new ConscienceError('invalid_input', `retention.maxAgeDays: unknown kind "${kind}".`);
|
|
28
|
+
if (typeof days !== 'number' || !Number.isFinite(days) || days <= 0) throw new ConscienceError('invalid_input', `retention.maxAgeDays.${kind} must be a positive number of days.`);
|
|
29
|
+
}
|
|
30
|
+
return Object.freeze({ erasure, maxAgeDays: Object.freeze(maxAgeDays) });
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Revision bookkeeping: number, current flag and when a later revision replaced it. */
|
|
34
|
+
function withRevisions(envelopes, groupOf) {
|
|
35
|
+
const groups = new Map();
|
|
36
|
+
for (const envelope of envelopes) {
|
|
37
|
+
const key = groupOf(envelope);
|
|
38
|
+
if (!groups.has(key)) groups.set(key, []);
|
|
39
|
+
groups.get(key).push(envelope);
|
|
40
|
+
}
|
|
41
|
+
const out = [];
|
|
42
|
+
for (const list of groups.values()) {
|
|
43
|
+
list.forEach((envelope, index) => {
|
|
44
|
+
const next = list[index + 1];
|
|
45
|
+
out.push({ ...envelope.data, revision: index + 1, current: !next, supersededAt: next ? next.recordedAt : null });
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
return out;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Conscience (P1): the documented memory of an agent's decisions. Records
|
|
53
|
+
* decisions, predictions, outcomes, corrections, lessons and self-model
|
|
54
|
+
* snapshots; isolates every read and write by organisation (and person);
|
|
55
|
+
* keeps every revision; erases a person completely.
|
|
56
|
+
*/
|
|
57
|
+
function createConscience(options = {}) {
|
|
58
|
+
if (options.governor == null) {
|
|
59
|
+
throw new GovernorError('governor_missing', 'No governor: conscience refuses to start without one (createGovernor(policy) from @astratra/conscience/governor).');
|
|
60
|
+
}
|
|
61
|
+
if (!isGovernor(options.governor)) {
|
|
62
|
+
throw new GovernorError('governor_invalid', 'governor must be built by createGovernor() from @astratra/conscience/governor.');
|
|
63
|
+
}
|
|
64
|
+
const governor = options.governor;
|
|
65
|
+
const mask = maskerOf(options.masker);
|
|
66
|
+
const store = options.store ?? createMemoryConscienceStore();
|
|
67
|
+
for (const method of ['put', 'get', 'list', 'replace', 'remove']) {
|
|
68
|
+
if (typeof store[method] !== 'function') throw new ConscienceError('store_invalid', `Conscience store is missing ${method}().`);
|
|
69
|
+
}
|
|
70
|
+
const now = options.now ?? Date.now;
|
|
71
|
+
const retention = retentionOf(options.retention);
|
|
72
|
+
const minimumSample = minimum(options.minimumSample);
|
|
73
|
+
const erasers = options.erasers ?? [];
|
|
74
|
+
if (!Array.isArray(erasers) || !erasers.every((fn) => typeof fn === 'function')) throw new ConscienceError('invalid_input', 'erasers must be an array of functions.');
|
|
75
|
+
const iso = () => new Date(now()).toISOString();
|
|
76
|
+
|
|
77
|
+
async function emit(event) {
|
|
78
|
+
try { await options.onEvent?.({ type: 'conscience', ...event }); } catch (_error) { /* Observers never change a record. */ }
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
async function maskText(value) {
|
|
82
|
+
if (value == null) return value;
|
|
83
|
+
const masked = await mask(String(value));
|
|
84
|
+
if (typeof masked !== 'string') throw new ConscienceError('masker_invalid', 'The masker must return a string.');
|
|
85
|
+
return masked;
|
|
86
|
+
}
|
|
87
|
+
async function maskDeep(value, depth = 0) {
|
|
88
|
+
if (typeof value === 'string') return maskText(value);
|
|
89
|
+
if (depth > 32 || value == null || typeof value !== 'object') return value;
|
|
90
|
+
if (Array.isArray(value)) return Promise.all(value.map((item) => maskDeep(item, depth + 1)));
|
|
91
|
+
const out = {};
|
|
92
|
+
for (const [key, child] of Object.entries(value)) out[key] = await maskDeep(child, depth + 1);
|
|
93
|
+
return out;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const organisationOf = (input) => governor.assertSingleOrganisation(scopeOf(input).organisationId);
|
|
97
|
+
const visible = (envelope, scope) => Boolean(envelope) && envelope.organisationId === scope.organisationId
|
|
98
|
+
&& (scope.userId == null || envelope.userId === scope.userId);
|
|
99
|
+
const readScope = (scope) => { const s = scopeOf(scope); governor.assertSingleOrganisation(s.organisationId); return s; };
|
|
100
|
+
const idOf = (input, prefix, fingerprint) => {
|
|
101
|
+
if (input.id == null) return `${prefix}_${fingerprint.slice(0, 32)}`;
|
|
102
|
+
if (!isNonEmptyString(input.id) || input.id.length > 500) throw new ConscienceError('invalid_input', 'id must be a non-empty string of at most 500 characters.');
|
|
103
|
+
return input.id;
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
async function put(envelope) {
|
|
107
|
+
const { record, created } = await store.put(envelope);
|
|
108
|
+
if (!created && record.fingerprint !== envelope.fingerprint) throw new ConscienceError('conflict', `A different ${envelope.kind} already uses the id "${envelope.id}". Records are immutable: record a revision instead.`);
|
|
109
|
+
if (created) await emit({ action: 'recorded', kind: envelope.kind, id: envelope.id, organisationId: envelope.organisationId });
|
|
110
|
+
return { record, created };
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
function envelopeOf(kind, data, fields) {
|
|
114
|
+
return {
|
|
115
|
+
kind, id: data.revisionId ?? data.id, organisationId: data.organisationId, userId: data.userId ?? null,
|
|
116
|
+
agentId: fields.agentId ?? null, decisionId: fields.decisionId ?? null, lessonId: fields.lessonId ?? null,
|
|
117
|
+
eventAt: fields.eventAt ?? null, recordedAt: data.recordedAt, fingerprint: fields.fingerprint,
|
|
118
|
+
evidenceRefs: fields.evidenceRefs ?? [], data
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
async function decisionIn(organisationId, decisionId) {
|
|
123
|
+
const found = await store.get('decision', organisationId, decisionId);
|
|
124
|
+
if (!found) throw new ConscienceError('not_found', 'Decision not found.');
|
|
125
|
+
return found;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
async function listAll(kind, filter) {
|
|
129
|
+
return store.list(kind, { ...filter, limit: filter.limit ?? 10000 });
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/* ---------- active mode: decisions, predictions, outcomes, corrections ---------- */
|
|
133
|
+
|
|
134
|
+
async function recordDecision(input) {
|
|
135
|
+
const n = normalize.decision(input);
|
|
136
|
+
organisationOf(n);
|
|
137
|
+
const fingerprint = fingerprintOf({ kind: 'decision', ...n });
|
|
138
|
+
const id = idOf(input, 'dec', fingerprint);
|
|
139
|
+
const data = {
|
|
140
|
+
id, ...n,
|
|
141
|
+
objective: await maskText(n.objective),
|
|
142
|
+
context: { at: n.context.at, summary: await maskText(n.context.summary), data: await maskDeep(n.context.data) },
|
|
143
|
+
action: { ...n.action, input: await maskDeep(n.action.input) },
|
|
144
|
+
alternatives: await maskDeep(n.alternatives),
|
|
145
|
+
expectedOutcome: await maskDeep(n.expectedOutcome),
|
|
146
|
+
recordedAt: iso()
|
|
147
|
+
};
|
|
148
|
+
const { record, created } = await put(envelopeOf('decision', data, { agentId: n.agentId, decisionId: id, eventAt: n.decidedAt, fingerprint }));
|
|
149
|
+
return { decision: record.data, created };
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
async function recordPrediction(input) {
|
|
153
|
+
const n = normalize.prediction(input);
|
|
154
|
+
organisationOf(n);
|
|
155
|
+
const decision = await decisionIn(n.organisationId, n.decisionId);
|
|
156
|
+
const fingerprint = fingerprintOf({ kind: 'prediction', ...n });
|
|
157
|
+
const id = idOf(input, 'pred', fingerprint);
|
|
158
|
+
const data = { id, ...n, domain: n.domain ?? decision.data.domain ?? 'general', userId: n.userId ?? decision.userId, agentId: decision.agentId, statement: await maskText(n.statement), recordedAt: iso() };
|
|
159
|
+
data.madeAt = n.madeAt ?? data.recordedAt;
|
|
160
|
+
const { record, created } = await put(envelopeOf('prediction', data, { agentId: decision.agentId, decisionId: n.decisionId, eventAt: data.madeAt, fingerprint }));
|
|
161
|
+
return { prediction: record.data, created };
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
async function attachOutcome(input) {
|
|
165
|
+
const n = normalize.outcome(input);
|
|
166
|
+
organisationOf(n);
|
|
167
|
+
const decision = await decisionIn(n.organisationId, n.decisionId);
|
|
168
|
+
if (n.predictionId) {
|
|
169
|
+
const prediction = await store.get('prediction', n.organisationId, n.predictionId);
|
|
170
|
+
if (!prediction || prediction.decisionId !== n.decisionId) throw new ConscienceError('not_found', 'Prediction not found for this decision.');
|
|
171
|
+
}
|
|
172
|
+
const fingerprint = fingerprintOf({ kind: 'outcome', ...n });
|
|
173
|
+
const id = idOf(input, 'out', fingerprint);
|
|
174
|
+
const existing = await store.get('outcome', n.organisationId, id);
|
|
175
|
+
const previous = existing ? null : (await store.list('outcome', { organisationId: n.organisationId, decisionId: n.decisionId, order: 'desc', limit: 10000 }))
|
|
176
|
+
.find((envelope) => envelope.data.sensor === n.sensor) ?? null;
|
|
177
|
+
const data = {
|
|
178
|
+
id, ...n, userId: n.userId ?? decision.userId, agentId: decision.agentId,
|
|
179
|
+
observation: await maskText(n.observation), confounders: await maskDeep(n.confounders),
|
|
180
|
+
revises: previous ? previous.id : null, recordedAt: iso()
|
|
181
|
+
};
|
|
182
|
+
const { record, created } = await put(envelopeOf('outcome', data, { agentId: decision.agentId, decisionId: n.decisionId, eventAt: n.observedAt, fingerprint }));
|
|
183
|
+
const versions = await getOutcomes({ organisationId: n.organisationId }, n.decisionId);
|
|
184
|
+
const self = versions.find((version) => version.id === record.id);
|
|
185
|
+
return { outcome: self ?? record.data, created };
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
async function recordCorrection(input) {
|
|
189
|
+
const n = normalize.correction(input);
|
|
190
|
+
organisationOf(n);
|
|
191
|
+
const decision = await decisionIn(n.organisationId, n.decisionId);
|
|
192
|
+
const fingerprint = fingerprintOf({ kind: 'correction', ...n });
|
|
193
|
+
const id = idOf(input, 'cor', fingerprint);
|
|
194
|
+
const delta = wordDelta(await maskText(n.proposed), await maskText(n.final));
|
|
195
|
+
const data = {
|
|
196
|
+
id, organisationId: n.organisationId, userId: n.userId ?? decision.userId, agentId: decision.agentId, decisionId: n.decisionId,
|
|
197
|
+
class: n.class, authorRole: n.authorRole, correctedAt: n.correctedAt, delta, recordedAt: iso()
|
|
198
|
+
};
|
|
199
|
+
const { record, created } = await put(envelopeOf('correction', data, { agentId: decision.agentId, decisionId: n.decisionId, eventAt: n.correctedAt, fingerprint }));
|
|
200
|
+
return { correction: record.data, created };
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/* ---------- reflective writes: lessons and self-model (governor required) ---------- */
|
|
204
|
+
|
|
205
|
+
async function appendRevision(kind, content, chain, prefix, fields) {
|
|
206
|
+
const contentFingerprint = fingerprintOf({ kind, ...content.raw });
|
|
207
|
+
const latest = (await store.list(kind, { organisationId: content.raw.organisationId, ...chain, order: 'desc', limit: 1 }))[0];
|
|
208
|
+
if (latest && latest.data.contentFingerprint === contentFingerprint) return { record: latest, created: false };
|
|
209
|
+
const fingerprint = fingerprintOf({ contentFingerprint, previous: latest ? latest.id : null });
|
|
210
|
+
const data = { ...content.data, revisionId: `${prefix}#${fingerprint.slice(0, 20)}`, contentFingerprint, previousRevision: latest ? latest.id : null, recordedAt: iso() };
|
|
211
|
+
await assertGovernorReady(governor, { organisationId: content.raw.organisationId });
|
|
212
|
+
return put(envelopeOf(kind, data, { ...fields(data), fingerprint }));
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
async function lessonSample(n, { strict = true, asOf } = {}) {
|
|
216
|
+
const decisions = new Set();
|
|
217
|
+
let factualEligible = true;
|
|
218
|
+
for (const item of n.evidence) {
|
|
219
|
+
if (!INTERNAL_EVIDENCE.includes(item.kind)) continue;
|
|
220
|
+
const found = await store.get(item.kind, n.organisationId, item.ref);
|
|
221
|
+
if (!found || (asOf != null && found.recordedAt > new Date(asOf).toISOString()) || (n.userId != null && found.userId !== n.userId)) {
|
|
222
|
+
if (strict) throw new ConscienceError('evidence_not_found', 'Evidence not found in this scope.');
|
|
223
|
+
continue;
|
|
224
|
+
}
|
|
225
|
+
if (n.agentId != null && found.agentId !== n.agentId) continue;
|
|
226
|
+
const decision = await store.get('decision', n.organisationId, found.decisionId);
|
|
227
|
+
if (!decision || (decision.data.domain ?? 'general') !== n.domain) continue;
|
|
228
|
+
if (item.kind === 'correction') {
|
|
229
|
+
if (found.data.class !== 'factual') { if (n.factual) factualEligible = false; continue; }
|
|
230
|
+
if (!found.data.delta?.unchanged) decisions.add(found.decisionId);
|
|
231
|
+
}
|
|
232
|
+
if (item.kind === 'outcome' && found.data.status !== 'unknown') {
|
|
233
|
+
const current = (await getOutcomes({ organisationId: n.organisationId, asOf }, found.decisionId)).find((o) => o.id === found.id);
|
|
234
|
+
if (current?.current) decisions.add(found.decisionId);
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
return { sampleSize: decisions.size, factualEligible };
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
async function persistLesson(n, requested) {
|
|
241
|
+
await assertGovernorReady(governor, { organisationId: n.organisationId });
|
|
242
|
+
const sample = await lessonSample(n);
|
|
243
|
+
n = { ...n, ...sample };
|
|
244
|
+
if (n.status !== 'retired') n.status = assessedLessonStatus(n, { minimumSample: Math.max(minimumSample, n.minimumSample) });
|
|
245
|
+
if (!n.evidence.length) n.evidenceDegree = 'none';
|
|
246
|
+
const lessonId = n.lessonId;
|
|
247
|
+
const raw = { ...n, lessonId };
|
|
248
|
+
const data = { id: lessonId, ...n, summary: await maskText(n.summary),
|
|
249
|
+
evidence: await Promise.all(n.evidence.map(async (item) => ({ ...item, note: await maskText(item.note) }))), statusForced: requested !== n.status };
|
|
250
|
+
delete data.lessonId;
|
|
251
|
+
const { record, created } = await appendRevision('lesson', { raw, data }, { lessonId }, lessonId, (d) => ({
|
|
252
|
+
agentId: n.agentId, lessonId, eventAt: d.validFrom ?? d.recordedAt, evidenceRefs: n.evidence.map((item) => item.ref)
|
|
253
|
+
}));
|
|
254
|
+
return { lesson: record.data, created, statusForced: record.data.statusForced };
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
async function recordLesson(input) {
|
|
258
|
+
const n = normalize.lesson({ minimumSample, ...input });
|
|
259
|
+
const organisationId = organisationOf(n);
|
|
260
|
+
await assertGovernorReady(governor, { organisationId });
|
|
261
|
+
n.lessonId ??= `lesson_${fingerprintOf({ organisationId, userId: n.userId, agentId: n.agentId, summary: n.summary }).slice(0, 32)}`;
|
|
262
|
+
const requested = n.status;
|
|
263
|
+
const current = await listLessons({ organisationId, userId: n.userId ?? undefined });
|
|
264
|
+
for (const ref of [...n.contradictions, ...n.supersedes]) {
|
|
265
|
+
if (!current.some((l) => l.id === ref)) throw new ConscienceError('not_found', 'Referenced lesson not found in this scope.');
|
|
266
|
+
}
|
|
267
|
+
// Open conflicts are symmetric. Retired opponents stay in history but cannot block verification.
|
|
268
|
+
const opposing = current.filter((l) => oppositeLessons({ ...n, id: n.lessonId }, l));
|
|
269
|
+
n.contradictions = [...new Set([...n.contradictions.filter((id) => current.some((l) => l.id === id && l.status !== 'retired')), ...opposing.map((l) => l.id)])];
|
|
270
|
+
const result = await persistLesson(n, requested);
|
|
271
|
+
for (const other of opposing) {
|
|
272
|
+
await persistLesson(normalize.lesson({ ...other, lessonId: other.id, status: 'to_reassess', contradictions: [...new Set([...other.contradictions, n.lessonId])] }), other.status);
|
|
273
|
+
}
|
|
274
|
+
return result;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** Explicit evidence-based arbitration; preserves every earlier revision. */
|
|
278
|
+
async function resolveLessonConflict(input) {
|
|
279
|
+
const s = readScope(input);
|
|
280
|
+
await assertGovernorReady(governor, s);
|
|
281
|
+
const winner = (await getLesson(s, input.winnerId))?.current;
|
|
282
|
+
const loser = (await getLesson(s, input.loserId))?.current;
|
|
283
|
+
if (!winner || !loser) throw new ConscienceError('not_found', 'Conflict lessons not found.');
|
|
284
|
+
if (!oppositeLessons(winner, loser)) throw new ConscienceError('invalid_input', 'No opposite lessons in this scope and domain.');
|
|
285
|
+
const evidence = input.evidence ?? [];
|
|
286
|
+
if (!evidence.length) throw new ConscienceError('invalid_input', 'Arbitration requires new evidence.');
|
|
287
|
+
const candidate = normalize.lesson({ ...winner, lessonId: winner.id, evidence, contradictions: [] });
|
|
288
|
+
const sample = await lessonSample(candidate);
|
|
289
|
+
if (assessedLessonStatus({ ...candidate, ...sample }, { minimumSample: Math.max(minimumSample, candidate.minimumSample) }) !== 'verified') {
|
|
290
|
+
throw new ConscienceError('insufficient_evidence', 'Arbitration requires sufficient factual evidence in the same domain.');
|
|
291
|
+
}
|
|
292
|
+
const retired = await recordLesson({ ...loser, lessonId: loser.id, status: 'retired' });
|
|
293
|
+
const resolved = await recordLesson({ ...winner, lessonId: winner.id, evidence, status: 'verified', contradictions: winner.contradictions.filter((id) => id !== loser.id), supersedes: [...new Set([...winner.supersedes, loser.id])] });
|
|
294
|
+
return { winner: resolved.lesson, loser: retired.lesson };
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
async function updateSelfModel(input) {
|
|
298
|
+
const n = normalize.self_model(input);
|
|
299
|
+
const organisationId = organisationOf(n);
|
|
300
|
+
await assertGovernorReady(governor, { organisationId });
|
|
301
|
+
const data = { id: `self_${n.agentId}`, ...n };
|
|
302
|
+
const { record, created } = await appendRevision('self_model', { raw: n, data }, { agentId: n.agentId }, `self_${n.agentId}`, (d) => ({
|
|
303
|
+
agentId: n.agentId, eventAt: d.at ?? d.recordedAt
|
|
304
|
+
}));
|
|
305
|
+
return { snapshot: { ...record.data, at: record.data.at ?? record.data.recordedAt }, created };
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/* ---------- reads ---------- */
|
|
309
|
+
|
|
310
|
+
async function getDecision(scope, id) {
|
|
311
|
+
const s = readScope(scope);
|
|
312
|
+
const found = await store.get('decision', s.organisationId, id);
|
|
313
|
+
return visible(found, s) ? found.data : null;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
async function getOutcomes(scope, decisionId) {
|
|
317
|
+
const s = readScope(scope);
|
|
318
|
+
if (!(await getDecision(s, decisionId))) return [];
|
|
319
|
+
const list = await listAll('outcome', { organisationId: s.organisationId, decisionId, recordedTo: scope.asOf ? new Date(scope.asOf).toISOString() : undefined });
|
|
320
|
+
return withRevisions(list.filter((envelope) => visible(envelope, s)), (envelope) => envelope.data.sensor);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
async function recallDecisions(scope, query = {}) {
|
|
324
|
+
const s = readScope(scope);
|
|
325
|
+
const filter = { organisationId: s.organisationId, limit: Math.min(Math.max(Number(query.limit) || 100, 1), 1000), order: query.order === 'asc' ? 'asc' : 'desc' };
|
|
326
|
+
if (s.userId != null) filter.userId = s.userId;
|
|
327
|
+
if (query.agentId != null) filter.agentId = query.agentId;
|
|
328
|
+
if (query.from != null) filter.eventFrom = new Date(query.from).toISOString();
|
|
329
|
+
if (query.to != null) filter.eventTo = new Date(query.to).toISOString();
|
|
330
|
+
if (query.asOf != null) filter.recordedTo = new Date(query.asOf).toISOString();
|
|
331
|
+
const decisions = (await store.list('decision', filter)).filter((envelope) => visible(envelope, s)).map((envelope) => envelope.data);
|
|
332
|
+
if (!query.withOutcomes) return decisions;
|
|
333
|
+
return Promise.all(decisions.map(async (decision) => ({
|
|
334
|
+
...decision,
|
|
335
|
+
outcomes: (await getOutcomes({ ...s, asOf: query.asOf }, decision.id)).filter((outcome) => outcome.current)
|
|
336
|
+
})));
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
async function lessonsCurrent(s, filter = {}) {
|
|
340
|
+
const query = { organisationId: s.organisationId };
|
|
341
|
+
if (s.userId != null) query.userId = s.userId;
|
|
342
|
+
if (filter.agentId != null) query.agentId = filter.agentId;
|
|
343
|
+
if (filter.lessonId != null) query.lessonId = filter.lessonId;
|
|
344
|
+
if (filter.evidenceRef != null) query.evidenceRef = filter.evidenceRef;
|
|
345
|
+
if (filter.asOf != null) query.recordedTo = new Date(filter.asOf).toISOString();
|
|
346
|
+
let envelopes = await listAll('lesson', query);
|
|
347
|
+
if (filter.evidenceRef != null) {
|
|
348
|
+
const ids = [...new Set(envelopes.map((envelope) => envelope.lessonId))];
|
|
349
|
+
envelopes = [];
|
|
350
|
+
for (const lessonId of ids) envelopes.push(...await listAll('lesson', { ...query, evidenceRef: undefined, lessonId }));
|
|
351
|
+
}
|
|
352
|
+
return withRevisions(envelopes.filter((envelope) => visible(envelope, s)), (envelope) => envelope.lessonId);
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
async function getLesson(scope, lessonId, { asOf } = {}) {
|
|
356
|
+
const s = readScope(scope);
|
|
357
|
+
const history = await lessonsCurrent(s, { lessonId, asOf });
|
|
358
|
+
if (!history.length) return null;
|
|
359
|
+
const current = (await assessedLessons(s, history.filter((l) => l.current), { asOf }))[0];
|
|
360
|
+
return { current, history };
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
async function assessedLessons(scope, selected, { asOf } = {}) {
|
|
364
|
+
const all = (await lessonsCurrent(scope, { asOf })).filter((l) => l.current);
|
|
365
|
+
const assessed = [];
|
|
366
|
+
for (const l of selected) {
|
|
367
|
+
const sample = await lessonSample({ ...l, minimumSample: l.minimumSample ?? minimumSample }, { strict: false, asOf });
|
|
368
|
+
const contradictions = [...new Set([...(l.contradictions ?? []).filter((id) => all.some((other) => other.id === id && other.status !== 'retired')),
|
|
369
|
+
...all.filter((other) => oppositeLessons(l, other)).map((other) => other.id)])];
|
|
370
|
+
const status = l.status === 'retired' ? 'retired' : assessedLessonStatus({ ...l, ...sample, contradictions }, { minimumSample: Math.max(minimumSample, l.minimumSample ?? minimumSample) });
|
|
371
|
+
assessed.push({ ...l, ...sample, contradictions, storedStatus: l.status, status });
|
|
372
|
+
}
|
|
373
|
+
return assessed;
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
async function listLessons(scope, filter = {}) {
|
|
377
|
+
const s = readScope(scope);
|
|
378
|
+
const at = filter.validAt != null ? new Date(filter.validAt).toISOString() : null;
|
|
379
|
+
const current = (await lessonsCurrent(s, filter)).filter((l) => l.current);
|
|
380
|
+
return (await assessedLessons(s, current, { asOf: filter.asOf })).filter((lesson) => (filter.status == null || lesson.status === filter.status)
|
|
381
|
+
&& (at == null || ((lesson.validFrom == null || lesson.validFrom <= at) && (lesson.validUntil == null || at < lesson.validUntil))));
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
async function getSelfModel(scope, agentId, { asOf } = {}) {
|
|
385
|
+
const s = readScope(scope);
|
|
386
|
+
const filter = { organisationId: s.organisationId, agentId, order: 'desc', limit: 1 };
|
|
387
|
+
if (asOf != null) filter.recordedTo = new Date(asOf).toISOString();
|
|
388
|
+
const latest = (await store.list('self_model', filter))[0];
|
|
389
|
+
return latest ? { ...latest.data, at: latest.data.at ?? latest.data.recordedAt } : null;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
async function getSelfModelHistory(scope, agentId) {
|
|
393
|
+
const s = readScope(scope);
|
|
394
|
+
const list = await listAll('self_model', { organisationId: s.organisationId, agentId });
|
|
395
|
+
return withRevisions(list, () => agentId);
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
async function getMemoryTimeline(scope, query = {}) {
|
|
399
|
+
const s = readScope(scope);
|
|
400
|
+
const axis = query.axis === 'recorded' ? 'recorded' : 'event';
|
|
401
|
+
const kinds = query.kinds ?? KINDS;
|
|
402
|
+
const from = query.from != null ? new Date(query.from).toISOString() : null;
|
|
403
|
+
const to = query.to != null ? new Date(query.to).toISOString() : null;
|
|
404
|
+
const validAt = query.validAt != null ? new Date(query.validAt).toISOString() : null;
|
|
405
|
+
const base = { organisationId: s.organisationId };
|
|
406
|
+
if (s.userId != null) base.userId = s.userId;
|
|
407
|
+
if (query.agentId != null) base.agentId = query.agentId;
|
|
408
|
+
if (query.asOf != null) base.recordedTo = new Date(query.asOf).toISOString();
|
|
409
|
+
const entries = [];
|
|
410
|
+
for (const kind of kinds) {
|
|
411
|
+
if (!KINDS.includes(kind)) throw new ConscienceError('invalid_input', `Unknown kind "${kind}".`);
|
|
412
|
+
const envelopes = (await listAll(kind, base)).filter((envelope) => visible(envelope, s));
|
|
413
|
+
const byId = new Map(envelopes.map((e) => [e.id, e]));
|
|
414
|
+
const groupOf = kind === 'outcome' ? (e) => `${e.decisionId}\u0000${e.data.sensor}` : kind === 'lesson' ? (e) => e.lessonId : kind === 'self_model' ? (e) => e.agentId : (e) => e.id;
|
|
415
|
+
for (const record of withRevisions(envelopes, groupOf)) {
|
|
416
|
+
const envelope = byId.get(record.revisionId ?? record.id);
|
|
417
|
+
const validFrom = kind === 'lesson' ? record.validFrom : kind === 'outcome' ? record.observedAt : envelope.eventAt;
|
|
418
|
+
const validUntil = kind === 'lesson' ? record.validUntil : kind === 'prediction' ? record.resolvesBy : null;
|
|
419
|
+
entries.push({
|
|
420
|
+
kind, id: record.id, revisionId: record.revisionId ?? null, revision: record.revision, current: record.current,
|
|
421
|
+
decisionId: envelope.decisionId, eventAt: envelope.eventAt, recordedAt: envelope.recordedAt,
|
|
422
|
+
validFrom: validFrom ?? null, validUntil: validUntil ?? null, supersededAt: record.supersededAt,
|
|
423
|
+
status: record.status ?? null
|
|
424
|
+
});
|
|
425
|
+
}
|
|
426
|
+
}
|
|
427
|
+
const timeOf = (entry) => (axis === 'event' ? entry.eventAt : entry.recordedAt);
|
|
428
|
+
return entries
|
|
429
|
+
.filter((entry) => (from == null || (timeOf(entry) != null && timeOf(entry) >= from)) && (to == null || (timeOf(entry) != null && timeOf(entry) < to)))
|
|
430
|
+
.filter((entry) => validAt == null || ((entry.validFrom == null || entry.validFrom <= validAt) && (entry.validUntil == null || validAt < entry.validUntil)))
|
|
431
|
+
.sort((a, b) => ((timeOf(a) ?? '') < (timeOf(b) ?? '') ? -1 : (timeOf(a) ?? '') > (timeOf(b) ?? '') ? 1 : 0));
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
async function getLineage(scope, decisionId) {
|
|
435
|
+
const s = readScope(scope);
|
|
436
|
+
const decision = await getDecision(s, decisionId);
|
|
437
|
+
if (!decision) return null;
|
|
438
|
+
const related = async (kind) => (await listAll(kind, { organisationId: s.organisationId, decisionId })).filter((e) => visible(e, s));
|
|
439
|
+
const predictions = (await related('prediction')).map((e) => e.data);
|
|
440
|
+
const outcomes = await getOutcomes(s, decisionId);
|
|
441
|
+
const corrections = (await related('correction')).map((e) => e.data);
|
|
442
|
+
const refs = [decisionId, ...predictions.map((p) => p.id), ...outcomes.map((o) => o.id), ...corrections.map((c) => c.id)];
|
|
443
|
+
const lessons = new Map();
|
|
444
|
+
for (const ref of refs) {
|
|
445
|
+
for (const lesson of await lessonsCurrent(s, { evidenceRef: ref })) if (lesson.current) lessons.set(lesson.id, lesson);
|
|
446
|
+
}
|
|
447
|
+
return {
|
|
448
|
+
objective: decision.objective,
|
|
449
|
+
decision,
|
|
450
|
+
action: decision.action,
|
|
451
|
+
tools: decision.tools,
|
|
452
|
+
predictions,
|
|
453
|
+
outcomes,
|
|
454
|
+
corrections,
|
|
455
|
+
lessons: await assessedLessons(s, [...lessons.values()]),
|
|
456
|
+
chain: ['objective', 'action', 'tools', 'outcomes', 'corrections', 'lessons']
|
|
457
|
+
};
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
/* ---------- erasure and retention ---------- */
|
|
461
|
+
|
|
462
|
+
async function stripEvidence(organisationId, removedRefs) {
|
|
463
|
+
let updated = 0;
|
|
464
|
+
const touched = new Map();
|
|
465
|
+
for (const ref of removedRefs) {
|
|
466
|
+
for (const envelope of await listAll('lesson', { organisationId, evidenceRef: ref })) touched.set(envelope.id, envelope);
|
|
467
|
+
}
|
|
468
|
+
for (const envelope of touched.values()) {
|
|
469
|
+
const evidence = envelope.data.evidence.filter((item) => !removedRefs.has(item.ref));
|
|
470
|
+
const data = { ...envelope.data, evidence };
|
|
471
|
+
data.sampleSize = (await lessonSample({ ...data, minimumSample: data.minimumSample ?? minimumSample })).sampleSize;
|
|
472
|
+
if (data.status === 'verified' && data.sampleSize < Math.max(minimumSample, data.minimumSample ?? minimumSample)) data.status = 'hypothesis';
|
|
473
|
+
if (!evidence.length) { data.status = 'hypothesis'; data.evidenceDegree = 'none'; }
|
|
474
|
+
await store.replace({ ...envelope, evidenceRefs: evidence.map((item) => item.ref), data });
|
|
475
|
+
updated += 1;
|
|
476
|
+
}
|
|
477
|
+
return updated;
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
async function removeWhere(kind, filter, removedRefs) {
|
|
481
|
+
let total = 0;
|
|
482
|
+
for (;;) {
|
|
483
|
+
const page = await store.list(kind, { ...filter, limit: PAGE });
|
|
484
|
+
if (!page.length) return total;
|
|
485
|
+
const ids = page.map((envelope) => envelope.id);
|
|
486
|
+
for (const envelope of page) removedRefs.add(kind === 'lesson' ? envelope.lessonId : envelope.id);
|
|
487
|
+
const count = await store.remove(kind, filter.organisationId, ids);
|
|
488
|
+
total += count;
|
|
489
|
+
if (count === 0) return total;
|
|
490
|
+
}
|
|
491
|
+
}
|
|
492
|
+
|
|
493
|
+
async function eraseSubject(subject = {}) {
|
|
494
|
+
const { organisationId, userId } = scopeOf(subject);
|
|
495
|
+
governor.assertSingleOrganisation(organisationId);
|
|
496
|
+
if (!isNonEmptyString(userId)) throw new ConscienceError('invalid_input', 'eraseSubject needs organisationId and userId.');
|
|
497
|
+
const removed = { decisions: 0, predictions: 0, outcomes: 0, corrections: 0, lessons: 0 };
|
|
498
|
+
const removedRefs = new Set();
|
|
499
|
+
let anonymised = 0;
|
|
500
|
+
if (retention.erasure === 'anonymise') {
|
|
501
|
+
for (const kind of ['decision', 'prediction', 'outcome', 'correction', 'lesson']) {
|
|
502
|
+
for (const envelope of await listAll(kind, { organisationId, userId })) {
|
|
503
|
+
await store.replace({ ...envelope, userId: null, data: { ...envelope.data, userId: null, subjectErased: true } });
|
|
504
|
+
anonymised += 1;
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
} else {
|
|
508
|
+
const decisions = await listAll('decision', { organisationId, userId });
|
|
509
|
+
const decisionIds = decisions.map((envelope) => envelope.id);
|
|
510
|
+
for (const [kind, key] of [['prediction', 'predictions'], ['outcome', 'outcomes'], ['correction', 'corrections']]) {
|
|
511
|
+
removed[key] += await removeWhere(kind, { organisationId, userId }, removedRefs);
|
|
512
|
+
if (decisionIds.length) removed[key] += await removeWhere(kind, { organisationId, decisionIds }, removedRefs);
|
|
513
|
+
}
|
|
514
|
+
removed.decisions = await removeWhere('decision', { organisationId, userId }, removedRefs);
|
|
515
|
+
removed.lessons = await removeWhere('lesson', { organisationId, userId }, removedRefs);
|
|
516
|
+
}
|
|
517
|
+
const lessonsUpdated = removedRefs.size ? await stripEvidence(organisationId, removedRefs) : 0;
|
|
518
|
+
const extensions = [];
|
|
519
|
+
for (const eraser of erasers) {
|
|
520
|
+
const result = await eraser({ organisationId, userId });
|
|
521
|
+
extensions.push({ name: String(result?.name ?? 'extension'), count: Number(result?.count ?? 0) });
|
|
522
|
+
}
|
|
523
|
+
const report = { organisationId, mode: retention.erasure, removed, anonymised, lessonsUpdated, extensions, completedAt: iso() };
|
|
524
|
+
await emit({ action: 'erased', organisationId, removed: { ...removed }, anonymised, lessonsUpdated });
|
|
525
|
+
return report;
|
|
526
|
+
}
|
|
527
|
+
|
|
528
|
+
async function applyRetention({ organisationId } = {}) {
|
|
529
|
+
governor.assertSingleOrganisation(organisationId);
|
|
530
|
+
const removed = {};
|
|
531
|
+
const removedRefs = new Set();
|
|
532
|
+
for (const [kind, days] of Object.entries(retention.maxAgeDays)) {
|
|
533
|
+
const cutoff = new Date(now() - days * 86400000).toISOString();
|
|
534
|
+
removed[kind] = 0;
|
|
535
|
+
for (;;) {
|
|
536
|
+
const page = (await store.list(kind, { organisationId, recordedTo: cutoff, limit: PAGE })).filter((envelope) => envelope.recordedAt < cutoff);
|
|
537
|
+
if (!page.length) break;
|
|
538
|
+
for (const envelope of page) removedRefs.add(kind === 'lesson' ? envelope.lessonId : envelope.id);
|
|
539
|
+
const count = await store.remove(kind, organisationId, page.map((envelope) => envelope.id));
|
|
540
|
+
removed[kind] += count;
|
|
541
|
+
if (count === 0) break;
|
|
542
|
+
}
|
|
543
|
+
}
|
|
544
|
+
const lessonsUpdated = removedRefs.size ? await stripEvidence(organisationId, removedRefs) : 0;
|
|
545
|
+
await emit({ action: 'retention', organisationId, removed: { ...removed } });
|
|
546
|
+
return { organisationId, removed, lessonsUpdated, completedAt: iso() };
|
|
547
|
+
}
|
|
548
|
+
|
|
549
|
+
return Object.freeze({
|
|
550
|
+
store, governor, retention: copy(retention),
|
|
551
|
+
recordDecision, recordPrediction, attachOutcome, recordCorrection,
|
|
552
|
+
recordLesson, resolveLessonConflict, updateSelfModel,
|
|
553
|
+
getDecision, getOutcomes, recallDecisions, getLesson, listLessons, getSelfModel, getSelfModelHistory,
|
|
554
|
+
getMemoryTimeline, getLineage,
|
|
555
|
+
eraseSubject, applyRetention
|
|
556
|
+
});
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
module.exports = { createConscience, ERASURE_MODES };
|
package/src/diff.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const MAX_CHARS = 4000;
|
|
4
|
+
const words = (text) => String(text).split(/\s+/).filter(Boolean);
|
|
5
|
+
const bounded = (list) => { const text = list.join(' '); return text.length > MAX_CHARS ? `${text.slice(0, MAX_CHARS)}…` : text; };
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Difference between a proposed text and its final version, word by word:
|
|
9
|
+
* the common start and end are dropped and the middle parts kept. Linear in
|
|
10
|
+
* the length of the texts. Call it on MASKED texts only.
|
|
11
|
+
*/
|
|
12
|
+
function wordDelta(before, after) {
|
|
13
|
+
const a = words(before); const b = words(after);
|
|
14
|
+
let start = 0;
|
|
15
|
+
while (start < a.length && start < b.length && a[start] === b[start]) start += 1;
|
|
16
|
+
let endA = a.length; let endB = b.length;
|
|
17
|
+
while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) { endA -= 1; endB -= 1; }
|
|
18
|
+
const removed = a.slice(start, endA); const added = b.slice(start, endB);
|
|
19
|
+
return {
|
|
20
|
+
removed: bounded(removed), added: bounded(added),
|
|
21
|
+
removedWords: removed.length, addedWords: added.length,
|
|
22
|
+
totalWordsBefore: a.length, totalWordsAfter: b.length,
|
|
23
|
+
unchanged: removed.length === 0 && added.length === 0
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
module.exports = { wordDelta };
|