@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
@@ -0,0 +1,203 @@
1
+ /** Deterministic P2 evaluation. No language model is imported or consulted. */
2
+ import type { Governor } from '../governor';
3
+ import type { EvidenceDegree, RecordKind, Conscience, Scope, ToolTrace, Justification, CorrectionClass, LessonVersion, Evidence } from '../index';
4
+
5
+ export type ReflectionTrigger = 'schedule' | 'idle' | 'volume' | 'on_demand';
6
+ export type ReflectionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'skipped';
7
+
8
+ /** One reflective cycle. Its lock, budget and checkpoints are those of an @astratra/agent task. */
9
+ export interface ReflectionRun {
10
+ id: string; organisationId: string; agentId?: string;
11
+ window: { from: string; to: string };
12
+ trigger: ReflectionTrigger;
13
+ /** Owner of the task lease (TaskStore.acquire of @astratra/agent). */
14
+ lockOwner?: string;
15
+ budget: { maxMs?: number; maxTurns?: number; maxTokens?: number; maxCost?: number };
16
+ model?: string; engineVersion: string;
17
+ startedAt?: string; finishedAt?: string; durationMs?: number; cost?: number;
18
+ findings: string[];
19
+ usefulFindings?: number; acceptedProposals?: number; userId?: string | null;
20
+ status: ReflectionStatus;
21
+ /** Measured benefit of the cycle against its cost (39); null until measured. */
22
+ utility?: number | null;
23
+ checkpoints?: Array<{ step: string; at: string }>;
24
+ /** Why a cycle did not start: too few new decisions, useless recent cycles, budget spent. */
25
+ skippedReason?: string;
26
+ }
27
+
28
+ export interface ReflectionFinding {
29
+ id: string; runId: string; organisationId: string;
30
+ decisionIds: string[]; observation: string; hypothesis?: string;
31
+ evidence: Array<{ kind: RecordKind | 'external'; ref: string }>;
32
+ evidenceDegree: EvidenceDegree;
33
+ confidence: number; severity: 'low' | 'medium' | 'high' | 'critical';
34
+ sampleSize: number;
35
+ kind: string; status: string; agentId?: string; domain?: string; confounders: string[]; details?: unknown;
36
+ /** Descriptive uncertainty interval; null when no known observations exist (10). */
37
+ interval: { low: number; high: number; level: number } | null;
38
+ /** "causality not established" is a legitimate answer (11). */
39
+ causality: 'established' | 'not_established' | 'unknown';
40
+ competingExplanations?: string[];
41
+ }
42
+
43
+ /** Announced probability against observed frequency (01). */
44
+ export interface CalibrationPoint { domain: string; organisationId: string; agentId: string; bucket: { low: number; high: number }; predicted: number; observed: number; count: number; window: { from: string; to: string } }
45
+
46
+ /** A supposed cause with its alternatives and a protocol written before the data is seen (16). */
47
+ export interface Hypothesis { id: string; organisationId: string; statement: string; alternatives: string[]; createdAt: string; status: 'open' | 'supported' | 'refuted' | 'inconclusive' }
48
+ export interface Experiment {
49
+ id: string; hypothesisId: string; organisationId: string;
50
+ protocol: { registeredAt: string; metrics: string[]; counterMetrics: string[]; cohorts: string[]; minimumSample: number; stopRule?: string };
51
+ /** Experiments run in a sandbox only: simulated tools, no outside effect (32). */
52
+ sandbox: true;
53
+ results?: Record<string, unknown>;
54
+ }
55
+
56
+ /** Weight of each error by its business severity (23). */
57
+ export interface ErrorCostPolicy extends Scope { agentId?: string; domain: string; falsePositive: number; falseNegative: number }
58
+
59
+ /** A measure that must not get worse while another improves (22). */
60
+ export interface Metric { name: string; direction: 'higher_is_better' | 'lower_is_better'; before: number; after: number }
61
+ export interface CounterMetric extends Metric { maxRegression: number; protectedSet?: boolean }
62
+
63
+ export interface ToolReliability {
64
+ organisationId?: string; window?: { from: string; to: string }; tool: string; provider: string | null;
65
+ calls: number; knownCalls: number; unknownCalls: number; failures: number; emptyResults: number; slowCalls: number;
66
+ errorRate: number | null; emptyRate: number; slowRate: number;
67
+ errorStatistics: HonestStatistics; emptyStatistics: HonestStatistics; slowStatistics: HonestStatistics; latencyP95Ms: number;
68
+ }
69
+
70
+ /** Business periods taken into account before blaming the agent (29). */
71
+ export interface DomainCalendar extends Scope { domain: string; name: string; periods: Array<{ label: string; from: string; to: string; kind: string }> }
72
+
73
+ /** A candidate strategy observing real requests without acting (21), always in a sandbox (32). */
74
+ export interface ShadowRun { id: string; organisationId: string; candidate: { kind: string; id: string; version: string }; baseline: { kind: string; id: string; version: string }; sandbox: true; from: string; to?: string; comparisons: number; status: 'running' | 'stopped' | 'completed' }
75
+
76
+ export interface StatisticsOptions { minimumSample?: number; level?: 0.9 | 0.95 | 0.99 }
77
+ export interface Interval { low: number; high: number; level: number }
78
+ export interface HonestStatistics {
79
+ succeeded: number; failed: number; unknown: number; sampleSize: number; minimumSample: number;
80
+ rate: number | null; interval: Interval | null; status: 'observed' | 'insufficient_data';
81
+ conclusion: 'descriptive_only' | 'refuse_to_conclude';
82
+ }
83
+ export interface PredictionPoint { decisionId: string; agentId: string; domain: string; probability: number; status: 'succeeded' | 'failed' | 'unknown' }
84
+ export interface CalibrationResult extends HonestStatistics {
85
+ agentId: string; domain: string; brierScore: number | null; confidenceGap: number | null; overconfidence: number | null; underconfidence: number | null;
86
+ curve: Array<{ bucket: { low: number; high: number }; count: number; predicted: number | null; observed: number | null; interval: Interval | null; status: 'observed' | 'insufficient_data' }>;
87
+ }
88
+ export interface ErrorCostScore { falsePositives: number; falseNegatives: number; sampleSize: number; unknown: number; totalCost: number; weightedScore: number | null; status: 'observed' | 'insufficient_data' }
89
+ export interface CycleOptions { findingWeight?: number; proposalWeight?: number; costWeight?: number; uselessCycles?: number; reductionFactor?: number }
90
+ export interface CycleUtility { usefulFindings: number; acceptedProposals: number; cost: number; benefit: number | null; utility: number | null; useful: boolean | null; status?: 'unmeasured' }
91
+ export type CycleMeasurement = Pick<ReflectionRun, 'id' | 'organisationId' | 'status'> & Partial<ReflectionRun>;
92
+ export interface Conflict { lessonIds: string[]; subject: string; domain: string; status: 'open'; lessonStatus: 'to_reassess'; preferredLessonId: string | null; newerLessonId: string; reason: 'stronger_evidence' | 'inconclusive'; evidence: Evidence[] }
93
+ export interface EvaluationInput extends Scope, StatisticsOptions, CycleOptions {
94
+ agentId?: string; window?: { from: string; to: string }; decisionIds?: string[]; runId?: string; signal?: AbortSignal;
95
+ buckets?: number; decisionThreshold?: number; slowMs?: number;
96
+ claimRules?: Readonly<Record<string, readonly string[]>>; calendars?: DomainCalendar[]; errorCostPolicies?: ErrorCostPolicy[];
97
+ targetMetric?: Metric; counterMetrics?: CounterMetric[]; reflectionRuns?: CycleMeasurement[]; competingExplanations?: string[];
98
+ }
99
+ export interface EvaluateOutcomesOptions extends EvaluationInput { governor: Governor; conscience: Conscience }
100
+ export interface Evaluator { evaluate(input: EvaluationInput): Promise<ReflectionFinding[]> }
101
+ export type RunReflectionOptions = EvaluateOutcomesOptions;
102
+ export function evaluateOutcomes(options: EvaluateOutcomesOptions): Promise<ReflectionFinding[]>;
103
+ export function runReflection(options: RunReflectionOptions): Promise<ReflectionFinding[]>;
104
+ export function createEvaluator(options: { governor: Governor; conscience: Conscience } & Partial<EvaluationInput>): Evaluator;
105
+ export function wilsonInterval(successes: number, total: number, level?: 0.9 | 0.95 | 0.99): Interval | null;
106
+ export function honestStatistics(statuses: Array<'succeeded' | 'failed' | 'unknown'>, options?: StatisticsOptions): HonestStatistics;
107
+ export function calibratePredictions(points: PredictionPoint[], options?: StatisticsOptions & { buckets?: number }): CalibrationResult[];
108
+ export function scoreErrorCosts(points: PredictionPoint[], policy: Pick<ErrorCostPolicy, 'domain' | 'falsePositive' | 'falseNegative'>, options?: StatisticsOptions & { decisionThreshold?: number }): ErrorCostScore;
109
+ export function classifyCorrection(input: { class?: CorrectionClass; tags?: string[] }): CorrectionClass;
110
+ export function checkReasoningFidelity(justification?: Justification, traces?: ToolTrace[], rules?: Readonly<Record<string, readonly string[]>>): { status: 'unfaithful' | 'faithful' | 'unknown'; unsupported: string[]; uncheckable: string[] };
111
+ export function toolReliability(traces: ToolTrace[], options?: StatisticsOptions & { slowMs?: number }): ToolReliability[];
112
+ export function calendarConfounders(domain: string, at: string, calendars?: DomainCalendar[]): { status: 'calendar_confounded' | 'not_confounded'; periods: Array<{ calendar: string; label: string; from: string; to: string }> };
113
+ export function checkCounterMetrics(target: Metric, counters: CounterMetric[]): { status: 'no_improvement' | 'accepted' | 'rejected'; improvement: number; measures: Array<{ name: string; regression: number; maxRegression: number }>; violations: Array<{ name: string; regression: number; maxRegression: number }> };
114
+ export function reflectionUtility(run: Partial<ReflectionRun>, options?: CycleOptions): CycleUtility;
115
+ export function recommendReflectionFrequency(runs: CycleMeasurement[], options?: CycleOptions): { recommendation: 'reduce' | 'maintain'; uselessStreak: number; intervalMultiplier: number };
116
+ export function evaluateLessonConflicts(lessons: LessonVersion[], options?: StatisticsOptions): Conflict[];
117
+ export function oppositeLessons(a: Partial<LessonVersion>, b: Partial<LessonVersion>): boolean;
118
+ export function assessedLessonStatus(input: { evidence: Evidence[]; sampleSize: number; contradictions?: string[]; factualEligible?: boolean }, options?: StatisticsOptions): 'hypothesis' | 'verified' | 'to_reassess';
119
+ export const DEFAULT_CLAIM_RULES: Readonly<Record<string, readonly string[]>>;
120
+ export const AVAILABLE_FROM: 'P2';
121
+
122
+ /** P3 experiments (first half). Candidate functions are serialized into isolated workers;
123
+ * closures, host callbacks, network and filesystem APIs are unavailable. */
124
+ export type ExperimentData = null | boolean | number | string | ExperimentData[] | { [key: string]: ExperimentData };
125
+ export type DeepReadonlyExperiment<T> = T extends (...args: any[]) => any ? T : T extends object ? { readonly [K in keyof T]: DeepReadonlyExperiment<T[K]> } : T;
126
+ export interface ExperimentBinding { governor: Governor; organisationId: string }
127
+ export interface SimulatedToolDescriptor {
128
+ kind: 'read' | 'write' | 'confirm';
129
+ /** Real implementations are ignored, including read tools with side effects. */
130
+ execute?: (...args: any[]) => unknown;
131
+ response?: ExperimentData;
132
+ recordings?: Array<{ input: ExperimentData; output: ExperimentData }>;
133
+ }
134
+ export type SandboxTools = Record<string, SimulatedToolDescriptor | ((...args: any[]) => unknown)>;
135
+ export interface SandboxJournalEntry { sequence: number; tool: string; kind: 'read' | 'write'; input: ExperimentData; simulated: true; caseId?: string }
136
+ export interface Sandbox {
137
+ readonly tools: Readonly<Record<string, (input?: ExperimentData) => Promise<ExperimentData>>>;
138
+ getJournal(): Promise<SandboxJournalEntry[]>;
139
+ }
140
+ export function createSandbox(options: ExperimentBinding & { tools?: SandboxTools }): Promise<Sandbox>;
141
+ /** Self-contained function. A model's computation may be embedded here; it never judges scores. */
142
+ export type ExperimentAgent = (input: any, tools: Readonly<Record<string, (input?: ExperimentData) => Promise<ExperimentData>>>) => unknown | Promise<unknown>;
143
+ export interface ExperimentCase { id: string; input: ExperimentData; expected: ExperimentData }
144
+ export interface ExperimentMetric { name: string; kind: 'exact_match'; outputKey?: string; expectedKey?: string }
145
+ export interface AggregateExperimentScore { sandbox: true; metrics: Record<string, HonestStatistics> }
146
+ export interface ExperimentStageScore extends AggregateExperimentScore { journal?: SandboxJournalEntry[] }
147
+ export interface HoldoutAccess { sequence: number; action: 'read_denied' | 'reserved' | 'evaluation_started' | 'evaluation_completed' | 'evaluation_failed' | 'evaluation_denied' | 'registration_failed'; at: string }
148
+ export interface HoldoutEvaluationOptions extends StatisticsOptions {
149
+ agent: ExperimentAgent; metrics?: ExperimentMetric[]; tools?: SandboxTools; sandbox?: Sandbox; timeoutMs?: number; organisationId?: string;
150
+ }
151
+ /** Only provisioning code supplies cases. Never hand their originals to reflection.
152
+ * The handle permits one opaque evaluation; all content reads throw holdout_protected. */
153
+ export interface ProtectedHoldout {
154
+ evaluate(options: HoldoutEvaluationOptions): Promise<AggregateExperimentScore>;
155
+ getAccessLog(): Promise<HoldoutAccess[]>;
156
+ read(): never;
157
+ }
158
+ export function createHoldout(options: ExperimentBinding & { cases: ExperimentCase[] }): Promise<ProtectedHoldout>;
159
+ export interface TemporalExperimentData extends Scope { at: string | number; recordedAt: string | number; data: ExperimentData }
160
+ export interface ReplayProposal { agent: ExperimentAgent; information?: TemporalExperimentData[] }
161
+ export type ReplaySelection = { decisionIds: string[]; window?: never } | { decisionIds?: never; window: { from: import('../index').DateInput; to: import('../index').DateInput } };
162
+ export type ReplayDecisionsOptions = ExperimentBinding & Scope & ReplaySelection & {
163
+ conscience: Conscience; proposal: ReplayProposal; asOf: import('../index').DateInput;
164
+ agentId?: string; snapshots?: Record<string, TemporalExperimentData>; tools?: SandboxTools; sandbox?: Sandbox; timeoutMs?: number;
165
+ };
166
+ export interface ReplayResult {
167
+ purpose: 'compatibility_only'; provesProgress: false; causality: 'not_established'; sandbox: true;
168
+ cases: Array<{ decisionId: string; asOf: string; status: 'completed' | 'unknown'; compatible: boolean | null; output?: ExperimentData; intentions: number; journal: SandboxJournalEntry[] }>;
169
+ }
170
+ export function replayDecisions(options: ReplayDecisionsOptions): Promise<ReplayResult>;
171
+ export interface ExperimentProtocol extends StatisticsOptions {
172
+ development: ExperimentCase[]; validation: ExperimentCase[]; timeoutMs?: number;
173
+ /** Additional plain JSON protocol fields are retained in the frozen fingerprint. */
174
+ [key: string]: unknown;
175
+ }
176
+ export interface ProposeExperimentOptions extends ExperimentBinding {
177
+ id?: string; hypothesis: string; metrics: ExperimentMetric[]; protocol: ExperimentProtocol;
178
+ thresholds: Record<string, number>; holdout: ProtectedHoldout; agent: ExperimentAgent; tools?: SandboxTools; now?(): number;
179
+ }
180
+ declare const preregisteredExperiment: unique symbol;
181
+ export type RegisteredExperiment = DeepReadonlyExperiment<{
182
+ readonly [preregisteredExperiment]: true;
183
+ id: string; organisationId: string; hypothesis: string; metrics: ExperimentMetric[];
184
+ protocol: ExperimentProtocol & { minimumSample: number; level: 0.9 | 0.95 | 0.99; timeoutMs: number };
185
+ thresholds: Record<string, number>; candidateFingerprint: string; toolsFingerprint: string;
186
+ registrationId: string; registeredAt: string; fingerprint: string; sandbox: true;
187
+ }>;
188
+ export function proposeExperiment(options: ProposeExperimentOptions): Promise<RegisteredExperiment>;
189
+ export interface RunExperimentOptions extends ExperimentBinding {
190
+ experiment: RegisteredExperiment;
191
+ /** Optional repeats are compared with the registration; changes are refused even after execution. */
192
+ protocol?: ExperimentProtocol; metrics?: ExperimentMetric[]; thresholds?: Record<string, number>; hypothesis?: string; agent?: ExperimentAgent; tools?: SandboxTools;
193
+ }
194
+ export interface ExperimentResult {
195
+ experimentId: string; fingerprint: string; registeredAt: string; sandbox: true;
196
+ decision: 'supported' | 'refuted' | 'inconclusive'; causality: 'not_established'; interval: Interval | null;
197
+ stages: { development: ExperimentStageScore; validation: ExperimentStageScore; holdout: AggregateExperimentScore };
198
+ }
199
+ export function runExperiment(options: RunExperimentOptions): Promise<ExperimentResult>;
200
+ /* P3 · vigilance (2/2). */
201
+ export * from './vigilance';
202
+ /* P4 · shadow mode. */
203
+ export * from './shadow';
@@ -0,0 +1,116 @@
1
+ 'use strict';
2
+ const { assertGovernorReady } = require('../governor/governor');
3
+ const { fingerprintOf } = require('../governor/util');
4
+ const statistics = require('./statistics');
5
+ const signals = require('./signals');
6
+ const lessons = require('./lessons');
7
+ const { invalid } = statistics;
8
+ const { ConscienceError } = require('../errors');
9
+ const AVAILABLE_FROM = 'P2';
10
+
11
+ /** Evaluate stored P1 records without persisting derived data or drawing causal conclusions. */
12
+ async function evaluateOutcomes(options = {}) {
13
+ await assertGovernorReady(options.governor, { organisationId: options.organisationId });
14
+ const { conscience, organisationId, userId, agentId } = options;
15
+ let window = options.window;
16
+ options.governor.assertSingleOrganisation(organisationId);
17
+ if (!conscience || conscience.governor !== options.governor) invalid('conscience must use the supplied governor.');
18
+ statistics.minimum(options.minimumSample);
19
+ if (window && (!Number.isFinite(Date.parse(window.from)) || !Number.isFinite(Date.parse(window.to)) || Date.parse(window.from) >= Date.parse(window.to))) invalid('Invalid evaluation window.');
20
+ if (window) window = { from: new Date(window.from).toISOString(), to: new Date(window.to).toISOString() };
21
+ const scope = { organisationId, userId };
22
+ let decisions;
23
+ if (options.decisionIds) {
24
+ if (!Array.isArray(options.decisionIds) || !options.decisionIds.every((id) => typeof id === 'string')) invalid('decisionIds must be strings.');
25
+ decisions = (await Promise.all([...new Set(options.decisionIds)].map((id) => conscience.getDecision(scope, id)))).filter(Boolean);
26
+ decisions = decisions.filter((d) => (!agentId || d.agentId === agentId) && (!window || (d.decidedAt >= window.from && d.decidedAt < window.to)));
27
+ } else {
28
+ decisions = await conscience.recallDecisions(scope, { agentId, from: window?.from, to: window?.to, limit: 1000, order: 'asc' });
29
+ if (decisions.length === 1000) throw new ConscienceError('evaluation_limit', 'Use explicit decisionIds to evaluate 1000 or more decisions without truncation.');
30
+ }
31
+ const inScope = (record) => {
32
+ if (typeof record.organisationId !== 'string' || !record.organisationId.trim()) invalid('Evaluation configuration requires organisationId.');
33
+ options.governor.assertSingleOrganisation(organisationId, record.organisationId);
34
+ if (userId != null && record.userId != null && record.userId !== userId) invalid('Cross-person evaluation input.');
35
+ };
36
+ for (const list of [options.calendars ?? [], options.errorCostPolicies ?? [], options.reflectionRuns ?? []]) for (const r of list) inScope(r);
37
+ const findings = [], points = [], allTraces = [], currentLessons = await conscience.listLessons(scope, { agentId });
38
+ const runId = options.runId ?? `evaluation_${fingerprintOf({ organisationId, userId, agentId, window, decisionIds: decisions.map((d) => d.id) }).slice(0, 24)}`;
39
+ const add = (kind, data) => {
40
+ const content = { runId, organisationId, kind, decisionIds: [], observation: kind, evidence: [], evidenceDegree: 'observational', confidence: 0,
41
+ severity: 'low', sampleSize: 0, interval: null, status: 'observed', causality: 'not_established',
42
+ competingExplanations: ['chance', 'environment', 'decision_method'], confounders: [], ...data };
43
+ findings.push({ id: `finding_${fingerprintOf(content).slice(0, 24)}`, ...content });
44
+ };
45
+ for (const d of decisions) {
46
+ options.signal?.throwIfAborted();
47
+ const lineage = await conscience.getLineage(scope, d.id);
48
+ const outcomes = lineage.outcomes.filter((o) => o.current);
49
+ const predictions = [...lineage.predictions].sort((a, b) => a.madeAt.localeCompare(b.madeAt) || a.id.localeCompare(b.id));
50
+ const last = new Map();
51
+ for (const p of predictions) last.set(p.domain ?? d.domain ?? 'general', p);
52
+ for (const [domain, p] of last) {
53
+ const matched = outcomes.filter((o) => (!p.sensor || p.sensor === o.sensor) && (!o.predictionId || o.predictionId === p.id));
54
+ const o = matched.length === 1 ? matched[0] : null;
55
+ // A prediction made after observing its outcome cannot be calibrated.
56
+ const status = o && p.madeAt <= o.observedAt ? o.status : 'unknown';
57
+ points.push({ decisionId: d.id, predictionId: p.id, outcomeId: o?.id ?? null, agentId: d.agentId, domain, probability: p.probability, status });
58
+ }
59
+ const traces = d.toolTrace ?? [];
60
+ allTraces.push(...traces);
61
+ const fidelity = signals.checkReasoningFidelity(d.justification, traces, options.claimRules);
62
+ if (fidelity.status !== 'unknown') add('reasoning_fidelity', { decisionIds: [d.id], evidence: [{ kind: 'decision', ref: d.id }], sampleSize: 1,
63
+ confidence: 1, status: fidelity.status, severity: fidelity.status === 'unfaithful' ? 'high' : 'low', details: fidelity });
64
+ for (const o of outcomes) {
65
+ const calendar = signals.calendarConfounders(d.domain ?? 'general', o.observedAt, options.calendars);
66
+ add('outcome', { decisionIds: [d.id], evidence: [{ kind: 'outcome', ref: o.id }], sampleSize: o.status === 'unknown' ? 0 : 1,
67
+ confidence: o.status === 'unknown' ? 0 : 1 - (o.uncertainty ?? 0), status: calendar.status === 'calendar_confounded' ? calendar.status : o.status,
68
+ confounders: [...o.confounders, ...calendar.periods.map((p) => p.label)], competingExplanations: options.competingExplanations ?? ['chance', 'environment', 'decision_method'],
69
+ details: { outcomeStatus: o.status, methodStatus: fidelity.status, calendar, generalRule: null } });
70
+ }
71
+ for (const c of lineage.corrections) add('correction', { decisionIds: [d.id], evidence: [{ kind: 'correction', ref: c.id }], sampleSize: 1,
72
+ status: 'observed', confidence: 1, details: { class: signals.classifyCorrection(c), factualLessonEligible: c.class === 'factual' } });
73
+ }
74
+ for (const calibration of statistics.calibratePredictions(points, options)) {
75
+ const group = points.filter((p) => p.agentId === calibration.agentId && p.domain === calibration.domain);
76
+ add('calibration', { agentId: calibration.agentId, domain: calibration.domain, decisionIds: group.map((p) => p.decisionId),
77
+ evidence: group.flatMap((p) => [{ kind: 'prediction', ref: p.predictionId }, ...(p.outcomeId ? [{ kind: 'outcome', ref: p.outcomeId }] : [])]),
78
+ sampleSize: calibration.sampleSize, interval: calibration.interval, status: calibration.status,
79
+ confidence: calibration.status === 'observed' ? calibration.interval.level : 0, details: calibration });
80
+ const policies = (options.errorCostPolicies ?? []).filter((p) => p.domain === calibration.domain && (!p.agentId || p.agentId === calibration.agentId));
81
+ if (policies.length > 1) invalid('Ambiguous error cost policy.');
82
+ if (policies.length) add('error_cost', { agentId: calibration.agentId, domain: calibration.domain, sampleSize: calibration.sampleSize,
83
+ decisionIds: group.map((p) => p.decisionId), evidence: group.filter((p) => p.outcomeId).map((p) => ({ kind: 'outcome', ref: p.outcomeId })),
84
+ status: calibration.status, details: statistics.scoreErrorCosts(group, policies[0], options) });
85
+ }
86
+ for (const reliability of signals.toolReliability(allTraces, options)) add('tool_reliability', {
87
+ sampleSize: reliability.knownCalls, interval: reliability.errorStatistics.interval, status: reliability.errorStatistics.status, details: reliability,
88
+ evidence: decisions.filter((d) => (d.toolTrace ?? []).some((t) => t.tool === reliability.tool && (t.provider ?? null) === reliability.provider)).map((d) => ({ kind: 'decision', ref: d.id })) });
89
+ for (const conflict of lessons.evaluateLessonConflicts(currentLessons, options)) add('contradiction', { status: 'to_reassess', evidence: conflict.evidence, details: conflict });
90
+ if (options.targetMetric) {
91
+ const check = signals.checkCounterMetrics(options.targetMetric, options.counterMetrics ?? []);
92
+ add('anti_goodhart', { status: check.status, details: check });
93
+ }
94
+ const runs = (options.reflectionRuns ?? []).filter((r) => !agentId || r.agentId === agentId);
95
+ if (runs.length) add('reflection_quality', { evidence: runs.map((r) => ({ kind: 'external', ref: r.id })), sampleSize: runs.filter((r) => r.status === 'completed').length,
96
+ details: { runs: runs.map((r) => ({ id: r.id, ...signals.reflectionUtility(r, options) })), frequency: signals.recommendReflectionFrequency(runs, options) } });
97
+ return findings;
98
+ }
99
+ async function runReflection(options) { return evaluateOutcomes(options); }
100
+ function createEvaluator(options) {
101
+ return Object.freeze({ evaluate: (input) => evaluateOutcomes({ ...options, ...input, governor: options.governor, conscience: options.conscience }) });
102
+ }
103
+ module.exports = { runReflection, evaluateOutcomes, createEvaluator, AVAILABLE_FROM,
104
+ wilsonInterval: statistics.wilsonInterval, honestStatistics: statistics.honestStatistics,
105
+ calibratePredictions: statistics.calibratePredictions, scoreErrorCosts: statistics.scoreErrorCosts, ...signals, ...lessons };
106
+
107
+ // P3 experiments (first half); append-only integration with the evaluation core.
108
+ const { createSandbox } = require('./experiments/sandbox');
109
+ const { replayDecisions } = require('./experiments/replay');
110
+ const { createHoldout } = require('./experiments/holdout');
111
+ const { proposeExperiment, runExperiment } = require('./experiments/laboratory');
112
+ Object.assign(module.exports, { createSandbox, replayDecisions, createHoldout, proposeExperiment, runExperiment });
113
+ /* P3 · vigilance (2/2): drift, follow-ups, abstention, night adversary, multi-role review, lessons turned into tests. */
114
+ Object.assign(module.exports, require('./vigilance'));
115
+ /* P4 · shadow mode: a candidate approved by humans processes real requests in silence, in the sandbox, and is compared with the stable strategy. */
116
+ Object.assign(module.exports, require('./shadow'));
@@ -0,0 +1,32 @@
1
+ 'use strict';
2
+ const { minimum } = require('./statistics');
3
+ const DEGREE = ['none', 'anecdotal', 'observational', 'experimental', 'replicated'];
4
+ function oppositeLessons(a, b) {
5
+ return a.id !== b.id && a.organisationId === b.organisationId && a.userId === b.userId && a.agentId === b.agentId
6
+ && a.domain === b.domain && a.subject != null && a.subject === b.subject && a.stance != null && b.stance != null && a.stance !== b.stance
7
+ && a.status !== 'retired' && b.status !== 'retired';
8
+ }
9
+ /** Recommendations only: conflicting lessons stay open until explicitly arbitrated. Newer alone is not proof. */
10
+ function evaluateLessonConflicts(lessons, options = {}) {
11
+ const conflicts = [];
12
+ for (let i = 0; i < lessons.length; i += 1) {
13
+ for (const b of lessons.slice(i + 1)) {
14
+ const a = lessons[i];
15
+ if (!oppositeLessons(a, b)) continue;
16
+ const sufficient = (l) => l.evidence.length > 0 && (l.sampleSize ?? 0) >= minimum(options.minimumSample);
17
+ const rank = (l) => sufficient(l) ? DEGREE.indexOf(l.evidenceDegree) : -1;
18
+ const ar = rank(a), br = rank(b);
19
+ const newer = (a.validFrom ?? a.recordedAt) > (b.validFrom ?? b.recordedAt) ? a : b;
20
+ const preferred = ar > br ? a : br > ar ? b : null;
21
+ conflicts.push({ lessonIds: [a.id, b.id].sort(), subject: a.subject, domain: a.domain, status: 'open', lessonStatus: 'to_reassess',
22
+ preferredLessonId: preferred?.id ?? null, newerLessonId: newer.id, reason: preferred ? 'stronger_evidence' : 'inconclusive',
23
+ evidence: [...a.evidence, ...b.evidence] });
24
+ }
25
+ }
26
+ return conflicts;
27
+ }
28
+ function assessedLessonStatus({ evidence, sampleSize, contradictions = [], factualEligible = true }, options = {}) {
29
+ if (contradictions.length) return 'to_reassess';
30
+ return evidence.length && sampleSize >= minimum(options.minimumSample) && factualEligible ? 'verified' : 'hypothesis';
31
+ }
32
+ module.exports = { oppositeLessons, evaluateLessonConflicts, assessedLessonStatus };
@@ -0,0 +1,69 @@
1
+ 'use strict';
2
+ /*
3
+ * Which strategy may run in the shadow? Only one that humans already approved:
4
+ * a governor object version in the "candidate" state (it was staged from an
5
+ * approved proposal), or a proposal in the "approved" state with human
6
+ * approvals. A pending, declined, rejected or expired proposal is refused, and
7
+ * so is a stable or discarded version. Re-checked before every run.
8
+ */
9
+ const { ConscienceError } = require('../../errors');
10
+ const { fingerprintOf } = require('../../governor/util');
11
+ const { isNonEmptyString } = require('../vigilance/common');
12
+
13
+ const refuse = (code, message) => { throw new ConscienceError(code, message); };
14
+
15
+ function approvedByHumans(proposal) {
16
+ return proposal.status === 'approved' && Array.isArray(proposal.approvals) && proposal.approvals.length > 0
17
+ && proposal.approvals.every((a) => a?.approver?.kind === 'human' && isNonEmptyString(a.approver.id));
18
+ }
19
+
20
+ async function approvedProposal(governor, organisationId, proposalId) {
21
+ const proposal = await governor.getProposal(organisationId, proposalId);
22
+ if (!proposal) refuse('not_found', 'Proposal not found.');
23
+ if (proposal.organisationId !== organisationId) refuse('cross_organisation', 'The proposal belongs to another organisation.');
24
+ if (!approvedByHumans(proposal)) {
25
+ refuse('candidate_not_approved', `Proposal is ${proposal.status}: only a proposal approved by humans may run in the shadow.`);
26
+ }
27
+ return proposal;
28
+ }
29
+
30
+ /**
31
+ * @param reference `{ proposalId }` or `{ kind, id, versionId? }`
32
+ * @returns the verified description of the candidate strategy (data only)
33
+ */
34
+ async function resolveCandidate(governor, organisationId, reference) {
35
+ if (!reference || typeof reference !== 'object') refuse('invalid_input', 'candidate must name a governor object version or an approved proposal.');
36
+ const byProposal = reference.proposalId != null, byVersion = reference.kind != null || reference.id != null;
37
+ if (byProposal === byVersion) refuse('invalid_input', 'candidate: give either { proposalId } or { kind, id }.');
38
+ if (byProposal) {
39
+ if (!isNonEmptyString(reference.proposalId)) refuse('invalid_input', 'proposalId must be a non-empty string.');
40
+ const proposal = await approvedProposal(governor, organisationId, reference.proposalId);
41
+ const content = proposal.change;
42
+ return { source: 'proposal', kind: proposal.target.kind, id: proposal.target.id, versionId: null, proposalId: proposal.id, content,
43
+ fingerprint: fingerprintOf({ proposalId: proposal.id, proposal: proposal.fingerprint, content }) };
44
+ }
45
+ if (!isNonEmptyString(reference.kind) || !isNonEmptyString(reference.id)) refuse('invalid_input', 'candidate needs kind and id.');
46
+ const at = { organisationId, kind: reference.kind, id: reference.id };
47
+ const object = await governor.getObject(at);
48
+ if (!object) refuse('not_found', 'Object not registered.');
49
+ if (!object.candidate) refuse('candidate_not_staged', 'This object has no candidate version: only a candidate may run in the shadow.');
50
+ if (reference.versionId != null && reference.versionId !== object.candidate) refuse('candidate_not_staged', 'That version is not the candidate of this object.');
51
+ const version = (await governor.listVersions(at)).find((v) => v.versionId === object.candidate);
52
+ if (!version || version.status !== 'candidate') refuse('candidate_not_staged', 'The candidate version cannot be read.');
53
+ if (version.source !== 'proposal' || !isNonEmptyString(version.proposalId)) refuse('candidate_not_approved', 'A candidate version must come from an approved proposal.');
54
+ // The governor staged it from an approved proposal; check again that the approval is still a human one.
55
+ await approvedProposalOrExpired(governor, organisationId, version.proposalId);
56
+ return { source: 'version', kind: at.kind, id: at.id, versionId: version.versionId, proposalId: version.proposalId, content: version.content,
57
+ fingerprint: fingerprintOf({ kind: at.kind, id: at.id, versionId: version.versionId, version: version.fingerprint }) };
58
+ }
59
+
60
+ /* A staged proposal keeps the "approved" status; only a lapsed approval changes it. A lapsed approval does not undo a staged candidate. */
61
+ async function approvedProposalOrExpired(governor, organisationId, proposalId) {
62
+ const proposal = await governor.getProposal(organisationId, proposalId);
63
+ if (!proposal) refuse('not_found', 'Proposal not found.');
64
+ const humans = Array.isArray(proposal.approvals) && proposal.approvals.length > 0 && proposal.approvals.every((a) => a?.approver?.kind === 'human');
65
+ if (!['approved', 'expired'].includes(proposal.status) || !humans) refuse('candidate_not_approved', `The proposal behind this candidate is ${proposal.status}.`);
66
+ return proposal;
67
+ }
68
+
69
+ module.exports = { resolveCandidate };
@@ -0,0 +1,169 @@
1
+ /** P4 · shadow mode (21 shadow mode, 32 sandbox of the shadow mode). Deterministic: no language model, nothing is ever applied or promoted. */
2
+ import type { Governor, ChangeProposal } from '../../governor';
3
+ import type { Interval, HonestStatistics, StatisticsOptions, Sandbox, ExperimentAgent, ExperimentData } from '../index';
4
+ import type { Masker, Actor } from '../vigilance';
5
+
6
+ /** Rows of the shadow store: one ShadowRun per sampled request, already masked. */
7
+ export interface ShadowStore {
8
+ putShadowRun(record: ShadowRun): Promise<{ record: ShadowRun; created: boolean }>;
9
+ getShadowRun(organisationId: string, id: string): Promise<ShadowRun | null>;
10
+ listShadowRuns(filter: { organisationId: string; shadowId?: string; userId?: string | null; limit?: number }): Promise<ShadowRun[]>;
11
+ removeShadowRuns(subject: { organisationId: string; userId: string }): Promise<number>;
12
+ }
13
+ export function createMemoryShadowStore(): ShadowStore;
14
+ export function createPostgresShadowStore(db: { query(sql: string, params?: unknown[]): Promise<{ rows: any[]; rowCount?: number | null }> }, options?: { prefix?: string }): ShadowStore;
15
+ export function postgresShadowSchema(options?: { prefix?: string }): string;
16
+ /** Eraser for `createConscience({ erasers: [...] })`: removes the shadow runs of a person with the rest of their data. */
17
+ export function shadowEraser(store: Pick<ShadowStore, 'removeShadowRuns'>): (subject: { organisationId: string; userId: string }) => Promise<{ name: 'shadow_runs'; count: number }>;
18
+
19
+ export type ShadowConclusion = 'insufficient_data' | 'regression' | 'no_difference' | 'promising';
20
+ export const SHADOW_CONCLUSIONS: readonly ShadowConclusion[];
21
+ export type ShadowScore = 'succeeded' | 'failed' | 'unknown';
22
+
23
+ /** A strategy that may run in the shadow: a candidate version of a governor object, or a proposal approved by humans (never a pending or declined one). */
24
+ export type ShadowCandidateReference = { proposalId: string; kind?: never; id?: never; versionId?: never } | { kind: string; id: string; versionId?: string; proposalId?: never };
25
+ export interface ShadowCandidateInput {
26
+ /**
27
+ * Self-contained function, serialised into the P3 sandbox. Called as `agent({ input, version }, tools)`:
28
+ * `input` is the request, `version` the content of the governed version. A model call can only be a sandbox tool (simulated or recorded).
29
+ */
30
+ agent: ExperimentAgent;
31
+ }
32
+ export interface ShadowCandidate {
33
+ source: 'version' | 'proposal'; kind: string; id: string; versionId: string | null; proposalId: string | null;
34
+ fingerprint: string; agentFingerprint: string;
35
+ }
36
+
37
+ export interface ShadowMetric {
38
+ /** Lower-case code: `accuracy`, `sources_accuracy`... */
39
+ name: string;
40
+ /** Deterministic judgement of one answer. true: good; false: bad; null: cannot tell (excluded from the statistics). Receives the real request. */
41
+ score(input: { input: any; output: any; side: 'candidate' | 'stable' }): boolean | null | Promise<boolean | null>;
42
+ /** A candidate failure where the stable strategy succeeded is a critical regression (listed, and enough for `regression`). */
43
+ critical?: boolean;
44
+ /** Anti-Goodhart: how much the success rate may drop (absolute, 0 to 1) while the target improves. Default 0.02. */
45
+ maxRegression?: number;
46
+ }
47
+ export interface ShadowBudget {
48
+ maxRuns?: number; maxCost?: number;
49
+ /** Measured sandbox time. May be exceeded by the runs in flight. */
50
+ maxDurationMs?: number;
51
+ /** Ceiling reserved for one run (default 1). `costOf` can only lower it. */
52
+ costPerRun?: number;
53
+ costOf?(run: { durationMs: number; status: 'completed' | 'failed'; writeIntentions: number; output: any }): number;
54
+ /** Also spend through `governor.authorizeSpend` for this agent: the governor budgets apply and a refusal stops the shadow. */
55
+ governorAgentId?: string;
56
+ }
57
+ export interface ShadowRunnerOptions extends StatisticsOptions {
58
+ governor: Governor; organisationId: string;
59
+ candidate: ShadowCandidateInput & ShadowCandidateReference;
60
+ /** Built with `createSandbox` for the same governor and organisation. Every tool of the candidate goes through it. */
61
+ sandbox: Sandbox;
62
+ /** Share of the requests, in ]0, 1], decided by a hash of the request id: deterministic and nested. */
63
+ sampleRate: number;
64
+ budget: ShadowBudget;
65
+ /** Required: nothing is stored unmasked. A function, a `@astratra/privacy` redactor, or an object with `mask()`. */
66
+ masker: Masker;
67
+ metrics: ShadowMetric[];
68
+ /** The metric the candidate is meant to improve; every other metric (and `limits.cost`) is a counter-measure. At least one is required. */
69
+ target: string;
70
+ limits?: { cost?: number };
71
+ store?: ShadowStore;
72
+ /** Sandbox time limit of one run (10 to 30000, default 1000). */
73
+ timeoutMs?: number;
74
+ /** Deadline of the whole background work of one request (default timeoutMs + 3000). */
75
+ deadlineMs?: number;
76
+ /** Simultaneous background runs (default 4). More are skipped as `busy`, never queued. */
77
+ maxConcurrent?: number;
78
+ maxCriticalRegressions?: number;
79
+ /** A candidate whose incident rate is significantly above this is a regression (default 0.05). */
80
+ maxIncidentRate?: number;
81
+ id?: string; now?(): number;
82
+ }
83
+
84
+ export interface ShadowObservation {
85
+ request: { id: string; userId?: string | null; input: ExperimentData };
86
+ stableResult: { output: ExperimentData; durationMs?: number; cost?: number };
87
+ /** Recorded results of read tools for this request, replayed to the candidate (never for a write tool). */
88
+ recordings?: Record<string, Array<{ input: ExperimentData; output: ExperimentData }>>;
89
+ }
90
+ /** What `observe` says in the background. It never carries an answer of the candidate. */
91
+ export type ShadowOutcome =
92
+ | { status: 'recorded'; runId: string; created: boolean }
93
+ | { status: 'skipped'; reason: 'not_sampled' | 'busy' | 'duplicate' | 'budget_exhausted' | 'governor_halted' | 'governor_unavailable' | 'governor_budget' | 'candidate_unavailable' | 'candidate_changed' }
94
+ | { status: 'rejected'; reason: 'invalid_input' }
95
+ | { status: 'timeout'; reason: 'deadline' }
96
+ | { status: 'error'; reason: string };
97
+ export interface ShadowHandle {
98
+ /** The request was selected and a background run started. */
99
+ scheduled: boolean;
100
+ /** Why it was not, when it was not. */
101
+ reason: string | null;
102
+ /** Never rejects. Do not wait for it before answering the user. */
103
+ done: Promise<ShadowOutcome>;
104
+ }
105
+
106
+ export interface ShadowRun {
107
+ id: string; shadowId: string; organisationId: string; userId: string | null; createdAt: string; sampleRate: number;
108
+ candidate: ShadowCandidate & { status: 'completed' | 'error' | 'timeout'; reason: string | null; output: ExperimentData; outputFingerprint: string };
109
+ request: { input: ExperimentData; fingerprint: string };
110
+ stable: { output: ExperimentData; outputFingerprint: string; durationMs: number | null };
111
+ scores: Record<string, { candidate: ShadowScore; stable: ShadowScore }>;
112
+ /** Same answer from both strategies. */
113
+ agreement: boolean;
114
+ /** Writes the candidate tried: journalled, never executed. */
115
+ writeIntentions: Array<{ sequence: number; tool: string; input: ExperimentData }>;
116
+ toolCalls: { read: number; write: number };
117
+ durationMs: number; cost: number; stableCost: number | null;
118
+ incidents: string[];
119
+ }
120
+
121
+ export interface ShadowMetricReport {
122
+ name: string; critical: boolean; status: 'observed' | 'insufficient_data';
123
+ candidate: HonestStatistics; stable: HonestStatistics;
124
+ paired: { bothSucceeded: number; onlyStableSucceeded: number; onlyCandidateSucceeded: number; bothFailed: number; unknown: number };
125
+ /** Candidate minus stable success rate, Newcombe interval on the Wilson intervals of P2. null below the minimum sample. */
126
+ difference: { difference: number; low: number; high: number; level: number } | null;
127
+ }
128
+ export interface ShadowReport {
129
+ organisationId: string; shadowId: string; candidate: ShadowCandidate; generatedAt: string;
130
+ conclusion: ShadowConclusion; reasons: string[];
131
+ sample: { runs: number; minimumSample: number; level: number; status: 'observed' | 'insufficient_data'; firstAt: string | null; lastAt: string | null; sampleRates: number[] };
132
+ target: string; metrics: Record<string, ShadowMetricReport>;
133
+ /** The check of P2 (target against counter-measures); null while the target has too few observations. */
134
+ antiGoodhart: null | { target: string; status: 'accepted' | 'rejected' | 'no_improvement'; improvement: number; violations: Array<{ name: string; regression: number; maxRegression: number }>; measures: Array<{ name: string; regression: number; maxRegression: number }>; counterMeasures: number };
135
+ criticalRegressions: Array<{ runId: string; metric: string; createdAt: string; request: { input: ExperimentData; fingerprint: string }; candidateOutput: ExperimentData; stableOutput: ExperimentData; incidents: string[] }>;
136
+ incidents: { runs: number; rate: number | null; interval: Interval | null; byCode: Record<string, number>; status: 'observed' | 'insufficient_data'; maxRate: number };
137
+ agreement: HonestStatistics;
138
+ writeIntentions: { total: number; runsWithWrites: number; byTool: Record<string, number>; neverExecuted: true };
139
+ cost: { total: number | null; mean: number | null; stableMean: number | null };
140
+ durationMs: { mean: number | null; max: number | null };
141
+ stopped: null | { reason: string; at: string };
142
+ /** A shadow comparison on real requests can make an improvement promising, never established. */
143
+ provesImprovement: false; causality: 'not_established'; applied: false;
144
+ /** With `propose` and a promising result: a PENDING proposal at the governor. A human decides; deployment and promotion stay theirs. */
145
+ proposal: ChangeProposal | null;
146
+ finding: unknown | null;
147
+ }
148
+ export interface ShadowReportOptions extends Partial<StatisticsOptions> {
149
+ propose?: { proposedBy?: Actor; owner?: string; risk?: 'low' | 'medium' | 'high' | 'critical' };
150
+ recordedBy?: Actor;
151
+ }
152
+ export interface ShadowRunner {
153
+ readonly id: string; readonly candidate: ShadowCandidate; readonly sampleRate: number;
154
+ /**
155
+ * Hands the request and the stable result to the shadow. Synchronous, never throws, never waits: call it when the stable answer is
156
+ * ready (or already sent) and do not await `done`. The candidate answer is stored masked and returned to nobody.
157
+ */
158
+ observe(observation: ShadowObservation): ShadowHandle;
159
+ report(options?: ShadowReportOptions): Promise<ShadowReport>;
160
+ /** Waits for the background runs in progress (tests, shutdown). */
161
+ flush(): Promise<void>;
162
+ listRuns(options?: { limit?: number }): Promise<ShadowRun[]>;
163
+ eraseSubject(subject: { organisationId: string; userId: string }): Promise<{ removed: number }>;
164
+ readonly eraser: (subject: { organisationId: string; userId: string }) => Promise<{ name: 'shadow_runs'; count: number }>;
165
+ stats(): { seen: number; sampled: number; executed: number; recorded: number; skipped: Record<string, number>; errors: Record<string, number>; inflight: number; stopped: { reason: string; at: string } | null };
166
+ /** True once the budget is spent, the kill switch was pulled or the candidate left the candidate state. It does not restart by itself. */
167
+ isStopped(): boolean;
168
+ }
169
+ export function createShadowRunner(options: ShadowRunnerOptions): Promise<ShadowRunner>;
@@ -0,0 +1,11 @@
1
+ 'use strict';
2
+ /* P4 · shadow mode (21 shadow mode, 32 sandbox of the shadow mode). */
3
+ const runner = require('./runner');
4
+ const store = require('./store');
5
+ const report = require('./report');
6
+
7
+ module.exports = {
8
+ createShadowRunner: runner.createShadowRunner, SHADOW_CONCLUSIONS: report.CONCLUSIONS,
9
+ createMemoryShadowStore: store.createMemoryShadowStore, createPostgresShadowStore: store.createPostgresShadowStore,
10
+ postgresShadowSchema: store.postgresShadowSchema, shadowEraser: store.shadowEraser
11
+ };