@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.
Files changed (126) hide show
  1. package/README.md +124 -4
  2. package/dist/src/ai/case.d.ts +3 -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 +6 -2
  11. package/dist/src/ai/prompt.d.ts.map +1 -1
  12. package/dist/src/ai/prompt.js +11 -0
  13. package/dist/src/ai/prompt.js.map +1 -1
  14. package/dist/src/ai/service.d.ts +5 -1
  15. package/dist/src/ai/service.d.ts.map +1 -1
  16. package/dist/src/ai/service.js +2 -0
  17. package/dist/src/ai/service.js.map +1 -1
  18. package/dist/src/ai/types.d.ts +18 -2
  19. package/dist/src/ai/types.d.ts.map +1 -1
  20. package/dist/src/ai/types.js +2 -2
  21. package/dist/src/ai/types.js.map +1 -1
  22. package/dist/src/ai/worker.d.ts +3 -1
  23. package/dist/src/ai/worker.d.ts.map +1 -1
  24. package/dist/src/ai/worker.js +10 -3
  25. package/dist/src/ai/worker.js.map +1 -1
  26. package/dist/src/chat.d.ts +39 -1
  27. package/dist/src/chat.d.ts.map +1 -1
  28. package/dist/src/chat.js +85 -6
  29. package/dist/src/chat.js.map +1 -1
  30. package/dist/src/chatwarden.d.ts +68 -1
  31. package/dist/src/chatwarden.d.ts.map +1 -1
  32. package/dist/src/chatwarden.js +119 -5
  33. package/dist/src/chatwarden.js.map +1 -1
  34. package/dist/src/documents.d.ts +1 -1
  35. package/dist/src/documents.d.ts.map +1 -1
  36. package/dist/src/documents.js +3 -1
  37. package/dist/src/documents.js.map +1 -1
  38. package/dist/src/freeze.d.ts +3 -0
  39. package/dist/src/freeze.d.ts.map +1 -0
  40. package/dist/src/freeze.js +10 -0
  41. package/dist/src/freeze.js.map +1 -0
  42. package/dist/src/index.d.ts +13 -6
  43. package/dist/src/index.d.ts.map +1 -1
  44. package/dist/src/index.js +7 -2
  45. package/dist/src/index.js.map +1 -1
  46. package/dist/src/ladder.d.ts +28 -0
  47. package/dist/src/ladder.d.ts.map +1 -1
  48. package/dist/src/ladder.js +37 -1
  49. package/dist/src/ladder.js.map +1 -1
  50. package/dist/src/pace.d.ts +66 -0
  51. package/dist/src/pace.d.ts.map +1 -0
  52. package/dist/src/pace.js +111 -0
  53. package/dist/src/pace.js.map +1 -0
  54. package/dist/src/pacing.d.ts +63 -0
  55. package/dist/src/pacing.d.ts.map +1 -0
  56. package/dist/src/pacing.js +198 -0
  57. package/dist/src/pacing.js.map +1 -0
  58. package/dist/src/policy.d.ts +57 -1
  59. package/dist/src/policy.d.ts.map +1 -1
  60. package/dist/src/policy.js +67 -4
  61. package/dist/src/policy.js.map +1 -1
  62. package/dist/src/profile.d.ts +35 -8
  63. package/dist/src/profile.d.ts.map +1 -1
  64. package/dist/src/profile.js +57 -25
  65. package/dist/src/profile.js.map +1 -1
  66. package/dist/src/profileError.d.ts +10 -0
  67. package/dist/src/profileError.d.ts.map +1 -0
  68. package/dist/src/profileError.js +17 -0
  69. package/dist/src/profileError.js.map +1 -0
  70. package/dist/src/retention.d.ts +9 -0
  71. package/dist/src/retention.d.ts.map +1 -1
  72. package/dist/src/retention.js +10 -1
  73. package/dist/src/retention.js.map +1 -1
  74. package/dist/src/signalCounts.d.ts +37 -0
  75. package/dist/src/signalCounts.d.ts.map +1 -0
  76. package/dist/src/signalCounts.js +117 -0
  77. package/dist/src/signalCounts.js.map +1 -0
  78. package/dist/src/signalInert.d.ts +10 -0
  79. package/dist/src/signalInert.d.ts.map +1 -0
  80. package/dist/src/signalInert.js +28 -0
  81. package/dist/src/signalInert.js.map +1 -0
  82. package/dist/src/signalService.d.ts +101 -0
  83. package/dist/src/signalService.d.ts.map +1 -0
  84. package/dist/src/signalService.js +383 -0
  85. package/dist/src/signalService.js.map +1 -0
  86. package/dist/src/signals.d.ts +186 -0
  87. package/dist/src/signals.d.ts.map +1 -0
  88. package/dist/src/signals.js +361 -0
  89. package/dist/src/signals.js.map +1 -0
  90. package/dist/src/subjects.d.ts +2 -0
  91. package/dist/src/subjects.d.ts.map +1 -1
  92. package/dist/src/subjects.js +4 -0
  93. package/dist/src/subjects.js.map +1 -1
  94. package/dist/src/team.d.ts +27 -0
  95. package/dist/src/team.d.ts.map +1 -1
  96. package/dist/src/team.js +92 -4
  97. package/dist/src/team.js.map +1 -1
  98. package/dist/src/types.d.ts +56 -1
  99. package/dist/src/types.d.ts.map +1 -1
  100. package/dist/src/types.js.map +1 -1
  101. package/package.json +2 -2
  102. package/src/ai/case.ts +4 -4
  103. package/src/ai/hash.ts +5 -2
  104. package/src/ai/prompt.ts +16 -1
  105. package/src/ai/service.ts +8 -2
  106. package/src/ai/types.ts +19 -2
  107. package/src/ai/worker.ts +12 -4
  108. package/src/chat.ts +109 -8
  109. package/src/chatwarden.ts +184 -7
  110. package/src/documents.ts +5 -3
  111. package/src/freeze.ts +8 -0
  112. package/src/index.ts +41 -3
  113. package/src/ladder.ts +59 -1
  114. package/src/pace.ts +139 -0
  115. package/src/pacing.ts +242 -0
  116. package/src/policy.ts +107 -7
  117. package/src/profile.ts +83 -25
  118. package/src/profileError.ts +17 -0
  119. package/src/retention.ts +17 -1
  120. package/src/signalCounts.ts +133 -0
  121. package/src/signalInert.ts +31 -0
  122. package/src/signalService.ts +406 -0
  123. package/src/signals.ts +489 -0
  124. package/src/subjects.ts +5 -0
  125. package/src/team.ts +93 -5
  126. 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 (down.has(person)) {
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
- if (deferred.length === 0) return null;
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(deferred, this.clock.now()).map((c) => c.person));
344
- for (const person of deferred) {
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