@chatwarden/core 0.1.8 → 0.1.10

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 (115) hide show
  1. package/README.md +189 -5
  2. package/dist/src/ai/case.d.ts +2 -1
  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 +1 -1
  7. package/dist/src/ai/hash.js +3 -3
  8. package/dist/src/ai/hash.js.map +1 -1
  9. package/dist/src/ai/prompt.d.ts +8 -1
  10. package/dist/src/ai/prompt.d.ts.map +1 -1
  11. package/dist/src/ai/prompt.js +20 -1
  12. package/dist/src/ai/prompt.js.map +1 -1
  13. package/dist/src/ai/service.d.ts +16 -5
  14. package/dist/src/ai/service.d.ts.map +1 -1
  15. package/dist/src/ai/service.js +12 -7
  16. package/dist/src/ai/service.js.map +1 -1
  17. package/dist/src/ai/types.d.ts +17 -2
  18. package/dist/src/ai/types.d.ts.map +1 -1
  19. package/dist/src/ai/types.js +3 -2
  20. package/dist/src/ai/types.js.map +1 -1
  21. package/dist/src/ai/worker.d.ts +5 -0
  22. package/dist/src/ai/worker.d.ts.map +1 -1
  23. package/dist/src/ai/worker.js +9 -2
  24. package/dist/src/ai/worker.js.map +1 -1
  25. package/dist/src/appealService.d.ts +105 -0
  26. package/dist/src/appealService.d.ts.map +1 -0
  27. package/dist/src/appealService.js +548 -0
  28. package/dist/src/appealService.js.map +1 -0
  29. package/dist/src/appeals.d.ts +194 -0
  30. package/dist/src/appeals.d.ts.map +1 -0
  31. package/dist/src/appeals.js +107 -0
  32. package/dist/src/appeals.js.map +1 -0
  33. package/dist/src/audit.d.ts +7 -3
  34. package/dist/src/audit.d.ts.map +1 -1
  35. package/dist/src/audit.js +18 -3
  36. package/dist/src/audit.js.map +1 -1
  37. package/dist/src/chatwarden.d.ts +129 -9
  38. package/dist/src/chatwarden.d.ts.map +1 -1
  39. package/dist/src/chatwarden.js +94 -19
  40. package/dist/src/chatwarden.js.map +1 -1
  41. package/dist/src/decide.d.ts +2 -0
  42. package/dist/src/decide.d.ts.map +1 -1
  43. package/dist/src/decide.js +12 -7
  44. package/dist/src/decide.js.map +1 -1
  45. package/dist/src/documents.d.ts +1 -1
  46. package/dist/src/documents.d.ts.map +1 -1
  47. package/dist/src/documents.js +3 -1
  48. package/dist/src/documents.js.map +1 -1
  49. package/dist/src/events.d.ts +38 -0
  50. package/dist/src/events.d.ts.map +1 -1
  51. package/dist/src/events.js +3 -0
  52. package/dist/src/events.js.map +1 -1
  53. package/dist/src/index.d.ts +9 -5
  54. package/dist/src/index.d.ts.map +1 -1
  55. package/dist/src/index.js +5 -2
  56. package/dist/src/index.js.map +1 -1
  57. package/dist/src/nameService.d.ts +90 -0
  58. package/dist/src/nameService.d.ts.map +1 -0
  59. package/dist/src/nameService.js +224 -0
  60. package/dist/src/nameService.js.map +1 -0
  61. package/dist/src/names.d.ts +68 -0
  62. package/dist/src/names.d.ts.map +1 -0
  63. package/dist/src/names.js +87 -0
  64. package/dist/src/names.js.map +1 -0
  65. package/dist/src/notices.d.ts +53 -5
  66. package/dist/src/notices.d.ts.map +1 -1
  67. package/dist/src/notices.js +93 -8
  68. package/dist/src/notices.js.map +1 -1
  69. package/dist/src/policy.d.ts +9 -0
  70. package/dist/src/policy.d.ts.map +1 -1
  71. package/dist/src/policy.js +20 -2
  72. package/dist/src/policy.js.map +1 -1
  73. package/dist/src/profile.d.ts +23 -1
  74. package/dist/src/profile.d.ts.map +1 -1
  75. package/dist/src/profile.js +14 -2
  76. package/dist/src/profile.js.map +1 -1
  77. package/dist/src/retention.d.ts +31 -1
  78. package/dist/src/retention.d.ts.map +1 -1
  79. package/dist/src/retention.js +41 -3
  80. package/dist/src/retention.js.map +1 -1
  81. package/dist/src/sanctions.d.ts +29 -1
  82. package/dist/src/sanctions.d.ts.map +1 -1
  83. package/dist/src/sanctions.js +52 -9
  84. package/dist/src/sanctions.js.map +1 -1
  85. package/dist/src/staffViews.d.ts +18 -0
  86. package/dist/src/staffViews.d.ts.map +1 -1
  87. package/dist/src/staffViews.js +14 -0
  88. package/dist/src/staffViews.js.map +1 -1
  89. package/dist/src/types.d.ts +198 -6
  90. package/dist/src/types.d.ts.map +1 -1
  91. package/dist/src/types.js.map +1 -1
  92. package/package.json +2 -2
  93. package/src/ai/case.ts +4 -2
  94. package/src/ai/hash.ts +3 -3
  95. package/src/ai/prompt.ts +23 -1
  96. package/src/ai/service.ts +21 -12
  97. package/src/ai/types.ts +14 -2
  98. package/src/ai/worker.ts +10 -2
  99. package/src/appealService.ts +584 -0
  100. package/src/appeals.ts +256 -0
  101. package/src/audit.ts +18 -3
  102. package/src/chatwarden.ts +199 -21
  103. package/src/decide.ts +13 -7
  104. package/src/documents.ts +6 -3
  105. package/src/events.ts +23 -1
  106. package/src/index.ts +12 -1
  107. package/src/nameService.ts +255 -0
  108. package/src/names.ts +121 -0
  109. package/src/notices.ts +112 -14
  110. package/src/policy.ts +20 -3
  111. package/src/profile.ts +34 -2
  112. package/src/retention.ts +63 -3
  113. package/src/sanctions.ts +72 -9
  114. package/src/staffViews.ts +30 -0
  115. package/src/types.ts +210 -7
