@fedify/fedify 2.4.0-dev.1490 → 2.4.0-dev.1508

package/dist/{context-BU6jSQdo.d.ts → context-BF5B4ZDk.d.ts}

@@ -3,13 +3,14 @@ import { o as JsonValue, s as NodeInfo, t as GetNodeInfoOptions } from "./client
 import { o as VerifyRequestFailureReason, t as HttpMessageSignaturesSpec } from "./http-lf8Hsd91.js";
 import { n as GetKeyOwnerOptions } from "./owner-CnngXDNJ.js";
 import { n as KvStore, t as KvKey } from "./kv-D6hNiMTK.js";
-import { r as MessageQueue } from "./mq-D-nlpY04.js";
+import { r as MessageQueue } from "./mq-B5_hohs7.js";
 import { Router } from "@fedify/uri-template";
 import { Activity, Actor, Collection, CryptographicKey, Hashtag, Link, LookupObjectOptions, Multikey, Object as Object$1, Recipient, Tombstone, TraverseCollectionOptions } from "@fedify/vocab";
 import { MeterProvider, Span, Tracer, TracerProvider } from "@opentelemetry/api";
 import { AuthenticatedDocumentLoaderFactory, DocumentLoader, DocumentLoaderFactory, GetUserAgentOptions } from "@fedify/vocab-runtime";
 import { Link as Link$1, LookupWebFingerOptions, ResourceDescriptor } from "@fedify/webfinger";
 import { MeterProvider as MeterProvider$1, MetricReader } from "@opentelemetry/sdk-metrics";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/compat/types.d.ts
 /**
@@ -18,177 +19,6 @@ import { MeterProvider as MeterProvider$1, MetricReader } from "@opentelemetry/s
 */
 type ActivityTransformer<TContextData> = (activity: Activity, context: Context<TContextData>) => Activity;
 //#endregion
