@chatwarden/core 0.1.5 → 0.1.7

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 (131) hide show
  1. package/README.md +51 -1
  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 +13 -0
  31. package/dist/src/ai/hash.d.ts.map +1 -0
  32. package/dist/src/ai/hash.js +19 -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 +44 -0
  47. package/dist/src/ai/prompt.d.ts.map +1 -0
  48. package/dist/src/ai/prompt.js +185 -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 +328 -0
  59. package/dist/src/ai/service.d.ts.map +1 -0
  60. package/dist/src/ai/service.js +749 -0
  61. package/dist/src/ai/service.js.map +1 -0
  62. package/dist/src/ai/types.d.ts +180 -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 +74 -0
  71. package/dist/src/ai/worker.d.ts.map +1 -0
  72. package/dist/src/ai/worker.js +286 -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/chatwarden.d.ts +28 -0
  79. package/dist/src/chatwarden.d.ts.map +1 -1
  80. package/dist/src/chatwarden.js +60 -1
  81. package/dist/src/chatwarden.js.map +1 -1
  82. package/dist/src/decide.d.ts +36 -1
  83. package/dist/src/decide.d.ts.map +1 -1
  84. package/dist/src/decide.js +62 -2
  85. package/dist/src/decide.js.map +1 -1
  86. package/dist/src/documents.d.ts +1 -1
  87. package/dist/src/documents.d.ts.map +1 -1
  88. package/dist/src/documents.js +4 -1
  89. package/dist/src/documents.js.map +1 -1
  90. package/dist/src/index.d.ts +27 -5
  91. package/dist/src/index.d.ts.map +1 -1
  92. package/dist/src/index.js +17 -2
  93. package/dist/src/index.js.map +1 -1
  94. package/dist/src/profile.d.ts +30 -1
  95. package/dist/src/profile.d.ts.map +1 -1
  96. package/dist/src/profile.js +43 -4
  97. package/dist/src/profile.js.map +1 -1
  98. package/dist/src/retention.d.ts +19 -0
  99. package/dist/src/retention.d.ts.map +1 -1
  100. package/dist/src/retention.js +33 -10
  101. package/dist/src/retention.js.map +1 -1
  102. package/dist/src/types.d.ts +269 -2
  103. package/dist/src/types.d.ts.map +1 -1
  104. package/dist/src/types.js.map +1 -1
  105. package/package.json +2 -2
  106. package/src/ai/agreement.ts +106 -0
  107. package/src/ai/breaker.ts +73 -0
  108. package/src/ai/budget.ts +65 -0
  109. package/src/ai/case.ts +74 -0
  110. package/src/ai/casebook.ts +75 -0
  111. package/src/ai/ceilings.ts +68 -0
  112. package/src/ai/fake.ts +105 -0
  113. package/src/ai/hash.ts +20 -0
  114. package/src/ai/inert.ts +26 -0
  115. package/src/ai/injection.ts +32 -0
  116. package/src/ai/lines.ts +216 -0
  117. package/src/ai/prompt.ts +208 -0
  118. package/src/ai/redact.ts +174 -0
  119. package/src/ai/schema.ts +51 -0
  120. package/src/ai/service.ts +955 -0
  121. package/src/ai/types.ts +165 -0
  122. package/src/ai/validate.ts +173 -0
  123. package/src/ai/worker.ts +364 -0
  124. package/src/audit.ts +31 -5
  125. package/src/chatwarden.ts +82 -1
  126. package/src/decide.ts +97 -4
  127. package/src/documents.ts +5 -2
  128. package/src/index.ts +52 -1
  129. package/src/profile.ts +68 -4
  130. package/src/retention.ts +47 -10
  131. package/src/types.ts +294 -2
package/src/decide.ts CHANGED
@@ -1,3 +1,6 @@
1
+ import type { AiOutcomeHook } from './ai/casebook.js';
2
+ import { ROLES } from './audit.js';
3
+ import type { Role } from './audit.js';
1
4
  import { sha256Hex } from './crypto.js';
2
5
  import { safeWarn } from './log.js';
3
6
  import { ownLines } from './notices.js';
@@ -6,7 +9,8 @@ import type { CommunityRules, RuleRef } from './rules.js';
6
9
  import { SANCTION_KINDS, SANCTION_SOURCES, validateSanctionInput, writeSanction } from './sanctions.js';
7
10
  import type { SanctionIndex } from './sanctions.js';
