@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.
Files changed (53) hide show
  1. package/LICENSE +21 -0
  2. package/README.fr.md +901 -0
  3. package/README.md +864 -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 +308 -0
  41. package/src/governor/index.js +20 -0
  42. package/src/governor/policy.js +136 -0
  43. package/src/governor/postgres.js +243 -0
  44. package/src/governor/review.js +191 -0
  45. package/src/governor/rollout.js +66 -0
  46. package/src/governor/stores.js +136 -0
  47. package/src/governor/util.js +53 -0
  48. package/src/guard.js +21 -0
  49. package/src/index.d.ts +244 -0
  50. package/src/index.js +23 -0
  51. package/src/memoryStore.js +65 -0
  52. package/src/postgres.js +93 -0
  53. package/src/records.js +220 -0
@@ -0,0 +1,136 @@
1
+ 'use strict';
2
+ const { copy } = require('./util');
3
+
4
+ const proposalKey = (organisationId, id) => `${organisationId}\u0000${id}`;
5
+ const boundedLimit = (limit, fallback = 100) => Math.min(Math.max(Number(limit) || fallback, 1), 1000);
6
+
7
+ function sumsOf(entries, entry, limits) {
8
+ let cycle = 0; let agent = 0; let organisation = 0;
9
+ for (const row of entries) {
10
+ if (row.organisationId !== entry.organisationId) continue;
11
+ if (entry.cycleId != null && row.cycleId === entry.cycleId) cycle += row.cost;
12
+ if (row.at < limits.since) continue;
13
+ organisation += row.cost;
14
+ if (row.agentId === entry.agentId) agent += row.cost;
15
+ }
16
+ return { cycle, agent, organisation };
17
+ }
18
+
19
+ const objectKey = (organisationId, kind, id) => `${organisationId}\u0000${kind}\u0000${id}`;
20
+ const approvalCount = (record) => (Array.isArray(record.approvals) ? record.approvals.length : 0);
21
+ const decidedOrCreated = (record) => record.decidedAt ?? record.createdAt;
22
+
23
+ /**
24
+ * Governor store kept in memory: proposals, audit journal, spending, controls.
25
+ * Copies on every read and write; lost when the process exits.
26
+ */
27
+ function createMemoryGovernorStore() {
28
+ const proposals = new Map();
29
+ const audit = [];
30
+ const spend = new Map();
31
+ const controls = new Map();
32
+ const objects = new Map();
33
+ const versions = new Map();
34
+ const findings = new Map();
35
+ return {
36
+ async putProposal(record) {
37
+ const key = proposalKey(record.organisationId, record.id);
38
+ const old = proposals.get(key);
39
+ if (old) return { record: copy(old), created: false };
40
+ proposals.set(key, copy(record));
41
+ return { record: copy(record), created: true };
42
+ },
43
+ async getProposal(organisationId, id) { return copy(proposals.get(proposalKey(organisationId, id))); },
44
+ async transitionProposal(organisationId, id, fromStatus, patch, guard) {
45
+ const key = proposalKey(organisationId, id);
46
+ const old = proposals.get(key);
47
+ if (!old || old.status !== fromStatus) return null;
48
+ if (guard?.approvals !== undefined && approvalCount(old) !== guard.approvals) return null;
49
+ const next = { ...old, ...copy(patch) };
50
+ proposals.set(key, next);
51
+ return copy(next);
52
+ },
53
+ async listProposals(filter = {}) {
54
+ return [...proposals.values()]
55
+ .filter((p) => p.organisationId === filter.organisationId && (filter.status == null || p.status === filter.status)
56
+ && (filter.statuses == null || filter.statuses.includes(p.status))
57
+ && (filter.since == null || decidedOrCreated(p) >= filter.since))
58
+ .sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0))
59
+ .slice(0, boundedLimit(filter.limit)).map(copy);
60
+ },
61
+ async appendAudit(entry) { audit.push(copy(entry)); return copy(entry); },
62
+ async listAudit(filter = {}) {
63
+ return audit
64
+ .filter((e) => (filter.organisationId === undefined || e.organisationId === filter.organisationId)
65
+ && (filter.proposalId == null || e.proposalId === filter.proposalId)
66
+ && (filter.actions == null || filter.actions.includes(e.action))
67
+ && (filter.since == null || e.at >= filter.since)
68
+ && (filter.objectKind == null || e.objectKind === filter.objectKind)
69
+ && (filter.objectId == null || e.objectId === filter.objectId))
70
+ .slice(-boundedLimit(filter.limit)).reverse().map(copy);
71
+ },
72
+ async reserveSpend(entry, limits) {
73
+ const key = proposalKey(entry.organisationId, entry.id);
74
+ const entries = [...spend.values()];
75
+ if (spend.has(key)) return { reserved: true, created: false, totals: sumsOf(entries, entry, limits) };
76
+ const totals = sumsOf(entries, entry, limits);
77
+ const fits = (entry.cycleId == null || totals.cycle + entry.cost <= limits.perCycle)
78
+ && totals.agent + entry.cost <= limits.perAgent
79
+ && totals.organisation + entry.cost <= limits.perOrganisation;
80
+ if (!fits) return { reserved: false, created: false, totals };
81
+ spend.set(key, copy(entry));
82
+ return { reserved: true, created: true, totals: sumsOf([...spend.values()], entry, limits) };
83
+ },
84
+ async getControl(key) { return controls.has(key) ? copy(controls.get(key)) : null; },
85
+ async setControl(key, value) { controls.set(key, copy(value)); return copy(value); },
86
+
87
+ async getObject(organisationId, kind, id) { return copy(objects.get(objectKey(organisationId, kind, id))); },
88
+ async createObject(state) {
89
+ const key = objectKey(state.organisationId, state.kind, state.id);
90
+ if (objects.has(key)) return { record: copy(objects.get(key)), created: false };
91
+ objects.set(key, copy(state));
92
+ return { record: copy(state), created: true };
93
+ },
94
+ async updateObject(organisationId, kind, id, expectedRevision, next) {
95
+ const key = objectKey(organisationId, kind, id);
96
+ const old = objects.get(key);
97
+ if (!old || old.revision !== expectedRevision) return null;
98
+ objects.set(key, copy(next));
99
+ return copy(next);
100
+ },
101
+ async listObjects(filter = {}) {
102
+ return [...objects.values()]
103
+ .filter((o) => (filter.organisationId == null || o.organisationId === filter.organisationId)
104
+ && (filter.kind == null || o.kind === filter.kind) && (!filter.hasCandidate || o.candidate != null))
105
+ .sort((a, b) => (objectKey(a.organisationId, a.kind, a.id) < objectKey(b.organisationId, b.kind, b.id) ? -1 : 1))
106
+ .slice(0, boundedLimit(filter.limit)).map(copy);
107
+ },
108
+ async putVersion(record) {
109
+ const key = `${objectKey(record.organisationId, record.kind, record.id)}\u0000${record.versionId}`;
110
+ if (versions.has(key)) return { record: copy(versions.get(key)), created: false };
111
+ versions.set(key, copy(record));
112
+ return { record: copy(record), created: true };
113
+ },
114
+ async getVersion(organisationId, kind, id, versionId) { return copy(versions.get(`${objectKey(organisationId, kind, id)}\u0000${versionId}`)); },
115
+ async listVersions(filter) {
116
+ return [...versions.values()]
117
+ .filter((v) => v.organisationId === filter.organisationId && v.kind === filter.kind && v.id === filter.id)
118
+ .sort((a, b) => a.number - b.number).slice(0, boundedLimit(filter.limit, 1000)).map(copy);
119
+ },
120
+
121
+ async putFinding(record) {
122
+ const key = proposalKey(record.organisationId, record.id);
123
+ if (findings.has(key)) return { record: copy(findings.get(key)), created: false };
124
+ findings.set(key, copy(record));
125
+ return { record: copy(record), created: true };
126
+ },
127
+ async listFindings(filter = {}) {
128
+ return [...findings.values()]
129
+ .filter((f) => f.organisationId === filter.organisationId && (filter.since == null || f.receivedAt >= filter.since) && (filter.until == null || f.receivedAt <= filter.until))
130
+ .sort((a, b) => (a.receivedAt < b.receivedAt ? 1 : a.receivedAt > b.receivedAt ? -1 : a.id < b.id ? -1 : 1))
131
+ .slice(0, boundedLimit(filter.limit)).map(copy);
132
+ }
133
+ };
134
+ }
135
+
136
+ module.exports = { createMemoryGovernorStore, boundedLimit };
@@ -0,0 +1,53 @@
1
+ 'use strict';
2
+ /*
3
+ * Plain helpers of the governor. This folder imports Node built-ins and its own
4
+ * files only: no language model, no AI package, nothing that could make a
5
+ * governance decision depend on generated text. A test walks the import graph.
6
+ */
7
+ const crypto = require('node:crypto');
8
+
9
+ class GovernorError extends Error {
10
+ constructor(code, message) {
11
+ super(message);
12
+ this.name = 'GovernorError';
13
+ this.code = code;
14
+ }
15
+ }
16
+
17
+ /** JSON with sorted keys, so equal values always give the same text. */
18
+ function canonical(value) {
19
+ if (value === undefined) return 'null';
20
+ if (value === null || typeof value !== 'object') return JSON.stringify(value);
21
+ if (value instanceof Date) return JSON.stringify(value.toISOString());
22
+ if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
23
+ const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort();
24
+ return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
25
+ }
26
+
27
+ const sha256 = (text) => crypto.createHash('sha256').update(text).digest('hex');
28
+ const fingerprintOf = (value) => sha256(canonical(value));
29
+ const copy = (value) => (value == null ? null : JSON.parse(JSON.stringify(value)));
30
+
31
+ function deepFreeze(value) {
32
+ if (value && typeof value === 'object' && !Object.isFrozen(value)) {
33
+ Object.freeze(value);
34
+ for (const child of Object.values(value)) deepFreeze(child);
35
+ }
36
+ return value;
37
+ }
38
+
39
+ const isNonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0;
40
+ const SQL_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]{0,40}$/;
41
+
42
+ function prefixOf(options = {}, fallback) {
43
+ const name = options.prefix ?? fallback;
44
+ if (typeof name !== 'string' || !SQL_IDENTIFIER.test(name)) throw new Error('prefix must be a plain SQL identifier of at most 41 characters.');
45
+ return name;
46
+ }
47
+
48
+ function requireQueryable(db) {
49
+ if (!db || typeof db.query !== 'function') throw new Error('A database with query(sql, params) is required.');
50
+ return db;
51
+ }
52
+
53
+ module.exports = { GovernorError, canonical, sha256, fingerprintOf, copy, deepFreeze, isNonEmptyString, prefixOf, requireQueryable };
package/src/guard.js ADDED
@@ -0,0 +1,21 @@
1
+ 'use strict';
2
+ /*
3
+ * Memory guard (34). Everything this package stores (context, observations,
4
+ * lessons, corrections) is untrusted data: it may have been written by a
5
+ * person, a tool or a model that was itself manipulated. Nothing here ever
6
+ * reads stored text as an instruction, and the helpers below frame it before
7
+ * a future model reads it, with the framing of @astratra/ai/guards.
8
+ */
9
+ const { frameUntrusted } = require('@astratra/ai/guards');
10
+
11
+ /** Frames one stored text as data for a model. */
12
+ function frameStoredText(text, { source = 'conscience-memory', nonce } = {}) {
13
+ return frameUntrusted(String(text ?? ''), { source, nonce });
14
+ }
15
+
16
+ /** Frames records (decisions, outcomes, lessons...) as one JSON block of data. */
17
+ function frameRecordsForModel(records, { source = 'conscience-memory', nonce } = {}) {
18
+ return frameUntrusted(JSON.stringify(records ?? [], null, 2), { source, nonce });
19
+ }
20
+
21
+ module.exports = { frameStoredText, frameRecordsForModel };
package/src/index.d.ts ADDED
@@ -0,0 +1,244 @@
1
+ import type { Governor, Queryable } from './governor';
2
+ export { assertGovernorReady, isGovernor, GovernorError } from './governor';
3
+
4
+ export type RecordKind = 'decision' | 'prediction' | 'outcome' | 'correction' | 'lesson' | 'self_model';
5
+ export type OutcomeStatus = 'succeeded' | 'failed' | 'unknown';
6
+ export type CorrectionClass = 'factual' | 'style' | 'objective' | 'disagreement';
7
+ export type LessonStatus = 'hypothesis' | 'verified' | 'to_reassess' | 'retired';
8
+ export type EvidenceDegree = 'none' | 'anecdotal' | 'observational' | 'experimental' | 'replicated';
9
+ export type EvidenceKind = 'decision' | 'prediction' | 'outcome' | 'correction' | 'external';
10
+ export type ProvenanceKind = 'sensor' | 'tool' | 'human' | 'feedback' | 'system' | 'model';
11
+ export type DateInput = string | number | Date;
12
+
13
+ /** Read and write scope: one organisation, optionally one person. */
14
+ export interface Scope { organisationId: string; userId?: string | null }
15
+ export interface Provenance { kind: ProvenanceKind; id: string }
16
+
17
+ export interface ToolTrace { callId: string; tool: string; provider?: string | null; status: OutcomeStatus; empty?: boolean; durationMs: number; labels?: string[] }
18
+ export interface Justification { claims?: string[] }
19
+
20
+ export interface DecisionInput extends Scope {
21
+ domain?: string; justification?: Justification; toolTrace?: ToolTrace[];
22
+ /** Stable id; derived from the content when absent (the same decision twice is one row). */
23
+ id?: string;
24
+ agentId: string;
25
+ objective: string;
26
+ /** Dated context. `data` strings are masked before storage. */
27
+ context: { at: DateInput; summary?: string; data?: unknown };
28
+ action: { name: string; kind?: string; input?: unknown };
29
+ alternatives?: Array<string | { name: string; reason?: string }>;
30
+ expectedOutcome: { description: string; metric?: string; target?: unknown };
31
+ /** When the outcome should be observable. */
32
+ horizon: DateInput;
33
+ /** 0 to 1. */
34
+ confidence: number;
35
+ permissions?: string[];
36
+ versions: { model?: string; tools?: unknown; instructions?: string };
37
+ /** Reference to a snapshot of the inputs, kept by your application. */
38
+ inputSnapshotRef?: string;
39
+ tools?: Array<{ name: string; version?: string; callId?: string }>;
40
+ /** Defaults to context.at. */
41
+ decidedAt?: DateInput;
42
+ }
43
+
44
+ export interface DecisionRecord {
45
+ domain: string; justification: Justification; toolTrace: ToolTrace[];
46
+ id: string; organisationId: string; userId: string | null; agentId: string; objective: string;
47
+ context: { at: string; summary: string | null; data: unknown };
48
+ action: { name: string; kind: string | null; input: unknown };
49
+ alternatives: Array<{ name: string; reason: string | null }>;
50
+ expectedOutcome: { description: string; metric: string | null; target: unknown };
51
+ horizon: string; confidence: number; permissions: string[];
52
+ versions: { model: string | null; tools: unknown; instructions: string | null };
53
+ inputSnapshotRef: string | null; tools: Array<{ name: string; version: string | null; callId: string | null }>;
54
+ decidedAt: string; recordedAt: string; subjectErased?: boolean;
55
+ }
56
+
57
+ export interface PredictionInput extends Scope { domain?: string; sensor?: string; id?: string; decisionId: string; statement: string; probability: number; resolvesBy: DateInput; madeAt?: DateInput }
58
+ export interface PredictionRecord { domain: string; sensor: string | null; id: string; organisationId: string; userId: string | null; agentId: string; decisionId: string; statement: string; probability: number; resolvesBy: string; madeAt: string; recordedAt: string }
59
+
60
+ export interface OutcomeInput extends Scope {
61
+ predictionId?: string;
62
+ id?: string; decisionId: string; status: OutcomeStatus; observation?: string; sensor: string; sources?: string[];
63
+ /** 0 (certain) to 1 (no idea). */
64
+ uncertainty?: number; confounders?: string[]; provenance: Provenance; observedAt: DateInput;
65
+ }
66
+ export interface OutcomeRecord {
67
+ predictionId: string | null;
68
+ id: string; organisationId: string; userId: string | null; agentId: string; decisionId: string; status: OutcomeStatus;
69
+ observation: string | null; sensor: string; sources: string[]; uncertainty: number | null; confounders: string[];
70
+ provenance: Provenance; observedAt: string; recordedAt: string;
71
+ /** Previous outcome of the same sensor when this one was recorded. */
72
+ revises: string | null;
73
+ }
74
+ export interface OutcomeVersion extends OutcomeRecord { revision: number; current: boolean; supersededAt: string | null }
75
+
76
+ export interface CorrectionInput extends Scope {
77
+ id?: string; decisionId: string;
78
+ /** What the agent proposed and the final version. Masked, then only the difference is kept. */
79
+ proposed: string; final: string;
80
+ class?: CorrectionClass; tags?: Array<'fact_changed' | 'wording_changed' | 'goal_changed' | 'opinion_changed'>; authorRole: string; correctedAt: DateInput;
81
+ }
82
+ export interface MaskedDelta { removed: string; added: string; removedWords: number; addedWords: number; totalWordsBefore: number; totalWordsAfter: number; unchanged: boolean }
83
+ export interface CorrectionRecord { id: string; organisationId: string; userId: string | null; agentId: string; decisionId: string; class: CorrectionClass; authorRole: string; correctedAt: string; delta: MaskedDelta; recordedAt: string }
84
+
85
+ export interface Evidence { kind: EvidenceKind; ref: string; note?: string | null }
86
+ export interface LessonInput extends Scope {
87
+ domain?: string; subject?: string | null; stance?: 'supports' | 'opposes' | null; factual?: boolean; minimumSample?: number;
88
+ /** Same lessonId = a new revision of the same lesson. */
89
+ lessonId?: string; agentId?: string; summary: string; evidence?: Evidence[]; evidenceDegree?: EvidenceDegree;
90
+ /** Computed from evidence and independent sample size; open conflicts force to_reassess. */
91
+ status?: LessonStatus;
92
+ validFrom?: DateInput; validUntil?: DateInput; contradictions?: string[]; supersedes?: string[];
93
+ consent?: unknown; retention?: unknown; scenarioRef?: string;
94
+ }
95
+ export interface MemoryLesson {
96
+ domain: string; subject: string | null; stance: 'supports' | 'opposes' | null; factual: boolean; minimumSample: number; sampleSize: number; factualEligible: boolean;
97
+ id: string; revisionId: string; previousRevision: string | null; contentFingerprint: string;
98
+ organisationId: string; userId: string | null; agentId: string | null; summary: string;
99
+ evidence: Array<{ kind: EvidenceKind; ref: string; note: string | null }>; evidenceDegree: EvidenceDegree; status: LessonStatus;
100
+ validFrom: string | null; validUntil: string | null; contradictions: string[]; supersedes: string[];
101
+ consent: unknown; retention: unknown; scenarioRef: string | null; statusForced: boolean; recordedAt: string;
102
+ }
103
+ export interface LessonVersion extends MemoryLesson { storedStatus?: LessonStatus; revision: number; current: boolean; supersededAt: string | null }
104
+
105
+ export interface SelfModelInput extends Scope {
106
+ agentId: string;
107
+ /** Each capability needs test evidence (scenario ids, reports): nothing is assumed. */
108
+ capabilities?: Array<{ name: string; evidence: string[]; score?: number; testedAt?: DateInput }>;
109
+ tools?: Array<{ name: string; version?: string }>; limits?: string[]; permissions?: string[]; domains?: string[];
110
+ metrics?: Record<string, number>; provenance: Provenance; at?: DateInput;
111
+ }
112
+ export interface SelfModelSnapshot {
113
+ id: string; revisionId: string; previousRevision: string | null; contentFingerprint: string;
114
+ organisationId: string; userId: string | null; agentId: string;
115
+ capabilities: Array<{ name: string; evidence: string[]; score: number | null; testedAt: string | null }>;
116
+ tools: Array<{ name: string; version: string | null }>; limits: string[]; permissions: string[]; domains: string[];
117
+ metrics: Record<string, number>; provenance: Provenance; at: string; recordedAt: string;
118
+ }
119
+
120
+ export interface TimelineEntry {
121
+ kind: RecordKind; id: string; revisionId: string | null; revision: number; current: boolean; decisionId: string | null;
122
+ /** When it happened. */ eventAt: string | null;
123
+ /** When it was written down. */ recordedAt: string;
124
+ validFrom: string | null; validUntil: string | null;
125
+ /** Recording time of the next revision. */ supersededAt: string | null;
126
+ status: string | null;
127
+ }
128
+
129
+ export interface Lineage {
130
+ objective: string; decision: DecisionRecord; action: DecisionRecord['action']; tools: DecisionRecord['tools'];
131
+ predictions: PredictionRecord[]; outcomes: OutcomeVersion[]; corrections: CorrectionRecord[]; lessons: LessonVersion[];
132
+ chain: ['objective', 'action', 'tools', 'outcomes', 'corrections', 'lessons'];
133
+ }
134
+
135
+ export interface ErasureReport {
136
+ organisationId: string; mode: 'delete' | 'anonymise';
137
+ removed: { decisions: number; predictions: number; outcomes: number; corrections: number; lessons: number };
138
+ anonymised: number;
139
+ /** Lessons of the organisation that cited erased records: references removed, back to 'hypothesis' when none is left. */
140
+ lessonsUpdated: number;
141
+ extensions: Array<{ name: string; count: number }>;
142
+ completedAt: string;
143
+ }
144
+
145
+ /** What a store keeps: an immutable envelope with indexed columns and the record itself in `data`. */
146
+ export interface RecordEnvelope<T = any> {
147
+ kind: RecordKind; id: string; organisationId: string; userId: string | null; agentId: string | null;
148
+ decisionId: string | null; lessonId: string | null; eventAt: string | null; recordedAt: string;
149
+ fingerprint: string; evidenceRefs: string[]; data: T;
150
+ }
151
+ export interface RecordFilter {
152
+ organisationId: string; userId?: string | null; agentId?: string | null; decisionId?: string | null; lessonId?: string | null;
153
+ decisionIds?: string[]; evidenceRef?: string; eventFrom?: string; eventTo?: string;
154
+ /** Inclusive upper bound on recordedAt ("as of"). */ recordedTo?: string;
155
+ limit?: number; order?: 'asc' | 'desc';
156
+ }
157
+ /**
158
+ * Storage of the conscience. Five methods; see README to write one for
159
+ * another database. Order: recordedAt, then insertion order.
160
+ */
161
+ export interface ConscienceStore {
162
+ /** Insert once; an existing (organisationId, kind, id) is returned unchanged with created: false. */
163
+ put(envelope: RecordEnvelope): Promise<{ record: RecordEnvelope; created: boolean }>;
164
+ get(kind: RecordKind, organisationId: string, id: string): Promise<RecordEnvelope | null>;
165
+ list(kind: RecordKind, filter: RecordFilter): Promise<RecordEnvelope[]>;
166
+ /** Erasure and retention only. */
167
+ replace(envelope: RecordEnvelope): Promise<RecordEnvelope | null>;
168
+ remove(kind: RecordKind, organisationId: string, ids: string[]): Promise<number>;
169
+ }
170
+
171
+ export type Masker = ((text: string) => string | Promise<string>) | { redactString(text: string): string } | { mask(text: string): string | Promise<string> };
172
+
173
+ export interface ConscienceOptions {
174
+ /** Minimum independent known outcomes/factual corrections for verification; default 30. */
175
+ minimumSample?: number;
176
+ /** Required: built by createGovernor() of @astratra/conscience/governor. */
177
+ governor: Governor;
178
+ /** Required: applied to every free text before storage. Should be deterministic. */
179
+ masker: Masker;
180
+ /** Default: memory store (lost on exit). */
181
+ store?: ConscienceStore;
182
+ now?(): number;
183
+ retention?: {
184
+ /** What eraseSubject does. Default 'delete'. */
185
+ erasure?: 'delete' | 'anonymise';
186
+ /** Used by applyRetention() only; nothing is deleted on a timer. */
187
+ maxAgeDays?: Partial<Record<RecordKind, number>>;
188
+ };
189
+ /** Called by eraseSubject for data kept elsewhere (vectors, indexes, caches, calibrations). */
190
+ erasers?: Array<(subject: { organisationId: string; userId: string }) => Promise<{ name: string; count: number }> | { name: string; count: number }>;
191
+ onEvent?(event: { type: 'conscience'; action: string; organisationId: string; [key: string]: unknown }): void | Promise<void>;
192
+ }
193
+
194
+ export interface Conscience {
195
+ readonly store: ConscienceStore;
196
+ readonly governor: Governor;
197
+ readonly retention: { erasure: 'delete' | 'anonymise'; maxAgeDays: Partial<Record<RecordKind, number>> };
198
+ recordDecision(input: DecisionInput): Promise<{ decision: DecisionRecord; created: boolean }>;
199
+ recordPrediction(input: PredictionInput): Promise<{ prediction: PredictionRecord; created: boolean }>;
200
+ /** A later outcome of the same sensor is a new revision; the earlier one is kept. */
201
+ attachOutcome(input: OutcomeInput): Promise<{ outcome: OutcomeVersion; created: boolean }>;
202
+ recordCorrection(input: CorrectionInput): Promise<{ correction: CorrectionRecord; created: boolean }>;
203
+ /** Reflective write: requires a ready governor. */
204
+ recordLesson(input: LessonInput): Promise<{ lesson: MemoryLesson; created: boolean; statusForced: boolean }>;
205
+ /** Reflective write: requires a ready governor. */
206
+ resolveLessonConflict(input: Scope & { winnerId: string; loserId: string; evidence: Evidence[] }): Promise<{ winner: MemoryLesson; loser: MemoryLesson }>;
207
+ updateSelfModel(input: SelfModelInput): Promise<{ snapshot: SelfModelSnapshot; created: boolean }>;
208
+ getDecision(scope: Scope, id: string): Promise<DecisionRecord | null>;
209
+ getOutcomes(scope: Scope & { asOf?: DateInput }, decisionId: string): Promise<OutcomeVersion[]>;
210
+ recallDecisions(scope: Scope, query?: { agentId?: string; from?: DateInput; to?: DateInput; asOf?: DateInput; limit?: number; order?: 'asc' | 'desc'; withOutcomes?: boolean }): Promise<Array<DecisionRecord & { outcomes?: OutcomeVersion[] }>>;
211
+ getLesson(scope: Scope, lessonId: string, options?: { asOf?: DateInput }): Promise<{ current: LessonVersion; history: LessonVersion[] } | null>;
212
+ listLessons(scope: Scope, filter?: { agentId?: string; status?: LessonStatus; validAt?: DateInput; asOf?: DateInput }): Promise<LessonVersion[]>;
213
+ getSelfModel(scope: Scope, agentId: string, options?: { asOf?: DateInput }): Promise<SelfModelSnapshot | null>;
214
+ getSelfModelHistory(scope: Scope, agentId: string): Promise<Array<SelfModelSnapshot & { revision: number; current: boolean; supersededAt: string | null }>>;
215
+ getMemoryTimeline(scope: Scope, query?: { axis?: 'event' | 'recorded'; from?: DateInput; to?: DateInput; asOf?: DateInput; validAt?: DateInput; kinds?: RecordKind[]; agentId?: string }): Promise<TimelineEntry[]>;
216
+ getLineage(scope: Scope, decisionId: string): Promise<Lineage | null>;
217
+ eraseSubject(subject: { organisationId: string; userId: string }): Promise<ErasureReport>;
218
+ applyRetention(options: { organisationId: string }): Promise<{ organisationId: string; removed: Partial<Record<RecordKind, number>>; lessonsUpdated: number; completedAt: string }>;
219
+ }
220
+
221
+ export function createConscience(options: ConscienceOptions): Conscience;
222
+ export function createMemoryConscienceStore(): ConscienceStore;
223
+ export function createPostgresConscienceStore(db: Queryable, options?: { prefix?: string }): ConscienceStore;
224
+ export function postgresConscienceSchema(options?: { prefix?: string }): string;
225
+ /** Memory guard: frames stored text as untrusted data before a model reads it. */
226
+ export function frameStoredText(text: string, options?: { source?: string; nonce?: string }): string;
227
+ export function frameRecordsForModel(records: unknown, options?: { source?: string; nonce?: string }): string;
228
+ export function wordDelta(before: string, after: string): MaskedDelta;
229
+ export function matchesFilter(envelope: RecordEnvelope, filter: RecordFilter): boolean;
230
+
231
+ export class ConscienceError extends Error {
232
+ code: 'invalid_input' | 'organisation_required' | 'not_found' | 'conflict' | 'evidence_not_found' | 'capability_without_evidence'
233
+ | 'masker_required' | 'masker_invalid' | 'store_invalid' | 'not_available' | string;
234
+ constructor(code: string, message: string);
235
+ }
236
+
237
+ export const RECORD_KINDS: readonly RecordKind[];
238
+ export const OUTCOME_STATUSES: readonly OutcomeStatus[];
239
+ export const CORRECTION_CLASSES: readonly CorrectionClass[];
240
+ export const LESSON_STATUSES: readonly LessonStatus[];
241
+ export const EVIDENCE_DEGREES: readonly EvidenceDegree[];
242
+ export const EVIDENCE_KINDS: readonly EvidenceKind[];
243
+ export const PROVENANCE_KINDS: readonly ProvenanceKind[];
244
+ export const ERASURE_MODES: readonly ['delete', 'anonymise'];
package/src/index.js ADDED
@@ -0,0 +1,23 @@
1
+ 'use strict';
2
+ /*
3
+ * @astratra/conscience (P1): memory of an agent's decisions, outcomes,
4
+ * corrections, lessons with evidence, and self-model, under a governor.
5
+ */
6
+ const { createConscience, ERASURE_MODES } = require('./conscience');
7
+ const { createMemoryConscienceStore, matchesFilter } = require('./memoryStore');
8
+ const { postgresConscienceSchema, createPostgresConscienceStore } = require('./postgres');
9
+ const { frameStoredText, frameRecordsForModel } = require('./guard');
10
+ const { wordDelta } = require('./diff');
11
+ const { ConscienceError } = require('./errors');
12
+ const records = require('./records');
13
+ const { assertGovernorReady, isGovernor } = require('./governor/governor');
14
+ const { GovernorError } = require('./governor/util');
15
+
16
+ module.exports = {
17
+ createConscience, createMemoryConscienceStore, createPostgresConscienceStore, postgresConscienceSchema,
18
+ frameStoredText, frameRecordsForModel, wordDelta, matchesFilter,
19
+ ConscienceError, GovernorError, assertGovernorReady, isGovernor,
20
+ RECORD_KINDS: records.KINDS, OUTCOME_STATUSES: records.OUTCOME_STATUSES, CORRECTION_CLASSES: records.CORRECTION_CLASSES,
21
+ LESSON_STATUSES: records.LESSON_STATUSES, EVIDENCE_DEGREES: records.EVIDENCE_DEGREES, EVIDENCE_KINDS: records.EVIDENCE_KINDS,
22
+ PROVENANCE_KINDS: records.PROVENANCE_KINDS, ERASURE_MODES
23
+ };
@@ -0,0 +1,65 @@
1
+ 'use strict';
2
+ const { copy } = require('./governor/util');
3
+
4
+ const MAX_LIMIT = 10000;
5
+ const limitOf = (value) => Math.min(Math.max(Number(value) || 1000, 1), MAX_LIMIT);
6
+ const keyOf = (kind, organisationId, id) => `${kind}\u0000${organisationId}\u0000${id}`;
7
+
8
+ /** True when an envelope passes a list filter. Shared with tests of other stores. */
9
+ function matchesFilter(row, filter) {
10
+ if (row.organisationId !== filter.organisationId) return false;
11
+ for (const field of ['userId', 'agentId', 'decisionId', 'lessonId']) {
12
+ if (filter[field] !== undefined && row[field] !== filter[field]) return false;
13
+ }
14
+ if (Array.isArray(filter.decisionIds) && !filter.decisionIds.includes(row.decisionId)) return false;
15
+ if (filter.evidenceRef != null && !(row.evidenceRefs || []).includes(filter.evidenceRef)) return false;
16
+ if (filter.eventFrom != null && (row.eventAt == null || row.eventAt < filter.eventFrom)) return false;
17
+ if (filter.eventTo != null && (row.eventAt == null || row.eventAt >= filter.eventTo)) return false;
18
+ if (filter.recordedTo != null && row.recordedAt > filter.recordedTo) return false;
19
+ return true;
20
+ }
21
+
22
+ /**
23
+ * Conscience store kept in memory. Records are immutable envelopes
24
+ * `{ kind, id, organisationId, userId, agentId, decisionId, lessonId, eventAt,
25
+ * recordedAt, fingerprint, evidenceRefs, data }`; `put` never overwrites
26
+ * (idempotent), `replace` and `remove` exist for erasure and retention only.
27
+ */
28
+ function createMemoryConscienceStore() {
29
+ const rows = new Map();
30
+ let seq = 0;
31
+ return {
32
+ async put(envelope) {
33
+ const key = keyOf(envelope.kind, envelope.organisationId, envelope.id);
34
+ const old = rows.get(key);
35
+ if (old) return { record: copy(old.envelope), created: false };
36
+ seq += 1;
37
+ rows.set(key, { seq, envelope: copy(envelope) });
38
+ return { record: copy(envelope), created: true };
39
+ },
40
+ async get(kind, organisationId, id) {
41
+ return copy(rows.get(keyOf(kind, organisationId, id))?.envelope ?? null);
42
+ },
43
+ async list(kind, filter = {}) {
44
+ const found = [...rows.values()]
45
+ .filter(({ envelope }) => envelope.kind === kind && matchesFilter(envelope, filter))
46
+ .sort((a, b) => (a.envelope.recordedAt < b.envelope.recordedAt ? -1 : a.envelope.recordedAt > b.envelope.recordedAt ? 1 : a.seq - b.seq));
47
+ if (filter.order === 'desc') found.reverse();
48
+ return found.slice(0, limitOf(filter.limit)).map(({ envelope }) => copy(envelope));
49
+ },
50
+ async replace(envelope) {
51
+ const key = keyOf(envelope.kind, envelope.organisationId, envelope.id);
52
+ const old = rows.get(key);
53
+ if (!old) return null;
54
+ rows.set(key, { seq: old.seq, envelope: copy(envelope) });
55
+ return copy(envelope);
56
+ },
57
+ async remove(kind, organisationId, ids) {
58
+ let count = 0;
59
+ for (const id of ids) if (rows.delete(keyOf(kind, organisationId, id))) count += 1;
60
+ return count;
61
+ }
62
+ };
63
+ }
64
+
65
+ module.exports = { createMemoryConscienceStore, matchesFilter, MAX_LIMIT };
@@ -0,0 +1,93 @@
1
+ 'use strict';
2
+ const { prefixOf, requireQueryable } = require('./governor/util');
3
+ const { MAX_LIMIT } = require('./memoryStore');
4
+
5
+ const DEFAULT_PREFIX = 'astratra_conscience';
6
+ const limitOf = (value) => Math.min(Math.max(Number(value) || 1000, 1), MAX_LIMIT);
7
+
8
+ /** SQL that creates the conscience table. Idempotent: run it at every start or in a migration. */
9
+ function postgresConscienceSchema(options) {
10
+ const p = prefixOf(options, DEFAULT_PREFIX);
11
+ const table = `"${p}_records"`;
12
+ return `CREATE TABLE IF NOT EXISTS ${table} (
13
+ organisation_id text NOT NULL,
14
+ kind text NOT NULL CHECK (kind IN ('decision', 'prediction', 'outcome', 'correction', 'lesson', 'self_model')),
15
+ id text NOT NULL,
16
+ user_id text,
17
+ agent_id text,
18
+ decision_id text,
19
+ lesson_id text,
20
+ event_at timestamptz,
21
+ recorded_at timestamptz NOT NULL,
22
+ fingerprint text NOT NULL,
23
+ evidence_refs text[] NOT NULL DEFAULT '{}',
24
+ envelope jsonb NOT NULL,
25
+ seq bigserial,
26
+ PRIMARY KEY (organisation_id, kind, id)
27
+ );
28
+ CREATE INDEX IF NOT EXISTS "${p}_recorded_idx" ON ${table} (organisation_id, kind, recorded_at, seq);
29
+ CREATE INDEX IF NOT EXISTS "${p}_user_idx" ON ${table} (organisation_id, user_id);
30
+ CREATE INDEX IF NOT EXISTS "${p}_decision_idx" ON ${table} (organisation_id, kind, decision_id);
31
+ CREATE INDEX IF NOT EXISTS "${p}_lesson_idx" ON ${table} (organisation_id, kind, lesson_id);
32
+ CREATE INDEX IF NOT EXISTS "${p}_event_idx" ON ${table} (organisation_id, kind, event_at);
33
+ CREATE INDEX IF NOT EXISTS "${p}_evidence_idx" ON ${table} USING gin (evidence_refs);`;
34
+ }
35
+
36
+ const read = (row) => (row ? (typeof row.envelope === 'string' ? JSON.parse(row.envelope) : row.envelope) : null);
37
+
38
+ /**
39
+ * Conscience store on PostgreSQL. `db` is any `{ query(sql, params) }` (a
40
+ * `pg` Pool or client). Every value is a SQL parameter; identifiers come from
41
+ * a checked prefix only.
42
+ */
43
+ function createPostgresConscienceStore(db, options) {
44
+ requireQueryable(db);
45
+ const table = `"${prefixOf(options, DEFAULT_PREFIX)}_records"`;
46
+ const columns = (e) => [e.organisationId, e.kind, e.id, e.userId, e.agentId, e.decisionId, e.lessonId, e.eventAt, e.recordedAt, e.fingerprint, e.evidenceRefs || [], JSON.stringify(e)];
47
+
48
+ return {
49
+ async put(envelope) {
50
+ const inserted = await db.query(
51
+ `INSERT INTO ${table} (organisation_id, kind, id, user_id, agent_id, decision_id, lesson_id, event_at, recorded_at, fingerprint, evidence_refs, envelope)
52
+ VALUES ($1, $2, $3, $4, $5, $6, $7, $8::timestamptz, $9::timestamptz, $10, $11::text[], $12::jsonb)
53
+ ON CONFLICT (organisation_id, kind, id) DO NOTHING RETURNING envelope`, columns(envelope));
54
+ if (inserted.rows.length) return { record: read(inserted.rows[0]), created: true };
55
+ return { record: await this.get(envelope.kind, envelope.organisationId, envelope.id), created: false };
56
+ },
57
+ async get(kind, organisationId, id) {
58
+ return read((await db.query(`SELECT envelope FROM ${table} WHERE organisation_id = $1 AND kind = $2 AND id = $3`, [organisationId, kind, id])).rows[0]);
59
+ },
60
+ async list(kind, filter = {}) {
61
+ const params = [filter.organisationId, kind];
62
+ const parts = ['organisation_id = $1', 'kind = $2'];
63
+ const add = (sql, value) => { params.push(value); parts.push(sql.replace('?', `$${params.length}`)); };
64
+ for (const [field, column] of [['userId', 'user_id'], ['agentId', 'agent_id'], ['decisionId', 'decision_id'], ['lessonId', 'lesson_id']]) {
65
+ if (filter[field] === undefined) continue;
66
+ if (filter[field] === null) parts.push(`${column} IS NULL`); else add(`${column} = ?`, filter[field]);
67
+ }
68
+ if (Array.isArray(filter.decisionIds)) add('decision_id = ANY(?::text[])', filter.decisionIds);
69
+ if (filter.evidenceRef != null) add('evidence_refs @> ARRAY[?::text]', filter.evidenceRef);
70
+ if (filter.eventFrom != null) add('event_at >= ?::timestamptz', filter.eventFrom);
71
+ if (filter.eventTo != null) add('event_at < ?::timestamptz', filter.eventTo);
72
+ if (filter.recordedTo != null) add('recorded_at <= ?::timestamptz', filter.recordedTo);
73
+ params.push(limitOf(filter.limit));
74
+ const order = filter.order === 'desc' ? 'DESC' : 'ASC';
75
+ const sql = `SELECT envelope FROM ${table} WHERE ${parts.join(' AND ')} ORDER BY recorded_at ${order}, seq ${order} LIMIT $${params.length}`;
76
+ return (await db.query(sql, params)).rows.map(read);
77
+ },
78
+ async replace(envelope) {
79
+ const result = await db.query(
80
+ `UPDATE ${table} SET user_id = $4, agent_id = $5, decision_id = $6, lesson_id = $7, event_at = $8::timestamptz, recorded_at = $9::timestamptz,
81
+ fingerprint = $10, evidence_refs = $11::text[], envelope = $12::jsonb
82
+ WHERE organisation_id = $1 AND kind = $2 AND id = $3 RETURNING envelope`, columns(envelope));
83
+ return read(result.rows[0]);
84
+ },
85
+ async remove(kind, organisationId, ids) {
86
+ if (!ids.length) return 0;
87
+ const result = await db.query(`DELETE FROM ${table} WHERE organisation_id = $1 AND kind = $2 AND id = ANY($3::text[])`, [organisationId, kind, ids]);
88
+ return result.rowCount ?? 0;
89
+ }
90
+ };
91
+ }
92
+
93
+ module.exports = { postgresConscienceSchema, createPostgresConscienceStore };