@chatwarden/core 0.1.10 → 0.1.12

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.
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4BAA4B;AA+gB5B,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAA4B,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC,CAAC;AA2KvH,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AA+C3C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4BAA4B;AAkhB5B,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAA4B,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC,CAAC;AA2KvH,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AA+C3C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chatwarden/core",
3
- "version": "0.1.10",
3
+ "version": "0.1.12",
4
4
  "private": false,
5
5
  "description": "Chat moderation engine for games: reports, warnings, timeouts and bans, a moderator queue and player notices. No sockets, HTTP or disk.",
6
6
  "license": "Apache-2.0",
@@ -43,7 +43,7 @@
43
43
  "prepack": "tsc -b"
44
44
  },
45
45
  "devDependencies": {
46
- "@chatwarden/store-memory": "0.1.10"
46
+ "@chatwarden/store-memory": "0.1.12"
47
47
  },
48
48
  "publishConfig": {
49
49
  "access": "public"
package/src/audit.ts CHANGED
@@ -20,6 +20,13 @@ export type Role = (typeof ROLES)[number];
20
20
  * The three appeal and name actions (0.1.9): `appeal.view` is a staff read of the inbox, one appeal or the numbers (its target is the
21
21
  * `appeal`, or none for the list and the numbers); `appeal.decide` points at the `appeal` decided and needs it; `name.rename_required`
22
22
  * points at the `person` asked to rename and needs it. None of them carries a detail: a statement, a reason or a name never reaches the trail.
23
+ *
24
+ * The community-list actions (0.1.11): `term.share` is a moderator offering one of the adopter's own terms to the shared list (its target is the
25
+ * `term` id, never the word) and `community.apply` is an owner applying a release of the shared list (its target is the `release` version, such as
26
+ * `2026.12.0`). Neither carries a detail.
27
+ *
28
+ * `term.report` (0.1.11, appended last) is a moderator reporting a problem with a term from the shared list; it targets the `term` id, never the word,
29
+ * and carries no detail. It is a name of its own, so a report is never read as an offer.
23
30
  */
