@astratra/conscience 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.fr.md +954 -0
  3. package/README.md +915 -2
  4. package/package.json +50 -4
  5. package/src/autoconscience/experiments/common.js +76 -0
  6. package/src/autoconscience/experiments/execution.js +33 -0
  7. package/src/autoconscience/experiments/holdout.js +88 -0
  8. package/src/autoconscience/experiments/laboratory.js +99 -0
  9. package/src/autoconscience/experiments/replay.js +113 -0
  10. package/src/autoconscience/experiments/runner.js +54 -0
  11. package/src/autoconscience/experiments/sandbox.js +58 -0
  12. package/src/autoconscience/index.d.ts +203 -0
  13. package/src/autoconscience/index.js +116 -0
  14. package/src/autoconscience/lessons.js +32 -0
  15. package/src/autoconscience/shadow/candidate.js +69 -0
  16. package/src/autoconscience/shadow/index.d.ts +169 -0
  17. package/src/autoconscience/shadow/index.js +11 -0
  18. package/src/autoconscience/shadow/report.js +125 -0
  19. package/src/autoconscience/shadow/runner.js +384 -0
  20. package/src/autoconscience/shadow/store.js +98 -0
  21. package/src/autoconscience/signals.js +88 -0
  22. package/src/autoconscience/statistics.js +84 -0
  23. package/src/autoconscience/vigilance/abstention.js +123 -0
  24. package/src/autoconscience/vigilance/adversary.js +145 -0
  25. package/src/autoconscience/vigilance/common.js +56 -0
  26. package/src/autoconscience/vigilance/drift.js +306 -0
  27. package/src/autoconscience/vigilance/followups.js +100 -0
  28. package/src/autoconscience/vigilance/index.d.ts +190 -0
  29. package/src/autoconscience/vigilance/index.js +23 -0
  30. package/src/autoconscience/vigilance/lessonTests.js +40 -0
  31. package/src/autoconscience/vigilance/library.js +162 -0
  32. package/src/autoconscience/vigilance/roles.js +122 -0
  33. package/src/autoconscience/vigilance/store.js +166 -0
  34. package/src/conscience.js +559 -0
  35. package/src/diff.js +27 -0
  36. package/src/errors.js +11 -0
  37. package/src/governor/approvals.js +132 -0
  38. package/src/governor/changes.js +269 -0
  39. package/src/governor/governor.js +286 -0
  40. package/src/governor/index.d.ts +385 -0
  41. package/src/governor/index.js +22 -0
  42. package/src/governor/policy.js +136 -0
  43. package/src/governor/postgres.js +243 -0
  44. package/src/governor/remote.js +305 -0
  45. package/src/governor/review.js +191 -0
  46. package/src/governor/rollout.js +66 -0
  47. package/src/governor/stores.js +136 -0
  48. package/src/governor/util.js +53 -0
  49. package/src/guard.js +21 -0
  50. package/src/index.d.ts +244 -0
  51. package/src/index.js +23 -0
  52. package/src/memoryStore.js +65 -0
  53. package/src/postgres.js +93 -0
  54. package/src/records.js +220 -0
