@chatwarden/core 0.1.6 → 0.1.8

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 (196) hide show
  1. package/README.md +173 -3
  2. package/dist/src/ai/agreement.d.ts +46 -0
  3. package/dist/src/ai/agreement.d.ts.map +1 -0
  4. package/dist/src/ai/agreement.js +71 -0
  5. package/dist/src/ai/agreement.js.map +1 -0
  6. package/dist/src/ai/breaker.d.ts +31 -0
  7. package/dist/src/ai/breaker.d.ts.map +1 -0
  8. package/dist/src/ai/breaker.js +62 -0
  9. package/dist/src/ai/breaker.js.map +1 -0
  10. package/dist/src/ai/budget.d.ts +26 -0
  11. package/dist/src/ai/budget.d.ts.map +1 -0
  12. package/dist/src/ai/budget.js +57 -0
  13. package/dist/src/ai/budget.js.map +1 -0
  14. package/dist/src/ai/case.d.ts +37 -0
  15. package/dist/src/ai/case.d.ts.map +1 -0
  16. package/dist/src/ai/case.js +30 -0
  17. package/dist/src/ai/case.js.map +1 -0
  18. package/dist/src/ai/casebook.d.ts +59 -0
  19. package/dist/src/ai/casebook.d.ts.map +1 -0
  20. package/dist/src/ai/casebook.js +47 -0
  21. package/dist/src/ai/casebook.js.map +1 -0
  22. package/dist/src/ai/ceilings.d.ts +42 -0
  23. package/dist/src/ai/ceilings.d.ts.map +1 -0
  24. package/dist/src/ai/ceilings.js +59 -0
  25. package/dist/src/ai/ceilings.js.map +1 -0
  26. package/dist/src/ai/fake.d.ts +41 -0
  27. package/dist/src/ai/fake.d.ts.map +1 -0
  28. package/dist/src/ai/fake.js +75 -0
  29. package/dist/src/ai/fake.js.map +1 -0
  30. package/dist/src/ai/hash.d.ts +15 -0
  31. package/dist/src/ai/hash.d.ts.map +1 -0
  32. package/dist/src/ai/hash.js +22 -0
  33. package/dist/src/ai/hash.js.map +1 -0
  34. package/dist/src/ai/inert.d.ts +5 -0
  35. package/dist/src/ai/inert.d.ts.map +1 -0
  36. package/dist/src/ai/inert.js +22 -0
  37. package/dist/src/ai/inert.js.map +1 -0
  38. package/dist/src/ai/injection.d.ts +8 -0
  39. package/dist/src/ai/injection.d.ts.map +1 -0
  40. package/dist/src/ai/injection.js +30 -0
  41. package/dist/src/ai/injection.js.map +1 -0
  42. package/dist/src/ai/lines.d.ts +64 -0
  43. package/dist/src/ai/lines.d.ts.map +1 -0
  44. package/dist/src/ai/lines.js +172 -0
  45. package/dist/src/ai/lines.js.map +1 -0
  46. package/dist/src/ai/prompt.d.ts +48 -0
  47. package/dist/src/ai/prompt.d.ts.map +1 -0
  48. package/dist/src/ai/prompt.js +196 -0
  49. package/dist/src/ai/prompt.js.map +1 -0
  50. package/dist/src/ai/redact.d.ts +29 -0
  51. package/dist/src/ai/redact.d.ts.map +1 -0
  52. package/dist/src/ai/redact.js +160 -0
  53. package/dist/src/ai/redact.js.map +1 -0
  54. package/dist/src/ai/schema.d.ts +6 -0
  55. package/dist/src/ai/schema.d.ts.map +1 -0
  56. package/dist/src/ai/schema.js +50 -0
  57. package/dist/src/ai/schema.js.map +1 -0
  58. package/dist/src/ai/service.d.ts +332 -0
  59. package/dist/src/ai/service.d.ts.map +1 -0
  60. package/dist/src/ai/service.js +751 -0
  61. package/dist/src/ai/service.js.map +1 -0
  62. package/dist/src/ai/types.d.ts +196 -0
  63. package/dist/src/ai/types.d.ts.map +1 -0
  64. package/dist/src/ai/types.js +23 -0
  65. package/dist/src/ai/types.js.map +1 -0
  66. package/dist/src/ai/validate.d.ts +30 -0
  67. package/dist/src/ai/validate.d.ts.map +1 -0
  68. package/dist/src/ai/validate.js +160 -0
  69. package/dist/src/ai/validate.js.map +1 -0
  70. package/dist/src/ai/worker.d.ts +76 -0
  71. package/dist/src/ai/worker.d.ts.map +1 -0
  72. package/dist/src/ai/worker.js +293 -0
  73. package/dist/src/ai/worker.js.map +1 -0
  74. package/dist/src/audit.d.ts +12 -3
  75. package/dist/src/audit.d.ts.map +1 -1
  76. package/dist/src/audit.js +30 -4
  77. package/dist/src/audit.js.map +1 -1
  78. package/dist/src/chat.d.ts +39 -1
  79. package/dist/src/chat.d.ts.map +1 -1
  80. package/dist/src/chat.js +85 -6
  81. package/dist/src/chat.js.map +1 -1
  82. package/dist/src/chatwarden.d.ts +84 -1
  83. package/dist/src/chatwarden.d.ts.map +1 -1
  84. package/dist/src/chatwarden.js +168 -6
  85. package/dist/src/chatwarden.js.map +1 -1
  86. package/dist/src/decide.d.ts +36 -1
  87. package/dist/src/decide.d.ts.map +1 -1
  88. package/dist/src/decide.js +62 -2
  89. package/dist/src/decide.js.map +1 -1
  90. package/dist/src/documents.d.ts +1 -1
  91. package/dist/src/documents.d.ts.map +1 -1
  92. package/dist/src/documents.js +6 -1
  93. package/dist/src/documents.js.map +1 -1
  94. package/dist/src/freeze.d.ts +3 -0
  95. package/dist/src/freeze.d.ts.map +1 -0
  96. package/dist/src/freeze.js +10 -0
  97. package/dist/src/freeze.js.map +1 -0
  98. package/dist/src/index.d.ts +37 -8
  99. package/dist/src/index.d.ts.map +1 -1
  100. package/dist/src/index.js +23 -3
  101. package/dist/src/index.js.map +1 -1
  102. package/dist/src/ladder.d.ts +28 -0
  103. package/dist/src/ladder.d.ts.map +1 -1
  104. package/dist/src/ladder.js +37 -1
  105. package/dist/src/ladder.js.map +1 -1
  106. package/dist/src/pace.d.ts +66 -0
  107. package/dist/src/pace.d.ts.map +1 -0
  108. package/dist/src/pace.js +111 -0
  109. package/dist/src/pace.js.map +1 -0
  110. package/dist/src/pacing.d.ts +63 -0
  111. package/dist/src/pacing.d.ts.map +1 -0
  112. package/dist/src/pacing.js +198 -0
  113. package/dist/src/pacing.js.map +1 -0
  114. package/dist/src/policy.d.ts +57 -1
  115. package/dist/src/policy.d.ts.map +1 -1
  116. package/dist/src/policy.js +67 -4
  117. package/dist/src/policy.js.map +1 -1
  118. package/dist/src/profile.d.ts +64 -8
  119. package/dist/src/profile.d.ts.map +1 -1
  120. package/dist/src/profile.js +98 -27
  121. package/dist/src/profile.js.map +1 -1
  122. package/dist/src/profileError.d.ts +10 -0
  123. package/dist/src/profileError.d.ts.map +1 -0
  124. package/dist/src/profileError.js +17 -0
  125. package/dist/src/profileError.js.map +1 -0
  126. package/dist/src/retention.d.ts +28 -0
  127. package/dist/src/retention.d.ts.map +1 -1
  128. package/dist/src/retention.js +42 -10
  129. package/dist/src/retention.js.map +1 -1
  130. package/dist/src/signalCounts.d.ts +37 -0
  131. package/dist/src/signalCounts.d.ts.map +1 -0
  132. package/dist/src/signalCounts.js +117 -0
  133. package/dist/src/signalCounts.js.map +1 -0
  134. package/dist/src/signalInert.d.ts +10 -0
  135. package/dist/src/signalInert.d.ts.map +1 -0
  136. package/dist/src/signalInert.js +28 -0
  137. package/dist/src/signalInert.js.map +1 -0
  138. package/dist/src/signalService.d.ts +101 -0
  139. package/dist/src/signalService.d.ts.map +1 -0
  140. package/dist/src/signalService.js +383 -0
  141. package/dist/src/signalService.js.map +1 -0
  142. package/dist/src/signals.d.ts +186 -0
  143. package/dist/src/signals.d.ts.map +1 -0
  144. package/dist/src/signals.js +361 -0
  145. package/dist/src/signals.js.map +1 -0
  146. package/dist/src/subjects.d.ts +2 -0
  147. package/dist/src/subjects.d.ts.map +1 -1
  148. package/dist/src/subjects.js +4 -0
  149. package/dist/src/subjects.js.map +1 -1
  150. package/dist/src/team.d.ts +27 -0
  151. package/dist/src/team.d.ts.map +1 -1
  152. package/dist/src/team.js +92 -4
  153. package/dist/src/team.js.map +1 -1
  154. package/dist/src/types.d.ts +324 -2
  155. package/dist/src/types.d.ts.map +1 -1
  156. package/dist/src/types.js.map +1 -1
  157. package/package.json +2 -2
  158. package/src/ai/agreement.ts +106 -0
  159. package/src/ai/breaker.ts +73 -0
  160. package/src/ai/budget.ts +65 -0
  161. package/src/ai/case.ts +74 -0
  162. package/src/ai/casebook.ts +75 -0
  163. package/src/ai/ceilings.ts +68 -0
  164. package/src/ai/fake.ts +105 -0
  165. package/src/ai/hash.ts +23 -0
  166. package/src/ai/inert.ts +26 -0
  167. package/src/ai/injection.ts +32 -0
  168. package/src/ai/lines.ts +216 -0
  169. package/src/ai/prompt.ts +223 -0
  170. package/src/ai/redact.ts +174 -0
  171. package/src/ai/schema.ts +51 -0
  172. package/src/ai/service.ts +961 -0
  173. package/src/ai/types.ts +182 -0
  174. package/src/ai/validate.ts +173 -0
  175. package/src/ai/worker.ts +372 -0
  176. package/src/audit.ts +31 -5
  177. package/src/chat.ts +109 -8
  178. package/src/chatwarden.ts +248 -8
  179. package/src/decide.ts +97 -4
  180. package/src/documents.ts +7 -2
  181. package/src/freeze.ts +8 -0
  182. package/src/index.ts +91 -2
  183. package/src/ladder.ts +59 -1
  184. package/src/pace.ts +139 -0
  185. package/src/pacing.ts +242 -0
  186. package/src/policy.ts +107 -7
  187. package/src/profile.ts +149 -27
  188. package/src/profileError.ts +17 -0
  189. package/src/retention.ts +63 -10
  190. package/src/signalCounts.ts +133 -0
  191. package/src/signalInert.ts +31 -0
  192. package/src/signalService.ts +406 -0
  193. package/src/signals.ts +489 -0
  194. package/src/subjects.ts +5 -0
  195. package/src/team.ts +93 -5
  196. package/src/types.ts +358 -2
