@meith/tasks 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@meith/tasks",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/tasks"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/builtin.ts

@@ -0,0 +1,455 @@
+import type { TaskDefinition } from './types'
+
+export interface TaskWorkers {
+  relayOutbox(batchSize: number): Promise<number>
+  deliverWebhooks(batchSize: number): Promise<{
+    readonly attempted: number
+    readonly delivered: number
+    readonly retried: number
+    readonly dead: number
+  }>
+  drainQueue(batchSize: number, signal: AbortSignal): Promise<number>
+  pruneSessions(): Promise<number>
+  pruneExpiredTokens(): Promise<number>
+  pruneRateLimits(): Promise<number>
+  pruneAuthEvents(): Promise<number>
+  reconcileCounters(batchSize: number): Promise<number>
+  flushThreadViews(batchSize: number): Promise<number>
+  backfillPostRenders(batchSize: number): Promise<number>
+  reindexSearch(batchSize: number): Promise<number>
+  refreshMarketplaceCatalog(): Promise<{ ok: boolean; listingCount: number; notified: number }>
+  applyPromotions(batchSize: number): Promise<number>
+  expireBans(batchSize: number): Promise<number>
+  expireGroupMemberships(batchSize: number): Promise<number>
+  expireWarnings(batchSize: number): Promise<number>
+  notifySubscribers(batchSize: number, signal: AbortSignal): Promise<number>
+  sendDigests(batchSize: number, signal: AbortSignal): Promise<number>
+  sweepAttachments(batchSize: number): Promise<{ deleted: number; failed: number }>
+  sweepAvatars(batchSize: number): Promise<number>
+  rollUpStatistics(): Promise<{ memberCount: number; online: number; record: boolean }>
+}
+
+function allDefinitions(workers: TaskWorkers): TaskDefinition[] {
+  return [
+    {
+      id: 'outbox.relay',
+      title: 'Relay domain events',
+      titleKey: 'adminSystem.task.outboxRelay.title',
+      description:
+        'Moves committed events from the outbox onto the queue. Runs most ' +
+        'frequently because user-visible side effects (notifications, search ' +
+        'indexing) wait on it.',
+      descriptionKey: 'adminSystem.task.outboxRelay.description',
+      intervalSeconds: 60,
+      maxDurationSeconds: 30,
+      async run() {
+        const relayed = await workers.relayOutbox(200)
+        return { detail: { relayed } }
+      },
+    },
+
+    {
+      id: 'webhooks.deliver',
+      title: 'Deliver queued webhooks',
+      titleKey: 'adminSystem.task.webhooksDeliver.title',
+      description:
+        'Sends pending webhook deliveries to their subscribers, then records ' +
+        'each verdict: delivered, retried with backoff, or dead-lettered.',
+      descriptionKey: 'adminSystem.task.webhooksDeliver.description',
+      intervalSeconds: 60,
+      maxDurationSeconds: 240,
+      async run() {
+        const result = await workers.deliverWebhooks(20)
+        return { detail: { ...result } }
+      },
+    },
+
+    {
+      id: 'queue.drain',
+      title: 'Process queued jobs',
+      titleKey: 'adminSystem.task.queueDrain.title',
+      description:
+        'Executes due jobs. Bounded per run: a large backlog is drained across ' +
+        'several ticks rather than risking a function timeout mid-job. Stops ' +
+        'between jobs when its budget is spent, handing back the jobs it did ' +
+        'not reach.',
+      descriptionKey: 'adminSystem.task.queueDrain.description',
+      intervalSeconds: 60,
+      maxDurationSeconds: 45,
+      async run({ signal }) {
+        const processed = await workers.drainQueue(50, signal)
+        return { detail: { processed } }
+      },
+    },
+
+    {
+      id: 'sessions.prune',
+      title: 'Prune idle sessions',
+      titleKey: 'adminSystem.task.sessionsPrune.title',
+      description:
+        'Deletes sessions past the idle timeout. Purely subtractive, so running ' +
+        'it twice removes nothing extra.',
+      descriptionKey: 'adminSystem.task.sessionsPrune.description',
+      intervalSeconds: 3600,
+      maxDurationSeconds: 30,
+      async run() {
+        const removed = await workers.pruneSessions()
+        return { detail: { removed } }
+      },
+    },
+
+    {
+      id: 'tokens.prune',
+      title: 'Prune expired tokens',
+      titleKey: 'adminSystem.task.tokensPrune.title',
+      description: 'Clears spent activation and password-reset tokens.',
+      descriptionKey: 'adminSystem.task.tokensPrune.description',
+      intervalSeconds: 3600,
+      maxDurationSeconds: 30,
+      async run() {
+        const removed = await workers.pruneExpiredTokens()
+        return { detail: { removed } }
+      },
+    },
+
+    {
+      id: 'ratelimits.prune',
+      title: 'Prune rate-limit counters',
+      titleKey: 'adminSystem.task.rateLimitsPrune.title',
+      description:
+        'Drops anti-spam counters whose window has passed. They are bookkeeping ' +
+        'and grow with traffic rather than with content, so nothing is lost and ' +
+        'a busy board would otherwise keep a row per member per hour forever.',
+      descriptionKey: 'adminSystem.task.rateLimitsPrune.description',
+      intervalSeconds: 3600,
+      maxDurationSeconds: 30,
+      async run() {
+        const removed = await workers.pruneRateLimits()
+        return { detail: { removed } }
+      },
+    },
+
+    {
+      id: 'authevents.prune',
+      title: 'Prune sign-in activity',
+      titleKey: 'adminSystem.task.authEventsPrune.title',
+      description:
+        'Drops sign-in activity older than the retention the board is set to ' +
+        'keep. Does nothing at all while that setting is 0, which is the ' +
+        'default: the log is an audit trail, and one that expires without ' +
+        'being asked to is worse than one that grows.',
+      descriptionKey: 'adminSystem.task.authEventsPrune.description',
+      intervalSeconds: 3600,
+      maxDurationSeconds: 30,
+      async run() {
+        const removed = await workers.pruneAuthEvents()
+        return { detail: { removed } }
+      },
+    },
+
+    {
+      id: 'counters.reconcile',
+      title: 'Reconcile denormalised counters',
+      titleKey: 'adminSystem.task.countersReconcile.title',
+      description:
+        'Recomputes forum and thread counters from source rows. Counters are ' +
+        'maintained incrementally on the write path for speed; this is the ' +
+        'safety net that repairs drift from a crashed request or a bad import. ' +
+        'Idempotent by construction — it writes a computed truth, not a delta.',
+      descriptionKey: 'adminSystem.task.countersReconcile.description',
+      intervalSeconds: 21_600,
+      maxDurationSeconds: 60,
+      async run() {
+        const corrected = await workers.reconcileCounters(500)
+        return { detail: { corrected } }
+      },
+    },
+
+    {
+      id: 'views.flush',
+      title: 'Flush buffered thread views',
+      titleKey: 'adminSystem.task.viewsFlush.title',
+      description:
+        'Applies buffered view counts to their threads. Views are buffered on ' +
+        'the write path so a busy thread does not rewrite the row behind the ' +
+        'listing index on every page view; this is where they land. Bounded, ' +
+        'and a skipped run only delays the numbers.',
+      descriptionKey: 'adminSystem.task.viewsFlush.description',
+      intervalSeconds: 300,
+      maxDurationSeconds: 30,
+      async run() {
+        const flushed = await workers.flushThreadViews(500)
+        return { detail: { flushed } }
+      },
+    },
+
+    {
+      id: 'posts.render_backfill',
+      title: 'Re-render stale post bodies',
+      titleKey: 'adminSystem.task.postsRenderBackfill.title',
+      description:
+        'Rewrites the stored HTML of posts rendered by an older version of the ' +
+        'renderer, and converts any body still stored as BBCode. A stale render ' +
+        'is rendered live on read, so this never gates correctness — it stops a renderer ' +
+        'change, or an import that wrote none, from making every thread page ' +
+        'pay for it. Idempotent, and its own progress marker is the row.',
+      descriptionKey: 'adminSystem.task.postsRenderBackfill.description',
+      intervalSeconds: 600,
+      maxDurationSeconds: 45,
+      async run() {
+        const rendered = await workers.backfillPostRenders(200)
+        return { detail: { rendered } }
+      },
+    },
+
+    {
+      id: 'search.reindex',
+      title: 'Build the search index for posts that have none',
+      titleKey: 'adminSystem.task.searchReindex.title',
+      description:
+        'Writes the search document for posts that were never indexed, or were ' +
+        'indexed under an older definition of it. The write path indexes every post ' +
+        'it creates, so this is only ever a catch-up: an import, a seeded board, a ' +
+        'board adopting search, or a release that changed what the document holds.',
+      descriptionKey: 'adminSystem.task.searchReindex.description',
+      intervalSeconds: 600,
+      maxDurationSeconds: 45,
+      async run() {
+        const indexed = await workers.reindexSearch(200)
+        return { detail: { indexed } }
+      },
+    },
+
+    {
+      id: 'marketplace.refresh_catalog',
+      title: 'Refresh the plugin and theme catalog',
+      titleKey: 'adminSystem.task.marketplaceRefreshCatalog.title',
+      description:
+        'Fetches the marketplace feed, validates it and caches it for the admin ' +
+        "panel's Browse tab, then notifies administrators once per plugin version " +
+        'that becomes available for the first time. A board with no outbound network ' +
+        'fails this quietly — logged, not alarmed — and the Browse tab falls back to a ' +
+        'plain note that the catalog is unreachable.',
+      descriptionKey: 'adminSystem.task.marketplaceRefreshCatalog.description',
+      intervalSeconds: 86_400,
+      maxDurationSeconds: 30,
+      async run() {
+        const { ok, listingCount, notified } = await workers.refreshMarketplaceCatalog()
+        return { detail: { ok: ok ? 1 : 0, listingCount, notified } }
+      },
+    },
+
+    {
+      id: 'promotions.apply',
+      title: 'Apply group promotions',
+      titleKey: 'adminSystem.task.promotionsApply.title',
+      description:
+        'Moves users into groups whose promotion criteria they now meet. ' +
+        'Evaluates current post counts and registration age rather than tracking ' +
+        'thresholds crossed, so a missed run catches up on the next tick.',
+      descriptionKey: 'adminSystem.task.promotionsApply.description',
+      intervalSeconds: 21_600,
+      maxDurationSeconds: 60,
+      async run() {
+        const promoted = await workers.applyPromotions(500)
+        return { detail: { promoted } }
+      },
+    },
+
+    {
+      id: 'bans.expire',
+      title: 'Expire temporary bans',
+      titleKey: 'adminSystem.task.bansExpire.title',
+      description:
+        'Lifts bans whose expiry has passed, restoring each user to the group ' +
+        'they held when banned. Acts on outstanding state rather than on what ' +
+        'expired since the last run, so a skipped day costs a delay and nothing ' +
+        'else, and a doubled tick lifts nothing twice.',
+      descriptionKey: 'adminSystem.task.bansExpire.description',
+      intervalSeconds: 900,
+      maxDurationSeconds: 30,
+      async run() {
+        const lifted = await workers.expireBans(200)
+        return { detail: { lifted } }
+      },
+    },
+
+    {
+      id: 'groups.expire',
+      title: 'Expire timed group memberships',
+      titleKey: 'adminSystem.task.groupsExpire.title',
+      description:
+        'Deletes secondary group memberships whose expiry has passed and bumps ' +
+        'the permission version so derived caches follow. Actor assembly already ' +
+        'excludes a lapsed row, so access ended on time regardless — this tidies ' +
+        'the table rather than enforcing the boundary, and a doubled tick ' +
+        'deletes nothing twice.',
+      descriptionKey: 'adminSystem.task.groupsExpire.description',
+      intervalSeconds: 900,
+      maxDurationSeconds: 30,
+      async run() {
+        const removed = await workers.expireGroupMemberships(200)
+        return { detail: { removed } }
+      },
+    },
+
+    {
+      id: 'warnings.expire',
+      title: 'Expire warnings',
+      titleKey: 'adminSystem.task.warningsExpire.title',
+      description:
+        'Recomputes the points total of every member whose cached total still ' +
+        'counts a warning that has passed its expiry date, and re-evaluates the ' +
+        'restriction their level implies — which is how a suspension ends when ' +
+        'the warning behind it ages out. The live-warning predicate already ' +
+        'excludes an expired row, so this corrects the cache rather than ' +
+        'creating truth: a board whose tick has been down still reports honest ' +
+        'totals the moment anything recalculates.',
+      descriptionKey: 'adminSystem.task.warningsExpire.description',
+      intervalSeconds: 3_600,
+      maxDurationSeconds: 60,
+      async run() {
+        const expired = await workers.expireWarnings(200)
+        return { detail: { expired } }
+      },
+    },
+    {
+      id: 'subscriptions.instant',
+      title: 'Notify subscribers',
+      titleKey: 'adminSystem.task.subscriptionsInstant.title',
+      description:
+        'Tells members who follow a thread or forum "as it happens" about ' +
+        'posts that have arrived since they were last told. Runs on the ' +
+        'shortest interval the scheduler has, which is what "instant" means ' +
+        'here: fanning out inside the posting request would put an unbounded ' +
+        "loop — one permission check per subscriber — on the board's hottest " +
+        'write, and couple posting to the mail provider being up. Each ' +
+        'subscription carries a watermark, so a skipped tick delays a ' +
+        'notification and never loses one — which is also what lets it stop ' +
+        'between members when its budget is spent.',
+      descriptionKey: 'adminSystem.task.subscriptionsInstant.description',
+      intervalSeconds: 60,
+      maxDurationSeconds: 45,
+      async run({ signal }) {
+        const notified = await workers.notifySubscribers(50, signal)
+        return { detail: { notified } }
+      },
+    },
+
+    {
+      id: 'subscriptions.digest',
+      title: 'Send subscription digests',
+      titleKey: 'adminSystem.task.subscriptionsDigest.title',
+      description:
+        'Sends the daily and weekly digests that are due. The clock is per ' +
+        'member and per cadence rather than per run, so somebody who ' +
+        'subscribed on Sunday gets their first weekly digest a week later — ' +
+        'not at whatever moment the board tick happened to fire. Hourly, ' +
+        'because a digest that is due is a query that finds nobody most of the ' +
+        'time, and asking often is what keeps "daily" within an hour of the ' +
+        'same time each day.',
+      descriptionKey: 'adminSystem.task.subscriptionsDigest.description',
+      intervalSeconds: 3_600,
+      maxDurationSeconds: 60,
+      async run({ signal }) {
+        const notified = await workers.sendDigests(50, signal)
+        return { detail: { notified } }
+      },
+    },
+
+    {
+      id: 'attachments.sweep',
+      title: 'Collect abandoned attachment files',
+      titleKey: 'adminSystem.task.attachmentsSweep.title',
+      description:
+        'Deletes objects in the file store that nothing owns, and fails ' +
+        'uploads whose re-encoding never finished. An object key is recorded ' +
+        'before its bytes are written and forgotten when a row takes ownership, ' +
+        'so what this collects is exactly what a crash between those two steps ' +
+        'left behind — a question that is an indexed query here and a full ' +
+        'bucket listing anywhere else. Purely subtractive, and bounded by a ' +
+        'grace period, so an upload in flight is never collected out from ' +
+        'under itself.',
+      descriptionKey: 'adminSystem.task.attachmentsSweep.description',
+      intervalSeconds: 3_600,
+      maxDurationSeconds: 60,
+      async run() {
+        const { deleted, failed } = await workers.sweepAttachments(200)
+        return { detail: { deleted, failed } }
+      },
+    },
+
+    {
+      id: 'avatars.sweep',
+      title: 'Fail unfinished avatar uploads',
+      titleKey: 'adminSystem.task.avatarsSweep.title',
+      description:
+        'Marks avatar uploads whose re-encode never finished, so the member is ' +
+        'told to try again rather than left looking at a spinner that is not ' +
+        'there. Separate from the attachment sweep because it acts on `users` ' +
+        'rather than on the object ledger, and because an operator asking why ' +
+        'an avatar is stuck should not have to read a task about attachments. ' +
+        'Purely corrective, and safe to run twice.',
+      descriptionKey: 'adminSystem.task.avatarsSweep.description',
+      intervalSeconds: 3_600,
+      maxDurationSeconds: 60,
+      async run() {
+        const failed = await workers.sweepAvatars(200)
+        return { detail: { failed } }
+      },
+    },
+
+    {
+      id: 'stats.rollup',
+      title: 'Roll up board statistics',
+      titleKey: 'adminSystem.task.statsRollup.title',
+      description:
+        'Recomputes the board totals shown on the index and raises the ' +
+        '"most ever online" record when the current count has beaten it. The ' +
+        'totals are computed here rather than per page view because the member ' +
+        'count is a count of `users`, and the index is the most-requested page ' +
+        'on the board. The page shows when this last ran, so a number ten ' +
+        'minutes old is honest rather than wrong. Writes a computed truth, not ' +
+        'a delta, so a skipped tick costs freshness and a doubled one costs ' +
+        'nothing.',
+      descriptionKey: 'adminSystem.task.statsRollup.description',
+      intervalSeconds: 300,
+      maxDurationSeconds: 30,
+      async run() {
+        const { memberCount, online, record } = await workers.rollUpStatistics()
+        return { detail: { memberCount, online, record: record ? 1 : 0 } }
+      },
+    },
+  ]
+}
+
+const REQUIRED_WORKER: Readonly<Record<string, keyof TaskWorkers>> = {
+  'outbox.relay': 'relayOutbox',
+  'webhooks.deliver': 'deliverWebhooks',
+  'queue.drain': 'drainQueue',
+  'sessions.prune': 'pruneSessions',
+  'tokens.prune': 'pruneExpiredTokens',
+  'ratelimits.prune': 'pruneRateLimits',
+  'authevents.prune': 'pruneAuthEvents',
+  'counters.reconcile': 'reconcileCounters',
+  'views.flush': 'flushThreadViews',
+  'posts.render_backfill': 'backfillPostRenders',
+  'search.reindex': 'reindexSearch',
+  'marketplace.refresh_catalog': 'refreshMarketplaceCatalog',
+  'promotions.apply': 'applyPromotions',
+  'bans.expire': 'expireBans',
+  'groups.expire': 'expireGroupMemberships',
+  'warnings.expire': 'expireWarnings',
+  'subscriptions.instant': 'notifySubscribers',
+  'subscriptions.digest': 'sendDigests',
+  'attachments.sweep': 'sweepAttachments',
+  'avatars.sweep': 'sweepAvatars',
+  'stats.rollup': 'rollUpStatistics',
+}
+
+export function builtinTasks(workers: Partial<TaskWorkers>): TaskDefinition[] {
+  const supplied = workers as TaskWorkers
+  return allDefinitions(supplied).filter(
+    (task) => typeof supplied[REQUIRED_WORKER[task.id] as keyof TaskWorkers] === 'function',
+  )
+}