8
11
  import type { SubjectIndex } from './subjects.js';
9
- import type { Clock, Logger, ReportExcerptLine, ReportRecord, SanctionKind, SanctionRow, Source, Store, SubjectId } from './types.js';
12
+ import { CONDUCT_LEVELS } from './types.js';
13
+ import type { AiOutcomeInsert, Clock, ConductLevel, Logger, ReportExcerptLine, ReportRecord, SanctionKind, SanctionRow, Source, Store, SubjectId } from './types.js';
10
14
 
11
15
  // The one path every moderator decision on a report takes. A decision closes the report, writes each sanction and
12
16
  // its player notice, and records itself, all in ONE store transaction: it lands whole or not at all. The same
@@ -82,6 +86,29 @@ export interface DecisionInput {
82
86
  reason?: string;
83
87
  /** Defaults to `'moderator'`. */
84
88
  source?: Source;
89
+ /**
90
+ * AI levels 1 and 2. Optional: the casebook records how every decision compared with the report's AI read whether or not this is
91
+ * given (the server decides, from the stored read and the decision). It only tells the casebook which read the moderator saw, whether
92
+ * they clicked accept, the conduct level of their form and their role. It never changes the decision, its key or its answer, and a
93
+ * part that is not well formed is ignored. Agreement is computed from the stored read and the decision, never from this echo.
94
+ * @experimental
95
+ */
96
+ ai?: DecisionAiEcho;
97
+ }
98
+
99
+ /**
100
+ * What a decision tells the casebook about the AI. `readId` (with `accepted`) is the echo of the read the moderator saw: an id that is
101
+ * not one of this report's finished reads falls back to the newest. `accepted` is a claim that they accepted the pre-fill in one click:
102
+ * it counts only when the decision is the pre-fill. `severity` is the conduct level their form settled on: it counts only when it fits
103
+ * the verdict. Without the echo no example text is kept. `role` is the moderator's, for the `ai.outcome` audit row (without it none is
104
+ * written).
105
+ * @experimental
106
+ */
107
+ export interface DecisionAiEcho {
108
+ readId?: string;
109
+ accepted?: boolean;
110
+ severity?: ConductLevel;
111
+ role?: Role;
85
112
  }
86
113
 
87
114
  /**
@@ -120,6 +147,8 @@ export interface DecisionServiceDeps {
120
147
  * nothing, and the people acted on are still told.
121
148
  */
122
149
  reporterFeedback?: boolean;
150
+ /** AI casebook: the outcome row for a decision made with an AI echo. Fenced; null records nothing. */
151
+ aiOutcome?: AiOutcomeHook;
123
152
  }
124
153
 
125
154
  /**
@@ -146,7 +175,14 @@ export interface AppliedGroup {
146
175
  */
147
176
  export interface DecisionOutcome {
148
177
  result: DecisionResult;
149
- committed: { reportId: string; verdict: DecisionInput['verdict']; at: number; applied: AppliedGroup[] } | null;
178
+ committed: {
179
+ reportId: string;
180
+ verdict: DecisionInput['verdict'];
181
+ at: number;
182
+ applied: AppliedGroup[];
183
+ /** The casebook recorded an outcome with this decision; `role` is the moderator's, for the audit row (null when the echo had none). */
184
+ aiOutcome: { agreement: AiOutcomeInsert['agreement']; role: Role | null; actor: string } | null;
185
+ } | null;
150
186
  }
151
187
 
152
188
  const VERDICTS: readonly DecisionInput['verdict'][] = ['upheld', 'noted', 'no_action', 'bad_faith'];
@@ -191,6 +227,26 @@ interface Normal {
191
227
  source: Source;
192
228
  /** Sorted by canonical subject, then kind. */
193
229
  actions: NormalAction[];
230
+ /** The AI echo, or null when absent or not well formed. Not part of the key. */
231
+ ai: { readId: string | null; accepted: boolean; severity: ConductLevel | null; role: Role | null };
232
+ }
233
+
234
+ /** The longest read id an echo may carry. */
235
+ const AI_READ_ID_MAX = 128;
236
+
237
+ /**
238
+ * The AI echo of an input. Anything that is not well formed is ignored, never an error (the decision matters more): a malformed echo
239
+ * (a bad read id, or an `accepted` that is not a boolean) is as if there were none, but a good role is kept for the audit row.
240
+ */
241
+ function normalizeAi(v: unknown): Normal['ai'] {
242
+ const none: Normal['ai'] = { readId: null, accepted: false, severity: null, role: null };
243
+ if (typeof v !== 'object' || v === null) return none;
244
+ const o = v as Record<string, unknown>;
245
+ const role = (ROLES as readonly unknown[]).includes(o['role']) ? (o['role'] as Role) : null;
246
+ const readId = o['readId'];
247
+ if (typeof readId !== 'string' || readId === '' || readId.length > AI_READ_ID_MAX || typeof o['accepted'] !== 'boolean') return { ...none, role };
248
+ const severity = (CONDUCT_LEVELS as readonly unknown[]).includes(o['severity']) ? (o['severity'] as ConductLevel) : null;
249
+ return { readId, accepted: o['accepted'], severity, role };
194
250
  }
