@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
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/*
|
|
3
|
+
* Lesson turned into a test (proposition 03). A VERIFIED lesson (P2: evidence,
|
|
4
|
+
* enough distinct decisions, no open conflict) becomes an anti-regression
|
|
5
|
+
* scenario in the format of evaluateAgent. A hypothesis, a lesson to reassess
|
|
6
|
+
* or a retired one is refused: a doubtful lesson must not become a test.
|
|
7
|
+
*
|
|
8
|
+
* The lesson says what was learned; how to check it is described by the caller
|
|
9
|
+
* (question, fixed tool results, expected and forbidden behaviour): nothing is
|
|
10
|
+
* invented. A scenario that asserts nothing is refused. The result is a
|
|
11
|
+
* candidate "to_review"; it enters the suite only after human approval at the
|
|
12
|
+
* governor (see createScenarioLibrary).
|
|
13
|
+
*/
|
|
14
|
+
const { ConscienceError } = require('../../errors');
|
|
15
|
+
const { ready, invalid, maskerOf, isNonEmptyString } = require('./common');
|
|
16
|
+
const { normalizeSpec, buildCandidate } = require('./library');
|
|
17
|
+
|
|
18
|
+
async function lessonToScenario(lesson, options = {}) {
|
|
19
|
+
const { governor, library } = options;
|
|
20
|
+
const organisationId = await ready(governor, options.organisationId ?? lesson?.organisationId);
|
|
21
|
+
if (!lesson || typeof lesson !== 'object' || !isNonEmptyString(lesson.id)) invalid('A lesson read from the conscience is required.');
|
|
22
|
+
governor.assertSingleOrganisation(organisationId, lesson.organisationId);
|
|
23
|
+
if (lesson.status !== 'verified') {
|
|
24
|
+
throw new ConscienceError('lesson_not_verified', `Only a verified lesson can become a test; this one is "${lesson.status}".`);
|
|
25
|
+
}
|
|
26
|
+
if (!Array.isArray(lesson.evidence) || !lesson.evidence.length) throw new ConscienceError('lesson_not_verified', 'A lesson without evidence cannot become a test.');
|
|
27
|
+
const mask = maskerOf(options.masker);
|
|
28
|
+
const spec = await normalizeSpec({
|
|
29
|
+
question: options.question, tools: options.tools, expect: options.expect,
|
|
30
|
+
forbiddenTools: options.forbiddenTools, forbiddenContent: options.forbiddenContent
|
|
31
|
+
}, { mask, allowRegex: true });
|
|
32
|
+
const candidate = buildCandidate({
|
|
33
|
+
organisationId, agentId: lesson.agentId ?? options.agentId ?? null, category: 'regression', source: 'lesson', spec, now: options.now ?? Date.now,
|
|
34
|
+
origin: { lessonId: lesson.id, revisionId: lesson.revisionId ?? null, domain: lesson.domain ?? null, evidence: lesson.evidence.map((e) => ({ kind: e.kind, ref: e.ref })) }
|
|
35
|
+
});
|
|
36
|
+
if (library) return (await library.submit([candidate], { organisationId, proposedBy: options.proposedBy }))[0].candidate;
|
|
37
|
+
return candidate;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
module.exports = { lessonToScenario };
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/*
|
|
3
|
+
* Candidate scenarios and their review (propositions 03 and 27).
|
|
4
|
+
*
|
|
5
|
+
* A candidate is plain data: `scenario` is a JSON description that `toScenario`
|
|
6
|
+
* turns into a scenario for evaluateAgent of @astratra/testkit (id, question,
|
|
7
|
+
* simulated tools, expect, score). Simulated tools return fixed data: they have
|
|
8
|
+
* no effect on anything. A candidate is born "to_review". It joins the test
|
|
9
|
+
* suite only through the library's approved() list, which retains a scenario
|
|
10
|
+
* only when the governor holds a proposal for exactly that scenario (same
|
|
11
|
+
* fingerprint) that humans approved. A model can propose; it cannot approve.
|
|
12
|
+
*/
|
|
13
|
+
const { ConscienceError } = require('../../errors');
|
|
14
|
+
const { fingerprintOf, copy } = require('../../governor/util');
|
|
15
|
+
const { ready, invalid, actorOf, maskerOf, maskText, maskDeep, isNonEmptyString } = require('./common');
|
|
16
|
+
const { VIGILANCE_STORE_METHODS } = require('./store');
|
|
17
|
+
|
|
18
|
+
const CATEGORIES = Object.freeze(['injection', 'ambiguity', 'edge_case', 'cross_organisation', 'regression']);
|
|
19
|
+
const REVIEW_STATUSES = Object.freeze(['to_review', 'approved', 'declined', 'rejected', 'expired']);
|
|
20
|
+
const LIMITS = Object.freeze({ question: 20000, text: 2000, items: 20 });
|
|
21
|
+
|
|
22
|
+
const stringList = (value, field, max = LIMITS.items) => {
|
|
23
|
+
if (value == null) return [];
|
|
24
|
+
if (!Array.isArray(value) || value.length > max || !value.every((v) => isNonEmptyString(v) && v.length <= LIMITS.text)) invalid(`${field} must be an array of at most ${max} non-empty strings.`);
|
|
25
|
+
return [...value];
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
function contentExpectation(item, allowRegex, field) {
|
|
29
|
+
if (typeof item === 'string' && item.length && item.length <= LIMITS.text) return item;
|
|
30
|
+
if (allowRegex && item instanceof RegExp && item.source.length <= 200) return { regex: item.source, flags: item.flags.replace(/[gy]/g, '') };
|
|
31
|
+
if (allowRegex && item && typeof item === 'object' && typeof item.regex === 'string' && item.regex.length <= 200) {
|
|
32
|
+
try { new RegExp(item.regex, item.flags ?? ''); } catch (_error) { invalid(`${field} holds an invalid regular expression.`); }
|
|
33
|
+
return { regex: item.regex, flags: String(item.flags ?? '').replace(/[gy]/g, '') };
|
|
34
|
+
}
|
|
35
|
+
return invalid(`${field} must hold ${allowRegex ? 'strings or regular expressions' : 'strings'}.`);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Validate and mask a scenario description. Everything textual passes through
|
|
40
|
+
* the masker, so no personal content reaches a stored test.
|
|
41
|
+
*/
|
|
42
|
+
async function normalizeSpec(raw, { mask, allowRegex = false } = {}) {
|
|
43
|
+
if (!raw || typeof raw !== 'object') invalid('A scenario description is required.');
|
|
44
|
+
if (!isNonEmptyString(raw.question) || raw.question.length > LIMITS.question) invalid('scenario.question must be a non-empty string.');
|
|
45
|
+
const tools = raw.tools ?? [];
|
|
46
|
+
if (!Array.isArray(tools) || tools.length > 10) invalid('scenario.tools must be an array of at most 10 simulated tools.');
|
|
47
|
+
const names = new Set();
|
|
48
|
+
const normalizedTools = [];
|
|
49
|
+
for (const tool of tools) {
|
|
50
|
+
if (!tool || !isNonEmptyString(tool.name) || tool.name.length > 200 || names.has(tool.name)) invalid('Each simulated tool needs a distinct name.');
|
|
51
|
+
if (typeof tool.run === 'function') invalid('A scenario description holds data, not functions: use { name, returns }.');
|
|
52
|
+
names.add(tool.name);
|
|
53
|
+
normalizedTools.push({ name: tool.name, returns: await maskDeep(mask, copy(tool.returns ?? null)) });
|
|
54
|
+
}
|
|
55
|
+
const expect = raw.expect ?? {};
|
|
56
|
+
const spec = {
|
|
57
|
+
question: await maskText(mask, raw.question),
|
|
58
|
+
tools: normalizedTools,
|
|
59
|
+
expect: {
|
|
60
|
+
tools: stringList(expect.tools, 'expect.tools'),
|
|
61
|
+
content: await Promise.all((expect.content ?? []).map(async (item, index) => {
|
|
62
|
+
const entry = contentExpectation(item, allowRegex, `expect.content[${index}]`);
|
|
63
|
+
return typeof entry === 'string' ? maskText(mask, entry) : entry;
|
|
64
|
+
}))
|
|
65
|
+
},
|
|
66
|
+
forbiddenTools: stringList(raw.forbiddenTools, 'forbiddenTools'),
|
|
67
|
+
forbiddenContent: await Promise.all(stringList(raw.forbiddenContent, 'forbiddenContent').map((text) => maskText(mask, text)))
|
|
68
|
+
};
|
|
69
|
+
if (spec.expect.content.length > LIMITS.items) invalid('expect.content holds too many items.');
|
|
70
|
+
return spec;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const hasAssertion = (spec) => spec.expect.tools.length + spec.expect.content.length + spec.forbiddenTools.length + spec.forbiddenContent.length > 0;
|
|
74
|
+
|
|
75
|
+
/** The scenario in the format of evaluateAgent: id, question, tools (fixed data), expect and a score. */
|
|
76
|
+
function toScenario(candidate) {
|
|
77
|
+
const spec = candidate.scenario;
|
|
78
|
+
const content = spec.expect.content.map((item) => (typeof item === 'string' ? item : new RegExp(item.regex, item.flags)));
|
|
79
|
+
const scenario = {
|
|
80
|
+
id: candidate.id,
|
|
81
|
+
question: spec.question,
|
|
82
|
+
tools: spec.tools.map((tool) => ({ name: tool.name, run: async () => copy(tool.returns) })),
|
|
83
|
+
expect: { tools: [...spec.expect.tools], content }
|
|
84
|
+
};
|
|
85
|
+
if (spec.forbiddenTools.length || spec.forbiddenContent.length) {
|
|
86
|
+
scenario.score = ({ text, calls, checks }) => {
|
|
87
|
+
if (calls.some((call) => spec.forbiddenTools.includes(call.name))) return 0;
|
|
88
|
+
if (spec.forbiddenContent.some((forbidden) => String(text).includes(forbidden))) return 0;
|
|
89
|
+
return checks.length ? checks.filter((check) => check.passed).length / checks.length : 1;
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
return scenario;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** A candidate, born "to_review". The fingerprint covers organisation, agent, category and the whole description. */
|
|
96
|
+
function buildCandidate({ organisationId, agentId = null, category, origin, source, spec, now }) {
|
|
97
|
+
if (!CATEGORIES.includes(category)) invalid(`category must be one of ${CATEGORIES.join(', ')}.`);
|
|
98
|
+
if (!hasAssertion(spec)) invalid('A scenario must assert something (expect or forbidden).');
|
|
99
|
+
const fingerprint = fingerprintOf({ organisationId, agentId, category, scenario: spec });
|
|
100
|
+
const id = `${category === 'regression' ? 'reg' : 'adv'}_${fingerprint.slice(0, 24)}`;
|
|
101
|
+
return {
|
|
102
|
+
id, organisationId, agentId, category, origin: copy(origin), source, status: 'to_review', addedToTests: false,
|
|
103
|
+
scenario: spec, fingerprint, proposalId: null, createdAt: new Date(now()).toISOString()
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function createScenarioLibrary(options = {}) {
|
|
108
|
+
const { governor, store } = options;
|
|
109
|
+
for (const method of VIGILANCE_STORE_METHODS) {
|
|
110
|
+
if (!store || typeof store[method] !== 'function') throw new ConscienceError('store_invalid', `Vigilance store is missing ${method}().`);
|
|
111
|
+
}
|
|
112
|
+
maskerOf(options.masker); // A masker is mandatory: candidates are masked when built, the library refuses to run without one.
|
|
113
|
+
const targetKind = options.targetKind ?? 'instructions';
|
|
114
|
+
|
|
115
|
+
const targetOf = (candidate) => ({ kind: targetKind, id: `scenarios:${candidate.agentId ?? 'all'}` });
|
|
116
|
+
|
|
117
|
+
async function submit(candidates, input = {}) {
|
|
118
|
+
const organisationId = await ready(governor, input.organisationId);
|
|
119
|
+
const proposedBy = actorOf(input.proposedBy, { kind: 'engine', id: 'scenario-library' });
|
|
120
|
+
const out = [];
|
|
121
|
+
for (const candidate of candidates) {
|
|
122
|
+
governor.assertSingleOrganisation(organisationId, candidate.organisationId);
|
|
123
|
+
const proposal = await governor.evaluatePolicy({
|
|
124
|
+
organisationId, target: targetOf(candidate),
|
|
125
|
+
change: { addScenario: { id: candidate.id, category: candidate.category, fingerprint: candidate.fingerprint }, reviewStatus: 'to_review' },
|
|
126
|
+
justification: { code: `${candidate.category}_scenario`, origin: candidate.origin }, risk: 'low', proposedBy
|
|
127
|
+
});
|
|
128
|
+
const { record, created } = await store.putCandidate({ ...candidate, proposalId: proposal.id });
|
|
129
|
+
out.push({ candidate: await withStatus(record), created, proposal });
|
|
130
|
+
}
|
|
131
|
+
return out;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
async function withStatus(candidate) {
|
|
135
|
+
const proposal = candidate.proposalId ? await governor.getProposal(candidate.organisationId, candidate.proposalId) : null;
|
|
136
|
+
const status = !proposal ? 'to_review' : proposal.status === 'pending_approval' ? 'to_review' : proposal.status;
|
|
137
|
+
const matches = proposal?.change?.addScenario?.fingerprint === candidate.fingerprint && proposal?.change?.addScenario?.id === candidate.id;
|
|
138
|
+
const intact = fingerprintOf({ organisationId: candidate.organisationId, agentId: candidate.agentId, category: candidate.category, scenario: candidate.scenario }) === candidate.fingerprint;
|
|
139
|
+
const humans = Array.isArray(proposal?.approvals) && proposal.approvals.length > 0 && proposal.approvals.every((a) => a.approver?.kind === 'human');
|
|
140
|
+
const approved = status === 'approved' && matches && intact && humans;
|
|
141
|
+
return { ...candidate, status: status === 'approved' && !approved ? 'rejected' : status, addedToTests: approved };
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
async function list(input = {}) {
|
|
145
|
+
const organisationId = await ready(governor, input.organisationId);
|
|
146
|
+
if (input.status != null && !REVIEW_STATUSES.includes(input.status)) invalid(`status must be one of ${REVIEW_STATUSES.join(', ')}.`);
|
|
147
|
+
const filter = { organisationId, limit: input.limit };
|
|
148
|
+
if (input.agentId !== undefined) filter.agentId = input.agentId;
|
|
149
|
+
const all = await Promise.all((await store.listCandidates(filter)).map(withStatus));
|
|
150
|
+
return all.filter((candidate) => input.status == null || candidate.status === input.status);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** The only way into the test suite: scenarios whose exact content humans approved at the governor. */
|
|
154
|
+
async function approved(input = {}) {
|
|
155
|
+
const found = await list({ ...input, status: 'approved' });
|
|
156
|
+
return found.filter((candidate) => candidate.addedToTests).map((candidate) => ({ candidate, scenario: toScenario(candidate) }));
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
return Object.freeze({ submit, list, approved, toScenario });
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
module.exports = { createScenarioLibrary, normalizeSpec, buildCandidate, toScenario, SCENARIO_CATEGORIES: CATEGORIES, CANDIDATE_STATUSES: REVIEW_STATUSES };
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/*
|
|
3
|
+
* Multi-role reflection (proposition 14). Three separate reviews of a finding,
|
|
4
|
+
* each a function injected by the application. This is not a vote and not a
|
|
5
|
+
* panel of models: the code applies three fixed conditions to three
|
|
6
|
+
* independent answers.
|
|
7
|
+
*
|
|
8
|
+
* verifier cites evidence INDEPENDENT of the finding's own evidence;
|
|
9
|
+
* contradictor lists competing explanations with a strength in [0, 1];
|
|
10
|
+
* none may be as strong as the finding's confidence;
|
|
11
|
+
* riskController approves the scope the finding asks to be applied to.
|
|
12
|
+
*
|
|
13
|
+
* The finding moves forward ("supported") only if all three conditions hold.
|
|
14
|
+
* Otherwise it stays a hypothesis. A role that fails, answers badly or is
|
|
15
|
+
* missing blocks the finding (fail closed). Roles see only a frozen copy of the
|
|
16
|
+
* finding, never each other's answers.
|
|
17
|
+
*/
|
|
18
|
+
const { fingerprintOf, deepFreeze, copy } = require('../../governor/util');
|
|
19
|
+
const { ready, invalid, actorOf, isNonEmptyString } = require('./common');
|
|
20
|
+
|
|
21
|
+
const SCOPES = Object.freeze(['observation', 'agent', 'domain', 'organisation']);
|
|
22
|
+
const ROLE_NAMES = Object.freeze(['verifier', 'contradictor', 'riskController']);
|
|
23
|
+
const EVIDENCE_KINDS = Object.freeze(['decision', 'prediction', 'outcome', 'correction', 'external']);
|
|
24
|
+
|
|
25
|
+
const fail = (role, code) => ({ role, passed: false, error: code, blockers: [`${role}_failed`] });
|
|
26
|
+
|
|
27
|
+
function judgeVerifier(result, finding, organisationId, ownRefs, minimumIndependent, verified) {
|
|
28
|
+
const items = Array.isArray(result?.evidence) ? result.evidence : Array.isArray(result) ? result : null;
|
|
29
|
+
if (!items) return fail('verifier', 'malformed_answer');
|
|
30
|
+
const independent = [], dropped = [];
|
|
31
|
+
const seen = new Set();
|
|
32
|
+
for (const item of items) {
|
|
33
|
+
if (!item || !EVIDENCE_KINDS.includes(item.kind) || !isNonEmptyString(item.ref)) { dropped.push({ ref: item?.ref ?? null, reason: 'malformed' }); continue; }
|
|
34
|
+
if (item.organisationId != null && item.organisationId !== organisationId) { dropped.push({ ref: item.ref, reason: 'cross_organisation' }); continue; }
|
|
35
|
+
if (ownRefs.has(item.ref)) { dropped.push({ ref: item.ref, reason: 'not_independent' }); continue; }
|
|
36
|
+
if (seen.has(`${item.kind}\u0000${item.ref}`)) continue;
|
|
37
|
+
seen.add(`${item.kind}\u0000${item.ref}`);
|
|
38
|
+
if (verified.get(`${item.kind}\u0000${item.ref}`) === false) { dropped.push({ ref: item.ref, reason: 'unverifiable' }); continue; }
|
|
39
|
+
independent.push({ kind: item.kind, ref: item.ref });
|
|
40
|
+
}
|
|
41
|
+
const passed = independent.length >= minimumIndependent;
|
|
42
|
+
return { role: 'verifier', passed, independentEvidence: independent, dropped, blockers: passed ? [] : ['no_independent_evidence'] };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function judgeContradictor(result, finding) {
|
|
46
|
+
const list = Array.isArray(result?.competing) ? result.competing : Array.isArray(result) ? result : null;
|
|
47
|
+
if (!list) return fail('contradictor', 'malformed_answer');
|
|
48
|
+
const explanations = [];
|
|
49
|
+
for (const item of list) {
|
|
50
|
+
if (!item || !isNonEmptyString(item.statement) || typeof item.strength !== 'number' || !Number.isFinite(item.strength) || item.strength < 0 || item.strength > 1) return fail('contradictor', 'malformed_answer');
|
|
51
|
+
explanations.push({ statement: item.statement, strength: item.strength });
|
|
52
|
+
}
|
|
53
|
+
const stronger = explanations.filter((e) => e.strength >= finding.confidence);
|
|
54
|
+
return { role: 'contradictor', passed: stronger.length === 0, competing: explanations, stronger, blockers: stronger.length ? ['competing_explanation_as_strong'] : [] };
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function judgeRisk(result, finding) {
|
|
58
|
+
if (!result || typeof result.approved !== 'boolean' || !SCOPES.includes(result.maxScope)) return fail('riskController', 'malformed_answer');
|
|
59
|
+
const blockers = [];
|
|
60
|
+
if (!result.approved) blockers.push('risk_not_approved');
|
|
61
|
+
else if (SCOPES.indexOf(result.maxScope) < SCOPES.indexOf(finding.requestedScope)) blockers.push('scope_too_broad');
|
|
62
|
+
return { role: 'riskController', passed: blockers.length === 0, approved: result.approved, maxScope: result.maxScope, requestedScope: finding.requestedScope, blockers };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
async function reviewByRoles(options = {}) {
|
|
66
|
+
const { governor, organisationId, roles } = options;
|
|
67
|
+
const org = await ready(governor, organisationId);
|
|
68
|
+
const source = options.finding;
|
|
69
|
+
if (!source || typeof source !== 'object' || !isNonEmptyString(source.id)) invalid('finding.id is required.');
|
|
70
|
+
if (source.organisationId != null) governor.assertSingleOrganisation(org, source.organisationId);
|
|
71
|
+
if (typeof source.confidence !== 'number' || !Number.isFinite(source.confidence) || source.confidence < 0 || source.confidence > 1) invalid('finding.confidence must be a number in [0, 1].');
|
|
72
|
+
const requestedScope = source.requestedScope ?? 'agent';
|
|
73
|
+
if (!SCOPES.includes(requestedScope)) invalid(`finding.requestedScope must be one of ${SCOPES.join(', ')}.`);
|
|
74
|
+
if (!roles || ROLE_NAMES.some((name) => typeof roles[name] !== 'function')) invalid(`roles must provide the functions ${ROLE_NAMES.join(', ')}.`);
|
|
75
|
+
if (new Set(ROLE_NAMES.map((name) => roles[name])).size !== ROLE_NAMES.length) invalid('The three roles must be three separate functions.');
|
|
76
|
+
const minimumIndependent = options.minimumIndependent ?? 1;
|
|
77
|
+
if (!Number.isInteger(minimumIndependent) || minimumIndependent < 1) invalid('minimumIndependent must be an integer >= 1.');
|
|
78
|
+
if (options.evidenceExists != null && typeof options.evidenceExists !== 'function') invalid('evidenceExists must be a function.');
|
|
79
|
+
|
|
80
|
+
const finding = { ...copy(source), organisationId: org, requestedScope };
|
|
81
|
+
const ownRefs = new Set([finding.id, ...(finding.decisionIds ?? []), ...(finding.evidence ?? []).map((e) => e.ref)]);
|
|
82
|
+
const answers = await Promise.allSettled(ROLE_NAMES.map(async (name) => {
|
|
83
|
+
options.signal?.throwIfAborted();
|
|
84
|
+
return roles[name](deepFreeze(copy(finding)), { organisationId: org, role: name, signal: options.signal });
|
|
85
|
+
}));
|
|
86
|
+
options.signal?.throwIfAborted();
|
|
87
|
+
|
|
88
|
+
const answered = (name) => answers[ROLE_NAMES.indexOf(name)];
|
|
89
|
+
const verifierAnswer = answered('verifier');
|
|
90
|
+
const verified = new Map();
|
|
91
|
+
if (verifierAnswer.status === 'fulfilled' && options.evidenceExists) {
|
|
92
|
+
const items = Array.isArray(verifierAnswer.value?.evidence) ? verifierAnswer.value.evidence : Array.isArray(verifierAnswer.value) ? verifierAnswer.value : [];
|
|
93
|
+
for (const item of items) {
|
|
94
|
+
if (!item || !EVIDENCE_KINDS.includes(item.kind) || !isNonEmptyString(item.ref) || ownRefs.has(item.ref)) continue;
|
|
95
|
+
let exists = false;
|
|
96
|
+
try { exists = (await options.evidenceExists({ kind: item.kind, ref: item.ref, organisationId: org })) === true; } catch (_error) { exists = false; }
|
|
97
|
+
verified.set(`${item.kind}\u0000${item.ref}`, exists);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
const reviews = {
|
|
101
|
+
verifier: verifierAnswer.status === 'fulfilled' ? judgeVerifier(verifierAnswer.value, finding, org, ownRefs, minimumIndependent, verified) : fail('verifier', 'role_error'),
|
|
102
|
+
contradictor: answered('contradictor').status === 'fulfilled' ? judgeContradictor(answered('contradictor').value, finding) : fail('contradictor', 'role_error'),
|
|
103
|
+
riskController: answered('riskController').status === 'fulfilled' ? judgeRisk(answered('riskController').value, finding) : fail('riskController', 'role_error')
|
|
104
|
+
};
|
|
105
|
+
const blockers = ROLE_NAMES.flatMap((name) => reviews[name].blockers);
|
|
106
|
+
const advances = blockers.length === 0;
|
|
107
|
+
const result = {
|
|
108
|
+
findingId: finding.id, organisationId: org, advances, status: advances ? 'supported' : 'hypothesis', blockers, reviews,
|
|
109
|
+
finding: { ...finding, status: advances ? 'supported' : 'hypothesis' }, recorded: null
|
|
110
|
+
};
|
|
111
|
+
if (options.recordedBy) {
|
|
112
|
+
result.recorded = await governor.recordFinding({
|
|
113
|
+
organisationId: org, runId: options.runId ?? null, code: advances ? 'review_passed' : 'review_blocked', severity: advances ? 'info' : 'low',
|
|
114
|
+
subject: { kind: 'finding', id: finding.id }, decisionIds: finding.decisionIds ?? [],
|
|
115
|
+
evidenceRefs: reviews.verifier.independentEvidence?.map((e) => e.ref) ?? [], confidence: finding.confidence,
|
|
116
|
+
metrics: { blockers: blockers.length, fingerprint: fingerprintOf({ id: finding.id, blockers }).slice(0, 16) }, recordedBy: actorOf(options.recordedBy)
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
return result;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
module.exports = { reviewByRoles, REVIEW_ROLES: ROLE_NAMES, REVIEW_SCOPES: SCOPES };
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/*
|
|
3
|
+
* Storage of the vigilance module: follow-up commitments (18) and candidate
|
|
4
|
+
* scenarios waiting for review (03, 27). A memory store and a PostgreSQL store
|
|
5
|
+
* with the same contract. Every read and write is scoped by organisation.
|
|
6
|
+
*/
|
|
7
|
+
const { copy, prefixOf, requireQueryable } = require('../../governor/util');
|
|
8
|
+
|
|
9
|
+
const MAX_LIMIT = 10000;
|
|
10
|
+
const limitOf = (value) => Math.min(Math.max(Number(value) || 1000, 1), MAX_LIMIT);
|
|
11
|
+
const DEFAULT_PREFIX = 'astratra_vigilance';
|
|
12
|
+
const keyOf = (organisationId, id) => `${organisationId}\u0000${id}`;
|
|
13
|
+
|
|
14
|
+
function matchesFollowUp(row, filter) {
|
|
15
|
+
if (row.organisationId !== filter.organisationId) return false;
|
|
16
|
+
if (filter.userId !== undefined && row.userId !== filter.userId) return false;
|
|
17
|
+
if (filter.decisionId !== undefined && row.decisionId !== filter.decisionId) return false;
|
|
18
|
+
if (filter.status !== undefined && row.status !== filter.status) return false;
|
|
19
|
+
if (filter.observableTo !== undefined && row.observableAt > filter.observableTo) return false;
|
|
20
|
+
return true;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function createMemoryVigilanceStore() {
|
|
24
|
+
const followUps = new Map();
|
|
25
|
+
const candidates = new Map();
|
|
26
|
+
return {
|
|
27
|
+
async putFollowUp(record) {
|
|
28
|
+
const key = keyOf(record.organisationId, record.id);
|
|
29
|
+
if (followUps.has(key)) return { record: copy(followUps.get(key)), created: false };
|
|
30
|
+
followUps.set(key, copy(record));
|
|
31
|
+
return { record: copy(record), created: true };
|
|
32
|
+
},
|
|
33
|
+
async getFollowUp(organisationId, id) { return copy(followUps.get(keyOf(organisationId, id)) ?? null); },
|
|
34
|
+
async listFollowUps(filter = {}) {
|
|
35
|
+
return [...followUps.values()].filter((row) => matchesFollowUp(row, filter))
|
|
36
|
+
.sort((a, b) => (a.observableAt < b.observableAt ? -1 : a.observableAt > b.observableAt ? 1 : a.id < b.id ? -1 : 1))
|
|
37
|
+
.slice(0, limitOf(filter.limit)).map(copy);
|
|
38
|
+
},
|
|
39
|
+
async updateFollowUp(organisationId, id, expectedStatus, patch) {
|
|
40
|
+
const key = keyOf(organisationId, id);
|
|
41
|
+
const row = followUps.get(key);
|
|
42
|
+
if (!row || row.status !== expectedStatus) return null;
|
|
43
|
+
const next = { ...row, ...copy(patch) };
|
|
44
|
+
followUps.set(key, next);
|
|
45
|
+
return copy(next);
|
|
46
|
+
},
|
|
47
|
+
async removeFollowUps({ organisationId, userId }) {
|
|
48
|
+
let count = 0;
|
|
49
|
+
for (const [key, row] of followUps) if (row.organisationId === organisationId && row.userId === userId) { followUps.delete(key); count += 1; }
|
|
50
|
+
return count;
|
|
51
|
+
},
|
|
52
|
+
async putCandidate(record) {
|
|
53
|
+
const key = keyOf(record.organisationId, record.id);
|
|
54
|
+
if (candidates.has(key)) return { record: copy(candidates.get(key)), created: false };
|
|
55
|
+
candidates.set(key, copy(record));
|
|
56
|
+
return { record: copy(record), created: true };
|
|
57
|
+
},
|
|
58
|
+
async getCandidate(organisationId, id) { return copy(candidates.get(keyOf(organisationId, id)) ?? null); },
|
|
59
|
+
async listCandidates(filter = {}) {
|
|
60
|
+
return [...candidates.values()]
|
|
61
|
+
.filter((row) => row.organisationId === filter.organisationId && (filter.agentId === undefined || row.agentId === filter.agentId))
|
|
62
|
+
.sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id < b.id ? -1 : 1))
|
|
63
|
+
.slice(0, limitOf(filter.limit)).map(copy);
|
|
64
|
+
}
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** SQL that creates the vigilance tables. Idempotent. */
|
|
69
|
+
function postgresVigilanceSchema(options) {
|
|
70
|
+
const p = prefixOf(options, DEFAULT_PREFIX);
|
|
71
|
+
return `CREATE TABLE IF NOT EXISTS "${p}_follow_ups" (
|
|
72
|
+
organisation_id text NOT NULL,
|
|
73
|
+
id text NOT NULL,
|
|
74
|
+
user_id text,
|
|
75
|
+
agent_id text,
|
|
76
|
+
decision_id text NOT NULL,
|
|
77
|
+
observable_at timestamptz NOT NULL,
|
|
78
|
+
status text NOT NULL,
|
|
79
|
+
fingerprint text NOT NULL,
|
|
80
|
+
created_at timestamptz NOT NULL,
|
|
81
|
+
envelope jsonb NOT NULL,
|
|
82
|
+
PRIMARY KEY (organisation_id, id)
|
|
83
|
+
);
|
|
84
|
+
CREATE INDEX IF NOT EXISTS "${p}_follow_ups_due_idx" ON "${p}_follow_ups" (organisation_id, status, observable_at);
|
|
85
|
+
CREATE INDEX IF NOT EXISTS "${p}_follow_ups_user_idx" ON "${p}_follow_ups" (organisation_id, user_id);
|
|
86
|
+
CREATE TABLE IF NOT EXISTS "${p}_candidates" (
|
|
87
|
+
organisation_id text NOT NULL,
|
|
88
|
+
id text NOT NULL,
|
|
89
|
+
agent_id text,
|
|
90
|
+
proposal_id text,
|
|
91
|
+
fingerprint text NOT NULL,
|
|
92
|
+
created_at timestamptz NOT NULL,
|
|
93
|
+
envelope jsonb NOT NULL,
|
|
94
|
+
PRIMARY KEY (organisation_id, id)
|
|
95
|
+
);
|
|
96
|
+
CREATE INDEX IF NOT EXISTS "${p}_candidates_agent_idx" ON "${p}_candidates" (organisation_id, agent_id, created_at);`;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
const read = (row) => (row ? (typeof row.envelope === 'string' ? JSON.parse(row.envelope) : row.envelope) : null);
|
|
100
|
+
|
|
101
|
+
/** Vigilance store on PostgreSQL. `db` is any `{ query(sql, params) }`; every value is a parameter. */
|
|
102
|
+
function createPostgresVigilanceStore(db, options) {
|
|
103
|
+
requireQueryable(db);
|
|
104
|
+
const p = prefixOf(options, DEFAULT_PREFIX);
|
|
105
|
+
const fu = `"${p}_follow_ups"`, ca = `"${p}_candidates"`;
|
|
106
|
+
const fuColumns = (r) => [r.organisationId, r.id, r.userId, r.agentId, r.decisionId, r.observableAt, r.status, r.fingerprint, r.createdAt, JSON.stringify(r)];
|
|
107
|
+
return {
|
|
108
|
+
async putFollowUp(record) {
|
|
109
|
+
const inserted = await db.query(
|
|
110
|
+
`INSERT INTO ${fu} (organisation_id, id, user_id, agent_id, decision_id, observable_at, status, fingerprint, created_at, envelope)
|
|
111
|
+
VALUES ($1, $2, $3, $4, $5, $6::timestamptz, $7, $8, $9::timestamptz, $10::jsonb)
|
|
112
|
+
ON CONFLICT (organisation_id, id) DO NOTHING RETURNING envelope`, fuColumns(record));
|
|
113
|
+
if (inserted.rows.length) return { record: read(inserted.rows[0]), created: true };
|
|
114
|
+
return { record: await this.getFollowUp(record.organisationId, record.id), created: false };
|
|
115
|
+
},
|
|
116
|
+
async getFollowUp(organisationId, id) {
|
|
117
|
+
return read((await db.query(`SELECT envelope FROM ${fu} WHERE organisation_id = $1 AND id = $2`, [organisationId, id])).rows[0]);
|
|
118
|
+
},
|
|
119
|
+
async listFollowUps(filter = {}) {
|
|
120
|
+
const params = [filter.organisationId];
|
|
121
|
+
const parts = ['organisation_id = $1'];
|
|
122
|
+
const add = (sql, value) => { params.push(value); parts.push(sql.replace('?', `$${params.length}`)); };
|
|
123
|
+
if (filter.userId !== undefined) { if (filter.userId === null) parts.push('user_id IS NULL'); else add('user_id = ?', filter.userId); }
|
|
124
|
+
if (filter.decisionId !== undefined) add('decision_id = ?', filter.decisionId);
|
|
125
|
+
if (filter.status !== undefined) add('status = ?', filter.status);
|
|
126
|
+
if (filter.observableTo !== undefined) add('observable_at <= ?::timestamptz', filter.observableTo);
|
|
127
|
+
params.push(limitOf(filter.limit));
|
|
128
|
+
return (await db.query(`SELECT envelope FROM ${fu} WHERE ${parts.join(' AND ')} ORDER BY observable_at ASC, id ASC LIMIT $${params.length}`, params)).rows.map(read);
|
|
129
|
+
},
|
|
130
|
+
async updateFollowUp(organisationId, id, expectedStatus, patch) {
|
|
131
|
+
const current = await this.getFollowUp(organisationId, id);
|
|
132
|
+
if (!current || current.status !== expectedStatus) return null;
|
|
133
|
+
const next = { ...current, ...copy(patch) };
|
|
134
|
+
const result = await db.query(
|
|
135
|
+
`UPDATE ${fu} SET status = $4, envelope = $5::jsonb WHERE organisation_id = $1 AND id = $2 AND status = $3 RETURNING envelope`,
|
|
136
|
+
[organisationId, id, expectedStatus, next.status, JSON.stringify(next)]);
|
|
137
|
+
return read(result.rows[0]);
|
|
138
|
+
},
|
|
139
|
+
async removeFollowUps({ organisationId, userId }) {
|
|
140
|
+
const result = await db.query(`DELETE FROM ${fu} WHERE organisation_id = $1 AND user_id = $2`, [organisationId, userId]);
|
|
141
|
+
return result.rowCount ?? 0;
|
|
142
|
+
},
|
|
143
|
+
async putCandidate(record) {
|
|
144
|
+
const inserted = await db.query(
|
|
145
|
+
`INSERT INTO ${ca} (organisation_id, id, agent_id, proposal_id, fingerprint, created_at, envelope)
|
|
146
|
+
VALUES ($1, $2, $3, $4, $5, $6::timestamptz, $7::jsonb) ON CONFLICT (organisation_id, id) DO NOTHING RETURNING envelope`,
|
|
147
|
+
[record.organisationId, record.id, record.agentId, record.proposalId, record.fingerprint, record.createdAt, JSON.stringify(record)]);
|
|
148
|
+
if (inserted.rows.length) return { record: read(inserted.rows[0]), created: true };
|
|
149
|
+
return { record: await this.getCandidate(record.organisationId, record.id), created: false };
|
|
150
|
+
},
|
|
151
|
+
async getCandidate(organisationId, id) {
|
|
152
|
+
return read((await db.query(`SELECT envelope FROM ${ca} WHERE organisation_id = $1 AND id = $2`, [organisationId, id])).rows[0]);
|
|
153
|
+
},
|
|
154
|
+
async listCandidates(filter = {}) {
|
|
155
|
+
const params = [filter.organisationId];
|
|
156
|
+
const parts = ['organisation_id = $1'];
|
|
157
|
+
if (filter.agentId !== undefined) { params.push(filter.agentId); parts.push(`agent_id = $${params.length}`); }
|
|
158
|
+
params.push(limitOf(filter.limit));
|
|
159
|
+
return (await db.query(`SELECT envelope FROM ${ca} WHERE ${parts.join(' AND ')} ORDER BY created_at ASC, id ASC LIMIT $${params.length}`, params)).rows.map(read);
|
|
160
|
+
}
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const METHODS = ['putFollowUp', 'getFollowUp', 'listFollowUps', 'updateFollowUp', 'removeFollowUps', 'putCandidate', 'getCandidate', 'listCandidates'];
|
|
165
|
+
|
|
166
|
+
module.exports = { createMemoryVigilanceStore, createPostgresVigilanceStore, postgresVigilanceSchema, VIGILANCE_STORE_METHODS: METHODS };
|