@chatwarden/core 0.1.6 → 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 +173 -3
- package/dist/src/ai/agreement.d.ts +46 -0
- package/dist/src/ai/agreement.d.ts.map +1 -0
- package/dist/src/ai/agreement.js +71 -0
- package/dist/src/ai/agreement.js.map +1 -0
- package/dist/src/ai/breaker.d.ts +31 -0
- package/dist/src/ai/breaker.d.ts.map +1 -0
- package/dist/src/ai/breaker.js +62 -0
- package/dist/src/ai/breaker.js.map +1 -0
- package/dist/src/ai/budget.d.ts +26 -0
- package/dist/src/ai/budget.d.ts.map +1 -0
- package/dist/src/ai/budget.js +57 -0
- package/dist/src/ai/budget.js.map +1 -0
- package/dist/src/ai/case.d.ts +37 -0
- package/dist/src/ai/case.d.ts.map +1 -0
- package/dist/src/ai/case.js +30 -0
- package/dist/src/ai/case.js.map +1 -0
- package/dist/src/ai/casebook.d.ts +59 -0
- package/dist/src/ai/casebook.d.ts.map +1 -0
- package/dist/src/ai/casebook.js +47 -0
- package/dist/src/ai/casebook.js.map +1 -0
- package/dist/src/ai/ceilings.d.ts +42 -0
- package/dist/src/ai/ceilings.d.ts.map +1 -0
- package/dist/src/ai/ceilings.js +59 -0
- package/dist/src/ai/ceilings.js.map +1 -0
- package/dist/src/ai/fake.d.ts +41 -0
- package/dist/src/ai/fake.d.ts.map +1 -0
- package/dist/src/ai/fake.js +75 -0
- package/dist/src/ai/fake.js.map +1 -0
- package/dist/src/ai/hash.d.ts +15 -0
- package/dist/src/ai/hash.d.ts.map +1 -0
- package/dist/src/ai/hash.js +22 -0
- package/dist/src/ai/hash.js.map +1 -0
- package/dist/src/ai/inert.d.ts +5 -0
- package/dist/src/ai/inert.d.ts.map +1 -0
- package/dist/src/ai/inert.js +22 -0
- package/dist/src/ai/inert.js.map +1 -0
- package/dist/src/ai/injection.d.ts +8 -0
- package/dist/src/ai/injection.d.ts.map +1 -0
- package/dist/src/ai/injection.js +30 -0
- package/dist/src/ai/injection.js.map +1 -0
- package/dist/src/ai/lines.d.ts +64 -0
- package/dist/src/ai/lines.d.ts.map +1 -0
- package/dist/src/ai/lines.js +172 -0
- package/dist/src/ai/lines.js.map +1 -0
- package/dist/src/ai/prompt.d.ts +48 -0
- package/dist/src/ai/prompt.d.ts.map +1 -0
- package/dist/src/ai/prompt.js +196 -0
- package/dist/src/ai/prompt.js.map +1 -0
- package/dist/src/ai/redact.d.ts +29 -0
- package/dist/src/ai/redact.d.ts.map +1 -0
- package/dist/src/ai/redact.js +160 -0
- package/dist/src/ai/redact.js.map +1 -0
- package/dist/src/ai/schema.d.ts +6 -0
- package/dist/src/ai/schema.d.ts.map +1 -0
- package/dist/src/ai/schema.js +50 -0
- package/dist/src/ai/schema.js.map +1 -0
- package/dist/src/ai/service.d.ts +332 -0
- package/dist/src/ai/service.d.ts.map +1 -0
- package/dist/src/ai/service.js +751 -0
- package/dist/src/ai/service.js.map +1 -0
- package/dist/src/ai/types.d.ts +196 -0
- package/dist/src/ai/types.d.ts.map +1 -0
- package/dist/src/ai/types.js +23 -0
- package/dist/src/ai/types.js.map +1 -0
- package/dist/src/ai/validate.d.ts +30 -0
- package/dist/src/ai/validate.d.ts.map +1 -0
- package/dist/src/ai/validate.js +160 -0
- package/dist/src/ai/validate.js.map +1 -0
- package/dist/src/ai/worker.d.ts +76 -0
- package/dist/src/ai/worker.d.ts.map +1 -0
- package/dist/src/ai/worker.js +293 -0
- package/dist/src/ai/worker.js.map +1 -0
- package/dist/src/audit.d.ts +12 -3
- package/dist/src/audit.d.ts.map +1 -1
- package/dist/src/audit.js +30 -4
- package/dist/src/audit.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 +84 -1
- package/dist/src/chatwarden.d.ts.map +1 -1
- package/dist/src/chatwarden.js +168 -6
- package/dist/src/chatwarden.js.map +1 -1
- package/dist/src/decide.d.ts +36 -1
- package/dist/src/decide.d.ts.map +1 -1
- package/dist/src/decide.js +62 -2
- package/dist/src/decide.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 +6 -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 +37 -8
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +23 -3
- 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 +64 -8
- package/dist/src/profile.d.ts.map +1 -1
- package/dist/src/profile.js +98 -27
- 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 +28 -0
- package/dist/src/retention.d.ts.map +1 -1
- package/dist/src/retention.js +42 -10
- 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 +324 -2
- 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/agreement.ts +106 -0
- package/src/ai/breaker.ts +73 -0
- package/src/ai/budget.ts +65 -0
- package/src/ai/case.ts +74 -0
- package/src/ai/casebook.ts +75 -0
- package/src/ai/ceilings.ts +68 -0
- package/src/ai/fake.ts +105 -0
- package/src/ai/hash.ts +23 -0
- package/src/ai/inert.ts +26 -0
- package/src/ai/injection.ts +32 -0
- package/src/ai/lines.ts +216 -0
- package/src/ai/prompt.ts +223 -0
- package/src/ai/redact.ts +174 -0
- package/src/ai/schema.ts +51 -0
- package/src/ai/service.ts +961 -0
- package/src/ai/types.ts +182 -0
- package/src/ai/validate.ts +173 -0
- package/src/ai/worker.ts +372 -0
- package/src/audit.ts +31 -5
- package/src/chat.ts +109 -8
- package/src/chatwarden.ts +248 -8
- package/src/decide.ts +97 -4
- package/src/documents.ts +7 -2
- package/src/freeze.ts +8 -0
- package/src/index.ts +91 -2
- 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 +149 -27
- package/src/profileError.ts +17 -0
- package/src/retention.ts +63 -10
- 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 +358 -2
package/src/policy.ts
CHANGED
|
@@ -7,6 +7,10 @@ import { playerReporting } from './reporting.js';
|
|
|
7
7
|
import type { PlayerReporting } from './reporting.js';
|
|
8
8
|
import type { RuleRef } from './rules.js';
|
|
9
9
|
import { errorClass, safeWarn } from './log.js';
|
|
10
|
+
import { RETENTION_DEFAULTS } from './retention.js';
|
|
11
|
+
import { checkSignalFeeds, pruneSignalFeeds, SIGNAL_FEED_NAMES } from './signals.js';
|
|
12
|
+
import type { SignalDropReason } from './signals.js';
|
|
13
|
+
import { RATE_LIMIT, RATE_WINDOW_MS } from './chat.js';
|
|
10
14
|
import { retryBusy } from './team.js';
|
|
11
15
|
import { CONDUCT_LEVELS } from './types.js';
|
|
12
16
|
import type { Clock, ConductLevel, Logger, Store } from './types.js';
|
|
@@ -22,13 +26,38 @@ import type { Clock, ConductLevel, Logger, Store } from './types.js';
|
|
|
22
26
|
/** How often a read may look at the store for a newer version: 10 seconds. */
|
|
23
27
|
export const POLICY_REFRESH_MS = 10_000;
|
|
24
28
|
|
|
29
|
+
/**
|
|
30
|
+
* A stored signal feed that was dropped when the layer was read: the feed (`record`, `queue`, `ladder`, `ai`, or `unknown` for a name the kit
|
|
31
|
+
* does not have) and why. A code only: never a kind id, a rule id, a label or a number from the stored layer.
|
|
32
|
+
* @experimental
|
|
33
|
+
*/
|
|
34
|
+
export interface PolicyDropped {
|
|
35
|
+
feed: string;
|
|
36
|
+
reason: SignalDropReason;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* The kit's own numbers the settings screens need, read only: they come from `createChatwarden` (`limits.chatRate`, `retention.signalsMs`), are
|
|
41
|
+
* never part of the stored layer, and a save cannot change them.
|
|
42
|
+
* @experimental
|
|
43
|
+
*/
|
|
44
|
+
export interface PolicyLimits {
|
|
45
|
+
/** The chat rate the kit enforces per room and seat: at most `count` lines in any `windowMs` (default 3 per 5 000 ms). Slow mode and burst sit beside it. */
|
|
46
|
+
chatRate: { count: number; windowMs: number };
|
|
47
|
+
/** How long signal rows are kept, ms: the longest window a signal feed may look back (default 90 days, never less than 14). */
|
|
48
|
+
signalsMs: number;
|
|
49
|
+
}
|
|
50
|
+
|
|
25
51
|
/** What {@link PolicyService.get} answers. */
|
|
26
52
|
export interface PolicyState {
|
|
27
53
|
/** The profile in force: base, then the stored layer. Deep-frozen. */
|
|
28
54
|
effective: ResolvedProfile;
|
|
29
55
|
/** The profile from code (preset and overrides), without the stored layer. Deep-frozen. */
|
|
30
56
|
base: ResolvedProfile;
|
|
31
|
-
/**
|
|
57
|
+
/**
|
|
58
|
+
* The layer in force, as last read (`{}` when none), deep-frozen: the stored layer with any signal feed that could no longer be used
|
|
59
|
+
* taken out (see `dropped`). Send it back to `save` and the save is accepted, and repairs the stored row.
|
|
60
|
+
*/
|
|
32
61
|
layer: PolicyLayer;
|
|
33
62
|
/** The stored layer's version; 0 when nothing was ever saved. Pass it back to `save`. */
|
|
34
63
|
version: number;
|
|
@@ -41,6 +70,19 @@ export interface PolicyState {
|
|
|
41
70
|
* valid (a newer kit's field, a hand edit). Either way a save or a full `reset()` repairs it.
|
|
42
71
|
*/
|
|
43
72
|
layerError?: { path: string; kind: 'unreadable' | 'invalid' };
|
|
73
|
+
/**
|
|
74
|
+
* Present only when the stored layer held signal feeds that could no longer be used (the code stopped declaring their kind, or a
|
|
75
|
+
* window is longer than the retention now allows) and were left out of `layer` and of what is in force. One entry per feed, with the
|
|
76
|
+
* reason of the first thing lost from it. The stored row itself is rewritten by the next save.
|
|
77
|
+
* @experimental
|
|
78
|
+
*/
|
|
79
|
+
dropped?: readonly PolicyDropped[];
|
|
80
|
+
/**
|
|
81
|
+
* The chat rate limit actually in force and the signals retention window, so a settings screen can say what slow mode sits beside and how
|
|
82
|
+
* far back a feed may look. Read only, deep-frozen.
|
|
83
|
+
* @experimental
|
|
84
|
+
*/
|
|
85
|
+
limits: PolicyLimits;
|
|
44
86
|
}
|
|
45
87
|
|
|
46
88
|
/** What {@link PolicyService.save} and {@link PolicyService.reset} answer. */
|
|
@@ -91,11 +133,18 @@ export class PolicyService {
|
|
|
91
133
|
private readonly clock: Clock;
|
|
92
134
|
private readonly logger: Logger | undefined;
|
|
93
135
|
private readonly base: ResolvedProfile;
|
|
94
|
-
private state: { effective: ResolvedProfile; layer: PolicyLayer; version: number; layerError?: PolicyState['layerError'] };
|
|
136
|
+
private state: { effective: ResolvedProfile; layer: PolicyLayer; version: number; layerError?: PolicyState['layerError']; dropped?: readonly PolicyDropped[] };
|
|
95
137
|
/** When the store was last looked at (epoch ms), or null before the first read. */
|
|
96
138
|
private lastCheck: number | null = null;
|
|
97
139
|
|
|
98
|
-
|
|
140
|
+
/** How long signal rows are kept, ms: a feed window longer than this could never be met. */
|
|
141
|
+
private readonly signalsMs: () => number;
|
|
142
|
+
/** The chat rate in force (`limits.chatRate`), for `get().limits`. */
|
|
143
|
+
private readonly chatRate: { count: number; windowMs: number };
|
|
144
|
+
|
|
145
|
+
constructor(deps: { store: Store; clock: Clock; logger: Logger | undefined; base: ResolvedProfile; signalsMs?: () => number; chatRate?: { count: number; windowMs: number } }) {
|
|
146
|
+
this.signalsMs = deps.signalsMs ?? (() => RETENTION_DEFAULTS.signalsMs);
|
|
147
|
+
this.chatRate = Object.freeze({ count: deps.chatRate?.count ?? RATE_LIMIT, windowMs: deps.chatRate?.windowMs ?? RATE_WINDOW_MS });
|
|
99
148
|
this.store = deps.store;
|
|
100
149
|
this.clock = deps.clock;
|
|
101
150
|
this.logger = deps.logger;
|
|
@@ -121,7 +170,10 @@ export class PolicyService {
|
|
|
121
170
|
const raw: unknown = stored === null ? {} : stored.layer;
|
|
122
171
|
const layer = frozenCopy(raw as PolicyLayer);
|
|
123
172
|
try {
|
|
124
|
-
|
|
173
|
+
// What is read and shown is the layer in force: the stale feeds are out of it, so a save that sends it back is never refused for them.
|
|
174
|
+
const { layer: inForce, dropped } = this.withoutStaleFeeds(layer);
|
|
175
|
+
const shown = dropped.length === 0 ? layer : frozenCopy(inForce);
|
|
176
|
+
this.state = { effective: applyPolicyLayer(this.base, shown), layer: shown, version, ...(dropped.length === 0 ? {} : { dropped: Object.freeze(dropped.map((d) => Object.freeze(d))) }) };
|
|
125
177
|
} catch (err) {
|
|
126
178
|
if (!(err instanceof ProfileError)) throw err;
|
|
127
179
|
// What `get()` shows is always an object: an unreadable layer reads as empty, with the error beside it.
|
|
@@ -133,6 +185,36 @@ export class PolicyService {
|
|
|
133
185
|
}
|
|
134
186
|
}
|
|
135
187
|
|
|
188
|
+
/**
|
|
189
|
+
* The stored layer with any signal feed that can no longer be used taken out (it names a kind the code stopped declaring, or a window
|
|
190
|
+
* longer than the retention now allows), and what was taken out. Without this one stale feed would make the whole layer unusable and
|
|
191
|
+
* silently drop the owner's other edits too. Logged by feed name only. Anything else wrong with the layer is left for
|
|
192
|
+
* `applyPolicyLayer` to refuse; a layer with nothing to drop comes back as it is.
|
|
193
|
+
*/
|
|
194
|
+
private withoutStaleFeeds(layer: PolicyLayer): { layer: PolicyLayer; dropped: PolicyDropped[] } {
|
|
195
|
+
const dropped: PolicyDropped[] = [];
|
|
196
|
+
const signals: unknown = typeof layer === 'object' && layer !== null && !Array.isArray(layer) ? (layer as { signals?: unknown }).signals : undefined;
|
|
197
|
+
const feeds: unknown = typeof signals === 'object' && signals !== null && !Array.isArray(signals) ? (signals as { feeds?: unknown }).feeds : undefined;
|
|
198
|
+
if (typeof feeds !== 'object' || feeds === null || Array.isArray(feeds)) return { layer, dropped };
|
|
199
|
+
const pruned = pruneSignalFeeds(feeds, this.base.signals.kinds, {
|
|
200
|
+
signalsMs: this.signalsMs(),
|
|
201
|
+
onDrop: (name, reason) => {
|
|
202
|
+
const feed = SIGNAL_FEED_NAMES.includes(name) ? name : 'unknown';
|
|
203
|
+
safeWarn(this.logger, 'chatwarden.signal_feed_dropped', { feed });
|
|
204
|
+
dropped.push({ feed, reason });
|
|
205
|
+
},
|
|
206
|
+
});
|
|
207
|
+
if (dropped.length === 0) return { layer, dropped };
|
|
208
|
+
// Nothing usable is left of the section: it is not shown at all, so the code's own feeds are what is in force (a section with a `feeds`
|
|
209
|
+
// key replaces them wholesale, and an empty one would keep them off for a reason nobody can see).
|
|
210
|
+
const { feeds: _gone, ...others } = signals as { feeds?: unknown };
|
|
211
|
+
void _gone;
|
|
212
|
+
const rest = { ...layer } as Record<string, unknown>;
|
|
213
|
+
if (Object.keys(pruned).length === 0 && Object.keys(others).length === 0) delete rest['signals'];
|
|
214
|
+
else rest['signals'] = Object.keys(pruned).length === 0 ? others : { ...others, feeds: pruned };
|
|
215
|
+
return { layer: rest as PolicyLayer, dropped };
|
|
216
|
+
}
|
|
217
|
+
|
|
136
218
|
/** Look at the store now and adopt a strictly newer version (an older one, say a restored backup, never regresses what is in force). A store failure throws. */
|
|
137
219
|
private reload(): void {
|
|
138
220
|
const stored = this.store.loadPolicyLayer?.() ?? null;
|
|
@@ -166,8 +248,17 @@ export class PolicyService {
|
|
|
166
248
|
|
|
167
249
|
get(): PolicyState {
|
|
168
250
|
this.maybeRefresh();
|
|
169
|
-
const { effective, layer, version, layerError } = this.state;
|
|
170
|
-
return {
|
|
251
|
+
const { effective, layer, version, layerError, dropped } = this.state;
|
|
252
|
+
return {
|
|
253
|
+
effective,
|
|
254
|
+
base: this.base,
|
|
255
|
+
layer,
|
|
256
|
+
version,
|
|
257
|
+
canSave: this.supported,
|
|
258
|
+
...(layerError === undefined ? {} : { layerError: { ...layerError } }),
|
|
259
|
+
...(dropped === undefined ? {} : { dropped }),
|
|
260
|
+
limits: Object.freeze({ chatRate: this.chatRate, signalsMs: this.signalsMs() }),
|
|
261
|
+
};
|
|
171
262
|
}
|
|
172
263
|
|
|
173
264
|
/** Look at the store now, whatever the interval. A store failure throws. */
|
|
@@ -191,6 +282,11 @@ export class PolicyService {
|
|
|
191
282
|
return { ok: false, error: 'conflict' };
|
|
192
283
|
}
|
|
193
284
|
const changed = changedSections(before, layer);
|
|
285
|
+
// The layer this save was judged against had feeds taken out of it (`dropped`): the stored row loses them now, so `signals` changed.
|
|
286
|
+
if (this.state.version === expected && this.state.dropped !== undefined && !changed.includes('signals')) {
|
|
287
|
+
changed.push('signals');
|
|
288
|
+
changed.sort((a, b) => POLICY_SECTIONS.indexOf(a) - POLICY_SECTIONS.indexOf(b));
|
|
289
|
+
}
|
|
194
290
|
this.lastCheck = this.clock.now();
|
|
195
291
|
this.adopt({ layer, version: next });
|
|
196
292
|
return { ok: true, version: next, changed };
|
|
@@ -212,7 +308,9 @@ export class PolicyService {
|
|
|
212
308
|
return { ok: false, error: 'invalid', path: 'reason' };
|
|
213
309
|
}
|
|
214
310
|
try {
|
|
215
|
-
applyPolicyLayer(this.base, layer);
|
|
311
|
+
const effective = applyPolicyLayer(this.base, layer);
|
|
312
|
+
// The windows are checked against the retention here, where it is known: a window longer than it could never be met.
|
|
313
|
+
checkSignalFeeds(effective.signals.feeds, effective.signals.kinds, { signalsMs: this.signalsMs() }, 'layer.signals.feeds');
|
|
216
314
|
} catch (err) {
|
|
217
315
|
if (err instanceof ProfileError) return { ok: false, error: 'invalid', path: err.path };
|
|
218
316
|
throw err;
|
|
@@ -264,6 +362,8 @@ export class PolicyService {
|
|
|
264
362
|
let candidate: ResolvedProfile;
|
|
265
363
|
try {
|
|
266
364
|
candidate = applyPolicyLayer(this.base, layer);
|
|
365
|
+
// As save: a window longer than the retention could never be met, so the candidate is refused here too, not only when it is saved.
|
|
366
|
+
checkSignalFeeds(candidate.signals.feeds, candidate.signals.kinds, { signalsMs: this.signalsMs() }, 'layer.signals.feeds');
|
|
267
367
|
} catch (err) {
|
|
268
368
|
if (err instanceof ProfileError) return { ok: false, error: 'invalid', path: err.path };
|
|
269
369
|
throw err;
|
package/src/profile.ts
CHANGED
|
@@ -18,6 +18,12 @@ import {
|
|
|
18
18
|
resolveReporting,
|
|
19
19
|
} from './reporting.js';
|
|
20
20
|
import type { ReportingSettings, ResolvedReporting } from './reporting.js';
|
|
21
|
+
import { deepFreeze } from './freeze.js';
|
|
22
|
+
import { mergePace, resolvePace } from './pace.js';
|
|
23
|
+
import type { PaceSettings, ResolvedPace } from './pace.js';
|
|
24
|
+
import { checkSignalFeeds, resolveSignals } from './signals.js';
|
|
25
|
+
import type { ResolvedSignals, SignalFeeds, SignalSettings } from './signals.js';
|
|
26
|
+
import { ProfileError } from './profileError.js';
|
|
21
27
|
|
|
22
28
|
/**
|
|
23
29
|
* A moderation profile is a game's written standard: what each conduct level means, what happens on a first
|
|
@@ -144,8 +150,49 @@ export interface ModerationProfile extends ModerationProfileBase {
|
|
|
144
150
|
* {@link ReportingSettings}.
|
|
145
151
|
*/
|
|
146
152
|
reporting?: ReportingSettings;
|
|
153
|
+
/**
|
|
154
|
+
* The AI read, in the moderator's hands: `level` 0 is off (the default), 1 reads each report and shows a summary, 2 also
|
|
155
|
+
* recommends; `learn` (default true) lets decided cases teach the read. A level 3 or 4 is refused ("not available yet"). The
|
|
156
|
+
* hub edits this section; the code-side AI option sets the adapter and the highest level it may reach. See {@link AISettings}.
|
|
157
|
+
*/
|
|
158
|
+
ai?: Partial<AISettings>;
|
|
159
|
+
/**
|
|
160
|
+
* How a room paces a player's lines: a least gap between them (`slowModeMs`), a burst limit (`burst`) and no repeats
|
|
161
|
+
* (`duplicateWindowMs`). Every setting is off until set, so a profile without `pace` changes nothing. See {@link PaceSettings}.
|
|
162
|
+
* @experimental
|
|
163
|
+
*/
|
|
164
|
+
pace?: PaceSettings;
|
|
165
|
+
/**
|
|
166
|
+
* Signals: what the game records about a player (muted by others, kicked, left mid-game). `kinds` and `guards` are declared in code
|
|
167
|
+
* only; `feeds` says where counts may be read (the Person page record, the ladder suggestion, the AI read's context, the queue
|
|
168
|
+
* boost) and is editable in the hub. Nothing is unset-only: a profile without `signals` declares no kinds and has no feeds. A signal
|
|
169
|
+
* never acts. See {@link SignalSettings}.
|
|
170
|
+
* @experimental
|
|
171
|
+
*/
|
|
172
|
+
signals?: SignalSettings;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* The AI levels and the casebook switch, as the profile holds them. The level in force is also bounded by the adapter and the
|
|
177
|
+
* maximum level given in code, and is 0 when no adapter is configured.
|
|
178
|
+
* @experimental
|
|
179
|
+
*/
|
|
180
|
+
export interface AISettings {
|
|
181
|
+
/** 0 off, 1 read, 2 recommend. 3 and 4 are not available yet. */
|
|
182
|
+
level: 0 | 1 | 2;
|
|
183
|
+
/** Whether decided cases may be kept as pseudonymised examples for later reads. Default true. */
|
|
184
|
+
learn: boolean;
|
|
185
|
+
/**
|
|
186
|
+
* The most provider calls the AI may make in a UTC day, a second guard beside the spend cap in code (an adapter that reports no cost
|
|
187
|
+
* cannot run unbounded). A whole number from 1 to 100 000; default 5 000.
|
|
188
|
+
*/
|
|
189
|
+
dailyCalls: number;
|
|
147
190
|
}
|
|
148
191
|
|
|
192
|
+
/** The default and the largest value of {@link AISettings.dailyCalls}. */
|
|
193
|
+
export const AI_DAILY_CALLS_DEFAULT = 5000;
|
|
194
|
+
export const AI_DAILY_CALLS_MAX = 100_000;
|
|
195
|
+
|
|
149
196
|
/**
|
|
150
197
|
* What `defineProfile`, `resolveProfile`, `applyPolicyLayer`, `cw.profile` and `cw.policy.get()` return: a validated, deep-frozen
|
|
151
198
|
* profile with `durations` and `customDuration` filled in. It is a {@link ModerationProfile}, so it can be passed wherever one is
|
|
@@ -164,6 +211,12 @@ export interface ResolvedProfile extends ModerationProfileBase {
|
|
|
164
211
|
customDuration: boolean;
|
|
165
212
|
/** The reporting settings in force, every field filled in. */
|
|
166
213
|
reporting: ResolvedReporting;
|
|
214
|
+
/** The AI settings in force, every field filled in. */
|
|
215
|
+
ai: AISettings;
|
|
216
|
+
/** The pace settings in force, every field filled in (`null` is off). @experimental */
|
|
217
|
+
pace: ResolvedPace;
|
|
218
|
+
/** The signal settings in force: the declared kinds merged over the built-ins, the guards filled in, the feeds as given. @experimental */
|
|
219
|
+
signals: ResolvedSignals;
|
|
167
220
|
}
|
|
168
221
|
|
|
169
222
|
/** @deprecated The same as {@link ModerationProfile}, which now has the two fields optional. */
|
|
@@ -179,18 +232,7 @@ export type DeepPartial<T> = T extends readonly unknown[]
|
|
|
179
232
|
/** Overrides for {@link resolveProfile}. Any field; arrays replace the preset's array whole. */
|
|
180
233
|
export type ProfileOverrides = DeepPartial<ModerationProfile>;
|
|
181
234
|
|
|
182
|
-
|
|
183
|
-
export class ProfileError extends Error {
|
|
184
|
-
readonly path: string;
|
|
185
|
-
/** The rule that was broken, without the path. Never a value. */
|
|
186
|
-
readonly reason: string;
|
|
187
|
-
constructor(path: string, reason: string) {
|
|
188
|
-
super(`${path} ${reason}`);
|
|
189
|
-
this.name = 'ProfileError';
|
|
190
|
-
this.path = path;
|
|
191
|
-
this.reason = reason;
|
|
192
|
-
}
|
|
193
|
-
}
|
|
235
|
+
export { ProfileError };
|
|
194
236
|
|
|
195
237
|
// ---------------------------------------------------------------------------------------------------------------
|
|
196
238
|
// Validation
|
|
@@ -211,12 +253,16 @@ const TOP_KEYS = [
|
|
|
211
253
|
'durations',
|
|
212
254
|
'customDuration',
|
|
213
255
|
'reporting',
|
|
256
|
+
'ai',
|
|
257
|
+
'pace',
|
|
258
|
+
'signals',
|
|
214
259
|
'levels',
|
|
215
260
|
'guidelines',
|
|
216
261
|
] as const;
|
|
217
262
|
/** Top-level keys that may be left out (the kit falls back to its defaults). */
|
|
218
263
|
const RULE_LIST_KEYS: readonly string[] = ['areaRules', 'severeRules'];
|
|
219
|
-
const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting'];
|
|
264
|
+
const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting', 'ai', 'pace', 'signals'];
|
|
265
|
+
const AI_KEYS = ['level', 'learn', 'dailyCalls'] as const;
|
|
220
266
|
/** The most rule numbers `areaRules` or `severeRules` may list. */
|
|
221
267
|
export const MAX_RULE_LIST = 100;
|
|
222
268
|
const REPEAT_KEYS = ['windowDays', 'notes', 'distinctGames', 'outcome'] as const;
|
|
@@ -396,6 +442,23 @@ function lineOf(v: unknown, path: string, min: 0 | 1, max: number): void {
|
|
|
396
442
|
}
|
|
397
443
|
}
|
|
398
444
|
|
|
445
|
+
/** The `ai` section, in input shape (both fields optional). Levels 3 and 4 are designed but not built, so they are refused by name. */
|
|
446
|
+
function validateAI(v: unknown, path: string): void {
|
|
447
|
+
const ai = obj(v, path, AI_KEYS, AI_KEYS);
|
|
448
|
+
if (Object.hasOwn(ai, 'level')) {
|
|
449
|
+
const level = ai['level'];
|
|
450
|
+
if (level === 3 || level === 4) fail(`${path}.level`, 'AI levels 3 and 4 are not available yet');
|
|
451
|
+
if (level !== 0 && level !== 1 && level !== 2) fail(`${path}.level`, 'must be 0 (off), 1 (read) or 2 (recommend)');
|
|
452
|
+
}
|
|
453
|
+
if (Object.hasOwn(ai, 'learn') && typeof ai['learn'] !== 'boolean') fail(`${path}.learn`, 'must be true or false');
|
|
454
|
+
if (Object.hasOwn(ai, 'dailyCalls')) {
|
|
455
|
+
const n = ai['dailyCalls'];
|
|
456
|
+
if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > AI_DAILY_CALLS_MAX) {
|
|
457
|
+
fail(`${path}.dailyCalls`, `must be a whole number of calls from 1 to ${AI_DAILY_CALLS_MAX}`);
|
|
458
|
+
}
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
|
|
399
462
|
/** The `reporting` section, in input shape (every field optional, a reason needing only an id and a label). */
|
|
400
463
|
function validateReporting(v: unknown, path: string): void {
|
|
401
464
|
const rep = obj(v, path, REPORTING_KEYS, REPORTING_KEYS);
|
|
@@ -477,6 +540,9 @@ export function validateProfile(value: unknown): asserts value is ModerationProf
|
|
|
477
540
|
if (Object.hasOwn(p, 'durations')) validateDurations(p['durations'], 'profile.durations');
|
|
478
541
|
if (Object.hasOwn(p, 'customDuration') && typeof p['customDuration'] !== 'boolean') fail('profile.customDuration', 'must be true or false');
|
|
479
542
|
if (Object.hasOwn(p, 'reporting')) validateReporting(p['reporting'], 'profile.reporting');
|
|
543
|
+
if (Object.hasOwn(p, 'ai')) validateAI(p['ai'], 'profile.ai');
|
|
544
|
+
if (Object.hasOwn(p, 'pace')) resolvePace(p['pace'] as PaceSettings, 'profile.pace');
|
|
545
|
+
if (Object.hasOwn(p, 'signals')) resolveSignals(p['signals'] as SignalSettings, 'profile.signals');
|
|
480
546
|
|
|
481
547
|
const prof = obj(p['profanity'], 'profile.profanity', PROFANITY_KEYS);
|
|
482
548
|
oneOf(prof['mode'], 'profile.profanity.mode', PROFANITY_MODES, "must be 'allow', 'star' or 'refuse'");
|
|
@@ -538,14 +604,6 @@ function merge(base: unknown, over: unknown, depth = 0): unknown {
|
|
|
538
604
|
return clone(over, depth);
|
|
539
605
|
}
|
|
540
606
|
|
|
541
|
-
function deepFreeze<T>(v: T): T {
|
|
542
|
-
if (typeof v === 'object' && v !== null && !Object.isFrozen(v)) {
|
|
543
|
-
Object.freeze(v);
|
|
544
|
-
for (const item of Object.values(v)) deepFreeze(item);
|
|
545
|
-
}
|
|
546
|
-
return v;
|
|
547
|
-
}
|
|
548
|
-
|
|
549
607
|
/** Drop repeated numbers from `areaRules` and `severeRules` (first one wins, order kept) before they are validated. */
|
|
550
608
|
function dedupeRuleLists(copy: unknown): void {
|
|
551
609
|
if (!isPlain(copy)) return;
|
|
@@ -572,9 +630,16 @@ function dedupeReasonRules(copy: Record<string, unknown>): void {
|
|
|
572
630
|
});
|
|
573
631
|
}
|
|
574
632
|
|
|
575
|
-
/**
|
|
633
|
+
/** The AI settings with every field filled in; a value of the wrong shape is returned as it is, for the validator to name. */
|
|
634
|
+
function fillAI(value: unknown): unknown {
|
|
635
|
+
if (value === undefined) return { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT };
|
|
636
|
+
return isPlain(value) ? { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...value } : value;
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
/** A profile written before `durations`, `customDuration`, `reporting` and `ai` existed gets their defaults. */
|
|
576
640
|
function fillDefaults(copy: unknown): void {
|
|
577
641
|
if (!isPlain(copy)) return;
|
|
642
|
+
setOwn(copy, 'ai', fillAI(copy['ai']));
|
|
578
643
|
if (!Object.hasOwn(copy, 'durations')) setOwn(copy, 'durations', [...DEFAULT_DURATIONS]);
|
|
579
644
|
if (!Object.hasOwn(copy, 'customDuration')) setOwn(copy, 'customDuration', true);
|
|
580
645
|
// A section of the wrong shape is left as it is, for the validator to name; one that checks out is filled in.
|
|
@@ -588,6 +653,11 @@ function finalize(value: unknown): ResolvedProfile {
|
|
|
588
653
|
dedupeRuleLists(copy);
|
|
589
654
|
fillDefaults(copy);
|
|
590
655
|
validateProfile(copy);
|
|
656
|
+
// Checked above, so this cannot throw: every pace field is filled in, `null` meaning off.
|
|
657
|
+
if (isPlain(copy)) {
|
|
658
|
+
setOwn(copy, 'pace', resolvePace(copy['pace'] as PaceSettings | undefined, 'profile.pace'));
|
|
659
|
+
setOwn(copy, 'signals', resolveSignals(copy['signals'] as SignalSettings | undefined, 'profile.signals'));
|
|
660
|
+
}
|
|
591
661
|
return deepFreeze(copy as ResolvedProfile);
|
|
592
662
|
}
|
|
593
663
|
|
|
@@ -596,7 +666,15 @@ function finalize(value: unknown): ResolvedProfile {
|
|
|
596
666
|
* changed and the profile is not validated here (`validateProfile` does that). Used by the document functions.
|
|
597
667
|
*/
|
|
598
668
|
export function withDurationDefaults(p: ModerationProfile): ResolvedProfile {
|
|
599
|
-
return {
|
|
669
|
+
return {
|
|
670
|
+
...p,
|
|
671
|
+
durations: p.durations ?? [...DEFAULT_DURATIONS],
|
|
672
|
+
customDuration: p.customDuration ?? true,
|
|
673
|
+
reporting: resolveReporting(p.reporting),
|
|
674
|
+
ai: { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...p.ai },
|
|
675
|
+
pace: resolvePace(p.pace),
|
|
676
|
+
signals: resolveSignals(p.signals),
|
|
677
|
+
};
|
|
600
678
|
}
|
|
601
679
|
|
|
602
680
|
// ---------------------------------------------------------------------------------------------------------------
|
|
@@ -916,7 +994,7 @@ export function defineProfile(p: ModerationProfile): ResolvedProfile {
|
|
|
916
994
|
* The parts of a profile the hub may edit, and the order they are listed in. Everything else (identity, the written
|
|
917
995
|
* levels, the AI context, profanity handling) stays in code: changing profanity means rebuilding the filter.
|
|
918
996
|
*/
|
|
919
|
-
export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting'] as const;
|
|
997
|
+
export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting', 'ai', 'pace', 'signals'] as const;
|
|
920
998
|
export type PolicySection = (typeof POLICY_SECTIONS)[number];
|
|
921
999
|
|
|
922
1000
|
/** One ladder cell as the editor sends it: the label may be left out and is then generated ("Restrict chat 6 hours"). */
|
|
@@ -950,6 +1028,18 @@ export interface PolicyLayer {
|
|
|
950
1028
|
guidelines?: Array<{ outcome: string } | null>;
|
|
951
1029
|
/** The reporting settings: `flow` and `thanks` replace the profile's; `reasons` replaces the whole list. Each is optional; a reason needs only `id` and `label`. */
|
|
952
1030
|
reporting?: ReportingSettings;
|
|
1031
|
+
/** The AI settings: `level` (0 off, 1 read, 2 recommend), `learn` and `dailyCalls` (the owner's ceiling on calls in a UTC day, a whole number from 1 to 100 000). Each is optional and merges onto the profile's. Levels 3 and 4 are refused. */
|
|
1032
|
+
ai?: Partial<AISettings>;
|
|
1033
|
+
/**
|
|
1034
|
+
* The pace settings: each field is optional and merges onto the profile's (a field left out inherits, `null` turns it off, a value sets
|
|
1035
|
+
* it); `burst` replaces whole. @experimental
|
|
1036
|
+
*/
|
|
1037
|
+
pace?: PaceSettings;
|
|
1038
|
+
/**
|
|
1039
|
+
* The signal feeds: only `feeds` may be edited (the kinds and the guards are declared in code). The layer's `feeds` REPLACE the
|
|
1040
|
+
* profile's wholesale, like every other section: a feed left out is off. A feed names declared kinds only. @experimental
|
|
1041
|
+
*/
|
|
1042
|
+
signals?: { feeds?: SignalFeeds };
|
|
953
1043
|
}
|
|
954
1044
|
|
|
955
1045
|
/** The longest outcome text a layer may set on a guideline tier. */
|
|
@@ -997,6 +1087,28 @@ function wholeOutcome(v: unknown, path: string): void {
|
|
|
997
1087
|
if (!Object.hasOwn(v, 'durationMs')) fail(`${path}.durationMs`, 'is required');
|
|
998
1088
|
}
|
|
999
1089
|
|
|
1090
|
+
/**
|
|
1091
|
+
* A layer's `signals` may hold only `feeds`, and every feed must name kinds the profile declares. The feeds themselves are not put in
|
|
1092
|
+
* the overrides: they replace the profile's wholesale, which the deep merge would not do, so `applyPolicyLayer` sets them after it.
|
|
1093
|
+
*/
|
|
1094
|
+
function layerSignals(base: ModerationProfile, value: unknown): void {
|
|
1095
|
+
if (!isPlain(value)) return fail('profile.signals', 'must be an object');
|
|
1096
|
+
for (const k of Object.keys(value)) {
|
|
1097
|
+
if (k !== 'feeds') fail(`profile.signals.${k}`, 'is not an editable setting: kinds and guards are declared in code');
|
|
1098
|
+
}
|
|
1099
|
+
const feeds = Object.hasOwn(value, 'feeds') ? value['feeds'] : undefined;
|
|
1100
|
+
checkSignalFeeds(feeds as SignalFeeds | undefined, resolveSignals(base.signals, 'profile.signals').kinds, { signalsMs: Infinity }, 'profile.signals.feeds');
|
|
1101
|
+
}
|
|
1102
|
+
|
|
1103
|
+
/** Put the layer's signal feeds in place of the merged profile's (a feed the layer leaves out is off). */
|
|
1104
|
+
function replaceSignalFeeds(merged: unknown, layer: unknown): void {
|
|
1105
|
+
if (!isPlain(merged) || !isPlain(layer) || !Object.hasOwn(layer, 'signals') || !isPlain(layer['signals'])) return;
|
|
1106
|
+
const feeds = Object.hasOwn(layer['signals'], 'feeds') ? layer['signals']['feeds'] : undefined;
|
|
1107
|
+
const section = isPlain(merged['signals']) ? merged['signals'] : {};
|
|
1108
|
+
setOwn(section, 'feeds', feeds === undefined ? {} : clone(feeds));
|
|
1109
|
+
setOwn(merged, 'signals', section);
|
|
1110
|
+
}
|
|
1111
|
+
|
|
1000
1112
|
function layerToOverrides(base: ModerationProfile, layer: unknown): Record<string, unknown> {
|
|
1001
1113
|
if (!isPlain(layer)) return fail('profile', 'must be an object');
|
|
1002
1114
|
for (const key of Object.keys(layer)) {
|
|
@@ -1010,7 +1122,15 @@ function layerToOverrides(base: ModerationProfile, layer: unknown): Record<strin
|
|
|
1010
1122
|
for (const level of Object.keys(value)) wholeOutcome(value[level], `profile.firstOffense.${level}`);
|
|
1011
1123
|
}
|
|
1012
1124
|
if (key === 'repeat' && isPlain(value)) wholeOutcome(value['outcome'], 'profile.repeat.outcome');
|
|
1013
|
-
if (key === '
|
|
1125
|
+
if (key === 'signals') {
|
|
1126
|
+
layerSignals(base, value);
|
|
1127
|
+
continue;
|
|
1128
|
+
}
|
|
1129
|
+
if (key === 'pace') {
|
|
1130
|
+
// Checked on its own so the error names layer.pace..., then merged here so `burst` replaces whole instead of merging by member.
|
|
1131
|
+
resolvePace(value as PaceSettings, 'profile.pace');
|
|
1132
|
+
setOwn(out, key, mergePace(resolvePace(base.pace, 'profile.pace'), value as PaceSettings));
|
|
1133
|
+
} else if (key === 'ladder') setOwn(out, key, ladderOverride(value));
|
|
1014
1134
|
else if (key === 'guidelines') setOwn(out, key, guidelinesOverride(base, value));
|
|
1015
1135
|
else setOwn(out, key, value);
|
|
1016
1136
|
}
|
|
@@ -1020,7 +1140,7 @@ function layerToOverrides(base: ModerationProfile, layer: unknown): Record<strin
|
|
|
1020
1140
|
/** The same error, with the path named from the layer the editor sent (`profile.ladder[2]` is `layer.ladder[2]`). */
|
|
1021
1141
|
function inLayerTerms(err: ProfileError): ProfileError {
|
|
1022
1142
|
const path = err.path === 'profile' ? 'layer' : err.path.startsWith('profile.') ? `layer.${err.path.slice('profile.'.length)}` : err.path;
|
|
1023
|
-
return new ProfileError(path, err.reason);
|
|
1143
|
+
return new ProfileError(path, err.reason, err.code);
|
|
1024
1144
|
}
|
|
1025
1145
|
|
|
1026
1146
|
/**
|
|
@@ -1031,7 +1151,9 @@ function inLayerTerms(err: ProfileError): ProfileError {
|
|
|
1031
1151
|
*/
|
|
1032
1152
|
export function applyPolicyLayer(base: ModerationProfile, layer: PolicyLayer): ResolvedProfile {
|
|
1033
1153
|
try {
|
|
1034
|
-
|
|
1154
|
+
const merged = merge(base, layerToOverrides(base, layer));
|
|
1155
|
+
replaceSignalFeeds(merged, layer);
|
|
1156
|
+
return finalize(merged);
|
|
1035
1157
|
} catch (err) {
|
|
1036
1158
|
throw err instanceof ProfileError ? inLayerTerms(err) : err;
|
|
1037
1159
|
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// Kept apart from profile.ts so pace.ts (which profile.ts imports) can throw it without an import cycle.
|
|
2
|
+
|
|
3
|
+
/** A profile that fails validation. `path` names the field (`'profile.firstOffense.banter'`); the message never echoes a value. */
|
|
4
|
+
export class ProfileError extends Error {
|
|
5
|
+
readonly path: string;
|
|
6
|
+
/** The rule that was broken, without the path. Never a value. */
|
|
7
|
+
readonly reason: string;
|
|
8
|
+
/** A stable code for the few failures a caller tells apart (a signal feed's `unknown_kind`, `positive_kind` or `window`); undefined for the rest. */
|
|
9
|
+
readonly code: string | undefined;
|
|
10
|
+
constructor(path: string, reason: string, code?: string) {
|
|
11
|
+
super(`${path} ${reason}`);
|
|
12
|
+
this.name = 'ProfileError';
|
|
13
|
+
this.path = path;
|
|
14
|
+
this.reason = reason;
|
|
15
|
+
this.code = code;
|
|
16
|
+
}
|
|
17
|
+
}
|
package/src/retention.ts
CHANGED
|
@@ -25,6 +25,21 @@ export interface RetentionPolicy {
|
|
|
25
25
|
badFaithMs: number;
|
|
26
26
|
/** A staff audit entry is deleted once it is older than this. */
|
|
27
27
|
auditMs: number;
|
|
28
|
+
/**
|
|
29
|
+
* An AI outcome row (the agree-or-override record: ids and counts, no chat text) is kept this long. At least 90 days. A read
|
|
30
|
+
* itself goes with its report (`reportsMs`).
|
|
31
|
+
*/
|
|
32
|
+
aiOutcomesMs: number;
|
|
33
|
+
/**
|
|
34
|
+
* The pseudonymised example text kept with an AI outcome is deleted once it is older than this. It is the only chat text that
|
|
35
|
+
* outlives a report, so it is the shortest of the three; 0 keeps no text at all.
|
|
36
|
+
*/
|
|
37
|
+
aiExamplesMs: number;
|
|
38
|
+
/**
|
|
39
|
+
* A signal row (what a game recorded about a player, `flood_triggered` included) is deleted once it is older than this. At least 14
|
|
40
|
+
* days: a counting window needs at least two weeks of rows. A feed window longer than this is refused.
|
|
41
|
+
*/
|
|
42
|
+
signalsMs: number;
|
|
28
43
|
}
|
|
29
44
|
|
|
30
45
|
export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
|
|
@@ -34,12 +49,15 @@ export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
|
|
|
34
49
|
noticesMs: 90 * DAY_MS,
|
|
35
50
|
badFaithMs: 30 * DAY_MS,
|
|
36
51
|
auditMs: 365 * DAY_MS,
|
|
52
|
+
aiOutcomesMs: 365 * DAY_MS,
|
|
53
|
+
aiExamplesMs: 180 * DAY_MS,
|
|
54
|
+
signalsMs: 90 * DAY_MS,
|
|
37
55
|
};
|
|
38
56
|
|
|
39
57
|
/** The ladder looks back 90 days and "My record" shows 90 days, so the rows behind them must outlive that. */
|
|
40
58
|
const RECORD_FLOOR_MS = 90 * DAY_MS;
|
|
41
59
|
|
|
42
|
-
const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs'] as const;
|
|
60
|
+
const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs', 'aiOutcomesMs', 'aiExamplesMs', 'signalsMs'] as const;
|
|
43
61
|
|
|
44
62
|
/**
|
|
45
63
|
* Refuse a retention policy that would delete rows the kit still reads. Only the fields present are checked (an
|
|
@@ -48,6 +66,9 @@ const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'ba
|
|
|
48
66
|
* - `noticesMs` at least 90 days: "My record" shows that far back
|
|
49
67
|
* - `badFaithMs` at least `suspendWindowMs`: a bad-faith dismissal weighs against its reporter for that long
|
|
50
68
|
* - `auditMs` at least 90 days: the staff trail is how a community answers "who did that"
|
|
69
|
+
* - `aiOutcomesMs` at least 90 days: the agree-or-override record is the data the AI's later gates read
|
|
70
|
+
* - `aiExamplesMs` at least 0 (0 keeps no example text at all)
|
|
71
|
+
* - `signalsMs` at least 14 days: a counting window needs at least two weeks of rows
|
|
51
72
|
*
|
|
52
73
|
* Every field present must also be a finite number (`reportsMs` and `strikesMs` have no floor, only this).
|
|
53
74
|
*
|
|
@@ -76,6 +97,15 @@ export function checkRetentionFloors(policy: Partial<RetentionPolicy>, suspendWi
|
|
|
76
97
|
if (below(policy.auditMs, RECORD_FLOOR_MS)) {
|
|
77
98
|
throw new ProfileError('retention.auditMs', 'must be at least 90 days: the audit trail answers who did what, and when');
|
|
78
99
|
}
|
|
100
|
+
if (below(policy.aiOutcomesMs, RECORD_FLOOR_MS)) {
|
|
101
|
+
throw new ProfileError('retention.aiOutcomesMs', 'must be at least 90 days: it is the record of how often the AI and the moderators agreed');
|
|
102
|
+
}
|
|
103
|
+
if (below(policy.aiExamplesMs, 0)) {
|
|
104
|
+
throw new ProfileError('retention.aiExamplesMs', 'must be 0 or more: 0 keeps no example text at all');
|
|
105
|
+
}
|
|
106
|
+
if (below(policy.signalsMs, 14 * DAY_MS)) {
|
|
107
|
+
throw new ProfileError('retention.signalsMs', 'must be at least 14 days: a counting window needs at least two weeks of rows');
|
|
108
|
+
}
|
|
79
109
|
if (below(policy.badFaithMs, suspendWindowMs)) {
|
|
80
110
|
throw new ProfileError(
|
|
81
111
|
'retention.badFaithMs',
|
|
@@ -94,6 +124,12 @@ export interface PurgeResult {
|
|
|
94
124
|
notices: number;
|
|
95
125
|
audit: number;
|
|
96
126
|
webhookKeys: number;
|
|
127
|
+
/** AI reads deleted by the retention pass (a read also goes with its report). 0 for a store without the AI methods. */
|
|
128
|
+
aiReads: number;
|
|
129
|
+
/** AI casebook outcomes deleted. 0 for a store without the AI methods. */
|
|
130
|
+
aiOutcomes: number;
|
|
131
|
+
/** Signal rows deleted (flood_triggered included). 0 for a store without the signal methods. */
|
|
132
|
+
signals: number;
|
|
97
133
|
}
|
|
98
134
|
|
|
99
135
|
function checkWindow(name: string, ms: number): void {
|
|
@@ -114,6 +150,10 @@ function checkWindow(name: string, ms: number): void {
|
|
|
114
150
|
* term-editor rows written before the trail existed
|
|
115
151
|
* - webhook keys: `createdAt < now - 24 h` (incoming-webhook idempotency keys, pending or done)
|
|
116
152
|
* - mutes: `createdAt < now - 180 days`, the mute TTL (a mute past it is already ignored)
|
|
153
|
+
* - AI reads: `createdAt < now - reportsMs` (a read also goes with its report, in `purgeReports`); AI outcomes (agree-or-override
|
|
154
|
+
* record, no chat text): `decidedAt < now - aiOutcomesMs`; the pseudonymised example kept with an outcome:
|
|
155
|
+
* `decidedAt < now - aiExamplesMs`, the row stays with its counts. A store without the AI methods has none of these.
|
|
156
|
+
* - signals: `at < now - signalsMs` (90 days by default, never less than 14); a store without the signal methods has none
|
|
117
157
|
* - notices: withdrawn, or a seen warning / report outcome, with `createdAt < now - noticesMs`; or
|
|
118
158
|
* `until < now - noticesMs`. A notice for a permanent or running sanction is kept while it applies (agrees with
|
|
119
159
|
* `NoticeService.record`), and an unseen warning is kept until it is seen or withdrawn.
|
|
@@ -133,6 +173,9 @@ export async function purge(
|
|
|
133
173
|
noticesMs: policy.noticesMs ?? RETENTION_DEFAULTS.noticesMs,
|
|
134
174
|
badFaithMs: policy.badFaithMs ?? RETENTION_DEFAULTS.badFaithMs,
|
|
135
175
|
auditMs: policy.auditMs ?? RETENTION_DEFAULTS.auditMs,
|
|
176
|
+
aiOutcomesMs: policy.aiOutcomesMs ?? RETENTION_DEFAULTS.aiOutcomesMs,
|
|
177
|
+
aiExamplesMs: policy.aiExamplesMs ?? RETENTION_DEFAULTS.aiExamplesMs,
|
|
178
|
+
signalsMs: policy.signalsMs ?? RETENTION_DEFAULTS.signalsMs,
|
|
136
179
|
};
|
|
137
180
|
if (!Number.isFinite(now)) throw new Error('purge: invalid now');
|
|
138
181
|
checkWindow('reportsMs', p.reportsMs);
|
|
@@ -141,13 +184,23 @@ export async function purge(
|
|
|
141
184
|
checkWindow('noticesMs', p.noticesMs);
|
|
142
185
|
checkWindow('badFaithMs', p.badFaithMs);
|
|
143
186
|
checkWindow('auditMs', p.auditMs);
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
187
|
+
checkWindow('aiOutcomesMs', p.aiOutcomesMs);
|
|
188
|
+
checkWindow('aiExamplesMs', p.aiExamplesMs);
|
|
189
|
+
checkWindow('signalsMs', p.signalsMs);
|
|
190
|
+
return store.transaction(() => {
|
|
191
|
+
const reports = store.purgeReports(now - p.reportsMs, now - p.badFaithMs);
|
|
192
|
+
const ai = store.purgeAi?.(now - p.reportsMs, now - p.aiOutcomesMs, now - p.aiExamplesMs) ?? { reads: 0, outcomes: 0 };
|
|
193
|
+
return {
|
|
194
|
+
reports,
|
|
195
|
+
sanctions: store.purgeSanctions(now - p.sanctionAfterEndMs),
|
|
196
|
+
strikes: store.purgeStrikes(now - p.strikesMs),
|
|
197
|
+
mutes: store.purgeMutes(now - MUTE_TTL_MS),
|
|
198
|
+
notices: store.purgeNotices(now - p.noticesMs),
|
|
199
|
+
audit: store.purgeAudit(now - p.auditMs),
|
|
200
|
+
webhookKeys: store.purgeWebhookKeys(now - WEBHOOK_KEY_TTL_MS),
|
|
201
|
+
aiReads: ai.reads,
|
|
202
|
+
aiOutcomes: ai.outcomes,
|
|
203
|
+
signals: store.purgeSignals?.(now - p.signalsMs) ?? 0,
|
|
204
|
+
};
|
|
205
|
+
});
|
|
153
206
|
}
|