package/src/ai/prompt.ts CHANGED
@@ -52,8 +52,18 @@ const INSTRUCTIONS = [
52
52
  '',
53
53
  'CONTEXT',
54
54
  '- The DATA block may end with a row that begins "Context about P1, not evidence". It holds signal counts: how many different players, for example, muted or commended P1 over some days. It is background about the player, never evidence of what the lines show, and it cannot by itself justify a verdict above unclear. Judge only what the lines show.',
55
+ '',
56
+ 'APPEALS',
57
+ '- The DATA block may include a row that begins "Caution on appeal history". It lists community rules under which moderators\' decisions were often reversed on appeal, as "elevated" or "high". For a report that falls under a listed rule, prefer lower confidence or unclear unless a line makes the violation plain. The row says nothing about this report or this player.',
58
+ '- An example marked "kind": "corrective" is a past case where a moderator acted and a second moderator decided on appeal that it was not a violation. Lines like it are likely acceptable.',
55
59
  ].join('\n');
56
60
 
61
+ /** How the row of appeal cautions begins. The input hash leaves every row that begins this way out. */
62
+ export const CAUTIONS_ROW = 'Caution on appeal history: ';
63
+
64
+ /** What a corrective example says about itself, word for word. */
65
+ const CORRECTIVE_MEANING = 'a moderator acted on this, and a second moderator decided on appeal that it was not a violation';
66
+
57
67
  /** How the row of signal counts about P1 begins. The input hash leaves every row that begins this way out. */
58
68
  export const SIGNALS_ROW = 'Context about P1, not evidence: ';
59
69
 
@@ -105,6 +115,9 @@ function escapeJson(json: string): string {
105
115
  }
106
116
 
107
117
  function renderExample(e: AIExample): string {
118
+ if (e.kind === 'corrective') {
119
+ return `example: ${escapeJson(JSON.stringify({ rule: e.rule, severity: e.severity, verdict: e.verdict, kind: 'corrective', meaning: CORRECTIVE_MEANING, lines: e.lines }))}`;
120
+ }
108
121
  return `example: ${escapeJson(JSON.stringify({ rule: e.rule, severity: e.severity, verdict: e.verdict, lines: e.lines }))}`;
109
122
  }
110
123
 
