@fedify/fedify 2.5.0-dev.2597 → 2.5.0-dev.2614

package/dist/testing/mod.d.mts

@@ -416,6 +416,536 @@ interface GetKeyOwnerOptions {
   tracerProvider?: TracerProvider;
 }
 //#endregion
+//#region src/federation/outbound-report.d.ts
+/**
+ * The current producer's preparation result, not delivery completion.
+ * @since 2.5.0
+ */
+type OutboundPreparationResult = {
+  /** The producer finished preparing its continuation. */readonly type: "prepared"; /** Fanout-ready work still needs worker-side delivery preparation. */
+  readonly preparedFor: "fanout" | "delivery"; /** Number of deduplicated destinations, not actors or successful sends. */
+  readonly destinationCount: number;
+} | {
+  /** A deliberate no-send decision. */readonly type: "skipped"; /** The existing no-send decision made by this producer. */
+  readonly reason: "no-destinations" | "unsigned" | "forwarding-disabled" | "forwarding-unavailable" | "no-forwarding-targets";
+} | {
+  /** Preparation failed before the producer reached readiness. */readonly type: "failed"; /** The operation that failed and its original thrown value. */
+  readonly failure: {
+    /** Local processing failure, or unavailable operation provenance. */readonly kind: "local" | "unknown"; /** The observed operation, not a diagnosis from the error message. */
+    readonly phase: "sender-resolution" | "key-resolution" | "recipient-resolution" | "transformation" | "validation" | "signing" | "destination-planning" | "serialization" | "request-preparation" | "unknown"; /** Original thrown value, including non-Error values. */
+    readonly error: unknown;
+  }; /** Whether a complete destination plan was established before failure. */
+  readonly planning: "not-started" | "incomplete" | "complete"; /** Confirmed planned obligations so far, not an audience estimate. */
+  readonly plannedDestinationCount: number;
+};
+/**
+ * Known Activity ID and type at a broadcast observation boundary.
+ *
+ * Fields are captured without serializing the Activity or loading contexts.
+ * Successful transformation refreshes both the ID and the Activity class type.
+ * A `started` event may have an empty reference, and later events may reflect
+ * Activity transformations that happened after that event.
+ * @since 2.5.0
+ */
+type OutboundActivityReference = {
+  /** Activity identifier, when available at the observation boundary. */readonly id?: string; /** Activity class type IRI, when available at the observation boundary. */
+  readonly type?: string;
+};
+/**
+ * A send, original-payload forwarding, or portable replication producer lifecycle.
+ *
+ * Preparation results do not report queue acceptance or delivery completion.
+ * @since 2.5.0
+ */
+type OutboundBroadcastEvent = OutboundSourceMetadata & {
+  /** Fresh opaque identity shared by producer events, independent of tracing. */readonly broadcastId: string; /** The outgoing operation being observed. */
+  readonly operation: "send" | "forward" | "portable-replication"; /** Immutable Activity identity facts captured by the send path. */
+  readonly activity: OutboundActivityReference;
+} & ({
+  /** Entry before sender/recipient resolution or signing. */readonly stage: "started";
+} | {
+  /** The current producer's preparation settled. */readonly stage: "preparation-finished"; /** Readiness, a deliberate skip, or the original preparation failure. */
+  readonly result: OutboundPreparationResult;
+});
+/**
+ * A producer-side destination obligation, not delivery completion.
+ *
+ * IDs group producer handoffs and their fanout expansion across queue tasks.
+ * Concrete sends use separate {@link OutboundAttemptReport} values; these
+ * events do not establish delivery completion or worker scheduling outcomes.
+ * An unvisited destination stays planned when another destination's preparation
+ * interrupts the producer.
+ * @since 2.5.0
+ */
+type OutboundDeliveryEvent = OutboundSourceMetadata & {
+  /** The originating invocation, or unknown for legacy fanout work. */readonly broadcast: {
+    readonly type: "known";
+    readonly id: string;
+  } | {
+    readonly type: "unknown";
+  }; /** Opaque identity allocated after deduplication or a confirmed claim. */
+  readonly deliveryId: string; /** Planned destination, unchanged by concrete gateway selection. */
+  readonly destinationInbox: string; /** Canonical portable inbox when the selected route represents one. */
+  readonly portableInbox?: string;
+} & ({
+  /** This destination was established by the existing plan. */readonly stage: "planned"; /** Known actors sharing the destination, not an exhaustive audience. */
+  readonly actorIds: readonly string[]; /** Whether the selected destination uses a shared inbox. */
+  readonly sharedInbox: boolean; /** Fallback routes share one obligation; replication targets do not. */
+  readonly mode: "ordinary" | "portable-fallback" | "portable-replication";
+} | {
+  /** Local execution entry or enqueue settlement, not remote success. */readonly stage: "handoff"; /** Evidence from the actual producer handoff. */
+  readonly result: {
+    readonly type: "direct";
+  } | {
+    readonly type: "enqueued";
+    readonly queue: "fanout" | "outbox";
+    readonly queueMessageId: string;
+  } | {
+    readonly type: "enqueue-failed";
+    readonly acceptance: "unknown";
+    readonly error: unknown;
+  };
+} | {
+  /** Destination-local setup failed before entry into concrete sending. */readonly stage: "preparation-failed"; /** The original local setup failure, without inventing an attempt. */
+  readonly failure: {
+    readonly kind: "local";
+    readonly phase: "request-preparation";
+    readonly error: unknown;
+  };
+});
+/**
+ * The failure classification and available error evidence for a send attempt.
+ * @since 2.5.0
+ */
+type OutboundAttemptFailure = {
+  readonly kind: "http";
+  readonly phase: "response";
+  readonly error?: unknown;
+} | {
+  readonly kind: "transport";
+  readonly phase: "validation" | "request";
+  readonly error: unknown;
+} | {
+  readonly kind: "policy";
+  readonly phase: "validation";
+  readonly error: unknown;
+} | {
+  readonly kind: "local";
+  readonly phase: "serialization" | "request-preparation" | "cleanup" | "signing" | "spec-lookup" | "post-response";
+  readonly error: unknown;
+} | {
+  readonly kind: "unknown";
+  readonly phase: "unknown";
+  readonly error: unknown;
+};
+/** Immutable JSON data in a privacy projection. @since 2.5.0 */
+type OutboundJsonValue = null | boolean | number | string | readonly OutboundJsonValue[] | {
+  readonly [key: string]: OutboundJsonValue;
+};
+/** Attempt input evidence, never proof of a particular exchange's wire body. @since 2.5.0 */
+type OutboundSenderPayload = {
+  /** Concrete sender input, not a producer history or per-exchange wire body. */readonly stage: "sender-payload";
+} & ({
+  /** A safe independent projection was established without extra processing. */readonly type: "available"; /** Always a projection; no signature/proof or exact-wire claim is retained. */
+  readonly representation: "privacy-projection"; /** At least one blind-recipient field was removed from the copied value. */
+  readonly redacted: boolean; /** Recursively immutable JSON data; transport/signing input is unchanged. */
+  readonly value: OutboundJsonValue;
+} | {
+  /** No document value is exposed, including when export is disabled. */readonly type: "unavailable"; /** Opt-out, pre-snapshot failure, or unsupported privacy/context semantics. */
+  readonly reason: "disabled" | "not-materialized" | "privacy-filter-unavailable";
+});
+/** Result of an enabled response-body capture. Absence means disabled. @since 2.5.0 */
+type OutboundBodyCaptureSummary = {
+  /** Bytes handed to the application, not bytes durably stored. */readonly bytesExposed: number;
+} & ({
+  /** Selection, verified EOF, byte-cap uncertainty, or local lifetime end. */readonly type: "filtered" | "no-body" | "complete" | "limit-reached" | "deadline" | "callback-returned";
+} | {
+  /** Application cancellation ended capture. */readonly type: "consumer-stopped"; /** Original consumer reason, including non-Error values. */
+  readonly reason: unknown;
+} | {
+  /** Capture failed without changing received HTTP evidence. */readonly type: "failed"; /** Source reading versus application callback failure. */
+  readonly phase: "body" | "observer"; /** Original capture error; it does not become the attempt's failure. */
+  readonly error: unknown;
+});
+/** Bounded, revocable access to one selected response. @since 2.5.0 */
+type OutboundResponseBodyEvent = Omit<OutboundHttpExchangeReport, "outcome" | "bodyCapture"> & {
+  /** Immutable response metadata, independently of eventual attempt outcome. */readonly response: Extract<OutboundHttpExchangeReport["outcome"], {
+    type: "response";
+  }>["response"]; /** Pull-driven bytes; access ends when the callback settles or its limits apply. */
+  readonly body: ReadableStream<Uint8Array>; /** Capture-only lifetime signal; aborting it does not cancel transport. */
+  readonly signal: AbortSignal;
+};
+/** Explicit opt-in response-body capture limits and consumer. @since 2.5.0 */
+interface OutboundResponseBodyCapture<TContextData> {
+  /** Positive safe-integer exposure limit; exact cap without EOF stays uncertain. */
+  readonly maxBytes: number;
+  /** Positive finite absolute lifetime in milliseconds, rounded up; at most 2^31-1. */
+  readonly timeoutMs: number;
+  /** Actual response selector, defaulting to `all` only when enabled. */
+  readonly responses?: "all" | "non-success-http-responses";
+  /**
+   * Invoked after headers, before the terminal exchange report, with current data.
+   * Awaited within the absolute lifetime, including no-pull/slow-consumer time.
+   * Return/throw/cancel/cap/deadline revokes access even for retained locked readers.
+   * Errors cannot veto transport; ignoring the signal cannot be forcibly stopped.
+   */
+  readonly onBody: (context: Context<TContextData>, event: OutboundResponseBodyEvent) => void | Promise<void>;
+}
+/** Opt-in policy for one side of an actual HTTP exchange. @since 2.5.0 */
+interface OutboundHeaderPolicy {
+  /** Literal HTTP names, normalized to lowercase and deduplicated at registration. */
+  readonly allow: readonly string[];
+  /**
+   * Additional names whose selected values are always `[redacted]`.
+   * Credentials, signatures and cookies remain protected even without this list.
+   */
+  readonly redact?: readonly string[];
+  /**
+   * Positive safe-integer UTF-8 budget for `name: value\r\n` after redaction.
+   * Whole oversized entries are omitted; later entries remain eligible.
+   */
+  readonly maxBytes: number;
+}
+/** Immutable selected header values, using the runtime representation. @since 2.5.0 */
+interface OutboundHeaderSnapshot {
+  /** Lowercase names in lexical order; credentials/signatures/cookies are redacted. */
+  readonly entries: readonly (readonly [string, string])[];
+  /** At least one selected entry was omitted because it exceeded the budget. */
+  readonly limitReached: boolean;
+}
+/**
+ * Immutable HTTP response facts captured from a received response.
+ * @since 2.5.0
+ */
+interface OutboundHttpResponseMetadata {
+  /** Actual HTTP status returned by fetch. */
+  readonly status: number;
+  /** Copied HTTP status text. */
+  readonly statusText: string;
+  /** Response URL when supplied by fetch. */
+  readonly url?: string;
+}
+/**
+ * Response evidence and finality established during a send attempt.
+ * @since 2.5.0
+ */
+type OutboundAttemptResponse = {
+  /** The HTTP flow selected this response before follow-up work. */readonly type: "final"; /** Actual submission index of the selected response. */
+  readonly exchangeIndex: number; /** Frozen response facts, retained across later local failures. */
+  readonly metadata: OutboundHttpResponseMetadata;
+} | {
+  /** No response headers were received, including zero-fetch attempts. */readonly type: "not-observed";
+} | {
+  /** Continued past the response, or failed before deciding finality. */readonly type: "intermediate-only" | "undetermined"; /** Latest received response, without a finality claim. */
+  readonly lastObserved: {
+    readonly exchangeIndex: number;
+    readonly metadata: OutboundHttpResponseMetadata;
+  };
+};
+/**
+ * The terminal result of one concrete send.
+ *
+ * A send that fails before submitting HTTP still constitutes an attempt, with
+ * zero exchanges. Each gateway send and retry gets a fresh attempt identity.
+ * Final response evidence follows the HTTP flow's selection, not the last
+ * observed status; later cache/cleanup failures can still fail the execution.
+ * @since 2.5.0
+ */
+type OutboundAttemptReport = OutboundSourceMetadata & {
+  /** Fresh opaque identity allocated at concrete sender entry. */readonly attemptId: string; /** The originating invocation, independent of tracing. */
+  readonly broadcast: OutboundDeliveryEvent["broadcast"]; /** Destination obligation shared with producer delivery events. */
+  readonly deliveryId: string; /** Original planned inbox; unavailable on legacy outbox tasks. */
+  readonly destinationInbox?: string; /** Canonical portable inbox when the planned destination represents one. */
+  readonly portableInbox?: string; /** Inbox selected for this invocation of the concrete sender. */
+  readonly inboxUrl: string; /** Actual fetch submissions, including challenges and redirects; may be zero. */
+  readonly httpExchangeCount: number; /** Opt-in independent sender input projection; unavailable states remain explicit. */
+  readonly senderPayload: OutboundSenderPayload; /** Current queue execution; absent on immediate sends. */
+  readonly queue?: {
+    readonly queueMessageId: string; /** Present when the queue message carries a Fedify retry counter. */
+    readonly queueAttempt?: number;
+  }; /** Settled execution result, separate from producer preparation. */
+  readonly outcome: {
+    readonly type: "succeeded"; /** Final response selected by the sender. */
+    readonly response: Extract<OutboundAttemptResponse, {
+      type: "final";
+    }>;
+  } | {
+    readonly type: "failed";
+    /**
+     * Bounded failure kind and operation phase, captured before broad wrapping.
+     * Unknown provenance stays unknown; exception names do not establish it.
+     * Final non-OK HTTP evidence remains primary alongside local diagnostics.
+     */
+    readonly failure: OutboundAttemptFailure; /** Exact value escaping the sender, possibly different from failure.error. */
+    readonly error: unknown; /** Explicit final or last-observed response evidence, including absence. */
+    readonly response: OutboundAttemptResponse; /** Additional failures, without replacing the primary evidence. */
+    readonly diagnostics?: readonly OutboundAttemptFailure[];
+  };
+};
+/**
+ * One actual fetch submission within a concrete send attempt.
+ *
+ * A redirect response remains an observed response even if a later hop fails.
+ * This report does not establish the attempt's final response. Metadata is
+ * copied before callback awaiting; no live Request/Response/Headers are exposed.
+ * Enabled body capture uses a separate revocable callback; reports hold summaries.
+ * Exchange callbacks run after selected capture ends and may precede attempt settlement.
+ * @since 2.5.0
+ */
+type OutboundHttpExchangeReport = OutboundSourceMetadata & Pick<OutboundAttemptReport, "attemptId" | "broadcast" | "deliveryId" | "destinationInbox" | "portableInbox" | "inboxUrl" | "queue"> & {
+  /** Zero-based submission order within this attempt. */readonly exchangeIndex: number; /** Enabled capture result; absent when disabled or no response was received. */
+  readonly bodyCapture?: OutboundBodyCaptureSummary; /** Immutable facts of the request actually submitted. */
+  readonly request: {
+    readonly url: string;
+    readonly method: string; /** Selected header snapshot; absent when request header capture is disabled. */
+    readonly headers?: OutboundHeaderSnapshot;
+  }; /** A received response, including non-2xx, or the original fetch rejection. */
+  readonly outcome: {
+    readonly type: "response";
+    readonly response: OutboundHttpResponseMetadata & {
+      /** Selected snapshot; absent when response header capture is disabled. */readonly headers?: OutboundHeaderSnapshot;
+    };
+  } | {
+    readonly type: "failed";
+    readonly error: unknown;
+  };
+};
+/**
+ * A worker retry or deferral submission, separate from its enqueue outcome.
+ * @since 2.5.0
+ */
+type OutboundWorkerSchedule = {
+  readonly action: "retry" | "defer"; /** Actual continuation task and Fedify retry counter. */
+  readonly queue: NonNullable<OutboundAttemptReport["queue"]>; /** Actual affected routes, copied independently of the planned delivery. */
+  readonly inboxUrls: readonly string[]; /** ISO 8601 duration passed to enqueue after delay normalization. */
+  readonly delay: string; /** Per-route ISO instants retained by the scheduled continuation, if any. */
+  readonly notBefore?: Readonly<Record<string, string>>; /** Local preparation failures that contributed to this actual action. */
+  readonly preparationFailures?: readonly OutboundWorkerPreparationDiagnostic[];
+};
+/**
+ * One local preparation failure associated with a worker route.
+ * @since 2.5.0
+ */
+type OutboundWorkerPreparationDiagnostic = {
+  /** Route whose local setup produced the failure. */readonly inboxUrl: string; /** Existing worker preparation classification and original thrown value. */
+  readonly failure: Extract<OutboundWorkerReport["result"], {
+    type: "preparation-failed";
+  }>["failure"];
+};
+/**
+ * A child outbox task submitted by a fanout worker.
+ * @since 2.5.0
+ */
+type OutboundWorkerChild = {
+  readonly action: "enqueue"; /** Actual child task identity and initial Fedify retry counter. */
+  readonly queue: NonNullable<OutboundAttemptReport["queue"]>; /** Routes submitted with this child task. */
+  readonly inboxUrls: readonly string[]; /** Stable child obligation, independent of its task identity. */
+  readonly delivery?: OutboundWorkerReport["delivery"];
+};
+/**
+ * An observed worker handoff, scheduling outcome, or local abandonment.
+ * @since 2.5.0
+ */
+type OutboundWorkerAction = ((OutboundWorkerSchedule | OutboundWorkerChild) & {
+  readonly type: "scheduled";
+}) | ((OutboundWorkerSchedule | OutboundWorkerChild) & {
+  readonly type: "action-failed";
+  readonly acceptance: "unknown";
+  readonly error: unknown;
+}) | {
+  readonly type: "handoff";
+  readonly action: "direct"; /** Actual concrete sender target; entry does not establish HTTP success. */
+  readonly inboxUrls: readonly string[]; /** Planned obligation retained across gateway fallback targets. */
+  readonly delivery?: OutboundWorkerReport["delivery"];
+} | {
+  readonly type: "abandoned";
+  readonly reason: "held-ttl-expired" | "permanent-failure" | "retry-policy-declined" | "queue-unavailable"; /** Routes locally abandoned; other routes of the delivery may continue. */
+  readonly inboxUrls: readonly string[]; /** Local preparation failures that contributed to this abandonment. */
+  readonly preparationFailures?: readonly OutboundWorkerPreparationDiagnostic[];
+} | {
+  readonly type: "action-failed";
+  readonly action: "drop";
+  readonly inboxUrls: readonly string[];
+  readonly error: unknown;
+};
+/**
+ * One fanout or outbox worker execution after its local processing settles.
+ *
+ * Emitted after the local worker path and its instrumentation settle. A normal
+ * return can include handled send failures or abandonment; completion does not
+ * establish HTTP success or backend acknowledgment. Actions retain local route
+ * decisions and actual enqueue settlement, separately from attempt outcomes.
+ * A native rethrow does not establish a scheduled continuation or future replay.
+ * @since 2.5.0
+ */
+type OutboundWorkerReport = OutboundSourceMetadata & {
+  /** Current outgoing queue role; inbox/custom-task workers are separate. */readonly role: "fanout" | "outbox"; /** Actual task and available Fedify retry counter for this execution. */
+  readonly queue: NonNullable<OutboundAttemptReport["queue"]>; /** Concrete sender entries, independent of enabled attempt/exchange callbacks. */
+  readonly attemptsStarted: number;
+  /**
+   * Observed enqueue settlement, concrete direct-entry, and local abandonment.
+   * Accepted actions survive later worker failure; rejected batches leave each
+   * submitted child uncertain. Empty when no action was observed by settlement.
+   */
+  readonly actions: readonly OutboundWorkerAction[];
+  /**
+   * Caught preparation failures retained when later routes succeed or when
+   * the worker exits without scheduling a continuation. Omitted when none.
+   */
+  readonly preparationFailures?: readonly OutboundWorkerPreparationDiagnostic[];
+  /**
+   * Outbox obligation, with unavailable legacy relationships omitted.
+   * Fanout has no single delivery; its child actions carry their own references.
+   */
+  readonly delivery?: Pick<OutboundAttemptReport, "broadcast" | "deliveryId" | "destinationInbox" | "portableInbox">;
+  /**
+   * Actual local settlement, separate from individual attempts and queue actions.
+   * Preparation failures identify the operation that produced the escaping error.
+   */
+  readonly result: {
+    readonly type: "completed";
+  } | {
+    readonly type: "failed";
+    readonly error: unknown;
+  } | {
+    readonly type: "preparation-failed";
+    readonly failure: {
+      readonly kind: "local";
+      readonly phase: "key-import" | "activity-parsing" | "context-preparation" | "validation" | "key-resolution" | "signing" | "serialization" | "key-export" | "request-preparation";
+      readonly error: unknown;
+    }; /** Exact error escaping the worker preparation operation. */
+    readonly error: unknown;
+  };
+};
+/**
+ * Optional observers of outgoing activity processing.
+ *
+ * Send, original-payload forwarding, and automatic portable replication producer
+ * events are observed, including outbox-context operations and fanout
+ * continuation handoffs. Concrete attempts and actual fetch exchanges include
+ * queue workers, signature challenges, redirects, and alternate gateways.
+ * Worker reports describe local fanout/outbox settlement and actual queue
+ * actions; they do not establish backend acknowledgment or future execution.
+ * Known IDs and provenance survive queue continuations; callback context data
+ * belongs to the current execution. Each callback is independently optional.
+ * Metadata callbacks are awaited without a default timeout. An enabled body
+ * consumer instead uses its explicit bounded capture lifetime.
+ * Their errors, including errors logging observer failures, do not replace the
+ * send's result.
+ * A metadata callback that never settles can delay execution indefinitely. Detached
+ * recording must handle its own rejection and shutdown; no persistence is
+ * guaranteed. Existing portable forwarding deadlines may return while
+ * background preparation, sending, and observer callbacks continue.
+ * @template TContextData Application context data.
+ * @since 2.5.0
+ */
+interface OutboundObservers<TContextData> {
+  /**
+   * Opt-in immutable privacy projection of concrete sender input on attempt reports.
+   * Disabled by default. Unsupported context/data semantics yield no raw fallback;
+   * this is not exact wire evidence or proof that redirected requests kept a body.
+   */
+  readonly senderPayload?: boolean;
+  /**
+   * Independent opt-in body consumer; explicit byte/time limits are required.
+   * Shares one source reader with separately bounded diagnostics, without cloning
+   * or whole-body accumulation for the application. Finished reports hold summaries.
+   */
+  readonly responseBodyCapture?: OutboundResponseBodyCapture<TContextData>;
+  /**
+   * Opt-in actual request headers for exchange reports; disabled by default.
+   * Protected credentials, signatures, and cookies remain redacted even if allowed.
+   */
+  readonly requestHeaders?: OutboundHeaderPolicy;
+  /** Independent opt-in response header policy for exchange reports. */
+  readonly responseHeaders?: OutboundHeaderPolicy;
+  /**
+   * Observes terminal outgoing worker processing with current context/data.
+   * Errors are isolated; results do not replace attempt outcomes or establish
+   * future backend execution. Actions retain actual accepted/uncertain child
+   * handoffs and retry/defer/drop facts, separately from attempt outcomes.
+   */
+  readonly onWorker?: (context: Context<TContextData>, report: OutboundWorkerReport) => void | Promise<void>;
+  /**
+   * Observes each actual fetch after response headers or rejection, before
+   * subsequent challenge/redirect handling. Non-2xx responses are still response
+   * outcomes. Pre-fetch failures emit no exchange. Errors cannot veto transport.
+   */
+  readonly onHttpExchange?: (context: Context<TContextData>, report: OutboundHttpExchangeReport) => void | Promise<void>;
+  /**
+   * Observes settlement of concrete sends and forwarding, including workers
+   * and pre-fetch failures. Holds, drops, and failures before sender entry emit
+   * no attempt. Final HTTP evidence, local diagnostics, and the outward error
+   * remain distinct. Callback errors cannot replace the sender's result.
+   */
+  readonly onAttempt?: (context: Context<TContextData>, report: OutboundAttemptReport) => void | Promise<void>;
+  /**
+   * Observes invocation entry and the current producer's preparation result.
+   * The existing context is passed without loading data for observation.
+   * Returning or throwing cannot veto sending. Earlier immediate sends may
+   * already be running when preparation finishes; their outcomes are separate.
+   */
+  readonly onBroadcast?: (context: Context<TContextData>, event: OutboundBroadcastEvent) => void | Promise<void>;
+  /**
+   * Observes producer-side planning, handoffs, and destination preparation
+   * failures, including fanout continuation handoffs. Filtered recipients do
+   * not become planned deliveries. Concrete attempts and exchanges have their
+   * own callbacks. These events do not report remote success or worker
+   * scheduling outcomes.
+   */
+  readonly onDelivery?: (context: Context<TContextData>, event: OutboundDeliveryEvent) => void | Promise<void>;
+}
+/** URL facts captured independently of a mutable context URL. @since 2.5.0 */
+interface OutboundLocalContext {
+  /** Scheme and authority of the context URL. */
+  readonly origin: string;
+  /** URL hostname with its optional port. */
+  readonly host: string;
+  /** URL hostname without a port. */
+  readonly hostname: string;
+  /** Configured canonical web origin, falling back to this context's origin. */
+  readonly canonicalOrigin: string;
+}
+/** The original routed HTTP inbox request that caused outgoing work. @since 2.5.0 */
+interface OutboundInboxRequest {
+  /** Fresh server-generated identity, independent of Activity and trace IDs. */
+  readonly inboxRequestId: string;
+  /** Informational logging label; externally controlled and nonunique. */
+  readonly requestId: string;
+  /** Original request URL facts, preserved separately from current context. */
+  readonly context: OutboundLocalContext;
+}
+/** Explicit historical cause of outgoing work. @since 2.5.0 */
+interface OutboundProvenance {
+  /**
+   * Exact application-owned correlation, up to 1,024 UTF-8 bytes; an empty
+   * string is valid. Never a Fedify deduplication key. Each new public call
+   * supplies its own value; queued continuations retain it.
+   */
+  readonly dispatchId?: string;
+  /** Absent for independent contexts, programmatic routing, and unknown work. */
+  readonly inboxRequest?: OutboundInboxRequest;
+  /** Original logging label for request-derived work without an inbox cause. */
+  readonly originatingRequestId?: string;
+}
+/**
+ * Observation time, optional tracing, original provenance, and current context.
+ * @since 2.5.0
+ */
+interface OutboundSourceMetadata {
+  /** Unix milliseconds at observation; wall clocks do not ensure global ordering. */
+  readonly observedAt: number;
+  /** Valid IDs of this operation's own span, when one is available. */
+  readonly trace?: {
+    readonly traceId: string;
+    readonly spanId: string;
+  };
+  /** Immutable historical cause, distinct from this callback's context. */
+  readonly provenance: OutboundProvenance;
+  /** URL facts of the current callback context. */
+  readonly local: OutboundLocalContext;
+}
+//#endregion
 //#region src/federation/activity-listener.d.ts
 /**
  * Options for an inbox listener.
@@ -453,6 +983,13 @@ interface InboxListenerOptions {
 type InboxJsonValue = null | boolean | number | string | readonly InboxJsonValue[] | {
   readonly [key: string]: InboxJsonValue;
 };
+/** Request-signal state at inbox report construction, separate from processing outcome. @since 2.5.0 */
+type InboxRequestCancellation = {
+  readonly type: "not-aborted";
+} | {
+  readonly type: "aborted"; /** Exact Request.signal reason, including non-Error values. */
+  readonly reason: unknown;
+};
 /**
  * The final inbox authentication decision.
  * @since 2.4.0
@@ -529,6 +1066,31 @@ type InboxRequestOutcome = {
  * @since 2.4.0
  */
 interface InboxRequestReport {
+  /**
+   * Fresh server-generated identity for one routed HTTP inbox request,
+   * including preparation failures and duplicate deliveries. Preserved on
+   * outgoing causal descendants; absent without a known routed source.
+   * @since 2.5.0
+   */
+  readonly inboxRequestId?: string;
+  /**
+   * Original informational logging label; externally controlled and nonunique,
+   * independent of inboxRequestId. Absent without a known routed source.
+   * @since 2.5.0
+   */
+  readonly requestId?: string;
+  /**
+   * Original local URL facts from the routed request, independent of later contexts.
+   * Absent without a known routed source.
+   * @since 2.5.0
+   */
+  readonly local?: OutboundLocalContext;
+  /**
+   * Request.signal state immediately before report construction. An aborted request
+   * does not imply processing stopped or retract confirmed processing/enqueue outcomes.
+   * @since 2.5.0
+   */
+  readonly requestCancellation: InboxRequestCancellation;
   /** The delivery route, including a portable gateway route. */
   readonly inbox: {
     readonly kind: "personal" | "shared" | "portable";
@@ -579,6 +1141,379 @@ interface PageItems<TItem> {
   readonly items: readonly TItem[];
 }
 //#endregion
+//#region src/federation/inbox-authentication.d.ts
+/**
+ * A party that Fedify authenticated for an incoming activity, independently
+ * of the activity's declared `actor`.
+ * @since 2.5.0
+ */
+interface InboxPrincipal {
+  /**
+   * What {@link InboxPrincipal.id} is:
+   *
+   *  -  `"actor"`: an actor whose ownership of the verifying key Fedify
+   *     confirmed with the actor's own document.
+   *  -  `"portable-authority"`: a DID whose verification method made a valid
+   *     Object Integrity Proof.  It authenticates the [FEP-ef61] portable
+   *     actors of that DID, and nothing else.
+   *
+   * [FEP-ef61]: https://w3id.org/fep/ef61
+   */
+  readonly kind: "actor" | "portable-authority";
+  /** The actor ID, or the DID if {@link kind} is `"portable-authority"`. */
+  readonly id: URL;
+  /**
+   * How the principal was authenticated:
+   *
+   *  -  `"http-signatures"`: it signed the HTTP request.
+   *  -  `"linked-data-signatures"`: it made the Linked Data Signature of the
+   *     activity.
+   *  -  `"object-integrity-proofs"`: it made an Object Integrity Proof of the
+   *     activity.
+   *  -  `"origin"`: the activity was fetched again from the actor's own web
+   *     origin, which happens only for `Context.routeActivity()`.
+   */
+  readonly mechanism: "http-signatures" | "linked-data-signatures" | "object-integrity-proofs" | "origin";
+  /** The key or verification method that authenticated the principal. */
+  readonly keyId: URL | null;
+}
+/**
+ * Who Fedify authenticated for an incoming activity, and the interpretation of
+ * the activity it authenticated.  Inbox listeners receive it as
+ * {@link InboxContext.authentication}.
+ *
+ * Authenticated principals are independent of the activity's declared
+ * `actor`: an activity forwarded by a relay is signed by the relay in its
+ * HTTP request, but its document may be signed by its author, and some
+ * activities, such as [FEP-7aa9] `FeatureRequest`s sent by Mastodon, declare
+ * no `actor` at all.  A valid signature alone does not authorize anything;
+ * use {@link isActorAuthenticated} to check whether a specific actor was
+ * authenticated.
+ *
+ * [FEP-7aa9]: https://w3id.org/fep/7aa9
+ * @since 2.5.0
+ */
+interface InboxAuthenticationEvidence {
+  /**
+   * Whether signatures were verified at all.  It is `false` only when
+   * signature verification is skipped, or when there is no evidence, e.g.,
+   * for an activity queued by an older version of Fedify.  In that case all
+   * the principal lists are empty.
+   */
+  readonly verified: boolean;
+  /**
+   * The principals that signed the HTTP request, i.e., the server that
+   * delivered the activity, which may have forwarded it.  It is empty when
+   * the activity document was authenticated by its own signatures, so that
+   * HTTP Signatures did not need to be verified.
+   */
+  readonly requestSigners: readonly InboxPrincipal[];
+  /**
+   * The principals that made the verified Linked Data Signature or Object
+   * Integrity Proofs of the activity document.  All of them are listed when
+   * there are several proofs.
+   */
+  readonly documentSigners: readonly InboxPrincipal[];
+  /**
+   * The actors authenticated because `Context.routeActivity()` fetched the
+   * activity again from their own web origin.  It is always empty for
+   * activities delivered to an inbox.
+   */
+  readonly originAuthenticated: readonly InboxPrincipal[];
+  /**
+   * The activity as Fedify interpreted it while authenticating it, in
+   * expanded JSON-LD.  Typed vocabulary objects omit some values, such as
+   * blank node references and values they cannot decode, so authorization
+   * that has to count every value of a property, e.g., that a property has
+   * exactly one value, should inspect this instead.  It is deeply frozen.
+   * It is empty when there is no evidence.
+   */
+  readonly expandedActivity: readonly Record<string, unknown>[];
+  /**
+   * The base URL the activity was decoded with, e.g., the URL an activity
+   * fetched by `Context.routeActivity()` was finally retrieved from, or
+   * `null` if none was given.  Relative IRIs left in
+   * {@link expandedActivity} resolve against it, or against the activity's
+   * own `@id` if it is `null`, as the decoder resolves them.
+   */
+  readonly baseUrl: URL | null;
+}
+/**
+ * A {@link InboxPrincipal} as stored in a queued message.
+ * The wire spellings remain independent of the public API spellings.
+ * @internal
+ */
+interface SerializedInboxPrincipal {
+  readonly kind: "actor" | "portableAuthority";
+  readonly id: string;
+  readonly mechanism: "httpSignatures" | "linkedDataSignatures" | "objectIntegrityProofs" | "origin";
+  readonly keyId: string | null;
+}
+/**
+ * The principals of an {@link InboxAuthenticationEvidence} as stored in
+ * a queued message.  The expanded activity and the base URL are restored
+ * from the queued verified view instead.
+ * @internal
+ */
+interface SerializedInboxAuthentication {
+  readonly verified: boolean;
+  readonly requestSigners: readonly SerializedInboxPrincipal[];
+  readonly documentSigners: readonly SerializedInboxPrincipal[];
+  readonly originAuthenticated: readonly SerializedInboxPrincipal[];
+}
+//#endregion
+//#region src/sig/ld.d.ts
+/**
+ * How a context loader marked by {@link markEffectiveContextLoader} already
+ * resolves contexts.
+ * @internal
+ */
+type EffectiveContextLoaderPolicy = "standard" | "normalization";
+//#endregion
+//#region src/federation/inbox-view.d.ts
+/**
+ * A {@link ContextSnapshotEntry} as stored in a queued message.  A response
+ * that equals the one Fedify bundles for the URL is stored as a reference to
+ * the bundled context, along with its hash for diagnostics.
+ * @internal
+ */
+type SerializedContextSnapshotEntry = {
+  readonly policy: EffectiveContextLoaderPolicy;
+  readonly url: string; /** The SHA-256 of the canonical JSON of the whole response. */
+  readonly sha256: string;
+} & ({
+  readonly bundled: true;
+} | {
+  readonly response: RemoteDocument;
+});
+/**
+ * The interpretation of an incoming activity that Fedify authenticated, as
+ * stored in a queued message.  The document itself is not copied; it is
+ * a field of the message.
+ * @internal
+ */
+interface SerializedVerifiedActivityView {
+  /** The format version. */
+  readonly version: 1;
+  /** The context loader policy the activity was parsed with. */
+  readonly policy: EffectiveContextLoaderPolicy;
+  /**
+   * Which document the activity was parsed from, with its Linked Data
+   * Signature detached: the `activity` of the message, i.e., the payload as
+   * received, or its `normalizedActivity`, i.e., the payload compacted for
+   * Linked Data Signatures.
+   */
+  readonly source: "activity" | "normalizedActivity";
+  /** The `baseUrl` option the activity was parsed with. */
+  readonly baseUrl: string | null;
+  /** The context responses the interpretation used. */
+  readonly contexts: readonly SerializedContextSnapshotEntry[];
+  /** The digest of the expanded activity. */
+  readonly expandedDigest: string;
+}
+//#endregion
+//#region src/federation/queue.d.ts
+/** Serializable grouping facts, separate from queue task identity. @internal */
+interface SerializedOutboundDelivery {
+  readonly broadcast: {
+    readonly type: "known";
+    readonly id: string;
+  } | {
+    readonly type: "unknown";
+  };
+  readonly deliveryId: string;
+  readonly destinationInbox: string;
+  readonly portableInbox?: string;
+}
+interface SenderKeyJwkPair {
+  readonly keyId: string;
+  readonly privateKey: JsonWebKey;
+}
+/**
+ * A message that represents a task to be processed by the background worker.
+ * The concrete type of the message depends on the `type` property.
+ *
+ * Please do not depend on the concrete types of the messages, as they may
+ * change in the future.  You should treat the `Message` type as an opaque
+ * type.
+ * @since 1.6.0
+ */
+type Message = FanoutMessage | OutboxMessage | InboxMessage | TaskMessage;
+interface FanoutMessage {
+  /** Historical source facts; absent on legacy/independent messages. */
+  readonly provenance?: OutboundProvenance;
+  readonly type: "fanout";
+  readonly id: ReturnType<typeof crypto.randomUUID>;
+  readonly baseUrl: string;
+  readonly keys: readonly SenderKeyJwkPair[];
+  readonly inboxes: Readonly<Record<string, {
+    readonly actorIds: readonly string[];
+    readonly sharedInbox: boolean; /** Optional for continuations created before outbound observation. */
+    readonly outbound?: SerializedOutboundDelivery;
+    /**
+     * The canonical form of the FEP-ef61 portable inbox that the inbox
+     * stands for.
+     * @internal
+     */
+    readonly portableInbox?: string;
+    /**
+     * The compatible identifiers of the portable inbox on each gateway to
+     * deliver through, in order.
+     * @internal
+     */
+    readonly gatewayInboxes?: readonly string[];
+  }>>;
+  readonly activity: unknown;
+  readonly activityId?: string;
+  readonly activityType: string;
+  readonly collectionSync?: string;
+  readonly orderingKey?: string;
+  /**
+   * Whether to apply outgoing JSON-LD wire-format normalization to queued
+   * activities that already carry Object Integrity Proofs.
+   *
+   * `true` is used for proofs Fedify created before fanout, or when callers
+   * explicitly request normalization for locally pre-signed activities.
+   * `false`/`undefined` preserves existing proofs as-is.
+   */
+  readonly normalizeExistingProofs?: boolean;
+  readonly traceContext: Readonly<Record<string, string>>;
+}
+interface OutboxMessage {
+  /** Historical source facts; absent on legacy/independent messages. */
+  readonly provenance?: OutboundProvenance;
+  readonly type: "outbox";
+  readonly id: ReturnType<typeof crypto.randomUUID>;
+  /** Original delivery identity; absent on legacy/unobserved producers. */
+  readonly outbound?: SerializedOutboundDelivery;
+  readonly baseUrl: string;
+  readonly keys: readonly SenderKeyJwkPair[];
+  readonly activity: unknown;
+  readonly activityId?: string;
+  readonly activityType: string;
+  readonly inbox: string;
+  readonly sharedInbox: boolean;
+  readonly actorIds?: readonly string[];
+  readonly started: string;
+  readonly attempt: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly orderingKey?: string;
+  /**
+   * Whether this message is currently held by the outbound circuit breaker.
+   * @internal
+   */
+  readonly circuitHeld?: true;
+  /**
+   * When Fedify first held this message because the remote host circuit was
+   * open.
+   * @internal
+   */
+  readonly circuitHeldSince?: string;
+  /**
+   * The canonical form of the FEP-ef61 portable inbox that {@link inbox}, its
+   * compatible identifier on a gateway, stands for.
+   * @internal
+   */
+  readonly portableInbox?: string;
+  /**
+   * The compatible identifiers of the FEP-ef61 portable inbox on each gateway
+   * that is still to be tried, in order.  {@link inbox} is the first one.
+   * If there is more than one, the activity is delivered through the first
+   * gateway that accepts it.
+   * @internal
+   */
+  readonly gatewayInboxes?: readonly string[];
+  /**
+   * The times before which each of {@link gatewayInboxes} must not be tried
+   * again, as their responses' `Retry-After` headers requested, keyed by
+   * the inbox URL, in ISO 8601.
+   * @internal
+   */
+  readonly gatewayNotBefore?: Readonly<Record<string, 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 {
+  /** Historical source facts; absent on legacy/independent messages. */
+  readonly provenance?: OutboundProvenance;
+  readonly type: "inbox";
+  readonly id: ReturnType<typeof crypto.randomUUID>;
+  readonly baseUrl: string;
+  readonly activity: unknown;
+  /**
+   * The normalized JSON-LD representation of a signed inbox activity that
+   * Fedify already compacted successfully while accepting the request.  Queue
+   * workers can reuse this producer-side parse cache under stricter loader or
+   * network constraints without changing the raw payload preserved for
+   * forwarding.
+   *
+   * This may exist even when {@link ldSignatureVerified} is `false`, because
+   * fallback-authenticated traffic and already-queued backlog items can still
+   * depend on the cached normalized form to avoid re-fetching remote custom
+   * contexts during worker processing.
+   *
+   * This is optional for backward compatibility with messages that were
+   * queued by older Fedify versions or that were already in a queue before
+   * upgrading.
+   *
+   * Fedify keeps this on the queued message itself instead of an external
+   * sidecar because generic queue backends do not provide reliable lifecycle
+   * guarantees for auxiliary storage across retries and redeliveries.
+   *
+   * @internal
+   */
+  readonly normalizedActivity?: unknown;
+  /**
+   * Whether the producer actually verified the Linked Data Signature before
+   * queueing this message.  This lets workers distinguish verified LDS replay
+   * from other authenticated inbox traffic that merely happened to include a
+   * signature block.  This provenance marker is separate from the optional
+   * normalizedActivity parse cache.
+   *
+   * `undefined` preserves backward compatibility with older queued messages
+   * that predate this marker.
+   *
+   * @internal
+   */
+  readonly ldSignatureVerified?: boolean;
+  /**
+   * The interpretation of the activity that Fedify authenticated, i.e., which
+   * document it was parsed from and every JSON-LD context response the parse
+   * used, so that the worker and its retries dispatch the very same
+   * interpretation without loading contexts again.  Absent in messages queued
+   * by older Fedify versions.
+   * @internal
+   */
+  readonly verifiedView?: SerializedVerifiedActivityView;
+  /**
+   * Who Fedify authenticated for the activity.  Absent in messages queued by
+   * older Fedify versions.
+   * @internal
+   */
+  readonly authentication?: SerializedInboxAuthentication;
+  readonly started: string;
+  readonly attempt: number;
+  readonly identifier: string | null;
+  readonly traceContext: Readonly<Record<string, string>>;
+}
+//#endregion
 //#region src/federation/send.d.ts
 /**
  * A key pair for an actor who sends an activity.
@@ -613,7 +1548,9 @@ declare class SendActivityError extends Error {
    * The response body from the inbox, if any.  Note that this may be
    * truncated to a maximum of 1 KiB to prevent excessive memory consumption
    * when remote servers return large error pages (e.g., Cloudflare error pages).
-   * If truncated, the string will end with `"… (truncated)"`.
+   * If truncated, the string will end with `"… (truncated)"`. Diagnostic reading
+   * has a separate one-second budget; a deadline retains any partial preview and
+   * appends `"… (timed out)"`. This is independent of application body capture.
    */
   readonly responseBody: string;
   /**
@@ -1334,238 +2271,67 @@ interface MessageQueue {
    *
    * @default `false`
    * @since 2.4.0
-   */
-  readonly nativeDeduplication?: boolean;
-  /**
-   * Whether {@link enqueueMany} accepts either every message or no messages.
-   * Backends that implement `enqueueMany()` by sending messages individually
-   * must set this to `false`, so Fedify does not use that method for a batch
-   * governed by one `deduplicationKey`.  `true` by default when `enqueueMany`
-   * is implemented.
-   *
-   * @default `true`
-   * @since 2.4.0
-   */
-  readonly atomicEnqueueMany?: boolean;
-  /**
-   * The largest message, in bytes, that the backend can hold.  Fedify compares
-   * it with a conservative estimate of a message's serialized size: the
-   * length of its JSON serialization encoded in UTF-8, plus 8 bytes for each
-   * JSON value in it, plus what encoding strings beyond Latin-1 as UTF-16
-   * adds, which also bounds binary serialization formats.  When an
-   * incoming activity would make a larger inbox message, Fedify processes the
-   * activity right away instead of enqueueing it, as if there were no inbox
-   * queue.  When omitted, messages are enqueued regardless of their size.
-   * @since 2.5.0
-   */
-  readonly maxMessageSize?: number;
-  /**
-   * Enqueues a message in the queue.
-   * @param message The message to enqueue.
-   * @param options Additional options for enqueuing the message.
-   */
-  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
-  /**
-   * Enqueues multiple messages in the queue.  This operation is optional,
-   * and may not be supported by all implementations.  If not supported,
-   * Fedify will invoke {@link enqueue} for each message.  An implementation
-   * that may accept only part of a batch before rejecting must declare
-   * {@link atomicEnqueueMany} `false`.
-   *
-   * @param messages The messages to enqueue.
-   * @param options Additional options for enqueuing the messages.
-   */
-  enqueueMany?: (messages: readonly any[], options?: MessageQueueEnqueueOptions) => Promise<void>;
-  /**
-   * Listens for messages in the queue.
-   * @param handler The handler for messages in the queue.
-   * @param options Additional options for listening to the message queue.
-   * @returns A promise that resolves when the listening is done.  It never
-   *          rejects, and is resolved when the signal is aborted.  If no
-   *          signal is provided, it never resolves.
-   */
-  listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
-  /**
-   * Gets the number of messages waiting in the queue.
-   *
-   * This operation is optional, and may not be supported by all
-   * implementations.  The returned counts exclude messages currently being
-   * handled by a worker.
-   *
-   * @since 2.3.0
-   */
-  getDepth?(): Promise<MessageQueueDepth>;
-}
-//#endregion
-//#region src/federation/inbox-authentication.d.ts
-/**
- * A party that Fedify authenticated for an incoming activity, independently
- * of the activity's declared `actor`.
- * @since 2.5.0
- */
-interface InboxPrincipal {
-  /**
-   * What {@link InboxPrincipal.id} is:
-   *
-   *  -  `"actor"`: an actor whose ownership of the verifying key Fedify
-   *     confirmed with the actor's own document.
-   *  -  `"portable-authority"`: a DID whose verification method made a valid
-   *     Object Integrity Proof.  It authenticates the [FEP-ef61] portable
-   *     actors of that DID, and nothing else.
-   *
-   * [FEP-ef61]: https://w3id.org/fep/ef61
-   */
-  readonly kind: "actor" | "portable-authority";
-  /** The actor ID, or the DID if {@link kind} is `"portable-authority"`. */
-  readonly id: URL;
-  /**
-   * How the principal was authenticated:
-   *
-   *  -  `"http-signatures"`: it signed the HTTP request.
-   *  -  `"linked-data-signatures"`: it made the Linked Data Signature of the
-   *     activity.
-   *  -  `"object-integrity-proofs"`: it made an Object Integrity Proof of the
-   *     activity.
-   *  -  `"origin"`: the activity was fetched again from the actor's own web
-   *     origin, which happens only for `Context.routeActivity()`.
-   */
-  readonly mechanism: "http-signatures" | "linked-data-signatures" | "object-integrity-proofs" | "origin";
-  /** The key or verification method that authenticated the principal. */
-  readonly keyId: URL | null;
-}
-/**
- * Who Fedify authenticated for an incoming activity, and the interpretation of
- * the activity it authenticated.  Inbox listeners receive it as
- * {@link InboxContext.authentication}.
- *
- * Authenticated principals are independent of the activity's declared
- * `actor`: an activity forwarded by a relay is signed by the relay in its
- * HTTP request, but its document may be signed by its author, and some
- * activities, such as [FEP-7aa9] `FeatureRequest`s sent by Mastodon, declare
- * no `actor` at all.  A valid signature alone does not authorize anything;
- * use {@link isActorAuthenticated} to check whether a specific actor was
- * authenticated.
- *
- * [FEP-7aa9]: https://w3id.org/fep/7aa9
- * @since 2.5.0
- */
-interface InboxAuthenticationEvidence {
-  /**
-   * Whether signatures were verified at all.  It is `false` only when
-   * signature verification is skipped, or when there is no evidence, e.g.,
-   * for an activity queued by an older version of Fedify.  In that case all
-   * the principal lists are empty.
-   */
-  readonly verified: boolean;
-  /**
-   * The principals that signed the HTTP request, i.e., the server that
-   * delivered the activity, which may have forwarded it.  It is empty when
-   * the activity document was authenticated by its own signatures, so that
-   * HTTP Signatures did not need to be verified.
-   */
-  readonly requestSigners: readonly InboxPrincipal[];
-  /**
-   * The principals that made the verified Linked Data Signature or Object
-   * Integrity Proofs of the activity document.  All of them are listed when
-   * there are several proofs.
-   */
-  readonly documentSigners: readonly InboxPrincipal[];
-  /**
-   * The actors authenticated because `Context.routeActivity()` fetched the
-   * activity again from their own web origin.  It is always empty for
-   * activities delivered to an inbox.
-   */
-  readonly originAuthenticated: readonly InboxPrincipal[];
-  /**
-   * The activity as Fedify interpreted it while authenticating it, in
-   * expanded JSON-LD.  Typed vocabulary objects omit some values, such as
-   * blank node references and values they cannot decode, so authorization
-   * that has to count every value of a property, e.g., that a property has
-   * exactly one value, should inspect this instead.  It is deeply frozen.
-   * It is empty when there is no evidence.
-   */
-  readonly expandedActivity: readonly Record<string, unknown>[];
-  /**
-   * The base URL the activity was decoded with, e.g., the URL an activity
-   * fetched by `Context.routeActivity()` was finally retrieved from, or
-   * `null` if none was given.  Relative IRIs left in
-   * {@link expandedActivity} resolve against it, or against the activity's
-   * own `@id` if it is `null`, as the decoder resolves them.
-   */
-  readonly baseUrl: URL | null;
-}
-/**
- * A {@link InboxPrincipal} as stored in a queued message.
- * The wire spellings remain independent of the public API spellings.
- * @internal
- */
-interface SerializedInboxPrincipal {
-  readonly kind: "actor" | "portableAuthority";
-  readonly id: string;
-  readonly mechanism: "httpSignatures" | "linkedDataSignatures" | "objectIntegrityProofs" | "origin";
-  readonly keyId: string | null;
-}
-/**
- * The principals of an {@link InboxAuthenticationEvidence} as stored in
- * a queued message.  The expanded activity and the base URL are restored
- * from the queued verified view instead.
- * @internal
- */
-interface SerializedInboxAuthentication {
-  readonly verified: boolean;
-  readonly requestSigners: readonly SerializedInboxPrincipal[];
-  readonly documentSigners: readonly SerializedInboxPrincipal[];
-  readonly originAuthenticated: readonly SerializedInboxPrincipal[];
-}
-//#endregion
-//#region src/sig/ld.d.ts
-/**
- * How a context loader marked by {@link markEffectiveContextLoader} already
- * resolves contexts.
- * @internal
- */
-type EffectiveContextLoaderPolicy = "standard" | "normalization";
-//#endregion
-//#region src/federation/inbox-view.d.ts
-/**
- * A {@link ContextSnapshotEntry} as stored in a queued message.  A response
- * that equals the one Fedify bundles for the URL is stored as a reference to
- * the bundled context, along with its hash for diagnostics.
- * @internal
- */
-type SerializedContextSnapshotEntry = {
-  readonly policy: EffectiveContextLoaderPolicy;
-  readonly url: string; /** The SHA-256 of the canonical JSON of the whole response. */
-  readonly sha256: string;
-} & ({
-  readonly bundled: true;
-} | {
-  readonly response: RemoteDocument;
-});
-/**
- * The interpretation of an incoming activity that Fedify authenticated, as
- * stored in a queued message.  The document itself is not copied; it is
- * a field of the message.
- * @internal
- */
-interface SerializedVerifiedActivityView {
-  /** The format version. */
-  readonly version: 1;
-  /** The context loader policy the activity was parsed with. */
-  readonly policy: EffectiveContextLoaderPolicy;
+   */
+  readonly nativeDeduplication?: boolean;
   /**
-   * Which document the activity was parsed from, with its Linked Data
-   * Signature detached: the `activity` of the message, i.e., the payload as
-   * received, or its `normalizedActivity`, i.e., the payload compacted for
-   * Linked Data Signatures.
+   * Whether {@link enqueueMany} accepts either every message or no messages.
+   * Backends that implement `enqueueMany()` by sending messages individually
+   * must set this to `false`, so Fedify does not use that method for a batch
+   * governed by one `deduplicationKey`.  `true` by default when `enqueueMany`
+   * is implemented.
+   *
+   * @default `true`
+   * @since 2.4.0
    */
-  readonly source: "activity" | "normalizedActivity";
-  /** The `baseUrl` option the activity was parsed with. */
-  readonly baseUrl: string | null;
-  /** The context responses the interpretation used. */
-  readonly contexts: readonly SerializedContextSnapshotEntry[];
-  /** The digest of the expanded activity. */
-  readonly expandedDigest: string;
+  readonly atomicEnqueueMany?: boolean;
+  /**
+   * The largest message, in bytes, that the backend can hold.  Fedify compares
+   * it with a conservative estimate of a message's serialized size: the
+   * length of its JSON serialization encoded in UTF-8, plus 8 bytes for each
+   * JSON value in it, plus what encoding strings beyond Latin-1 as UTF-16
+   * adds, which also bounds binary serialization formats.  When an
+   * incoming activity would make a larger inbox message, Fedify processes the
+   * activity right away instead of enqueueing it, as if there were no inbox
+   * queue.  When omitted, messages are enqueued regardless of their size.
+   * @since 2.5.0
+   */
+  readonly maxMessageSize?: number;
+  /**
+   * Enqueues a message in the queue.
+   * @param message The message to enqueue.
+   * @param options Additional options for enqueuing the message.
+   */
+  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+   * Enqueues multiple messages in the queue.  This operation is optional,
+   * and may not be supported by all implementations.  If not supported,
+   * Fedify will invoke {@link enqueue} for each message.  An implementation
+   * that may accept only part of a batch before rejecting must declare
+   * {@link atomicEnqueueMany} `false`.
+   *
+   * @param messages The messages to enqueue.
+   * @param options Additional options for enqueuing the messages.
+   */
+  enqueueMany?: (messages: readonly any[], options?: MessageQueueEnqueueOptions) => Promise<void>;
+  /**
+   * Listens for messages in the queue.
+   * @param handler The handler for messages in the queue.
+   * @param options Additional options for listening to the message queue.
+   * @returns A promise that resolves when the listening is done.  It never
+   *          rejects, and is resolved when the signal is aborted.  If no
+   *          signal is provided, it never resolves.
+   */
+  listen(handler: (message: any) => Promise<void> | void, options?: MessageQueueListenOptions): Promise<void>;
+  /**
+   * Gets the number of messages waiting in the queue.
+   *
+   * This operation is optional, and may not be supported by all
+   * implementations.  The returned counts exclude messages currently being
+   * handled by a worker.
+   *
+   * @since 2.3.0
+   */
+  getDepth?(): Promise<MessageQueueDepth>;
 }
 //#endregion
 //#region src/federation/retry.d.ts
@@ -1742,187 +2508,6 @@ interface TaskEnqueueOptions {
   readonly deduplicationKey?: string;
 }
 //#endregion
-//#region src/federation/queue.d.ts
-interface SenderKeyJwkPair {
-  readonly keyId: string;
-  readonly privateKey: JsonWebKey;
-}
-/**
- * A message that represents a task to be processed by the background worker.
- * The concrete type of the message depends on the `type` property.
- *
- * Please do not depend on the concrete types of the messages, as they may
- * change in the future.  You should treat the `Message` type as an opaque
- * type.
- * @since 1.6.0
- */
-type Message = FanoutMessage | OutboxMessage | InboxMessage | TaskMessage;
-interface FanoutMessage {
-  readonly type: "fanout";
-  readonly id: ReturnType<typeof crypto.randomUUID>;
-  readonly baseUrl: string;
-  readonly keys: readonly SenderKeyJwkPair[];
-  readonly inboxes: Readonly<Record<string, {
-    readonly actorIds: readonly string[];
-    readonly sharedInbox: boolean;
-    /**
-     * The canonical form of the FEP-ef61 portable inbox that the inbox
-     * stands for.
-     * @internal
-     */
-    readonly portableInbox?: string;
-    /**
-     * The compatible identifiers of the portable inbox on each gateway to
-     * deliver through, in order.
-     * @internal
-     */
-    readonly gatewayInboxes?: readonly string[];
-  }>>;
-  readonly activity: unknown;
-  readonly activityId?: string;
-  readonly activityType: string;
-  readonly collectionSync?: string;
-  readonly orderingKey?: string;
-  /**
-   * Whether to apply outgoing JSON-LD wire-format normalization to queued
-   * activities that already carry Object Integrity Proofs.
-   *
-   * `true` is used for proofs Fedify created before fanout, or when callers
-   * explicitly request normalization for locally pre-signed activities.
-   * `false`/`undefined` preserves existing proofs as-is.
-   */
-  readonly normalizeExistingProofs?: boolean;
-  readonly traceContext: Readonly<Record<string, string>>;
-}
-interface OutboxMessage {
-  readonly type: "outbox";
-  readonly id: ReturnType<typeof crypto.randomUUID>;
-  readonly baseUrl: string;
-  readonly keys: readonly SenderKeyJwkPair[];
-  readonly activity: unknown;
-  readonly activityId?: string;
-  readonly activityType: string;
-  readonly inbox: string;
-  readonly sharedInbox: boolean;
-  readonly actorIds?: readonly string[];
-  readonly started: string;
-  readonly attempt: number;
-  readonly headers: Readonly<Record<string, string>>;
-  readonly orderingKey?: string;
-  /**
-   * Whether this message is currently held by the outbound circuit breaker.
-   * @internal
-   */
-  readonly circuitHeld?: true;
-  /**
-   * When Fedify first held this message because the remote host circuit was
-   * open.
-   * @internal
-   */
-  readonly circuitHeldSince?: string;
-  /**
-   * The canonical form of the FEP-ef61 portable inbox that {@link inbox}, its
-   * compatible identifier on a gateway, stands for.
-   * @internal
-   */
-  readonly portableInbox?: string;
-  /**
-   * The compatible identifiers of the FEP-ef61 portable inbox on each gateway
-   * that is still to be tried, in order.  {@link inbox} is the first one.
-   * If there is more than one, the activity is delivered through the first
-   * gateway that accepts it.
-   * @internal
-   */
-  readonly gatewayInboxes?: readonly string[];
-  /**
-   * The times before which each of {@link gatewayInboxes} must not be tried
-   * again, as their responses' `Retry-After` headers requested, keyed by
-   * the inbox URL, in ISO 8601.
-   * @internal
-   */
-  readonly gatewayNotBefore?: Readonly<Record<string, 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>;
-  readonly baseUrl: string;
-  readonly activity: unknown;
-  /**
-   * The normalized JSON-LD representation of a signed inbox activity that
-   * Fedify already compacted successfully while accepting the request.  Queue
-   * workers can reuse this producer-side parse cache under stricter loader or
-   * network constraints without changing the raw payload preserved for
-   * forwarding.
-   *
-   * This may exist even when {@link ldSignatureVerified} is `false`, because
-   * fallback-authenticated traffic and already-queued backlog items can still
-   * depend on the cached normalized form to avoid re-fetching remote custom
-   * contexts during worker processing.
-   *
-   * This is optional for backward compatibility with messages that were
-   * queued by older Fedify versions or that were already in a queue before
-   * upgrading.
-   *
-   * Fedify keeps this on the queued message itself instead of an external
-   * sidecar because generic queue backends do not provide reliable lifecycle
-   * guarantees for auxiliary storage across retries and redeliveries.
-   *
-   * @internal
-   */
-  readonly normalizedActivity?: unknown;
-  /**
-   * Whether the producer actually verified the Linked Data Signature before
-   * queueing this message.  This lets workers distinguish verified LDS replay
-   * from other authenticated inbox traffic that merely happened to include a
-   * signature block.  This provenance marker is separate from the optional
-   * normalizedActivity parse cache.
-   *
-   * `undefined` preserves backward compatibility with older queued messages
-   * that predate this marker.
-   *
-   * @internal
-   */
-  readonly ldSignatureVerified?: boolean;
-  /**
-   * The interpretation of the activity that Fedify authenticated, i.e., which
-   * document it was parsed from and every JSON-LD context response the parse
-   * used, so that the worker and its retries dispatch the very same
-   * interpretation without loading contexts again.  Absent in messages queued
-   * by older Fedify versions.
-   * @internal
-   */
-  readonly verifiedView?: SerializedVerifiedActivityView;
-  /**
-   * Who Fedify authenticated for the activity.  Absent in messages queued by
-   * older Fedify versions.
-   * @internal
-   */
-  readonly authentication?: SerializedInboxAuthentication;
-  readonly started: string;
-  readonly attempt: number;
-  readonly identifier: string | null;
-  readonly traceContext: Readonly<Record<string, string>>;
-}
-//#endregion
 //#region src/federation/middleware.d.ts
 /**
  * Configures the task queues for sending and receiving activities.
@@ -2058,6 +2643,31 @@ interface FederationStartQueueOptions {
  * @since 1.6.0
  */
 interface Federatable<TContextData> extends TaskRegistry<TContextData> {
+  /**
+   * Registers observers for outgoing activity processing.
+   *
+   * Each call replaces all previously registered outbound observers.
+   * Pass an empty object to clear them.  Fedify copies callbacks and capture policies;
+   * later changes to the supplied object do not affect registration.
+   * Available on builders and directly created federations.  Building copies
+   * the callbacks, and an active send keeps the callback selected at entry.
+   * Observes send, original-payload forwarding, and automatic portable
+   * replication preparation, destination planning, and handoffs, including
+   * outbox-context operations and fanout continuation handoffs. Separate
+   * callbacks report concrete send attempts and actual HTTP exchanges, including
+   * queued retries and gateway fallback. Worker reports retain local execution
+   * results and actual enqueue, retry, deferral, and abandonment actions,
+   * separately from attempts and backend acknowledgment.
+   * Known IDs, original inbox source, and
+   * application correlation survive queue work; workers use current context data.
+   * Header values, bounded response-body streaming and sender-payload projections
+   * are independently opt-in. Body consumers require explicit byte/time limits;
+   * other metadata callbacks have no default timeout.
+   * This is separate from incoming C2S {@link Federatable.setOutboxListeners}.
+   * @param observers The optional callbacks to register.
+   * @since 2.5.0
+   */
+  setOutboundObservers(observers: OutboundObservers<TContextData>): void;
   /**
    * Registers a NodeInfo dispatcher.
    * @param path The URI path pattern for the NodeInfo dispatcher.  The syntax
@@ -5165,6 +5775,14 @@ type ParseUriResult =
  * Options for {@link Context.sendActivity} method.
  */
 interface SendActivityOptions {
+  /**
+   * Application-owned correlation for this invocation, never a deduplication
+   * key. Preserved exactly, including an empty string. At most 1,024 UTF-8
+   * bytes; invalid types and oversized values are rejected before preparation.
+   * Omission means no application dispatch ID for this new invocation.
+   * @since 2.5.0
+   */
+  readonly dispatchId?: string;
   /**
    * Whether to prefer the shared inbox for the recipients.
    */