@longarc/mdash 3.1.2 → 3.1.3

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 (172) hide show
  1. package/README.md +86 -23
  2. package/SECURITY.md +254 -0
  3. package/dist/accountability/engine.d.ts +27 -0
  4. package/dist/accountability/engine.d.ts.map +1 -0
  5. package/dist/accountability/engine.js +148 -0
  6. package/dist/accountability/engine.js.map +1 -0
  7. package/dist/accountability/types.d.ts +46 -0
  8. package/dist/accountability/types.d.ts.map +1 -0
  9. package/dist/accountability/types.js +8 -0
  10. package/dist/accountability/types.js.map +1 -0
  11. package/dist/checkpoint/engine.d.ts.map +1 -1
  12. package/dist/checkpoint/engine.js +4 -0
  13. package/dist/checkpoint/engine.js.map +1 -1
  14. package/dist/context/compose.d.ts +62 -0
  15. package/dist/context/compose.d.ts.map +1 -0
  16. package/dist/context/compose.js +286 -0
  17. package/dist/context/compose.js.map +1 -0
  18. package/dist/context/crypto/hash.d.ts +100 -0
  19. package/dist/context/crypto/hash.d.ts.map +1 -0
  20. package/dist/context/crypto/hash.js +248 -0
  21. package/dist/context/crypto/hash.js.map +1 -0
  22. package/dist/context/crypto/hmac.d.ts +80 -0
  23. package/dist/context/crypto/hmac.d.ts.map +1 -0
  24. package/dist/context/crypto/hmac.js +192 -0
  25. package/dist/context/crypto/hmac.js.map +1 -0
  26. package/dist/context/crypto/index.d.ts +7 -0
  27. package/dist/context/crypto/index.d.ts.map +1 -0
  28. package/dist/context/crypto/index.js +7 -0
  29. package/dist/context/crypto/index.js.map +1 -0
  30. package/dist/context/engine-v3.0-backup.d.ts +197 -0
  31. package/dist/context/engine-v3.0-backup.d.ts.map +1 -0
  32. package/dist/context/engine-v3.0-backup.js +392 -0
  33. package/dist/context/engine-v3.0-backup.js.map +1 -0
  34. package/dist/context/fragment.d.ts +99 -0
  35. package/dist/context/fragment.d.ts.map +1 -0
  36. package/dist/context/fragment.js +316 -0
  37. package/dist/context/fragment.js.map +1 -0
  38. package/dist/context/index.d.ts +99 -0
  39. package/dist/context/index.d.ts.map +1 -0
  40. package/dist/context/index.js +180 -0
  41. package/dist/context/index.js.map +1 -0
  42. package/dist/context/provenance.d.ts +80 -0
  43. package/dist/context/provenance.d.ts.map +1 -0
  44. package/dist/context/provenance.js +294 -0
  45. package/dist/context/provenance.js.map +1 -0
  46. package/dist/context/resolve.d.ts +106 -0
  47. package/dist/context/resolve.d.ts.map +1 -0
  48. package/dist/context/resolve.js +440 -0
  49. package/dist/context/resolve.js.map +1 -0
  50. package/dist/context/store.d.ts +156 -0
  51. package/dist/context/store.d.ts.map +1 -0
  52. package/dist/context/store.js +396 -0
  53. package/dist/context/store.js.map +1 -0
  54. package/dist/context/types.d.ts +463 -0
  55. package/dist/context/types.d.ts.map +1 -0
  56. package/dist/context/types.js +94 -0
  57. package/dist/context/types.js.map +1 -0
  58. package/dist/context/utils/atomic.d.ts +76 -0
  59. package/dist/context/utils/atomic.d.ts.map +1 -0
  60. package/dist/context/utils/atomic.js +159 -0
  61. package/dist/context/utils/atomic.js.map +1 -0
  62. package/dist/context/utils/credit.d.ts +65 -0
  63. package/dist/context/utils/credit.d.ts.map +1 -0
  64. package/dist/context/utils/credit.js +164 -0
  65. package/dist/context/utils/credit.js.map +1 -0
  66. package/dist/context/utils/index.d.ts +13 -0
  67. package/dist/context/utils/index.d.ts.map +1 -0
  68. package/dist/context/utils/index.js +13 -0
  69. package/dist/context/utils/index.js.map +1 -0
  70. package/dist/context/utils/utility.d.ts +63 -0
  71. package/dist/context/utils/utility.d.ts.map +1 -0
  72. package/dist/context/utils/utility.js +141 -0
  73. package/dist/context/utils/utility.js.map +1 -0
  74. package/dist/core/commitment.d.ts +25 -2
  75. package/dist/core/commitment.d.ts.map +1 -1
  76. package/dist/core/commitment.js +44 -6
  77. package/dist/core/commitment.js.map +1 -1
  78. package/dist/core/crypto.d.ts +2 -0
  79. package/dist/core/crypto.d.ts.map +1 -1
  80. package/dist/core/crypto.js +12 -0
  81. package/dist/core/crypto.js.map +1 -1
  82. package/dist/index.d.ts +11 -6
  83. package/dist/index.d.ts.map +1 -1
  84. package/dist/index.js +35 -10
  85. package/dist/index.js.map +1 -1
  86. package/dist/mcca/engine.d.ts.map +1 -1
  87. package/dist/mcca/engine.js +5 -4
  88. package/dist/mcca/engine.js.map +1 -1
  89. package/dist/physics/engine.d.ts +1 -0
  90. package/dist/physics/engine.d.ts.map +1 -1
  91. package/dist/physics/engine.js +36 -2
  92. package/dist/physics/engine.js.map +1 -1
  93. package/dist/provenance/api-handler.d.ts +45 -0
  94. package/dist/provenance/api-handler.d.ts.map +1 -0
  95. package/dist/provenance/api-handler.js +223 -0
  96. package/dist/provenance/api-handler.js.map +1 -0
  97. package/dist/provenance/api-types.d.ts +108 -0
  98. package/dist/provenance/api-types.d.ts.map +1 -0
  99. package/dist/provenance/api-types.js +9 -0
  100. package/dist/provenance/api-types.js.map +1 -0
  101. package/dist/provenance/index.d.ts +6 -0
  102. package/dist/provenance/index.d.ts.map +1 -0
  103. package/dist/provenance/index.js +3 -0
  104. package/dist/provenance/index.js.map +1 -0
  105. package/dist/provenance/provenance-engine.d.ts +63 -0
  106. package/dist/provenance/provenance-engine.d.ts.map +1 -0
  107. package/dist/provenance/provenance-engine.js +311 -0
  108. package/dist/provenance/provenance-engine.js.map +1 -0
  109. package/dist/provenance/types.d.ts +193 -0
  110. package/dist/provenance/types.d.ts.map +1 -0
  111. package/dist/provenance/types.js +9 -0
  112. package/dist/provenance/types.js.map +1 -0
  113. package/dist/tee/engine.d.ts.map +1 -1
  114. package/dist/tee/engine.js +14 -0
  115. package/dist/tee/engine.js.map +1 -1
  116. package/dist/warrant/engine.d.ts +24 -1
  117. package/dist/warrant/engine.d.ts.map +1 -1
  118. package/dist/warrant/engine.js +76 -1
  119. package/dist/warrant/engine.js.map +1 -1
  120. package/dist/zk/engine.d.ts.map +1 -1
  121. package/dist/zk/engine.js +7 -4
  122. package/dist/zk/engine.js.map +1 -1
  123. package/docs/SECURITY-PATCHES.md +170 -0
  124. package/package.json +17 -5
  125. package/src/__tests__/accountability.test.ts +308 -0
  126. package/src/__tests__/l1-verification-modes.test.ts +424 -0
  127. package/src/__tests__/phase1.benchmark.test.ts +94 -0
  128. package/src/__tests__/phase1.test.ts +0 -77
  129. package/src/__tests__/phase2-4.benchmark.test.ts +60 -0
  130. package/src/__tests__/phase2-4.test.ts +1 -52
  131. package/src/__tests__/provenance/api-handler.test.ts +356 -0
  132. package/src/__tests__/provenance/provenance-engine.test.ts +628 -0
  133. package/src/__tests__/sa-2026-008.test.ts +45 -0
  134. package/src/__tests__/sa-2026-009.test.ts +86 -0
  135. package/src/__tests__/sa-2026-010.test.ts +72 -0
  136. package/src/__tests__/sa-2026-012.test.ts +65 -0
  137. package/src/__tests__/sa-2026-nfc.test.ts +40 -0
  138. package/src/__tests__/security.test.ts +786 -0
  139. package/src/accountability/engine.ts +230 -0
  140. package/src/accountability/types.ts +58 -0
  141. package/src/checkpoint/engine.ts +4 -0
  142. package/src/context/__tests__/caret-v0.2.0.test.ts +860 -0
  143. package/src/context/__tests__/integration.test.ts +356 -0
  144. package/src/context/compose.ts +388 -0
  145. package/src/context/crypto/hash.ts +277 -0
  146. package/src/context/crypto/hmac.ts +253 -0
  147. package/src/context/crypto/index.ts +29 -0
  148. package/src/context/engine-v3.0-backup.ts +598 -0
  149. package/src/context/fragment.ts +454 -0
  150. package/src/context/index.ts +427 -0
  151. package/src/context/provenance.ts +380 -0
  152. package/src/context/resolve.ts +581 -0
  153. package/src/context/store.ts +503 -0
  154. package/src/context/types.ts +679 -0
  155. package/src/context/utils/atomic.ts +207 -0
  156. package/src/context/utils/credit.ts +224 -0
  157. package/src/context/utils/index.ts +13 -0
  158. package/src/context/utils/utility.ts +200 -0
  159. package/src/core/commitment.ts +129 -67
  160. package/src/core/crypto.ts +13 -0
  161. package/src/index.ts +62 -10
  162. package/src/mcca/engine.ts +5 -4
  163. package/src/physics/engine.ts +40 -3
  164. package/src/provenance/api-handler.ts +248 -0
  165. package/src/provenance/api-types.ts +112 -0
  166. package/src/provenance/index.ts +19 -0
  167. package/src/provenance/provenance-engine.ts +387 -0
  168. package/src/provenance/types.ts +211 -0
  169. package/src/tee/engine.ts +16 -0
  170. package/src/warrant/engine.ts +89 -1
  171. package/src/zk/engine.ts +8 -4
  172. package/tsconfig.json +1 -1
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Caret — Atomic Encoding Utilities
3
+ * @module @longarcstudios/caret/utils/atomic
4
+ *
5
+ * Coreference resolution for atomic attestation encoding.
6
+ * Transforms ambiguous text into explicit references.
7
+ *
8
+ * Rules:
9
+ * - Pronouns → Agent IDs
10
+ * - Relative time → ISO 8601 timestamps
11
+ * - "it/this/that" → Explicit entity IDs
12
+ * - Ambiguous verbs → MdashActionCode
13
+ */
14
+ const COREFERENCE_PATTERNS = [
15
+ // Pronouns → Agent IDs
16
+ {
17
+ pattern: /\b(he|she|it|they)\b/gi,
18
+ resolver: (_, ctx) => ctx.lastAgentId ?? 'Agent_unknown',
19
+ },
20
+ // Relative time → ISO 8601
21
+ {
22
+ pattern: /\byesterday\b/gi,
23
+ resolver: (_, ctx) => {
24
+ const d = new Date(ctx.referenceTime);
25
+ d.setDate(d.getDate() - 1);
26
+ return d.toISOString();
27
+ },
28
+ },
29
+ {
30
+ pattern: /\btomorrow\b/gi,
31
+ resolver: (_, ctx) => {
32
+ const d = new Date(ctx.referenceTime);
33
+ d.setDate(d.getDate() + 1);
34
+ return d.toISOString();
35
+ },
36
+ },
37
+ {
38
+ pattern: /\bnow\b/gi,
39
+ resolver: (_, ctx) => new Date(ctx.referenceTime).toISOString(),
40
+ },
41
+ {
42
+ pattern: /\btoday\b/gi,
43
+ resolver: (_, ctx) => {
44
+ const d = new Date(ctx.referenceTime);
45
+ d.setHours(0, 0, 0, 0);
46
+ return d.toISOString();
47
+ },
48
+ },
49
+ // Implicit references → Explicit IDs
50
+ {
51
+ pattern: /\bthe warrant\b/gi,
52
+ resolver: (_, ctx) => ctx.lastWarrantId ?? 'Warrant_unknown',
53
+ },
54
+ {
55
+ pattern: /\bthe checkpoint\b/gi,
56
+ resolver: (_, ctx) => ctx.lastCheckpointId ?? 'Checkpoint_unknown',
57
+ },
58
+ {
59
+ pattern: /\bthe agent\b/gi,
60
+ resolver: (_, ctx) => ctx.lastAgentId ?? 'Agent_unknown',
61
+ },
62
+ ];
63
+ // ============================================================================
64
+ // MAIN FUNCTIONS
65
+ // ============================================================================
66
+ /**
67
+ * Resolve coreferences in a text string.
68
+ * Transforms ambiguous language into atomic references.
69
+ *
70
+ * @example
71
+ * ```ts
72
+ * const result = resolveCoreferences(
73
+ * "He approved it yesterday",
74
+ * {
75
+ * referenceTime: '2026-01-18T12:00:00Z',
76
+ * lastAgentId: 'Agent_0x7f3a',
77
+ * lastWarrantId: 'Warrant_0x8b2c'
78
+ * }
79
+ * );
80
+ * // "Agent_0x7f3a approved Warrant_0x8b2c 2026-01-17T12:00:00.000Z"
81
+ * ```
82
+ */
83
+ export function resolveCoreferences(text, context) {
84
+ let resolved = text;
85
+ for (const { pattern, resolver } of COREFERENCE_PATTERNS) {
86
+ resolved = resolved.replace(pattern, (match) => resolver(match, context));
87
+ }
88
+ return resolved;
89
+ }
90
+ /**
91
+ * Create a default coreference context with current time.
92
+ */
93
+ export function createDefaultContext(overrides) {
94
+ return {
95
+ referenceTime: new Date().toISOString(),
96
+ ...overrides,
97
+ };
98
+ }
99
+ /**
100
+ * Check if text contains unresolved coreferences.
101
+ * Useful for validation before sealing.
102
+ */
103
+ export function hasUnresolvedCoreferences(text) {
104
+ const patterns = [
105
+ /\b(he|she|it|they)\b/i,
106
+ /\b(yesterday|tomorrow|now|today)\b/i,
107
+ /\bthe (warrant|checkpoint|agent)\b/i,
108
+ ];
109
+ return patterns.some(p => p.test(text));
110
+ }
111
+ /**
112
+ * Extract entity IDs from resolved text.
113
+ * Returns all Agent_, Warrant_, Checkpoint_, User_ prefixed IDs.
114
+ */
115
+ export function extractEntityIds(text) {
116
+ const pattern = /\b(Agent|Warrant|Checkpoint|User)_[a-f0-9]+\b/gi;
117
+ const matches = text.match(pattern);
118
+ return matches ? [...new Set(matches)] : [];
119
+ }
120
+ /**
121
+ * Create canonical encoding for commitment hash.
122
+ * Deterministic string representation suitable for hashing.
123
+ */
124
+ export function canonicalEncode(attestation) {
125
+ const parts = [
126
+ attestation.subject,
127
+ attestation.action,
128
+ attestation.object ?? '',
129
+ attestation.timestamp,
130
+ attestation.context ?? '',
131
+ ];
132
+ return parts.join('|');
133
+ }
134
+ /**
135
+ * Compute SHA-256 hash of canonical encoding.
136
+ * Uses Web Crypto API for cross-platform compatibility.
137
+ */
138
+ export async function computeCommitmentHash(attestation) {
139
+ const canonical = canonicalEncode(attestation);
140
+ const encoder = new TextEncoder();
141
+ const data = encoder.encode(canonical);
142
+ const hashBuffer = await crypto.subtle.digest('SHA-256', data);
143
+ const hashArray = Array.from(new Uint8Array(hashBuffer));
144
+ return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
145
+ }
146
+ /**
147
+ * Validate atomic attestation subject format.
148
+ * Must be Entity_hexid pattern.
149
+ */
150
+ export function isValidSubject(subject) {
151
+ return /^(Agent|Warrant|Checkpoint|User)_[a-f0-9]+$/i.test(subject);
152
+ }
153
+ /**
154
+ * Validate ISO 8601 timestamp format.
155
+ */
156
+ export function isValidTimestamp(timestamp) {
157
+ return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(timestamp);
158
+ }
159
+ //# sourceMappingURL=atomic.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../../src/context/utils/atomic.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,65 @@
1
+ /**
2
+ * Caret — Credit Assignment Utilities
3
+ * @module @longarcstudios/caret/utils/credit
4
+ *
5
+ * Step-wise credit assignment for execution traces.
6
+ * Distributes terminal reward proportionally to influence consumption.
7
+ *
8
+ * Properties:
9
+ * - Credits sum to terminal reward (conservation)
10
+ * - Higher influence steps receive higher credit
11
+ * - Works for arbitrarily long chains
12
+ */
13
+ import type { ExecutionTrace, CreditAssignment, LiabilityShare, InfluenceBudget } from '../types.js';
14
+ /**
15
+ * Assign credit to execution steps proportional to influence consumption.
16
+ * Terminal reward is distributed to all steps based on their contribution.
17
+ *
18
+ * @param trace - Execution trace with steps
19
+ * @param terminalReward - Final outcome reward to distribute
20
+ * @returns Credit assignment for all steps
21
+ *
22
+ * @example
23
+ * ```ts
24
+ * const credits = assignCredit(trace, 1.0);
25
+ * // Sum of credits.step_credits[].credit === 1.0
26
+ * ```
27
+ */
28
+ export declare function assignCredit(trace: ExecutionTrace, terminalReward: number): CreditAssignment;
29
+ /**
30
+ * Validate that credit assignment conserves terminal reward.
31
+ * Credits should sum to terminal reward within tolerance.
32
+ */
33
+ export declare function validateCreditAssignment(assignment: CreditAssignment, tolerance?: number): boolean;
34
+ /**
35
+ * Attribute liability to contributing agents based on influence consumption.
36
+ *
37
+ * @param trace - Execution trace
38
+ * @returns Liability shares summing to 1.0
39
+ */
40
+ export declare function attributeLiability(trace: ExecutionTrace): LiabilityShare[];
41
+ /**
42
+ * Validate that liability shares sum to 1.0 within tolerance.
43
+ */
44
+ export declare function validateLiabilityShares(shares: LiabilityShare[], tolerance?: number): boolean;
45
+ /**
46
+ * Create MCCA-compliant default influence budget.
47
+ */
48
+ export declare function createDefaultInfluenceBudget(): InfluenceBudget;
49
+ /**
50
+ * Check if influence budget is MCCA-compliant.
51
+ */
52
+ export declare function isMCCACompliant(budget: InfluenceBudget): boolean;
53
+ /**
54
+ * Normalize influence budget to sum to 1.0.
55
+ */
56
+ export declare function normalizeInfluenceBudget(budget: InfluenceBudget): InfluenceBudget;
57
+ /**
58
+ * Add two influence budgets.
59
+ */
60
+ export declare function addInfluenceBudgets(a: InfluenceBudget, b: InfluenceBudget): InfluenceBudget;
61
+ /**
62
+ * Compute total influence consumed in a trace.
63
+ */
64
+ export declare function computeTraceInfluence(trace: ExecutionTrace): InfluenceBudget;
65
+ //# sourceMappingURL=credit.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"credit.d.ts","sourceRoot":"","sources":["../../../src/context/utils/credit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAEhB,cAAc,EACd,eAAe,EAEhB,MAAM,aAAa,CAAC;AAOrB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,cAAc,EAAE,MAAM,GACrB,gBAAgB,CA0BlB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,gBAAgB,EAC5B,SAAS,GAAE,MAAc,GACxB,OAAO,CAMT;AAeD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CAiC1E;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,cAAc,EAAE,EACxB,SAAS,GAAE,MAAc,GACxB,OAAO,CAKT;AAMD;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,eAAe,CAO9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAOhE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAajF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,eAAe,EAClB,CAAC,EAAE,eAAe,GACjB,eAAe,CAOjB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAK5E"}
@@ -0,0 +1,164 @@
1
+ /**
2
+ * Caret — Credit Assignment Utilities
3
+ * @module @longarcstudios/caret/utils/credit
4
+ *
5
+ * Step-wise credit assignment for execution traces.
6
+ * Distributes terminal reward proportionally to influence consumption.
7
+ *
8
+ * Properties:
9
+ * - Credits sum to terminal reward (conservation)
10
+ * - Higher influence steps receive higher credit
11
+ * - Works for arbitrarily long chains
12
+ */
13
+ import { sumInfluence } from '../types.js';
14
+ // ============================================================================
15
+ // CREDIT ASSIGNMENT
16
+ // ============================================================================
17
+ /**
18
+ * Assign credit to execution steps proportional to influence consumption.
19
+ * Terminal reward is distributed to all steps based on their contribution.
20
+ *
21
+ * @param trace - Execution trace with steps
22
+ * @param terminalReward - Final outcome reward to distribute
23
+ * @returns Credit assignment for all steps
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * const credits = assignCredit(trace, 1.0);
28
+ * // Sum of credits.step_credits[].credit === 1.0
29
+ * ```
30
+ */
31
+ export function assignCredit(trace, terminalReward) {
32
+ // Compute total influence
33
+ const totalInfluence = trace.steps.reduce((sum, step) => sum + sumInfluence(step.influence_consumed), 0);
34
+ // Distribute credit proportionally
35
+ const stepCredits = trace.steps.map((step) => {
36
+ const influence = sumInfluence(step.influence_consumed);
37
+ const influenceFraction = totalInfluence > 0 ? influence / totalInfluence : 0;
38
+ return {
39
+ step_id: step.step_id,
40
+ credit: influenceFraction * terminalReward,
41
+ influence,
42
+ influence_fraction: influenceFraction,
43
+ };
44
+ });
45
+ return {
46
+ trace_id: trace.trace_id,
47
+ terminal_reward: terminalReward,
48
+ step_credits: stepCredits,
49
+ assigned_at: new Date().toISOString(),
50
+ };
51
+ }
52
+ /**
53
+ * Validate that credit assignment conserves terminal reward.
54
+ * Credits should sum to terminal reward within tolerance.
55
+ */
56
+ export function validateCreditAssignment(assignment, tolerance = 0.001) {
57
+ const creditSum = assignment.step_credits.reduce((acc, step) => acc + step.credit, 0);
58
+ return Math.abs(creditSum - assignment.terminal_reward) < tolerance;
59
+ }
60
+ // ============================================================================
61
+ // LIABILITY ATTRIBUTION
62
+ // ============================================================================
63
+ /**
64
+ * Extract agent ID from step ID.
65
+ * Convention: step IDs prefixed with agent identifier.
66
+ */
67
+ function extractAgentId(stepId) {
68
+ const match = stepId.match(/^(Agent_[a-f0-9]+)/i);
69
+ return match && match[1] ? match[1] : 'Agent_unknown';
70
+ }
71
+ /**
72
+ * Attribute liability to contributing agents based on influence consumption.
73
+ *
74
+ * @param trace - Execution trace
75
+ * @returns Liability shares summing to 1.0
76
+ */
77
+ export function attributeLiability(trace) {
78
+ // Compute total influence
79
+ const totalInfluence = trace.steps.reduce((sum, step) => sum + sumInfluence(step.influence_consumed), 0);
80
+ if (totalInfluence === 0) {
81
+ return []; // No liability if no influence consumed
82
+ }
83
+ // Group steps by agent
84
+ const agentContributions = new Map();
85
+ for (const step of trace.steps) {
86
+ const agentId = extractAgentId(step.step_id);
87
+ const stepInfluence = sumInfluence(step.influence_consumed);
88
+ const existing = agentContributions.get(agentId) ?? { influence: 0, steps: [] };
89
+ existing.influence += stepInfluence;
90
+ existing.steps.push(step.step_id);
91
+ agentContributions.set(agentId, existing);
92
+ }
93
+ // Convert to liability shares
94
+ return Array.from(agentContributions.entries()).map(([agentId, data]) => ({
95
+ agent_id: agentId,
96
+ contribution: data.influence / totalInfluence,
97
+ evidence: data.steps,
98
+ }));
99
+ }
100
+ /**
101
+ * Validate that liability shares sum to 1.0 within tolerance.
102
+ */
103
+ export function validateLiabilityShares(shares, tolerance = 0.001) {
104
+ if (shares.length === 0)
105
+ return true; // Empty is valid
106
+ const sum = shares.reduce((acc, share) => acc + share.contribution, 0);
107
+ return Math.abs(sum - 1.0) < tolerance;
108
+ }
109
+ // ============================================================================
110
+ // INFLUENCE UTILITIES
111
+ // ============================================================================
112
+ /**
113
+ * Create MCCA-compliant default influence budget.
114
+ */
115
+ export function createDefaultInfluenceBudget() {
116
+ return {
117
+ system: 0.45,
118
+ user: 0.30,
119
+ environment: 0.15,
120
+ assistant: 0.10,
121
+ };
122
+ }
123
+ /**
124
+ * Check if influence budget is MCCA-compliant.
125
+ */
126
+ export function isMCCACompliant(budget) {
127
+ return (budget.system >= 0.40 &&
128
+ budget.user <= 0.35 &&
129
+ budget.environment <= 0.20 &&
130
+ budget.assistant <= 0.25);
131
+ }
132
+ /**
133
+ * Normalize influence budget to sum to 1.0.
134
+ */
135
+ export function normalizeInfluenceBudget(budget) {
136
+ const total = sumInfluence(budget);
137
+ if (total === 0) {
138
+ return createDefaultInfluenceBudget();
139
+ }
140
+ return {
141
+ system: budget.system / total,
142
+ user: budget.user / total,
143
+ environment: budget.environment / total,
144
+ assistant: budget.assistant / total,
145
+ };
146
+ }
147
+ /**
148
+ * Add two influence budgets.
149
+ */
150
+ export function addInfluenceBudgets(a, b) {
151
+ return {
152
+ system: a.system + b.system,
153
+ user: a.user + b.user,
154
+ environment: a.environment + b.environment,
155
+ assistant: a.assistant + b.assistant,
156
+ };
157
+ }
158
+ /**
159
+ * Compute total influence consumed in a trace.
160
+ */
161
+ export function computeTraceInfluence(trace) {
162
+ return trace.steps.reduce((total, step) => addInfluenceBudgets(total, step.influence_consumed), { system: 0, user: 0, environment: 0, assistant: 0 });
163
+ }
164
+ //# sourceMappingURL=credit.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"credit.js","sourceRoot":"","sources":["../../../src/context/utils/credit.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Caret — Utility Functions
3
+ * @module @longarcstudios/caret/utils
4
+ *
5
+ * Research pattern utilities for Caret v0.2.0:
6
+ * - Atomic encoding (coreference resolution)
7
+ * - Utility learning (incremental score updates)
8
+ * - Credit assignment (step-wise reward distribution)
9
+ */
10
+ export * from './atomic.js';
11
+ export * from './utility.js';
12
+ export * from './credit.js';
13
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Caret — Utility Functions
3
+ * @module @longarcstudios/caret/utils
4
+ *
5
+ * Research pattern utilities for Caret v0.2.0:
6
+ * - Atomic encoding (coreference resolution)
7
+ * - Utility learning (incremental score updates)
8
+ * - Credit assignment (step-wise reward distribution)
9
+ */
10
+ export * from './atomic.js';
11
+ export * from './utility.js';
12
+ export * from './credit.js';
13
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/context/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Caret — Utility Learning Functions
3
+ * @module @longarcstudios/caret/utils/utility
4
+ *
5
+ * Incremental utility score learning.
6
+ * Implements: score ← score + α(reward - score)
7
+ */
8
+ import type { Outcome, UtilityScore, UtilityFeedback } from '../types.js';
9
+ /**
10
+ * Update utility score based on feedback.
11
+ * Implements incremental learning: score ← score + α(reward - score)
12
+ *
13
+ * @param current - Current utility score
14
+ * @param feedback - Feedback to incorporate
15
+ * @param alpha - Learning rate (default 0.1)
16
+ * @returns Updated utility score (immutable)
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * const updated = updateUtilityScore(
21
+ * { score: 0.5, confidence: 0.3, update_count: 3 },
22
+ * { reward: 0.8, source: 'human', timestamp: '2026-01-18T12:00:00Z' }
23
+ * );
24
+ * // { score: 0.53, confidence: 0.33, update_count: 4 }
25
+ * ```
26
+ */
27
+ export declare function updateUtilityScore(current: UtilityScore, feedback: UtilityFeedback, alpha?: number): UtilityScore;
28
+ /**
29
+ * Update an Outcome's utility score based on feedback.
30
+ * Returns a new Outcome with updated utility (immutable).
31
+ */
32
+ export declare function updateOutcomeUtility<T>(outcome: Outcome<T>, feedback: UtilityFeedback, alpha?: number): Outcome<T>;
33
+ /**
34
+ * Create a fresh utility score (no observations yet).
35
+ */
36
+ export declare function createInitialUtility(priorScore?: number): UtilityScore;
37
+ /**
38
+ * Create utility score from historical observations.
39
+ */
40
+ export declare function createUtilityFromHistory(rewards: number[], alpha?: number): UtilityScore;
41
+ /**
42
+ * Predict success probability from historical outcomes.
43
+ * Uses exponential moving average with recency bias.
44
+ *
45
+ * @param historicalScores - Array of past utility scores
46
+ * @param decayFactor - Weight decay per position (default 0.9)
47
+ * @returns Predicted success probability [0, 1]
48
+ */
49
+ export declare function predictSuccess(historicalScores: UtilityScore[], decayFactor?: number): number;
50
+ /**
51
+ * Compute expected utility given success probability and reward magnitudes.
52
+ */
53
+ export declare function expectedUtility(successProb: number, successReward: number, failureReward: number): number;
54
+ /**
55
+ * Compare two utility scores, accounting for confidence.
56
+ * Returns positive if a > b, negative if a < b, zero if equivalent.
57
+ */
58
+ export declare function compareUtility(a: UtilityScore, b: UtilityScore): number;
59
+ /**
60
+ * Select the best outcome from a list by utility.
61
+ */
62
+ export declare function selectBestOutcome<T>(outcomes: Outcome<T>[]): Outcome<T> | null;
63
+ //# sourceMappingURL=utility.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"utility.d.ts","sourceRoot":"","sources":["../../../src/context/utils/utility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,eAAe,EAChB,MAAM,aAAa,CAAC;AAgBrB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,eAAe,EACzB,KAAK,GAAE,MAAsB,GAC5B,YAAY,CAkBd;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,eAAe,EACzB,KAAK,GAAE,MAAsB,GAC5B,OAAO,CAAC,CAAC,CAAC,CAKZ;AAMD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,GAAE,MAAU,GAAG,YAAY,CAMzE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,GAAE,MAAsB,GAC5B,YAAY,CAYd;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,gBAAgB,EAAE,YAAY,EAAE,EAChC,WAAW,GAAE,MAAY,GACxB,MAAM,CA0BR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,GACpB,MAAM,CAER;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAMvE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAM9E"}
@@ -0,0 +1,141 @@
1
+ /**
2
+ * Caret — Utility Learning Functions
3
+ * @module @longarcstudios/caret/utils/utility
4
+ *
5
+ * Incremental utility score learning.
6
+ * Implements: score ← score + α(reward - score)
7
+ */
8
+ // ============================================================================
9
+ // CONSTANTS
10
+ // ============================================================================
11
+ /** Default learning rate for utility updates */
12
+ const DEFAULT_ALPHA = 0.1;
13
+ /** Confidence saturation constant (updates needed for ~90% confidence) */
14
+ const CONFIDENCE_TAU = 10;
15
+ // ============================================================================
16
+ // UTILITY UPDATE
17
+ // ============================================================================
18
+ /**
19
+ * Update utility score based on feedback.
20
+ * Implements incremental learning: score ← score + α(reward - score)
21
+ *
22
+ * @param current - Current utility score
23
+ * @param feedback - Feedback to incorporate
24
+ * @param alpha - Learning rate (default 0.1)
25
+ * @returns Updated utility score (immutable)
26
+ *
27
+ * @example
28
+ * ```ts
29
+ * const updated = updateUtilityScore(
30
+ * { score: 0.5, confidence: 0.3, update_count: 3 },
31
+ * { reward: 0.8, source: 'human', timestamp: '2026-01-18T12:00:00Z' }
32
+ * );
33
+ * // { score: 0.53, confidence: 0.33, update_count: 4 }
34
+ * ```
35
+ */
36
+ export function updateUtilityScore(current, feedback, alpha = DEFAULT_ALPHA) {
37
+ // Clamp feedback reward to [-1, 1]
38
+ const reward = Math.max(-1, Math.min(1, feedback.reward));
39
+ // Incremental update
40
+ const newScore = Math.max(-1, Math.min(1, current.score + alpha * (reward - current.score)));
41
+ // Update confidence based on count
42
+ const newCount = current.update_count + 1;
43
+ const newConfidence = Math.min(0.99, 1 - Math.exp(-newCount / CONFIDENCE_TAU));
44
+ return {
45
+ score: newScore,
46
+ confidence: newConfidence,
47
+ update_count: newCount,
48
+ };
49
+ }
50
+ /**
51
+ * Update an Outcome's utility score based on feedback.
52
+ * Returns a new Outcome with updated utility (immutable).
53
+ */
54
+ export function updateOutcomeUtility(outcome, feedback, alpha = DEFAULT_ALPHA) {
55
+ return {
56
+ ...outcome,
57
+ utility: updateUtilityScore(outcome.utility, feedback, alpha),
58
+ };
59
+ }
60
+ // ============================================================================
61
+ // UTILITY INITIALIZATION
62
+ // ============================================================================
63
+ /**
64
+ * Create a fresh utility score (no observations yet).
65
+ */
66
+ export function createInitialUtility(priorScore = 0) {
67
+ return {
68
+ score: Math.max(-1, Math.min(1, priorScore)),
69
+ confidence: 0,
70
+ update_count: 0,
71
+ };
72
+ }
73
+ /**
74
+ * Create utility score from historical observations.
75
+ */
76
+ export function createUtilityFromHistory(rewards, alpha = DEFAULT_ALPHA) {
77
+ let utility = createInitialUtility();
78
+ for (const reward of rewards) {
79
+ utility = updateUtilityScore(utility, { reward, source: 'system', timestamp: new Date().toISOString() }, alpha);
80
+ }
81
+ return utility;
82
+ }
83
+ // ============================================================================
84
+ // UTILITY PREDICTION
85
+ // ============================================================================
86
+ /**
87
+ * Predict success probability from historical outcomes.
88
+ * Uses exponential moving average with recency bias.
89
+ *
90
+ * @param historicalScores - Array of past utility scores
91
+ * @param decayFactor - Weight decay per position (default 0.9)
92
+ * @returns Predicted success probability [0, 1]
93
+ */
94
+ export function predictSuccess(historicalScores, decayFactor = 0.9) {
95
+ if (historicalScores.length === 0) {
96
+ return 0.5; // Uninformative prior
97
+ }
98
+ // Sort by update count (proxy for recency if no timestamps)
99
+ const sorted = [...historicalScores].sort((a, b) => b.update_count - a.update_count);
100
+ let weightedSum = 0;
101
+ let weightSum = 0;
102
+ for (let i = 0; i < sorted.length; i++) {
103
+ const score = sorted[i];
104
+ if (!score)
105
+ continue;
106
+ const weight = Math.pow(decayFactor, i);
107
+ // Map score from [-1, 1] to [0, 1] for probability
108
+ const prob = (score.score + 1) / 2;
109
+ weightedSum += weight * prob;
110
+ weightSum += weight;
111
+ }
112
+ return weightedSum / weightSum;
113
+ }
114
+ /**
115
+ * Compute expected utility given success probability and reward magnitudes.
116
+ */
117
+ export function expectedUtility(successProb, successReward, failureReward) {
118
+ return successProb * successReward + (1 - successProb) * failureReward;
119
+ }
120
+ // ============================================================================
121
+ // UTILITY COMPARISON
122
+ // ============================================================================
123
+ /**
124
+ * Compare two utility scores, accounting for confidence.
125
+ * Returns positive if a > b, negative if a < b, zero if equivalent.
126
+ */
127
+ export function compareUtility(a, b) {
128
+ // Weight by confidence
129
+ const aWeighted = a.score * a.confidence;
130
+ const bWeighted = b.score * b.confidence;
131
+ return aWeighted - bWeighted;
132
+ }
133
+ /**
134
+ * Select the best outcome from a list by utility.
135
+ */
136
+ export function selectBestOutcome(outcomes) {
137
+ if (outcomes.length === 0)
138
+ return null;
139
+ return outcomes.reduce((best, current) => compareUtility(current.utility, best.utility) > 0 ? current : best);
140
+ }
141
+ //# sourceMappingURL=utility.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"utility.js","sourceRoot":"","sources":["../../../src/context/utils/utility.ts"],"names":[],"mappings":"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"}