@meith/plugin-awards 0.37.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Harrison and the Meith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @meith/plugin-awards
+
+Community awards, manual recognition and achievements.
+
+## What it adds
+
+- A public catalogue at `/plugins/awards`, award holder pages and member award pages.
+- Admin award creation, ordering, archiving, manual assignment and revocation.
+- Icons beside posts, a profile panel and a seven-day dashboard count.
+- Per-award multiple grants, optional notifications and public reason controls.
+
+## Installation and operation
+
+The package exports `plugin` and `messages` for the board manifest. It depends
+only on the plugin kit and shared UI. Run migrations when installing it.
+
+The [Awards guide](../../docs/guides/community/awards-guide.md) covers setup,
+visibility, icons, notifications, caching and version-one limits.
+
+## What it stores
+
+One migration creates awards, grants, rules, a dirty-member queue and a scan
+cursor, all under `plugin_awards_*`. Foreign keys remain inside that namespace;
+member ids are plain columns. Account deletion removes grants; account merging
+preserves recognition while collapsing single-only and same-rule duplicates.
+
+## Automatic rules
+
+Administrators can combine minimum posts, threads, reputation and registration
+age. A five-minute task drains queued changes and scans existing members in
+bounded, resumable batches. Its rule/member unique index prevents duplicate
+awards from repeated runs. The public catalogue describes how awards are earned.
+See the guide for progress controls, revocation behaviour and failure recovery.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@meith/plugin-awards",
+  "version": "0.37.0",
+  "description": "Community awards, manual recognition and achievements.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "plugins/awards"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/plugin-kit": "^0.37.0",
+    "@meith/ui": "^0.37.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18"
+  }
+}

package/src/awards.ts