-//#region src/federation/circuit-breaker.d.ts
-/**
-* The state of a remote host circuit breaker.
-* @since 2.3.0
-*/
-type CircuitBreakerState = "closed" | "open" | "half-open";
-/**
-* The JSON-serializable state stored in the configured {@link KvStore}.
-* @since 2.3.0
-*/
-interface CircuitBreakerKvState {
-  readonly state: CircuitBreakerState;
-  readonly failures: readonly string[];
-  readonly opened?: string;
-  readonly halfOpened?: string;
-}
-/**
-* Details passed to {@link CircuitBreakerOptions.onActivityDrop} when a held
-* activity expires before the remote host recovers.
-* @since 2.3.0
-*/
-interface CircuitBreakerActivityDrop {
-  /** The inbox URL that would have received the activity. */
-  readonly inbox: URL;
-  /** The activity that was dropped. */
-  readonly activity: Activity;
-  /** The activity ID, when known. */
-  readonly activityId?: string;
-  /** The activity type. */
-  readonly activityType: string;
-  /** The actor IDs represented by this inbox. */
-  readonly actorIds: readonly URL[];
-  /** The time when Fedify first held this activity. */
-  readonly heldSince: Temporal.Instant;
-}
-/**
-* Configures how a remote host circuit opens after repeated delivery
-* failures.
-* @since 2.3.0
-*/
-type CircuitBreakerFailurePolicy = {
-  failure(timestamps: readonly Temporal.Instant[]): boolean;
-  readonly failureThreshold?: never;
-  readonly failureWindow?: never;
-} | {
-  readonly failure?: never;
-  readonly failureThreshold?: number;
-  readonly failureWindow?: Temporal.Duration | Temporal.DurationLike;
-};
-/**
-* Options for Fedify's outbound activity circuit breaker.
-* @since 2.3.0
-*/
-type CircuitBreakerOptions = CircuitBreakerFailurePolicy & {
-  /**
-  * How long an open circuit waits before allowing a half-open recovery probe.
-  * @default `{ minutes: 30 }`
-  */
-  readonly recoveryDelay?: Temporal.Duration | Temporal.DurationLike;
-  /**
-  * How long Fedify keeps requeueing activities held by an open circuit before
-  * dropping them.
-  * @default `{ days: 7 }`
-  */
-  readonly heldActivityTtl?: Temporal.Duration | Temporal.DurationLike;
-  /**
-  * How often other held activities retry while a half-open probe is in
-  * flight.  The probe is treated as stale after the recovery delay.
-  * @default `{ seconds: 1 }`
-  */
-  readonly releaseInterval?: Temporal.Duration | Temporal.DurationLike;
-  /**
-  * Called whenever the circuit state changes.
-  */
-  readonly onStateChange?: (remoteHost: string, previousState: CircuitBreakerState, newState: CircuitBreakerState) => void | Promise<void>;
-  /**
-  * Called when an activity held by the circuit breaker expires.
-  */
-  readonly onActivityDrop?: (remoteHost: string, details: CircuitBreakerActivityDrop) => void | Promise<void>;
-};
-/**
-* Normalized circuit breaker options used internally by Fedify.
-* @internal
-*/
-interface NormalizedCircuitBreakerOptions {
-  readonly failure: (timestamps: readonly Temporal.Instant[]) => boolean;
-  readonly pruneFailures: (timestamps: readonly Temporal.Instant[], now: Temporal.Instant) => readonly Temporal.Instant[];
-  readonly recoveryDelay: Temporal.Duration;
-  readonly heldActivityTtl: Temporal.Duration;
-  readonly releaseInterval: Temporal.Duration;
-  readonly onStateChange?: CircuitBreakerOptions["onStateChange"];
-  readonly onActivityDrop?: CircuitBreakerOptions["onActivityDrop"];
-}
-/**
-* Constructor options for {@link CircuitBreaker}.
-* @internal
-*/
-interface CircuitBreakerCreateOptions {
-  readonly kv: KvStore;
-  readonly prefix: KvKey;
-  readonly options?: CircuitBreakerOptions;
-  readonly now?: () => Temporal.Instant;
-  /**
-  * Observes state changes after user callbacks have run.
-  * @internal
-  */
-  readonly stateChangeObserver?: (remoteHost: string, previousState: CircuitBreakerState, newState: CircuitBreakerState) => void | Promise<void>;
-}
-/**
-* The delivery decision returned by {@link CircuitBreaker.beforeSend}.
-* @internal
-*/
-type CircuitBreakerBeforeSendDecision = {
-  readonly type: "send";
-  readonly probe: boolean;
-  readonly stateChange?: CircuitBreakerStateChange;
-} | {
-  readonly type: "hold";
-  readonly state: "open" | "half-open";
-  readonly delay: Temporal.Duration;
-  readonly heldSince: Temporal.Instant;
-} | {
-  readonly type: "drop";
-  readonly heldSince: Temporal.Instant;
-};
-/**
-* A circuit breaker state transition.
-* @since 2.3.0
-*/
-interface CircuitBreakerStateChange {
-  readonly previousState: CircuitBreakerState;
-  readonly newState: CircuitBreakerState;
-}
-/**
-* Tracks reachability state for remote outbox delivery hosts.
-* @since 2.3.0
-*/
-declare class CircuitBreaker {
-  #private;
-  constructor(options: CircuitBreakerCreateOptions);
-  get options(): NormalizedCircuitBreakerOptions;
-  capHeldDelay(heldSince: Temporal.Instant, delay: Temporal.Duration): Temporal.Duration;
-  beforeSend(remoteHost: string, message: {
-    readonly circuitHeldSince?: string;
-  }): Promise<CircuitBreakerBeforeSendDecision>;
-  recordSuccess(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
-  recordReachableFailure(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
-  recordFailure(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
-  dropActivity(remoteHost: string, details: CircuitBreakerActivityDrop): Promise<void>;
-  getState(remoteHost: string): Promise<CircuitBreakerKvState | undefined>;
-}
-/**
-* Normalizes user-provided circuit breaker options into the internal policy
-* shape used while processing queued outbox deliveries.
-*
-* @param options The public circuit breaker options supplied to Fedify.
-* @returns The normalized failure predicate, failure pruning function,
-* duration values, and optional callbacks with defaults applied.
-* @throws {RangeError} If any configured duration is not positive.
-* @throws {TypeError} If `failureThreshold` is not a positive integer.
-*/
-declare function normalizeCircuitBreakerOptions(options: CircuitBreakerOptions): NormalizedCircuitBreakerOptions;
-/**
-* Parses a value loaded from the circuit breaker KV store.
-*
-* @param value The raw KV value to validate.
-* @returns A circuit breaker state when `value` has a recognized state and
-* valid instant strings, or `undefined` when the stored value is malformed.
-*/
-declare function parseCircuitBreakerKvState(value: unknown): CircuitBreakerKvState | undefined;
-//#endregion
 //#region src/federation/collection.d.ts
 /**
 * A page of items.
@@ -555,28 +385,199 @@ type ObjectAuthorizePredicate<TContextData, TParam extends string> = (context: R
 */
 type CustomCollectionDispatcher<TItem, TParam extends string, TContext extends Context<TContextData>, TContextData> = (context: TContext, values: Record<TParam, string>, cursor: string | null) => PageItems<TItem> | null | Promise<PageItems<TItem> | null>;
 /**
-* A callback that counts the number of items in a custom collection.
+* A callback that counts the number of items in a custom collection.
+*
+* @template TParams The parameter names of the requested URL.
+* @template TContextData The context data to pass to the {@link Context}.
+* @param context The context.
+* @param values The parameters of the requested URL.
+* @since 1.8.0
+*/
+type CustomCollectionCounter<TParam extends string, TContextData> = (context: RequestContext<TContextData>, values: Record<TParam, string>) => number | bigint | null | Promise<number | bigint | null>;
+/**
+* A callback that returns a cursor for a custom collection.
+*
+* @template TParams The parameter names of the requested URL.
+* @template TContext The type of the context. {@link Context} or
+*                     {@link RequestContext}.
+* @template TContextData The context data to pass to the {@link Context}.
+* @template TFilter The type of the filter, if any.
+* @param context The context.
+* @param values The parameters of the requested URL.
+* @since 1.8.0
+*/
+type CustomCollectionCursor<TParam extends string, TContext extends Context<TContextData>, TContextData> = (context: TContext, values: Record<TParam, string>) => string | null | Promise<string | null>;
+//#endregion
+//#region src/federation/circuit-breaker.d.ts
+/**
+* The state of a remote host circuit breaker.
+* @since 2.3.0
+*/
+type CircuitBreakerState = "closed" | "open" | "half-open";
+/**
+* The JSON-serializable state stored in the configured {@link KvStore}.
+* @since 2.3.0
+*/
+interface CircuitBreakerKvState {
+  readonly state: CircuitBreakerState;
+  readonly failures: readonly string[];
+  readonly opened?: string;
+  readonly halfOpened?: string;
+}
+/**
+* Details passed to {@link CircuitBreakerOptions.onActivityDrop} when a held
+* activity expires before the remote host recovers.
+* @since 2.3.0
+*/
+interface CircuitBreakerActivityDrop {
+  /** The inbox URL that would have received the activity. */
+  readonly inbox: URL;
+  /** The activity that was dropped. */
+  readonly activity: Activity;
+  /** The activity ID, when known. */
+  readonly activityId?: string;
+  /** The activity type. */
+  readonly activityType: string;
+  /** The actor IDs represented by this inbox. */
+  readonly actorIds: readonly URL[];
+  /** The time when Fedify first held this activity. */
+  readonly heldSince: Temporal.Instant;
+}
+/**
+* Configures how a remote host circuit opens after repeated delivery
+* failures.
+* @since 2.3.0
+*/
+type CircuitBreakerFailurePolicy = {
+  failure(timestamps: readonly Temporal.Instant[]): boolean;
+  readonly failureThreshold?: never;
+  readonly failureWindow?: never;
+} | {
+  readonly failure?: never;
+  readonly failureThreshold?: number;
+  readonly failureWindow?: Temporal.Duration | Temporal.DurationLike;
+};
+/**
+* Options for Fedify's outbound activity circuit breaker.
+* @since 2.3.0
+*/
+type CircuitBreakerOptions = CircuitBreakerFailurePolicy & {
+  /**
+  * How long an open circuit waits before allowing a half-open recovery probe.
+  * @default `{ minutes: 30 }`
+  */
+  readonly recoveryDelay?: Temporal.Duration | Temporal.DurationLike;
+  /**
+  * How long Fedify keeps requeueing activities held by an open circuit before
+  * dropping them.
+  * @default `{ days: 7 }`
+  */
+  readonly heldActivityTtl?: Temporal.Duration | Temporal.DurationLike;
+  /**
+  * How often other held activities retry while a half-open probe is in
+  * flight.  The probe is treated as stale after the recovery delay.
+  * @default `{ seconds: 1 }`
+  */
+  readonly releaseInterval?: Temporal.Duration | Temporal.DurationLike;
+  /**
+  * Called whenever the circuit state changes.
+  */
+  readonly onStateChange?: (remoteHost: string, previousState: CircuitBreakerState, newState: CircuitBreakerState) => void | Promise<void>;
+  /**
+  * Called when an activity held by the circuit breaker expires.
+  */
+  readonly onActivityDrop?: (remoteHost: string, details: CircuitBreakerActivityDrop) => void | Promise<void>;
+};
+/**
+* Normalized circuit breaker options used internally by Fedify.
+* @internal
+*/
+interface NormalizedCircuitBreakerOptions {
+  readonly failure: (timestamps: readonly Temporal.Instant[]) => boolean;
+  readonly pruneFailures: (timestamps: readonly Temporal.Instant[], now: Temporal.Instant) => readonly Temporal.Instant[];
+  readonly recoveryDelay: Temporal.Duration;
+  readonly heldActivityTtl: Temporal.Duration;
+  readonly releaseInterval: Temporal.Duration;
+  readonly onStateChange?: CircuitBreakerOptions["onStateChange"];
+  readonly onActivityDrop?: CircuitBreakerOptions["onActivityDrop"];
+}
+/**
+* Constructor options for {@link CircuitBreaker}.
+* @internal
+*/
+interface CircuitBreakerCreateOptions {
+  readonly kv: KvStore;
+  readonly prefix: KvKey;
+  readonly options?: CircuitBreakerOptions;
+  readonly now?: () => Temporal.Instant;
+  /**
+  * Observes state changes after user callbacks have run.
+  * @internal
+  */
+  readonly stateChangeObserver?: (remoteHost: string, previousState: CircuitBreakerState, newState: CircuitBreakerState) => void | Promise<void>;
+}
+/**
+* The delivery decision returned by {@link CircuitBreaker.beforeSend}.
+* @internal
+*/
+type CircuitBreakerBeforeSendDecision = {
+  readonly type: "send";
+  readonly probe: boolean;
+  readonly stateChange?: CircuitBreakerStateChange;
+} | {
+  readonly type: "hold";
+  readonly state: "open" | "half-open";
+  readonly delay: Temporal.Duration;
+  readonly heldSince: Temporal.Instant;
+} | {
+  readonly type: "drop";
+  readonly heldSince: Temporal.Instant;
+};
+/**
+* A circuit breaker state transition.
+* @since 2.3.0
+*/
+interface CircuitBreakerStateChange {
+  readonly previousState: CircuitBreakerState;
+  readonly newState: CircuitBreakerState;
+}
+/**
+* Tracks reachability state for remote outbox delivery hosts.
+* @since 2.3.0
+*/
+declare class CircuitBreaker {
+  #private;
+  constructor(options: CircuitBreakerCreateOptions);
+  get options(): NormalizedCircuitBreakerOptions;
+  capHeldDelay(heldSince: Temporal.Instant, delay: Temporal.Duration): Temporal.Duration;
+  beforeSend(remoteHost: string, message: {
+    readonly circuitHeldSince?: string;
+  }): Promise<CircuitBreakerBeforeSendDecision>;
+  recordSuccess(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
+  recordReachableFailure(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
+  recordFailure(remoteHost: string): Promise<CircuitBreakerStateChange | undefined>;
+  dropActivity(remoteHost: string, details: CircuitBreakerActivityDrop): Promise<void>;
+  getState(remoteHost: string): Promise<CircuitBreakerKvState | undefined>;
+}
+/**
+* Normalizes user-provided circuit breaker options into the internal policy
+* shape used while processing queued outbox deliveries.
 *
-* @template TParams The parameter names of the requested URL.
-* @template TContextData The context data to pass to the {@link Context}.
-* @param context The context.
-* @param values The parameters of the requested URL.
-* @since 1.8.0
+* @param options The public circuit breaker options supplied to Fedify.
+* @returns The normalized failure predicate, failure pruning function,
+* duration values, and optional callbacks with defaults applied.
+* @throws {RangeError} If any configured duration is not positive.
+* @throws {TypeError} If `failureThreshold` is not a positive integer.
 */
-type CustomCollectionCounter<TParam extends string, TContextData> = (context: RequestContext<TContextData>, values: Record<TParam, string>) => number | bigint | null | Promise<number | bigint | null>;
+declare function normalizeCircuitBreakerOptions(options: CircuitBreakerOptions): NormalizedCircuitBreakerOptions;
 /**
-* A callback that returns a cursor for a custom collection.
+* Parses a value loaded from the circuit breaker KV store.
 *
-* @template TParams The parameter names of the requested URL.
-* @template TContext The type of the context. {@link Context} or
-*                     {@link RequestContext}.
-* @template TContextData The context data to pass to the {@link Context}.
-* @template TFilter The type of the filter, if any.
-* @param context The context.
-* @param values The parameters of the requested URL.
-* @since 1.8.0
+* @param value The raw KV value to validate.
+* @returns A circuit breaker state when `value` has a recognized state and
+* valid instant strings, or `undefined` when the stored value is malformed.
 */
-type CustomCollectionCursor<TParam extends string, TContext extends Context<TContextData>, TContextData> = (context: TContext, values: Record<TParam, string>) => string | null | Promise<string | null>;
+declare function parseCircuitBreakerKvState(value: unknown): CircuitBreakerKvState | undefined;
 //#endregion
 //#region src/federation/handler.d.ts
 /**
@@ -610,6 +611,220 @@ declare function respondWithObject(object: Object$1, options?: RespondWithObject
 */
 declare function respondWithObjectIfAcceptable(object: Object$1, request: Request, options?: RespondWithObjectOptions): Promise<Response | null>;
 //#endregion
+//#region src/federation/retry.d.ts
+/**
+* The context passed to a {@link RetryPolicy} callback.
+* @since 0.12.0
+*/
+interface RetryContext {
+  /**
+  * The elapsed time since the first attempt.
+  */
+  readonly elapsedTime: Temporal.Duration;
+  /**
+  * The number of attempts so far.
+  */
+  readonly attempts: number;
+}
+/**
+* A policy that determines the delay before the next retry.
+* @param context The retry context.
+* @returns The delay before the next retry, or `null` to stop retrying.
+*          It must not negative.
+* @since 0.12.0
+*/
+type RetryPolicy = (context: RetryContext) => Temporal.Duration | null;
+/**
+* Options for {@link createExponentialBackoffPolicy} function.
+* @since 0.12.0
+*/
+interface CreateExponentialBackoffPolicyOptions {
+  /**
+  * The initial delay before the first retry.  Defaults to 1 second.
+  */
+  readonly initialDelay?: Temporal.DurationLike;
+  /**
+  * The maximum delay between retries.  Defaults to 12 hours.
+  */
+  readonly maxDelay?: Temporal.DurationLike;
+  /**
+  * The maximum number of attempts before giving up.
+  * Defaults to 10.
+  */
+  readonly maxAttempts?: number;
+  /**
+  * The factor to multiply the previous delay by for each retry.
+  * Defaults to 2.
+  */
+  readonly factor?: number;
+  /**
+  * Whether to add jitter to the delay to avoid synchronization.
+  * Turned on by default.
+  */
+  readonly jitter?: boolean;
+}
+/**
+* Creates an exponential backoff retry policy.  The delay between retries
+* starts at the `initialDelay` and is multiplied by the `factor` for each
+* subsequent retry, up to the `maxDelay`.  The policy will give up after
+* `maxAttempts` attempts.  The actual delay is randomized to avoid
+* synchronization (jitter).
+* @param options The options for the policy.
+* @returns The retry policy.
+* @since 0.12.0
+*/
+declare function createExponentialBackoffPolicy(options?: CreateExponentialBackoffPolicyOptions): RetryPolicy;
+//#endregion
+//#region src/federation/tasks/task.d.ts
+/**
+* A callback that processes a custom background task.
+* @template TContextData The context data to pass to the {@link Context}.
+* @template TData The type of the task payload, inferred from the task's
+*                 schema.
+* @param ctx The context for the worker processing the task.
+* @param data The decoded and validated task payload.
+* @since 2.4.0
+*/
+type TaskHandler<TContextData, TData> = (ctx: Context<TContextData>, data: TData) => Promise<void> | void;
+/**
+* Options for {@link TaskRegistry.defineTask}.
+* @template TContextData The context data to pass to the {@link Context}.
+* @template TSchema The [Standard Schema](https://standardschema.dev/) that
+*                   validates the task payload.
+* @since 2.4.0
+*/
+interface TaskDefinitionOptions<TContextData, TSchema extends StandardSchemaV1> {
+  /**
+  * The [Standard Schema](https://standardschema.dev/) that validates the
+  * task payload.  The payload type is inferred from this schema.
+  *
+  * The payload is validated twice: once at enqueue time (fail fast) and
+  * once at dequeue time (drift protection against payloads enqueued by an
+  * older deployment).  Because the same schema runs on both sides, its
+  * validation must be idempotent: the validated output must itself be
+  * a valid input.  Transforming schemas (e.g., Zod's `.transform()`) whose
+  * output differs in shape from their input are not supported.
+  */
+  readonly schema: TSchema;
+  /**
+  * The callback that processes the task on a background worker.
+  */
+  readonly handler: TaskHandler<TContextData, StandardSchemaV1.InferOutput<TSchema>>;
+  /**
+  * The retry policy for this task.  If omitted, the federation-wide
+  * task retry policy is used, which defaults to an exponential backoff
+  * policy.
+  */
+  readonly retryPolicy?: RetryPolicy;
+  /**
+  * A callback invoked when the {@link handler} throws an error, before
+  * a retry is scheduled.
+  * @param ctx The context for the worker processing the task.
+  * @param error The error thrown by the handler.
+  * @param data The decoded and validated task payload.
+  */
+  readonly onError?: (ctx: Context<TContextData>, error: unknown, data: StandardSchemaV1.InferOutput<TSchema>) => Promise<void> | void;
+  /**
+  * The message queue dedicated to this task.  If omitted, the task is
+  * routed to the federation-wide task queue, falling back to the outbox
+  * queue (unless `taskQueueResolution: "strict"` is configured).
+  */
+  readonly queue?: MessageQueue;
+}
+/**
+* Phantom key binding a {@link TaskDefinition} to its federation's context
+* data type.  Declared only—no value exists at runtime, and the symbol is
+* not exported, so the marker stays out of user-facing completions.
+*/
+declare const contextDataBrand: unique symbol;
+/**
+* The handle returned by {@link TaskRegistry.defineTask}.  It carries the
+* task name and schema so that {@link Context.enqueueTask} can validate the
+* payload and infer its type at every call site.
+* @template TContextData The context data to pass to the {@link Context}.
+* @template TData The type of the task payload, inferred from the task's
+*                 schema.
+* @since 2.4.0
+*/
+interface TaskDefinition<TContextData, TData> {
+  /**
+  * The unique name of the task.
+  */
+  readonly name: string;
+  /**
+  * The [Standard Schema](https://standardschema.dev/) that validates the
+  * task payload.
+  */
+  readonly schema: StandardSchemaV1<unknown, TData>;
+  /**
+  * @internal Phantom marker binding the handle to its federation.
+  */
+  readonly [contextDataBrand]?: TContextData;
+}
+/**
+* Registration of custom background tasks.  Both {@link Federation} and
+* {@link FederationBuilder} implement this interface.
+* @template TContextData The context data to pass to the {@link Context}.
+* @since 2.4.0
+*/
+interface TaskRegistry<TContextData> {
+  /**
+  * Defines a custom background task.  The returned handle is passed to
+  * {@link Context.enqueueTask} to enqueue the task.
+  *
+  * @example
+  * ``` typescript
+  * const sendDigest = federation.defineTask("sendDigest", {
+  *   schema: digestSchema,
+  *   handler: async (ctx, data) => {
+  *     // …process the payload on a background worker…
+  *   },
+  * });
+  * ```
+  *
+  * @param name The unique name of the task.
+  * @param options The task definition options.  The payload type is
+  *                inferred from `options.schema`.
+  * @returns The handle to pass to {@link Context.enqueueTask}.
+  * @throws {TypeError} If a task with the same name is already defined.
+  */
+  defineTask<TSchema extends StandardSchemaV1>(name: string, options: TaskDefinitionOptions<TContextData, TSchema>): TaskDefinition<TContextData, StandardSchemaV1.InferOutput<TSchema>>;
+}
+/**
+* Options for {@link Context.enqueueTask} and {@link Context.enqueueTaskMany}.
+* @since 2.4.0
+*/
+interface TaskEnqueueOptions {
+  /**
+  * The delay before the task is processed.  No delay by default.
+  */
+  readonly delay?: Temporal.DurationLike;
+  /**
+  * An optional key that ensures tasks with the same ordering key are
+  * processed sequentially (one at a time).
+  */
+  readonly orderingKey?: string;
+  /**
+  * An optional key requesting at-most-once enqueue for tasks that share it.
+  *
+  * A queue with {@link MessageQueue.nativeDeduplication} `true` enforces it
+  * strictly; otherwise deduplication is best-effort via {@link KvStore.cas},
+  * and {@link FederationOptions.taskDeduplicationFallback} decides whether a
+  * missing `cas` proceeds without deduplication or throws.
+  *
+  * For {@link Context.enqueueTaskMany}, one key governs the whole batch.  When
+  * deduplication is actually applied—a native queue, or the key–value
+  * fallback through {@link KvStore.cas}—a multi-item batch with a
+  * `deduplicationKey` requires the queue to implement
+  * {@link MessageQueue.enqueueMany} so it enqueues atomically, or the call
+  * throws a `TypeError`.  Under the `"open"` fallback with no `cas`, no marker
+  * is taken, so such a batch instead fans out without deduplication.
+  *
+  * @since 2.4.0
+  */
+  readonly deduplicationKey?: string;
+}
+//#endregion
 //#region src/federation/builder.d.ts
 /**
 * Creates a new {@link FederationBuilder} instance.
@@ -632,7 +847,7 @@ interface SenderKeyJwkPair {
 * type.
 * @since 1.6.0
 */
-type Message = FanoutMessage | OutboxMessage | InboxMessage;
+type Message = FanoutMessage | OutboxMessage | InboxMessage | TaskMessage;
 interface FanoutMessage {
   readonly type: "fanout";
   readonly id: ReturnType<typeof crypto.randomUUID>;
@@ -686,6 +901,24 @@ interface OutboxMessage {
   readonly circuitHeldSince?: string;
   readonly traceContext: Readonly<Record<string, string>>;
 }
+/**
+* A message that carries a custom background task.  Every field is
+* a string, number, or plain record so that the message survives both
+* JSON serialization and structured clone on every queue backend.
+* @since 2.4.0
+*/
+interface TaskMessage {
+  readonly type: "task";
+  readonly id: ReturnType<typeof crypto.randomUUID>;
+  readonly baseUrl: string;
+  readonly taskName: string;
+  /** devalue-encoded task data; vocab objects bridged to expanded JSON-LD. */
+  readonly data: string;
+  readonly started: string;
+  readonly attempt: number;
+  readonly orderingKey?: string;
+  readonly traceContext: Readonly<Record<string, string>>;
+}
 interface InboxMessage {
   readonly type: "inbox";
   readonly id: ReturnType<typeof crypto.randomUUID>;
@@ -733,70 +966,6 @@ interface InboxMessage {
   readonly traceContext: Readonly<Record<string, string>>;
 }
 //#endregion
-//#region src/federation/retry.d.ts
-/**
-* The context passed to a {@link RetryPolicy} callback.
-* @since 0.12.0
-*/
-interface RetryContext {
-  /**
-  * The elapsed time since the first attempt.
-  */
-  readonly elapsedTime: Temporal.Duration;
-  /**
-  * The number of attempts so far.
-  */
-  readonly attempts: number;
-}
-/**
-* A policy that determines the delay before the next retry.
-* @param context The retry context.
-* @returns The delay before the next retry, or `null` to stop retrying.
-*          It must not negative.
-* @since 0.12.0
-*/
-type RetryPolicy = (context: RetryContext) => Temporal.Duration | null;
-/**
-* Options for {@link createExponentialBackoffPolicy} function.
-* @since 0.12.0
-*/
-interface CreateExponentialBackoffPolicyOptions {
-  /**
-  * The initial delay before the first retry.  Defaults to 1 second.
-  */
-  readonly initialDelay?: Temporal.DurationLike;
-  /**
-  * The maximum delay between retries.  Defaults to 12 hours.
-  */
-  readonly maxDelay?: Temporal.DurationLike;
-  /**
-  * The maximum number of attempts before giving up.
-  * Defaults to 10.
-  */
-  readonly maxAttempts?: number;
-  /**
-  * The factor to multiply the previous delay by for each retry.
-  * Defaults to 2.
-  */
-  readonly factor?: number;
-  /**
-  * Whether to add jitter to the delay to avoid synchronization.
-  * Turned on by default.
-  */
-  readonly jitter?: boolean;
-}
-/**
-* Creates an exponential backoff retry policy.  The delay between retries
-* starts at the `initialDelay` and is multiplied by the `factor` for each
-* subsequent retry, up to the `maxDelay`.  The policy will give up after
-* `maxAttempts` attempts.  The actual delay is randomized to avoid
-* synchronization (jitter).
-* @param options The options for the policy.
-* @returns The retry policy.
-* @since 0.12.0
-*/
-declare function createExponentialBackoffPolicy(options?: CreateExponentialBackoffPolicyOptions): RetryPolicy;
-//#endregion
 //#region src/federation/middleware.d.ts
 /**
 * Configures the task queues for sending and receiving activities.
@@ -820,6 +989,13 @@ interface FederationQueueOptions {
   * {@link Context.sendActivity} calls.
   */
   readonly fanout?: MessageQueue;
+  /**
+  * The message queue for custom background tasks.  If not provided,
+  * tasks are routed to the outbox queue (unless
+  * {@link FederationOptions.taskQueueResolution} is `"strict"`).
+  * @since 2.4.0
+  */
+  readonly task?: MessageQueue;
 }
 /**
 * Prefixes for namespacing keys in the Deno KV store.
@@ -863,6 +1039,14 @@ interface FederationKvPrefixes {
   * @since 2.3.0
   */
   readonly circuitBreaker: KvKey;
+  /**
+  * The key prefix used for storing custom background task deduplication
+  * markers.  Kept separate from {@link activityIdempotence} so the two key
+  * spaces never collide.
+  * @default `["_fedify", "taskDeduplication"]`
+  * @since 2.4.0
+  */
+  readonly taskDeduplication: KvKey;
 }
 /**
 * Options for {@link FederationOptions.origin} when it is not a string.
@@ -904,18 +1088,18 @@ interface FederationStartQueueOptions {
   signal?: AbortSignal;
   /**
   * Starts the task worker only for the specified queue.  If unspecified,
-  * which is the default, the task worker starts for all three queues:
-  * inbox, outbox, and fanout.
+  * which is the default, the task worker starts for all four queues:
+  * inbox, outbox, fanout, and task.
   * @since 1.3.0
   */
-  queue?: "inbox" | "outbox" | "fanout";
+  queue?: "inbox" | "outbox" | "fanout" | "task";
 }
 /**
 * A common interface between {@link Federation} and {@link FederationBuilder}.
 * @template TContextData The context data to pass to the {@link Context}.
 * @since 1.6.0
 */
-interface Federatable<TContextData> {
+interface Federatable<TContextData> extends TaskRegistry<TContextData> {
   /**
   * Registers a NodeInfo dispatcher.
   * @param path The URI path pattern for the NodeInfo dispatcher.  The syntax
@@ -1622,6 +1806,50 @@ interface FederationOptions<TContextData> {
   */
   inboxRetryPolicy?: RetryPolicy;
   /**
+  * The retry policy for processing custom background tasks.  By default,
+  * this uses an exponential backoff strategy with a maximum of 10 attempts
+  * and a maximum delay of 12 hours.  A per-task retry policy
+  * ({@link TaskDefinitionOptions.retryPolicy}) overrides this.
+  * @since 2.4.0
+  */
+  taskRetryPolicy?: RetryPolicy;
+  /**
+  * How a queue is resolved for a custom background task when neither
+  * a per-task queue ({@link TaskDefinitionOptions.queue}) nor a dedicated
+  * task queue ({@link FederationQueueOptions.task}) is configured.
+  *
+  * - `"fallback"` (the default): the task is routed to the outbox queue.
+  * - `"strict"`: no fallback; enqueuing the task throws instead of
+  *   silently sharing the outbox queue.
+  * @default `"fallback"`
+  * @since 2.4.0
+  */
+  taskQueueResolution?: "fallback" | "strict";
+  /**
+  * The time-to-live for a {@link TaskEnqueueOptions.deduplicationKey} marker
+  * stored in the key–value deduplication fallback.  A second enqueue with the
+  * same key within this window is skipped; once it expires, the key may
+  * enqueue again.  Ignored when the task's queue declares
+  * {@link MessageQueue.nativeDeduplication} (the backend owns the window).
+  * @default `{ hours: 1 }`
+  * @since 2.4.0
+  */
+  taskDeduplicationTtl?: Temporal.DurationLike;
+  /**
+  * The behavior when a {@link TaskEnqueueOptions.deduplicationKey} is supplied
+  * but the task's queue does not declare
+  * {@link MessageQueue.nativeDeduplication} *and* the configured
+  * {@link KvStore} exposes no `cas` (compare-and-swap) primitive:
+  *
+  * - `"open"` (the default): proceeds without deduplication after logging at
+  *   debug level.
+  * - `"closed"`: rejects with a `TypeError` before enqueuing.
+  *
+  * @default `"open"`
+  * @since 2.4.0
+  */
+  taskDeduplicationFallback?: "open" | "closed";
+  /**
   * Activity transformers that are applied to outgoing activities.  It is
   * useful for adjusting outgoing activities to satisfy some ActivityPub
   * implementations.
@@ -2374,6 +2602,48 @@ interface Context<TContextData> {
   */
   routeActivity(recipient: string | null, activity: Activity, options?: RouteActivityOptions): Promise<boolean>;
   /**
+  * Enqueues a custom background task.  The payload is validated against
+  * the task's schema, serialized, and processed by the task's handler on
+  * a background worker.
+  *
+  * @example
+  * ``` typescript
+  * await ctx.enqueueTask(sendDigest, { userId: "alice" });
+  * ```
+  *
+  * @template TData The type of the task payload, inferred from the task's
+  *                 schema.
+  * @param task The handle returned by {@link TaskRegistry.defineTask}.
+  * @param data The task payload.  It is validated against the task's
+  *             schema before being enqueued.
+  * @param options Options for enqueuing the task.
+  * @throws {TypeError} If the task is not defined on this federation,
+  *                     if no message queue is configured for tasks, or if
+  *                     the payload fails schema validation.
+  * @since 2.4.0
+  */
+  enqueueTask<TData>(task: TaskDefinition<TContextData, TData>, data: TData, options?: TaskEnqueueOptions): Promise<void>;
+  /**
+  * Enqueues multiple payloads for a custom background task at once.
+  * Uses the queue's bulk enqueue operation when available.  Without
+  * deduplication, it may fall back to parallel single enqueues when the
+  * queue does not implement bulk enqueue.
+  * @template TData The type of the task payload, inferred from the task's
+  *                 schema.
+  * @param task The handle returned by {@link TaskRegistry.defineTask}.
+  * @param payloads The task payloads.  Each is validated against the
+  *                 task's schema before being enqueued.
+  * @param options Options for enqueuing the tasks.
+  * @throws {TypeError} If the task is not defined on this federation,
+  *                     if no message queue is configured for tasks, if
+  *                     a payload fails schema validation, or if a
+  *                     deduplicated multi-item batch cannot be enqueued
+  *                     atomically because the queue does not implement
+  *                     bulk enqueue.
+  * @since 2.4.0
+  */
+  enqueueTaskMany<TData>(task: TaskDefinition<TContextData, TData>, payloads: readonly TData[], options?: TaskEnqueueOptions): Promise<void>;
+  /**
   * Builds the URI of a collection of objects with the given name and values.
   * @param name The name of the collection, which can be a string or a symbol.
   * @param values The values of the URI parameters.
@@ -2884,4 +3154,4 @@ interface ActorKeyPair extends CryptoKeyPair {
   readonly multikey: Multikey;
 }
 //#endregion
-export { CustomCollectionCursor as $, Rfc6570Expression as A, parseCircuitBreakerKvState as At, createFederationBuilder as B, FederationStartQueueOptions as C, CircuitBreakerFailurePolicy as Ct, InboxListenerSetters as D, CircuitBreakerStateChange as Dt, InboxChallengePolicy as E, CircuitBreakerState as Et, CreateExponentialBackoffPolicyOptions as F, ActorDispatcher as G, respondWithObject as H, RetryContext as I, AuthorizePredicate as J, ActorHandleMapper as K, RetryPolicy as L, FederationOrigin as M, FederationQueueOptions as N, ObjectCallbackSetters as O, NormalizedCircuitBreakerOptions as Ot, createFederation as P, CustomCollectionCounter as Q, createExponentialBackoffPolicy as R, FederationOptions as S, CircuitBreakerCreateOptions as St, IdempotencyStrategy as T, CircuitBreakerOptions as Tt, respondWithObjectIfAcceptable as U, RespondWithObjectOptions as V, ActorAliasMapper as W, CollectionCursor as X, CollectionCounter as Y, CollectionDispatcher as Z, Federatable as _, buildCollectionSynchronizationHeader as _t, GetSignedKeyOptions as a, ObjectDispatcher as at, FederationBuilder as b, CircuitBreakerActivityDrop as bt, ParseUriResult as c, OutboxListenerErrorHandler as ct, SendActivityOptions as d, UnverifiedActivityHandler as dt, CustomCollectionDispatcher as et, SendActivityOptionsForCollection as f, UnverifiedActivityReason as ft, CustomCollectionCallbackSetters as g, PageItems as gt, ConstructorWithTypeId as h, SenderKeyPair as ht, GetActorOptions as i, ObjectAuthorizePredicate as it, FederationKvPrefixes as j, ActivityTransformer as jt, OutboxListenerSetters as k, normalizeCircuitBreakerOptions as kt, RequestContext as l, OutboxPermanentFailureHandler as lt, CollectionCallbackSetters as m, SendActivityError as mt, Context as n, InboxListener as nt, InboxContext as o, OutboxErrorHandler as ot, ActorCallbackSetters as p, WebFingerLinksDispatcher as pt, ActorKeyPairsDispatcher as q, ForwardActivityOptions as r, NodeInfoDispatcher as rt, OutboxContext as s, OutboxListener as st, ActorKeyPair as t, InboxErrorHandler as tt, RouteActivityOptions as u, SharedInboxKeyDispatcher as ut, Federation as v, digest as vt, IdempotencyKeyCallback as w, CircuitBreakerKvState as wt, FederationFetchOptions as x, CircuitBreakerBeforeSendDecision as xt, FederationBenchmarkOptions as y, CircuitBreaker as yt, Message as z };
+export { CircuitBreakerFailurePolicy as $, Rfc6570Expression as A, WebFingerLinksDispatcher as At, TaskHandler as B, FederationStartQueueOptions as C, OutboxErrorHandler as Ct, InboxListenerSetters as D, SharedInboxKeyDispatcher as Dt, InboxChallengePolicy as E, OutboxPermanentFailureHandler as Et, Message as F, digest as Ft, createExponentialBackoffPolicy as G, CreateExponentialBackoffPolicyOptions as H, createFederationBuilder as I, ActivityTransformer as It, respondWithObjectIfAcceptable as J, RespondWithObjectOptions as K, TaskDefinition as L, FederationOrigin as M, SenderKeyPair as Mt, FederationQueueOptions as N, PageItems as Nt, ObjectCallbackSetters as O, UnverifiedActivityHandler as Ot, createFederation as P, buildCollectionSynchronizationHeader as Pt, CircuitBreakerCreateOptions as Q, TaskDefinitionOptions as R, FederationOptions as S, ObjectDispatcher as St, IdempotencyStrategy as T, OutboxListenerErrorHandler as Tt, RetryContext as U, TaskRegistry as V, RetryPolicy as W, CircuitBreakerActivityDrop as X, CircuitBreaker as Y, CircuitBreakerBeforeSendDecision as Z, Federatable as _, CustomCollectionDispatcher as _t, GetSignedKeyOptions as a, normalizeCircuitBreakerOptions as at, FederationBuilder as b, NodeInfoDispatcher as bt, ParseUriResult as c, ActorDispatcher as ct, SendActivityOptions as d, AuthorizePredicate as dt, CircuitBreakerKvState as et, SendActivityOptionsForCollection as f, CollectionCounter as ft, CustomCollectionCallbackSetters as g, CustomCollectionCursor as gt, ConstructorWithTypeId as h, CustomCollectionCounter as ht, GetActorOptions as i, NormalizedCircuitBreakerOptions as it, FederationKvPrefixes as j, SendActivityError as jt, OutboxListenerSetters as k, UnverifiedActivityReason as kt, RequestContext as l, ActorHandleMapper as lt, CollectionCallbackSetters as m, CollectionDispatcher as mt, Context as n, CircuitBreakerState as nt, InboxContext as o, parseCircuitBreakerKvState as ot, ActorCallbackSetters as p, CollectionCursor as pt, respondWithObject as q, ForwardActivityOptions as r, CircuitBreakerStateChange as rt, OutboxContext as s, ActorAliasMapper as st, ActorKeyPair as t, CircuitBreakerOptions as tt, RouteActivityOptions as u, ActorKeyPairsDispatcher as ut, Federation as v, InboxErrorHandler as vt, IdempotencyKeyCallback as w, OutboxListener as wt, FederationFetchOptions as x, ObjectAuthorizePredicate as xt, FederationBenchmarkOptions as y, InboxListener as yt, TaskEnqueueOptions as z };