Deduplicate custom background tasks

AGENTS.md

@@ -127,11 +127,18 @@ Development workflow
  -  **Code Generation**: Run `mise run codegen` whenever vocabulary YAML files
     or code generation scripts change.
  -  **Building Packages**: After installation, all packages are automatically
-    built. To rebuild a specific package and its dependencies, run `pnpm build`
-    in that package's directory.
- -  **Checking Code**: Run `mise run check` before committing.
- -  **Running Tests**: Use `mise run test:deno` for Deno tests or
-    `mise run test` for all environments.
+    built. To rebuild a specific package and its dependencies, run
+    `mise run prepare`, or run `mise run prepare-each <pkgs>` to build
+    specific packages.
+ -  **Checking Code**: Run `mise run check` before committing, or run
+    `mise run check-each <pkgs>` to check specific packages.
+ -  **Running Tests**:
+     -  `mise run test`: Executes all the tests in every runtime.
+     -  `mise run test:<runtime:deno,node,bun>`: Executes all the tests by the
+        runtime. If some specific tests are needed, execute
+        `mise run test:<runtime> <test-file-path-from-the-root>`.
+     -  `mise run test-each <pkgs>`: Executes tests in packages that include
+        `pkgs` in every runtime.
 
 For detailed contribution guidelines, see *CONTRIBUTING.md*.
 
@@ -151,6 +158,13 @@ When working with federation code:
 Common tasks
 ------------
 
+### **BE WELL-ACQUAINTED WITH `mise tasks`**
+
+*mise.toml* has useful tasks. **Acquaint all of them** and use them in the right
+place at the right time. If it has too much information, use `mise tasks`. This
+command shows the summary of the tasks and descriptions. If `mise tasks` does
+not make it clear, use `mise tasks <task>` to check the details for the task.
+
 ### Adding ActivityPub vocabulary types
 
 1.  Create a new YAML file in *packages/vocab/vocab/* following existing

CHANGES.md

@@ -259,6 +259,47 @@ To be released.
     the dispatcher overload hot path; other contributors to `check-all` cost
     may remain.  [[#613], [#800] by ChanHaeng Lee]
 
+ -  Added a custom background task API that generalizes Fedify's
+    enqueue-and-process-later pattern to arbitrary application-defined jobs:
+
+     -  `Federation` and `FederationBuilder` gained a `defineTask()` method
+        through the new `TaskRegistry` interface, which `Federatable` now
+        extends.
+     -  `Context` gained `enqueueTask()` and `enqueueTaskMany()` methods,
+        with `delay` and `orderingKey` options
+        (new `TaskEnqueueOptions` interface).
+     -  Every task requires a [Standard Schema]
+        (`schema` option) from which the payload type is inferred; payloads
+        are validated at enqueue time (fail fast) and again at dequeue time
+        (protection against schema drift across deployments).
+     -  Payloads are serialized by Fedify with devalue, so `Date`, `Map`,
+        `Set`, `URL`, `bigint`, circular references, and Activity Vocabulary
+        objects round-trip faithfully across every message queue backend.
+     -  Failed handlers are retried with exponential backoff by default;
+        tasks support per-task `retryPolicy` and `onError` options, the new
+        `FederationOptions.taskRetryPolicy` sets the federation-wide default,
+        and queues with `nativeRetrial` delegate retries to the backend.
+     -  Tasks can be isolated from activity delivery through the new
+        `FederationQueueOptions.task` slot or a per-task `queue` option;
+        without them, tasks fall back to the outbox queue unless the new
+        `FederationOptions.taskQueueResolution` option is set to `"strict"`.
+        `Federation.startQueue()` now accepts `queue: "task"` to run
+        a task-only worker.
+     -  Tasks can request at-most-once enqueue with a `deduplicationKey`
+        (new `TaskEnqueueOptions.deduplicationKey`).  A queue declaring the new
+        `MessageQueue.nativeDeduplication` capability owns the check and
+        receives the key through the new
+        `MessageQueueEnqueueOptions.deduplicationKey`; otherwise Fedify
+        performs a best-effort key–value guard through the optional
+        `KvStore.cas` primitive, under a new `taskDeduplication` key prefix.
+        The marker TTL and the no-`cas` fallback are tunable with the new
+        `FederationOptions.taskDeduplicationTtl` and
+        `FederationOptions.taskDeduplicationFallback` options.
+
+    [[#206], [#797], [#798], [#803] by ChanHaeng Lee]
+
+[Standard Schema]: https://standardschema.dev/
+[#206]: https://github.com/fedify-dev/fedify/issues/206
 [#316]: https://github.com/fedify-dev/fedify/issues/316
 [#418]: https://github.com/fedify-dev/fedify/issues/418
 [#613]: https://github.com/fedify-dev/fedify/issues/613
@@ -288,7 +329,10 @@ To be released.
 [#778]: https://github.com/fedify-dev/fedify/pull/778
 [#782]: https://github.com/fedify-dev/fedify/issues/782
 [#787]: https://github.com/fedify-dev/fedify/pull/787
+[#797]: https://github.com/fedify-dev/fedify/issues/797
+[#798]: https://github.com/fedify-dev/fedify/issues/798
 [#800]: https://github.com/fedify-dev/fedify/pull/800
+[#803]: https://github.com/fedify-dev/fedify/pull/803
 
 ### @fedify/cli
 

docs/.vitepress/config.mts

@@ -145,6 +145,7 @@ const MANUAL = {
     { text: "Pragmatics", link: "/manual/pragmatics.md" },
     { text: "Key–value store", link: "/manual/kv.md" },
     { text: "Message queue", link: "/manual/mq.md" },
+    { text: "Background tasks", link: "/manual/tasks.md" },
     { text: "Circuit breaker", link: "/manual/circuit-breaker.md" },
     { text: "Integration", link: "/manual/integration.md" },
     { text: "Migration", link: "/manual/migrate.md" },