@chatwarden/core 0.1.7 → 0.1.9

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 (176) hide show
  1. package/README.md +306 -7
  2. package/dist/src/ai/case.d.ts +4 -3
  3. package/dist/src/ai/case.d.ts.map +1 -1
  4. package/dist/src/ai/case.js +1 -1
  5. package/dist/src/ai/case.js.map +1 -1
  6. package/dist/src/ai/hash.d.ts +3 -1
  7. package/dist/src/ai/hash.d.ts.map +1 -1
  8. package/dist/src/ai/hash.js +5 -2
  9. package/dist/src/ai/hash.js.map +1 -1
  10. package/dist/src/ai/prompt.d.ts +13 -2
  11. package/dist/src/ai/prompt.d.ts.map +1 -1
  12. package/dist/src/ai/prompt.js +31 -1
  13. package/dist/src/ai/prompt.js.map +1 -1
  14. package/dist/src/ai/service.d.ts +21 -6
  15. package/dist/src/ai/service.d.ts.map +1 -1
  16. package/dist/src/ai/service.js +14 -7
  17. package/dist/src/ai/service.js.map +1 -1
  18. package/dist/src/ai/types.d.ts +33 -2
  19. package/dist/src/ai/types.d.ts.map +1 -1
  20. package/dist/src/ai/types.js +3 -2
  21. package/dist/src/ai/types.js.map +1 -1
  22. package/dist/src/ai/worker.d.ts +8 -1
  23. package/dist/src/ai/worker.d.ts.map +1 -1
  24. package/dist/src/ai/worker.js +17 -3
  25. package/dist/src/ai/worker.js.map +1 -1
  26. package/dist/src/appealService.d.ts +105 -0
  27. package/dist/src/appealService.d.ts.map +1 -0
  28. package/dist/src/appealService.js +548 -0
  29. package/dist/src/appealService.js.map +1 -0
  30. package/dist/src/appeals.d.ts +194 -0
  31. package/dist/src/appeals.d.ts.map +1 -0
  32. package/dist/src/appeals.js +107 -0
  33. package/dist/src/appeals.js.map +1 -0
  34. package/dist/src/audit.d.ts +7 -3
  35. package/dist/src/audit.d.ts.map +1 -1
  36. package/dist/src/audit.js +18 -3
  37. package/dist/src/audit.js.map +1 -1
  38. package/dist/src/chat.d.ts +39 -1
  39. package/dist/src/chat.d.ts.map +1 -1
  40. package/dist/src/chat.js +85 -6
  41. package/dist/src/chat.js.map +1 -1
  42. package/dist/src/chatwarden.d.ts +197 -10
  43. package/dist/src/chatwarden.d.ts.map +1 -1
  44. package/dist/src/chatwarden.js +212 -23
  45. package/dist/src/chatwarden.js.map +1 -1
  46. package/dist/src/decide.d.ts +2 -0
  47. package/dist/src/decide.d.ts.map +1 -1
  48. package/dist/src/decide.js +12 -7
  49. package/dist/src/decide.js.map +1 -1
  50. package/dist/src/documents.d.ts +1 -1
  51. package/dist/src/documents.d.ts.map +1 -1
  52. package/dist/src/documents.js +5 -1
  53. package/dist/src/documents.js.map +1 -1
  54. package/dist/src/events.d.ts +38 -0
  55. package/dist/src/events.d.ts.map +1 -1
  56. package/dist/src/events.js +3 -0
  57. package/dist/src/events.js.map +1 -1
  58. package/dist/src/freeze.d.ts +3 -0
  59. package/dist/src/freeze.d.ts.map +1 -0
  60. package/dist/src/freeze.js +10 -0
  61. package/dist/src/freeze.js.map +1 -0
  62. package/dist/src/index.d.ts +20 -9
  63. package/dist/src/index.d.ts.map +1 -1
  64. package/dist/src/index.js +11 -3
  65. package/dist/src/index.js.map +1 -1
  66. package/dist/src/ladder.d.ts +28 -0
  67. package/dist/src/ladder.d.ts.map +1 -1
  68. package/dist/src/ladder.js +37 -1
  69. package/dist/src/ladder.js.map +1 -1
  70. package/dist/src/nameService.d.ts +90 -0
  71. package/dist/src/nameService.d.ts.map +1 -0
  72. package/dist/src/nameService.js +224 -0
  73. package/dist/src/nameService.js.map +1 -0
  74. package/dist/src/names.d.ts +68 -0
  75. package/dist/src/names.d.ts.map +1 -0
  76. package/dist/src/names.js +87 -0
  77. package/dist/src/names.js.map +1 -0
  78. package/dist/src/notices.d.ts +53 -5
  79. package/dist/src/notices.d.ts.map +1 -1
  80. package/dist/src/notices.js +93 -8
  81. package/dist/src/notices.js.map +1 -1
  82. package/dist/src/pace.d.ts +66 -0
  83. package/dist/src/pace.d.ts.map +1 -0
  84. package/dist/src/pace.js +111 -0
  85. package/dist/src/pace.js.map +1 -0
  86. package/dist/src/pacing.d.ts +63 -0
  87. package/dist/src/pacing.d.ts.map +1 -0
  88. package/dist/src/pacing.js +198 -0
  89. package/dist/src/pacing.js.map +1 -0
  90. package/dist/src/policy.d.ts +66 -1
  91. package/dist/src/policy.d.ts.map +1 -1
  92. package/dist/src/policy.js +86 -5
  93. package/dist/src/policy.js.map +1 -1
  94. package/dist/src/profile.d.ts +57 -8
  95. package/dist/src/profile.d.ts.map +1 -1
  96. package/dist/src/profile.js +69 -25
  97. package/dist/src/profile.js.map +1 -1
  98. package/dist/src/profileError.d.ts +10 -0
  99. package/dist/src/profileError.d.ts.map +1 -0
  100. package/dist/src/profileError.js +17 -0
  101. package/dist/src/profileError.js.map +1 -0
  102. package/dist/src/retention.d.ts +40 -1
  103. package/dist/src/retention.d.ts.map +1 -1
  104. package/dist/src/retention.js +50 -3
  105. package/dist/src/retention.js.map +1 -1
  106. package/dist/src/sanctions.d.ts +29 -1
  107. package/dist/src/sanctions.d.ts.map +1 -1
  108. package/dist/src/sanctions.js +52 -9
  109. package/dist/src/sanctions.js.map +1 -1
  110. package/dist/src/signalCounts.d.ts +37 -0
  111. package/dist/src/signalCounts.d.ts.map +1 -0
  112. package/dist/src/signalCounts.js +117 -0
  113. package/dist/src/signalCounts.js.map +1 -0
  114. package/dist/src/signalInert.d.ts +10 -0
  115. package/dist/src/signalInert.d.ts.map +1 -0
  116. package/dist/src/signalInert.js +28 -0
  117. package/dist/src/signalInert.js.map +1 -0
  118. package/dist/src/signalService.d.ts +101 -0
  119. package/dist/src/signalService.d.ts.map +1 -0
  120. package/dist/src/signalService.js +383 -0
  121. package/dist/src/signalService.js.map +1 -0
  122. package/dist/src/signals.d.ts +186 -0
  123. package/dist/src/signals.d.ts.map +1 -0
  124. package/dist/src/signals.js +361 -0
  125. package/dist/src/signals.js.map +1 -0
  126. package/dist/src/staffViews.d.ts +18 -0
  127. package/dist/src/staffViews.d.ts.map +1 -1
  128. package/dist/src/staffViews.js +14 -0
  129. package/dist/src/staffViews.js.map +1 -1
  130. package/dist/src/subjects.d.ts +2 -0
  131. package/dist/src/subjects.d.ts.map +1 -1
  132. package/dist/src/subjects.js +4 -0
  133. package/dist/src/subjects.js.map +1 -1
  134. package/dist/src/team.d.ts +27 -0
  135. package/dist/src/team.d.ts.map +1 -1
  136. package/dist/src/team.js +92 -4
  137. package/dist/src/team.js.map +1 -1
  138. package/dist/src/types.d.ts +254 -7
  139. package/dist/src/types.d.ts.map +1 -1
  140. package/dist/src/types.js.map +1 -1
  141. package/package.json +2 -2
  142. package/src/ai/case.ts +6 -4
  143. package/src/ai/hash.ts +5 -2
  144. package/src/ai/prompt.ts +39 -2
  145. package/src/ai/service.ts +29 -14
  146. package/src/ai/types.ts +31 -2
  147. package/src/ai/worker.ts +20 -4
  148. package/src/appealService.ts +584 -0
  149. package/src/appeals.ts +256 -0
  150. package/src/audit.ts +18 -3
  151. package/src/chat.ts +109 -8
  152. package/src/chatwarden.ts +382 -27
  153. package/src/decide.ts +13 -7
  154. package/src/documents.ts +8 -3
  155. package/src/events.ts +23 -1
  156. package/src/freeze.ts +8 -0
  157. package/src/index.ts +52 -3
  158. package/src/ladder.ts +59 -1
  159. package/src/nameService.ts +255 -0
  160. package/src/names.ts +121 -0
  161. package/src/notices.ts +112 -14
  162. package/src/pace.ts +139 -0
  163. package/src/pacing.ts +242 -0
  164. package/src/policy.ts +125 -8
  165. package/src/profile.ts +115 -25
  166. package/src/profileError.ts +17 -0
  167. package/src/retention.ts +79 -3
  168. package/src/sanctions.ts +72 -9
  169. package/src/signalCounts.ts +133 -0
  170. package/src/signalInert.ts +31 -0
  171. package/src/signalService.ts +406 -0
  172. package/src/signals.ts +489 -0
  173. package/src/staffViews.ts +30 -0
  174. package/src/subjects.ts +5 -0
  175. package/src/team.ts +93 -5
  176. package/src/types.ts +275 -8
