@chatwarden/core 0.1.4 → 0.1.6
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.
- package/README.md +6 -4
- package/dist/src/audit.d.ts +1 -1
- package/dist/src/audit.d.ts.map +1 -1
- package/dist/src/audit.js +2 -0
- package/dist/src/audit.js.map +1 -1
- package/dist/src/chatwarden.d.ts +47 -0
- package/dist/src/chatwarden.d.ts.map +1 -1
- package/dist/src/chatwarden.js +54 -30
- package/dist/src/chatwarden.js.map +1 -1
- package/dist/src/decide.d.ts +16 -2
- package/dist/src/decide.d.ts.map +1 -1
- package/dist/src/decide.js +19 -2
- package/dist/src/decide.js.map +1 -1
- package/dist/src/dismissMany.d.ts +83 -0
- package/dist/src/dismissMany.d.ts.map +1 -0
- package/dist/src/dismissMany.js +165 -0
- package/dist/src/dismissMany.js.map +1 -0
- package/dist/src/index.d.ts +7 -3
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +4 -2
- package/dist/src/index.js.map +1 -1
- package/dist/src/reporterAccuracy.d.ts +54 -0
- package/dist/src/reporterAccuracy.d.ts.map +1 -0
- package/dist/src/reporterAccuracy.js +69 -0
- package/dist/src/reporterAccuracy.js.map +1 -0
- package/dist/src/staffViews.d.ts +8 -0
- package/dist/src/staffViews.d.ts.map +1 -1
- package/dist/src/staffViews.js +4 -0
- package/dist/src/staffViews.js.map +1 -1
- package/dist/src/team.d.ts +19 -0
- package/dist/src/team.d.ts.map +1 -1
- package/dist/src/team.js +97 -18
- package/dist/src/team.js.map +1 -1
- package/dist/src/types.d.ts +26 -1
- package/dist/src/types.d.ts.map +1 -1
- package/dist/src/types.js.map +1 -1
- package/package.json +2 -2
- package/src/audit.ts +2 -0
- package/src/chatwarden.ts +95 -29
- package/src/decide.ts +25 -4
- package/src/dismissMany.ts +220 -0
- package/src/index.ts +25 -2
- package/src/reporterAccuracy.ts +104 -0
- package/src/staffViews.ts +13 -0
- package/src/team.ts +93 -19
- 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
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
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)
|
|
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..
|
|
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
|