package/package.json CHANGED
@@ -1,6 +1,52 @@
1
1
  {
2
2
  "name": "@astratra/conscience",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.1.0",
4
+ "description": "Documented memory of an AI agent's decisions (outcomes, corrections, lessons with evidence, self-model, lineage, erasure) under a deterministic governor with no language model: constitution, permissions, budgets, isolation, kill switch, human approval.",
5
+ "engines": {
6
+ "node": ">=20"
7
+ },
8
+ "main": "src/index.js",
9
+ "types": "src/index.d.ts",
10
+ "type": "commonjs",
11
+ "files": [
12
+ "src"
13
+ ],
14
+ "scripts": {
15
+ "test": "node --test test/*.test.js"
16
+ },
17
+ "keywords": [
18
+ "astratra",
19
+ "ai",
20
+ "agent",
21
+ "governance",
22
+ "decisions",
23
+ "memory",
24
+ "audit",
25
+ "postgres"
26
+ ],
27
+ "license": "MIT",
28
+ "publishConfig": {
29
+ "access": "public"
30
+ },
31
+ "dependencies": {
32
+ "@astratra/ai": "^1.8.0"
33
+ },
34
+ "devDependencies": {
35
+ "pg": "^8.13.1"
36
+ },
37
+ "exports": {
38
+ ".": {
39
+ "types": "./src/index.d.ts",
40
+ "default": "./src/index.js"
41
+ },
42
+ "./governor": {
43
+ "types": "./src/governor/index.d.ts",
44
+ "default": "./src/governor/index.js"
45
+ },
46
+ "./autoconscience": {
47
+ "types": "./src/autoconscience/index.d.ts",
48
+ "default": "./src/autoconscience/index.js"
49
+ },
50
+ "./package.json": "./package.json"
51
+ }
52
+ }
@@ -0,0 +1,76 @@
1
+ 'use strict';
2
+ const { assertGovernorReady } = require('../../governor/governor');
3
+ const { ConscienceError } = require('../../errors');
4
+ const { fingerprintOf, deepFreeze } = require('../../governor/util');
5
+ const { invalid, minimum, number, honestStatistics } = require('../statistics');
6
+ const fail = (code, message) => { throw new ConscienceError(code, message); };
7
+ async function ready(options = {}) {
8
+ await assertGovernorReady(options.governor, { organisationId: options.organisationId });
9
+ options.governor.assertSingleOrganisation(options.organisationId);
10
+ return options;
11
+ }
12
+ function date(value, label) {
13
+ if (value == null || (!['string', 'number'].includes(typeof value) && !(value instanceof Date))) invalid(`${label} requires a date.`);
14
+ const ms = value instanceof Date ? value.getTime() : typeof value === 'number' ? value : Date.parse(value);
15
+ if (!Number.isFinite(ms)) invalid(`${label} requires a date.`);
16
+ return new Date(ms).toISOString();
17
+ }
18
+ /** Copy only data, without invoking accessors, toJSON or executable callbacks. */
19
+ function data(value, depth = 0, seen = new Set()) {
20
+ if (depth > 32 || seen.has(value)) invalid('Data must be acyclic and at most 32 levels deep.');
21
+ if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
22
+ if (typeof value === 'number' && Number.isFinite(value)) return value;
23
+ if (!value || typeof value !== 'object' || (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))) invalid('Only plain JSON data is allowed.');
24
+ seen.add(value);
25
+ const out = Array.isArray(value) ? [] : Object.create(null);
26
+ for (const key of Object.keys(value)) {
27
+ const descriptor = Object.getOwnPropertyDescriptor(value, key);
28
+ if (!Object.hasOwn(descriptor, 'value')) invalid('Data accessors are forbidden.');
29
+ out[key] = data(descriptor.value, depth + 1, seen);
30
+ }
31
+ seen.delete(value);
32
+ // Restore ordinary JSON objects, including safe own __proto__ properties.
33
+ return JSON.parse(JSON.stringify(out));
34
+ }
35
+ function agentSource(agent) {
36
+ if (typeof agent !== 'function') invalid('agent must be a self-contained function.');
37
+ const source = Function.prototype.toString.call(agent);
38
+ if (source.length > 100000 || source.includes('[native code]')) invalid('agent must be serializable source, without bound/native functions.');
39
+ return source;
40
+ }
41
+ function casesOf(cases, label = 'cases') {
42
+ const list = data(cases);
43
+ if (!Array.isArray(list) || !list.length || list.length > 10000) invalid(`${label} needs 1 to 10000 cases.`);
44
+ const ids = new Set();
45
+ for (const item of list) {
46
+ if (!item || typeof item.id !== 'string' || !item.id.trim() || !Object.hasOwn(item, 'input') || !Object.hasOwn(item, 'expected')) invalid('Every case needs id, input and expected.');
47
+ if (ids.has(item.id)) invalid('Case ids must be distinct.');
48
+ ids.add(item.id);
49
+ }
50
+ if (new Set(list.map((item) => fingerprintOf(item.input))).size !== list.length) invalid('Duplicate inputs cannot count as independent cases.');
51
+ return list;
52
+ }
53
+ function metricsOf(metrics = [{ name: 'accuracy', kind: 'exact_match' }]) {
54
+ const list = data(metrics);
55
+ if (!Array.isArray(list) || !list.length || list.length > 20) invalid('metrics must be a non-empty list (at most 20).');
56
+ const names = new Set();
57
+ for (const metric of list) {
58
+ if (!metric || typeof metric.name !== 'string' || !/^[a-z][a-z0-9_]{0,60}$/.test(metric.name) || metric.kind !== 'exact_match') invalid('Metrics require a name and kind: exact_match.');
59
+ for (const key of ['outputKey', 'expectedKey']) if (metric[key] != null && (typeof metric[key] !== 'string' || !metric[key])) invalid('Metric keys must be non-empty strings.');
60
+ if (names.has(metric.name)) invalid('Duplicate metric name.');
61
+ names.add(metric.name);
62
+ }
63
+ return list;
64
+ }
65
+ function statisticsOptions(options = {}) {
66
+ const minimumSample = minimum(options.minimumSample);
67
+ const level = options.level ?? 0.95;
68
+ honestStatistics([], { minimumSample, level });
69
+ return { minimumSample, level };
70
+ }
71
+ function timeoutOf(value = 1000) {
72
+ number(value, 'timeoutMs', 10, 30000);
73
+ if (!Number.isInteger(value)) invalid('timeoutMs must be an integer.');
74
+ return value;
75
+ }
76
+ module.exports = { ready, fail, date, data, agentSource, casesOf, metricsOf, statisticsOptions, timeoutOf, invalid, fingerprintOf, deepFreeze };
@@ -0,0 +1,33 @@
1
+ 'use strict';
2
+ const { Worker } = require('node:worker_threads');
3
+ const path = require('node:path');
4
+ const { ready, timeoutOf, fail } = require('./common');
5
+ /** Candidate source is executed in a fresh realm; no host callbacks or objects enter it. */
6
+ async function execute({ governor, organisationId, source, input, config = {}, timeoutMs = 1000 }) {
7
+ await ready({ governor, organisationId });
8
+ const timeout = timeoutOf(timeoutMs);
9
+ const result = await new Promise((resolve, reject) => {
10
+ const worker = new Worker(path.join(__dirname, 'runner.js'), {
11
+ workerData: { source, input: JSON.stringify(input), config: JSON.stringify(config), timeout },
12
+ resourceLimits: { maxOldGenerationSizeMb: 32, maxYoungGenerationSizeMb: 8, stackSizeMb: 2 },
13
+ stdout: true, stderr: true, env: {}, execArgv: ['--experimental-vm-modules']
14
+ });
15
+ // No output of the candidate, including logs or thrown messages, is forwarded.
16
+ worker.stdout.resume(); worker.stderr.resume();
17
+ let settled = false;
18
+ const finish = (fn, value) => {
19
+ if (settled) return;
20
+ settled = true; clearTimeout(timer);
21
+ worker.terminate().catch(() => {}); fn(value);
22
+ };
23
+ const timer = setTimeout(() => finish(resolve, { status: 'unknown', reason: 'timeout', intentions: 0 }), timeout + 500);
24
+ worker.once('message', (message) => finish(resolve, message));
25
+ worker.once('error', () => finish(resolve, { status: 'unknown', reason: 'execution_failed', intentions: 0 }));
26
+ worker.once('exit', () => finish(resolve, { status: 'unknown', reason: 'execution_failed', intentions: 0 }));
27
+ worker.once('messageerror', () => finish(reject, new Error('Invalid sandbox message.')));
28
+ });
29
+ await ready({ governor, organisationId });
30
+ if (!result || !['completed', 'unknown'].includes(result.status)) fail('sandbox_invalid', 'Invalid sandbox result.');
31
+ return result;
32
+ }
33
+ module.exports = { execute };
@@ -0,0 +1,88 @@
1
+ 'use strict';
2
+ const { ready, fail, data, casesOf, metricsOf, statisticsOptions, agentSource, timeoutOf, fingerprintOf, deepFreeze } = require('./common');
3
+ const { createSandbox, sandboxState } = require('./sandbox');
4
+ const { execute } = require('./execution');
5
+ const { honestStatistics } = require('../statistics');
6
+ const states = new WeakMap();
7
+ function score(output, expected, metric, completed) {
8
+ if (!completed) return 'unknown';
9
+ const field = (value, key) => !key ? value : value !== null && typeof value === 'object' && Object.hasOwn(value, key) ? value[key] : undefined;
10
+ const actual = field(output, metric.outputKey);
11
+ const target = field(expected, metric.expectedKey);
12
+ if (actual === undefined || target === undefined) return 'unknown';
13
+ return fingerprintOf(actual) === fingerprintOf(target) ? 'succeeded' : 'failed';
14
+ }
15
+ /** Only aggregate binomial statistics leave this function for a protected set. */
16
+ async function evaluateCases({ binding, source, cases, metrics, config, statistics, timeoutMs, protectedSet = true }) {
17
+ const statuses = Object.fromEntries(metrics.map((m) => [m.name, []]));
18
+ const journal = [];
19
+ for (const sample of cases) {
20
+ const result = await execute({ ...binding, source, input: sample.input, config, timeoutMs });
21
+ if (!protectedSet) journal.push(...(result.journal ?? []).map((entry) => ({ ...entry, caseId: sample.id })));
22
+ for (const metric of metrics) statuses[metric.name].push(score(result.output, sample.expected, metric, result.status === 'completed'));
23
+ }
24
+ return { sandbox: true, ...(!protectedSet ? { journal } : {}), metrics: Object.fromEntries(metrics.map((m) => [m.name, honestStatistics(statuses[m.name], statistics)])) };
25
+ }
26
+ async function createHoldout(options = {}) {
27
+ await ready(options);
28
+ const binding = { governor: options.governor, organisationId: options.organisationId };
29
+ const cases = deepFreeze(casesOf(options.cases));
30
+ const access = [];
31
+ const state = { ...binding, cases, used: false, reserved: null, inputHashes: new Set(cases.map((c) => fingerprintOf(c.input))) };
32
+ const log = (action) => access.push({ sequence: access.length + 1, action, at: new Date().toISOString() });
33
+ const deny = () => { log('read_denied'); return fail('holdout_protected', 'Holdout content is never readable.'); };
34
+ async function evaluate(input = {}) {
35
+ await ready(binding);
36
+ if (input.organisationId != null) binding.governor.assertSingleOrganisation(binding.organisationId, input.organisationId);
37
+ if (state.reserved) fail('holdout_protected', 'This final set is reserved for its registered experiment.');
38
+ const source = agentSource(input.agent), metrics = metricsOf(input.metrics), statistics = statisticsOptions(input), timeoutMs = timeoutOf(input.timeoutMs);
39
+ const sandbox = input.sandbox ?? await createSandbox({ ...binding, tools: input.tools });
40
+ const { config } = await sandboxState(sandbox, binding);
41
+ return consume(state, { source, metrics, statistics, timeoutMs, config }, log);
42
+ }
43
+ const target = Object.assign(Object.create(null), {
44
+ evaluate, async getAccessLog() { await ready(binding); return data(access); },
45
+ read: deny
46
+ });
47
+ Object.freeze(target);
48
+ const protectedSet = new Proxy(target, {
49
+ get: (object, key) => key === 'then' ? undefined : Object.hasOwn(object, key) ? object[key] : deny(),
50
+ ownKeys: deny, set: deny, defineProperty: deny, deleteProperty: deny,
51
+ getOwnPropertyDescriptor: (object, key) => Object.hasOwn(object, key) ? Object.getOwnPropertyDescriptor(object, key) : deny(),
52
+ has: (object, key) => Object.hasOwn(object, key) ? true : deny()
53
+ });
54
+ state.log = log;
55
+ states.set(protectedSet, state);
56
+ return protectedSet;
57
+ }
58
+ async function consume(state, input, log = state.log) {
59
+ await ready(state);
60
+ if (state.used) { log('evaluation_denied'); fail('holdout_consumed', 'A final set can be evaluated only once.'); }
61
+ state.used = true; log('evaluation_started');
62
+ try {
63
+ const result = await evaluateCases({ binding: state, cases: state.cases, ...input });
64
+ log('evaluation_completed'); return result;
65
+ } catch (error) { log('evaluation_failed'); throw error; }
66
+ }
67
+ async function reserveHoldout(holdout, binding, token, development, validation) {
68
+ await ready(binding);
69
+ const state = states.get(holdout);
70
+ if (!state || state.governor !== binding.governor) fail('holdout_protected', 'Use a holdout created with this governor.');
71
+ binding.governor.assertSingleOrganisation(binding.organisationId, state.organisationId);
72
+ if (state.used || state.reserved) fail('holdout_consumed', 'Holdout already used or reserved.');
73
+ const hashes = new Set();
74
+ for (const sample of [...development, ...validation]) {
75
+ const hash = fingerprintOf(sample.input);
76
+ if (hashes.has(hash) || state.inputHashes.has(hash) || state.cases.some((c) => c.id === sample.id)) fail('split_overlap', 'Development, validation and holdout inputs must be disjoint.');
77
+ hashes.add(hash);
78
+ }
79
+ state.reserved = token; state.log('reserved');
80
+ return Object.freeze({ release() {
81
+ if (!state.used && state.reserved === token) { state.reserved = null; state.log('registration_failed'); }
82
+ }, async evaluate(input) {
83
+ await ready(binding);
84
+ if (state.reserved !== token) fail('holdout_protected', 'Invalid final evaluation capability.');
85
+ return consume(state, input);
86
+ } });
87
+ }
88
+ module.exports = { createHoldout, evaluateCases, reserveHoldout };
@@ -0,0 +1,99 @@
1
+ 'use strict';
2
+ const { ready, fail, data, casesOf, metricsOf, statisticsOptions, timeoutOf, agentSource, invalid, date, fingerprintOf, deepFreeze } = require('./common');
3
+ const { number } = require('../statistics');
4
+ const { createSandbox, sandboxState, configurations } = require('./sandbox');
5
+ const { evaluateCases, reserveHoldout } = require('./holdout');
6
+ const { randomUUID } = require('node:crypto');
7
+ const registrations = new WeakMap();
8
+ const idsByGovernor = new WeakMap();
9
+ function protocolOf(input) {
10
+ if (!input || typeof input !== 'object') invalid('protocol is required.');
11
+ const protocol = data(input);
12
+ protocol.development = casesOf(protocol.development, 'development');
13
+ protocol.validation = casesOf(protocol.validation, 'validation');
14
+ const ids = [...protocol.development, ...protocol.validation].map((c) => c.id);
15
+ if (new Set(ids).size !== ids.length) invalid('Development and validation case ids must be disjoint.');
16
+ return { ...protocol, ...statisticsOptions(protocol), timeoutMs: timeoutOf(protocol.timeoutMs) };
17
+ }
18
+ async function finding(binding, id, code, metrics) {
19
+ await ready(binding);
20
+ return binding.governor.recordFinding({ organisationId: binding.organisationId, id: `${id}:${code}`, code, severity: 'info',
21
+ subject: { kind: 'experiment', id }, recordedBy: { kind: 'system', id: 'experiment-laboratory' }, metrics });
22
+ }
23
+ async function proposeExperiment(options = {}) {
24
+ await ready(options);
25
+ const binding = { governor: options.governor, organisationId: options.organisationId };
26
+ if (typeof options.hypothesis !== 'string' || !options.hypothesis.trim()) invalid('hypothesis is required.');
27
+ if (!options.metrics) invalid('metrics must be preregistered.');
28
+ const metrics = metricsOf(options.metrics), protocol = protocolOf(options.protocol), thresholds = data(options.thresholds);
29
+ if (!thresholds || Array.isArray(thresholds) || typeof thresholds !== 'object') invalid('thresholds must map metric names to numbers.');
30
+ if (Object.keys(thresholds).length !== metrics.length) invalid('Every metric requires exactly one preregistered threshold.');
31
+ for (const metric of metrics) number(thresholds[metric.name], `thresholds.${metric.name}`, 0, 1);
32
+ const source = agentSource(options.agent), config = configurations(options.tools);
33
+ const registeredAt = date((options.now ?? Date.now)(), 'registeredAt');
34
+ const content = { organisationId: binding.organisationId, hypothesis: options.hypothesis, metrics, protocol, thresholds,
35
+ candidateFingerprint: fingerprintOf(source), toolsFingerprint: fingerprintOf(config), registrationId: randomUUID(), registeredAt };
36
+ const fingerprint = fingerprintOf(content), id = options.id ?? `experiment_${fingerprint.slice(0, 24)}`;
37
+ if (typeof id !== 'string' || !id.trim()) invalid('Experiment id must be a non-empty string.');
38
+ const ids = idsByGovernor.get(binding.governor) ?? new Set();
39
+ idsByGovernor.set(binding.governor, ids);
40
+ const scopedId = JSON.stringify([binding.organisationId, id]);
41
+ if (ids.has(scopedId)) fail('experiment_conflict', 'An experiment already uses this id.');
42
+ ids.add(scopedId);
43
+ const token = Object.freeze({});
44
+ let final;
45
+ try {
46
+ final = await reserveHoldout(options.holdout, binding, token, protocol.development, protocol.validation);
47
+ const recorded = await finding(binding, id, 'experiment_registered', { fingerprint, registeredAt, candidateFingerprint: content.candidateFingerprint,
48
+ metrics, thresholds, protocolFingerprint: fingerprintOf(protocol) });
49
+ if (recorded.metrics?.fingerprint !== fingerprint) fail('experiment_conflict', 'Stored registration already uses this id.');
50
+ } catch (error) { final?.release(); ids.delete(scopedId); throw error; }
51
+ const experiment = deepFreeze({ id, ...content, fingerprint, sandbox: true });
52
+ registrations.set(experiment, { ...binding, final, config, used: false, contentFingerprint: fingerprint, source });
53
+ return experiment;
54
+ }
55
+ function conclusion(stages, metrics, thresholds) {
56
+ const all = Object.values(stages).flatMap((stage) => metrics.map((metric) => ({ stats: stage.metrics[metric.name], threshold: thresholds[metric.name] })));
57
+ if (all.some(({ stats }) => stats.status === 'insufficient_data' || stats.unknown > 0)) return 'inconclusive';
58
+ if (all.some(({ stats, threshold }) => stats.interval.high < threshold)) return 'refuted';
59
+ return all.every(({ stats, threshold }) => stats.interval.low >= threshold) ? 'supported' : 'inconclusive';
60
+ }
61
+ async function runExperiment(options = {}) {
62
+ await ready(options);
63
+ const { experiment } = options;
64
+ const state = registrations.get(experiment);
65
+ if (!state) fail('protocol_changed', 'Use the original preregistered experiment handle.');
66
+ if (state.governor !== options.governor) invalid('Experiment governor mismatch.');
67
+ options.governor.assertSingleOrganisation(options.organisationId, state.organisationId);
68
+ for (const key of ['protocol', 'metrics', 'thresholds', 'hypothesis']) {
69
+ if (options[key] !== undefined && fingerprintOf(data(options[key])) !== fingerprintOf(experiment[key])) fail('protocol_changed', 'Preregistered experiment content cannot change.');
70
+ }
71
+ if (options.agent && agentSource(options.agent) !== state.source) fail('protocol_changed', 'The registered candidate cannot change.');
72
+ if (options.tools && fingerprintOf(configurations(options.tools)) !== experiment.toolsFingerprint) fail('protocol_changed', 'Registered tools cannot change.');
73
+ const content = { ...experiment };
74
+ delete content.fingerprint; delete content.id; delete content.sandbox;
75
+ if (fingerprintOf(content) !== state.contentFingerprint) fail('protocol_changed', 'Experiment fingerprint mismatch.');
76
+ if (state.used) fail('experiment_consumed', 'An experiment can execute only once; preregister a new experiment and final set.');
77
+ state.used = true;
78
+ const { protocol, metrics, thresholds } = experiment;
79
+ const sandbox = await createSandbox({ ...state, tools: state.config });
80
+ const { config } = await sandboxState(sandbox, state);
81
+ const input = { binding: state, source: state.source, metrics, config, statistics: statisticsOptions(protocol), timeoutMs: protocol.timeoutMs };
82
+ await finding(state, experiment.id, 'experiment_started', { fingerprint: experiment.fingerprint });
83
+ try {
84
+ const development = await evaluateCases({ ...input, cases: protocol.development, protectedSet: false });
85
+ const validation = await evaluateCases({ ...input, cases: protocol.validation, protectedSet: false });
86
+ const holdout = await state.final.evaluate(input);
87
+ const stages = { development, validation, holdout };
88
+ const result = { experimentId: experiment.id, fingerprint: experiment.fingerprint, registeredAt: experiment.registeredAt,
89
+ sandbox: true, decision: conclusion(stages, metrics, thresholds), causality: 'not_established',
90
+ interval: holdout.metrics[metrics[0].name].interval, stages };
91
+ await finding(state, experiment.id, 'experiment_completed', result);
92
+ return result;
93
+ } catch (error) {
94
+ // Keep errors out of the public evidence: a candidate message can contain protected inputs.
95
+ await finding(state, experiment.id, 'experiment_failed', { fingerprint: experiment.fingerprint, code: 'execution_failed' });
96
+ throw error;
97
+ }
98
+ }
99
+ module.exports = { proposeExperiment, runExperiment };
@@ -0,0 +1,113 @@
1
+ 'use strict';
2
+ const { ready, fail, date, data, agentSource, invalid, fingerprintOf } = require('./common');
3
+ const { createSandbox, sandboxState } = require('./sandbox');
4
+ const { execute } = require('./execution');
5
+ const FACT_DATES = new Set(['at', 'recordedAt', 'observedAt', 'decidedAt', 'madeAt', 'correctedAt', 'knownAt', 'availableAt', 'testedAt', 'createdAt', 'validFrom']);
6
+ /** Validate factual availability recursively; planned horizons/expiry dates are not facts from the future. */
7
+ function temporal(value, cutoff) {
8
+ if (!value || typeof value !== 'object') return;
9
+ for (const [key, child] of Object.entries(value)) {
10
+ if (FACT_DATES.has(key) && child != null && date(child, key) > cutoff) fail('future_data', 'Replay contains information unavailable at the decision date.');
11
+ if (child && typeof child === 'object') temporal(child, cutoff);
12
+ }
13
+ }
14
+ function scoped(record, options) {
15
+ options.governor.assertSingleOrganisation(options.organisationId, record.organisationId);
16
+ if (!record.organisationId) invalid('Replay data needs organisationId.');
17
+ if (options.userId != null && record.userId !== options.userId) fail('cross_person', 'Replay data belongs to another person.');
18
+ }
19
+ async function list(store, kind, filter) {
20
+ const result = await store.list(kind, { ...filter, limit: 10000, order: 'asc' });
21
+ if (result.length >= 10000) fail('replay_limit', 'Narrow the replay scope to avoid truncation.');
22
+ return result;
23
+ }
24
+ async function replayDecisions(options = {}) {
25
+ await ready(options);
26
+ const { governor, conscience } = options;
27
+ if (!conscience || conscience.governor !== governor) invalid('conscience must use the supplied governor.');
28
+ const asOf = date(options.asOf, 'asOf');
29
+ const source = agentSource(options.proposal?.agent);
30
+ const information = data(options.proposal?.information ?? []);
31
+ if (!Array.isArray(information)) invalid('proposal.information must be dated data.');
32
+ if (Boolean(options.decisionIds) === Boolean(options.window)) invalid('Choose decisionIds or window, exclusively.');
33
+ const scope = { organisationId: options.organisationId, ...(options.userId != null ? { userId: options.userId } : {}) };
34
+ let decisions;
35
+ if (options.decisionIds) {
36
+ if (!Array.isArray(options.decisionIds) || !options.decisionIds.length || !options.decisionIds.every((id) => typeof id === 'string' && id.trim())) invalid('decisionIds must be a non-empty list of ids.');
37
+ decisions = await Promise.all([...new Set(options.decisionIds)].map((id) => conscience.getDecision(scope, id)));
38
+ if (decisions.some((d) => !d)) fail('not_found', 'A replay decision is unavailable in this scope.');
39
+ } else {
40
+ const from = date(options.window.from, 'window.from'), to = date(options.window.to, 'window.to');
41
+ if (from >= to) invalid('Replay window must be non-empty.');
42
+ decisions = (await list(conscience.store, 'decision', { ...scope, agentId: options.agentId, eventFrom: from, eventTo: to })).map((r) => r.data);
43
+ }
44
+ if (options.agentId && decisions.some((d) => d.agentId !== options.agentId)) invalid('Replay agent mismatch.');
45
+ const snapshots = data(options.snapshots ?? {});
46
+ const sandbox = options.sandbox ?? await createSandbox({ ...scope, governor, tools: options.tools });
47
+ const { config } = await sandboxState(sandbox, { ...scope, governor });
48
+ const cases = [];
49
+ // Validate every case before running any candidate: contaminated batches never partly execute.
50
+ const prepared = [];
51
+ for (const raw of decisions) {
52
+ const d = data(raw), cutoff = date(d.decidedAt, 'decidedAt');
53
+ scoped(d, options);
54
+ if (cutoff > asOf) fail('future_data', 'The decision is later than asOf.');
55
+ temporal(d, cutoff);
56
+ temporal(config, cutoff);
57
+ for (const tool of Object.values(config)) {
58
+ if (tool.kind !== 'read') continue;
59
+ const responses = [...(tool.recordings ?? []).map((r) => r.output), ...(Object.hasOwn(tool, 'response') ? [tool.response] : [])];
60
+ for (const response of responses) {
61
+ if (!response || typeof response !== 'object' || response.at == null || response.recordedAt == null || !Object.hasOwn(response, 'data')) fail('temporal_metadata_required', 'Replay read responses need organisationId, at, recordedAt and data.');
62
+ scoped(response, options); date(response.at, 'tool.at'); date(response.recordedAt, 'tool.recordedAt');
63
+ }
64
+ }
65
+ const snapshot = d.inputSnapshotRef ? snapshots[d.inputSnapshotRef] : { ...scope, at: d.context.at, recordedAt: d.recordedAt, data: d.context.data };
66
+ if (!snapshot) fail('snapshot_missing', 'The referenced input snapshot is required.');
67
+ scoped(snapshot, options);
68
+ date(snapshot.at, 'snapshot.at'); date(snapshot.recordedAt, 'snapshot.recordedAt');
69
+ if (!Object.hasOwn(snapshot, 'data')) invalid('Snapshot needs data.');
70
+ temporal(snapshot, cutoff);
71
+ for (const item of information) {
72
+ scoped(item, options); date(item.at, 'information.at'); date(item.recordedAt, 'information.recordedAt'); temporal(item, cutoff);
73
+ }
74
+ const filter = { ...scope, agentId: d.agentId, recordedTo: cutoff };
75
+ const historicalDecisions = await list(conscience.store, 'decision', filter);
76
+ const knownIds = new Set(historicalDecisions.filter((r) => r.data.decidedAt <= cutoff).map((r) => r.id));
77
+ const outcomeRows = await list(conscience.store, 'outcome', filter);
78
+ const latest = new Map();
79
+ for (const row of outcomeRows) {
80
+ if (!knownIds.has(row.decisionId)) continue;
81
+ scoped(row.data, options); temporal(row.data, cutoff);
82
+ latest.set(JSON.stringify([row.decisionId, row.data.sensor]), data(row.data));
83
+ }
84
+ // Load stored revisions directly: derived P2 status must not disclose later evidence.
85
+ const lessonRows = await list(conscience.store, 'lesson', { ...scope, recordedTo: cutoff });
86
+ const latestLessons = new Map();
87
+ for (const row of lessonRows) if (row.agentId == null || row.agentId === d.agentId) latestLessons.set(row.lessonId, row.data);
88
+ const lessons = [];
89
+ for (const rawLesson of latestLessons.values()) {
90
+ if (rawLesson.status === 'retired' || (rawLesson.validFrom && rawLesson.validFrom > cutoff) || (rawLesson.validUntil && rawLesson.validUntil <= cutoff)) continue;
91
+ const lesson = data(rawLesson); scoped(lesson, options); temporal(lesson, cutoff);
92
+ for (const proof of lesson.evidence) {
93
+ if (proof.kind === 'external') fail('temporal_evidence_required', 'External lesson evidence needs a dated internal record for replay.');
94
+ const record = await conscience.store.get(proof.kind, options.organisationId, proof.ref);
95
+ if (!record) fail('temporal_evidence_required', 'Historical lesson evidence is unavailable.');
96
+ scoped(record.data, options); temporal(record.data, cutoff);
97
+ }
98
+ lessons.push(lesson);
99
+ }
100
+ const input = { inputs: snapshot.data, outcomes: [...latest.values()], lessons, information,
101
+ decision: { id: d.id, objective: d.objective, context: d.context, versions: d.versions, permissions: d.permissions }, asOf: cutoff };
102
+ prepared.push({ d, input });
103
+ }
104
+ for (const { d, input } of prepared) {
105
+ const result = await execute({ ...scope, governor, source, input, config, timeoutMs: options.timeoutMs });
106
+ const expected = { name: d.action.name, input: d.action.input };
107
+ cases.push({ decisionId: d.id, asOf: d.decidedAt, status: result.status,
108
+ compatible: result.status === 'completed' && Object.hasOwn(result, 'output') ? fingerprintOf(result.output) === fingerprintOf(expected) : null,
109
+ ...(Object.hasOwn(result, 'output') ? { output: result.output } : {}), intentions: result.intentions, journal: result.journal ?? [] });
110
+ }
111
+ return { purpose: 'compatibility_only', provesProgress: false, causality: 'not_established', sandbox: true, cases };
112
+ }
113
+ module.exports = { replayDecisions };
@@ -0,0 +1,54 @@
1
+ 'use strict';
2
+ const { parentPort, workerData } = require('node:worker_threads');
3
+ const vm = require('node:vm');
4
+ // The realm has no require, process, fetch, timers or host functions. JSON is
5
+ // parsed inside it: even Object/Function constructors belong to that realm.
6
+ const context = vm.createContext(Object.create(null), { codeGeneration: { strings: false, wasm: false }, microtaskMode: 'afterEvaluate' });
7
+ // Reject imports with a realm-local error. A host Error would expose its host
8
+ // Function constructor through a caught rejection. The worker enables VM module
9
+ // callbacks so Node does not substitute a host missing-flag error.
10
+ const importDenied = vm.runInContext('new Error("Dynamic imports are unavailable.")', context);
11
+ const literal = (s) => JSON.stringify(s);
12
+ const script = `
13
+ 'use strict';
14
+ const candidate = (${workerData.source});
15
+ const evaluation = (() => {
16
+ // Capture the realm's primitives before invoking the candidate.
17
+ const objectFreeze = Object.freeze, values = Object.values, keys = Object.keys, hasOwn = Object.hasOwn;
18
+ const parse = JSON.parse, stringify = JSON.stringify;
19
+ const promiseResolve = Promise.resolve.bind(Promise);
20
+ const promiseThen = Function.prototype.call.bind(Promise.prototype.then);
21
+ const input = parse(${literal(workerData.input)});
22
+ const config = parse(${literal(workerData.config)});
23
+ let intentions = 0; const journal = [];
24
+ const freeze = (value) => { if (value && typeof value === 'object') { objectFreeze(value); for (const v of values(value)) freeze(v); } return value; };
25
+ freeze(input); freeze(config);
26
+ const canonical = (v) => v === null || typeof v !== 'object' ? stringify(v) : Array.isArray(v) ? '[' + v.map(canonical).join(',') + ']' : '{' + keys(v).sort().map(k => stringify(k) + ':' + canonical(v[k])).join(',') + '}';
27
+ const tools = Object.create(null);
28
+ for (const [name, tool] of Object.entries(config)) tools[name] = async (args = null) => {
29
+ journal.push({ sequence: journal.length + 1, tool: name, kind: tool.kind, input: parse(stringify(args)), simulated: true });
30
+ if (tool.kind === 'write') { intentions++; return { simulated: true, intention: true }; }
31
+ const recorded = tool.recordings?.find(r => canonical(r.input) === canonical(args));
32
+ return recorded ? recorded.output : hasOwn(tool, 'response') ? tool.response : { simulated: true, status: 'unknown' };
33
+ };
34
+ freeze(tools);
35
+ let completed = false, serialized;
36
+ promiseThen(promiseResolve(candidate(input, tools)), output => {
37
+ const json = stringify({ output, intentions, journal });
38
+ if (json.length > 1000000) throw new Error('Output limit');
39
+ serialized = json; completed = true;
40
+ }, () => { serialized = null; completed = true; });
41
+ return objectFreeze({ result: () => completed ? serialized : null });
42
+ })();
43
+ `;
44
+ try {
45
+ vm.runInContext(script, context, { timeout: workerData.timeout, importModuleDynamically: () => { throw importDenied; } });
46
+ const result = vm.runInContext('evaluation.result()', context, { timeout: workerData.timeout });
47
+ if (typeof result !== 'string') parentPort.postMessage({ status: 'unknown', reason: 'execution_failed', intentions: 0 });
48
+ else {
49
+ const parsed = JSON.parse(result);
50
+ parentPort.postMessage({ status: 'completed', ...parsed });
51
+ }
52
+ } catch (_error) {
53
+ parentPort.postMessage({ status: 'unknown', reason: 'execution_failed', intentions: 0 });
54
+ }
@@ -0,0 +1,58 @@
1
+ 'use strict';
2
+ const { ready, data, invalid, deepFreeze, fingerprintOf } = require('./common');
3
+ const states = new WeakMap();
4
+ function configurations(tools = {}) {
5
+ if (!tools || typeof tools !== 'object' || Array.isArray(tools)) invalid('tools must map names to descriptors or real functions to replace.');
6
+ const out = Object.create(null);
7
+ for (const name of Object.keys(tools)) {
8
+ const own = Object.getOwnPropertyDescriptor(tools, name);
9
+ if (!Object.hasOwn(own, 'value')) invalid('Tool getters are forbidden.');
10
+ const tool = own.value;
11
+ if (typeof tool === 'function') { out[name] = { kind: 'write' }; continue; }
12
+ if (!tool || typeof tool !== 'object') invalid('Invalid tool descriptor.');
13
+ const descriptor = Object.getOwnPropertyDescriptors(tool);
14
+ for (const key of ['kind', 'response', 'recordings']) if (descriptor[key] && !Object.hasOwn(descriptor[key], 'value')) invalid('Tool simulation getters are forbidden.');
15
+ const kind = descriptor.kind?.value;
16
+ if (!['read', 'write', 'confirm'].includes(kind)) invalid('Tool kind must be read, write or confirm.');
17
+ const config = { kind: kind === 'read' ? 'read' : 'write' };
18
+ if (config.kind === 'read') {
19
+ if (descriptor.response) config.response = data(descriptor.response.value);
20
+ if (descriptor.recordings) {
21
+ config.recordings = data(descriptor.recordings.value);
22
+ if (!Array.isArray(config.recordings) || !config.recordings.every((r) => r && Object.hasOwn(r, 'input') && Object.hasOwn(r, 'output'))) invalid('recordings must contain input/output pairs.');
23
+ const ids = config.recordings.map((r) => fingerprintOf(r.input));
24
+ if (new Set(ids).size !== ids.length) invalid('Ambiguous recorded tool inputs.');
25
+ }
26
+ }
27
+ out[name] = config;
28
+ }
29
+ return deepFreeze(JSON.parse(JSON.stringify(out)));
30
+ }
31
+ async function createSandbox(options = {}) {
32
+ await ready(options);
33
+ const binding = { governor: options.governor, organisationId: options.organisationId };
34
+ const config = configurations(options.tools);
35
+ const journal = [];
36
+ const tools = Object.create(null);
37
+ for (const [name, tool] of Object.entries(config)) {
38
+ tools[name] = async (input = null) => {
39
+ await ready(binding);
40
+ const payload = data(input);
41
+ journal.push({ sequence: journal.length + 1, tool: name, kind: tool.kind, input: payload, simulated: true });
42
+ if (tool.kind === 'write') return { simulated: true, intention: true };
43
+ const record = tool.recordings?.find((r) => fingerprintOf(r.input) === fingerprintOf(payload));
44
+ return record ? data(record.output) : Object.hasOwn(tool, 'response') ? data(tool.response) : { simulated: true, status: 'unknown' };
45
+ };
46
+ }
47
+ const sandbox = Object.freeze({ tools: Object.freeze(tools), async getJournal() { await ready(binding); return data(journal); } });
48
+ states.set(sandbox, { ...binding, config });
49
+ return sandbox;
50
+ }
51
+ async function sandboxState(sandbox, binding) {
52
+ await ready(binding);
53
+ const state = states.get(sandbox);
54
+ if (!state || state.governor !== binding.governor) invalid('Use a sandbox built with this governor.');
55
+ binding.governor.assertSingleOrganisation(binding.organisationId, state.organisationId);
56
+ return state;
57
+ }
58
+ module.exports = { createSandbox, sandboxState, configurations };