package/src/ai/service.ts CHANGED
@@ -21,7 +21,7 @@ import { actionsOnTarget, AI_EXAMPLES_MIN, pickExampleLines } from './casebook.j
21
21
  import type { AiOutcomeArgs } from './casebook.js';
22
22
  import { aiPolicyText } from './prompt.js';
23
23
  import { sha256Hex } from '../crypto.js';
24
- import type { AIExampleInput, AIRead, ModerationAI } from './types.js';
24
+ import type { AIExampleInput, AIRead, AISignal, ModerationAI } from './types.js';
25
25
  import { isFinalRow, Meter, runRead } from './worker.js';
26
26
  import type { AiStore, ReadEnd, WorkerEnv } from './worker.js';
27
27
 
@@ -114,6 +114,8 @@ export interface AiReadView {
114
114
  model: string | null;
115
115
  /** When the read was started, epoch ms. */
116
116
  at: number;
117
+ /** How many signal counts the read was shown (`feeds.ai`); absent when it was shown none. Only the number: the counts stay in the stored row. */
118
+ contextSignals?: number;
117
119
  /** Level 2 only. */
118
120
  recommendation: null | {
119
121
  verdict: 'upheld' | 'noted' | 'no_action' | 'unclear';
@@ -203,11 +205,13 @@ export interface AiFacade {
203
205
  /** The casebook counts for decisions at or after `since` (default: the last 30 days). */
204
206
  stats(q?: { since?: number }): AiStatsView;
205
207
  /**
206
- * The one function the appeals inbox calls when a decision is reversed (a granted appeal, a take-back): the report's casebook row can
207
- * never teach again, loses its example text, and counts as an AI false positive when the AI had recommended action. True when the
208
- * report has a row.
208
+ * The one function the appeals inbox calls when a decision is reversed on appeal: the report's casebook row can never teach as a
209
+ * positive example again and loses its example text. With `{ corrective: true }` (a REVOKE: a second moderator found the decision
210
+ * wrong) the example text is kept and becomes a corrective example, and the row counts as an AI false positive when the AI had
211
+ * recommended action. Without it (a REDUCE: the rule applied, the sanction was too heavy) the row only stops teaching: it is not a
212
+ * false positive and teaches nothing. True when the report has a row.
209
213
  */
210
- markReversed(reportId: string): boolean;
214
+ markReversed(reportId: string, opts?: { corrective?: boolean }): boolean;
211
215
  /** A senior's "don't teach" mark on a decided case: the row can never teach again and loses its example text. True when the report has a row. */
212
216
  dontTeach(reportId: string): boolean;
213
217
  /** Resolves when no read is queued or running (tests, graceful shutdown). */
@@ -317,6 +321,10 @@ export interface AiServiceDeps {
317
321
  audit: (input: AuditRecordInput) => boolean;
318
322
  /** How long the text of a casebook example is kept (`retention.aiExamplesMs`); 0 keeps none. */
319
323
  exampleRetentionMs: () => number;
324
+ /** The signal counts about a person for the AI read (`feeds.ai`): empty with the feed off. Without it no signals are sent. */
325
+ signals?: (subject: SubjectId) => AISignal[];
326
+ /** The rules with an elevated or high revoke-on-appeal rate (90 days): empty with appeals off. Without it no cautions are sent. */
327
+ cautions?: () => Array<{ rule: number; band: 'elevated' | 'high' }>;
320
328
  }
321
329
 
322
330
  const ruleOfText = (rule: string | null): number | 'uncovered' | null => (rule === null ? null : /^\d+$/.test(rule) ? Number(rule) : rule === 'uncovered' ? 'uncovered' : null);
@@ -556,15 +564,15 @@ export class AiService implements AiFacade {
556
564
  }
557
565
  }
558
566
 
559
- markReversed(reportId: string): boolean {
560
- return this.mark(reportId, { reversed: true });
567
+ markReversed(reportId: string, opts?: { corrective?: boolean }): boolean {
568
+ return this.mark(reportId, opts?.corrective === true ? { reversed: true, corrective: true } : { reversed: true });
561
569
  }
562
570
 
563
571
  dontTeach(reportId: string): boolean {
564
572
  return this.mark(reportId, { dontTeach: true });
565
573
  }
566
574
 
567
- private mark(reportId: string, patch: { reversed?: true; dontTeach?: true }): boolean {
575
+ private mark(reportId: string, patch: { reversed?: true; dontTeach?: true; corrective?: true }): boolean {
568
576
  try {
569
577
  return typeof reportId === 'string' && this.store.markAiOutcome(reportId, patch);
570
578
  } catch (err) {
@@ -764,7 +772,7 @@ export class AiService implements AiFacade {
764
772
  return made;
765
773
  }
766
774
 
767
- private view(row: { id: string; read: AIRead | null; inputHash: string; model: string | null; createdAt: number }, report: ReportRecord, prepared: Prepared, level: number): AiReadView {
775
+ private view(row: { id: string; read: AIRead | null; inputHash: string; model: string | null; createdAt: number; signals?: readonly AISignal[] | null }, report: ReportRecord, prepared: Prepared, level: number): AiReadView {
768
776
  const read = row.read as AIRead;
769
777
  const rec = read.recommendation;
770
778
  return {
@@ -778,6 +786,7 @@ export class AiService implements AiFacade {
778
786
  injectionSuspected: read.injectionSuspected,
779
787
  model: row.model,
780
788
  at: row.createdAt,
789
+ ...(row.signals === null || row.signals === undefined ? {} : { contextSignals: row.signals.length }),
781
790
  recommendation: level >= 2 && rec !== null ? { verdict: rec.verdict, severity: rec.severity, rule: rec.rule, evidenceLineIds: [...rec.evidence], ...this.stepFor(report, prepared, rec) } : null,
782
791
  };
783
792
  }
@@ -823,6 +832,8 @@ export class AiService implements AiFacade {
823
832
  closed: () => this.isClosed,
824
833
  prepare: (report) => this.prepare(report),
825
834
  examplesFor: (report, prepared) => this.examplesFor(report, prepared),
835
+ signalsFor: (report) => this.deps.signals?.(report.targetSubject) ?? [],
836
+ cautionsFor: () => this.deps.cautions?.() ?? [],
826
837
  track: (c) => void this.controllers.add(c),
827
838
  untrack: (c) => void this.controllers.delete(c),
828
839
  auditRead: (reportId) => {
@@ -852,11 +863,15 @@ export class AiService implements AiFacade {
852
863
  if (this.store.aiTeachableCount(since) < AI_EXAMPLES_MIN) return [];
853
864
  const known = this.store.loadAiRead(report.id)?.read?.severity;
854
865
  const levels: readonly ConductLevel[] = known === undefined ? CONDUCT_LEVELS : [known];
855
- return levels
856
- .flatMap((level) => this.store.aiExamples(String(rule), level, 2, since))
857
- .sort((a, b) => b.decidedAt - a.decidedAt || (a.reportId < b.reportId ? 1 : -1))
858
- .slice(0, 2)
859
- .map((row): AIExampleInput => ({ ...row.example, id: row.reportId }));
866
+ const newest = (a: { decidedAt: number; reportId: string }, b: { decidedAt: number; reportId: string }): number => b.decidedAt - a.decidedAt || (a.reportId < b.reportId ? 1 : -1);
867
+ const rows = levels.flatMap((level) => this.store.aiExamples(String(rule), level, 2, since));
868
+ // At most one of the two slots goes to a corrective example (the newest one); the standard examples fill the rest. The corrective row
869
+ // never counted toward the 30 above, and is only asked for once that threshold is met.
870
+ const corrective = rows.filter((r) => r.kind === 'corrective').sort(newest).slice(0, 1);
871
+ const standard = rows.filter((r) => r.kind !== 'corrective').sort(newest).slice(0, 2 - corrective.length);
872
+ return [...standard, ...corrective]
873
+ .sort(newest)
874
+ .map((row): AIExampleInput => ({ ...row.example, ...(row.kind === 'corrective' ? { kind: 'corrective' as const } : {}), id: row.reportId }));
860
875
  }
861
876
 
862
877
  // --- the casebook ----------------------------------------------------------------------------------------------------------
package/src/ai/types.ts CHANGED
@@ -6,10 +6,23 @@ import type { ConductLevel } from '../types.js';
6
6
 
7
7
  /**
8
8
  * The prompt version. Bumped when the prompt or the output schema changes; part of the input hash, so a bump makes every stored
9
- * read stale.
9
+ * read stale. 2 added the full-stop spacing line; 3 added the stable paragraph about signal counts; 4 added the stable paragraph about
10
+ * appeal cautions and corrective examples.
10
11
  * @experimental
11
12
  */
12
- export const AI_PROMPT_VERSION = 2;
13
+ export const AI_PROMPT_VERSION = 4;
14
+
15
+ /**
16
+ * One signal count about the reported person (P1), as the model is shown it: the adopter's own short label, whether it counts for or
17
+ * against, how many DIFFERENT players, and over how many days. Nothing else about a signal ever leaves the process.
18
+ * @experimental
19
+ */
20
+ export interface AISignal {
21
+ label: string;
22
+ polarity: 'negative' | 'positive';
23
+ distinct: number;
24
+ windowDays: number;
25
+ }
13
26
 
14
27
  /**
15
28
  * One speaker in a read: an alias (`P1` is the reported person, `P2` the reporter, the rest `P3...` in order of first appearance)
@@ -27,6 +40,11 @@ export interface AIPerson {
27
40
  * @experimental
28
41
  */
29
42
  export interface AIExample {
43
+ /**
44
+ * `'corrective'` for a decision a second moderator found wrong on appeal (revoked): shown with fixed wording, as an example of what is
45
+ * NOT a violation. Absent (or `'standard'`) for every other example, and then the example reads exactly as before.
46
+ */
47
+ kind?: 'standard' | 'corrective';
30
48
  rule: number | 'uncovered' | null;
31
49
  severity: ConductLevel;
32
50
  /** What the human settled on. */
@@ -66,6 +84,17 @@ export interface AIReadInput {
66
84
  standard: string;
67
85
  /** Casebook, at most 2, pseudonymised. */
68
86
  examples: AIExample[];
87
+ /**
88
+ * Counts of signals about P1 (`feeds.ai`), a snapshot taken when the read is made; absent with the feed off or nothing to say. Rendered as
89
+ * the last row of `prompt.variable`; the input hash leaves it out.
90
+ */
91
+ signals?: AISignal[];
92
+ /**
93
+ * The rules under which moderators' decisions were often reversed on appeal (the revoke-only rate at the `elevated` or `high` band, over
94
+ * 90 days): rule numbers and bands only, never a number or a person. A snapshot taken when the read is made, rendered as the row after
95
+ * the signal counts; the input hash leaves it out. Absent when appeals are off or no rule qualifies.
96
+ */
97
+ cautions?: Array<{ rule: number; band: 'elevated' | 'high' }>;
69
98
  /** The same content rendered by core. An adapter should use it as is. */
70
99
  prompt: { stable: string; variable: string; schema: object };
71
100
  }
package/src/ai/worker.ts CHANGED
@@ -5,7 +5,7 @@ import type { Breaker } from './breaker.js';
5
5
  import type { Prepared } from './case.js';
6
6
  import { usedExampleIds } from './prompt.js';
7
7
  import { validateAIOutput } from './validate.js';
8
- import type { AbortSignalLike, AIExampleInput, AIRead, AIReadInput, AIReadResult, AIUsage, ModerationAI } from './types.js';
8
+ import type { AbortSignalLike, AIExampleInput, AIRead, AIReadInput, AIReadResult, AISignal, AIUsage, ModerationAI } from './types.js';
9
9
 
10
10
  // One read, start to finish (design section 4). The job reserves the right to call (one atomic write on the store, so two processes
11
11
  // make one call), checks the budget, the breaker and the rate, calls the adapter under a deadline, validates the answer in core,
@@ -94,6 +94,10 @@ export interface WorkerEnv {
94
94
  prepare(report: ReportRecord): Prepared;
95
95
  /** Casebook examples for this case, newest first; empty when there are none, learning is off or something fails. */
96
96
  examplesFor(report: ReportRecord, prepared: Prepared): AIExampleInput[];
97
+ /** The signal counts about the reported person (`feeds.ai`): a snapshot for this read; empty when the feed is off or nothing qualifies. Fenced by the caller. */
98
+ signalsFor(report: ReportRecord): AISignal[];
99
+ /** The rules with an elevated or high revoke-on-appeal rate: a snapshot for this read; empty with appeals off or nothing to say. Fenced by the caller. */
100
+ cautionsFor(): Array<{ rule: number; band: 'elevated' | 'high' }>;
97
101
  track(controller: Abortable): void;
98
102
  untrack(controller: Abortable): void;
99
103
  /** The `ai.read` audit row for a terminal outcome. Fenced by the caller. */
@@ -244,11 +248,23 @@ export async function runRead(env: WorkerEnv, reportId: string, opts?: { retake?
244
248
  } catch (err) {
245
249
  env.warn('ai.examples_failed', { error: errName(err) });
246
250
  }
251
+ let signals: AISignal[] = [];
252
+ try {
253
+ signals = env.signalsFor(report);
254
+ } catch (err) {
255
+ env.warn('ai.signals_failed', { error: errName(err) });
256
+ }
257
+ let cautions: Array<{ rule: number; band: 'elevated' | 'high' }> = [];
258
+ try {
259
+ cautions = env.cautionsFor();
260
+ } catch (err) {
261
+ env.warn('ai.cautions_failed', { error: errName(err) });
262
+ }
247
263
  let input: AIReadInput = prepared.input;
248
264
  let exampleIds: string[] = [];
249
265
  try {
250
- if (examples.length > 0) {
251
- input = prepared.build(examples);
266
+ if (examples.length > 0 || signals.length > 0 || cautions.length > 0) {
267
+ input = prepared.build(examples, signals, cautions);
252
268
  exampleIds = usedExampleIds(examples);
253
269
  }
254
270
  } catch (err) {
@@ -327,7 +343,7 @@ export async function runRead(env: WorkerEnv, reportId: string, opts?: { retake?
327
343
  recommendation: rec === null ? null : { ...rec, evidence: toIds(rec.evidence) },
328
344
  };
329
345
  env.breaker.success();
330
- const stored = env.store.completeAiRead(id, lease, { ...usage, read, exampleIds });
346
+ const stored = env.store.completeAiRead(id, lease, { ...usage, read, exampleIds, signals: input.signals ?? [] });
331
347
  if (!stored) {
332
348
  env.warn('ai.read_superseded');
333
349
  return NOTHING;