@chatwarden/core 0.1.7 → 0.1.8
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 +124 -4
- package/dist/src/ai/case.d.ts +3 -3
- package/dist/src/ai/case.d.ts.map +1 -1
- package/dist/src/ai/case.js +1 -1
- package/dist/src/ai/case.js.map +1 -1
- package/dist/src/ai/hash.d.ts +3 -1
- package/dist/src/ai/hash.d.ts.map +1 -1
- package/dist/src/ai/hash.js +5 -2
- package/dist/src/ai/hash.js.map +1 -1
- package/dist/src/ai/prompt.d.ts +6 -2
- package/dist/src/ai/prompt.d.ts.map +1 -1
- package/dist/src/ai/prompt.js +11 -0
- package/dist/src/ai/prompt.js.map +1 -1
- package/dist/src/ai/service.d.ts +5 -1
- package/dist/src/ai/service.d.ts.map +1 -1
- package/dist/src/ai/service.js +2 -0
- package/dist/src/ai/service.js.map +1 -1
- package/dist/src/ai/types.d.ts +18 -2
- package/dist/src/ai/types.d.ts.map +1 -1
- package/dist/src/ai/types.js +2 -2
- package/dist/src/ai/types.js.map +1 -1
- package/dist/src/ai/worker.d.ts +3 -1
- package/dist/src/ai/worker.d.ts.map +1 -1
- package/dist/src/ai/worker.js +10 -3
- package/dist/src/ai/worker.js.map +1 -1
- package/dist/src/chat.d.ts +39 -1
- package/dist/src/chat.d.ts.map +1 -1
- package/dist/src/chat.js +85 -6
- package/dist/src/chat.js.map +1 -1
- package/dist/src/chatwarden.d.ts +68 -1
- package/dist/src/chatwarden.d.ts.map +1 -1
- package/dist/src/chatwarden.js +119 -5
- package/dist/src/chatwarden.js.map +1 -1
- package/dist/src/documents.d.ts +1 -1
- package/dist/src/documents.d.ts.map +1 -1
- package/dist/src/documents.js +3 -1
- package/dist/src/documents.js.map +1 -1
- package/dist/src/freeze.d.ts +3 -0
- package/dist/src/freeze.d.ts.map +1 -0
- package/dist/src/freeze.js +10 -0
- package/dist/src/freeze.js.map +1 -0
- package/dist/src/index.d.ts +13 -6
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +7 -2
- package/dist/src/index.js.map +1 -1
- package/dist/src/ladder.d.ts +28 -0
- package/dist/src/ladder.d.ts.map +1 -1
- package/dist/src/ladder.js +37 -1
- package/dist/src/ladder.js.map +1 -1
- package/dist/src/pace.d.ts +66 -0
- package/dist/src/pace.d.ts.map +1 -0
- package/dist/src/pace.js +111 -0
- package/dist/src/pace.js.map +1 -0
- package/dist/src/pacing.d.ts +63 -0
- package/dist/src/pacing.d.ts.map +1 -0
- package/dist/src/pacing.js +198 -0
- package/dist/src/pacing.js.map +1 -0
- package/dist/src/policy.d.ts +57 -1
- package/dist/src/policy.d.ts.map +1 -1
- package/dist/src/policy.js +67 -4
- package/dist/src/policy.js.map +1 -1
- package/dist/src/profile.d.ts +35 -8
- package/dist/src/profile.d.ts.map +1 -1
- package/dist/src/profile.js +57 -25
- package/dist/src/profile.js.map +1 -1
- package/dist/src/profileError.d.ts +10 -0
- package/dist/src/profileError.d.ts.map +1 -0
- package/dist/src/profileError.js +17 -0
- package/dist/src/profileError.js.map +1 -0
- package/dist/src/retention.d.ts +9 -0
- package/dist/src/retention.d.ts.map +1 -1
- package/dist/src/retention.js +10 -1
- package/dist/src/retention.js.map +1 -1
- package/dist/src/signalCounts.d.ts +37 -0
- package/dist/src/signalCounts.d.ts.map +1 -0
- package/dist/src/signalCounts.js +117 -0
- package/dist/src/signalCounts.js.map +1 -0
- package/dist/src/signalInert.d.ts +10 -0
- package/dist/src/signalInert.d.ts.map +1 -0
- package/dist/src/signalInert.js +28 -0
- package/dist/src/signalInert.js.map +1 -0
- package/dist/src/signalService.d.ts +101 -0
- package/dist/src/signalService.d.ts.map +1 -0
- package/dist/src/signalService.js +383 -0
- package/dist/src/signalService.js.map +1 -0
- package/dist/src/signals.d.ts +186 -0
- package/dist/src/signals.d.ts.map +1 -0
- package/dist/src/signals.js +361 -0
- package/dist/src/signals.js.map +1 -0
- package/dist/src/subjects.d.ts +2 -0
- package/dist/src/subjects.d.ts.map +1 -1
- package/dist/src/subjects.js +4 -0
- package/dist/src/subjects.js.map +1 -1
- package/dist/src/team.d.ts +27 -0
- package/dist/src/team.d.ts.map +1 -1
- package/dist/src/team.js +92 -4
- package/dist/src/team.js.map +1 -1
- package/dist/src/types.d.ts +56 -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/ai/case.ts +4 -4
- package/src/ai/hash.ts +5 -2
- package/src/ai/prompt.ts +16 -1
- package/src/ai/service.ts +8 -2
- package/src/ai/types.ts +19 -2
- package/src/ai/worker.ts +12 -4
- package/src/chat.ts +109 -8
- package/src/chatwarden.ts +184 -7
- package/src/documents.ts +5 -3
- package/src/freeze.ts +8 -0
- package/src/index.ts +41 -3
- package/src/ladder.ts +59 -1
- package/src/pace.ts +139 -0
- package/src/pacing.ts +242 -0
- package/src/policy.ts +107 -7
- package/src/profile.ts +83 -25
- package/src/profileError.ts +17 -0
- package/src/retention.ts +17 -1
- package/src/signalCounts.ts +133 -0
- package/src/signalInert.ts +31 -0
- package/src/signalService.ts +406 -0
- package/src/signals.ts +489 -0
- package/src/subjects.ts +5 -0
- package/src/team.ts +93 -5
- package/src/types.ts +65 -1
package/src/team.ts
CHANGED
|
@@ -38,6 +38,11 @@ const NEXT_PAGE = 200;
|
|
|
38
38
|
|
|
39
39
|
/** With `rankDownHabitual`, candidates are ranked this many at a time (see `next`). */
|
|
40
40
|
const RANK_SLICE = 20;
|
|
41
|
+
/** The most "handed to this moderator" markers `next` keeps (the oldest go). */
|
|
42
|
+
const SERVED_MAX = 1000;
|
|
43
|
+
|
|
44
|
+
/** With `signalBoost`, take-next looks at most this many people (oldest first) for an overdue or boosted case. @experimental */
|
|
45
|
+
export const SIGNAL_BOOST_SCAN_MAX = 200;
|
|
41
46
|
|
|
42
47
|
/** A claim as staff see it. Staff only: `by` is a staff actor. */
|
|
43
48
|
export interface CaseClaim {
|
|
@@ -192,8 +197,16 @@ export interface TeamDeps {
|
|
|
192
197
|
reasons?: () => readonly ReportReason[];
|
|
193
198
|
/** How each person's reports have turned out (see `cw.reports.reporterAccuracy`). Without it, `rankDownHabitual` ranks nobody down. */
|
|
194
199
|
accuracy?: (people: readonly SubjectId[]) => Map<SubjectId, ReporterAccuracy>;
|
|
200
|
+
/**
|
|
201
|
+
* Which of these people meet the queue signal feed (`cw.signals.boosted`), as canonical ids. Only asked when `next` is given
|
|
202
|
+
* `signalBoost`, once per page of candidates. Without it nobody is boosted. A throw reads as nobody boosted.
|
|
203
|
+
*/
|
|
204
|
+
boosted?: (people: readonly SubjectId[]) => Set<SubjectId>;
|
|
195
205
|
}
|
|
196
206
|
|
|
207
|
+
/** The key of a lapsed-claim marker: the moderator and the person, apart by a character neither can hold. */
|
|
208
|
+
const markerKey = (actor: string, person: SubjectId): string => `${actor}\u0000${person}`;
|
|
209
|
+
|
|
197
210
|
/** Claims, take next and viewing. The facade exposes it as `cw.cases`. */
|
|
198
211
|
export class CaseDesk {
|
|
199
212
|
private readonly store: Store;
|
|
@@ -201,7 +214,10 @@ export class CaseDesk {
|
|
|
201
214
|
private readonly clock: Clock;
|
|
202
215
|
private readonly reasons: () => readonly ReportReason[];
|
|
203
216
|
private readonly accuracy: NonNullable<TeamDeps['accuracy']>;
|
|
217
|
+
private readonly boosted: TeamDeps['boosted'];
|
|
204
218
|
private readonly presence: ViewingPresence;
|
|
219
|
+
/** `moderator, person` -> when the claim `next` handed that moderator ran out (this process only). See `lapsedByMe`. */
|
|
220
|
+
private readonly served = new Map<string, number>();
|
|
205
221
|
|
|
206
222
|
constructor(deps: TeamDeps) {
|
|
207
223
|
this.store = deps.store;
|
|
@@ -209,6 +225,7 @@ export class CaseDesk {
|
|
|
209
225
|
this.clock = deps.clock;
|
|
210
226
|
this.reasons = deps.reasons ?? (() => []);
|
|
211
227
|
this.accuracy = deps.accuracy ?? (() => new Map());
|
|
228
|
+
this.boosted = deps.boosted;
|
|
212
229
|
this.presence = new ViewingPresence(deps.clock);
|
|
213
230
|
}
|
|
214
231
|
|
|
@@ -243,6 +260,8 @@ export class CaseDesk {
|
|
|
243
260
|
}
|
|
244
261
|
const now = this.clock.now();
|
|
245
262
|
const res = this.store.claimCase(canonical, actor, now, now + CLAIM_TTL_MS, opts.takeOver === true ? 'takeover' : 'claim');
|
|
263
|
+
// The holder keeping the claim alive (or taking it again) is not one who let it lapse.
|
|
264
|
+
if (res.won) this.served.delete(markerKey(actor, canonical));
|
|
246
265
|
return res.won
|
|
247
266
|
? { ok: true, claim: claimOf(res.claim), tookOverFrom: res.from }
|
|
248
267
|
: { ok: false, error: 'claimed', claim: claimOf(res.claim) };
|
|
@@ -254,6 +273,8 @@ export class CaseDesk {
|
|
|
254
273
|
release(person: SubjectId, actor: string): boolean {
|
|
255
274
|
needActor(actor);
|
|
256
275
|
const canonical = this.subjects.canonical(needPerson(person));
|
|
276
|
+
// Released on purpose: not a claim that ran out (`lapsedByMe`).
|
|
277
|
+
this.served.delete(markerKey(actor, canonical));
|
|
257
278
|
return this.store.transaction(() => this.store.releaseClaim(canonical, actor, this.clock.now()));
|
|
258
279
|
}
|
|
259
280
|
|
|
@@ -268,6 +289,8 @@ export class CaseDesk {
|
|
|
268
289
|
const canonical = this.subjects.canonical(needPerson(person));
|
|
269
290
|
return this.store.transaction(() => {
|
|
270
291
|
if (this.store.listOpenReportsByPerson(this.subjects.aliasesOf(canonical), 1).length > 0) return false;
|
|
292
|
+
// Decided and done: the claim ending is not "let it lapse".
|
|
293
|
+
this.served.delete(markerKey(actor, canonical));
|
|
271
294
|
return this.store.releaseClaim(canonical, actor, this.clock.now());
|
|
272
295
|
});
|
|
273
296
|
}
|
|
@@ -283,8 +306,20 @@ export class CaseDesk {
|
|
|
283
306
|
* reporter, or no accuracy data, keeps the case normal). The first normal case in oldest-first order is claimed; ranked-down
|
|
284
307
|
* ones are remembered in order and, when the scan ends (end of the queue, or {@link RANK_DOWN_SCAN_MAX} reports read), the
|
|
285
308
|
* oldest of them is claimed. Nothing is skipped for good: a queue holding only habitual cases still serves them, oldest first.
|
|
309
|
+
*
|
|
310
|
+
* With `signalBoost` (default false: behaviour unchanged), the scan stays oldest first but a case is claimed only when it is OVERDUE (its
|
|
311
|
+
* oldest open report has waited {@link REPORTER_RANK_LAPSE_MS}) or BOOSTED (the person meets the queue signal feed, `TeamDeps.boosted`);
|
|
312
|
+
* the first such case wins. When the queue ends, or {@link SIGNAL_BOOST_SCAN_MAX} people have been looked at, with neither, the oldest
|
|
313
|
+
* free case is claimed as it would be without the filter. A boosted case is never ranked down as a habitual reporter's. Because the
|
|
314
|
+
* queue is oldest first an overdue case is always met before anything newer, so boosted cases cannot starve an old one past 24 hours.
|
|
315
|
+
* Nothing leaves the queue.
|
|
316
|
+
*
|
|
317
|
+
* Also with `signalBoost`: a case `next` handed this moderator whose claim then ran out (they did not decide it, and did not hold it)
|
|
318
|
+
* is served to them after every other free case for one claim window ({@link CLAIM_TTL_MS}) from the moment it ran out, so a boosted or
|
|
319
|
+
* overdue case does not come straight back to the person who let it lapse. Other moderators are not affected, it is still served when it
|
|
320
|
+
* is all that is left, and it is kept in this process only (a restart forgets it).
|
|
286
321
|
*/
|
|
287
|
-
next(actor: string, filter: { category?: ReportCategory; reason?: string | null; rankDownHabitual?: boolean } = {}): NextCase | null {
|
|
322
|
+
next(actor: string, filter: { category?: ReportCategory; reason?: string | null; rankDownHabitual?: boolean; signalBoost?: boolean } = {}): NextCase | null {
|
|
288
323
|
needActor(actor);
|
|
289
324
|
const category = filter.category;
|
|
290
325
|
if (category !== undefined && !REPORT_CATEGORIES.includes(category)) throw new RangeError('cases: unknown category');
|
|
@@ -294,9 +329,19 @@ export class CaseDesk {
|
|
|
294
329
|
const rank = filter.rankDownHabitual;
|
|
295
330
|
if (rank !== undefined && typeof rank !== 'boolean') throw new RangeError('cases: rankDownHabitual must be a boolean');
|
|
296
331
|
const rankDown = rank === true;
|
|
332
|
+
const boost = filter.signalBoost;
|
|
333
|
+
if (boost !== undefined && typeof boost !== 'boolean') throw new RangeError('cases: signalBoost must be a boolean');
|
|
334
|
+
const boostMode = boost === true;
|
|
297
335
|
const seen = new Set<SubjectId>();
|
|
298
336
|
// Ranked-down people in the order the scan met them (oldest first).
|
|
299
337
|
const deferred: SubjectId[] = [];
|
|
338
|
+
// With signalBoost: free people who are neither overdue nor boosted, in scan order, claimed when the scan ends (before the ranked-down).
|
|
339
|
+
const ordinary: SubjectId[] = [];
|
|
340
|
+
// With signalBoost: free people whose claim this moderator let lapse in the last claim window, claimed last of all.
|
|
341
|
+
const lapsed: SubjectId[] = [];
|
|
342
|
+
// With signalBoost: when each person's oldest open report was filed (the first one the scan met), and how many people were looked at.
|
|
343
|
+
const oldestAt = new Map<SubjectId, number>();
|
|
344
|
+
let scanned = 0;
|
|
300
345
|
let read = 0;
|
|
301
346
|
let after: { createdAt: number; id: string } | undefined;
|
|
302
347
|
for (;;) {
|
|
@@ -315,33 +360,53 @@ export class CaseDesk {
|
|
|
315
360
|
if (seen.has(person)) continue;
|
|
316
361
|
seen.add(person);
|
|
317
362
|
candidates.push(person);
|
|
363
|
+
if (boostMode) oldestAt.set(person, report.createdAt);
|
|
364
|
+
}
|
|
365
|
+
if (boostMode) {
|
|
366
|
+
// At most SIGNAL_BOOST_SCAN_MAX people in all, held ones included: they are looked at too.
|
|
367
|
+
candidates.length = Math.max(0, Math.min(candidates.length, SIGNAL_BOOST_SCAN_MAX - scanned));
|
|
368
|
+
scanned += candidates.length;
|
|
318
369
|
}
|
|
319
370
|
const held = new Set(this.store.loadClaims(candidates, this.clock.now()).map((c) => c.person));
|
|
320
371
|
const free = candidates.filter((p) => !held.has(p));
|
|
372
|
+
// One grouped read for the page.
|
|
373
|
+
const boosted = boostMode ? this.boostedAmong(free) : new Set<SubjectId>();
|
|
374
|
+
const now = this.clock.now();
|
|
321
375
|
// Ranked lazily, a slice at a time: the first ordinary case ends the scan, so "next, next, next" does not read the open
|
|
322
376
|
// reports of a whole page of candidates to claim the first one.
|
|
323
377
|
for (let i = 0; i < free.length; i += RANK_SLICE) {
|
|
324
378
|
const slice = free.slice(i, i + RANK_SLICE);
|
|
325
379
|
const down = rankDown ? this.rankedDown(slice) : new Set<SubjectId>();
|
|
326
380
|
for (const person of slice) {
|
|
327
|
-
if (
|
|
381
|
+
if (boostMode && this.lapsedByMe(actor, person, now)) {
|
|
382
|
+
lapsed.push(person);
|
|
383
|
+
continue;
|
|
384
|
+
}
|
|
385
|
+
const isBoosted = boosted.has(person);
|
|
386
|
+
if (down.has(person) && !isBoosted) {
|
|
328
387
|
deferred.push(person);
|
|
329
388
|
continue;
|
|
330
389
|
}
|
|
390
|
+
if (boostMode && !isBoosted && now - (oldestAt.get(person) ?? now) < REPORTER_RANK_LAPSE_MS) {
|
|
391
|
+
ordinary.push(person);
|
|
392
|
+
continue;
|
|
393
|
+
}
|
|
331
394
|
const won = this.tryClaim(person, actor);
|
|
332
395
|
if (won !== null) return won;
|
|
333
396
|
}
|
|
334
397
|
}
|
|
335
398
|
const last = page[page.length - 1];
|
|
336
399
|
if (page.length < NEXT_PAGE || last === undefined) break;
|
|
400
|
+
if (boostMode && scanned >= SIGNAL_BOOST_SCAN_MAX) break;
|
|
337
401
|
// Enough read to have looked for a normal case: serve the oldest ranked-down one rather than scan the whole queue.
|
|
338
402
|
if (rankDown && read >= RANK_DOWN_SCAN_MAX && deferred.length > 0) break;
|
|
339
403
|
after = { createdAt: last.createdAt, id: last.id };
|
|
340
404
|
}
|
|
341
|
-
|
|
405
|
+
const rest = [...ordinary, ...deferred, ...lapsed];
|
|
406
|
+
if (rest.length === 0) return null;
|
|
342
407
|
// 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(
|
|
344
|
-
for (const person of
|
|
408
|
+
const heldNow = new Set(this.store.loadClaims(rest, this.clock.now()).map((c) => c.person));
|
|
409
|
+
for (const person of rest) {
|
|
345
410
|
if (heldNow.has(person)) continue;
|
|
346
411
|
const won = this.tryClaim(person, actor);
|
|
347
412
|
if (won !== null) return won;
|
|
@@ -349,6 +414,25 @@ export class CaseDesk {
|
|
|
349
414
|
return null;
|
|
350
415
|
}
|
|
351
416
|
|
|
417
|
+
/** Did a claim `next` handed this moderator on this person run out within the last claim window? Forgets markers older than that. */
|
|
418
|
+
private lapsedByMe(actor: string, person: SubjectId, now: number): boolean {
|
|
419
|
+
const key = markerKey(actor, person);
|
|
420
|
+
const until = this.served.get(key);
|
|
421
|
+
if (until === undefined) return false;
|
|
422
|
+
if (now - until >= CLAIM_TTL_MS) this.served.delete(key);
|
|
423
|
+
return until <= now && now - until < CLAIM_TTL_MS;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/** Who of these people the queue signal feed boosts (canonical ids). Nobody without the dependency, or when it throws. */
|
|
427
|
+
private boostedAmong(people: readonly SubjectId[]): Set<SubjectId> {
|
|
428
|
+
if (this.boosted === undefined || people.length === 0) return new Set();
|
|
429
|
+
try {
|
|
430
|
+
return this.boosted(people);
|
|
431
|
+
} catch {
|
|
432
|
+
return new Set();
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
|
|
352
436
|
/** 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
437
|
private tryClaim(person: SubjectId, actor: string): NextCase | null {
|
|
354
438
|
return retryBusy(() =>
|
|
@@ -356,6 +440,10 @@ export class CaseDesk {
|
|
|
356
440
|
const now = this.clock.now();
|
|
357
441
|
const res = this.store.claimCase(person, actor, now, now + CLAIM_TTL_MS, 'free');
|
|
358
442
|
if (!res.won) return null;
|
|
443
|
+
const key = markerKey(actor, person);
|
|
444
|
+
this.served.delete(key);
|
|
445
|
+
this.served.set(key, res.claim.until);
|
|
446
|
+
if (this.served.size > SERVED_MAX) this.served.delete(this.served.keys().next().value!);
|
|
359
447
|
const newest = this.store.listOpenReportsByPerson(this.subjects.aliasesOf(person), 1)[0];
|
|
360
448
|
if (newest === undefined) {
|
|
361
449
|
// The case closed under us: do not leave a claim on nothing.
|
package/src/types.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// Core types for @chatwarden/core. Organized by section; later tasks append
|
|
2
2
|
// their own sections below.
|
|
3
3
|
|
|
4
|
-
import type { AIExample, AIRead } from './ai/types.js';
|
|
4
|
+
import type { AIExample, AIRead, AISignal } from './ai/types.js';
|
|
5
5
|
import type { AuditListQuery, AuditRow } from './audit.js';
|
|
6
6
|
import type { PolicyLayer } from './profile.js';
|
|
7
7
|
import type { RuleRef } from './rules.js';
|
|
@@ -270,6 +270,11 @@ export interface AiReadDone extends AiCallUsage {
|
|
|
270
270
|
* hash, so the read records which ones it saw. Ids only; none by default.
|
|
271
271
|
*/
|
|
272
272
|
exampleIds?: readonly string[];
|
|
273
|
+
/**
|
|
274
|
+
* The signal counts about the reported person the prompt carried (`feeds.ai`): exactly what was sent, label, polarity, distinct and window
|
|
275
|
+
* only. Stored with the read (`signals_json`); none (or an empty list) is stored as null.
|
|
276
|
+
*/
|
|
277
|
+
signals?: readonly AISignal[];
|
|
273
278
|
}
|
|
274
279
|
|
|
275
280
|
/**
|
|
@@ -293,6 +298,8 @@ export interface AiReadRow {
|
|
|
293
298
|
read: AIRead | null;
|
|
294
299
|
/** The ids of the casebook examples this read saw (empty when none, and for every row but an `ok` one). */
|
|
295
300
|
exampleIds: readonly string[];
|
|
301
|
+
/** The signal counts this read was shown (see {@link AiReadDone.signals}); null when none were sent, for every row but an `ok` one, and for a read made before signals existed. */
|
|
302
|
+
signals: readonly AISignal[] | null;
|
|
296
303
|
inputTokens: number | null;
|
|
297
304
|
outputTokens: number | null;
|
|
298
305
|
cacheReadTokens: number | null;
|
|
@@ -312,6 +319,43 @@ export interface AiReadRow {
|
|
|
312
319
|
retaken: boolean;
|
|
313
320
|
}
|
|
314
321
|
|
|
322
|
+
/**
|
|
323
|
+
* One signal a game recorded about a player (flood control and signals, design 5.8). Staff-side data: it holds ids and numbers only, no
|
|
324
|
+
* text, handle or seat. `sourceKey` is `b:<canonical by>`, `r:<roomId>` or `d:<UTC day>`; `(kind, subject, sourceKey, capBucket)` is unique,
|
|
325
|
+
* which is the per-source cap.
|
|
326
|
+
* @experimental
|
|
327
|
+
*/
|
|
328
|
+
export interface SignalRow {
|
|
329
|
+
id: string;
|
|
330
|
+
kind: string;
|
|
331
|
+
subject: SubjectId;
|
|
332
|
+
/** 'b:<canonical by>' | 'r:<roomId>' | 'd:<UTC day>' */
|
|
333
|
+
sourceKey: string;
|
|
334
|
+
bySubject: SubjectId | null;
|
|
335
|
+
roomId: string | null;
|
|
336
|
+
at: number;
|
|
337
|
+
/** The effective weight, stored at record time (0 or more). */
|
|
338
|
+
weight: number;
|
|
339
|
+
/** floor(at / perByWindowMs): the cap bucket. */
|
|
340
|
+
capBucket: number;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* What `listSignalSources` answers: one row per source of a kind about a subject. Rows are bounded by distinct sources, not by volume.
|
|
345
|
+
* @experimental
|
|
346
|
+
*/
|
|
347
|
+
export interface SignalSourceRow {
|
|
348
|
+
subject: SubjectId;
|
|
349
|
+
kind: string;
|
|
350
|
+
sourceKey: string;
|
|
351
|
+
/** The source's `by` (the smallest, when rows of one source name more than one); null for a room or day source. */
|
|
352
|
+
bySubject: SubjectId | null;
|
|
353
|
+
/** The highest weight among the source's rows in range. */
|
|
354
|
+
weight: number;
|
|
355
|
+
firstAt: number;
|
|
356
|
+
lastAt: number;
|
|
357
|
+
}
|
|
358
|
+
|
|
315
359
|
/**
|
|
316
360
|
* The answer to a reserve: this caller owns the read now (`id`), or a row already exists for that report and input. `lease` is the
|
|
317
361
|
* caller's fence token (the row's `attempts` after this reserve): `completeAiRead` and `failAiRead` must be given it, and do nothing
|
|
@@ -1149,6 +1193,26 @@ export interface Store {
|
|
|
1149
1193
|
*/
|
|
1150
1194
|
purgeAi?(readsBefore: number, outcomesBefore: number, examplesBefore: number): { reads: number; outcomes: number };
|
|
1151
1195
|
|
|
1196
|
+
// Signals (flood control and signals, design 5.8). OPTIONAL: a store without them cannot keep signals, and `createChatwarden` refuses a
|
|
1197
|
+
// profile that declares kinds or feeds with one. SYNCHRONOUS on purpose (like claims); they run inside `transaction`. They do not move
|
|
1198
|
+
// the change token.
|
|
1199
|
+
|
|
1200
|
+
/**
|
|
1201
|
+
* OPTIONAL. Insert one signal as ONE atomic statement: false, and nothing written, when a row with the same `(kind, subject, sourceKey,
|
|
1202
|
+
* capBucket)` exists (the per-source cap; of two callers, two processes on one database included, exactly one writes) or the id is
|
|
1203
|
+
* taken. True when a row was written.
|
|
1204
|
+
*/
|
|
1205
|
+
insertSignal?(row: SignalRow): boolean;
|
|
1206
|
+
|
|
1207
|
+
/**
|
|
1208
|
+
* OPTIONAL. One row per `(subject, kind, sourceKey)` that has a row at or after `since`, for these subjects (a person's canonical id and
|
|
1209
|
+
* aliases): the highest weight, the earliest and the latest `at` among the rows in range. No subjects: `[]`. Returns copies.
|
|
1210
|
+
*/
|
|
1211
|
+
listSignalSources?(subjects: readonly SubjectId[], since: number): SignalSourceRow[];
|
|
1212
|
+
|
|
1213
|
+
/** OPTIONAL. Delete rows with `at < before` (a row exactly on the line is kept); returns how many. */
|
|
1214
|
+
purgeSignals?(before: number): number;
|
|
1215
|
+
|
|
1152
1216
|
// Staff audit trail. SYNCHRONOUS on purpose (like sanctions). The trail also holds the rows `closeGap` and the term
|
|
1153
1217
|
// editor write; none of these methods ever returns the json columns those carry (they may hold term text).
|
|
1154
1218
|
|