24
31
  export const AUDIT_ACTIONS = [
25
32
  'report.view',
@@ -51,6 +58,9 @@ export const AUDIT_ACTIONS = [
51
58
  'appeal.view',
52
59
  'appeal.decide',
53
60
  'name.rename_required',
61
+ 'term.share',
62
+ 'community.apply',
63
+ 'term.report',
54
64
  ] as const;
55
65
  export type AuditAction = (typeof AUDIT_ACTIONS)[number];
56
66
 
@@ -82,15 +92,15 @@ const AI_ACTOR_PREFIX = 'ai:';
82
92
  /** The actions whose row carries an {@link AuditDetail}, and the only ones that may. */
83
93
  const DETAIL_ACTIONS: readonly string[] = ['policy.update', 'policy.reset'];
84
94
 
85
- /** What an entry points at: a report id, a sanction group id, a person (a staff ref), a term id, an exception id, a saved reason id or an appeal id. */
86
- export const AUDIT_TARGET_TYPES = ['report', 'sanction', 'person', 'term', 'exception', 'reason', 'appeal'] as const;
95
+ /** What an entry points at: a report id, a sanction group id, a person (a staff ref), a term id, an exception id, a saved reason id, an appeal id or a release version. */
96
+ export const AUDIT_TARGET_TYPES = ['report', 'sanction', 'person', 'term', 'exception', 'reason', 'appeal', 'release'] as const;
87
97
  export type AuditTargetType = (typeof AUDIT_TARGET_TYPES)[number];
88
98
 
89
99
  export interface AuditTarget {
90
100
  type: AuditTargetType;
91
101
  /**
92
102
  * An id: 1..64 characters of `A-Z a-z 0-9 _ . : -`. It holds ids only (a report id, a sanction group id, a
93
- * subject id, a term id), never text: pass the id of a term, not the term.
103
+ * subject id, a term id, a release version such as `2026.12.0`), never text: pass the id of a term, not the term.
94
104
  */
95
105
  ref: string;
96
106
  }
package/src/chatwarden.ts CHANGED
@@ -40,11 +40,13 @@ import { NoticeService } from './notices.js';
40
40
  import type { PlayerNotice } from './notices.js';
41
41
  import { ReportService } from './reports.js';
42
42
  import type { ReportCounts, ReportDetailInput, ReportDetailResult, ReportInput, ReportResult } from './reports.js';
43
+ import { checkLinkRow, hasLinkMethods, isLinkSystem, isLinkValue, linkLimit } from './links.js';
44
+ import type { LinkRow, LinkSystem } from './links.js';
43
45
  import { checkRetentionFloors, purge, RETENTION_DEFAULTS } from './retention.js';
44
46
  import type { PurgeResult, RetentionPolicy } from './retention.js';
45
47
  import { defineRules, parseRuleRef, starterRules } from './rules.js';
46
48
  import type { CommunityRules, RuleRef } from './rules.js';
47
- import { applySanction, SanctionIndex } from './sanctions.js';
49
+ import { applySanction, normalizeRefCode, SanctionIndex } from './sanctions.js';
48
50
  import type { SanctionInput } from './sanctions.js';
49
51
  import { StrikeService } from './strikes.js';
50
52
  import {
@@ -53,6 +55,7 @@ import {
53
55
  blockedNameItems,
54
56
  listSanctionGroups,
55
57
  reporterRecord,
58
+ sanctionByRef,
56
59
  sanctionsOfPerson,
57
60
  } from './staffViews.js';
58
61
  import { reporterAccuracyFor } from './reporterAccuracy.js';
@@ -61,6 +64,7 @@ import type {
61
64
  BlockedDays,
62
65
  BlockedItem,
63
66
  BlockedNameItem,
67
+ PersonSanctionView,
64
68
  ReporterRecord,
65
69
  SanctionGroupView,
66
70
  SanctionListInput,
@@ -497,6 +501,15 @@ export interface Chatwarden {
497
501
  * unknown source. Carries subject ids and staff-only text: never send to a player.
498
502
  */
499
503
  list(q?: SanctionListInput): SanctionPage;
504
+ /**
505
+ * One group's staff view, with its canonical `person`, by the player-quotable reference code (`M-` plus five characters; case and
506
+ * surrounding spaces are ignored, and a bare five characters is read as `M-` plus them). Null for a code nobody holds, a malformed one
507
+ * or one with an ambiguous letter (never throws for a string; a non-string is a `TypeError`). Revoked and ended groups are found: the
508
+ * code never changes. Built from the group's subject row only (never an IP row). Synchronous. Carries staff-only text (reason, actor):
509
+ * never send to a player. A store without `sanctionGroupByRef` is read through its newest 1 000 groups.
510
+ * @experimental
511
+ */
512
+ byRef(refCode: string): PersonSanctionView | null;
500
513
  };
501
514
  /**
502
515
  * Subscribe to what happens in the kit: `'report.created'`, `'report.closed'`, `'sanction.applied'`,
@@ -555,6 +568,24 @@ export interface Chatwarden {
555
568
  /** A person's rename requests, newest first, at most 20: `{ at, pending }` each. No reason, actor, rule or name. Staff only: never send to a player. @experimental */
556
569
  renamesOf(subject: SubjectId): Array<{ at: number; pending: boolean }>;
557
570
  };
571
+ /**
572
+ * "This kit id is that outside id": a small table the Coop and EOS adapters keep their links in (a report sent to Coop, a sanction pushed
573
+ * to EOS, an EOS report already filed, a polling cursor). Rows are ids and one short state word, never text. Purged with `retention.reportsMs`.
574
+ * @experimental
575
+ */
576
+ links: {
577
+ /** True when the store implements the link methods. An adapter that needs links throws `RangeError` at construction when false. */
578
+ readonly supported: boolean;
579
+ /** The row for `(system, ref)`, a copy, or null (also for a value `put` would refuse, and for a store without links). Never throws. */
580
+ get(system: LinkSystem, ref: string): LinkRow | null;
581
+ /**
582
+ * Insert or replace the row for `(system, ref)`. Throws `RangeError` for a value outside the shapes (the message names the field, never the
583
+ * value) and a plain `Error` for a store without links. Only the five fields are stored.
584
+ */
585
+ put(row: LinkRow): void;
586
+ /** The system's rows, oldest `at` first and then `ref`, only this state when given, at most `limit` (1..500, default 100). Empty for a store without links. */
587
+ list(system: LinkSystem, q?: { state?: string; limit?: number }): LinkRow[];
588
+ };
558
589
  /**
559
590
  * The AI read and recommend service. Always present: without an `ai` option (or at level 0) it answers as if there were no AI. A
560
591
  * read is made after the report is stored and never delays the player's ack; a failing, slow or refusing provider changes nothing
@@ -1408,6 +1439,10 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
1408
1439
  },
1409
1440
  forPerson: (subject) => sanctionsOfPerson(store, subjects, subject, clock.now()),
1410
1441
  list: (q) => listSanctionGroups(store, subjects, q ?? {}, clock.now()),
1442
+ byRef: (refCode) => {
1443
+ const code = normalizeRefCode(refCode);
1444
+ return code === null ? null : sanctionByRef(store, subjects, code, clock.now());
1445
+ },
1411
1446
  },
1412
1447
  on: bus.on,
1413
1448
  names: {
@@ -1419,6 +1454,24 @@ export async function createChatwarden(opts: ChatwardenOptions): Promise<Chatwar
1419
1454
  renamesEnabled: () => nameService.renamesEnabled(),
1420
1455
  renamesOf: (subject) => nameService.renamesOf(subject),
1421
1456
  },
1457
+ links: {
1458
+ supported: hasLinkMethods(store),
1459
+ get: (system, ref) => {
1460
+ if (!hasLinkMethods(store) || !isLinkSystem(system) || !isLinkValue(ref)) return null;
1461
+ return store.getLink?.(system, ref) ?? null;
1462
+ },
1463
+ put: (row) => {
1464
+ checkLinkRow(row);
1465
+ if (!hasLinkMethods(store)) throw new Error('chatwarden: links are not supported by this store');
1466
+ const { system, ref, external, state, at } = row;
1467
+ store.putLink?.({ system, ref, external, state, at });
1468
+ },
1469
+ list: (system, q) => {
1470
+ if (!hasLinkMethods(store) || !isLinkSystem(system)) return [];
1471
+ const state = q?.state;
1472
+ return store.listLinks?.(system, { ...(typeof state === 'string' ? { state } : {}), limit: linkLimit(q?.limit) }) ?? [];
1473
+ },
1474
+ },
1422
1475
  rules,
1423
1476
  get profile() {
1424
1477
  return policy.profileNow();
package/src/index.ts CHANGED
@@ -1,4 +1,4 @@
1
- export const VERSION = '0.1.10';
1
+ export const VERSION = '0.1.12';
2
2
 
3
3
  export type {
4
4
  Clock,
@@ -92,6 +92,7 @@ export {
92
92
  MAX_SANCTION_DURATION_MS,
93
93
  SANCTION_KINDS,
94
94
  SanctionError,
95
+ normalizeRefCode,
95
96
  SANCTION_SOURCES,
96
97
  SanctionIndex,
97
98
  validateSanctionInput,
@@ -330,6 +331,8 @@ export type { PaceReason, PaceSettings, ResolvedPace } from './pace.js';
330
331
  // Appeals and names settings (@experimental): off until set (names masking in the hub is the one default-on setting).
331
332
  export { APPEAL_OUTCOMES, APPEAL_RATE_ELEVATED, APPEAL_RATE_HIGH, APPEAL_STATEMENT_MAX, APPEAL_STATS_MIN_SANCTIONS, normalizeStatement, resolveAppeals, SANCTION_KIND_ORDER, statementLength } from './appeals.js';
332
333
  export type { AppealDecideResult, AppealDecision, AppealDetail, AppealFileResult, AppealOutcome, AppealPage, AppealRuleStats, AppealStats, AppealSummary, AppealRefusal, AppealSettings, AppealStatus, PlayerAppeal, ResolvedAppeals } from './appeals.js';
334
+ export { LINK_SYSTEMS } from './links.js';
335
+ export type { LinkRow, LinkSystem } from './links.js';
333
336
  export { resolveNames } from './names.js';
334
337
  export type { NameCheckResult, NameReason, NameSettings, ResolvedNames } from './names.js';
335
338
  // Signals (@experimental): kinds a game declares, the guards, and the feeds that say where counts may be read.
package/src/links.ts ADDED
@@ -0,0 +1,80 @@
1
+ // `cw.links` (K5 design 5.1): "this kit id is that outside id", one small table for the outside-system adapters (Coop jobs, EOS sanctions,
2
+ // EOS report keys and one polling cursor). Rows are ids and one short state word, never text: no chat line, handle, reason or outside
3
+ // account id is written here, and a check pins the value shapes.
4
+
5
+ /** The systems a link can belong to: a closed list. */
6
+ export const LINK_SYSTEMS = ['coop-report', 'eos-sanction', 'eos-report', 'eos-cursor'] as const;
7
+ export type LinkSystem = (typeof LINK_SYSTEMS)[number];
8
+
9
+ /**
10
+ * One link row.
11
+ * @experimental
12
+ */
13
+ export interface LinkRow {
14
+ system: LinkSystem;
15
+ /** A kit id or a key derived from outside data (never an outside account id): 1..128 characters of A-Z a-z 0-9 _ . : # -. */
16
+ ref: string;
17
+ /** The outside system's id for it (a Coop report uuid, an EOS referenceId, an ISO cursor): 1..128 characters of the same set. */
18
+ external: string;
19
+ /** One short word: 'sent', 'decided', 'active', 'removed', 'filed', 'skipped'. 1..32 characters of a-z _ . */
20
+ state: string;
21
+ /** Epoch ms, from the kit's clock. */
22
+ at: number;
23
+ }
24
+
25
+ /** The longest ref or external. */
26
+ export const LINK_VALUE_MAX = 128;
27
+ /** The longest state. */
28
+ export const LINK_STATE_MAX = 32;
29
+ /** `list` takes at most this many rows; the default is {@link LINK_LIST_DEFAULT}. */
30
+ export const LINK_LIST_MAX = 500;
31
+ export const LINK_LIST_DEFAULT = 100;
32
+
33
+ const VALUE_RE = /^[A-Za-z0-9_.:#-]+$/;
34
+ const STATE_RE = /^[a-z_.]+$/;
35
+
36
+ /** True for a system on the closed list. */
37
+ export function isLinkSystem(value: unknown): value is LinkSystem {
38
+ return typeof value === 'string' && (LINK_SYSTEMS as readonly string[]).includes(value);
39
+ }
40
+
41
+ /** True for a `ref` or `external` value: 1..128 characters of the allowed set. */
42
+ export function isLinkValue(value: unknown): value is string {
43
+ return typeof value === 'string' && value.length >= 1 && value.length <= LINK_VALUE_MAX && VALUE_RE.test(value);
44
+ }
45
+
46
+ /**
47
+ * Check a row's shape. Throws `TypeError` for a value that is not an object and `RangeError` for a field outside its shape; the message
48
+ * names the field and never the value.
49
+ */
50
+ export function checkLinkRow(row: LinkRow): void {
51
+ if (typeof row !== 'object' || row === null || Array.isArray(row)) throw new TypeError('a link row is an object');
52
+ if (!isLinkSystem(row.system)) throw new RangeError('link system is not one of the known systems');
53
+ if (!isLinkValue(row.ref)) throw new RangeError(`link ref must be 1 to ${LINK_VALUE_MAX} characters of A-Z a-z 0-9 _ . : # -`);
54
+ if (!isLinkValue(row.external)) throw new RangeError(`link external must be 1 to ${LINK_VALUE_MAX} characters of A-Z a-z 0-9 _ . : # -`);
55
+ if (typeof row.state !== 'string' || row.state.length < 1 || row.state.length > LINK_STATE_MAX || !STATE_RE.test(row.state)) {
56
+ throw new RangeError(`link state must be 1 to ${LINK_STATE_MAX} characters of a-z _ .`);
57
+ }
58
+ if (typeof row.at !== 'number' || !Number.isFinite(row.at) || row.at < 0) throw new RangeError('link at must be a finite non-negative number');
59
+ }
60
+
61
+ /** The default and the clamp of `list`'s limit: a fraction is floored, a non-number or NaN is the default. */
62
+ export function linkLimit(limit: unknown): number {
63
+ if (typeof limit !== 'number' || Number.isNaN(limit)) return LINK_LIST_DEFAULT;
64
+ return Math.min(LINK_LIST_MAX, Math.max(1, Math.floor(limit)));
65
+ }
66
+
67
+ /** True when the store has all four link methods. */
68
+ export function hasLinkMethods(store: {
69
+ getLink?: unknown;
70
+ putLink?: unknown;
71
+ listLinks?: unknown;
72
+ purgeLinks?: unknown;
73
+ }): boolean {
74
+ return (
75
+ typeof store.getLink === 'function' &&
76
+ typeof store.putLink === 'function' &&
77
+ typeof store.listLinks === 'function' &&
78
+ typeof store.purgeLinks === 'function'
79
+ );
80
+ }
package/src/retention.ts CHANGED
@@ -195,6 +195,7 @@ function checkWindow(name: string, ms: number): void {
195
195
  * permanent, or timed and not yet ended before that cutoff, and not revoked (that row stops a second appeal). An open appeal is never
196
196
  * deleted or cleared; but one whose sanction rows this pass removed (or that has none) is first mooted, so it ends up decided-like. Blocked names: `at < now - blockedNamesMs` (30 days by default).
197
197
  * A store without the appeal or blocked-name methods has none of these.
198
+ * - links (`cw.links`): `at < now - reportsMs` (90 days by default), every system. A store without the link methods has none.
198
199
  * - notices: withdrawn, or a seen warning / report outcome, with `createdAt < now - noticesMs`; or
199
200
  * `until < now - noticesMs`. A notice for a permanent or running sanction is kept while it applies (agrees with
200
201
  * `NoticeService.record`), and an unseen warning is kept until it is seen or withdrawn. The four message kinds: seen, as a report outcome;
@@ -237,6 +238,8 @@ export async function purge(
237
238
  checkWindow('blockedNamesMs', p.blockedNamesMs);
238
239
  return store.transaction(() => {
239
240
  const reports = store.purgeReports(now - p.reportsMs, now - p.badFaithMs);
241
+ // Link rows (`cw.links`) are ids only and outlive the report they name by no useful time: the same clock as reports. Not counted in the result. A live row (an active EOS sanction, the EOS cursor) is kept by the store whatever its age.
242
+ store.purgeLinks?.(now - p.reportsMs);
240
243
  const ai = store.purgeAi?.(now - p.reportsMs, now - p.aiOutcomesMs, now - p.aiExamplesMs) ?? { reads: 0, outcomes: 0 };
241
244
  return {
242
245
  reports,
package/src/sanctions.ts CHANGED
@@ -49,6 +49,23 @@ const REF_ATTEMPTS = 5;
49
49
  /** No I, L, O, 0 or 1: a player reads the code aloud or types it from a screenshot. */
50
50
  const REF_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
51
51
 
52
+ /**
53
+ * Reads a player-typed reference code: trims, ignores case, accepts a bare five characters as `M-` plus them. Returns the canonical
54
+ * `M-XXXXX`, or null for anything else (a wrong length, an ambiguous character I, L, O, 0 or 1, another prefix). A non-string is a
55
+ * `TypeError`. Pure.
56
+ * @experimental
57
+ */
58
+ export function normalizeRefCode(text: string): string | null {
59
+ if (typeof text !== 'string') throw new TypeError('a reference code is a string');
60
+ const t = text.trim();
61
+ // ASCII only before upper-casing: a few non-ASCII letters (a long s) upper-case into a valid one.
62
+ const m = /^(?:[Mm]-)?([A-Za-z0-9]{5})$/.exec(t);
63
+ const code = m?.[1]?.toUpperCase();
64
+ if (code === undefined) return null;
65
+ for (const ch of code) if (!REF_ALPHABET.includes(ch)) return null;
66
+ return `M-${code}`;
67
+ }
68
+
52
69
  /**
53
70
  * The key to `SanctionInput.startsAt`. It is exported from this module only, never from the package index, so only code inside the kit (the
54
71
  * appeals service) can hold it; a public caller passing a start time is refused with a `RangeError`.
package/src/staffViews.ts CHANGED
@@ -208,6 +208,39 @@ export function listSanctionGroups(store: Store, subjects: SubjectIndex, q: Sanc
208
208
  };
209
209
  }
210
210
 
211
+ /** How many of the newest groups the by-ref fallback reads for a store with no `sanctionGroupByRef`. */
212
+ export const BY_REF_FALLBACK_GROUPS = 1000;
213
+
214
+ /**
215
+ * One group's staff view with its canonical person, found by a normalised ref code (`M-XXXXX`), or null. A store with
216
+ * `sanctionGroupByRef` answers from its index; one without is read through the newest {@link BY_REF_FALLBACK_GROUPS} groups.
217
+ * Built from the group's SUBJECT row only: an IP row is never read.
218
+ */
219
+ export function sanctionByRef(store: Store, subjects: SubjectIndex, code: string, now: number): PersonSanctionView | null {
220
+ const view = (r: SanctionRow): PersonSanctionView => ({ ...sanctionGroupView(r, now), person: subjects.canonical(r.value) });
221
+ if (typeof store.sanctionGroupByRef === 'function') {
222
+ const groupId = store.sanctionGroupByRef(code);
223
+ if (groupId === null) return null;
224
+ const row = store.listSubjectSanctions({ groupId, limit: 5 }).find((r) => r.groupId === groupId && r.refCode === code);
225
+ return row === undefined ? null : view(row);
226
+ }
227
+ let before: { startsAt: number; id: string } | null = null;
228
+ let seen = 0;
229
+ while (seen < BY_REF_FALLBACK_GROUPS) {
230
+ const page = store.listSubjectSanctions({
231
+ limit: Math.min(200, BY_REF_FALLBACK_GROUPS - seen),
232
+ ...(before === null ? {} : { before: before.startsAt, beforeId: before.id }),
233
+ });
234
+ const hit = page.find((r) => r.refCode === code);
235
+ if (hit !== undefined) return view(hit);
236
+ const last = page[page.length - 1];
237
+ if (last === undefined || page.length < Math.min(200, BY_REF_FALLBACK_GROUPS - seen)) return null;
238
+ seen += page.length;
239
+ before = { startsAt: last.startsAt, id: last.id };
240
+ }
241
+ return null;
242
+ }
243
+
211
244
  // ---------------------------------------------------------------------------
212
245
  // The reporter's record
213
246
  // ---------------------------------------------------------------------------
package/src/types.ts CHANGED
@@ -4,6 +4,7 @@
4
4
  import type { AIExample, AIRead, AISignal } from './ai/types.js';
5
5
  import type { AppealStatus } from './appeals.js';
6
6
  import type { AuditListQuery, AuditRow } from './audit.js';
7
+ import type { LinkRow, LinkSystem } from './links.js';
7
8
  import type { NameReason } from './names.js';
8
9
  import type { PolicyLayer } from './profile.js';
9
10
  import type { RuleRef } from './rules.js';
@@ -216,6 +217,8 @@ export interface SanctionListQuery {
216
217
  /** Keyset cursor: only rows older than this (`startsAt` below it, or equal with an id below `beforeId`). `beforeId` without `before` is ignored. */
217
218
  before?: number;
218
219
  beforeId?: string;
220
+ /** Only the rows of this sanction group (its subject row: an IP row is never listed). Optional, additive (0.1.12). */
221
+ groupId?: string;
219
222
  /** Clamped to 1..200 (a fraction is floored). */
220
223
  limit: number;
221
224
  }
@@ -883,6 +886,15 @@ export interface Store {
883
886
  */
884
887
  sanctionRefCode(groupId: string): string | null;
885
888
 
889
+ /**
890
+ * OPTIONAL (0.1.12, `@experimental`). The sanction group that holds this exact ref code (`M-` plus five characters, already
891
+ * normalised: upper case), or null. Revoked and ended groups are found: the code never changes. A store that implements it MUST also honour
892
+ * `SanctionListQuery.groupId` (`cw.sanctions.byRef` reads the group's rows with it; a store that ignores the filter returns other groups'
893
+ * rows and the code is silently missed). A store without it makes
894
+ * `cw.sanctions.byRef` read the newest 1 000 groups through {@link Store.listSubjectSanctions} instead.
895
+ */
896
+ sanctionGroupByRef?(refCode: string): string | null;
897
+
886
898
  /**
887
899
  * The person a sanction group is about and the rule it cites, for the `sanction.revoked` event: the group's SUBJECT row
888
900
  * (its IP row is not a person) and its stored rule text (`'1'`.., `'uncovered'`, or null on a row written before rules
@@ -1398,6 +1410,29 @@ export interface Store {
1398
1410
  /** OPTIONAL. Delete names with `at < before` (a row exactly on the line is kept); returns how many. */
1399
1411
  purgeBlockedNames?(before: number): number;
1400
1412
 
1413
+ // Links (K5 design 5.1, `cw.links`). OPTIONAL: a store without all four has `cw.links.supported` false, and an adapter that needs links
1414
+ // refuses it at construction. SYNCHRONOUS (like notices); they run inside `transaction` and are undone with it. They take a row the
1415
+ // facade has already validated, keep it as it is and return copies. A link write is not a queue change: it does not move the change token.
1416
+
1417
+ /** OPTIONAL (`@experimental`). The row for `(system, ref)`, a copy, or null. */
1418
+ getLink?(system: LinkSystem, ref: string): LinkRow | null;
1419
+
1420
+ /** OPTIONAL (`@experimental`). Insert the row, or replace the one with the same `(system, ref)`. */
1421
+ putLink?(row: LinkRow): void;
1422
+
1423
+ /**
1424
+ * OPTIONAL (`@experimental`). The `system`'s rows, oldest `at` first and then by `ref` (code point order), only this `state` when given,
1425
+ * at most `limit` (floored, clamped to 1..500; NaN is 1). The state filter applies before the limit. Copies.
1426
+ */
1427
+ listLinks?(system: LinkSystem, q: { state?: string; limit: number }): LinkRow[];
1428
+
1429
+ /**
1430
+ * OPTIONAL (`@experimental`). Delete rows with `at < before` (a row exactly on the line is kept); returns how many. A row that says it is live
1431
+ * is never deleted by age: an `eos-sanction` row in state `active` (a lift long after the push must still find it) and every `eos-cursor`
1432
+ * row. Once such a row is marked `removed` (or `failed`) its `at` is new and it ages out like any other.
1433
+ */
1434
+ purgeLinks?(before: number): number;
1435
+
1401
1436
  // Staff audit trail. SYNCHRONOUS on purpose (like sanctions). The trail also holds the rows `closeGap` and the term
1402
1437
  // editor write; none of these methods ever returns the json columns those carry (they may hold term text).
1403
1438