@@ -0,0 +1,99 @@
+export const ICON_PATHS = {
+  trophy: 'M8 3h8v6a4 4 0 0 1-8 0V3ZM8 5H4v3a4 4 0 0 0 4 4m8-7h4v3a4 4 0 0 1-4 4m-4 1v7m-4 0h8',
+  medal: 'm7 3 5 7 5-7M4 3h5m6 0h5M17 15a5 5 0 1 1-10 0 5 5 0 0 1 10 0Z',
+  star: 'm12 3 3 6 7 1-5 5 1 7-6-3-6 3 1-7-5-5 7-1Z',
+  shield: 'm12 3 8 3v6c0 5-8 9-8 9s-8-4-8-9V6Z',
+  crown: 'm3 6 5 5 4-8 4 8 5-5-2 13H5Zm2 10h14',
+  heart: 'M12 21 3 12C-2 5 7 0 12 7c5-7 14-2 9 5Z',
+  flame: 'M12 2c2 7-6 8-3 12 3 0 4-3 4-5 9 7 4 13-1 13S1 15 7 9c0 3 1 3 1 3-2-5 4-7 4-10Z',
+  gem: 'm3 8 4-5h10l4 5-9 13Zm0 0h18M7 3l5 18 5-18',
+  ribbon: 'M17 8A5 5 0 1 1 7 8a5 5 0 0 1 10 0Zm-9 4-2 9 6-3 6 3-2-9',
+  rocket:
+    'M9 15 5 11C9 3 16 2 22 2c0 6-1 13-9 17Zm-4-4-3 2v4l7-2m4 4-2 3H7l2-7m6-8h2v2h-2Zm-10 12-3 3',
+  book: 'M12 5C8 2 4 3 2 4v16c4-2 7-2 10 0 3-2 6-2 10 0V4c-2-1-6-2-10 1Zm0 0v15',
+  handshake: 'm2 8 4-4 5 2 3-2 8 5-4 9-4 3-8-5Zm9-2-4 5 3 2 4-4 6 6m-10 0 5 4m-7-1 4 3',
+} as const
+
+export type IconKind = 'emoji' | 'svg' | 'image'
+export interface AwardDraft {
+  readonly name: string
+  readonly description: string
+  readonly icon_kind: IconKind
+  readonly icon: string
+  readonly display_order: number
+  readonly allow_multiple: boolean
+  readonly listed: boolean
+}
+export interface Award extends AwardDraft {
+  readonly id: number
+  readonly archived_at: Date | string | null
+}
+
+export function asId(value: string | undefined): number | null {
+  if (!/^[1-9]\d*$/.test(value ?? '')) return null
+  const id = Number(value)
+  return Number.isSafeInteger(id) ? id : null
+}
+
+export function parseIcon(value: string): { icon_kind: IconKind; icon: string } | null {
+  const icon = value.trim()
+  if (Object.hasOwn(ICON_PATHS, icon)) return { icon_kind: 'svg', icon }
+  if (icon.length > 2048 || /[\s\\\p{Cc}]/u.test(icon)) return null
+  if (icon[0] === '/' && icon[1] !== '/') return { icon_kind: 'image', icon }
+  try {
+    const url = new URL(icon)
+    if (url.protocol === 'https:' && !url.username && !url.password) {
+      return { icon_kind: 'image', icon: url.href }
+    }
+  } catch {}
+  if (
+    /^(?:\p{Regional_Indicator}{2}|[0-9#*]\uFE0F?\u20E3|\p{Extended_Pictographic}\uFE0F?\p{Emoji_Modifier}?(?:\u200D\p{Extended_Pictographic}\uFE0F?\p{Emoji_Modifier}?)*)$/u.test(
+      icon,
+    )
+  ) {
+    return { icon_kind: 'emoji', icon }
+  }
+  return null
+}
+
+export function parseAward(
+  form: Readonly<Record<string, string>>,
+): { draft: AwardDraft; error?: never } | { draft?: never; error: 'invalid' | 'icon' } {
+  const name = (form.name ?? '').trim()
+  const description = (form.description ?? '').trim()
+  const order = form.display_order?.trim() || '0'
+  const display_order = Number(order)
+  if (
+    !name ||
+    name.length > 120 ||
+    description.length > 2000 ||
+    !/^\d+$/.test(order) ||
+    !Number.isSafeInteger(display_order) ||
+    display_order > 2147483647
+  )
+    return { error: 'invalid' }
+  const icon = parseIcon(form.icon ?? '🏆')
+  if (icon === null) return { error: 'icon' }
+  return {
+    draft: {
+      name,
+      description,
+      ...icon,
+      display_order,
+      allow_multiple: form.allow_multiple === 'on',
+      listed: form.listed === 'on',
+    },
+  }
+}
+
+export function postbitLimit(
+  settings: Readonly<Record<string, string | number | boolean>>,
+): number {
+  const value = Number(settings.postbit_limit ?? 5)
+  return Number.isFinite(value) ? Math.max(0, Math.min(100, Math.floor(value))) : 5
+}
+
+export interface DisplayAward extends Award, Record<string, unknown> {
+  readonly count: number
+  readonly total: number
+}

package/src/definition.ts

@@ -0,0 +1,116 @@
+import { definePlugin } from '@meith/plugin-kit'
+
+import { handleAward, handleGrant, handleRules } from './handlers'
+import en from './messages/en.json'
+import { AWARDS_MIGRATIONS } from './schema'
+import { deleteMember, mergeMember } from './store'
+import { evaluateAwards, queueMember } from './tasks'
+import { AwardsAdmin, GrantAdmin } from './ui/admin'
+import {
+  AwardPage,
+  AwardsPage,
+  Dashboard,
+  MemberPage,
+  PostbitBadges,
+  ProfilePanel,
+} from './ui/page'
+import { RulesAdmin } from './ui/rules'
+
+export const plugin = definePlugin({
+  key: 'awards',
+  name: en['awards.title'],
+  nameKey: 'awards.title',
+  version: '0.37.0',
+  apiVersion: '0',
+  description: en['awards.definition.description'],
+  descriptionKey: 'awards.definition.description',
+  migrations: AWARDS_MIGRATIONS,
+  tasks: [{ id: 'evaluate', intervalSeconds: 300, run: evaluateAwards }],
+  settings: [
+    {
+      key: 'postbit_limit',
+      type: 'number',
+      default: 5,
+      label: en['awards.setting.limit'],
+      labelKey: 'awards.setting.limit',
+    },
+    {
+      key: 'notify_on_grant',
+      type: 'boolean',
+      default: true,
+      label: en['awards.setting.notify'],
+      labelKey: 'awards.setting.notify',
+    },
+    {
+      key: 'show_reasons',
+      type: 'boolean',
+      default: true,
+      label: en['awards.setting.reasons'],
+      labelKey: 'awards.setting.reasons',
+    },
+  ],
+  notifications: [
+    {
+      key: 'award_received',
+      title: en['awards.notification.subject'],
+      titleKey: 'awards.notification.subject',
+      description: en['awards.notification.description'],
+      descriptionKey: 'awards.notification.description',
+      emailByDefault: false,
+    },
+  ],
+  navigation: [
+    { key: 'awards', label: 'Awards', labelKey: 'awards.title', path: '', audience: 'all' },
+  ],
+  pages: [
+    {
+      path: '',
+      title: en['awards.title'],
+      titleKey: 'awards.title',
+      access: 'anonymous',
+      render: AwardsPage,
+    },
+    {
+      path: 'award',
+      title: en['awards.award'],
+      titleKey: 'awards.award',
+      access: 'anonymous',
+      render: AwardPage,
+    },
+    {
+      path: 'member',
+      title: en['awards.member.awards'],
+      titleKey: 'awards.member.awards',
+      access: 'anonymous',
+      render: MemberPage,
+    },
+  ],
+  adminPages: [
+    { path: 'awards', title: en['awards.title'], titleKey: 'awards.title', render: AwardsAdmin },
+    { path: 'grant', title: en['awards.grant'], titleKey: 'awards.grant', render: GrantAdmin },
+    { path: 'rules', title: en['awards.rules'], titleKey: 'awards.rules', render: RulesAdmin },
+  ],
+  routes: [
+    { path: 'rules', method: 'POST', access: 'admin', handler: handleRules },
+    { path: 'awards', method: 'POST', access: 'admin', handler: handleAward },
+    { path: 'grant', method: 'POST', access: 'admin', handler: handleGrant },
+  ],
+  hooks: {
+    'post.created': async (post, _context, runtime) => queueMember(await runtime(), post.authorId),
+    'thread.created': async (thread, _context, runtime) =>
+      queueMember(await runtime(), thread.authorId),
+    'reputation.changed': async (user, _context, runtime) =>
+      queueMember(await runtime(), user.userId),
+    'user.registered': async (user, _context, runtime) => queueMember(await runtime(), user.userId),
+    'user.activated': async (user, _context, runtime) => queueMember(await runtime(), user.userId),
+    'user.deleted': async (user, _context, runtime) =>
+      deleteMember((await runtime()).data, user.userId),
+    'user.merged': async (user, _context, runtime) =>
+      mergeMember((await runtime()).data, user.keptUserId, user.mergedUserId),
+  },
+  contributions: [
+    { region: 'postbit.badges', render: PostbitBadges },
+    { region: 'profile.panel', render: ProfilePanel },
+    { region: 'admin.dashboard', render: Dashboard },
+  ],
+})

package/src/display-cache.ts

@@ -0,0 +1,48 @@
+import type { PluginData } from '@meith/plugin-kit'
+
+import type { DisplayAward } from './awards'
+
+type DisplayCache = Map<
+  number,
+  { until: number; limit: number; rows: Promise<readonly DisplayAward[]> }
+>
+const CACHE_KEY = Symbol.for('@meith/plugin-awards.display')
+const shared = globalThis as typeof globalThis & { [CACHE_KEY]?: DisplayCache }
+const cache: DisplayCache = shared[CACHE_KEY] ?? new Map()
+shared[CACHE_KEY] = cache
+
+export function clearDisplay(userId?: number): void {
+  if (userId === undefined) cache.clear()
+  else cache.delete(userId)
+}
+
+export function cachedAwards(
+  data: PluginData,
+  userId: number,
+  limit: number,
+): Promise<readonly DisplayAward[]> {
+  const found = cache.get(userId)
+  if (found !== undefined && found.until > Date.now() && found.limit === limit) return found.rows
+  cache.delete(userId)
+  if (cache.size >= 2000) cache.delete(cache.keys().next().value!)
+  const entry = { until: Date.now() + 60_000, limit, rows: displayAwards(data, userId, limit + 1) }
+  cache.set(userId, entry)
+  void entry.rows.catch(() => {
+    if (cache.get(userId) === entry) cache.delete(userId)
+  })
+  return entry.rows
+}
+
+export async function displayAwards(
+  data: PluginData,
+  userId: number,
+  limit: number,
+): Promise<readonly DisplayAward[]> {
+  return data.query<DisplayAward>(
+    `select a.*, count(*)::int as count, count(*) over ()::int as total
+    from plugin_awards_grant g join plugin_awards_award a on a.id = g.award_id
+    where g.user_id = $1 and a.archived_at is null
+    group by a.id order by a.display_order, a.id limit $2`,
+    [userId, limit],
+  )
+}

package/src/handlers.ts

@@ -0,0 +1,125 @@
+import type { PluginRequest, PluginResponse, PluginRuntimeContext } from '@meith/plugin-kit'
+
+import { asId, parseAward } from './awards'
+import { awardRuleProblem, parseRule } from './rules'
+import {
+  archiveAward,
+  awardById,
+  awardRules,
+  deleteAward,
+  grantAward,
+  revokeGrant,
+  saveAward,
+  saveRule,
+} from './store'
+import { evaluateAwards } from './tasks'
+
+export function toAdmin(page: string, notice: string): PluginResponse {
+  return {
+    kind: 'redirect',
+    to: `/admin/plugins/awards/${page}?notice=${encodeURIComponent(notice)}`,
+  }
+}
+
+export async function handleAward(
+  request: PluginRequest,
+  context: PluginRuntimeContext,
+): Promise<PluginResponse> {
+  const form = request.form ?? {}
+  const id = asId(form.id)
+  if (form.id && id === null) return toAdmin('awards', 'invalid')
+  if (form.action === 'delete' || form.action === 'archive' || form.action === 'restore') {
+    if (id === null || (await awardById(context.data, id)) === null)
+      return toAdmin('awards', 'missing')
+    if (form.action === 'delete')
+      return toAdmin('awards', (await deleteAward(context.data, id)) ? 'deleted' : 'held')
+    await archiveAward(context.data, id, form.action === 'archive')
+    return toAdmin('awards', 'saved')
+  }
+  const parsed = parseAward(form)
+  if (parsed.error !== undefined) return toAdmin('awards', parsed.error)
+  return toAdmin('awards', await saveAward(context.data, parsed.draft, id))
+}
+
+export async function handleGrant(
+  request: PluginRequest,
+  context: PluginRuntimeContext,
+): Promise<PluginResponse> {
+  const form = request.form ?? {}
+  if (form.action === 'revoke') {
+    const id = asId(form.id)
+    if (id === null) return toAdmin('grant', 'invalid')
+    await revokeGrant(context.data, id)
+    return toAdmin('grant', 'revoked')
+  }
+  const awardId = asId(form.award_id)
+  const reason = (form.reason ?? '').trim()
+  const names = [
+    ...new Set(
+      (form.usernames ?? '')
+        .split(',')
+        .map((name) => name.trim().toLowerCase())
+        .filter(Boolean),
+    ),
+  ]
+  if (awardId === null || !names.length || names.length > 200 || reason.length > 2000)
+    return toAdmin('grant', 'invalid')
+  const award = await awardById(context.data, awardId)
+  if (award === null || award.archived_at !== null) return toAdmin('grant', 'missing')
+  const members = await Promise.all(names.map((name) => context.users.byUsername(name)))
+  if (members.some((member) => member === null)) return toAdmin('grant', 'unknown')
+  let granted = 0
+  for (const member of members) {
+    if (
+      member !== null &&
+      (await grantAward(context, {
+        awardId,
+        userId: member.userId,
+        byUserId: request.viewer.userId,
+        reason,
+      })) !== null
+    )
+      granted++
+  }
+  return toAdmin(
+    'grant',
+    granted === members.length ? 'granted' : granted === 0 ? 'already' : 'partial',
+  )
+}
+
+export async function handleRules(
+  request: PluginRequest,
+  context: PluginRuntimeContext,
+): Promise<PluginResponse> {
+  const form = request.form ?? {}
+  if (form.action === 'run') {
+    await evaluateAwards(context)
+    return toAdmin('rules', 'evaluated')
+  }
+  if (form.action === 'reset') {
+    await context.data.query(`update plugin_awards_scan set cursor = 0 where id = 1`)
+    return toAdmin('rules', 'reset')
+  }
+  const id = asId(form.id)
+  if (form.id && id === null) return toAdmin('rules', 'rule-invalid')
+  if (id !== null && !(await awardRules(context.data)).some((rule) => rule.id === id))
+    return toAdmin('rules', 'rule-missing')
+  if (form.action === 'delete' || form.action === 'enable' || form.action === 'disable') {
+    if (id === null) return toAdmin('rules', 'rule-missing')
+    if (form.action === 'delete')
+      await context.data.query(`delete from plugin_awards_rule where id = $1`, [id])
+    else
+      await context.data.query(
+        `update plugin_awards_rule set enabled = $2, updated_at = now() where id = $1`,
+        [id, form.action === 'enable'],
+      )
+    return toAdmin('rules', 'rule-saved')
+  }
+  const rule = parseRule(form)
+  const problem = awardRuleProblem(rule)
+  if (problem !== null) return toAdmin('rules', problem)
+  const award = await awardById(context.data, rule.awardId)
+  if (award === null || award.archived_at !== null) return toAdmin('rules', 'missing')
+  await saveRule(context.data, rule, id)
+  return toAdmin('rules', 'rule-saved')
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { plugin } from './definition'
+export { messages } from './messages'

package/src/messages/en.json

@@ -0,0 +1,82 @@
+{
+  "awards.actions": "Actions",
+  "awards.archive": "Archive",
+  "awards.award": "Award",
+  "awards.create": "Create award",
+  "awards.dashboard": "Grants in the last 7 days",
+  "awards.date": "Granted (UTC)",
+  "awards.definition.description": "Community awards, manual recognition and achievements.",
+  "awards.delete": "Delete",
+  "awards.deletedMember": "Deleted member",
+  "awards.description": "Description",
+  "awards.edit": "Edit award",
+  "awards.empty": "No awards are listed yet.",
+  "awards.filter": "Filter by username",
+  "awards.filter.apply": "Filter",
+  "awards.grant": "Grant awards",
+  "awards.holders": "Holders",
+  "awards.icon": "Icon",
+  "awards.icon.help": "Use one emoji, a same-origin image path, an HTTPS image URL, or a built-in icon:",
+  "awards.listed": "Listed in the catalogue",
+  "awards.member": "Member",
+  "awards.member.awards": "Member awards",
+  "awards.member.empty": "No awards yet.",
+  "awards.more": "See all awards",
+  "awards.multiple": "Allow multiple grants per member",
+  "awards.name": "Name",
+  "awards.next": "Next",
+  "awards.notice.already": "These members already hold this award.",
+  "awards.notice.deleted": "Award deleted.",
+  "awards.notice.evaluated": "Evaluation batch finished.",
+  "awards.notice.granted": "Awards granted.",
+  "awards.notice.held": "This award has grants and cannot be deleted. Use Archive to retire it.",
+  "awards.notice.icon": "Use one emoji, a built-in icon name, or a same-origin or HTTPS image URL.",
+  "awards.notice.invalid": "Check the required fields and whole numbers. Names allow 120 characters and descriptions and reasons allow 2,000.",
+  "awards.notice.missing": "The award does not exist or is archived.",
+  "awards.notice.multiple": "Members hold multiple grants. Revoke duplicates before making this a single-only award.",
+  "awards.notice.partial": "Some awards were granted; other members already hold this award.",
+  "awards.notice.reset": "The next evaluation starts the full scan from the beginning.",
+  "awards.notice.revoked": "Grant revoked.",
+  "awards.notice.rule-empty": "Set at least one threshold. Zero is allowed and explicitly matches every member for that criterion.",
+  "awards.notice.rule-invalid": "Choose an award, enter a title of up to 120 characters, and use nonnegative whole-number thresholds.",
+  "awards.notice.rule-missing": "That rule no longer exists.",
+  "awards.notice.rule-saved": "Rule saved.",
+  "awards.notice.saved": "Award saved.",
+  "awards.notice.unknown": "A username was not found. Check all names; no awards were granted.",
+  "awards.notification.description": "Staff or an achievement rule gave you an award.",
+  "awards.notification.subject": "You received an award",
+  "awards.order": "Display order",
+  "awards.pagination": "Award holders pages",
+  "awards.previous": "Previous",
+  "awards.reason": "Reason",
+  "awards.recent": "Recent grants",
+  "awards.restore": "Unarchive",
+  "awards.revoke": "Revoke",
+  "awards.rule.all": "All of:",
+  "awards.rule.budget": "Every five minutes, evaluate up to 500 queued members and scan up to 1,000 members. Run now uses the same budget.",
+  "awards.rule.completed": "Last full scan completed (UTC)",
+  "awards.rule.create": "Create rule",
+  "awards.rule.cursor": "Full scan cursor (member id)",
+  "awards.rule.days": "Minimum days registered",
+  "awards.rule.disable": "Disable",
+  "awards.rule.edit": "Edit rule",
+  "awards.rule.enable": "Enable",
+  "awards.rule.enabled": "Enabled",
+  "awards.rule.help": "Leave a threshold blank to ignore it. Set at least one; zero is allowed. All configured thresholds must hold.",
+  "awards.rule.never": "Not yet",
+  "awards.rule.posts": "Minimum posts",
+  "awards.rule.reputation": "Minimum reputation",
+  "awards.rule.reset": "Re-check everyone",
+  "awards.rule.run": "Run now",
+  "awards.rule.save": "Save rule",
+  "awards.rule.threads": "Minimum threads",
+  "awards.rule.title": "Rule title",
+  "awards.rules": "Rules",
+  "awards.save": "Save award",
+  "awards.setting.limit": "Maximum awards beside each post (0 hides, up to 100)",
+  "awards.setting.notify": "Notify members when they receive an award",
+  "awards.setting.reasons": "Show manual grant reasons publicly",
+  "awards.staff": "Given by staff",
+  "awards.title": "Awards",
+  "awards.usernames": "Usernames (comma-separated)"
+}

package/src/messages/index.ts

@@ -0,0 +1,3 @@
+import en from './en.json'
+
+export const messages = { en }

package/src/rules.ts

@@ -0,0 +1,77 @@
+import type { PluginUserStanding } from '@meith/plugin-kit'
+
+export interface AwardRuleInput {
+  readonly awardId: number
+  readonly title: string
+  readonly enabled: boolean
+  readonly minPostCount: number | null
+  readonly minThreadCount: number | null
+  readonly minReputation: number | null
+  readonly minDaysRegistered: number | null
+}
+export interface AwardRule extends AwardRuleInput {
+  readonly id: number
+}
+export const CRITERIA = [
+  'minPostCount',
+  'minThreadCount',
+  'minReputation',
+  'minDaysRegistered',
+] as const
+
+export function awardRuleProblem(input: AwardRuleInput): 'rule-invalid' | 'rule-empty' | null {
+  if (
+    !input.title.trim() ||
+    input.title.trim().length > 120 ||
+    !Number.isSafeInteger(input.awardId) ||
+    input.awardId <= 0
+  )
+    return 'rule-invalid'
+  for (const key of CRITERIA) {
+    const value = input[key]
+    if (value !== null && (!Number.isSafeInteger(value) || value < 0 || value > 2147483647))
+      return 'rule-invalid'
+  }
+  return CRITERIA.every((key) => input[key] === null) ? 'rule-empty' : null
+}
+
+export function parseRule(form: Readonly<Record<string, string>>): AwardRuleInput {
+  const threshold = (key: string): number | null => {
+    const value = form[key]?.trim() ?? ''
+    return value === '' ? null : /^\d+$/.test(value) ? Number(value) : Number.NaN
+  }
+  return {
+    awardId: Number(form.award_id),
+    title: (form.title ?? '').trim(),
+    enabled: form.enabled === 'on',
+    minPostCount: threshold('min_post_count'),
+    minThreadCount: threshold('min_thread_count'),
+    minReputation: threshold('min_reputation'),
+    minDaysRegistered: threshold('min_days_registered'),
+  }
+}
+
+export function evaluateAwardRules(
+  rules: readonly AwardRule[],
+  members: readonly PluginUserStanding[],
+  now: Date = new Date(),
+): Array<{ userId: number; ruleId: number; awardId: number }> {
+  const active = rules
+    .filter((rule) => rule.enabled && awardRuleProblem(rule) === null)
+    .sort((a, b) => a.id - b.id)
+  const outcomes: Array<{ userId: number; ruleId: number; awardId: number }> = []
+  for (const member of members) {
+    for (const rule of active) {
+      if (rule.minPostCount !== null && !(member.postCount >= rule.minPostCount)) continue
+      if (rule.minThreadCount !== null && !(member.threadCount >= rule.minThreadCount)) continue
+      if (rule.minReputation !== null && !(member.reputation >= rule.minReputation)) continue
+      if (
+        rule.minDaysRegistered !== null &&
+        !((now.getTime() - member.registeredAt.getTime()) / 86_400_000 >= rule.minDaysRegistered)
+      )
+        continue
+      outcomes.push({ userId: member.userId, ruleId: rule.id, awardId: rule.awardId })
+    }
+  }
+  return outcomes
+}