package/src/policy.ts CHANGED
@@ -7,6 +7,10 @@ import { playerReporting } from './reporting.js';
7
7
  import type { PlayerReporting } from './reporting.js';
8
8
  import type { RuleRef } from './rules.js';
9
9
  import { errorClass, safeWarn } from './log.js';
10
+ import { RETENTION_DEFAULTS } from './retention.js';
11
+ import { checkSignalFeeds, pruneSignalFeeds, SIGNAL_FEED_NAMES } from './signals.js';
12
+ import type { SignalDropReason } from './signals.js';
13
+ import { RATE_LIMIT, RATE_WINDOW_MS } from './chat.js';
10
14
  import { retryBusy } from './team.js';
11
15
  import { CONDUCT_LEVELS } from './types.js';
12
16
  import type { Clock, ConductLevel, Logger, Store } from './types.js';
@@ -22,13 +26,38 @@ import type { Clock, ConductLevel, Logger, Store } from './types.js';
22
26
  /** How often a read may look at the store for a newer version: 10 seconds. */
23
27
  export const POLICY_REFRESH_MS = 10_000;
24
28
 
29
+ /**
30
+ * A stored signal feed that was dropped when the layer was read: the feed (`record`, `queue`, `ladder`, `ai`, or `unknown` for a name the kit
31
+ * does not have) and why. A code only: never a kind id, a rule id, a label or a number from the stored layer.
32
+ * @experimental
33
+ */
34
+ export interface PolicyDropped {
35
+ feed: string;
36
+ reason: SignalDropReason;
37
+ }
38
+
39
+ /**
40
+ * The kit's own numbers the settings screens need, read only: they come from `createChatwarden` (`limits.chatRate`, `retention.signalsMs`), are
41
+ * never part of the stored layer, and a save cannot change them.
42
+ * @experimental
43
+ */
44
+ export interface PolicyLimits {
45
+ /** The chat rate the kit enforces per room and seat: at most `count` lines in any `windowMs` (default 3 per 5 000 ms). Slow mode and burst sit beside it. */
46
+ chatRate: { count: number; windowMs: number };
47
+ /** How long signal rows are kept, ms: the longest window a signal feed may look back (default 90 days, never less than 14). */
48
+ signalsMs: number;
49
+ }
50
+
25
51
  /** What {@link PolicyService.get} answers. */
