@chatwarden/core 0.1.4 → 0.1.5

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 (46) hide show
  1. package/README.md +5 -3
  2. package/dist/src/audit.d.ts +1 -1
  3. package/dist/src/audit.d.ts.map +1 -1
  4. package/dist/src/audit.js +2 -0
  5. package/dist/src/audit.js.map +1 -1
  6. package/dist/src/chatwarden.d.ts +35 -0
  7. package/dist/src/chatwarden.d.ts.map +1 -1
  8. package/dist/src/chatwarden.js +43 -30
  9. package/dist/src/chatwarden.js.map +1 -1
  10. package/dist/src/decide.d.ts +16 -2
  11. package/dist/src/decide.d.ts.map +1 -1
  12. package/dist/src/decide.js +19 -2
  13. package/dist/src/decide.js.map +1 -1
  14. package/dist/src/dismissMany.d.ts +83 -0
  15. package/dist/src/dismissMany.d.ts.map +1 -0
  16. package/dist/src/dismissMany.js +165 -0
  17. package/dist/src/dismissMany.js.map +1 -0
  18. package/dist/src/index.d.ts +7 -3
  19. package/dist/src/index.d.ts.map +1 -1
  20. package/dist/src/index.js +4 -2
  21. package/dist/src/index.js.map +1 -1
  22. package/dist/src/reporterAccuracy.d.ts +54 -0
  23. package/dist/src/reporterAccuracy.d.ts.map +1 -0
  24. package/dist/src/reporterAccuracy.js +69 -0
  25. package/dist/src/reporterAccuracy.js.map +1 -0
  26. package/dist/src/staffViews.d.ts +8 -0
  27. package/dist/src/staffViews.d.ts.map +1 -1
  28. package/dist/src/staffViews.js +4 -0
  29. package/dist/src/staffViews.js.map +1 -1
  30. package/dist/src/team.d.ts +19 -0
  31. package/dist/src/team.d.ts.map +1 -1
  32. package/dist/src/team.js +97 -18
  33. package/dist/src/team.js.map +1 -1
  34. package/dist/src/types.d.ts +26 -1
  35. package/dist/src/types.d.ts.map +1 -1
  36. package/dist/src/types.js.map +1 -1
  37. package/package.json +2 -2
  38. package/src/audit.ts +2 -0
  39. package/src/chatwarden.ts +77 -29
  40. package/src/decide.ts +25 -4
  41. package/src/dismissMany.ts +220 -0
  42. package/src/index.ts +25 -2
  43. package/src/reporterAccuracy.ts +104 -0
  44. package/src/staffViews.ts +13 -0
  45. package/src/team.ts +93 -19
  46. package/src/types.ts +29 -1
package/src/team.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import { randomId } from './crypto.js';
2
2
  import { isValidAuditActor } from './audit.js';
3
+ import { RANK_DOWN_SCAN_MAX, REPORTER_ACCURACY_BATCH_MAX, REPORTER_RANK_LAPSE_MS } from './reporterAccuracy.js';
4
+ import type { ReporterAccuracy } from './reporterAccuracy.js';
3
5
  import { REPORT_CATEGORIES } from './reports.js';
4
6
  import { canonicalReasonId, isReasonId } from './reporting.js';
5
7
  import type { ReportReason } from './reporting.js';
@@ -34,6 +36,9 @@ const VIEWING_SWEEP_AT = 1_000;
34
36
  /** Reports read per page while take next scans for a free case. */
35
37
  const NEXT_PAGE = 200;
36
38
 
39
+ /** With `rankDownHabitual`, candidates are ranked this many at a time (see `next`). */
40
+ const RANK_SLICE = 20;
41
+
37
42
  /** A claim as staff see it. Staff only: `by` is a staff actor. */
