@classytic/arc 2.41.1 → 2.43.0

package/dist/discovery/index.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
 import { readdir } from "node:fs/promises";
 import { extname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/docs/index.d.mts

@@ -1,5 +1,5 @@
 
-import { p as RegistryEntry } from "../index-DHbyPo5j.mjs";
+import { o as RegistryEntry } from "../index-mqaqZNpe.mjs";
 import { t as ExternalOpenApiPaths } from "../externalPaths-CmGOxOtD.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/docs/openapi/types.d.ts
@@ -86,6 +86,14 @@ interface Operation {
     type: string;
     name: string;
   }>;
+  /** Idempotency-key fence: every call (`required`) or the listed actions (`requiredActions`). */
+  "x-arc-idempotency"?: {
+    required?: true;
+    requiredActions?: readonly string[];
+    dedup?: "handler";
+    owner?: string;
+    handlerDedup?: Readonly<Record<string, string>>;
+  };
 }
 interface Parameter {
   name: string;
@@ -137,7 +145,6 @@ interface SecurityScheme {
 }
 //#endregion
 //#region src/docs/openapi/index.d.ts
-declare const openApiPlugin: FastifyPluginAsync<OpenApiOptions>;
 /**
  * Build OpenAPI spec from registry resources.
  * Shared by HTTP docs endpoint and CLI export command.
@@ -166,7 +173,6 @@ interface ScalarOptions {
   /** Favicon URL */
   favicon?: string;
 }
-declare const scalarPlugin: FastifyPluginAsync<ScalarOptions>;
 declare const _default$1: FastifyPluginAsync<ScalarOptions>;
 //#endregion
-export { type ExternalOpenApiPaths, type OpenApiBuildOptions, type OpenApiOptions, type OpenApiSpec, type ScalarOptions, buildOpenApiSpec, _default as openApiPlugin, openApiPlugin as openApiPluginFn, _default$1 as scalarPlugin, scalarPlugin as scalarPluginFn };
+export { type ExternalOpenApiPaths, type OpenApiBuildOptions, type OpenApiOptions, type OpenApiSpec, type ScalarOptions, buildOpenApiSpec, _default as openApiPlugin, _default$1 as scalarPlugin };