26
52
  export interface PolicyState {
27
53
  /** The profile in force: base, then the stored layer. Deep-frozen. */
28
54
  effective: ResolvedProfile;
29
55
  /** The profile from code (preset and overrides), without the stored layer. Deep-frozen. */
30
56
  base: ResolvedProfile;
31
- /** The stored layer as last read (`{}` when none), deep-frozen. */
57
+ /**
58
+ * The layer in force, as last read (`{}` when none), deep-frozen: the stored layer with any signal feed that could no longer be used
59
+ * taken out (see `dropped`). Send it back to `save` and the save is accepted, and repairs the stored row.
60
+ */
32
61
  layer: PolicyLayer;
33
62
  /** The stored layer's version; 0 when nothing was ever saved. Pass it back to `save`. */
34
63
  version: number;
@@ -41,6 +70,19 @@ export interface PolicyState {
41
70
  * valid (a newer kit's field, a hand edit). Either way a save or a full `reset()` repairs it.
42
71
  */
43
72
  layerError?: { path: string; kind: 'unreadable' | 'invalid' };
73
+ /**
74
+ * Present only when the stored layer held signal feeds that could no longer be used (the code stopped declaring their kind, or a
75
+ * window is longer than the retention now allows) and were left out of `layer` and of what is in force. One entry per feed, with the
76
+ * reason of the first thing lost from it. The stored row itself is rewritten by the next save.
77
+ * @experimental
78
+ */
79
+ dropped?: readonly PolicyDropped[];
80
+ /**
81
+ * The chat rate limit actually in force and the signals retention window, so a settings screen can say what slow mode sits beside and how
82
+ * far back a feed may look. Read only, deep-frozen.
83
+ * @experimental
84
+ */
85
+ limits: PolicyLimits;
44
86
  }
45
87
 
46
88
  /** What {@link PolicyService.save} and {@link PolicyService.reset} answer. */
@@ -91,11 +133,18 @@ export class PolicyService {
91
133
  private readonly clock: Clock;
92
134
  private readonly logger: Logger | undefined;
93
135
  private readonly base: ResolvedProfile;
94
- private state: { effective: ResolvedProfile; layer: PolicyLayer; version: number; layerError?: PolicyState['layerError'] };
136
+ private state: { effective: ResolvedProfile; layer: PolicyLayer; version: number; layerError?: PolicyState['layerError']; dropped?: readonly PolicyDropped[] };
95
137
  /** When the store was last looked at (epoch ms), or null before the first read. */
96
138
  private lastCheck: number | null = null;
97
139
 
98
- constructor(deps: { store: Store; clock: Clock; logger: Logger | undefined; base: ResolvedProfile }) {
140
+ /** How long signal rows are kept, ms: a feed window longer than this could never be met. */
141
+ private readonly signalsMs: () => number;
142
+ /** The chat rate in force (`limits.chatRate`), for `get().limits`. */
143
+ private readonly chatRate: { count: number; windowMs: number };
144
+
145
+ constructor(deps: { store: Store; clock: Clock; logger: Logger | undefined; base: ResolvedProfile; signalsMs?: () => number; chatRate?: { count: number; windowMs: number } }) {
146
+ this.signalsMs = deps.signalsMs ?? (() => RETENTION_DEFAULTS.signalsMs);
147
+ this.chatRate = Object.freeze({ count: deps.chatRate?.count ?? RATE_LIMIT, windowMs: deps.chatRate?.windowMs ?? RATE_WINDOW_MS });
99
148
  this.store = deps.store;
100
149
  this.clock = deps.clock;
101
150
  this.logger = deps.logger;
@@ -121,7 +170,10 @@ export class PolicyService {
121
170
  const raw: unknown = stored === null ? {} : stored.layer;
122
171
  const layer = frozenCopy(raw as PolicyLayer);
123
172
  try {
124
- this.state = { effective: applyPolicyLayer(this.base, layer), layer, version };
173
+ // What is read and shown is the layer in force: the stale feeds are out of it, so a save that sends it back is never refused for them.
174
+ const { layer: inForce, dropped } = this.withoutStaleFeeds(layer);
175
+ const shown = dropped.length === 0 ? layer : frozenCopy(inForce);
176
+ this.state = { effective: applyPolicyLayer(this.base, shown), layer: shown, version, ...(dropped.length === 0 ? {} : { dropped: Object.freeze(dropped.map((d) => Object.freeze(d))) }) };
125
177
  } catch (err) {
126
178
  if (!(err instanceof ProfileError)) throw err;
127
179
  // What `get()` shows is always an object: an unreadable layer reads as empty, with the error beside it.
@@ -133,6 +185,36 @@ export class PolicyService {
133
185
  }
134
186
  }
135
187
 
188
+ /**
189
+ * The stored layer with any signal feed that can no longer be used taken out (it names a kind the code stopped declaring, or a window
190
+ * longer than the retention now allows), and what was taken out. Without this one stale feed would make the whole layer unusable and
191
+ * silently drop the owner's other edits too. Logged by feed name only. Anything else wrong with the layer is left for
192
+ * `applyPolicyLayer` to refuse; a layer with nothing to drop comes back as it is.
193
+ */
194
+ private withoutStaleFeeds(layer: PolicyLayer): { layer: PolicyLayer; dropped: PolicyDropped[] } {
195
+ const dropped: PolicyDropped[] = [];
196
+ const signals: unknown = typeof layer === 'object' && layer !== null && !Array.isArray(layer) ? (layer as { signals?: unknown }).signals : undefined;
197
+ const feeds: unknown = typeof signals === 'object' && signals !== null && !Array.isArray(signals) ? (signals as { feeds?: unknown }).feeds : undefined;
198
+ if (typeof feeds !== 'object' || feeds === null || Array.isArray(feeds)) return { layer, dropped };
199
+ const pruned = pruneSignalFeeds(feeds, this.base.signals.kinds, {
200
+ signalsMs: this.signalsMs(),
201
+ onDrop: (name, reason) => {
202
+ const feed = SIGNAL_FEED_NAMES.includes(name) ? name : 'unknown';
203
+ safeWarn(this.logger, 'chatwarden.signal_feed_dropped', { feed });
204
+ dropped.push({ feed, reason });
205
+ },
206
+ });
207
+ if (dropped.length === 0) return { layer, dropped };
208
+ // Nothing usable is left of the section: it is not shown at all, so the code's own feeds are what is in force (a section with a `feeds`
209
+ // key replaces them wholesale, and an empty one would keep them off for a reason nobody can see).
210
+ const { feeds: _gone, ...others } = signals as { feeds?: unknown };
211
+ void _gone;
212
+ const rest = { ...layer } as Record<string, unknown>;
213
+ if (Object.keys(pruned).length === 0 && Object.keys(others).length === 0) delete rest['signals'];
214
+ else rest['signals'] = Object.keys(pruned).length === 0 ? others : { ...others, feeds: pruned };
215
+ return { layer: rest as PolicyLayer, dropped };
216
+ }
217
+
136
218
  /** Look at the store now and adopt a strictly newer version (an older one, say a restored backup, never regresses what is in force). A store failure throws. */
137
219
  private reload(): void {
138
220
  const stored = this.store.loadPolicyLayer?.() ?? null;
@@ -166,8 +248,17 @@ export class PolicyService {
166
248
 
167
249
  get(): PolicyState {
168
250
  this.maybeRefresh();
169
- const { effective, layer, version, layerError } = this.state;
170
- return { effective, base: this.base, layer, version, canSave: this.supported, ...(layerError === undefined ? {} : { layerError: { ...layerError } }) };
251
+ const { effective, layer, version, layerError, dropped } = this.state;
252
+ return {
253
+ effective,
254
+ base: this.base,
255
+ layer,
256
+ version,
257
+ canSave: this.supported,
258
+ ...(layerError === undefined ? {} : { layerError: { ...layerError } }),
259
+ ...(dropped === undefined ? {} : { dropped }),
260
+ limits: Object.freeze({ chatRate: this.chatRate, signalsMs: this.signalsMs() }),
261
+ };
171
262
  }
172
263
 
173
264
  /** Look at the store now, whatever the interval. A store failure throws. */
@@ -191,6 +282,11 @@ export class PolicyService {
191
282
  return { ok: false, error: 'conflict' };
192
283
  }
193
284
  const changed = changedSections(before, layer);
285
+ // The layer this save was judged against had feeds taken out of it (`dropped`): the stored row loses them now, so `signals` changed.
286
+ if (this.state.version === expected && this.state.dropped !== undefined && !changed.includes('signals')) {
287
+ changed.push('signals');
288
+ changed.sort((a, b) => POLICY_SECTIONS.indexOf(a) - POLICY_SECTIONS.indexOf(b));
289
+ }
194
290
  this.lastCheck = this.clock.now();
195
291
  this.adopt({ layer, version: next });
196
292
  return { ok: true, version: next, changed };
@@ -212,7 +308,9 @@ export class PolicyService {
212
308
  return { ok: false, error: 'invalid', path: 'reason' };
213
309
  }
214
310
  try {
215
- applyPolicyLayer(this.base, layer);
311
+ const effective = applyPolicyLayer(this.base, layer);
312
+ // The windows are checked against the retention here, where it is known: a window longer than it could never be met.
313
+ checkSignalFeeds(effective.signals.feeds, effective.signals.kinds, { signalsMs: this.signalsMs() }, 'layer.signals.feeds');
216
314
  } catch (err) {
217
315
  if (err instanceof ProfileError) return { ok: false, error: 'invalid', path: err.path };
218
316
  throw err;
@@ -264,6 +362,8 @@ export class PolicyService {
264
362
  let candidate: ResolvedProfile;
265
363
  try {
266
364
  candidate = applyPolicyLayer(this.base, layer);
365
+ // As save: a window longer than the retention could never be met, so the candidate is refused here too, not only when it is saved.
366
+ checkSignalFeeds(candidate.signals.feeds, candidate.signals.kinds, { signalsMs: this.signalsMs() }, 'layer.signals.feeds');
267
367
  } catch (err) {
268
368
  if (err instanceof ProfileError) return { ok: false, error: 'invalid', path: err.path };
269
369
  throw err;
package/src/profile.ts CHANGED
@@ -18,6 +18,12 @@ import {
18
18
  resolveReporting,
19
19
  } from './reporting.js';
20
20
  import type { ReportingSettings, ResolvedReporting } from './reporting.js';
21
+ import { deepFreeze } from './freeze.js';
22
+ import { mergePace, resolvePace } from './pace.js';
23
+ import type { PaceSettings, ResolvedPace } from './pace.js';
24
+ import { checkSignalFeeds, resolveSignals } from './signals.js';
25
+ import type { ResolvedSignals, SignalFeeds, SignalSettings } from './signals.js';
26
+ import { ProfileError } from './profileError.js';
21
27
 
22
28
  /**
23
29
  * A moderation profile is a game's written standard: what each conduct level means, what happens on a first
@@ -144,8 +150,49 @@ export interface ModerationProfile extends ModerationProfileBase {
144
150
  * {@link ReportingSettings}.
145
151
  */
146
152
  reporting?: ReportingSettings;
153
+ /**
154
+ * The AI read, in the moderator's hands: `level` 0 is off (the default), 1 reads each report and shows a summary, 2 also
155
+ * recommends; `learn` (default true) lets decided cases teach the read. A level 3 or 4 is refused ("not available yet"). The
156
+ * hub edits this section; the code-side AI option sets the adapter and the highest level it may reach. See {@link AISettings}.
157
+ */
158
+ ai?: Partial<AISettings>;
159
+ /**
160
+ * How a room paces a player's lines: a least gap between them (`slowModeMs`), a burst limit (`burst`) and no repeats
161
+ * (`duplicateWindowMs`). Every setting is off until set, so a profile without `pace` changes nothing. See {@link PaceSettings}.
162
+ * @experimental
163
+ */
164
+ pace?: PaceSettings;
165
+ /**
166
+ * Signals: what the game records about a player (muted by others, kicked, left mid-game). `kinds` and `guards` are declared in code
167
+ * only; `feeds` says where counts may be read (the Person page record, the ladder suggestion, the AI read's context, the queue
168
+ * boost) and is editable in the hub. Nothing is unset-only: a profile without `signals` declares no kinds and has no feeds. A signal
169
+ * never acts. See {@link SignalSettings}.
170
+ * @experimental
171
+ */
172
+ signals?: SignalSettings;
173
+ }
174
+
175
+ /**
176
+ * The AI levels and the casebook switch, as the profile holds them. The level in force is also bounded by the adapter and the
177
+ * maximum level given in code, and is 0 when no adapter is configured.
178
+ * @experimental
179
+ */
180
+ export interface AISettings {
181
+ /** 0 off, 1 read, 2 recommend. 3 and 4 are not available yet. */
182
+ level: 0 | 1 | 2;
183
+ /** Whether decided cases may be kept as pseudonymised examples for later reads. Default true. */
184
+ learn: boolean;
185
+ /**
186
+ * The most provider calls the AI may make in a UTC day, a second guard beside the spend cap in code (an adapter that reports no cost
187
+ * cannot run unbounded). A whole number from 1 to 100 000; default 5 000.
188
+ */
189
+ dailyCalls: number;
147
190
  }
148
191
 
192
+ /** The default and the largest value of {@link AISettings.dailyCalls}. */
193
+ export const AI_DAILY_CALLS_DEFAULT = 5000;
194
+ export const AI_DAILY_CALLS_MAX = 100_000;
195
+
149
196
  /**
150
197
  * What `defineProfile`, `resolveProfile`, `applyPolicyLayer`, `cw.profile` and `cw.policy.get()` return: a validated, deep-frozen
151
198
  * profile with `durations` and `customDuration` filled in. It is a {@link ModerationProfile}, so it can be passed wherever one is
@@ -164,6 +211,12 @@ export interface ResolvedProfile extends ModerationProfileBase {
164
211
  customDuration: boolean;
165
212
  /** The reporting settings in force, every field filled in. */
166
213
  reporting: ResolvedReporting;
214
+ /** The AI settings in force, every field filled in. */
215
+ ai: AISettings;
216
+ /** The pace settings in force, every field filled in (`null` is off). @experimental */
217
+ pace: ResolvedPace;
218
+ /** The signal settings in force: the declared kinds merged over the built-ins, the guards filled in, the feeds as given. @experimental */
219
+ signals: ResolvedSignals;
167
220
  }
168
221
 
169
222
  /** @deprecated The same as {@link ModerationProfile}, which now has the two fields optional. */
@@ -179,18 +232,7 @@ export type DeepPartial<T> = T extends readonly unknown[]
179
232
  /** Overrides for {@link resolveProfile}. Any field; arrays replace the preset's array whole. */
180
233
  export type ProfileOverrides = DeepPartial<ModerationProfile>;
181
234
 
182
- /** A profile that fails validation. `path` names the field (`'profile.firstOffense.banter'`); the message never echoes a value. */
183
- export class ProfileError extends Error {
184
- readonly path: string;
185
- /** The rule that was broken, without the path. Never a value. */
186
- readonly reason: string;
187
- constructor(path: string, reason: string) {
188
- super(`${path} ${reason}`);
189
- this.name = 'ProfileError';
190
- this.path = path;
191
- this.reason = reason;
192
- }
193
- }
235
+ export { ProfileError };
194
236
 
195
237
  // ---------------------------------------------------------------------------------------------------------------
196
238
  // Validation
@@ -211,12 +253,16 @@ const TOP_KEYS = [
211
253
  'durations',
212
254
  'customDuration',
213
255
  'reporting',
256
+ 'ai',
257
+ 'pace',
258
+ 'signals',
214
259
  'levels',
215
260
  'guidelines',
216
261
  ] as const;
217
262
  /** Top-level keys that may be left out (the kit falls back to its defaults). */
218
263
  const RULE_LIST_KEYS: readonly string[] = ['areaRules', 'severeRules'];
219
- const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting'];
264
+ const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting', 'ai', 'pace', 'signals'];
265
+ const AI_KEYS = ['level', 'learn', 'dailyCalls'] as const;
220
266
  /** The most rule numbers `areaRules` or `severeRules` may list. */
221
267
  export const MAX_RULE_LIST = 100;
222
268
  const REPEAT_KEYS = ['windowDays', 'notes', 'distinctGames', 'outcome'] as const;
@@ -396,6 +442,23 @@ function lineOf(v: unknown, path: string, min: 0 | 1, max: number): void {
396
442
  }
397
443
  }
398
444
 
445
+ /** The `ai` section, in input shape (both fields optional). Levels 3 and 4 are designed but not built, so they are refused by name. */
446
+ function validateAI(v: unknown, path: string): void {
447
+ const ai = obj(v, path, AI_KEYS, AI_KEYS);
448
+ if (Object.hasOwn(ai, 'level')) {
449
+ const level = ai['level'];
450
+ if (level === 3 || level === 4) fail(`${path}.level`, 'AI levels 3 and 4 are not available yet');
451
+ if (level !== 0 && level !== 1 && level !== 2) fail(`${path}.level`, 'must be 0 (off), 1 (read) or 2 (recommend)');
452
+ }
453
+ if (Object.hasOwn(ai, 'learn') && typeof ai['learn'] !== 'boolean') fail(`${path}.learn`, 'must be true or false');
454
+ if (Object.hasOwn(ai, 'dailyCalls')) {
455
+ const n = ai['dailyCalls'];
456
+ if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > AI_DAILY_CALLS_MAX) {
457
+ fail(`${path}.dailyCalls`, `must be a whole number of calls from 1 to ${AI_DAILY_CALLS_MAX}`);
458
+ }
459
+ }
460
+ }
461
+
399
462
  /** The `reporting` section, in input shape (every field optional, a reason needing only an id and a label). */
400
463
  function validateReporting(v: unknown, path: string): void {
401
464
  const rep = obj(v, path, REPORTING_KEYS, REPORTING_KEYS);
@@ -477,6 +540,9 @@ export function validateProfile(value: unknown): asserts value is ModerationProf
477
540
  if (Object.hasOwn(p, 'durations')) validateDurations(p['durations'], 'profile.durations');
478
541
  if (Object.hasOwn(p, 'customDuration') && typeof p['customDuration'] !== 'boolean') fail('profile.customDuration', 'must be true or false');
479
542
  if (Object.hasOwn(p, 'reporting')) validateReporting(p['reporting'], 'profile.reporting');
543
+ if (Object.hasOwn(p, 'ai')) validateAI(p['ai'], 'profile.ai');
544
+ if (Object.hasOwn(p, 'pace')) resolvePace(p['pace'] as PaceSettings, 'profile.pace');
545
+ if (Object.hasOwn(p, 'signals')) resolveSignals(p['signals'] as SignalSettings, 'profile.signals');
480
546
 
481
547
  const prof = obj(p['profanity'], 'profile.profanity', PROFANITY_KEYS);
482
548
  oneOf(prof['mode'], 'profile.profanity.mode', PROFANITY_MODES, "must be 'allow', 'star' or 'refuse'");
@@ -538,14 +604,6 @@ function merge(base: unknown, over: unknown, depth = 0): unknown {
538
604
  return clone(over, depth);
539
605
  }
540
606
 
541
- function deepFreeze<T>(v: T): T {
542
- if (typeof v === 'object' && v !== null && !Object.isFrozen(v)) {
543
- Object.freeze(v);
544
- for (const item of Object.values(v)) deepFreeze(item);
545
- }
546
- return v;
547
- }
548
-
549
607
  /** Drop repeated numbers from `areaRules` and `severeRules` (first one wins, order kept) before they are validated. */
550
608
  function dedupeRuleLists(copy: unknown): void {
551
609
  if (!isPlain(copy)) return;
@@ -572,9 +630,16 @@ function dedupeReasonRules(copy: Record<string, unknown>): void {
572
630
  });
573
631
  }
574
632
 
575
- /** A profile written before `durations`, `customDuration` and `reporting` existed gets their defaults. */
633
+ /** The AI settings with every field filled in; a value of the wrong shape is returned as it is, for the validator to name. */
634
+ function fillAI(value: unknown): unknown {
635
+ if (value === undefined) return { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT };
636
+ return isPlain(value) ? { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...value } : value;
637
+ }
638
+
639
+ /** A profile written before `durations`, `customDuration`, `reporting` and `ai` existed gets their defaults. */
576
640
  function fillDefaults(copy: unknown): void {
577
641
  if (!isPlain(copy)) return;
642
+ setOwn(copy, 'ai', fillAI(copy['ai']));
578
643
  if (!Object.hasOwn(copy, 'durations')) setOwn(copy, 'durations', [...DEFAULT_DURATIONS]);
579
644
  if (!Object.hasOwn(copy, 'customDuration')) setOwn(copy, 'customDuration', true);
580
645
  // A section of the wrong shape is left as it is, for the validator to name; one that checks out is filled in.
@@ -588,6 +653,11 @@ function finalize(value: unknown): ResolvedProfile {
588
653
  dedupeRuleLists(copy);
589
654
  fillDefaults(copy);
590
655
  validateProfile(copy);
656
+ // Checked above, so this cannot throw: every pace field is filled in, `null` meaning off.
657
+ if (isPlain(copy)) {
658
+ setOwn(copy, 'pace', resolvePace(copy['pace'] as PaceSettings | undefined, 'profile.pace'));
659
+ setOwn(copy, 'signals', resolveSignals(copy['signals'] as SignalSettings | undefined, 'profile.signals'));
660
+ }
591
661
  return deepFreeze(copy as ResolvedProfile);
592
662
  }
593
663
 
@@ -596,7 +666,15 @@ function finalize(value: unknown): ResolvedProfile {
596
666
  * changed and the profile is not validated here (`validateProfile` does that). Used by the document functions.
597
667
  */
598
668
  export function withDurationDefaults(p: ModerationProfile): ResolvedProfile {
599
- return { ...p, durations: p.durations ?? [...DEFAULT_DURATIONS], customDuration: p.customDuration ?? true, reporting: resolveReporting(p.reporting) };
669
+ return {
670
+ ...p,
671
+ durations: p.durations ?? [...DEFAULT_DURATIONS],
672
+ customDuration: p.customDuration ?? true,
673
+ reporting: resolveReporting(p.reporting),
674
+ ai: { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...p.ai },
675
+ pace: resolvePace(p.pace),
676
+ signals: resolveSignals(p.signals),
677
+ };
600
678
  }
601
679
 
602
680
  // ---------------------------------------------------------------------------------------------------------------
@@ -916,7 +994,7 @@ export function defineProfile(p: ModerationProfile): ResolvedProfile {
916
994
  * The parts of a profile the hub may edit, and the order they are listed in. Everything else (identity, the written
917
995
  * levels, the AI context, profanity handling) stays in code: changing profanity means rebuilding the filter.
918
996
  */
919
- export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting'] as const;
997
+ export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting', 'ai', 'pace', 'signals'] as const;
920
998
  export type PolicySection = (typeof POLICY_SECTIONS)[number];
921
999
 
922
1000
  /** One ladder cell as the editor sends it: the label may be left out and is then generated ("Restrict chat 6 hours"). */
@@ -950,6 +1028,18 @@ export interface PolicyLayer {
950
1028
  guidelines?: Array<{ outcome: string } | null>;
951
1029
  /** The reporting settings: `flow` and `thanks` replace the profile's; `reasons` replaces the whole list. Each is optional; a reason needs only `id` and `label`. */
952
1030
  reporting?: ReportingSettings;
1031
+ /** The AI settings: `level` (0 off, 1 read, 2 recommend), `learn` and `dailyCalls` (the owner's ceiling on calls in a UTC day, a whole number from 1 to 100 000). Each is optional and merges onto the profile's. Levels 3 and 4 are refused. */
1032
+ ai?: Partial<AISettings>;
1033
+ /**
1034
+ * The pace settings: each field is optional and merges onto the profile's (a field left out inherits, `null` turns it off, a value sets
1035
+ * it); `burst` replaces whole. @experimental
1036
+ */
1037
+ pace?: PaceSettings;
1038
+ /**
1039
+ * The signal feeds: only `feeds` may be edited (the kinds and the guards are declared in code). The layer's `feeds` REPLACE the
1040
+ * profile's wholesale, like every other section: a feed left out is off. A feed names declared kinds only. @experimental
1041
+ */
1042
+ signals?: { feeds?: SignalFeeds };
953
1043
  }
954
1044
 
955
1045
  /** The longest outcome text a layer may set on a guideline tier. */
@@ -997,6 +1087,28 @@ function wholeOutcome(v: unknown, path: string): void {
997
1087
  if (!Object.hasOwn(v, 'durationMs')) fail(`${path}.durationMs`, 'is required');
998
1088
  }
999
1089
 
1090
+ /**
1091
+ * A layer's `signals` may hold only `feeds`, and every feed must name kinds the profile declares. The feeds themselves are not put in
1092
+ * the overrides: they replace the profile's wholesale, which the deep merge would not do, so `applyPolicyLayer` sets them after it.
1093
+ */
1094
+ function layerSignals(base: ModerationProfile, value: unknown): void {
1095
+ if (!isPlain(value)) return fail('profile.signals', 'must be an object');
1096
+ for (const k of Object.keys(value)) {
1097
+ if (k !== 'feeds') fail(`profile.signals.${k}`, 'is not an editable setting: kinds and guards are declared in code');
1098
+ }
1099
+ const feeds = Object.hasOwn(value, 'feeds') ? value['feeds'] : undefined;
1100
+ checkSignalFeeds(feeds as SignalFeeds | undefined, resolveSignals(base.signals, 'profile.signals').kinds, { signalsMs: Infinity }, 'profile.signals.feeds');
1101
+ }
1102
+
1103
+ /** Put the layer's signal feeds in place of the merged profile's (a feed the layer leaves out is off). */
1104
+ function replaceSignalFeeds(merged: unknown, layer: unknown): void {
1105
+ if (!isPlain(merged) || !isPlain(layer) || !Object.hasOwn(layer, 'signals') || !isPlain(layer['signals'])) return;
1106
+ const feeds = Object.hasOwn(layer['signals'], 'feeds') ? layer['signals']['feeds'] : undefined;
1107
+ const section = isPlain(merged['signals']) ? merged['signals'] : {};
1108
+ setOwn(section, 'feeds', feeds === undefined ? {} : clone(feeds));
1109
+ setOwn(merged, 'signals', section);
1110
+ }
1111
+
1000
1112
  function layerToOverrides(base: ModerationProfile, layer: unknown): Record<string, unknown> {
1001
1113
  if (!isPlain(layer)) return fail('profile', 'must be an object');
1002
1114
  for (const key of Object.keys(layer)) {
@@ -1010,7 +1122,15 @@ function layerToOverrides(base: ModerationProfile, layer: unknown): Record<strin
1010
1122
  for (const level of Object.keys(value)) wholeOutcome(value[level], `profile.firstOffense.${level}`);
1011
1123
  }
1012
1124
  if (key === 'repeat' && isPlain(value)) wholeOutcome(value['outcome'], 'profile.repeat.outcome');
1013
- if (key === 'ladder') setOwn(out, key, ladderOverride(value));
1125
+ if (key === 'signals') {
1126
+ layerSignals(base, value);
1127
+ continue;
1128
+ }
1129
+ if (key === 'pace') {
1130
+ // Checked on its own so the error names layer.pace..., then merged here so `burst` replaces whole instead of merging by member.
1131
+ resolvePace(value as PaceSettings, 'profile.pace');
1132
+ setOwn(out, key, mergePace(resolvePace(base.pace, 'profile.pace'), value as PaceSettings));
1133
+ } else if (key === 'ladder') setOwn(out, key, ladderOverride(value));
1014
1134
  else if (key === 'guidelines') setOwn(out, key, guidelinesOverride(base, value));
1015
1135
  else setOwn(out, key, value);
1016
1136
  }
@@ -1020,7 +1140,7 @@ function layerToOverrides(base: ModerationProfile, layer: unknown): Record<strin
1020
1140
  /** The same error, with the path named from the layer the editor sent (`profile.ladder[2]` is `layer.ladder[2]`). */
1021
1141
  function inLayerTerms(err: ProfileError): ProfileError {
1022
1142
  const path = err.path === 'profile' ? 'layer' : err.path.startsWith('profile.') ? `layer.${err.path.slice('profile.'.length)}` : err.path;
1023
- return new ProfileError(path, err.reason);
1143
+ return new ProfileError(path, err.reason, err.code);
1024
1144
  }
1025
1145
 
1026
1146
  /**
@@ -1031,7 +1151,9 @@ function inLayerTerms(err: ProfileError): ProfileError {
1031
1151
  */
1032
1152
  export function applyPolicyLayer(base: ModerationProfile, layer: PolicyLayer): ResolvedProfile {
1033
1153
  try {
1034
- return finalize(merge(base, layerToOverrides(base, layer)));
1154
+ const merged = merge(base, layerToOverrides(base, layer));
1155
+ replaceSignalFeeds(merged, layer);
1156
+ return finalize(merged);
1035
1157
  } catch (err) {
1036
1158
  throw err instanceof ProfileError ? inLayerTerms(err) : err;
1037
1159
  }
@@ -0,0 +1,17 @@
1
+ // Kept apart from profile.ts so pace.ts (which profile.ts imports) can throw it without an import cycle.
2
+
3
+ /** A profile that fails validation. `path` names the field (`'profile.firstOffense.banter'`); the message never echoes a value. */
4
+ export class ProfileError extends Error {
5
+ readonly path: string;
6
+ /** The rule that was broken, without the path. Never a value. */
7
+ readonly reason: string;
8
+ /** A stable code for the few failures a caller tells apart (a signal feed's `unknown_kind`, `positive_kind` or `window`); undefined for the rest. */
9
+ readonly code: string | undefined;
10
+ constructor(path: string, reason: string, code?: string) {
11
+ super(`${path} ${reason}`);
12
+ this.name = 'ProfileError';
13
+ this.path = path;
14
+ this.reason = reason;
15
+ this.code = code;
16
+ }
17
+ }
package/src/retention.ts CHANGED
@@ -25,6 +25,21 @@ export interface RetentionPolicy {
25
25
  badFaithMs: number;
26
26
  /** A staff audit entry is deleted once it is older than this. */
27
27
  auditMs: number;
28
+ /**
29
+ * An AI outcome row (the agree-or-override record: ids and counts, no chat text) is kept this long. At least 90 days. A read
30
+ * itself goes with its report (`reportsMs`).
31
+ */
32
+ aiOutcomesMs: number;
33
+ /**
34
+ * The pseudonymised example text kept with an AI outcome is deleted once it is older than this. It is the only chat text that
35
+ * outlives a report, so it is the shortest of the three; 0 keeps no text at all.
36
+ */
37
+ aiExamplesMs: number;
38
+ /**
39
+ * A signal row (what a game recorded about a player, `flood_triggered` included) is deleted once it is older than this. At least 14
40
+ * days: a counting window needs at least two weeks of rows. A feed window longer than this is refused.
41
+ */
42
+ signalsMs: number;
28
43
  }
29
44
 
30
45
  export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
@@ -34,12 +49,15 @@ export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
34
49
  noticesMs: 90 * DAY_MS,
35
50
  badFaithMs: 30 * DAY_MS,
36
51
  auditMs: 365 * DAY_MS,
52
+ aiOutcomesMs: 365 * DAY_MS,
53
+ aiExamplesMs: 180 * DAY_MS,
54
+ signalsMs: 90 * DAY_MS,
37
55
  };
38
56
 
39
57
  /** The ladder looks back 90 days and "My record" shows 90 days, so the rows behind them must outlive that. */
40
58
  const RECORD_FLOOR_MS = 90 * DAY_MS;
41
59
 
42
- const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs'] as const;
60
+ const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs', 'aiOutcomesMs', 'aiExamplesMs', 'signalsMs'] as const;
43
61
 
44
62
  /**
45
63
  * Refuse a retention policy that would delete rows the kit still reads. Only the fields present are checked (an
@@ -48,6 +66,9 @@ const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'ba
48
66
  * - `noticesMs` at least 90 days: "My record" shows that far back
49
67
  * - `badFaithMs` at least `suspendWindowMs`: a bad-faith dismissal weighs against its reporter for that long
50
68
  * - `auditMs` at least 90 days: the staff trail is how a community answers "who did that"
69
+ * - `aiOutcomesMs` at least 90 days: the agree-or-override record is the data the AI's later gates read
70
+ * - `aiExamplesMs` at least 0 (0 keeps no example text at all)
71
+ * - `signalsMs` at least 14 days: a counting window needs at least two weeks of rows
51
72
  *
52
73
  * Every field present must also be a finite number (`reportsMs` and `strikesMs` have no floor, only this).
53
74
  *
@@ -76,6 +97,15 @@ export function checkRetentionFloors(policy: Partial<RetentionPolicy>, suspendWi
76
97
  if (below(policy.auditMs, RECORD_FLOOR_MS)) {
77
98
  throw new ProfileError('retention.auditMs', 'must be at least 90 days: the audit trail answers who did what, and when');
78
99
  }
100
+ if (below(policy.aiOutcomesMs, RECORD_FLOOR_MS)) {
101
+ throw new ProfileError('retention.aiOutcomesMs', 'must be at least 90 days: it is the record of how often the AI and the moderators agreed');
102
+ }
103
+ if (below(policy.aiExamplesMs, 0)) {
104
+ throw new ProfileError('retention.aiExamplesMs', 'must be 0 or more: 0 keeps no example text at all');
105
+ }
106
+ if (below(policy.signalsMs, 14 * DAY_MS)) {
107
+ throw new ProfileError('retention.signalsMs', 'must be at least 14 days: a counting window needs at least two weeks of rows');
108
+ }
79
109
  if (below(policy.badFaithMs, suspendWindowMs)) {
80
110
  throw new ProfileError(
81
111
  'retention.badFaithMs',
@@ -94,6 +124,12 @@ export interface PurgeResult {
94
124
  notices: number;
95
125
  audit: number;
96
126
  webhookKeys: number;
127
+ /** AI reads deleted by the retention pass (a read also goes with its report). 0 for a store without the AI methods. */
128
+ aiReads: number;
129
+ /** AI casebook outcomes deleted. 0 for a store without the AI methods. */
130
+ aiOutcomes: number;
131
+ /** Signal rows deleted (flood_triggered included). 0 for a store without the signal methods. */
132
+ signals: number;
97
133
  }
98
134
 
99
135
  function checkWindow(name: string, ms: number): void {
@@ -114,6 +150,10 @@ function checkWindow(name: string, ms: number): void {
114
150
  * term-editor rows written before the trail existed
115
151
  * - webhook keys: `createdAt < now - 24 h` (incoming-webhook idempotency keys, pending or done)
116
152
  * - mutes: `createdAt < now - 180 days`, the mute TTL (a mute past it is already ignored)
153
+ * - AI reads: `createdAt < now - reportsMs` (a read also goes with its report, in `purgeReports`); AI outcomes (agree-or-override
154
+ * record, no chat text): `decidedAt < now - aiOutcomesMs`; the pseudonymised example kept with an outcome:
155
+ * `decidedAt < now - aiExamplesMs`, the row stays with its counts. A store without the AI methods has none of these.
156
+ * - signals: `at < now - signalsMs` (90 days by default, never less than 14); a store without the signal methods has none
117
157
  * - notices: withdrawn, or a seen warning / report outcome, with `createdAt < now - noticesMs`; or
118
158
  * `until < now - noticesMs`. A notice for a permanent or running sanction is kept while it applies (agrees with
119
159
  * `NoticeService.record`), and an unseen warning is kept until it is seen or withdrawn.
@@ -133,6 +173,9 @@ export async function purge(
133
173
  noticesMs: policy.noticesMs ?? RETENTION_DEFAULTS.noticesMs,
134
174
  badFaithMs: policy.badFaithMs ?? RETENTION_DEFAULTS.badFaithMs,
135
175
  auditMs: policy.auditMs ?? RETENTION_DEFAULTS.auditMs,
176
+ aiOutcomesMs: policy.aiOutcomesMs ?? RETENTION_DEFAULTS.aiOutcomesMs,
177
+ aiExamplesMs: policy.aiExamplesMs ?? RETENTION_DEFAULTS.aiExamplesMs,
178
+ signalsMs: policy.signalsMs ?? RETENTION_DEFAULTS.signalsMs,
136
179
  };
137
180
  if (!Number.isFinite(now)) throw new Error('purge: invalid now');
138
181
  checkWindow('reportsMs', p.reportsMs);
@@ -141,13 +184,23 @@ export async function purge(
141
184
  checkWindow('noticesMs', p.noticesMs);
142
185
  checkWindow('badFaithMs', p.badFaithMs);
143
186
  checkWindow('auditMs', p.auditMs);
144
- return store.transaction(() => ({
145
- reports: store.purgeReports(now - p.reportsMs, now - p.badFaithMs),
146
- sanctions: store.purgeSanctions(now - p.sanctionAfterEndMs),
147
- strikes: store.purgeStrikes(now - p.strikesMs),
148
- mutes: store.purgeMutes(now - MUTE_TTL_MS),
149
- notices: store.purgeNotices(now - p.noticesMs),
150
- audit: store.purgeAudit(now - p.auditMs),
151
- webhookKeys: store.purgeWebhookKeys(now - WEBHOOK_KEY_TTL_MS),
152
- }));
187
+ checkWindow('aiOutcomesMs', p.aiOutcomesMs);
188
+ checkWindow('aiExamplesMs', p.aiExamplesMs);
189
+ checkWindow('signalsMs', p.signalsMs);
190
+ return store.transaction(() => {
191
+ const reports = store.purgeReports(now - p.reportsMs, now - p.badFaithMs);
192
+ const ai = store.purgeAi?.(now - p.reportsMs, now - p.aiOutcomesMs, now - p.aiExamplesMs) ?? { reads: 0, outcomes: 0 };
193
+ return {
194
+ reports,
195
+ sanctions: store.purgeSanctions(now - p.sanctionAfterEndMs),
196
+ strikes: store.purgeStrikes(now - p.strikesMs),
197
+ mutes: store.purgeMutes(now - MUTE_TTL_MS),
198
+ notices: store.purgeNotices(now - p.noticesMs),
199
+ audit: store.purgeAudit(now - p.auditMs),
200
+ webhookKeys: store.purgeWebhookKeys(now - WEBHOOK_KEY_TTL_MS),
201
+ aiReads: ai.reads,
202
+ aiOutcomes: ai.outcomes,
203
+ signals: store.purgeSignals?.(now - p.signalsMs) ?? 0,
204
+ };
205
+ });
153
206
  }