@chatwarden/core 0.1.7 → 0.1.9
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 +306 -7
- package/dist/src/ai/case.d.ts +4 -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 +13 -2
- package/dist/src/ai/prompt.d.ts.map +1 -1
- package/dist/src/ai/prompt.js +31 -1
- package/dist/src/ai/prompt.js.map +1 -1
- package/dist/src/ai/service.d.ts +21 -6
- package/dist/src/ai/service.d.ts.map +1 -1
- package/dist/src/ai/service.js +14 -7
- package/dist/src/ai/service.js.map +1 -1
- package/dist/src/ai/types.d.ts +33 -2
- package/dist/src/ai/types.d.ts.map +1 -1
- package/dist/src/ai/types.js +3 -2
- package/dist/src/ai/types.js.map +1 -1
- package/dist/src/ai/worker.d.ts +8 -1
- package/dist/src/ai/worker.d.ts.map +1 -1
- package/dist/src/ai/worker.js +17 -3
- package/dist/src/ai/worker.js.map +1 -1
- package/dist/src/appealService.d.ts +105 -0
- package/dist/src/appealService.d.ts.map +1 -0
- package/dist/src/appealService.js +548 -0
- package/dist/src/appealService.js.map +1 -0
- package/dist/src/appeals.d.ts +194 -0
- package/dist/src/appeals.d.ts.map +1 -0
- package/dist/src/appeals.js +107 -0
- package/dist/src/appeals.js.map +1 -0
- package/dist/src/audit.d.ts +7 -3
- package/dist/src/audit.d.ts.map +1 -1
- package/dist/src/audit.js +18 -3
- 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 +197 -10
- package/dist/src/chatwarden.d.ts.map +1 -1
- package/dist/src/chatwarden.js +212 -23
- package/dist/src/chatwarden.js.map +1 -1
- package/dist/src/decide.d.ts +2 -0
- package/dist/src/decide.d.ts.map +1 -1
- package/dist/src/decide.js +12 -7
- 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 +5 -1
- package/dist/src/documents.js.map +1 -1
- package/dist/src/events.d.ts +38 -0
- package/dist/src/events.d.ts.map +1 -1
- package/dist/src/events.js +3 -0
- package/dist/src/events.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 +20 -9
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +11 -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/nameService.d.ts +90 -0
- package/dist/src/nameService.d.ts.map +1 -0
- package/dist/src/nameService.js +224 -0
- package/dist/src/nameService.js.map +1 -0
- package/dist/src/names.d.ts +68 -0
- package/dist/src/names.d.ts.map +1 -0
- package/dist/src/names.js +87 -0
- package/dist/src/names.js.map +1 -0
- package/dist/src/notices.d.ts +53 -5
- package/dist/src/notices.d.ts.map +1 -1
- package/dist/src/notices.js +93 -8
- package/dist/src/notices.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 +66 -1
- package/dist/src/policy.d.ts.map +1 -1
- package/dist/src/policy.js +86 -5
- package/dist/src/policy.js.map +1 -1
- package/dist/src/profile.d.ts +57 -8
- package/dist/src/profile.d.ts.map +1 -1
- package/dist/src/profile.js +69 -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 +40 -1
- package/dist/src/retention.d.ts.map +1 -1
- package/dist/src/retention.js +50 -3
- package/dist/src/retention.js.map +1 -1
- package/dist/src/sanctions.d.ts +29 -1
- package/dist/src/sanctions.d.ts.map +1 -1
- package/dist/src/sanctions.js +52 -9
- package/dist/src/sanctions.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/staffViews.d.ts +18 -0
- package/dist/src/staffViews.d.ts.map +1 -1
- package/dist/src/staffViews.js +14 -0
- package/dist/src/staffViews.js.map +1 -1
- 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 +254 -7
- 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 +6 -4
- package/src/ai/hash.ts +5 -2
- package/src/ai/prompt.ts +39 -2
- package/src/ai/service.ts +29 -14
- package/src/ai/types.ts +31 -2
- package/src/ai/worker.ts +20 -4
- package/src/appealService.ts +584 -0
- package/src/appeals.ts +256 -0
- package/src/audit.ts +18 -3
- package/src/chat.ts +109 -8
- package/src/chatwarden.ts +382 -27
- package/src/decide.ts +13 -7
- package/src/documents.ts +8 -3
- package/src/events.ts +23 -1
- package/src/freeze.ts +8 -0
- package/src/index.ts +52 -3
- package/src/ladder.ts +59 -1
- package/src/nameService.ts +255 -0
- package/src/names.ts +121 -0
- package/src/notices.ts +112 -14
- package/src/pace.ts +139 -0
- package/src/pacing.ts +242 -0
- package/src/policy.ts +125 -8
- package/src/profile.ts +115 -25
- package/src/profileError.ts +17 -0
- package/src/retention.ts +79 -3
- package/src/sanctions.ts +72 -9
- 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/staffViews.ts +30 -0
- package/src/subjects.ts +5 -0
- package/src/team.ts +93 -5
- package/src/types.ts +275 -8
package/README.md
CHANGED
|
@@ -110,25 +110,28 @@ For the moderators' screens and the player's notices, mount the routes in
|
|
|
110
110
|
|
|
111
111
|
| Part | What it is for |
|
|
112
112
|
| --- | --- |
|
|
113
|
-
| `cw.rooms` | `seat`, `seatConnection`, `unseat`, `close`: who is in which seat of which room. |
|
|
113
|
+
| `cw.rooms` | `seat`, `seatConnection`, `unseat`, `close`: who is in which seat of which room. `setPace(roomId, pace)` and `pace(roomId)` (`@experimental`) give one room its own slow mode, burst limit and repeat rule, in this process only. See "Slow mode and flood control". |
|
|
114
114
|
| `cw.chat.accept(room, seat, text)` | The answer for one line: `{ deliver }` or `{ refuse: { reason } }`. `visibleTo` applies a viewer's mutes. `restricted(who)` says whether a person is chat-restricted, for typing indicators; `restrictedBySubject(subject)` (`@experimental`) says the same for a subject id from `cw.rooms.subjectAt`, so a server that keeps a connection open need not keep the player's key to ask again. |
|
|
115
115
|
| `cw.mutes` | A player mutes another player for themselves only. |
|
|
116
|
+
| `cw.signals` | `@experimental`. What your game records about a player, counted by distinct source: `record`, `counts`, `kinds`, `boosted`, `forRecord`. See "Signals". |
|
|
116
117
|
| `cw.reports` | `submit` and `addDetail` (players; see "Reporting settings"), `list`, `get` and `reporterRecord` (staff). `reporterRecord(person)` is how the reports a person filed stand: `{ reports, open, actioned, dismissed, badFaith, suspendedUntil, reasonMatched, reasonDecided, accuracy }`. `reporterAccuracy(people)` is how often each person's recent reports turned out to be unfounded (see "Reporter accuracy"). |
|
|
117
118
|
| `cw.decide(input)` | A moderator closes a report and writes the sanctions and notices in one transaction. Safe to send twice. `reason` is required, except for a `no_action` with no actions (a one-click dismissal): leave it out and the standard reason `NO_ACTION_DEFAULT_REASON` (`No action needed`) is stored. |
|
|
118
119
|
| `cw.sanctions` | `apply` and `revoke`, for a moderator who acts without a report. `forPerson(subject)` and `list({ cursor?, limit?, source? })` (staff) read sanctions as `SanctionGroupView`s: one per group, built from the person's own row, so no IP, hash or stored value is in them. |
|
|
119
|
-
| `cw.blocked` | `list({ days })` and `countsByTerm({ days })` (staff), with `days` 1, 7 or 30: the lines the slur filter blocked, with the raw text, and the strikes per term. |
|
|
120
|
+
| `cw.blocked` | `list({ days })` and `countsByTerm({ days })` (staff), with `days` 1, 7 or 30: the lines the slur filter blocked, with the raw text, and the strikes per term. `names({ days })` (`@experimental`) lists the blocked names kept as evidence with `names.keepBlocked`. |
|
|
120
121
|
| `cw.reports.dismissMany(input)` | Staff, `@experimental`. "Nothing wrong here" for every open report about one person (`scope: { person }`, merged aliases included) or from one reporter (`scope: { reporter }`) in one call: at most 200 (`BULK_DISMISS_MAX`), `more: true` when there are more. Each report is closed like a single `no_action` decision with no actions and the standard reason (its own transaction, its own `report.closed` event); a bulk never marks bad faith and never counts toward a suspension. A case another moderator holds is skipped and counted unless `ignoreClaims`; `dryRun` counts and writes nothing. It writes no audit row: the staff layer does. Safe to run again. |
|
|
121
122
|
| `cw.cases` | The team workbench (staff): `claim(person, actor, { takeOver? })` and `release` a soft claim on a person's case (`releaseWhenDone` is what a decision does: it ends the claim only when the person has no other open report, so one case per person is held until its last report is decided), `next(actor, { category?, reason?, rankDownHabitual? })` to claim the oldest open case nobody holds (with `rankDownHabitual`, a case whose open reports all come from habitual false reporters and none has waited 24 hours is served after the ordinary ones, never skipped for good), `holder` / `holders` to read claims, and `view` / `viewers` for who has a case open. A claim lasts 10 minutes from the last beat on your clock, lives in the store (so several server processes on one database agree, and two moderators racing for one case never both win), and is a courtesy: the core never refuses a decision because of one (the HTTP routes do). Viewing is a 30 second hint kept in this process's memory and never stored; it tracks only people with an open report, and one actor keeps at most 20 cases open. A claimer that loses a database lock race to another process is retried (3 attempts) and gets the normal "claimed" answer. |
|
|
122
123
|
| `cw.changes.token()` | A cheap, opaque change token for the queue. It differs after any report filed or decided, sanction applied or revoked, rule gap closed, claim taken, taken over or released, or saved reason changed, and is the same otherwise (a claim heartbeat does not move it). It is kept in the store, so a restart does not rewind it (the in-memory store is the exception: it starts again at "0"). |
|
|
123
124
|
| `cw.reasons` | Saved decision reasons (staff): `list`, `add({ label, text })`, `update(id, patch)` and `setActive(id, active)`. A label is up to 40 characters, a text up to 500 (counted as characters, an emoji is one), at most 200 reasons; a label holds no control character, a text none but a newline. |
|
|
124
125
|
| `cw.notices` | A player's pending notices, acknowledgements and "My record". Built so no identifier can leak. |
|
|
125
126
|
| `cw.doors` | `check` a person at the door (login, join) against bans. |
|
|
126
|
-
| `cw.names
|
|
127
|
+
| `cw.names` | `check(text, opts?)`: may a player use this as a name? (`name_not_allowed`, and `name_profane` with `names.profanity`). `@experimental` since 0.1.9: `flagged`, `requireRename`, `pendingRename`, `renamed`, `renamesEnabled`, `renamesOf`. See "Names". |
|
|
128
|
+
| `cw.appeals` | `@experimental`. Appeals against sanctions: `file`, `mine` (players), `list`, `get`, `decide`, `stats`, `openCount`, `forPerson` (staff). Off until `appeals.enabled`. See "Appeals". |
|
|
129
|
+
| `cw.people` | `canonical`, `aliases`, and `accountIds(subject)` (`@experimental`, staff, server side only): the account ids you passed as `RawWho.accountId` for that person, so a game can find the player to rename. |
|
|
127
130
|
| `cw.history`, `cw.suggest` | A person's recent record, and what the preset suggests as the next step. |
|
|
128
131
|
| `cw.rules`, `cw.profile`, `cw.limits`, `cw.summary`, `cw.documents` | The rules, standard and numbers in force, and the written code of conduct and guides. `cw.profile` and `cw.summary` are read live: the profile in force is your code's profile with the owner's stored edits on top (see "The editable profile"), so read it when you need it and never keep it. |
|
|
129
|
-
| `cw.policy` | The editable profile: `get`, `save`, `preview`, `reset` and `refresh`. The lengths a moderator is offered, the ladder, the first offences, the repeat rule, the area and severe rules and the guideline outcome texts can be edited at runtime and are stored in your store. |
|
|
132
|
+
| `cw.policy` | The editable profile: `get` (it also reports `limits`, read only: the chat rate in force and the signals retention), `save`, `preview`, `reset` and `refresh`. The lengths a moderator is offered, the ladder, the first offences, the repeat rule, the area and severe rules and the guideline outcome texts can be edited at runtime and are stored in your store. |
|
|
130
133
|
| `cw.gaps`, `cw.audit` | Rule gaps for the periodic review, and the staff audit trail. |
|
|
131
|
-
| `cw.on(type, listener)` | Events: `report.created`, `report.closed`, `sanction.applied`, `sanction.revoked`, `gap.created`, `auto.restricted
|
|
134
|
+
| `cw.on(type, listener)` | Events: `report.created`, `report.closed`, `sanction.applied`, `sanction.revoked`, `gap.created`, `auto.restricted`, and, new in 0.1.9, `appeal.created`, `appeal.decided` and `rename.required` (`@experimental`; ids, codes and times only, never a statement, a reason or a name). |
|
|
132
135
|
| `cw.purge`, `cw.ready`, `cw.flush`, `cw.close` | Housekeeping. |
|
|
133
136
|
|
|
134
137
|
## Deciding a report
|
|
@@ -190,6 +193,9 @@ cw.policy.reset('durations'); // put one section back to the base; reset() puts
|
|
|
190
193
|
cannot be used: it is then ignored, the base stays in force, and one `chatwarden.policy_layer_invalid` line is logged. `kind` is `'unreadable'`
|
|
191
194
|
when the stored text could not be read at all (corrupted, not JSON, not an object), so the owner's edits are gone until they save again, and
|
|
192
195
|
`'invalid'` when it was read but a setting is not valid (a field from a newer kit, say). A save or a full `reset()` repairs either.
|
|
196
|
+
`layer` is the layer in force: a stored signal feed that can no longer be used (its kind is no longer declared in code, or its window is longer
|
|
197
|
+
than `retention.signalsMs` now allows) is dropped alone, the rest of the layer stays, and `dropped` (`[{ feed, reason }]`, a feed name and a reason
|
|
198
|
+
code, never a kind or a rule id; `@experimental`) says what went. Send `layer` back to `save` and it is accepted and repairs the stored row.
|
|
193
199
|
- **`save(layer, { version, actor, reason })`** stores the whole layer: a section you leave out goes back to the base. It answers
|
|
194
200
|
`{ ok: true, version, changed }`, `{ ok: false, error: 'conflict' }` for a stale `version` (nothing is written),
|
|
195
201
|
`{ ok: false, error: 'invalid', path }` for a layer that touches a setting that is not editable or would make the profile invalid
|
|
@@ -276,6 +282,293 @@ const res = await cw.reports.addDetail(reportId, 'seat-1', { reason: 'cheating',
|
|
|
276
282
|
- **Your own store.** `addReportDetail` and `loadReporterDecisions` are optional on `Store`. Without the first, `addDetail` answers `off`; without the
|
|
277
283
|
second, the accuracy counts are 0. `insertReport` must keep `reportedReason`, and `listReports` must apply the `reason` filter (`null` means none).
|
|
278
284
|
|
|
285
|
+
## What is experimental in 0.1.8
|
|
286
|
+
|
|
287
|
+
These may change before 0.2, and are marked `@experimental` in the types: `PaceSettings`, `ResolvedPace`, `resolvePace`, `mergePace`, `checkPace`,
|
|
288
|
+
`PACE_SUGGESTIONS`, `cw.rooms.setPace`, `cw.rooms.pace`, `cw.signals` and every signal type (`SignalInput`, `SignalCount`, `SignalSettings`, the feeds,
|
|
289
|
+
`PolicyDropped`, `PolicyLimits`, `PolicyState.limits` and `.dropped`), `SuggestContext.hideSignalText`, `Suggestion.signals`, `signalBoost` in
|
|
290
|
+
`cw.cases.next`, `BUILTIN_SIGNAL_KINDS`, `withMemorySignals`, the `pace` prop of `RestrictedChatLine` and `secondsLeft` in `@chatwarden/player-react`.
|
|
291
|
+
|
|
292
|
+
## What is experimental in 0.1.9
|
|
293
|
+
|
|
294
|
+
These may change before 0.2, and are marked `@experimental` in the types: `AppealSettings`, `ResolvedAppeals`, `resolveAppeals`, `cw.appeals` and every appeal type
|
|
295
|
+
(`PlayerAppeal`, `AppealFileResult`, `AppealRefusal`, `AppealDecision`, `AppealDecideResult`, `AppealSummary`, `AppealDetail`, `AppealPage`, `AppealStats`,
|
|
296
|
+
`AppealRuleStats`, `AppealRow`), `normalizeStatement`, `NameSettings`, `ResolvedNames`, `resolveNames`, `cw.names.flagged`, `cw.names.requireRename`,
|
|
297
|
+
`cw.names.pendingRename`, `cw.names.renamed`, `cw.names.renamesEnabled`, `cw.names.renamesOf`, `cw.blocked.names`, `BlockedNameRow`, `cw.people.accountIds`,
|
|
298
|
+
the `appeals` and `names` profile sections, the events `appeal.created`, `appeal.decided` and `rename.required`, the optional `Store` methods for appeals,
|
|
299
|
+
blocked names and `withdrawNotice`, `withMemoryAppeals` and `withMemoryNames`, and, in the other packages, `AppealDialog`, `nameReasonText` and the
|
|
300
|
+
`appeals` prop of `NoticeQueue` and `MyRecord` in `@chatwarden/player-react`, `appealsRateLimit` and `includeAccounts` in `@chatwarden/http`, and the
|
|
301
|
+
Appeals and Names screens of `@chatwarden/hub-react`. The names a game already used (`cw.names.check` and its reasons, `cw.notices`, `cw.sanctions`) are
|
|
302
|
+
not experimental, but some of their unions are wider now: see "Upgrading to 0.1.9".
|
|
303
|
+
|
|
304
|
+
## Slow mode and flood control
|
|
305
|
+
|
|
306
|
+
Optional and off until you set it, `@experimental` until 0.2 and new in 0.1.8. Three checks pace one player's lines in one room: **slow mode**
|
|
307
|
+
(at least `slowModeMs` between lines, 500 to 600 000), a **burst limit** (at most `burst.lines` lines in any `burst.windowMs`: 2 to 100 lines
|
|
308
|
+
in 1 000 to 600 000 ms) and **repeats** (the same line again inside `duplicateWindowMs`, 1 000 to 3 600 000, is refused). Set them in code with
|
|
309
|
+
`overrides.pace`, or the owner sets them in the hub (Settings, Advanced, "Slow mode and flooding"); the stored layer wins over code. The presets set
|
|
310
|
+
nothing, so no install changes by itself.
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
import { createChatwarden } from '@chatwarden/core';
|
|
314
|
+
import { createMemoryStore } from '@chatwarden/store-memory';
|
|
315
|
+
|
|
316
|
+
const cw = await createChatwarden({
|
|
317
|
+
store: createMemoryStore(),
|
|
318
|
+
secret: 'a-long-random-secret',
|
|
319
|
+
platform: { identify: (ctx) => ctx as { clientKey: string } },
|
|
320
|
+
overrides: { pace: { slowModeMs: 2000, burst: { lines: 6, windowMs: 10_000 }, duplicateWindowMs: 15_000 } },
|
|
321
|
+
});
|
|
322
|
+
|
|
323
|
+
// One room that differs, in this process, until the room closes: a tournament final is slower, a practice room is not paced at all.
|
|
324
|
+
cw.rooms.setPace('tournament:final', { slowModeMs: 3000 });
|
|
325
|
+
cw.rooms.setPace('practice', { slowModeMs: null, burst: null, duplicateWindowMs: null });
|
|
326
|
+
console.log(cw.rooms.pace('tournament:final')); // the pace in force there: the defaults with the override on top
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
- **A refusal, not a sanction.** `cw.chat.accept` answers `{ refuse: { reason, retryAfterMs } }` with `reason` `'slow_mode'`, `'flood'` or
|
|
330
|
+
`'duplicate'`, and `retryAfterMs` (at least 1) is when the same player may try again, in milliseconds from now. There is no rule, no notice and no
|
|
331
|
+
text with it. **A new refusal reason**: a `switch (reason)` that ends in `assertNever` will not compile until it handles the three, though a kit
|
|
332
|
+
can only send them after you turn pacing on. The staff routes and the chat box carry them through (`@chatwarden/http`, `@chatwarden/player-react`).
|
|
333
|
+
- **The order.** After the length check and before the fixed rate limit, so a player hammering a slow-mode room reads "slow mode" and not "too fast". A
|
|
334
|
+
line the fixed rate refuses does not count toward pacing, and a refusal never changes pacing state (repeating a refused line cannot extend its own
|
|
335
|
+
block). Repeats compare the line with letters and digits only, case and width folded and combining marks kept, so `gg` and `ok` (under three
|
|
336
|
+
characters) are never repeats; only a short digest is kept, never the text.
|
|
337
|
+
- **Per process.** Pacing state lives in memory in the process that serves the room and is lost on restart, like the fixed rate limit. Route a room's
|
|
338
|
+
chat to one process for the full effect; send one player's lines to several and the effective limit is up to that many times looser. Nothing is shared
|
|
339
|
+
or written, by design: a store round trip per line is the cost this exists to avoid. At most 50 000 (room, player) states are kept (`PACE_KEYS_MAX`).
|
|
340
|
+
`cw.rooms.setPace` is per process as well: call it where you create the room, in each process that serves it.
|
|
341
|
+
- **A burst looser than the fixed limit never triggers.** `limits.chatRate` (3 per 5 seconds by default) answers first inside the same window; the hub
|
|
342
|
+
says so beside the field, with the real numbers (`cw.policy.get().limits.chatRate`).
|
|
343
|
+
- **Flooding is remembered.** When the burst limit trips, the built-in signal `flood_triggered` ("Flooded the chat") is recorded for that player in that
|
|
344
|
+
room, at most once a window, whether or not you declared any signals (see "Signals"). It needs a store with the signal methods, else it is skipped.
|
|
345
|
+
- **Suggested values.** `PACE_SUGGESTIONS` (relaxed: burst 10 in 10 s, repeats 10 s; standard: 6 in 10 s, 15 s; strict: slow mode 2 s, 5 in 10 s, 30 s) is
|
|
346
|
+
what the hub's "Use suggested values" button fills in; nothing applies them by itself. `resolvePace`, `mergePace` and `checkPace` validate and merge.
|
|
347
|
+
- **To try it**, run `examples/tiny-chat` with `CW_DEMO_PACE=1` (a 2 second slow mode) and open the page.
|
|
348
|
+
|
|
349
|
+
## Signals
|
|
350
|
+
|
|
351
|
+
Optional, `@experimental` until 0.2 and new in 0.1.8. A signal is one fact your game records about a player ("muted by another player", "kicked from a
|
|
352
|
+
room", "left mid-game"). The kit counts them by distinct source and shows the counts where a profile rule says so. **A signal never acts on its own: it
|
|
353
|
+
never writes a sanction, a mute or a notice, and a person always decides.** Nothing is recorded or shown until you declare kinds and switch a feed on.
|
|
354
|
+
|
|
355
|
+
```ts
|
|
356
|
+
import { createChatwarden } from '@chatwarden/core';
|
|
357
|
+
import { openStore } from '@chatwarden/store-sqlite';
|
|
358
|
+
|
|
359
|
+
const cw = await createChatwarden({
|
|
360
|
+
store: openStore({ path: './chatwarden.db' }),
|
|
361
|
+
secret: process.env.CHATWARDEN_SECRET!,
|
|
362
|
+
platform: { identify: (ctx) => ctx as { clientKey: string } },
|
|
363
|
+
overrides: {
|
|
364
|
+
signals: {
|
|
365
|
+
kinds: {
|
|
366
|
+
muted_by_player: { label: 'Muted by other players', polarity: 'negative' },
|
|
367
|
+
kicked_from_room: { label: 'Kicked from a room', polarity: 'negative', weight: 2 },
|
|
368
|
+
commended: { label: 'Commended by other players', polarity: 'positive' },
|
|
369
|
+
},
|
|
370
|
+
feeds: { record: { kinds: '*', windowDays: 14 } },
|
|
371
|
+
},
|
|
372
|
+
},
|
|
373
|
+
});
|
|
374
|
+
|
|
375
|
+
// From the game's own events, never from every chat line: one small write each.
|
|
376
|
+
const player = { clientKey: 'a-client-key' };
|
|
377
|
+
const muter = { clientKey: 'another-client-key' };
|
|
378
|
+
cw.signals.record({ kind: 'muted_by_player', subject: player, by: muter, roomId: 'lobby-7' });
|
|
379
|
+
console.log(cw.signals.counts(cw.rooms.subjectAt('lobby-7', 'p1') ?? 's_unknown'));
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
- **Kinds are code.** A kind id is a lower-case slug (`muted_by_player`); the label is plain text, 1 to 60 characters; `polarity` is `'negative'` or `'positive'`;
|
|
383
|
+
`weight` is 0 to 10 (default 1). The kit declares one itself, `flood_triggered`, which you may relabel or re-weight but not make positive.
|
|
384
|
+
- **`cw.signals.record(input)`** is synchronous, fenced and never throws: it returns `true` when a row was written and `false` for any refusal
|
|
385
|
+
(logged by reason code, at most once a minute, never an id). `subject` and `by` are a subject id the kit already knows or a `RawWho`
|
|
386
|
+
(`{ clientKey?, accountId?, ip? }`, each under 513 characters) that it has already seen: a stranger is refused, never created. `by`, `roomId` and `at`
|
|
387
|
+
may be left out or `null`. A player cannot signal themselves (also across a merge), `at` may not be more than 5 minutes ahead or older than the
|
|
388
|
+
retention, and `roomId` is the game's own id: 1 to 64 of `A-Z a-z 0-9 _ . : -` (the built-in flood row uses a digest of a room id that does not fit).
|
|
389
|
+
- **Events, not lines.** Record what happens in your game (a mute, a kick), not every chat line: each record is a store write.
|
|
390
|
+
- **Counting is by distinct source.** A source is the `by` player; with no `by`, the room; with neither, the UTC day. A thousand mutes from one
|
|
391
|
+
player are one source. At most one row per kind, subject and source per `guards.perByWindowMs` (a day by default): the cap is a calendar bucket
|
|
392
|
+
(`floor(at / perByWindowMs)`), not a rolling window, so two rows a millisecond apart across a bucket edge both count, and changing the window later
|
|
393
|
+
re-buckets old rows. The optional `signals.accountAgeDays` hook (asked at most once a minute per player) with `guards.newAccount` makes a new account
|
|
394
|
+
count for a fraction of one. What this cannot stop is several real accounts that agree to signal one player: that is why a signal never acts.
|
|
395
|
+
- **Four feeds** (`profile.signals.feeds`, each off until set, editable in the hub: Settings, Advanced, "Signals"; a layer's `feeds` replaces the code's
|
|
396
|
+
wholesale): **`record`** (counts on the Person page), **`queue`** (a person who meets a threshold is taken ahead of older ordinary cases, capped, and an
|
|
397
|
+
overdue case still comes first), **`ladder`** (rules that add a sentence to the suggested step, or raise it one step; negative kinds only for a raise)
|
|
398
|
+
and **`ai`** (the counts as background for the AI read). A threshold is `kinds`, `minDistinct` (1 to 50), `windowDays` (1 to 90 and not above
|
|
399
|
+
`retention.signalsMs`) and an optional `minWeight`.
|
|
400
|
+
- **Retention.** Signal rows are kept 90 days by default (`retention.signalsMs`, never less than 14); a feed window longer than that is refused, in code
|
|
401
|
+
and in the hub, which reads the number from `cw.policy.get().limits.signalsMs`. A stored feed that can no longer be used (its kind is gone, or its window
|
|
402
|
+
is now too long) is dropped alone and reported as `dropped` on `cw.policy.get()`; the rest of the layer stays.
|
|
403
|
+
- **Your store needs the signal methods** (`insertSignal`, `listSignalSources`, `purgeSignals`, optional on `Store`). The SQLite store has them (migration 21,
|
|
404
|
+
one-way: back up the database before upgrading, since 0.1.7 and older tools cannot read a database 0.1.8 has opened); the in-memory store has them only through
|
|
405
|
+
`withMemorySignals(store)`. Without them `record` answers `false` and logs `chatwarden.signals_store_unsupported` once, and declaring kinds or feeds throws at
|
|
406
|
+
creation. The kit loads the signal code only for a store that has the methods.
|
|
407
|
+
- **Reads** (staff only, never to a player): `cw.signals.counts(subject, { windowDays?, kinds? })`, `kinds()`, `boosted(people)` and `forRecord(subject)`.
|
|
408
|
+
The `@chatwarden/http` routes read them for you and show a count only to a role that holds `history.read`.
|
|
409
|
+
|
|
410
|
+
## Appeals
|
|
411
|
+
|
|
412
|
+
Optional and off until you turn it on, `@experimental` until 0.2 and new in 0.1.9. A player who thinks a sanction was a mistake asks for a second look from
|
|
413
|
+
the notice they were sent. A moderator reads what they wrote and keeps the decision, makes it lighter or removes it, and the player gets a plain message with
|
|
414
|
+
the outcome. Appeals are not a second queue: in the hub they are a view of the Cases screen.
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
import { createChatwarden, type RawWho } from '@chatwarden/core';
|
|
418
|
+
import { openStore } from '@chatwarden/store-sqlite';
|
|
419
|
+
|
|
420
|
+
const cw = await createChatwarden({
|
|
421
|
+
store: openStore({ path: './chatwarden.db' }),
|
|
422
|
+
secret: process.env.CHATWARDEN_SECRET!,
|
|
423
|
+
platform: { identify: (ctx) => ctx as RawWho },
|
|
424
|
+
overrides: { appeals: { enabled: true, perPlayerPerWeek: 3 } },
|
|
425
|
+
});
|
|
426
|
+
|
|
427
|
+
// The player files from one of their own sanction notices. `who` is what your game knows about them.
|
|
428
|
+
const who: RawWho = { clientKey: 'a-client-key' };
|
|
429
|
+
const notice = cw.notices.pending(who).find((n) => n.kind === 'chat');
|
|
430
|
+
if (notice !== undefined) {
|
|
431
|
+
const filed = cw.appeals.file(who, { noticeId: notice.id, statement: 'It was a joke between friends, and we had stopped.' });
|
|
432
|
+
console.log(filed.ok ? 'sent' : filed.refused);
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
// A different moderator decides: uphold, reduce (with the lighter outcome in `to`) or revoke. The reason is private.
|
|
436
|
+
const waiting = cw.appeals.list({ status: 'open' }).items[0];
|
|
437
|
+
if (waiting !== undefined) {
|
|
438
|
+
const result = await cw.appeals.decide({
|
|
439
|
+
appealId: waiting.id,
|
|
440
|
+
outcome: 'reduce',
|
|
441
|
+
actor: 'second.moderator@example.com',
|
|
442
|
+
reason: 'A warning is enough for a first offence.',
|
|
443
|
+
to: { kind: 'warning', durationMs: null },
|
|
444
|
+
});
|
|
445
|
+
console.log(result.ok ? result.status : result.error);
|
|
446
|
+
}
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
- **Turning it on.** `overrides.appeals` takes `enabled` (default `false`), `perPlayerPerWeek` (1 to 20, default 3) and `allowSelfReview` (default `false`), or
|
|
450
|
+
the owner sets them in the hub (Settings, Advanced). With appeals off every appeal route answers as if it did not exist, a notice keeps the old
|
|
451
|
+
`appealUrl` link if you gave one, and no response body changes. `appeals.enabled: true` in the profile or `overrides` over a store with no appeal methods throws when the kit is created; the owner's saved setting never does: saving it on such a store is refused (`invalid_profile`, path `layer.appeals.enabled`), and one already stored leaves appeals off and warns `chatwarden.appeals_unsupported_store`.
|
|
452
|
+
- **What can be appealed.** A warning, a chat restriction, an area ban or a full ban that is in the player's record (the same 90-day rule "My record" uses), from
|
|
453
|
+
its notice. A report outcome, a note and the four message notices (below) cannot. There is one appeal for each sanction for as long as it is kept. A sanction
|
|
454
|
+
made lighter on appeal is a new sanction with its own notice, and can be appealed once.
|
|
455
|
+
- **The statement.** It is the one new free text a player writes: at most `APPEAL_STATEMENT_MAX` (1000) characters, refused when over and never cut. The kit
|
|
456
|
+
cleans it first (`normalizeStatement`: control, bidirectional, zero-width and other invisible characters and stray surrogates are removed, blank-line runs
|
|
457
|
+
collapse, the text is trimmed) and counts what is left in code points. It is kept in the appeal row and nowhere else: never in an event, a webhook, a
|
|
458
|
+
Discord post, a log line, an audit row or an AI prompt. Staff read it only through `cw.appeals.get`, which the staff routes audit, and the hub masks it
|
|
459
|
+
when it trips the term filter. It is cleared 90 days after the decision (`retention.appealStatementsMs`; 0 clears it at the decision) and the row is deleted
|
|
460
|
+
after 365 days (`retention.appealsMs`, never less than 90). An open appeal keeps its statement until it is decided.
|
|
461
|
+
- **Filing.** `cw.appeals.file(who, { noticeId, statement })` answers `{ ok: true, appeal }` or `{ ok: false, refused }`, with `refused` one of `off`,
|
|
462
|
+
`not_found` (one answer for a notice that is not theirs and one that does not exist), `not_appealable`, `statement_invalid`, `already_appealed` and `rate`
|
|
463
|
+
(with `retryAfterMs`), checked in that order. A refusal writes nothing. `cw.appeals.mine(who)` lists the player's own appeals, newest first. What a player
|
|
464
|
+
gets back is an id, the notice id, a status and two times: no staff ref, no reason and no sanction or person id.
|
|
465
|
+
- **Deciding.** `cw.appeals.decide({ appealId, outcome, actor, reason, to? })` is one transaction. `uphold` keeps the sanction. `revoke` lifts it and withdraws
|
|
466
|
+
its notice. `reduce` needs `to`: a lower kind, or the same kind and shorter (permanent is the longest), and the replacement keeps the original start time, so
|
|
467
|
+
the ladder's 90-day lookback does not restart. Each outcome tells the player through a notice of kind `appeal_upheld`, `appeal_reduced` or `appeal_revoked`
|
|
468
|
+
(`reduce` also sends the replacement's own notice). It answers `{ ok: true, status, replacementGroupId? }` or `{ ok: false, error }` with `error` one of
|
|
469
|
+
`not_found`, `already_decided` (a second call, or the loser of a race, writes nothing), `invalid`, `same_decider` and `gone`. An appeal whose sanction someone
|
|
470
|
+
else revoked while it was open is closed as `moot`: nobody ruled on it, the player is sent nothing more, and a decide on it answers `gone`.
|
|
471
|
+
- **One login per person.** The kit refuses `same_decider` when `actor` is the staff ref that made the original decision, unless `appeals.allowSelfReview` is on.
|
|
472
|
+
It compares staff refs, so a team that shares one login looks like a team of one and the rule cannot hold: give each moderator their own login and `actor`.
|
|
473
|
+
A sanction the kit gave by itself (an automatic timeout) has no human decider and any holder of the permission may decide its appeal. A team of one sets
|
|
474
|
+
`allowSelfReview`, or lowers who may decide with `permissions` in `@chatwarden/http`.
|
|
475
|
+
- **The mistake rate.** `cw.appeals.stats({ days })` (30, 90 or 365; 90 by default) gives, for each rule, the sanctions given, the appeals filed, how many were
|
|
476
|
+
revoked (`granted`), how many were reduced (`lightened`), a `rate` and a `band`. **A reduction is not a false positive**: it disputes how severe a sanction
|
|
477
|
+
was, not whether it was right, so it is counted as `lightened`, shown beside the rate and never inside it. `rate` is `granted` over `sanctions`, and is
|
|
478
|
+
`null` below `APPEAL_STATS_MIN_SANCTIONS` (10) sanctions. The band is `elevated` from `APPEAL_RATE_ELEVATED` (0.15) and `high` from `APPEAL_RATE_HIGH` (0.30). The
|
|
479
|
+
hub shows it only behind Settings, Advanced, "Mistakes by rule", never on a queue or a card.
|
|
480
|
+
- **What a decided appeal teaches the AI.** All of it is a no-op without `ai`. A reduce or a revoke marks the original decision reversed, so it stops being a
|
|
481
|
+
standard example. A revoke also keeps the decision's pseudonymised lines as one corrective example (the opposite sign: "a moderator acted on this, and a
|
|
482
|
+
second moderator decided on appeal that it was not a violation"). The stats of `cw.ai.stats()` change with it: **an AI false positive is a recommendation to
|
|
483
|
+
act where the moderator chose no action or a revoke corrected it; a reduce is not one.** Rules at the elevated or high band are given to the read as a caution
|
|
484
|
+
(the rule number and the band word, never a rate, a count or a person), outside the input hash. The statement never reaches the AI. This changes the prompt
|
|
485
|
+
(version 4): see "The AI (levels 1 and 2)" for what that costs once, on upgrade.
|
|
486
|
+
- **Events.** `appeal.created` and `appeal.decided` are announced after the commit, never for a refusal and never for a `moot` closure. Like `report.created`
|
|
487
|
+
they carry ids, codes and times, and never the statement, the reason or the player's handle. `@chatwarden/http` can send them as webhooks and
|
|
488
|
+
`@chatwarden/discord` posts them.
|
|
489
|
+
- **Your store needs the appeal methods.** The SQLite store has them (migration 22, which is one-way: back up the database before upgrading, since 0.1.8
|
|
490
|
+
and older tools cannot read a database 0.1.9 has opened); the in-memory store has them only through `withMemoryAppeals(store)`. For a store you wrote:
|
|
491
|
+
every appeal method is optional on `Store`. Also optional, and worth adding: `closeOrphanAppeals` (without it an appeal whose sanction rows retention removed
|
|
492
|
+
stays open and cannot be decided), the trailing `clearStatement` argument of `decideAppeal` and `closeAppealsForGroup` (without it a statement is cleared at
|
|
493
|
+
the next purge, not at the decision), and the second argument of `purgeNotices(before, unseen?)`, the ceiling for an unseen message notice (a store that
|
|
494
|
+
ignores it keeps an unseen appeal outcome or rename request until the player sees it).
|
|
495
|
+
|
|
496
|
+
## Names
|
|
497
|
+
|
|
498
|
+
Optional, `@experimental` until 0.2 and new in 0.1.9, except that `cw.names.check` has been here since 0.1.0 and keeps its contract. This part checks a name
|
|
499
|
+
more closely, can keep a blocked name as evidence, lets a moderator ask a player to choose a new name, and hides a name the word list flags in the hub.
|
|
500
|
+
|
|
501
|
+
```ts
|
|
502
|
+
import { createChatwarden, type RawWho } from '@chatwarden/core';
|
|
503
|
+
import { openStore } from '@chatwarden/store-sqlite';
|
|
504
|
+
|
|
505
|
+
const cw = await createChatwarden({
|
|
506
|
+
store: openStore({ path: './chatwarden.db' }),
|
|
507
|
+
secret: process.env.CHATWARDEN_SECRET!,
|
|
508
|
+
platform: { identify: (ctx) => ctx as RawWho },
|
|
509
|
+
overrides: { names: { profanity: true, keepBlocked: true, renames: true } },
|
|
510
|
+
});
|
|
511
|
+
|
|
512
|
+
// At sign-up: may this be a name? `who` is only used to tie kept evidence to a person; it never changes the answer.
|
|
513
|
+
const who: RawWho = { clientKey: 'a-client-key', accountId: 'acct-1042' };
|
|
514
|
+
const checked = cw.names.check('big_snerp_99', { who });
|
|
515
|
+
if (!checked.ok) console.log(checked.reason, checked.rule); // 'name_not_allowed' or 'name_profane', and the Community Rule
|
|
516
|
+
|
|
517
|
+
// A moderator asked for a new name. The game hears it, finds its player and sends them to its own rename screen.
|
|
518
|
+
cw.on('rename.required', (event) => {
|
|
519
|
+
for (const accountId of cw.people.accountIds(event.target)) console.log('rename screen for', accountId);
|
|
520
|
+
});
|
|
521
|
+
|
|
522
|
+
// At login: is the player still held at the rename screen? After they chose a new name, say so.
|
|
523
|
+
if (cw.names.pendingRename(who)) console.log('hold at the rename screen');
|
|
524
|
+
cw.names.renamed(who);
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
- **Settings.** `overrides.names` takes `profanity` (default `false`), `keepBlocked` (default `false`), `renames` (default `false`) and `maskInHub` (default
|
|
528
|
+
`true`), or the owner sets them in the hub (Settings, Advanced, Names).
|
|
529
|
+
- **The check.** `cw.names.check(text, opts?)` is synchronous, keeps no state and never echoes the name. The answer is `{ ok: true }` or
|
|
530
|
+
`{ ok: false, reason, rule }`, with `reason` `'name_not_allowed'` (the matcher's name rules) or `'name_profane'` (the profanity filter, only with
|
|
531
|
+
`names.profanity`, on the name and on the name with underscores and digits read as spaces). A matcher or filter that throws lets the name through. `name_profane` is
|
|
532
|
+
a new value of `reason`: a `switch` that ends in `assertNever` will not compile until it handles it, though a kit never sends it with `names.profanity` off.
|
|
533
|
+
`cw.names.flagged(text)` is the staff-side read that asks only the matcher and stores nothing.
|
|
534
|
+
- **Evidence, only if you opt in.** With `names.keepBlocked` a blocked name is kept with the term it hit and, when `who` finds one, the person: at most 5 an hour
|
|
535
|
+
per person and 200 an hour overall (in memory, per process), after which the check still answers and keeps nothing more. An allowed name is never stored and a
|
|
536
|
+
name is never logged. Kept names are deleted after 30 days (`retention.blockedNamesMs`) and read by staff with `cw.blocked.names({ days })`. They need a store
|
|
537
|
+
with the blocked-name methods (SQLite, or `withMemoryNames(store)`).
|
|
538
|
+
- **Asking for a new name.** `cw.names.requireRename({ subject, actor, reason, rule? })` is for staff and needs `names.renames`. It writes one notice of kind
|
|
539
|
+
`rename_required` (it names no name, no reason and no excerpt; it is not a sanction, is not on "My record" and needs no acknowledgement) and then emits
|
|
540
|
+
`rename.required`. It answers `{ ok: true, noticeId }` or `{ ok: false, error }` with `error` `off`, `not_found`, `pending` (a request is already waiting) or
|
|
541
|
+
`invalid`. `cw.names.renamesEnabled()` says whether it can work now (the setting is on and the store can release a rename), and `cw.names.renamesOf(subject)`
|
|
542
|
+
lists a person's requests for the hub.
|
|
543
|
+
- **A game must act on `rename.required` and call `renamed`.** The kit cannot make a game rename anyone. It never learns the new name and never checks that one was
|
|
544
|
+
chosen. Listen for the event (or take it by webhook with `includeAccounts`, see `@chatwarden/http`), find the player with `cw.people.accountIds(event.target)`
|
|
545
|
+
(the account ids you passed as `RawWho.accountId`; a guest has none; server side only), hold them with `cw.names.pendingRename(who)` at login, and call
|
|
546
|
+
`cw.names.renamed(who)` when they have a new name. That withdraws the notice and answers `true`. A game that ignores the event leaves a notice nobody acts on,
|
|
547
|
+
and a player stays pending until the game calls `renamed`.
|
|
548
|
+
- **Hiding names in the hub is on by default.** This is the one default-on display change of 0.1.9. With `names.maskInHub` (default `true`), a handle the matcher
|
|
549
|
+
flags is shown in the hub as "Blocked words, hidden" until a moderator chooses Show, in queue rows, the case, the Person page, the transcript, the command bar and
|
|
550
|
+
the appeals. It changes only what the hub shows, only for flagged handles. To show names as before, set `overrides.names.maskInHub: false` or switch it off in
|
|
551
|
+
Settings, Advanced, Names. `@chatwarden/http` marks a flagged handle with `handleFlagged` in its staff bodies.
|
|
552
|
+
- **Your store.** The blocked-name methods are optional on `Store`. So is `withdrawNotice(id, at)`, which releases a rename notice (it has no sanction group): a
|
|
553
|
+
store without it cannot release a rename, `renamesEnabled()` is `false` and `requireRename` answers `off`. The SQLite store has all of them; the in-memory store
|
|
554
|
+
has `withdrawNotice` built in and the blocked-name methods through `withMemoryNames(store)`.
|
|
555
|
+
|
|
556
|
+
## Upgrading to 0.1.9
|
|
557
|
+
|
|
558
|
+
- **From 0.1.8.** SQLite migration 22 is one-way: a database it has run on cannot be opened by 0.1.8 or older. Back it up first.
|
|
559
|
+
- **Unions are wider.** `NoticeKind` gains `rename_required`, `appeal_upheld`, `appeal_reduced` and `appeal_revoked`; `NameReason` gains `name_profane`;
|
|
560
|
+
`AUDIT_ACTIONS` gains `appeal.view`, `appeal.decide` and `name.rename_required` and `AUDIT_TARGET_TYPES` gains `appeal`; `KIT_EVENT_TYPES` gains
|
|
561
|
+
`appeal.created`, `appeal.decided` and `rename.required`. Code with a `switch` that ends in `assertNever` will not compile until it handles them, though none
|
|
562
|
+
of the new values is sent until you turn the feature on.
|
|
563
|
+
- **Types you build by hand.** `RetentionPolicy` gains `appealStatementsMs`, `appealsMs` and `blockedNamesMs`; `PurgeResult` gains `appeals`, `appealStatements`,
|
|
564
|
+
`blockedNames` and `appealsClosed`; `ResolvedProfile` gains `appeals` and `names`; `POLICY_SECTIONS` gains `appeals` and `names`; `AiOutcomeRow` gains `corrective`.
|
|
565
|
+
- **A false positive means something different.** A reduction on appeal is not a false positive. `AppealRuleStats.granted` counts revokes only, and the AI's
|
|
566
|
+
`falsePositives` counts a recommendation to act that the moderator dismissed, or that a revoke corrected.
|
|
567
|
+
- **The AI re-reads once.** The prompt version is now 4, with appeals on or off: every stored read is marked stale and read again, once per open report. See "The AI
|
|
568
|
+
(levels 1 and 2)".
|
|
569
|
+
- **A custom `Store`.** Everything new is optional and its absence turns the feature off (appeals need their methods, renames need `withdrawNotice`, kept names need the
|
|
570
|
+
blocked-name methods). `purgeNotices` has an optional second argument.
|
|
571
|
+
|
|
279
572
|
## The AI (levels 1 and 2)
|
|
280
573
|
|
|
281
574
|
Optional help for the moderator, `@experimental` until 0.2 and new in 0.1.7. With an adapter, the kit reads each new report after the player's
|
|
@@ -309,7 +602,9 @@ console.log(cw.ai.status()); // { available: true, level: 0, maxLevel: 2, state:
|
|
|
309
602
|
(`AI_MAX_PREFILL_MS`), and a suggestion to uphold or note needs a cited line by the reported person.
|
|
310
603
|
- **What leaves your server.** Only the chosen lines of the report with the speakers replaced by `P1`, `P2`, ..., the reporter's reason and
|
|
311
604
|
note (redacted), your Community Rules and the standard. Flags, mutes and report counts are never sent, nor any id, handle, IP, hash, room or
|
|
312
|
-
tag.
|
|
605
|
+
tag. The one exception is the signal feed `feeds.ai` (`profile.signals`, off unless you set it): the counts you chose about the reported player
|
|
606
|
+
only are sent as one last row, a label, a number of players and a number of days, and the read records what it was shown (shown to moderators as
|
|
607
|
+
"Context included: N signal counts"). The prompt version is 4 for everyone (3 in 0.1.8), whether or not you use signals or appeals: the stable part of the prompt gained a short paragraph about appeal cautions and corrective examples, so it changes the input hash, and after upgrading from 0.1.8 every stored read is marked stale and read again, once per open report, the first time its case is opened or when the background sweep reaches it. Those reads spend your daily call and money caps, and your provider's prompt cache starts cold. A line the word filter blocked is sent as typed unless you set `blockedLines: 'mask'`: the model needs the words to judge intent.
|
|
313
608
|
- **What it costs.** `dailyBudgetMicros` (default $1.00 a UTC day) is set in code and a hub cannot raise it. The owner also sets a ceiling on
|
|
314
609
|
calls a day (`profile.ai.dailyCalls`, default 5 000), so an adapter that reports no cost still cannot run unbounded. There are at most 30 calls
|
|
315
610
|
a minute and 2 at once, a hard deadline per call (`timeoutMs`) and a breaker that opens after repeated failures. At a limit, reads pause. A call that a shutdown aborts books nothing, so a restart loop around a slow provider can under-count the day's money; the call ceiling still bounds it.
|
|
@@ -389,7 +684,7 @@ in a browser.
|
|
|
389
684
|
| `gate` | `(roomId, subject) => boolean`: who may chat. False refuses the line with `'gate'`. |
|
|
390
685
|
| `onReport` | Told once for each stored report. It carries subject ids and the evidence: staff channels only. |
|
|
391
686
|
| `onAutoRestrict` | Told when a blocked line earned an automatic timeout. The same moment is also the `auto.restricted` event. |
|
|
392
|
-
| `retention` | How long rows are kept and how often the purge runs (every 6 hours by default), or `false` to run `purge()` yourself. Defaults: reports 90 days, strikes 30, notices 90, audit 365. Floors apply. |
|
|
687
|
+
| `retention` | How long rows are kept and how often the purge runs (every 6 hours by default), or `false` to run `purge()` yourself. Defaults: reports 90 days, strikes 30, notices 90, audit 365, signals 90 (`signalsMs`, never less than 14), appeal statements 90 (`appealStatementsMs`, may be 0), appeals 365 (`appealsMs`, never less than 90), kept blocked names 30 (`blockedNamesMs`, may be 0). Floors apply. |
|
|
393
688
|
| `profile` | `'relaxed'`, `'standard'` (default), `'strict'`, or your own profile from `defineProfile`. |
|
|
394
689
|
| `overrides` | Changes to the profile, merged onto it (`{ profanity: { mode: 'allow' } }`). A list you give replaces the preset's list. |
|
|
395
690
|
| `limits` | The numbers the kit enforces: line length and rate, strikes and timeouts, report limits. Each must be a whole number above 0. |
|
|
@@ -397,6 +692,7 @@ in a browser.
|
|
|
397
692
|
| `rules` | The numbered Community Rules, from `defineRules`. Defaults to the preset's starter set. |
|
|
398
693
|
| `autoRestrictRule` | The rule number the automatic slur filter cites (default 1). Must be an active rule. |
|
|
399
694
|
| `ai` | `{ adapter, maxLevel?, dailyBudgetMicros?, ... }`: turns on AI reads (levels 1 and 2). Off without it. See "The AI (levels 1 and 2)" below. |
|
|
695
|
+
| `signals` | `{ accountAgeDays? }`: the one hook the profile cannot hold (how old a player's account is, for the new-account guard). The kinds, guards and feeds are in `profile.signals`. Needs a store with the signal methods (SQLite; `withMemorySignals(store)` for the in-memory store). `@experimental`. |
|
|
400
696
|
|
|
401
697
|
Bad options throw at creation (`ProfileError`, `RangeError`), before the store is touched.
|
|
402
698
|
|
|
@@ -417,6 +713,9 @@ Bad options throw at creation (`ProfileError`, `RangeError`), before the store i
|
|
|
417
713
|
- **Chat text is kept in two places only.** An evidence buffer in memory (the last 100 lines or 15 minutes of each room), and the
|
|
418
714
|
excerpt copied into a report or a notice when one is made. Reports and notices are deleted by retention. A player's notice
|
|
419
715
|
quotes only their own lines.
|
|
716
|
+
- **Two more kinds of player text, both opt-in.** An appeal statement (at most 1000 characters, only when appeals are on) is kept in the appeal row and cleared 90 days after
|
|
717
|
+
the decision. A blocked name (only with `names.keepBlocked`) is kept for 30 days. Neither is ever logged, sent in an event, a webhook or a Discord post, or shown to
|
|
718
|
+
another player, and a statement never reaches the AI.
|
|
420
719
|
- **Moderators' words stay with moderators.** A decision's reason, a gap note, a reporter's note and a moderator's identity are
|
|
421
720
|
never shown to a player.
|
|
422
721
|
- **The kit enforces nothing about who may call it.** It has no login. Put your own authentication in front of every staff read,
|
package/dist/src/ai/case.d.ts
CHANGED
|
@@ -2,7 +2,8 @@ import type { DocumentPolicy } from '../documents.js';
|
|
|
2
2
|
import type { ReportReason } from '../reporting.js';
|
|
3
3
|
import type { ReportRecord } from '../types.js';
|
|
4
4
|
import type { ChosenLines } from './lines.js';
|
|
5
|
-
import type {
|
|
5
|
+
import type { BuildAIInputArgs } from './prompt.js';
|
|
6
|
+
import type { AIExampleInput, AIReadInput, AISignal } from './types.js';
|
|
6
7
|
/** A report ready to be read (or to be compared with a stored read). */
|
|
7
8
|
export interface Prepared {
|
|
8
9
|
/** The input without casebook examples: what the hash is of. */
|
|
@@ -22,8 +23,8 @@ export interface Prepared {
|
|
|
22
23
|
idOf: ReadonlyMap<string, string>;
|
|
23
24
|
/** The real ids of the lines the reported person wrote (among the chosen). */
|
|
24
25
|
ownLineIds: ReadonlySet<string>;
|
|
25
|
-
/** The same input with casebook examples in it (at most two are used). The hash does not change. */
|
|
26
|
-
build(examples: readonly AIExampleInput[]): AIReadInput;
|
|
26
|
+
/** The same input with casebook examples and the signal counts about P1 in it (at most two examples are used). The hash does not change. */
|
|
27
|
+
build(examples: readonly AIExampleInput[], signals?: readonly AISignal[], cautions?: BuildAIInputArgs['cautions']): AIReadInput;
|
|
27
28
|
}
|
|
28
29
|
export interface PrepareArgs {
|
|
29
30
|
report: ReportRecord;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"case.d.ts","sourceRoot":"","sources":["../../../src/ai/case.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"case.d.ts","sourceRoot":"","sources":["../../../src/ai/case.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMxE,wEAAwE;AACxE,MAAM,WAAW,QAAQ;IACvB,gEAAgE;IAChE,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,SAAS,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,2EAA2E;IAC3E,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,uDAAuD;IACvD,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B,oEAAoE;IACpE,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,8EAA8E;IAC9E,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,4IAA4I;IAC5I,KAAK,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,EAAE,QAAQ,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG,WAAW,CAAC;CACjI;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,CA2BvD"}
|
package/dist/src/ai/case.js
CHANGED
|
@@ -8,7 +8,7 @@ export function prepareCase(args) {
|
|
|
8
8
|
const chosen = chooseLines(report, { mask: args.mask });
|
|
9
9
|
const reasonId = report.reportedReason ?? null;
|
|
10
10
|
const reason = reasonId === null ? null : { id: reasonId, label: reasonLabel(args.reasons, reasonId) ?? reasonId };
|
|
11
|
-
const build = (examples) => buildAIInput({ policy, reason, chosen, examples });
|
|
11
|
+
const build = (examples, signals, cautions) => buildAIInput({ policy, reason, chosen, examples, ...(signals === undefined ? {} : { signals }), ...(cautions === undefined ? {} : { cautions }) });
|
|
12
12
|
const input = build([]);
|
|
13
13
|
// The tripwire reads what the players typed (the raw text), whatever is sent.
|
|
14
14
|
const rawOf = new Map(report.excerpt.map((l) => [l.lineId, l.raw]));
|
package/dist/src/ai/case.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"case.js","sourceRoot":"","sources":["../../../src/ai/case.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"case.js","sourceRoot":"","sources":["../../../src/ai/case.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAwC3C,MAAM,UAAU,WAAW,CAAC,IAAiB;IAC3C,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,IAAI,IAAI,CAAC;IAC/C,MAAM,MAAM,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,QAAQ,EAAE,CAAC;IACnH,MAAM,KAAK,GAAG,CAAC,QAAmC,EAAE,OAA6B,EAAE,QAAuC,EAAe,EAAE,CACzI,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IACrJ,MAAM,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;IAExB,8EAA8E;IAC9E,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,SAAS,GACb,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE9E,OAAO;QACL,KAAK;QACL,MAAM;QACN,IAAI,EAAE,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC;QACtC,SAAS;QACT,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7C,WAAW,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACtD,OAAO,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC5E,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,UAAU,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAClF,KAAK;KACN,CAAC;AACJ,CAAC"}
|
package/dist/src/ai/hash.d.ts
CHANGED
|
@@ -4,7 +4,9 @@ import type { AIReadInput } from './types.js';
|
|
|
4
4
|
* policy text that changes meaning), the case's own rendered inputs and the adapter id, in that order. The casebook examples are
|
|
5
5
|
* NOT part of it: a growing casebook must not make every stored read look stale, and the read records the ids of the examples it
|
|
6
6
|
* used instead (`AIStoredRead.exampleIds`). The `example:` rows are therefore left out of the variable part before hashing; no
|
|
7
|
-
* other row of the data block can begin that way (a chat line starts `L<n> `, the rest are fixed keys). The
|
|
7
|
+
* other row of the data block can begin that way (a chat line starts `L<n> `, the rest are fixed keys). The same goes for the signal
|
|
8
|
+
* counts row (`Context about P1, ...`): counts move all day, so keying the hash on them would re-read every open report each time
|
|
9
|
+
* someone muted someone; the row is a snapshot taken when the read is made, and so is the row of appeal cautions (`Caution on appeal history: ...`). The fields are framed as a
|
|
8
10
|
* JSON array, so no part can slide into the next. Object key order in `input` cannot matter: only those values are read. A hex
|
|
9
11
|
* string of 64 characters.
|
|
10
12
|
* @experimental
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/ai/hash.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../../src/ai/hash.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMvE"}
|
package/dist/src/ai/hash.js
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
import { sha256Hex } from '../crypto.js';
|
|
2
|
+
import { CAUTIONS_ROW, SIGNALS_ROW } from './prompt.js';
|
|
2
3
|
/**
|
|
3
4
|
* The input hash a stored read is valid for (design section 6): sha256 over the prompt version, the rendered stable prefix (the
|
|
4
5
|
* policy text that changes meaning), the case's own rendered inputs and the adapter id, in that order. The casebook examples are
|
|
5
6
|
* NOT part of it: a growing casebook must not make every stored read look stale, and the read records the ids of the examples it
|
|
6
7
|
* used instead (`AIStoredRead.exampleIds`). The `example:` rows are therefore left out of the variable part before hashing; no
|
|
7
|
-
* other row of the data block can begin that way (a chat line starts `L<n> `, the rest are fixed keys). The
|
|
8
|
+
* other row of the data block can begin that way (a chat line starts `L<n> `, the rest are fixed keys). The same goes for the signal
|
|
9
|
+
* counts row (`Context about P1, ...`): counts move all day, so keying the hash on them would re-read every open report each time
|
|
10
|
+
* someone muted someone; the row is a snapshot taken when the read is made, and so is the row of appeal cautions (`Caution on appeal history: ...`). The fields are framed as a
|
|
8
11
|
* JSON array, so no part can slide into the next. Object key order in `input` cannot matter: only those values are read. A hex
|
|
9
12
|
* string of 64 characters.
|
|
10
13
|
* @experimental
|
|
@@ -12,7 +15,7 @@ import { sha256Hex } from '../crypto.js';
|
|
|
12
15
|
export function inputHash(input, adapterId) {
|
|
13
16
|
const caseInputs = input.prompt.variable
|
|
14
17
|
.split('\n')
|
|
15
|
-
.filter((row) => !row.startsWith('example: '))
|
|
18
|
+
.filter((row) => !row.startsWith('example: ') && !row.startsWith(SIGNALS_ROW) && !row.startsWith(CAUTIONS_ROW))
|
|
16
19
|
.join('\n');
|
|
17
20
|
return sha256Hex(JSON.stringify([input.promptVersion, input.prompt.stable, caseInputs, adapterId]));
|
|
18
21
|
}
|
package/dist/src/ai/hash.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../../src/ai/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../../src/ai/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,KAAkB,EAAE,SAAiB;IAC7D,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ;SACrC,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;SAC9G,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;AACtG,CAAC"}
|
package/dist/src/ai/prompt.d.ts
CHANGED
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import type { DocumentPolicy } from '../documents.js';
|
|
2
2
|
import type { ChosenLines } from './lines.js';
|
|
3
|
-
import type { AIExampleInput, AIReadInput } from './types.js';
|
|
3
|
+
import type { AIExampleInput, AIReadInput, AISignal } from './types.js';
|
|
4
4
|
/**
|
|
5
5
|
* Same as {@link AI_PROMPT_VERSION}.
|
|
6
6
|
* @experimental
|
|
7
7
|
*/
|
|
8
|
-
export declare const PROMPT_VERSION =
|
|
8
|
+
export declare const PROMPT_VERSION = 4;
|
|
9
|
+
/** How the row of appeal cautions begins. The input hash leaves every row that begins this way out. */
|
|
10
|
+
export declare const CAUTIONS_ROW = "Caution on appeal history: ";
|
|
11
|
+
/** How the row of signal counts about P1 begins. The input hash leaves every row that begins this way out. */
|
|
12
|
+
export declare const SIGNALS_ROW = "Context about P1, not evidence: ";
|
|
9
13
|
/**
|
|
10
14
|
* The part of the policy the model needs, as plain text: the active Community Rules in number order, the conduct-level meanings
|
|
11
15
|
* with their examples, and `aiContext`. No outcomes, no ladder, no ids, no times, so editing the ladder never changes it. Retired
|
|
@@ -33,6 +37,13 @@ export interface BuildAIInputArgs {
|
|
|
33
37
|
chosen: ChosenLines;
|
|
34
38
|
/** Casebook examples, already pseudonymised; at most two are used (see {@link usedExampleIds}). */
|
|
35
39
|
examples?: readonly AIExampleInput[];
|
|
40
|
+
/** Counts of signals about P1 (`feeds.ai`), a snapshot: one row after the lines, nothing for none. */
|
|
41
|
+
signals?: readonly AISignal[];
|
|
42
|
+
/** The rules with an elevated or high revoke-on-appeal rate, a snapshot: one row after the signal counts, nothing for none. Anything else is dropped. */
|
|
43
|
+
cautions?: ReadonlyArray<{
|
|
44
|
+
rule: number;
|
|
45
|
+
band: 'elevated' | 'high';
|
|
46
|
+
}>;
|
|
36
47
|
}
|
|
37
48
|
/**
|
|
38
49
|
* Render everything a provider needs for one read: the structured facts, and `prompt.stable` / `prompt.variable` / `prompt.schema`
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/ai/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,OAAO,KAAK,EAAa,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;
|
|
1
|
+
{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/ai/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,OAAO,KAAK,EAAa,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAOnF;;;GAGG;AACH,eAAO,MAAM,cAAc,IAAoB,CAAC;AAyChD,uGAAuG;AACvG,eAAO,MAAM,YAAY,gCAAgC,CAAC;AAK1D,8GAA8G;AAC9G,eAAO,MAAM,WAAW,qCAAqC,CAAC;AAU9D;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAkB3D;AA+DD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,EAAE,CAE5E;AAED,6HAA6H;AAC7H,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,+EAA+E;IAC/E,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7C,sGAAsG;IACtG,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,CAAC;IACpB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,sGAAsG;IACtG,OAAO,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC9B,yJAAyJ;IACzJ,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CACvE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CAgDhE"}
|