195
251
 
196
252
  const byText = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
@@ -265,6 +321,7 @@ function normalize(subjects: SubjectIndex, input: DecisionInput): Normal {
265
321
  evidence,
266
322
  source: source as Source,
267
323
  actions,
324
+ ai: normalizeAi(input.ai),
268
325
  };
269
326
  }
270
327
 
@@ -330,6 +387,7 @@ export class DecisionService {
330
387
  private readonly index: SanctionIndex | undefined;
331
388
  private readonly logger: Logger | undefined;
332
389
  private readonly reporterFeedback: boolean;
390
+ private readonly aiOutcome: AiOutcomeHook | undefined;
333
391
 
334
392
  constructor(deps: DecisionServiceDeps) {
335
393
  this.store = deps.store;
@@ -340,6 +398,7 @@ export class DecisionService {
340
398
  this.index = deps.index;
341
399
  this.logger = deps.logger;
342
400
  this.reporterFeedback = deps.reporterFeedback ?? true;
401
+ this.aiOutcome = deps.aiOutcome;
343
402
  }
344
403
 
345
404
  /**
@@ -442,6 +501,7 @@ export class DecisionService {
442
501
  const pending = this.index !== undefined && !this.index.isEnabled();
443
502
  const reporter = this.subjects.canonical(report.reporterSubject);
444
503
  const status = isDismissal(norm.verdict) ? 'dismissed' : 'actioned';
504
+ const outcome = this.outcomeFor(norm, report, now);
445
505
 
446
506
  const done = this.store.transaction(() => {
447
507
  if (!this.store.closeReport(report.id, status, norm.verdict === 'bad_faith', norm.actor, now, norm.reason, norm.evidence)) {
@@ -491,7 +551,16 @@ export class DecisionService {
491
551
  told.add(reporter);
492
552
  }
493
553
  this.store.insertDecision(key, report.id, now, JSON.stringify({ groups }));
494
- return { groups, applied, rows, told };
554
+ // The casebook row lands with the decision or not at all. A casebook that cannot be written never fails the decision.
555
+ let recorded: AiOutcomeInsert['agreement'] | null = null;
556
+ if (outcome !== null) {
557
+ try {
558
+ if (this.store.insertAiOutcome?.(outcome) === true) recorded = outcome.agreement;
559
+ } catch (err) {
560
+ this.warn('decide.ai_outcome_failed', { error: errName(err) });
561
+ }
562
+ }
563
+ return { groups, applied, rows, told, recorded };
495
564
  });
496
565
 
497
566
  if (done === null) {
@@ -515,10 +584,34 @@ export class DecisionService {
515
584
  }
516
585
  return {
517
586
  result: { ok: true, groups: done.groups, replay: false },
518
- committed: { reportId: report.id, verdict: norm.verdict, at: now, applied: done.applied },
587
+ committed: {
588
+ reportId: report.id,
589
+ verdict: norm.verdict,
590
+ at: now,
591
+ applied: done.applied,
592
+ aiOutcome: done.recorded === null ? null : { agreement: done.recorded, role: norm.ai.role, actor: norm.actor },
593
+ },
519
594
  };
520
595
  }
521
596
 
597
+ /** The casebook row for this decision, or null: no echo, no hook, no AI store method, or the hook declines or fails. */
598
+ private outcomeFor(norm: Normal, report: ReportRecord, now: number): AiOutcomeInsert | null {
599
+ if (this.aiOutcome === undefined || typeof this.store.insertAiOutcome !== 'function') return null;
600
+ try {
601
+ return this.aiOutcome({
602
+ report,
603
+ target: this.subjects.canonical(report.targetSubject),
604
+ verdict: norm.verdict,
605
+ actions: norm.actions.map((a) => ({ subject: a.subject, kind: a.kind, durationMs: a.durationMs, rule: a.rule, lineIds: a.lineIds })),
606
+ ai: { readId: norm.ai.readId, accepted: norm.ai.accepted, severity: norm.ai.severity },
607
+ now,
608
+ });
609
+ } catch (err) {
610
+ this.warn('decide.ai_outcome_failed', { error: errName(err) });
611
+ return null;
612
+ }
613
+ }
614
+
522
615
  private replayOf(resultJson: string): DecisionResult {
523
616
  const parsed: unknown = JSON.parse(resultJson);
524
617
  const groups = (parsed as { groups?: unknown } | null)?.groups;
package/src/documents.ts CHANGED
@@ -53,7 +53,7 @@ export interface ModeratorGuideOptions {
53
53
  export interface PolicyJson {
54
54
  version: 1;
55
55
  /** With `durations` and `customDuration` filled in, so a profile written for 0.1.1 reads back with the two new keys. */
56
- profile: ResolvedProfile;
56
+ profile: Omit<ResolvedProfile, 'ai'>;
57
57
  /** Every rule, retired ones included, in number order. */
58
58
  rules: CommunityRule[];
59
59
  }
@@ -705,7 +705,10 @@ export function agentBrief(policy: DocumentPolicy): string {
705
705
  */
706
706
  export function policyJson(policy: DocumentPolicy): PolicyJson {
707
707
  const snapshot = checkPolicy(policy);
708
- return { version: 1, profile: structuredClone(snapshot.profile), rules: snapshot.rules.all() };
708
+ // The AI settings are the moderator's runtime switch, not policy text: the document tools never carry them.
709
+ const profile: Omit<ResolvedProfile, 'ai'> & { ai?: unknown } = structuredClone(snapshot.profile);
710
+ delete profile.ai;
711
+ return { version: 1, profile, rules: snapshot.rules.all() };
709
712
  }
710
713
 
711
714
  /** The four documents bound to one policy, as `cw.documents` exposes them. */
package/src/index.ts CHANGED
@@ -1,4 +1,4 @@
1
- export const VERSION = '0.1.5';
1
+ export const VERSION = '0.1.7';
2
2
 
3
3
  export type {
4
4
  Clock,
@@ -26,6 +26,19 @@ export type {
26
26
  SanctionTargetType,
27
27
  ReporterDecision,
28
28
  ReporterOutcomeRow,
29
+ AiCallUsage,
30
+ AiErrorKind,
31
+ AiExampleRow,
32
+ AiOutcomeDetail,
33
+ AiOutcomeInsert,
34
+ AiOutcomeRow,
35
+ AiReadDone,
36
+ AiReadPending,
37
+ AiReadRow,
38
+ AiReadStatus,
39
+ AiReserveResult,
40
+ AiStatsRow,
41
+ AiVerdict,
29
42
  ReporterTally,
30
43
  ClaimAttempt,
31
44
  ClaimMode,
@@ -276,6 +289,7 @@ export {
276
289
  } from './decide.js';
277
290
  export type {
278
291
  DecisionAction,
292
+ DecisionAiEcho,
279
293
  DecisionGroup,
280
294
  DecisionInput,
281
295
  DecisionResult,
@@ -293,6 +307,8 @@ export {
293
307
  MAX_GUIDELINE_OUTCOME,
294
308
  MAX_RULE_LIST,
295
309
  MAX_WINDOW_DAYS,
310
+ AI_DAILY_CALLS_DEFAULT,
311
+ AI_DAILY_CALLS_MAX,
296
312
  POLICY_SECTIONS,
297
313
  PRESETS,
298
314
  ProfileError,
@@ -313,6 +329,7 @@ export type {
313
329
  GuidelineCover,
314
330
  GuidelineTier,
315
331
  LevelDescription,
332
+ AISettings,
316
333
  ModerationProfile,
317
334
  ModerationProfileBase,
318
335
  Outcome,
@@ -327,3 +344,37 @@ export type {
327
344
  ResolvedProfile,
328
345
  RulesFlavour,
329
346
  } from './profile.js';
347
+
348
+ // AI levels 1 and 2: the provider-free contract (@experimental). Kept apart from the rest so a bundler can drop it.
349
+ export { AI_PROMPT_VERSION, AIError } from './ai/types.js';
350
+ export type { AbortSignalLike, AIExample, AIExampleInput, AIPerson, AIRead, AIReadInput, AIReadResult, AIStoredRead, AIUsage, ModerationAI } from './ai/types.js';
351
+ export { AI_OUTPUT_SCHEMA } from './ai/schema.js';
352
+ export { validateAIOutput } from './ai/validate.js';
353
+ export type { AIValidation, AIValidationContext } from './ai/validate.js';
354
+ export { AI_MAX_KIND, AI_MAX_PREFILL_MS, AICeilingError, assertWithinCeilings, automationAllowed, isAllowedKind } from './ai/ceilings.js';
355
+ export { redactNote, redactText } from './ai/redact.js';
356
+ export { chooseLines, redactReportNote } from './ai/lines.js';
357
+ export type { ChosenLine, ChosenLines } from './ai/lines.js';
358
+ export { aiPolicyText, buildAIInput, PROMPT_VERSION, usedExampleIds } from './ai/prompt.js';
359
+ export type { BuildAIInputArgs } from './ai/prompt.js';
360
+ export { inputHash } from './ai/hash.js';
361
+ export { looksLikeInjection } from './ai/injection.js';
362
+ export { aiActorOf, AiService, READ_AGAIN_PER_MINUTE, SWEEP_BATCH, SWEEP_EVERY_MS } from './ai/service.js';
363
+ export { createInertAi } from './ai/inert.js';
364
+ export type {
365
+ AiBrief,
366
+ AiFacade,
367
+ AiOptions,
368
+ AiReadAgain,
369
+ AiReadView,
370
+ AiStatsRuleView,
371
+ AiStatsView,
372
+ AiStatus,
373
+ SuggestionStep,
374
+ } from './ai/service.js';
375
+ export { createFakeModerationAI, fakeRead, FAKE_USAGE } from './ai/fake.js';
376
+ export type { FakeCallContext, FakeModerationAI, FakeScript, FakeStep } from './ai/fake.js';
377
+ export { agreementOf, compareSteps } from './ai/agreement.js';
378
+ export type { Agreement, HumanDecision, StepLike } from './ai/agreement.js';
379
+ export { AI_EXAMPLES_MIN } from './ai/casebook.js';
380
+ export type { AiOutcomeArgs, AiOutcomeHook } from './ai/casebook.js';
package/src/profile.ts CHANGED
@@ -144,8 +144,35 @@ export interface ModerationProfile extends ModerationProfileBase {
144
144
  * {@link ReportingSettings}.
145
145
  */
146
146
  reporting?: ReportingSettings;
147
+ /**
148
+ * The AI read, in the moderator's hands: `level` 0 is off (the default), 1 reads each report and shows a summary, 2 also
149
+ * recommends; `learn` (default true) lets decided cases teach the read. A level 3 or 4 is refused ("not available yet"). The
150
+ * hub edits this section; the code-side AI option sets the adapter and the highest level it may reach. See {@link AISettings}.
151
+ */
152
+ ai?: Partial<AISettings>;
153
+ }
154
+
155
+ /**
156
+ * The AI levels and the casebook switch, as the profile holds them. The level in force is also bounded by the adapter and the
157
+ * maximum level given in code, and is 0 when no adapter is configured.
158
+ * @experimental
159
+ */
160
+ export interface AISettings {
161
+ /** 0 off, 1 read, 2 recommend. 3 and 4 are not available yet. */
162
+ level: 0 | 1 | 2;
163
+ /** Whether decided cases may be kept as pseudonymised examples for later reads. Default true. */
164
+ learn: boolean;
165
+ /**
166
+ * 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
167
+ * cannot run unbounded). A whole number from 1 to 100 000; default 5 000.
168
+ */
169
+ dailyCalls: number;
147
170
  }
148
171
 
172
+ /** The default and the largest value of {@link AISettings.dailyCalls}. */
173
+ export const AI_DAILY_CALLS_DEFAULT = 5000;
174
+ export const AI_DAILY_CALLS_MAX = 100_000;
175
+
149
176
  /**
150
177
  * What `defineProfile`, `resolveProfile`, `applyPolicyLayer`, `cw.profile` and `cw.policy.get()` return: a validated, deep-frozen
151
178
  * profile with `durations` and `customDuration` filled in. It is a {@link ModerationProfile}, so it can be passed wherever one is
@@ -164,6 +191,8 @@ export interface ResolvedProfile extends ModerationProfileBase {
164
191
  customDuration: boolean;
165
192
  /** The reporting settings in force, every field filled in. */
166
193
  reporting: ResolvedReporting;
194
+ /** The AI settings in force, every field filled in. */
195
+ ai: AISettings;
167
196
  }
168
197
 
169
198
  /** @deprecated The same as {@link ModerationProfile}, which now has the two fields optional. */
@@ -211,12 +240,14 @@ const TOP_KEYS = [
211
240
  'durations',
212
241
  'customDuration',
213
242
  'reporting',
243
+ 'ai',
214
244
  'levels',
215
245
  'guidelines',
216
246
  ] as const;
217
247
  /** Top-level keys that may be left out (the kit falls back to its defaults). */
218
248
  const RULE_LIST_KEYS: readonly string[] = ['areaRules', 'severeRules'];
219
- const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting'];
249
+ const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting', 'ai'];
250
+ const AI_KEYS = ['level', 'learn', 'dailyCalls'] as const;
220
251
  /** The most rule numbers `areaRules` or `severeRules` may list. */
221
252
  export const MAX_RULE_LIST = 100;
222
253
  const REPEAT_KEYS = ['windowDays', 'notes', 'distinctGames', 'outcome'] as const;
@@ -396,6 +427,23 @@ function lineOf(v: unknown, path: string, min: 0 | 1, max: number): void {
396
427
  }
397
428
  }
398
429
 
430
+ /** The `ai` section, in input shape (both fields optional). Levels 3 and 4 are designed but not built, so they are refused by name. */
431
+ function validateAI(v: unknown, path: string): void {
432
+ const ai = obj(v, path, AI_KEYS, AI_KEYS);
433
+ if (Object.hasOwn(ai, 'level')) {
434
+ const level = ai['level'];
435
+ if (level === 3 || level === 4) fail(`${path}.level`, 'AI levels 3 and 4 are not available yet');
436
+ if (level !== 0 && level !== 1 && level !== 2) fail(`${path}.level`, 'must be 0 (off), 1 (read) or 2 (recommend)');
437
+ }
438
+ if (Object.hasOwn(ai, 'learn') && typeof ai['learn'] !== 'boolean') fail(`${path}.learn`, 'must be true or false');
439
+ if (Object.hasOwn(ai, 'dailyCalls')) {
440
+ const n = ai['dailyCalls'];
441
+ if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > AI_DAILY_CALLS_MAX) {
442
+ fail(`${path}.dailyCalls`, `must be a whole number of calls from 1 to ${AI_DAILY_CALLS_MAX}`);
443
+ }
444
+ }
445
+ }
446
+
399
447
  /** The `reporting` section, in input shape (every field optional, a reason needing only an id and a label). */
400
448
  function validateReporting(v: unknown, path: string): void {
401
449
  const rep = obj(v, path, REPORTING_KEYS, REPORTING_KEYS);
@@ -477,6 +525,7 @@ export function validateProfile(value: unknown): asserts value is ModerationProf
477
525
  if (Object.hasOwn(p, 'durations')) validateDurations(p['durations'], 'profile.durations');
478
526
  if (Object.hasOwn(p, 'customDuration') && typeof p['customDuration'] !== 'boolean') fail('profile.customDuration', 'must be true or false');
479
527
  if (Object.hasOwn(p, 'reporting')) validateReporting(p['reporting'], 'profile.reporting');
528
+ if (Object.hasOwn(p, 'ai')) validateAI(p['ai'], 'profile.ai');
480
529
 
481
530
  const prof = obj(p['profanity'], 'profile.profanity', PROFANITY_KEYS);
482
531
  oneOf(prof['mode'], 'profile.profanity.mode', PROFANITY_MODES, "must be 'allow', 'star' or 'refuse'");
@@ -572,9 +621,16 @@ function dedupeReasonRules(copy: Record<string, unknown>): void {
572
621
  });
573
622
  }
574
623
 
575
- /** A profile written before `durations`, `customDuration` and `reporting` existed gets their defaults. */
624
+ /** The AI settings with every field filled in; a value of the wrong shape is returned as it is, for the validator to name. */
625
+ function fillAI(value: unknown): unknown {
626
+ if (value === undefined) return { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT };
627
+ return isPlain(value) ? { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...value } : value;
628
+ }
629
+
630
+ /** A profile written before `durations`, `customDuration`, `reporting` and `ai` existed gets their defaults. */
576
631
  function fillDefaults(copy: unknown): void {
577
632
  if (!isPlain(copy)) return;
633
+ setOwn(copy, 'ai', fillAI(copy['ai']));
578
634
  if (!Object.hasOwn(copy, 'durations')) setOwn(copy, 'durations', [...DEFAULT_DURATIONS]);
579
635
  if (!Object.hasOwn(copy, 'customDuration')) setOwn(copy, 'customDuration', true);
580
636
  // A section of the wrong shape is left as it is, for the validator to name; one that checks out is filled in.
@@ -596,7 +652,13 @@ function finalize(value: unknown): ResolvedProfile {
596
652
  * changed and the profile is not validated here (`validateProfile` does that). Used by the document functions.
597
653
  */
598
654
  export function withDurationDefaults(p: ModerationProfile): ResolvedProfile {
599
- return { ...p, durations: p.durations ?? [...DEFAULT_DURATIONS], customDuration: p.customDuration ?? true, reporting: resolveReporting(p.reporting) };
655
+ return {
656
+ ...p,
657
+ durations: p.durations ?? [...DEFAULT_DURATIONS],
658
+ customDuration: p.customDuration ?? true,
659
+ reporting: resolveReporting(p.reporting),
660
+ ai: { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...p.ai },
661
+ };
600
662
  }
601
663
 
602
664
  // ---------------------------------------------------------------------------------------------------------------
@@ -916,7 +978,7 @@ export function defineProfile(p: ModerationProfile): ResolvedProfile {
916
978
  * The parts of a profile the hub may edit, and the order they are listed in. Everything else (identity, the written
917
979
  * levels, the AI context, profanity handling) stays in code: changing profanity means rebuilding the filter.
918
980
  */
919
- export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting'] as const;
981
+ export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting', 'ai'] as const;
920
982
  export type PolicySection = (typeof POLICY_SECTIONS)[number];
921
983
 
922
984
  /** One ladder cell as the editor sends it: the label may be left out and is then generated ("Restrict chat 6 hours"). */
@@ -950,6 +1012,8 @@ export interface PolicyLayer {
950
1012
  guidelines?: Array<{ outcome: string } | null>;
951
1013
  /** 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
1014
  reporting?: ReportingSettings;
1015
+ /** 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. */
1016
+ ai?: Partial<AISettings>;
953
1017
  }
954
1018
 
955
1019
  /** The longest outcome text a layer may set on a guideline tier. */
package/src/retention.ts CHANGED
@@ -25,6 +25,16 @@ 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;
28
38
  }
29
39
 
30
40
  export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
@@ -34,12 +44,14 @@ export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
34
44
  noticesMs: 90 * DAY_MS,
35
45
  badFaithMs: 30 * DAY_MS,
36
46
  auditMs: 365 * DAY_MS,
47
+ aiOutcomesMs: 365 * DAY_MS,
48
+ aiExamplesMs: 180 * DAY_MS,
37
49
  };
38
50
 
39
51
  /** The ladder looks back 90 days and "My record" shows 90 days, so the rows behind them must outlive that. */
40
52
  const RECORD_FLOOR_MS = 90 * DAY_MS;
41
53
 
42
- const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs'] as const;
54
+ const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs', 'aiOutcomesMs', 'aiExamplesMs'] as const;
43
55
 
44
56
  /**
45
57
  * Refuse a retention policy that would delete rows the kit still reads. Only the fields present are checked (an
@@ -48,6 +60,8 @@ const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'ba
48
60
  * - `noticesMs` at least 90 days: "My record" shows that far back
49
61
  * - `badFaithMs` at least `suspendWindowMs`: a bad-faith dismissal weighs against its reporter for that long
50
62
  * - `auditMs` at least 90 days: the staff trail is how a community answers "who did that"
63
+ * - `aiOutcomesMs` at least 90 days: the agree-or-override record is the data the AI's later gates read
64
+ * - `aiExamplesMs` at least 0 (0 keeps no example text at all)
51
65
  *
52
66
  * Every field present must also be a finite number (`reportsMs` and `strikesMs` have no floor, only this).
53
67
  *
@@ -76,6 +90,12 @@ export function checkRetentionFloors(policy: Partial<RetentionPolicy>, suspendWi
76
90
  if (below(policy.auditMs, RECORD_FLOOR_MS)) {
77
91
  throw new ProfileError('retention.auditMs', 'must be at least 90 days: the audit trail answers who did what, and when');
78
92
  }
93
+ if (below(policy.aiOutcomesMs, RECORD_FLOOR_MS)) {
94
+ throw new ProfileError('retention.aiOutcomesMs', 'must be at least 90 days: it is the record of how often the AI and the moderators agreed');
95
+ }
96
+ if (below(policy.aiExamplesMs, 0)) {
97
+ throw new ProfileError('retention.aiExamplesMs', 'must be 0 or more: 0 keeps no example text at all');
98
+ }
79
99
  if (below(policy.badFaithMs, suspendWindowMs)) {
80
100
  throw new ProfileError(
81
101
  'retention.badFaithMs',
@@ -94,6 +114,10 @@ export interface PurgeResult {
94
114
  notices: number;
95
115
  audit: number;
96
116
  webhookKeys: number;
117
+ /** AI reads deleted by the retention pass (a read also goes with its report). 0 for a store without the AI methods. */
118
+ aiReads: number;
119
+ /** AI casebook outcomes deleted. 0 for a store without the AI methods. */
120
+ aiOutcomes: number;
97
121
  }
98
122
 
99
123
  function checkWindow(name: string, ms: number): void {
@@ -114,6 +138,9 @@ function checkWindow(name: string, ms: number): void {
114
138
  * term-editor rows written before the trail existed
115
139
  * - webhook keys: `createdAt < now - 24 h` (incoming-webhook idempotency keys, pending or done)
116
140
  * - mutes: `createdAt < now - 180 days`, the mute TTL (a mute past it is already ignored)
141
+ * - AI reads: `createdAt < now - reportsMs` (a read also goes with its report, in `purgeReports`); AI outcomes (agree-or-override
142
+ * record, no chat text): `decidedAt < now - aiOutcomesMs`; the pseudonymised example kept with an outcome:
143
+ * `decidedAt < now - aiExamplesMs`, the row stays with its counts. A store without the AI methods has none of these.
117
144
  * - notices: withdrawn, or a seen warning / report outcome, with `createdAt < now - noticesMs`; or
118
145
  * `until < now - noticesMs`. A notice for a permanent or running sanction is kept while it applies (agrees with
119
146
  * `NoticeService.record`), and an unseen warning is kept until it is seen or withdrawn.
@@ -133,6 +160,8 @@ export async function purge(
133
160
  noticesMs: policy.noticesMs ?? RETENTION_DEFAULTS.noticesMs,
134
161
  badFaithMs: policy.badFaithMs ?? RETENTION_DEFAULTS.badFaithMs,
135
162
  auditMs: policy.auditMs ?? RETENTION_DEFAULTS.auditMs,
163
+ aiOutcomesMs: policy.aiOutcomesMs ?? RETENTION_DEFAULTS.aiOutcomesMs,
164
+ aiExamplesMs: policy.aiExamplesMs ?? RETENTION_DEFAULTS.aiExamplesMs,
136
165
  };
137
166
  if (!Number.isFinite(now)) throw new Error('purge: invalid now');
138
167
  checkWindow('reportsMs', p.reportsMs);
@@ -141,13 +170,21 @@ export async function purge(
141
170
  checkWindow('noticesMs', p.noticesMs);
142
171
  checkWindow('badFaithMs', p.badFaithMs);
143
172
  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
- }));
173
+ checkWindow('aiOutcomesMs', p.aiOutcomesMs);
174
+ checkWindow('aiExamplesMs', p.aiExamplesMs);
175
+ return store.transaction(() => {
176
+ const reports = store.purgeReports(now - p.reportsMs, now - p.badFaithMs);
177
+ const ai = store.purgeAi?.(now - p.reportsMs, now - p.aiOutcomesMs, now - p.aiExamplesMs) ?? { reads: 0, outcomes: 0 };
178
+ return {
179
+ reports,
180
+ sanctions: store.purgeSanctions(now - p.sanctionAfterEndMs),
181
+ strikes: store.purgeStrikes(now - p.strikesMs),
182
+ mutes: store.purgeMutes(now - MUTE_TTL_MS),
183
+ notices: store.purgeNotices(now - p.noticesMs),
184
+ audit: store.purgeAudit(now - p.auditMs),
185
+ webhookKeys: store.purgeWebhookKeys(now - WEBHOOK_KEY_TTL_MS),
186
+ aiReads: ai.reads,
187
+ aiOutcomes: ai.outcomes,
188
+ };
189
+ });
153
190
  }