package/dist/docs/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { n as getUserRoles } from "../userHelpers-ChRvkuSZ.mjs";
-import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-CmFf3yq_.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { n as getUserRoles } from "../userHelpers-aklawRaK.mjs";
+import { n as openapi_default, t as buildOpenApiSpec } from "../openapi-DT_G4VhY.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/scalar.ts
 const scalarPlugin = async (fastify, opts = {}) => {
@@ -54,4 +54,4 @@ var scalar_default = fp(scalarPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { buildOpenApiSpec, openapi_default as openApiPlugin, openApiPlugin as openApiPluginFn, scalar_default as scalarPlugin, scalarPlugin as scalarPluginFn };
+export { buildOpenApiSpec, openapi_default as openApiPlugin, scalar_default as scalarPlugin };

package/dist/{elevation-BXCfVcNG.d.mts → elevation-BW2J3tNj.d.mts}

@@ -17,7 +17,6 @@ interface ElevationEvent {
   request: FastifyRequest;
   timestamp: Date;
 }
-declare const elevationPlugin: FastifyPluginAsync<ElevationOptions>;
 declare const _default: FastifyPluginAsync<ElevationOptions>;
 //#endregion
-export { elevationPlugin as i, ElevationOptions as n, _default as r, ElevationEvent as t };
+export { ElevationOptions as n, _default as r, ElevationEvent as t };

package/dist/{elevation-CkvG0LG2.mjs → elevation-DG8SrLN-.mjs}

@@ -1,10 +1,41 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
-import { arcLog } from "./logger/index.mjs";
-import { n as requireSingleHeaderValue } from "./headers-BIXWKrzQ.mjs";
-import { n as getUserRoles } from "./userHelpers-ChRvkuSZ.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-D1w9Y1VJ.mjs";
+import { t as arcLog } from "./logger-DXjfIqjV.mjs";
+import { n as requireSingleHeaderValue } from "./headers-BbkIF6vA.mjs";
+import { n as getUserRoles } from "./userHelpers-aklawRaK.mjs";
+import { ARC_ERROR_CODES } from "@classytic/repo-core/errors";
 import fp from "fastify-plugin";
 //#region src/scope/elevation.ts
+/**
+* Elevation Plugin — Explicit Platform Admin Access
+*
+* Opt-in Fastify plugin that allows platform admins to explicitly
+* elevate their scope via the `x-arc-scope: platform` header.
+*
+* Without this header, a superadmin is treated as a normal user.
+* This prevents implicit bypass and enables audit logging.
+*
+* ## Lifecycle
+*
+* Elevation wraps `fastify.authenticate` so it always runs AFTER
+* authentication has set `request.user`. This avoids the `onRequest`
+* timing issue where `request.user` doesn't exist yet.
+*
+* Flow: `authenticate()` → user is set → `elevation check` → scope is set
+*
+* Inspired by Stripe Connect's `Stripe-Account` header.
+*
+* @example
+* ```typescript
+* const app = await createApp({
+*   auth: { type: 'betterAuth', betterAuth: adapter },
+*   elevation: {
+*     platformRoles: ['superadmin'],
+*     onElevation: (event) => auditLog.write(event),
+*   },
+* });
+* ```
+*/
 var elevation_exports = /* @__PURE__ */ __exportAll({
 	default: () => elevation_default,
 	elevationPlugin: () => elevationPlugin
@@ -25,10 +56,9 @@ const elevationPlugin = async (fastify, opts = {}) => {
 		if (!user) {
 			log.debug("Elevation requested but no user after auth");
 			reply.code(401).send({
-				success: false,
-				error: "Unauthorized",
+				code: ARC_ERROR_CODES.ELEVATION_AUTH_REQUIRED,
 				message: "Authentication required for platform elevation",
-				code: "ELEVATION_AUTH_REQUIRED"
+				status: 401
 			});
 			return;
 		}
@@ -40,10 +70,9 @@ const elevationPlugin = async (fastify, opts = {}) => {
 				required: platformRoles
 			});
 			reply.code(403).send({
-				success: false,
-				error: "Forbidden",
+				code: ARC_ERROR_CODES.ELEVATION_FORBIDDEN,
 				message: "Insufficient privileges for platform elevation",
-				code: "ELEVATION_FORBIDDEN"
+				status: 403
 			});
 			return;
 		}
@@ -95,4 +124,4 @@ var elevation_default = fp(elevationPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { elevation_default as n, elevation_exports as r, elevationPlugin as t };
+export { elevation_exports as n, elevation_default as t };

package/dist/encryption/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as ArcError } from "../errors-BH7YU_9O.mjs";
-import { t as parseJsonBody } from "../jsonBody-ELR9lfeU.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { t as ArcError } from "../errors-CtrywMHP.mjs";
+import { t as parseJsonBody } from "../jsonBody-B4YVGcql.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/encryption/fieldCipher.ts

package/dist/{errorHandler-D1GHKGlV.mjs → errorHandler-BnfDviL1.mjs}

@@ -1,8 +1,8 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
-import { m as statusToArcCode, p as isArcError } from "./errors-BH7YU_9O.mjs";
-import { isProductionEnv } from "@classytic/primitives/environment";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-D1w9Y1VJ.mjs";
+import { m as statusToArcCode, p as isArcError } from "./errors-CtrywMHP.mjs";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
+import { isProductionEnv } from "@classytic/primitives/environment";
 import fp from "fastify-plugin";
 //#region src/plugins/errorHandler.ts
 /**
@@ -154,10 +154,15 @@ async function errorHandlerPluginFn(fastify, options = {}) {
 		};
 		const status = wire.status ?? 500;
 		if (status >= 500 && wire.code === "arc.internal_error" && !exposeInternalMessages) wire.message = "Internal Server Error";
-		if (status >= 500) request.log.error({
+		const deliberateUnavailable = status === 503 && wire.code !== "arc.internal_error";
+		if (status >= 500 && !deliberateUnavailable) request.log.error({
 			err: error,
 			status
 		}, "Server error");
+		else if (deliberateUnavailable) request.log.warn({
+			code: wire.code,
+			status
+		}, "Service unavailable");
 		else if (status >= 400) request.log.warn({
 			err: error,
 			status
@@ -166,10 +171,26 @@ async function errorHandlerPluginFn(fastify, options = {}) {
 			const causeLevel = status >= 500 ? "error" : "warn";
 			request.log[causeLevel]({ cause: error.cause }, "Error cause chain");
 		}
+		if (status === 429 || status === 503) {
+			const retryAfter = retryAfterSeconds(error);
+			if (retryAfter !== void 0) reply.header("retry-after", String(retryAfter));
+		}
 		return reply.status(status).send(wire);
 	});
 }
 /**
+* Seconds to put in `Retry-After`, read from the thrown error's own
+* `retryAfter` property (the convention `RateLimitError` set). Whole seconds,
+* never below 1 — `0` would tell every client to retry immediately, which is
+* the stampede the header exists to prevent.
+*/
+function retryAfterSeconds(error) {
+	if (!error || typeof error !== "object") return void 0;
+	const value = error.retryAfter;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return void 0;
+	return Math.max(1, Math.ceil(value));
+}
+/**
 * Is `code` a caller-defined DOMAIN error code that is safe to surface on the
 * wire, as opposed to a framework/runtime code that must never leak?
 *

package/dist/{errors-BH7YU_9O.mjs → errors-CtrywMHP.mjs}

@@ -1,6 +1,26 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { ARC_ERROR_CODES } from "@classytic/repo-core/errors";
 //#region src/utils/errors.ts
 /**
+* Arc error hierarchy.
+*
+* Throw an `ArcError` (or one of its subclasses) anywhere in a controller
+* or middleware. Arc's global error handler catches it and serializes to
+* the canonical `ErrorContract` wire shape via repo-core's
+* `toErrorContract(err)` — one contract across the org.
+*
+* `ArcError` implements the {@link HttpError} contract from
+* `@classytic/repo-core/errors`, so any host that already speaks that
+* contract (mongokit, sqlitekit, streamline, prismakit) catches and
+* serializes arc errors with the same code path it uses for its own.
+*
+* **Codes are catalogued in `@classytic/repo-core/errors`** (`ARC_ERROR_CODES`,
+* `ARC_REASON_CODES`) so client SDKs read the wire vocabulary without
+* depending on arc. Emit from those constants; `tests/utils/error-code-catalog.test.ts`
+* fails on an uncatalogued `arc.*` literal. Domain packages use their own
+* namespace (`commerce.cart.locked`).
+*/
+/**
 * Base Arc Error. Implements the canonical `HttpError` contract — `status`
 * mirrors `statusCode` and `meta` mirrors `details`, so consumers reading
 * either name see the same value without adapter glue.
@@ -13,7 +33,7 @@ var ArcError = class extends Error {
 	cause;
 	constructor(message, options = {}) {
 		super(message, options.cause ? { cause: options.cause } : void 0);
-		this.code = options.code ?? "arc.error";
+		this.code = options.code ?? ARC_ERROR_CODES.ERROR;
 		this.statusCode = options.statusCode ?? 500;
 		this.details = options.details;
 		this.cause = options.cause;
@@ -32,7 +52,7 @@ var NotFoundError = class extends ArcError {
 	constructor(resource, identifier) {
 		const message = identifier ? `${resource} with identifier '${identifier}' not found` : `${resource} not found`;
 		super(message, {
-			code: "arc.not_found",
+			code: ARC_ERROR_CODES.NOT_FOUND,
 			statusCode: 404,
 			details: {
 				resource,
@@ -46,18 +66,29 @@ var ValidationError = class extends ArcError {
 	errors;
 	constructor(message, errors = []) {
 		super(message, {
-			code: "arc.validation_error",
+			code: ARC_ERROR_CODES.VALIDATION_ERROR,
 			statusCode: 400,
 			details: { errors }
 		});
 		this.name = "ValidationError";
 		this.errors = errors;
 	}
+	/**
+	* `HttpError.validationErrors` — what `toErrorContract` turns into the wire's
+	* `details[]`, the one place clients (arc-next `fieldErrors`) read field errors.
+	*/
+	get validationErrors() {
+		return this.errors.map((e) => ({
+			path: e.field,
+			validator: "validation_error",
+			error: e.message
+		}));
+	}
 };
 var UnauthorizedError = class extends ArcError {
 	constructor(message = "Authentication required") {
 		super(message, {
-			code: "arc.unauthorized",
+			code: ARC_ERROR_CODES.UNAUTHORIZED,
 			statusCode: 401
 		});
 		this.name = "UnauthorizedError";
@@ -66,7 +97,7 @@ var UnauthorizedError = class extends ArcError {
 var ForbiddenError = class extends ArcError {
 	constructor(message = "Access denied") {
 		super(message, {
-			code: "arc.forbidden",
+			code: ARC_ERROR_CODES.FORBIDDEN,
 			statusCode: 403
 		});
 		this.name = "ForbiddenError";
@@ -75,7 +106,7 @@ var ForbiddenError = class extends ArcError {
 var ConflictError = class extends ArcError {
 	constructor(message, field) {
 		super(message, {
-			code: "arc.conflict",
+			code: ARC_ERROR_CODES.CONFLICT,
 			statusCode: 409,
 			...field ? { details: { field } } : {}
 		});
@@ -86,7 +117,7 @@ var OrgRequiredError = class extends ArcError {
 	organizations;
 	constructor(message, organizations) {
 		super(message, {
-			code: "arc.org.selection_required",
+			code: ARC_ERROR_CODES.ORG_SELECTION_REQUIRED,
 			statusCode: 403,
 			...organizations ? { details: { organizations } } : {}
 		});
@@ -97,7 +128,7 @@ var OrgRequiredError = class extends ArcError {
 var OrgAccessDeniedError = class extends ArcError {
 	constructor(orgId) {
 		super("Organization access denied", {
-			code: "arc.org.access_denied",
+			code: ARC_ERROR_CODES.ORG_ACCESS_DENIED,
 			statusCode: 403,
 			...orgId ? { details: { organizationId: orgId } } : {}
 		});
@@ -108,7 +139,7 @@ var RateLimitError = class extends ArcError {
 	retryAfter;
 	constructor(message = "Too many requests", retryAfter) {
 		super(message, {
-			code: "arc.rate_limited",
+			code: ARC_ERROR_CODES.RATE_LIMITED,
 			statusCode: 429,
 			...retryAfter ? { details: { retryAfter } } : {}
 		});
@@ -119,7 +150,7 @@ var RateLimitError = class extends ArcError {
 var ServiceUnavailableError = class extends ArcError {
 	constructor(message = "Service temporarily unavailable") {
 		super(message, {
-			code: "arc.service_unavailable",
+			code: ARC_ERROR_CODES.SERVICE_UNAVAILABLE,
 			statusCode: 503
 		});
 		this.name = "ServiceUnavailableError";
@@ -130,21 +161,25 @@ var ServiceUnavailableError = class extends ArcError {
 * and the global error handler when no explicit code is supplied.
 */
 const STATUS_CODE_MAP = {
-	400: "arc.bad_request",
-	401: "arc.unauthorized",
-	403: "arc.forbidden",
-	404: "arc.not_found",
-	409: "arc.conflict",
-	422: "arc.unprocessable_entity",
-	429: "arc.rate_limited",
-	500: "arc.internal_error",
-	502: "arc.bad_gateway",
-	503: "arc.service_unavailable",
-	504: "arc.gateway_timeout"
+	400: ARC_ERROR_CODES.BAD_REQUEST,
+	401: ARC_ERROR_CODES.UNAUTHORIZED,
+	403: ARC_ERROR_CODES.FORBIDDEN,
+	404: ARC_ERROR_CODES.NOT_FOUND,
+	409: ARC_ERROR_CODES.CONFLICT,
+	412: ARC_ERROR_CODES.PRECONDITION_FAILED,
+	413: ARC_ERROR_CODES.PAYLOAD_TOO_LARGE,
+	415: ARC_ERROR_CODES.UNSUPPORTED_MEDIA_TYPE,
+	422: ARC_ERROR_CODES.UNPROCESSABLE_ENTITY,
+	429: ARC_ERROR_CODES.RATE_LIMITED,
+	500: ARC_ERROR_CODES.INTERNAL_ERROR,
+	501: ARC_ERROR_CODES.NOT_IMPLEMENTED,
+	502: ARC_ERROR_CODES.BAD_GATEWAY,
+	503: ARC_ERROR_CODES.SERVICE_UNAVAILABLE,
+	504: ARC_ERROR_CODES.GATEWAY_TIMEOUT
 };
 /** Status → canonical arc code, falling back to `arc.error`. */
 function statusToArcCode(status) {
-	return STATUS_CODE_MAP[status] ?? "arc.error";
+	return STATUS_CODE_MAP[status] ?? ARC_ERROR_CODES.ERROR;
 }
 /**
 * Quick `ArcError` constructor when the bundled subclasses don't fit.

package/dist/{errors-BGdVwP25.d.mts → errors-JYc9vwqE.d.mts}

@@ -36,6 +36,15 @@ declare class ValidationError extends ArcError {
     field: string;
     message: string;
   }>);
+  /**
+   * `HttpError.validationErrors` — what `toErrorContract` turns into the wire's
+   * `details[]`, the one place clients (arc-next `fieldErrors`) read field errors.
+   */
+  get validationErrors(): Array<{
+    path: string;
+    validator: string;
+    error: string;
+  }>;
 }
 declare class UnauthorizedError extends ArcError {
   constructor(message?: string);

package/dist/{eventPlugin-B52abJ8W.d.mts → eventPlugin-BtmA4-3P.d.mts}

@@ -1,6 +1,7 @@
 
-import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler, s as MemoryEventTransportOptions } from "./EventTransport-CbUKDzZZ.mjs";
-import { FastifyPluginAsync } from "fastify";
+import { a as EventTransport, i as EventLogger, n as DomainEvent, r as EventHandler, s as MemoryEventTransportOptions } from "./EventTransport-CiicKz2Z.mjs";
+import { FastifyInstance, FastifyPluginAsync } from "fastify";
+import { EventDurability, FactExpectation } from "@classytic/primitives/durable-events";
 //#region src/events/defineEvent.d.ts
 interface EventSchema {
   type: "object";
@@ -11,26 +12,68 @@ interface EventSchema {
   required?: string[];
   [key: string]: unknown;
 }
-interface EventDefinitionInput {
+/** A zod (v4) schema — the one way to author an event payload. Structural: arc never imports zod for it. */
+interface ZodPayloadSchema {
+  readonly _zod: {
+    readonly output: unknown;
+  };
+  safeParse(value: unknown): {
+    success: boolean;
+    error?: {
+      issues: ReadonlyArray<{
+        path: ReadonlyArray<PropertyKey>;
+        message: string;
+      }>;
+    };
+  };
+}
+/**
+ * Whether the event books money or moves stock. `'durable'` needs `occurrence` (aggregate id plus
+ * step): `.create()` derives a fixed id from it, and `fastify.events.publish` refuses the type —
+ * it is written to the outbox in its unit of work. Undeclared reads as not yet classified.
+ */
+type EventDurabilityInput<T> = {
+  durability?: "ephemeral";
+  occurrence?: never;
+  produces?: never;
+} | {
+  durability: "durable";
+  occurrence(payload: T): string;
+  produces?: readonly FactExpectation<T>[];
+};
+interface EventDefinitionBase {
   /** Event type name (e.g., 'order.created') */
   name: string;
-  /** JSON Schema for payload validation */
+  /**
+   * The payload as a zod schema — preferred. arc derives the JSON Schema (registry, AsyncAPI,
+   * contract snapshots) and the payload TYPE from it, and validates with it.
+   */
+  payload?: ZodPayloadSchema;
+  /** Raw JSON Schema, for definitions that do not use zod (kernels with no zod dependency). */
   schema?: EventSchema;
   /** Event version for schema evolution (default: 1) */
   version?: number;
   /** Human-readable description */
   description?: string;
 }
+type EventDefinitionInput<T = unknown> = EventDefinitionBase & EventDurabilityInput<T>;
 interface EventDefinitionOutput<T = unknown> {
   /** Event type name */
   readonly name: string;
-  /** JSON Schema for payload validation */
+  /** JSON Schema for payload validation — generated from `payload` when that was given. */
   readonly schema?: EventSchema;
+  /** The zod schema the payload was declared with, when it was — the registry validates with it. */
+  readonly payloadSchema?: ZodPayloadSchema;
   /** Event version */
   readonly version: number;
   /** Human-readable description */
   readonly description?: string;
-  /** Create a DomainEvent with this type + auto-generated metadata */
+  /** `undefined` = not yet classified. */
+  readonly durability?: EventDurability;
+  /** Present on a durable definition: the occurrence its fixed id derives from. */
+  occurrence?(payload: T): string;
+  readonly produces?: readonly FactExpectation<T>[];
+  /** Create a DomainEvent with this type + auto-generated metadata (a fixed id when durable) */
   create(payload: T, meta?: Partial<DomainEvent["meta"]>): DomainEvent<T>;
 }
 interface ValidationResult {
@@ -72,6 +115,7 @@ interface EventRegistry {
     version: number;
     description?: string;
     schema?: EventSchema;
+    durability?: EventDurability;
   }>;
   /**
    * Validate a payload against a registered event's schema.
@@ -94,7 +138,11 @@ interface EventRegistry {
  *
  * const event = OrderCreated.create({ orderId: '123' });
  */
-declare function defineEvent<T = unknown>(input: EventDefinitionInput): EventDefinitionOutput<T>;
+declare function defineEvent<S extends ZodPayloadSchema>(input: EventDefinitionInput<S["_zod"]["output"]> & {
+  payload: S;
+  schema?: never;
+}): EventDefinitionOutput<S["_zod"]["output"]>;
+declare function defineEvent<T = unknown>(input: EventDefinitionInput<T>): EventDefinitionOutput<T>;
 /**
  * Create an event registry for cataloging and validating events.
  *
@@ -161,8 +209,8 @@ interface RetryOptions {
    */
   onDead?: (event: DomainEvent, errors: Error[]) => void | Promise<void>;
   /**
-   * What to do when `transport.deadLetter()` ITSELF fails after retries are
-   * exhausted.
+   * What to do when retries are exhausted and no durable sink took the event —
+   * `transport.deadLetter()` / `deadLetter` failed, or neither is wired.
    *
    *  - `'rethrow'` (default) — the wrapper throws, so the transport treats
    *    the handler as failed: an at-least-once transport (Redis Streams,
@@ -278,6 +326,9 @@ interface EventPluginOptions {
    * silently drop events while requests continue succeeding. Pair with the
    * `onPublishError` callback to monitor failures, or use `wal` for
    * at-least-once delivery guarantees.
+   *
+   * Never applies to a type the `registry` declares `durability: 'durable'`: the facade
+   * refuses it with `NonDurablePublishError` (it belongs in the outbox).
    */
   failOpen?: boolean;
   /**
@@ -383,6 +434,11 @@ declare module "fastify" {
       transportName: string;
       /** Event registry for introspection (undefined when no registry configured) */
       registry?: EventRegistry;
+      /**
+       * Watch every event that reaches the transport — a live publish or an outbox relay.
+       * Read-only: a listener cannot change or stop delivery, and one that throws is ignored.
+       */
+      observe: (listener: (event: DomainEvent) => void) => () => void;
     };
   }
 }