package/src/health.ts

@@ -0,0 +1,62 @@
+export interface TaskHealthInput {
+  readonly key: string
+  readonly intervalSeconds: number
+  readonly enabled: boolean
+  readonly lastRunAt: Date | null
+  readonly nextRunAt: Date | null
+  readonly consecutiveFailures: number
+}
+
+export type TaskHealthStatus = 'healthy' | 'late' | 'stale' | 'failing' | 'disabled' | 'never-run'
+
+export interface TaskHealth extends TaskHealthInput {
+  readonly status: TaskHealthStatus
+  readonly ageSeconds: number | null
+  readonly intervalsLate: number
+}
+
+export const STALE_INTERVALS = 3
+
+export const FAILING_THRESHOLD = 3
+
+export function assessTask(task: TaskHealthInput, now: Date): TaskHealth {
+  const ageSeconds =
+    task.lastRunAt === null
+      ? null
+      : Math.max(0, Math.floor((now.getTime() - task.lastRunAt.getTime()) / 1000))
+
+  const interval = Math.max(1, task.intervalSeconds)
+  const intervalsLate = ageSeconds === null ? 0 : Math.floor(ageSeconds / interval)
+
+  const status = ((): TaskHealthStatus => {
+    if (!task.enabled) return 'disabled'
+    if (task.consecutiveFailures >= FAILING_THRESHOLD) return 'failing'
+    if (task.lastRunAt === null) return 'never-run'
+    if (intervalsLate >= STALE_INTERVALS) return 'stale'
+    if (intervalsLate >= 1) return 'late'
+    return 'healthy'
+  })()
+
+  return { ...task, status, ageSeconds, intervalsLate }
+}
+
+export interface SchedulerHealth {
+  readonly tasks: readonly TaskHealth[]
+  readonly schedulerStopped: boolean
+  readonly stale: number
+  readonly failing: number
+}
+
+export function assessScheduler(tasks: readonly TaskHealthInput[], now: Date): SchedulerHealth {
+  const assessed = tasks.map((task) => assessTask(task, now))
+  const enabled = assessed.filter((task) => task.status !== 'disabled')
+
+  return {
+    tasks: assessed,
+    schedulerStopped:
+      enabled.length > 0 &&
+      enabled.every((task) => task.status === 'stale' || task.status === 'never-run'),
+    stale: assessed.filter((task) => task.status === 'stale').length,
+    failing: assessed.filter((task) => task.status === 'failing').length,
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { builtinTasks, type TaskWorkers } from './builtin'
+export {
+  assessScheduler,
+  assessTask,
+  FAILING_THRESHOLD,
+  type SchedulerHealth,
+  STALE_INTERVALS,
+  type TaskHealth,
+  type TaskHealthInput,
+  type TaskHealthStatus,
+} from './health'
+export {
+  type TaskRepository,
+  type TickDeps,
+  type TickOutcome,
+  tick,
+} from './scheduler'
+export type {
+  TaskContext,
+  TaskDefinition,
+  TaskResult,
+  TaskRunRecord,
+} from './types'

package/src/scheduler.ts

@@ -0,0 +1,129 @@
+import type { TaskContext, TaskDefinition, TaskResult } from './types'
+
+export interface TaskRepository {
+  claim(input: {
+    taskId: string
+    now: Date
+    staleBefore: Date
+  }): Promise<{ previousLastRunAt: Date | null } | null>
+
+  release(input: {
+    taskId: string
+    finishedAt: Date
+    success: boolean
+    detail?: Record<string, unknown>
+    error?: string
+  }): Promise<void>
+
+  ensureRegistered(tasks: readonly { id: string; intervalSeconds: number }[]): Promise<void>
+}
+
+export interface TickOutcome {
+  taskId: string
+  status: 'ran' | 'skipped' | 'failed'
+  durationMs: number
+  overran?: true
+  detail?: Record<string, unknown>
+  error?: string
+}
+
+export interface TickDeps {
+  repository: TaskRepository
+  tasks: readonly TaskDefinition[]
+  now?: Date
+  staleClaimSeconds?: number
+  onError?: (taskId: string, error: unknown) => void
+  signal?: AbortSignal
+}
+
+export async function tick({
+  repository,
+  tasks,
+  now = new Date(),
+  staleClaimSeconds = 900,
+  onError,
+  signal,
+}: TickDeps): Promise<TickOutcome[]> {
+  await repository.ensureRegistered(
+    tasks.map((t) => ({ id: t.id, intervalSeconds: t.intervalSeconds })),
+  )
+
+  const outcomes: TickOutcome[] = []
+  const staleBefore = new Date(now.getTime() - staleClaimSeconds * 1000)
+
+  for (const task of tasks) {
+    const startedAt = Date.now()
+
+    if (signal?.aborted === true) {
+      outcomes.push({ taskId: task.id, status: 'skipped', durationMs: 0 })
+      continue
+    }
+
+    const claim = await repository.claim({ taskId: task.id, now, staleBefore })
+
+    if (!claim) {
+      outcomes.push({ taskId: task.id, status: 'skipped', durationMs: 0 })
+      continue
+    }
+
+    const budget = new AbortController()
+    const timeout = setTimeout(
+      () => budget.abort(new Error(`Task "${task.id}" exceeded its budget`)),
+      task.maxDurationSeconds * 1000,
+    )
+
+    const elapsedSince = () => new Date(now.getTime() + (Date.now() - startedAt))
+
+    try {
+      const elapsedSeconds = claim.previousLastRunAt
+        ? Math.max(0, (now.getTime() - claim.previousLastRunAt.getTime()) / 1000)
+        : task.intervalSeconds
+
+      const context: TaskContext = {
+        now,
+        lastRunAt: claim.previousLastRunAt,
+        elapsedSeconds,
+        signal: signal === undefined ? budget.signal : AbortSignal.any([signal, budget.signal]),
+      }
+
+      const result: TaskResult = await task.run(context)
+
+      await repository.release({
+        taskId: task.id,
+        finishedAt: elapsedSince(),
+        success: true,
+        ...(result.detail ? { detail: result.detail } : {}),
+      })
+
+      outcomes.push({
+        taskId: task.id,
+        status: 'ran',
+        durationMs: Date.now() - startedAt,
+        ...(budget.signal.aborted ? { overran: true as const } : {}),
+        ...(result.detail ? { detail: result.detail } : {}),
+      })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      onError?.(task.id, error)
+
+      await repository.release({
+        taskId: task.id,
+        finishedAt: elapsedSince(),
+        success: false,
+        error: message,
+      })
+
+      outcomes.push({
+        taskId: task.id,
+        status: 'failed',
+        durationMs: Date.now() - startedAt,
+        ...(budget.signal.aborted ? { overran: true as const } : {}),
+        error: message,
+      })
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  return outcomes
+}

package/src/types.ts

@@ -0,0 +1,30 @@
+export interface TaskContext {
+  now: Date
+  lastRunAt: Date | null
+  elapsedSeconds: number
+  signal: AbortSignal
+}
+
+export interface TaskResult {
+  detail?: Record<string, number | string>
+}
+
+export interface TaskDefinition {
+  readonly id: string
+  readonly title: string
+  readonly description: string
+  readonly titleKey?: string
+  readonly descriptionKey?: string
+  readonly intervalSeconds: number
+  readonly maxDurationSeconds: number
+  run(context: TaskContext): Promise<TaskResult>
+}
+
+export interface TaskRunRecord {
+  taskId: string
+  startedAt: Date
+  finishedAt: Date | null
+  success: boolean | null
+  detail: Record<string, unknown> | null
+  error: string | null
+}