38
43
  export interface CaseClaim {
39
44
  by: string;
@@ -185,6 +190,8 @@ export interface TeamDeps {
185
190
  clock: Clock;
186
191
  /** The reporting reasons in force, so an old id (`disruption`) finds the reason that replaced it. Default: none. */
187
192
  reasons?: () => readonly ReportReason[];
193
+ /** How each person's reports have turned out (see `cw.reports.reporterAccuracy`). Without it, `rankDownHabitual` ranks nobody down. */
194
+ accuracy?: (people: readonly SubjectId[]) => Map<SubjectId, ReporterAccuracy>;
188
195
  }
189
196
 
190
197
  /** Claims, take next and viewing. The facade exposes it as `cw.cases`. */
@@ -193,6 +200,7 @@ export class CaseDesk {
193
200
  private readonly subjects: SubjectIndex;
194
201
  private readonly clock: Clock;
195
202
  private readonly reasons: () => readonly ReportReason[];
203
+ private readonly accuracy: NonNullable<TeamDeps['accuracy']>;
196
204
  private readonly presence: ViewingPresence;
197
205
 
198
206
  constructor(deps: TeamDeps) {
@@ -200,6 +208,7 @@ export class CaseDesk {
200
208
  this.subjects = deps.subjects;
201
209
  this.clock = deps.clock;
202
210
  this.reasons = deps.reasons ?? (() => []);
211
+ this.accuracy = deps.accuracy ?? (() => new Map());
203
212
  this.presence = new ViewingPresence(deps.clock);
204
213
  }
205
214
 
@@ -268,15 +277,27 @@ export class CaseDesk {
268
277
  * category, `reason` to cases with an open report that gave that reason id, or none at all for `null`; both may be given), or null. A case is a person, ranked by their OLDEST open report; it opens on their NEWEST. A case
269
278
  * `actor` already holds is skipped. Each candidate is one atomic conditional claim, so two moderators racing never
270
279
  * get the same case.
280
+ *
281
+ * With `rankDownHabitual`, a case is ranked DOWN when none of its open reports has waited {@link REPORTER_RANK_LAPSE_MS} and
282
+ * every open report against the person was filed by a habitual false reporter (`ReporterAccuracy.habitual`: one ordinary
283
+ * reporter, or no accuracy data, keeps the case normal). The first normal case in oldest-first order is claimed; ranked-down
284
+ * ones are remembered in order and, when the scan ends (end of the queue, or {@link RANK_DOWN_SCAN_MAX} reports read), the
285
+ * oldest of them is claimed. Nothing is skipped for good: a queue holding only habitual cases still serves them, oldest first.
271
286
  */
272
- next(actor: string, filter: { category?: ReportCategory; reason?: string | null } = {}): NextCase | null {
287
+ next(actor: string, filter: { category?: ReportCategory; reason?: string | null; rankDownHabitual?: boolean } = {}): NextCase | null {
273
288
  needActor(actor);
274
289
  const category = filter.category;
275
290
  if (category !== undefined && !REPORT_CATEGORIES.includes(category)) throw new RangeError('cases: unknown category');
276
291
  const asked = filter.reason;
277
292
  if (asked !== undefined && asked !== null && !isReasonId(asked)) throw new RangeError('cases: unknown reason');
278
293
  const reason = asked === undefined || asked === null ? asked : canonicalReasonId(this.reasons(), asked);
294
+ const rank = filter.rankDownHabitual;
295
+ if (rank !== undefined && typeof rank !== 'boolean') throw new RangeError('cases: rankDownHabitual must be a boolean');
296
+ const rankDown = rank === true;
279
297
  const seen = new Set<SubjectId>();
298
+ // Ranked-down people in the order the scan met them (oldest first).
299
+ const deferred: SubjectId[] = [];
300
+ let read = 0;
280
301
  let after: { createdAt: number; id: string } | undefined;
281
302
  for (;;) {
282
303
  const page = this.store.listOpenReports({
@@ -285,6 +306,7 @@ export class CaseDesk {
285
306
  ...(after === undefined ? {} : { after: after.createdAt, afterId: after.id }),
286
307
  limit: NEXT_PAGE,
287
308
  });
309
+ read += page.length;
288
310
  // New people on this page, oldest report first. Who already holds one is read once for the whole page, so a held case
289
311
  // costs no write; only the rest get the atomic 'free' claim (which stays the arbiter if a rival slips in).
290
312
  const candidates: SubjectId[] = [];
@@ -295,28 +317,80 @@ export class CaseDesk {
295
317
  candidates.push(person);
296
318
  }
297
319
  const held = new Set(this.store.loadClaims(candidates, this.clock.now()).map((c) => c.person));
298
- for (const person of candidates) {
299
- if (held.has(person)) continue;
300
- const won = retryBusy(() =>
301
- this.store.transaction(() => {
302
- const now = this.clock.now();
303
- const res = this.store.claimCase(person, actor, now, now + CLAIM_TTL_MS, 'free');
304
- if (!res.won) return null;
305
- const newest = this.store.listOpenReportsByPerson(this.subjects.aliasesOf(person), 1)[0];
306
- if (newest === undefined) {
307
- // The case closed under us: do not leave a claim on nothing.
308
- this.store.releaseClaim(person, actor, now);
309
- return null;
310
- }
311
- return { person, reportId: newest.id, claim: claimOf(res.claim) };
312
- }),
313
- );
314
- if (won !== null) return won;
320
+ const free = candidates.filter((p) => !held.has(p));
321
+ // Ranked lazily, a slice at a time: the first ordinary case ends the scan, so "next, next, next" does not read the open
322
+ // reports of a whole page of candidates to claim the first one.
323
+ for (let i = 0; i < free.length; i += RANK_SLICE) {
324
+ const slice = free.slice(i, i + RANK_SLICE);
325
+ const down = rankDown ? this.rankedDown(slice) : new Set<SubjectId>();
326
+ for (const person of slice) {
327
+ if (down.has(person)) {
328
+ deferred.push(person);
329
+ continue;
330
+ }
331
+ const won = this.tryClaim(person, actor);
332
+ if (won !== null) return won;
333
+ }
315
334
  }
316
335
  const last = page[page.length - 1];
317
- if (page.length < NEXT_PAGE || last === undefined) return null;
336
+ if (page.length < NEXT_PAGE || last === undefined) break;
337
+ // Enough read to have looked for a normal case: serve the oldest ranked-down one rather than scan the whole queue.
338
+ if (rankDown && read >= RANK_DOWN_SCAN_MAX && deferred.length > 0) break;
318
339
  after = { createdAt: last.createdAt, id: last.id };
319
340
  }
341
+ if (deferred.length === 0) return null;
342
+ // A rival may have taken one meanwhile: one read of the claims, so a held case costs no write.
343
+ const heldNow = new Set(this.store.loadClaims(deferred, this.clock.now()).map((c) => c.person));
344
+ for (const person of deferred) {
345
+ if (heldNow.has(person)) continue;
346
+ const won = this.tryClaim(person, actor);
347
+ if (won !== null) return won;
348
+ }
349
+ return null;
350
+ }
351
+
352
+ /** One atomic 'free' claim of a person's case, opened on their newest open report; null when a rival won or the case closed. */
353
+ private tryClaim(person: SubjectId, actor: string): NextCase | null {
354
+ return retryBusy(() =>
355
+ this.store.transaction(() => {
356
+ const now = this.clock.now();
357
+ const res = this.store.claimCase(person, actor, now, now + CLAIM_TTL_MS, 'free');
358
+ if (!res.won) return null;
359
+ const newest = this.store.listOpenReportsByPerson(this.subjects.aliasesOf(person), 1)[0];
360
+ if (newest === undefined) {
361
+ // The case closed under us: do not leave a claim on nothing.
362
+ this.store.releaseClaim(person, actor, now);
363
+ return null;
364
+ }
365
+ return { person, reportId: newest.id, claim: claimOf(res.claim) };
366
+ }),
367
+ );
368
+ }
369
+
370
+ /**
371
+ * Which of these people's cases are ranked down: no open report has waited {@link REPORTER_RANK_LAPSE_MS} and every open report
372
+ * against them came from a habitual reporter. One read of each person's open reports and the accuracy of all their reporters
373
+ * (chunked at the accuracy batch limit). A person with more open reports than one read returns is never ranked down.
374
+ */
375
+ private rankedDown(people: readonly SubjectId[]): Set<SubjectId> {
376
+ const out = new Set<SubjectId>();
377
+ if (people.length === 0) return out;
378
+ const now = this.clock.now();
379
+ const reporters = new Map<SubjectId, SubjectId[]>();
380
+ for (const person of people) {
381
+ const open = this.store.listOpenReportsByPerson(this.subjects.aliasesOf(person), 201);
382
+ // 201 or more is a case of its own kind: never bury it. One report past the lapse is a case that has waited long enough.
383
+ if (open.length === 0 || open.length > 200) continue;
384
+ if (open.some((r) => now - r.createdAt >= REPORTER_RANK_LAPSE_MS)) continue;
385
+ reporters.set(person, [...new Set(open.map((r) => this.subjects.canonical(r.reporterSubject)))]);
386
+ }
387
+ const all = [...new Set([...reporters.values()].flat())];
388
+ const habitual = new Set<SubjectId>();
389
+ for (let i = 0; i < all.length; i += REPORTER_ACCURACY_BATCH_MAX) {
390
+ for (const [who, acc] of this.accuracy(all.slice(i, i + REPORTER_ACCURACY_BATCH_MAX))) if (acc.habitual) habitual.add(who);
391
+ }
392
+ for (const [person, who] of reporters) if (who.length > 0 && who.every((r) => habitual.has(r))) out.add(person);
393
+ return out;
320
394
  }
321
395
 
322
396
  /**
package/src/types.ts CHANGED
@@ -218,6 +218,17 @@ export interface ReporterTally {
218
218
  badFaith: number;
219
219
  }
220
220
 
221
+ /**
222
+ * One reporter's decided reports (filed at or after `since`) by outcome, for {@link Store.reporterOutcomes}. `reporter` is the id
223
+ * as stored. `actioned` is `upheld` and `noted` alike; `noAction` is a dismissal without the bad-faith mark and `badFaith` one with it.
224
+ */
225
+ export interface ReporterOutcomeRow {
226
+ reporter: SubjectId;
227
+ actioned: number;
228
+ noAction: number;
229
+ badFaith: number;
230
+ }
231
+
221
232
  /**
222
233
  * One decided report a person filed that carried a reason, with what its decision did: for the reporter's accuracy. `reason` is
223
234
  * the report's stored `reportedReason`; `target` the reported subject as stored; `actions` one entry per sanction group the
@@ -705,10 +716,19 @@ export interface Store {
705
716
  /**
706
717
  * The OPEN reports filed AGAINST any of the given subjects (`targetSubject` as stored: pass the person's canonical id
707
718
  * and every alias merged into it), newest first (`createdAt` descending, then `id` descending), whole records. `limit` is
708
- * clamped to 1..200 (a fraction is floored). An empty list matches nothing.
719
+ * clamped to 1..201 (a fraction is floored; 201 so a caller can ask for 200 and one more to learn whether there is more, as
720
+ * `dismissMany` does: a custom store that clamps at 200 only makes it under-report `more`). An empty list matches nothing.
709
721
  */
710
722
  listOpenReportsByPerson(subjects: readonly SubjectId[], limit: number): ReportRecord[];
711
723
 
724
+ /**
725
+ * OPTIONAL. The OPEN reports FILED BY any of the given subjects (`reporterSubject` as stored: pass the person's canonical id
726
+ * and every alias merged into it), newest first (`createdAt` descending, then `id` descending), whole records. `limit` is
727
+ * clamped to 1..201 (a fraction is floored). An empty list matches nothing. The read behind a bulk dismissal of one reporter's
728
+ * reports; a store that leaves it out is scanned through `listOpenReports` instead (bounded).
729
+ */
730
+ listOpenReportsByReporter?(reporters: readonly SubjectId[], limit: number): ReportRecord[];
731
+
712
732
  /**
713
733
  * How the reports FILED BY any of the given subjects stand (`reporterSubject` as stored: pass the person's canonical id
714
734
  * and every alias merged into it): how many are still open, actioned or dismissed, and how many carry the bad-faith
@@ -725,6 +745,14 @@ export interface Store {
725
745
  */
726
746
  loadReporterDecisions?(reporters: readonly SubjectId[]): ReporterDecision[];
727
747
 
748
+ /**
749
+ * OPTIONAL. How the reports FILED BY any of the given subjects (`reporterSubject` as stored) that are no longer `open` and were
750
+ * filed (`createdAt`) at or after `since` turned out, one row per stored reporter id that has at least one: `actioned` (upheld
751
+ * or noted), `noAction` (dismissed, not marked bad faith) and `badFaith` (dismissed with the mark). The one grouped read behind
752
+ * reporter accuracy. An empty list gives `[]`; a repeated id counts once. A store that leaves it out shows no reporter accuracy.
753
+ */
754
+ reporterOutcomes?(reporters: readonly SubjectId[], since: number): ReporterOutcomeRow[];
755
+
728
756
  /**
729
757
  * OPTIONAL. Attach the reporter's one follow-up to an `open` report that has none yet: set `reportedReason` and `note` (the
730
758
  * FINAL values; the caller has merged them with what the report had) and `detailAt`, atomically. Returns true when this call