@sonate/schemas 2.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 (19) hide show
  1. package/README.md +93 -0
  2. package/dist/index.d.ts +516 -0
  3. package/dist/index.d.ts.map +1 -0
  4. package/dist/index.js +40 -0
  5. package/dist/index.js.map +1 -0
  6. package/dist/receipt.schema.json +501 -0
  7. package/dist/receipt.types.d.ts +457 -0
  8. package/dist/receipt.types.d.ts.map +1 -0
  9. package/dist/receipt.types.js +9 -0
  10. package/dist/receipt.types.js.map +1 -0
  11. package/dist/validator.d.ts +452 -0
  12. package/dist/validator.d.ts.map +1 -0
  13. package/dist/validator.js +194 -0
  14. package/dist/validator.js.map +1 -0
  15. package/package.json +57 -0
  16. package/src/index.ts +56 -0
  17. package/src/receipt.schema.json +501 -0
  18. package/src/receipt.types.ts +571 -0
  19. package/src/validator.ts +200 -0
package/dist/receipt.schema.json ADDED
@@ -0,0 +1,501 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "title": "SONATE Trust Receipt Schema",
4
+ "description": "Cryptographically signed, immutable record of an AI interaction with full audit trail",
5
+ "version": "2.0.0",
6
+ "type": "object",
7
+ "required": [
8
+ "id",
9
+ "version",
10
+ "timestamp",
11
+ "session_id",
12
+ "agent_did",
13
+ "human_did",
14
+ "policy_version",
15
+ "mode",
16
+ "interaction",
17
+ "signature",
18
+ "chain"
19
+ ],
20
+ "properties": {
21
+ "id": {
22
+ "type": "string",
23
+ "description": "Unique receipt identifier (SHA-256 hash of canonical content)",
24
+ "pattern": "^[a-f0-9]{64}$",
25
+ "example": "abcd1234...ef5678"
26
+ },
27
+ "version": {
28
+ "type": "string",
29
+ "description": "Receipt schema version",
30
+ "enum": ["2.0.0"],
31
+ "example": "2.0.0"
32
+ },
33
+ "timestamp": {
34
+ "type": "string",
35
+ "description": "ISO 8601 timestamp of interaction",
36
+ "format": "date-time",
37
+ "example": "2026-02-09T18:30:45.123Z"
38
+ },
39
+ "session_id": {
40
+ "type": "string",
41
+ "description": "Conversation/session identifier for grouping related interactions",
42
+ "example": "session_abc123"
43
+ },
44
+ "agent_did": {
45
+ "type": "string",
46
+ "description": "Decentralized Identifier of the AI agent",
47
+ "pattern": "^did:(web|sonate):.+$",
48
+ "example": "did:web:yseeku.com:agents:demo-agent"
49
+ },
50
+ "human_did": {
51
+ "type": "string",
52
+ "description": "Decentralized Identifier of the human user",
53
+ "pattern": "^did:(web|sonate):.+$",
54
+ "example": "did:web:yseeku.com:users:demo"
55
+ },
56
+ "policy_version": {
57
+ "type": "string",
58
+ "description": "Version of policy that governed this interaction",
59
+ "example": "policy_v1.2.0"
60
+ },
61
+ "mode": {
62
+ "type": "string",
63
+ "enum": ["constitutional", "directive"],
64
+ "description": "Governance mode: constitutional (principle-based) or directive (instruction-based)"
65
+ },
66
+ "interaction": {
67
+ "type": "object",
68
+ "description": "The actual AI interaction data",
69
+ "required": ["model"],
70
+ "properties": {
71
+ "prompt": {
72
+ "type": "string",
73
+ "description": "User's input/question to the AI (omitted when content hashing is enabled)",
74
+ "example": "What is the capital of France?"
75
+ },
76
+ "response": {
77
+ "type": "string",
78
+ "description": "AI's response (omitted when content hashing is enabled)",
79
+ "example": "Paris is the capital of France."
80
+ },
81
+ "prompt_hash": {
82
+ "type": "string",
83
+ "description": "SHA-256 hash of the prompt (privacy-preserving alternative to raw content)",
84
+ "pattern": "^[a-f0-9]{64}$"
85
+ },
86
+ "response_hash": {
87
+ "type": "string",
88
+ "description": "SHA-256 hash of the response (privacy-preserving alternative to raw content)",
89
+ "pattern": "^[a-f0-9]{64}$"
90
+ },
91
+ "model": {
92
+ "type": "string",
93
+ "description": "Model identifier used",
94
+ "example": "gpt-4-turbo"
95
+ },
96
+ "provider": {
97
+ "type": "string",
98
+ "description": "AI provider",
99
+ "enum": ["openai", "anthropic", "aws-bedrock", "local"],
100
+ "example": "openai"
101
+ },
102
+ "temperature": {
103
+ "type": "number",
104
+ "description": "Model temperature setting",
105
+ "minimum": 0,
106
+ "maximum": 2,
107
+ "example": 0.7
108
+ },
109
+ "max_tokens": {
110
+ "type": "integer",
111
+ "description": "Maximum tokens allowed",
112
+ "example": 2000
113
+ },
114
+ "reasoning": {
115
+ "type": "object",
116
+ "description": "Optional: Captured reasoning signals (where available from model)",
117
+ "properties": {
118
+ "thought_process": {
119
+ "type": "string",
120
+ "description": "Internal reasoning if exposed by model"
121
+ },
122
+ "confidence": {
123
+ "type": "number",
124
+ "description": "Model's confidence score (0-1)",
125
+ "minimum": 0,
126
+ "maximum": 1
127
+ },
128
+ "retrieved_context": {
129
+ "type": "array",
130
+ "description": "External context retrieved for this interaction",
131
+ "items": {
132
+ "type": "string"
133
+ }
134
+ }
135
+ }
136
+ }
137
+ }
138
+ },
139
+ "telemetry": {
140
+ "type": "object",
141
+ "description": "Trust and coherence metrics captured at interaction time",
142
+ "properties": {
143
+ "resonance_score": {
144
+ "type": "number",
145
+ "description": "Overall trust/resonance score (0-1)",
146
+ "minimum": 0,
147
+ "maximum": 1,
148
+ "example": 0.94
149
+ },
150
+ "resonance_rm": {
151
+ "type": "number",
152
+ "description": "Deterministic calculator resonance score (R_m, 0-1)",
153
+ "minimum": 0,
154
+ "maximum": 1,
155
+ "example": 0.71
156
+ },
157
+ "trust_resonance_gap": {
158
+ "type": "number",
159
+ "description": "Absolute gap between normalized constitutional trust and calculator R_m",
160
+ "minimum": 0,
161
+ "maximum": 1,
162
+ "example": 0.18
163
+ },
164
+ "resonance_input_mode": {
165
+ "type": "string",
166
+ "enum": ["paired_turns", "labeled_sections", "single_text_fallback"],
167
+ "description": "How the calculator constructed a comparable user/assistant interaction pair"
168
+ },
169
+ "resonance_quality": {
170
+ "type": "string",
171
+ "enum": ["STRONG", "ADVANCED", "BREAKTHROUGH"],
172
+ "description": "Qualitative rating of resonance"
173
+ },
174
+ "bedau_index": {
175
+ "type": "number",
176
+ "description": "Weak emergence detection (0-1)",
177
+ "minimum": 0,
178
+ "maximum": 1,
179
+ "example": 0.73
180
+ },
181
+ "coherence_score": {
182
+ "type": "number",
183
+ "description": "LBC (Longitudinal Behavioral Coherence) score",
184
+ "minimum": 0,
185
+ "maximum": 1,
186
+ "example": 0.82
187
+ },
188
+ "truth_debt": {
189
+ "type": "number",
190
+ "description": "Measure of unverifiable claims (0-1, where 1 = high unverifiability)",
191
+ "minimum": 0,
192
+ "maximum": 1,
193
+ "example": 0.15
194
+ },
195
+ "volatility": {
196
+ "type": "number",
197
+ "description": "Behavioral volatility score (0-1)",
198
+ "minimum": 0,
199
+ "maximum": 1,
200
+ "example": 0.22
201
+ },
202
+ "ciq_metrics": {
203
+ "type": "object",
204
+ "description": "Clarity, Integrity, Quality scores",
205
+ "properties": {
206
+ "clarity": {
207
+ "type": "number",
208
+ "description": "Communication clarity (0-1)",
209
+ "minimum": 0,
210
+ "maximum": 1
211
+ },
212
+ "integrity": {
213
+ "type": "number",
214
+ "description": "Reasoning transparency (0-1)",
215
+ "minimum": 0,
216
+ "maximum": 1
217
+ },
218
+ "quality": {
219
+ "type": "number",
220
+ "description": "Overall value (0-1)",
221
+ "minimum": 0,
222
+ "maximum": 1
223
+ }
224
+ }
225
+ },
226
+ "resonance_components": {
227
+ "type": "object",
228
+ "description": "Calculator component scores before weighted composition",
229
+ "properties": {
230
+ "vector_alignment": {
231
+ "type": "number",
232
+ "minimum": 0,
233
+ "maximum": 1
234
+ },
235
+ "context_continuity": {
236
+ "type": "number",
237
+ "minimum": 0,
238
+ "maximum": 1
239
+ },
240
+ "semantic_mirroring": {
241
+ "type": "number",
242
+ "minimum": 0,
243
+ "maximum": 1
244
+ },
245
+ "entropy_delta": {
246
+ "type": "number",
247
+ "minimum": 0,
248
+ "maximum": 1
249
+ }
250
+ }
251
+ },
252
+ "resonance_stakes": {
253
+ "type": "object",
254
+ "description": "Stakes classification for the interaction",
255
+ "properties": {
256
+ "level": {
257
+ "type": "string",
258
+ "enum": ["HIGH", "MEDIUM", "LOW"]
259
+ },
260
+ "confidence": {
261
+ "type": "number",
262
+ "minimum": 0,
263
+ "maximum": 1
264
+ }
265
+ }
266
+ },
267
+ "resonance_adversarial": {
268
+ "type": "object",
269
+ "description": "Adversarial/jailbreak detection summary from the calculator",
270
+ "properties": {
271
+ "detected": {
272
+ "type": "boolean"
273
+ },
274
+ "penalty": {
275
+ "type": "number",
276
+ "minimum": 0,
277
+ "maximum": 1
278
+ },
279
+ "keyword_density": {
280
+ "type": "number",
281
+ "minimum": 0,
282
+ "maximum": 1
283
+ },
284
+ "ethics_bypass_score": {
285
+ "type": "number",
286
+ "minimum": 0,
287
+ "maximum": 1
288
+ }
289
+ }
290
+ }
291
+ }
292
+ },
293
+ "policy_state": {
294
+ "type": "object",
295
+ "description": "State of policy constraints at time of interaction",
296
+ "properties": {
297
+ "constraints_applied": {
298
+ "type": "array",
299
+ "description": "Which policy constraints were active",
300
+ "items": {
301
+ "type": "string",
302
+ "example": ["consent_verified", "truth_debt_check", "safety_filter"]
303
+ }
304
+ },
305
+ "violations": {
306
+ "type": "array",
307
+ "description": "Any policy violations detected",
308
+ "items": {
309
+ "type": "object",
310
+ "properties": {
311
+ "rule": {
312
+ "type": "string",
313
+ "description": "Policy rule that was violated"
314
+ },
315
+ "severity": {
316
+ "type": "string",
317
+ "enum": ["warning", "violation", "critical"],
318
+ "description": "Severity level"
319
+ },
320
+ "action": {
321
+ "type": "string",
322
+ "enum": ["warn", "slow", "halt", "escalate"],
323
+ "description": "Action taken in response"
324
+ }
325
+ }
326
+ }
327
+ },
328
+ "consent_verified": {
329
+ "type": "boolean",
330
+ "description": "Was explicit user consent verified?"
331
+ },
332
+ "override_available": {
333
+ "type": "boolean",
334
+ "description": "Did user have option to override?"
335
+ }
336
+ }
337
+ },
338
+ "chain": {
339
+ "type": "object",
340
+ "description": "Hash chain for immutability",
341
+ "required": ["previous_hash", "chain_hash"],
342
+ "properties": {
343
+ "previous_hash": {
344
+ "type": "string",
345
+ "description": "Hash of previous receipt (genesis_hash for first)",
346
+ "pattern": "^[a-f0-9]{64}$|^GENESIS$"
347
+ },
348
+ "chain_hash": {
349
+ "type": "string",
350
+ "description": "SHA-256(canonical_json + previous_hash)",
351
+ "pattern": "^[a-f0-9]{64}$"
352
+ },
353
+ "chain_length": {
354
+ "type": "integer",
355
+ "description": "Number of receipts in this chain",
356
+ "minimum": 1,
357
+ "example": 42
358
+ }
359
+ }
360
+ },
361
+ "signature": {
362
+ "type": "object",
363
+ "description": "Cryptographic signature",
364
+ "required": ["algorithm", "value", "key_version"],
365
+ "properties": {
366
+ "algorithm": {
367
+ "type": "string",
368
+ "enum": ["Ed25519"],
369
+ "description": "Signature algorithm used"
370
+ },
371
+ "value": {
372
+ "type": "string",
373
+ "description": "Base64-encoded signature of canonical receipt",
374
+ "example": "MEQCIDGrvmTEr7c00rpf5Z+O50Ad5Z8Xxfqfjf9Z8O50Ad5=="
375
+ },
376
+ "key_version": {
377
+ "type": "string",
378
+ "description": "Which version of agent's key was used",
379
+ "example": "key_v1"
380
+ },
381
+ "timestamp_signed": {
382
+ "type": "string",
383
+ "format": "date-time",
384
+ "description": "When receipt was signed"
385
+ }
386
+ }
387
+ },
388
+ "metadata": {
389
+ "type": "object",
390
+ "description": "Optional metadata",
391
+ "properties": {
392
+ "tags": {
393
+ "type": "array",
394
+ "description": "Custom tags for categorization",
395
+ "items": {
396
+ "type": "string"
397
+ }
398
+ },
399
+ "context": {
400
+ "type": "object",
401
+ "description": "Application-specific context",
402
+ "additionalProperties": true
403
+ },
404
+ "user_agent": {
405
+ "type": "string",
406
+ "description": "Client that generated this receipt"
407
+ }
408
+ }
409
+ },
410
+ "policy_enforcement": {
411
+ "type": "object",
412
+ "description": "Policy enforcement results (Phase 2)",
413
+ "properties": {
414
+ "policies_evaluated": {
415
+ "type": "array",
416
+ "description": "List of policy IDs evaluated",
417
+ "items": {
418
+ "type": "string"
419
+ }
420
+ },
421
+ "violations": {
422
+ "type": "array",
423
+ "description": "Constraint violations detected",
424
+ "items": {
425
+ "type": "object",
426
+ "properties": {
427
+ "id": {
428
+ "type": "string",
429
+ "description": "Violation ID"
430
+ },
431
+ "constraint_id": {
432
+ "type": "string",
433
+ "description": "ID of constraint that triggered this violation"
434
+ },
435
+ "constraint_name": {
436
+ "type": "string",
437
+ "description": "Name of constraint"
438
+ },
439
+ "violation_type": {
440
+ "type": "string",
441
+ "enum": ["PII_DETECTED", "TRUTH_DEBT_EXCEEDED", "COMPLIANCE_BOUNDARY_VIOLATED", "POLICY_CONSTRAINT_FAILED", "CUSTOM_VIOLATION"],
442
+ "description": "Type of violation"
443
+ },
444
+ "severity": {
445
+ "type": "string",
446
+ "enum": ["warn", "block", "escalate"],
447
+ "description": "Severity level"
448
+ },
449
+ "message": {
450
+ "type": "string",
451
+ "description": "Human-readable violation message"
452
+ },
453
+ "evidence": {
454
+ "type": "object",
455
+ "description": "Supporting evidence for violation",
456
+ "additionalProperties": true
457
+ },
458
+ "receipt_annotation": {
459
+ "type": "string",
460
+ "description": "Annotation to add to receipt"
461
+ },
462
+ "detected_at": {
463
+ "type": "string",
464
+ "format": "date-time",
465
+ "description": "When violation was detected"
466
+ },
467
+ "remediation_suggested": {
468
+ "type": "string",
469
+ "description": "Suggested remediation action"
470
+ }
471
+ },
472
+ "required": ["id", "constraint_id", "constraint_name", "violation_type", "severity", "message", "evidence", "receipt_annotation", "detected_at"]
473
+ }
474
+ },
475
+ "status": {
476
+ "type": "string",
477
+ "enum": ["CLEAR", "FLAGGED", "BLOCKED"],
478
+ "description": "Overall policy compliance status"
479
+ },
480
+ "human_review_required": {
481
+ "type": "boolean",
482
+ "description": "Whether human review is required"
483
+ },
484
+ "enforcement_timestamp": {
485
+ "type": "string",
486
+ "format": "date-time",
487
+ "description": "When policy enforcement was performed"
488
+ },
489
+ "actions_taken": {
490
+ "type": "array",
491
+ "description": "Actions taken as result of policy enforcement",
492
+ "items": {
493
+ "type": "string",
494
+ "enum": ["ALERT", "ANNOTATE", "BLOCK", "ESCALATE", "REQUIRE_HUMAN_REVIEW"]
495
+ }
496
+ }
497
+ }
498
+ }
499
+ },
500
+ "additionalProperties": false
501
+ }