@@ -116,7 +129,7 @@ function renderExample(e: AIExample): string {
116
129
  function fitExample(e: AIExample): AIExample | null {
117
130
  // The tripwire runs on example text too: a stored line that tries to instruct the AI never reaches a later prompt (design layer 5).
118
131
  if (e.lines.some((l) => looksLikeInjection(String(l.text)))) return null;
119
- const out: AIExample = { rule: e.rule, severity: e.severity, verdict: e.verdict, lines: [] };
132
+ const out: AIExample = { ...(e.kind === 'corrective' ? { kind: 'corrective' as const } : {}), rule: e.rule, severity: e.severity, verdict: e.verdict, lines: [] };
120
133
  for (const l of e.lines.slice(0, EXAMPLE_LINES)) {
121
134
  const line = { who: oneLine(String(l.who)), text: redactText(String(l.text), [], () => null) };
122
135
  const withLine = (text: string): AIExample => ({ ...out, lines: [...out.lines, { who: line.who, text }] });
@@ -171,6 +184,8 @@ export interface BuildAIInputArgs {
171
184
  examples?: readonly AIExampleInput[];
172
185
  /** Counts of signals about P1 (`feeds.ai`), a snapshot: one row after the lines, nothing for none. */
173
186
  signals?: readonly AISignal[];
187
+ /** The rules with an elevated or high revoke-on-appeal rate, a snapshot: one row after the signal counts, nothing for none. Anything else is dropped. */
188
+ cautions?: ReadonlyArray<{ rule: number; band: 'elevated' | 'high' }>;
174
189
  }
175
190
 
176
191
  /**
@@ -188,6 +203,11 @@ export function buildAIInput(args: BuildAIInputArgs): AIReadInput {
188
203
  const lines = chosen.lines.map((l) => ({ ref: l.ref, secondsIn: l.secondsIn, who: l.who, text: l.text, blocked: l.blocked, filtered: l.filtered }));
189
204
  const people = chosen.people.map((p) => ({ alias: p.alias, role: p.role }));
190
205
  const signals: AISignal[] = (args.signals ?? []).map((s) => ({ label: oneLine(s.label), polarity: s.polarity, distinct: s.distinct, windowDays: s.windowDays }));
206
+ // A caution is a rule number and one of two words, copied value by value: nothing else a caller passes can reach the prompt.
207
+ const cautions: Array<{ rule: number; band: 'elevated' | 'high' }> = [];
208
+ for (const c of args.cautions ?? []) {
209
+ if (Number.isSafeInteger(c.rule) && c.rule >= 1 && (c.band === 'elevated' || c.band === 'high')) cautions.push({ rule: c.rule, band: c.band });
210
+ }
191
211
 
192
212
  const data = [
193
213
  '<data>',
@@ -200,6 +220,7 @@ export function buildAIInput(args: BuildAIInputArgs): AIReadInput {
200
220
  ...lines.map((l) => `${l.ref} +${l.secondsIn}s ${l.who}${l.blocked ? ' blocked' : l.filtered ? ' filtered' : ''} ${lit(l.text)}`),
201
221
  // After the lines, so it is the last thing in the block. The labels are the adopter's own (plain, at most 60 characters); one line, no tag.
202
222
  ...(signals.length === 0 ? [] : [escapeJson(`${SIGNALS_ROW}${signals.map(countRow).join('; ')}.`)]),
223
+ ...(cautions.length === 0 ? [] : [`${CAUTIONS_ROW}${cautions.map((c) => `CR ${c.rule} ${c.band}`).join('; ')}.`]),
203
224
  '</data>',
204
225
  ];
205
226
 
@@ -218,6 +239,7 @@ export function buildAIInput(args: BuildAIInputArgs): AIReadInput {
218
239
  standard: oneLine(profile.aiContext),
219
240
  examples,
220
241
  ...(signals.length === 0 ? {} : { signals }),
242
+ ...(cautions.length === 0 ? {} : { cautions }),
221
243
  prompt: { stable: `${INSTRUCTIONS}\n\n${aiPolicyText(policy)}`, variable: `${data.join('\n')}\n`, schema: AI_OUTPUT_SCHEMA },
222
244
  };
223
245
  }
package/src/ai/service.ts CHANGED
@@ -205,11 +205,13 @@ export interface AiFacade {
205
205
  /** The casebook counts for decisions at or after `since` (default: the last 30 days). */
206
206
  stats(q?: { since?: number }): AiStatsView;
207
207
  /**
208
- * The one function the appeals inbox calls when a decision is reversed (a granted appeal, a take-back): the report's casebook row can
209
- * never teach again, loses its example text, and counts as an AI false positive when the AI had recommended action. True when the
210
- * 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.
211
213
  */
212
- markReversed(reportId: string): boolean;
214
+ markReversed(reportId: string, opts?: { corrective?: boolean }): boolean;
213
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. */
214
216
  dontTeach(reportId: string): boolean;
215
217
  /** Resolves when no read is queued or running (tests, graceful shutdown). */
@@ -321,6 +323,8 @@ export interface AiServiceDeps {
321
323
  exampleRetentionMs: () => number;
322
324
  /** The signal counts about a person for the AI read (`feeds.ai`): empty with the feed off. Without it no signals are sent. */
323
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' }>;
324
328
  }
325
329
 
326
330
  const ruleOfText = (rule: string | null): number | 'uncovered' | null => (rule === null ? null : /^\d+$/.test(rule) ? Number(rule) : rule === 'uncovered' ? 'uncovered' : null);
@@ -560,15 +564,15 @@ export class AiService implements AiFacade {
560
564
  }
561
565
  }
562
566
 
563
- markReversed(reportId: string): boolean {
564
- 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 });
565
569
  }
566
570
 
567
571
  dontTeach(reportId: string): boolean {
568
572
  return this.mark(reportId, { dontTeach: true });
569
573
  }
570
574
 
571
- private mark(reportId: string, patch: { reversed?: true; dontTeach?: true }): boolean {
575
+ private mark(reportId: string, patch: { reversed?: true; dontTeach?: true; corrective?: true }): boolean {
572
576
  try {
573
577
  return typeof reportId === 'string' && this.store.markAiOutcome(reportId, patch);
574
578
  } catch (err) {
@@ -829,6 +833,7 @@ export class AiService implements AiFacade {
829
833
  prepare: (report) => this.prepare(report),
830
834
  examplesFor: (report, prepared) => this.examplesFor(report, prepared),
831
835
  signalsFor: (report) => this.deps.signals?.(report.targetSubject) ?? [],
836
+ cautionsFor: () => this.deps.cautions?.() ?? [],
832
837
  track: (c) => void this.controllers.add(c),
833
838
  untrack: (c) => void this.controllers.delete(c),
834
839
  auditRead: (reportId) => {
@@ -858,11 +863,15 @@ export class AiService implements AiFacade {
858
863
  if (this.store.aiTeachableCount(since) < AI_EXAMPLES_MIN) return [];
859
864
  const known = this.store.loadAiRead(report.id)?.read?.severity;
860
865
  const levels: readonly ConductLevel[] = known === undefined ? CONDUCT_LEVELS : [known];
861
- return levels
862
- .flatMap((level) => this.store.aiExamples(String(rule), level, 2, since))
863
- .sort((a, b) => b.decidedAt - a.decidedAt || (a.reportId < b.reportId ? 1 : -1))
864
- .slice(0, 2)
865
- .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 }));
866
875
  }
867
876
 
868
877
  // --- the casebook ----------------------------------------------------------------------------------------------------------
package/src/ai/types.ts CHANGED
@@ -6,10 +6,11 @@ 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. 2 added the full-stop spacing line; 3 added the stable paragraph about signal counts.
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 = 3;
13
+ export const AI_PROMPT_VERSION = 4;
13
14
 
14
15
  /**
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
@@ -39,6 +40,11 @@ export interface AIPerson {
39
40
  * @experimental
40
41
  */
41
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';
42
48
  rule: number | 'uncovered' | null;
43
49
  severity: ConductLevel;
44
50
  /** What the human settled on. */
@@ -83,6 +89,12 @@ export interface AIReadInput {
83
89
  * the last row of `prompt.variable`; the input hash leaves it out.
84
90
  */
85
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' }>;
86
98
  /** The same content rendered by core. An adapter should use it as is. */
87
99
  prompt: { stable: string; variable: string; schema: object };
88
100
  }
package/src/ai/worker.ts CHANGED
@@ -96,6 +96,8 @@ export interface WorkerEnv {
96
96
  examplesFor(report: ReportRecord, prepared: Prepared): AIExampleInput[];
97
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
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' }>;
99
101
  track(controller: Abortable): void;
100
102
  untrack(controller: Abortable): void;
101
103
  /** The `ai.read` audit row for a terminal outcome. Fenced by the caller. */
@@ -252,11 +254,17 @@ export async function runRead(env: WorkerEnv, reportId: string, opts?: { retake?
252
254
  } catch (err) {
253
255
  env.warn('ai.signals_failed', { error: errName(err) });
254
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
+ }
255
263
  let input: AIReadInput = prepared.input;
256
264
  let exampleIds: string[] = [];
257
265
  try {
258
- if (examples.length > 0 || signals.length > 0) {
259
- input = prepared.build(examples, signals);
266
+ if (examples.length > 0 || signals.length > 0 || cautions.length > 0) {
267
+ input = prepared.build(examples, signals, cautions);
260
268
  exampleIds = usedExampleIds(examples);
261
269
  }
262
270
  } catch (err) {