@beignet/core 0.0.3 → 0.0.4

package/dist/ports/testing.d.ts

@@ -1,5 +1,13 @@
-import type { EventBusPort } from "./events";
-import { type CreateGateOptions, type GateDecision, type GatePort, type PolicyContextFromDefinitions, type PolicyDefinition, type PolicyMapFromDefinitions, type PolicySubjectArgs } from "./policy";
+import type { MemoryIdempotencyEntry, MemoryIdempotencyStore } from "../idempotency/index.js";
+import type { MemoryMailDelivery, NormalizedMailMessage } from "../mail/index.js";
+import type { MemoryNotificationDelivery } from "../notifications/index.js";
+import type { DrainOutboxResult, OutboxErrorInfo, OutboxMessage, OutboxMessageKind, OutboxMessageStatus } from "../outbox/index.js";
+import type { ProviderInstrumentationEventInput, ProviderInstrumentationPort } from "../providers/index.js";
+import type { ScheduleDef, ScheduleRunnerPort, ScheduleRunOptions } from "../schedules/index.js";
+import { type ActivityActor, type ActivityMetadata, type ActivityMetadataValue, type ActivityResource, type ActivityTenant, type AuditLogEntry, type AuditOutcome } from "./audit.js";
+import type { EventBusPort, JobDef, JobDispatcherPort } from "./events.js";
+import { type CreateGateOptions, type GateDecision, type GatePort, type PolicyContextFromDefinitions, type PolicyDefinition, type PolicyMapFromDefinitions, type PolicySubjectArgs } from "./policy.js";
+import type { StorageObject, StoragePort, StorageVisibility } from "./storage.js";
 /**
  * A recorded event entry from the recording event bus.
  */
@@ -7,6 +15,19 @@ export interface RecordedEvent {
     name: string;
     payload: unknown;
 }
+/**
+ * Expected fields for a recorded event assertion.
+ */
+export interface RecordedEventExpectation {
+    /**
+     * Expected event name.
+     */
+    name?: string;
+    /**
+     * Expected event payload. Object values are matched as partial objects.
+     */
+    payload?: unknown;
+}
 /**
  * Create a recording event bus for testing.
  *
@@ -30,6 +51,1013 @@ export declare function createRecordingEventBus(): {
     bus: EventBusPort;
     events: RecordedEvent[];
 };
+/**
+ * A job dispatch captured by `createRecordingJobDispatcher(...)`.
+ */
+export interface RecordedJobDispatch {
+    /**
+     * Dispatched job name.
+     */
+    name: string;
+    /**
+     * Job definition supplied to the dispatcher.
+     */
+    job: JobDef;
+    /**
+     * Payload supplied to the dispatcher.
+     */
+    payload: unknown;
+}
+/**
+ * Expected fields for a recorded job dispatch assertion.
+ */
+export interface RecordedJobDispatchExpectation {
+    /**
+     * Expected job name.
+     */
+    name?: string;
+    /**
+     * Expected job payload. Object values are matched as partial objects.
+     */
+    payload?: unknown;
+}
+/**
+ * Create a recording job dispatcher for tests.
+ *
+ * The dispatcher records dispatch intent without running the job handler. Use
+ * this when a use case or listener should enqueue work but the test does not
+ * need to execute that work inline.
+ *
+ * @returns A job dispatcher plus its captured dispatches.
+ */
+export declare function createRecordingJobDispatcher(): {
+    jobs: JobDispatcherPort;
+    dispatchedJobs: RecordedJobDispatch[];
+};
+/**
+ * A schedule run captured by `createRecordingScheduleRunner(...)`.
+ */
+export interface RecordedScheduleRun {
+    /**
+     * Schedule name.
+     */
+    name: string;
+    /**
+     * Schedule definition supplied to the runner.
+     */
+    schedule: ScheduleDef;
+    /**
+     * Payload supplied to the runner, when present.
+     */
+    payload?: unknown;
+    /**
+     * Run ID supplied by the provider or test, when present.
+     */
+    id?: string;
+    /**
+     * Provider or app source label, when present.
+     */
+    source?: string;
+    /**
+     * Scheduled timestamp supplied to the runner, when present.
+     */
+    scheduledAt?: ScheduleRunOptions["scheduledAt"];
+    /**
+     * Triggered timestamp supplied to the runner, when present.
+     */
+    triggeredAt?: ScheduleRunOptions["triggeredAt"];
+}
+/**
+ * Expected fields for a recorded schedule run assertion.
+ */
+export interface RecordedScheduleRunExpectation {
+    /**
+     * Expected schedule name.
+     */
+    name?: string;
+    /**
+     * Expected schedule payload. Object values are matched as partial objects.
+     */
+    payload?: unknown;
+    /**
+     * Expected run ID.
+     */
+    id?: string;
+    /**
+     * Expected source label.
+     */
+    source?: string;
+}
+/**
+ * Expected fields for a provider instrumentation event assertion.
+ */
+export interface ProviderInstrumentationEventExpectation {
+    /**
+     * Expected instrumentation event type.
+     */
+    type?: ProviderInstrumentationEventInput["type"];
+    /**
+     * Expected event ID.
+     */
+    id?: string;
+    /**
+     * Expected ISO timestamp.
+     */
+    timestamp?: string;
+    /**
+     * Expected request correlation ID.
+     */
+    requestId?: string;
+    /**
+     * Expected trace ID.
+     */
+    traceId?: string;
+    /**
+     * Expected span ID.
+     */
+    spanId?: string;
+    /**
+     * Expected parent span ID.
+     */
+    parentSpanId?: string;
+    /**
+     * Expected traceparent header value.
+     */
+    traceparent?: string;
+    /**
+     * Expected watcher name.
+     */
+    watcher?: string;
+    /**
+     * Expected provider name. Matches `providerName` on provider lifecycle events
+     * and `details.providerName` on provider instrumentation events.
+     */
+    providerName?: string;
+    /**
+     * Expected structured details. Object values are matched as partial objects.
+     */
+    details?: unknown;
+    /**
+     * Expected request method.
+     */
+    method?: string;
+    /**
+     * Expected request path.
+     */
+    path?: string;
+    /**
+     * Expected contract name.
+     */
+    contractName?: string;
+    /**
+     * Expected status. This matches request status codes as well as job, outbox,
+     * and schedule status strings.
+     */
+    status?: unknown;
+    /**
+     * Expected duration in milliseconds.
+     */
+    durationMs?: number;
+    /**
+     * Expected human-readable summary.
+     */
+    summary?: string;
+    /**
+     * Expected error message.
+     */
+    message?: string;
+    /**
+     * Expected stack trace.
+     */
+    stack?: string;
+    /**
+     * Expected use-case name on error events.
+     */
+    useCaseName?: string;
+    /**
+     * Expected use-case or custom event name.
+     */
+    name?: string;
+    /**
+     * Expected use-case kind.
+     */
+    kind?: "command" | "query";
+    /**
+     * Expected use-case phase.
+     */
+    phase?: "start" | "end" | "error";
+    /**
+     * Expected error summary.
+     */
+    error?: string;
+    /**
+     * Expected event bus event name.
+     */
+    eventName?: string;
+    /**
+     * Expected job name.
+     */
+    jobName?: string;
+    /**
+     * Expected outbox message ID.
+     */
+    messageId?: string;
+    /**
+     * Expected outbox message kind.
+     */
+    messageKind?: "event" | "job";
+    /**
+     * Expected outbox message name.
+     */
+    messageName?: string;
+    /**
+     * Expected schedule name.
+     */
+    scheduleName?: string;
+    /**
+     * Expected schedule cron expression.
+     */
+    cron?: string;
+    /**
+     * Expected schedule time zone.
+     */
+    timezone?: string;
+    /**
+     * Expected provider lifecycle action.
+     */
+    action?: "setup" | "start" | "stop";
+    /**
+     * Expected custom event label.
+     */
+    label?: string;
+}
+/**
+ * Source accepted by provider instrumentation assertion helpers.
+ */
+export type ProviderInstrumentationAssertionSource = readonly ProviderInstrumentationEventInput[] | {
+    /**
+     * Recorded provider instrumentation events.
+     */
+    readonly events: readonly ProviderInstrumentationEventInput[];
+};
+/**
+ * Create a recording schedule runner for tests.
+ *
+ * The runner records schedule run intent without executing the schedule
+ * handler. Use `createInlineScheduleRunner(...)` when the test should run the
+ * handler.
+ *
+ * @returns A schedule runner plus its captured runs.
+ */
+export declare function createRecordingScheduleRunner(): {
+    runner: ScheduleRunnerPort;
+    runs: RecordedScheduleRun[];
+};
+/**
+ * Create a provider instrumentation port for tests.
+ *
+ * The port records every event and can optionally disable specific watchers.
+ * Use the returned `events` array with provider instrumentation assertion
+ * helpers.
+ *
+ * @returns A provider instrumentation port plus its captured events.
+ */
+export declare function createRecordingProviderInstrumentation(options?: {
+    enabledWatchers?: readonly string[];
+    disabledWatchers?: readonly string[];
+}): {
+    instrumentation: ProviderInstrumentationPort;
+    events: ProviderInstrumentationEventInput[];
+};
+/**
+ * Options for creating a test user actor.
+ */
+export interface CreateTestUserActorOptions extends Omit<ActivityActor, "type" | "id" | "metadata"> {
+    /**
+     * Optional role stored as `actor.metadata.role`.
+     */
+    role?: string;
+    /**
+     * Additional redaction-safe actor metadata.
+     */
+    metadata?: ActivityMetadata;
+}
+/**
+ * Options for creating a test actor that represents impersonated user access.
+ */
+export interface CreateTestImpersonatedUserActorOptions extends CreateTestUserActorOptions {
+    /**
+     * Stable ID for the actor performing the impersonation.
+     */
+    impersonatorId: string;
+}
+/**
+ * Options for creating a test tenant.
+ */
+export type CreateTestTenantOptions = Omit<ActivityTenant, "id">;
+/**
+ * Context fields commonly shared by Beignet tests that exercise audit,
+ * authorization, route hooks, and use cases.
+ */
+export interface TestActivityContext {
+    /**
+     * Actor under test.
+     */
+    actor: ActivityActor;
+    /**
+     * Tenant/account/workspace scope under test.
+     */
+    tenant?: ActivityTenant;
+    /**
+     * Stable request ID for assertions.
+     */
+    requestId: string;
+    /**
+     * Optional trace ID for assertions.
+     */
+    traceId?: string;
+}
+/**
+ * Options for creating a test activity context.
+ */
+export interface CreateTestActivityContextOptions {
+    /**
+     * Actor under test.
+     *
+     * @default createTestUserActor()
+     */
+    actor?: ActivityActor;
+    /**
+     * Tenant under test. Pass `null` to omit tenant context.
+     *
+     * @default createTestTenant()
+     */
+    tenant?: ActivityTenant | null;
+    /**
+     * Request ID to expose on the context.
+     *
+     * @default "test-request"
+     */
+    requestId?: string;
+    /**
+     * Trace ID to expose on the context.
+     *
+     * @default "test-trace"
+     */
+    traceId?: string;
+}
+/**
+ * Create a predictable user actor for tests.
+ *
+ * Use this when authorization or audit assertions need a stable actor shape
+ * without repeating the `ActivityActor` object in every test.
+ *
+ * @param id - Stable user ID for the test actor.
+ * @param options - Optional display name, role, and metadata.
+ * @returns A user actor with `type: "user"`.
+ */
+export declare function createTestUserActor(id?: string, options?: CreateTestUserActorOptions): ActivityActor;
+/**
+ * Create a predictable user actor for tests that exercise impersonation.
+ *
+ * The returned actor remains the effective user, with `metadata.impersonatorId`
+ * recording who initiated the impersonated access.
+ *
+ * @param id - Stable user ID being impersonated.
+ * @param options - Impersonator ID plus optional display name, role, and metadata.
+ * @returns A user actor with impersonation metadata.
+ */
+export declare function createTestImpersonatedUserActor(id: string, options: CreateTestImpersonatedUserActorOptions): ActivityActor;
+/**
+ * Create a predictable anonymous actor for tests.
+ *
+ * @param options - Optional display name or metadata.
+ * @returns An anonymous actor with `type: "anonymous"`.
+ */
+export declare function createTestAnonymousActor(options?: Omit<ActivityActor, "type">): ActivityActor;
+/**
+ * Create a predictable service actor for tests.
+ *
+ * @param id - Stable service ID.
+ * @param options - Optional display name or metadata.
+ * @returns A service actor with `type: "service"`.
+ */
+export declare function createTestServiceActor(id?: string, options?: Omit<ActivityActor, "type" | "id">): ActivityActor;
+/**
+ * Create a predictable system actor for tests.
+ *
+ * @param id - Stable system actor ID.
+ * @param options - Optional display name or metadata.
+ * @returns A system actor with `type: "system"`.
+ */
+export declare function createTestSystemActor(id?: string, options?: Omit<ActivityActor, "type" | "id">): ActivityActor;
+/**
+ * Create a predictable tenant for tests.
+ *
+ * @param id - Stable tenant ID.
+ * @param options - Optional slug or metadata.
+ * @returns A tenant descriptor.
+ */
+export declare function createTestTenant(id?: string, options?: CreateTestTenantOptions): ActivityTenant;
+/**
+ * Create the activity fields commonly copied onto app test contexts.
+ *
+ * @param options - Optional actor, tenant, request ID, and trace ID overrides.
+ * @returns Stable activity context fields for a test.
+ */
+export declare function createTestActivityContext(options?: CreateTestActivityContextOptions): TestActivityContext;
+/**
+ * Expected audit fields used by audit assertion helpers.
+ */
+export interface AuditLogEntryExpectation {
+    /**
+     * Expected action name.
+     */
+    action?: string;
+    /**
+     * Expected actor fields.
+     */
+    actor?: Partial<ActivityActor>;
+    /**
+     * Convenience matcher for `entry.actor.id`.
+     */
+    actorId?: string;
+    /**
+     * Convenience matcher for `entry.actor.type`.
+     */
+    actorType?: ActivityActor["type"];
+    /**
+     * Expected tenant fields.
+     */
+    tenant?: Partial<ActivityTenant>;
+    /**
+     * Convenience matcher for `entry.tenant.id`.
+     */
+    tenantId?: string;
+    /**
+     * Expected resource fields.
+     */
+    resource?: Partial<ActivityResource>;
+    /**
+     * Convenience matcher for `entry.resource.id`.
+     */
+    resourceId?: string;
+    /**
+     * Convenience matcher for `entry.resource.type`.
+     */
+    resourceType?: string;
+    /**
+     * Expected audit outcome.
+     */
+    outcome?: AuditOutcome;
+    /**
+     * Convenience matcher for `entry.metadata.severity`.
+     */
+    severity?: ActivityMetadataValue;
+    /**
+     * Expected request ID.
+     */
+    requestId?: string;
+    /**
+     * Expected trace ID.
+     */
+    traceId?: string;
+    /**
+     * Expected metadata fields. Object values are matched as partial objects.
+     */
+    metadata?: ActivityMetadata;
+}
+/**
+ * Expected mail delivery fields used by mail assertion helpers.
+ */
+export interface MailDeliveryExpectation {
+    /**
+     * Expected memory delivery ID.
+     */
+    id?: string;
+    /**
+     * Expected subject.
+     */
+    subject?: string;
+    /**
+     * Expected recipients.
+     */
+    to?: NormalizedMailMessage["to"];
+    /**
+     * Expected sender.
+     */
+    from?: NormalizedMailMessage["from"];
+    /**
+     * Expected text body.
+     */
+    text?: string;
+    /**
+     * Expected HTML body.
+     */
+    html?: string;
+    /**
+     * Expected message headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Expected normalized message fields.
+     */
+    message?: Partial<NormalizedMailMessage>;
+}
+/**
+ * Expected notification delivery fields used by notification assertion helpers.
+ */
+export interface NotificationDeliveryExpectation {
+    /**
+     * Expected memory delivery ID.
+     */
+    id?: string;
+    /**
+     * Expected notification name.
+     */
+    notificationName?: string;
+    /**
+     * Expected parsed payload. Object values are matched as partial objects.
+     */
+    payload?: unknown;
+    /**
+     * Expected selected channels.
+     */
+    channels?: readonly string[];
+    /**
+     * Expected delivery metadata. Object values are matched as partial objects.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Expected storage object fields used by storage assertion helpers.
+ */
+export interface StorageObjectExpectation {
+    /**
+     * Object key to look up.
+     */
+    key: string;
+    /**
+     * Expected size in bytes.
+     */
+    size?: number;
+    /**
+     * Expected content type.
+     */
+    contentType?: string;
+    /**
+     * Expected cache-control value.
+     */
+    cacheControl?: string;
+    /**
+     * Expected storage metadata.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Expected visibility.
+     */
+    visibility?: StorageVisibility;
+    /**
+     * Expected text body. Cannot be combined with `bytes`.
+     */
+    text?: string;
+    /**
+     * Expected object bytes. Cannot be combined with `text`.
+     */
+    bytes?: Uint8Array;
+}
+/**
+ * Source accepted by outbox message assertion helpers.
+ *
+ * Use a `MemoryOutboxPort` or a snapshot returned by a test adapter. Durable
+ * SQL adapters should expose app-owned snapshots rather than widening the
+ * production `OutboxPort` read surface.
+ */
+export type OutboxMessageAssertionSource = readonly OutboxMessage[] | {
+    /**
+     * Current outbox message snapshots.
+     */
+    readonly messages: readonly OutboxMessage[];
+};
+/**
+ * Expected outbox message fields used by outbox assertion helpers.
+ */
+export interface OutboxMessageExpectation {
+    /**
+     * Expected message ID.
+     */
+    id?: string;
+    /**
+     * Expected message kind.
+     */
+    kind?: OutboxMessageKind;
+    /**
+     * Expected event or job name.
+     */
+    name?: string;
+    /**
+     * Expected JSON payload. Object values are matched as partial objects.
+     */
+    payload?: unknown;
+    /**
+     * Expected delivery status.
+     */
+    status?: OutboxMessageStatus;
+    /**
+     * Expected claim attempt count.
+     */
+    attempts?: number;
+    /**
+     * Expected maximum delivery attempts.
+     */
+    maxAttempts?: number;
+    /**
+     * Expected delivery timestamp.
+     */
+    deliveredAt?: Date | null;
+    /**
+     * Expected serialized delivery error. Object values are matched as partial
+     * objects. Pass `null` to assert no error has been recorded.
+     */
+    lastError?: Partial<OutboxErrorInfo> | null;
+}
+/**
+ * Expected fields for one outbox drain result assertion.
+ */
+export interface OutboxDrainResultExpectation {
+    /**
+     * Expected claimed count.
+     */
+    claimed?: number;
+    /**
+     * Expected delivered count.
+     */
+    delivered?: number;
+    /**
+     * Expected retried count.
+     */
+    retried?: number;
+    /**
+     * Expected dead-lettered count.
+     */
+    deadLettered?: number;
+}
+/**
+ * Source accepted by idempotency entry assertion helpers.
+ *
+ * Use a `MemoryIdempotencyStore` or a snapshot array from an app-owned adapter.
+ * Durable SQL adapters should expose app-owned snapshots rather than widening
+ * the production `IdempotencyPort` read surface.
+ */
+export type IdempotencyEntryAssertionSource = readonly MemoryIdempotencyEntry[] | Pick<MemoryIdempotencyStore, "entries">;
+/**
+ * Expected idempotency entry fields used by idempotency assertion helpers.
+ */
+export interface IdempotencyEntryExpectation {
+    /**
+     * Expected operation namespace.
+     */
+    namespace?: string;
+    /**
+     * Expected client-provided idempotency key.
+     */
+    key?: string;
+    /**
+     * Expected normalized scope key.
+     */
+    scopeKey?: string;
+    /**
+     * Expected request fingerprint.
+     */
+    fingerprint?: string;
+    /**
+     * Expected reservation status.
+     */
+    status?: MemoryIdempotencyEntry["status"];
+    /**
+     * Expected replay result. Object values are matched as partial objects.
+     */
+    result?: unknown;
+    /**
+     * Expected reservation timestamp.
+     */
+    reservedAt?: Date;
+    /**
+     * Expected completion timestamp.
+     */
+    completedAt?: Date;
+    /**
+     * Expected expiration timestamp, or `null` when no expiration is set.
+     */
+    expiresAt?: Date | null;
+}
+/**
+ * Find the first audit entry matching the expected fields.
+ *
+ * @param entries - Audit entries captured by a memory or fake audit port.
+ * @param expectation - Partial audit fields to match.
+ * @returns The first matching entry, or `undefined`.
+ */
+export declare function findAuditEntry(entries: readonly AuditLogEntry[], expectation: AuditLogEntryExpectation): AuditLogEntry | undefined;
+/**
+ * Assert that an audit entry exists and return the matching entry.
+ *
+ * The helper throws a plain `Error`, so it works with Bun, Vitest, Jest, and
+ * other test runners.
+ *
+ * @param entries - Audit entries captured by a memory or fake audit port.
+ * @param expectation - Partial audit fields to match.
+ * @returns The matching audit entry.
+ * @throws Error when no entry matches.
+ */
+export declare function assertAuditEntry(entries: readonly AuditLogEntry[], expectation: AuditLogEntryExpectation): AuditLogEntry;
+/**
+ * Assert that no audit entry matches the expected fields.
+ *
+ * @param entries - Audit entries captured by a memory or fake audit port.
+ * @param expectation - Partial audit fields to reject.
+ * @throws Error when a matching entry exists.
+ */
+export declare function assertNoAuditEntry(entries: readonly AuditLogEntry[], expectation: AuditLogEntryExpectation): void;
+/**
+ * Find the first recorded event matching the expected fields.
+ *
+ * @param events - Events captured by `createRecordingEventBus(...)`.
+ * @param expectation - Partial event fields to match.
+ * @returns The first matching event, or `undefined`.
+ */
+export declare function findRecordedEvent(events: readonly RecordedEvent[], expectation: RecordedEventExpectation): RecordedEvent | undefined;
+/**
+ * Assert that a recorded event exists and return the matching event.
+ *
+ * @param events - Events captured by `createRecordingEventBus(...)`.
+ * @param expectation - Partial event fields to match.
+ * @returns The matching event.
+ * @throws Error when no event matches.
+ */
+export declare function assertRecordedEvent(events: readonly RecordedEvent[], expectation: RecordedEventExpectation): RecordedEvent;
+/**
+ * Assert that no recorded event matches the expected fields.
+ *
+ * @param events - Events captured by `createRecordingEventBus(...)`.
+ * @param expectation - Partial event fields to reject.
+ * @throws Error when a matching event exists.
+ */
+export declare function assertNoRecordedEvent(events: readonly RecordedEvent[], expectation: RecordedEventExpectation): void;
+/**
+ * Find the first recorded job dispatch matching the expected fields.
+ *
+ * @param jobs - Job dispatches captured by `createRecordingJobDispatcher(...)`.
+ * @param expectation - Partial job fields to match.
+ * @returns The first matching dispatch, or `undefined`.
+ */
+export declare function findDispatchedJob(jobs: readonly RecordedJobDispatch[], expectation: RecordedJobDispatchExpectation): RecordedJobDispatch | undefined;
+/**
+ * Assert that a job was dispatched and return the matching dispatch.
+ *
+ * @param jobs - Job dispatches captured by `createRecordingJobDispatcher(...)`.
+ * @param expectation - Partial job fields to match.
+ * @returns The matching dispatch.
+ * @throws Error when no dispatch matches.
+ */
+export declare function assertDispatchedJob(jobs: readonly RecordedJobDispatch[], expectation: RecordedJobDispatchExpectation): RecordedJobDispatch;
+/**
+ * Assert that no job dispatch matches the expected fields.
+ *
+ * @param jobs - Job dispatches captured by `createRecordingJobDispatcher(...)`.
+ * @param expectation - Partial job fields to reject.
+ * @throws Error when a matching dispatch exists.
+ */
+export declare function assertNoDispatchedJob(jobs: readonly RecordedJobDispatch[], expectation: RecordedJobDispatchExpectation): void;
+/**
+ * Find the first recorded schedule run matching the expected fields.
+ *
+ * @param runs - Runs captured by `createRecordingScheduleRunner(...)`.
+ * @param expectation - Partial schedule fields to match.
+ * @returns The first matching schedule run, or `undefined`.
+ */
+export declare function findScheduleRun(runs: readonly RecordedScheduleRun[], expectation: RecordedScheduleRunExpectation): RecordedScheduleRun | undefined;
+/**
+ * Find the first provider instrumentation event matching the expected fields.
+ *
+ * @param source - Recording instrumentation result or event snapshot array.
+ * @param expectation - Partial event fields to match.
+ * @returns The first matching event, or `undefined`.
+ */
+export declare function findProviderInstrumentationEvent(source: ProviderInstrumentationAssertionSource, expectation: ProviderInstrumentationEventExpectation): ProviderInstrumentationEventInput | undefined;
+/**
+ * Assert that a provider instrumentation event exists and return it.
+ *
+ * @param source - Recording instrumentation result or event snapshot array.
+ * @param expectation - Partial event fields to match.
+ * @returns The matching event.
+ * @throws Error when no event matches.
+ */
+export declare function assertProviderInstrumentationEvent(source: ProviderInstrumentationAssertionSource, expectation: ProviderInstrumentationEventExpectation): ProviderInstrumentationEventInput;
+/**
+ * Assert that no provider instrumentation event matches the expected fields.
+ *
+ * @param source - Recording instrumentation result or event snapshot array.
+ * @param expectation - Partial event fields to reject.
+ * @throws Error when a matching event exists.
+ */
+export declare function assertNoProviderInstrumentationEvent(source: ProviderInstrumentationAssertionSource, expectation: ProviderInstrumentationEventExpectation): void;
+/**
+ * Assert that a schedule run was recorded and return the matching run.
+ *
+ * @param runs - Runs captured by `createRecordingScheduleRunner(...)`.
+ * @param expectation - Partial schedule fields to match.
+ * @returns The matching schedule run.
+ * @throws Error when no run matches.
+ */
+export declare function assertScheduleRun(runs: readonly RecordedScheduleRun[], expectation: RecordedScheduleRunExpectation): RecordedScheduleRun;
+/**
+ * Assert that no schedule run matches the expected fields.
+ *
+ * @param runs - Runs captured by `createRecordingScheduleRunner(...)`.
+ * @param expectation - Partial schedule fields to reject.
+ * @throws Error when a matching run exists.
+ */
+export declare function assertNoScheduleRun(runs: readonly RecordedScheduleRun[], expectation: RecordedScheduleRunExpectation): void;
+/**
+ * Find the first mail delivery matching the expected fields.
+ *
+ * @param deliveries - Deliveries captured by `createMemoryMailer(...)`.
+ * @param expectation - Partial delivery or message fields to match.
+ * @returns The first matching delivery, or `undefined`.
+ */
+export declare function findMailDelivery(deliveries: readonly MemoryMailDelivery[], expectation: MailDeliveryExpectation): MemoryMailDelivery | undefined;
+/**
+ * Assert that a mail delivery exists and return the matching delivery.
+ *
+ * @param deliveries - Deliveries captured by `createMemoryMailer(...)`.
+ * @param expectation - Partial delivery or message fields to match.
+ * @returns The matching delivery.
+ * @throws Error when no delivery matches.
+ */
+export declare function assertMailDelivery(deliveries: readonly MemoryMailDelivery[], expectation: MailDeliveryExpectation): MemoryMailDelivery;
+/**
+ * Assert that no mail delivery matches the expected fields.
+ *
+ * @param deliveries - Deliveries captured by `createMemoryMailer(...)`.
+ * @param expectation - Partial delivery or message fields to reject.
+ * @throws Error when a matching delivery exists.
+ */
+export declare function assertNoMailDelivery(deliveries: readonly MemoryMailDelivery[], expectation: MailDeliveryExpectation): void;
+/**
+ * Find the first notification delivery matching the expected fields.
+ *
+ * @param deliveries - Deliveries captured by `createMemoryNotificationPort(...)`.
+ * @param expectation - Partial delivery fields to match.
+ * @returns The first matching delivery, or `undefined`.
+ */
+export declare function findNotificationDelivery(deliveries: readonly MemoryNotificationDelivery[], expectation: NotificationDeliveryExpectation): MemoryNotificationDelivery | undefined;
+/**
+ * Assert that a notification delivery exists and return the matching delivery.
+ *
+ * @param deliveries - Deliveries captured by `createMemoryNotificationPort(...)`.
+ * @param expectation - Partial delivery fields to match.
+ * @returns The matching delivery.
+ * @throws Error when no delivery matches.
+ */
+export declare function assertNotificationDelivery(deliveries: readonly MemoryNotificationDelivery[], expectation: NotificationDeliveryExpectation): MemoryNotificationDelivery;
+/**
+ * Assert that no notification delivery matches the expected fields.
+ *
+ * @param deliveries - Deliveries captured by `createMemoryNotificationPort(...)`.
+ * @param expectation - Partial delivery fields to reject.
+ * @throws Error when a matching delivery exists.
+ */
+export declare function assertNoNotificationDelivery(deliveries: readonly MemoryNotificationDelivery[], expectation: NotificationDeliveryExpectation): void;
+/**
+ * Assert that a storage object exists and optionally matches metadata/body
+ * expectations.
+ *
+ * This helper works against any `StoragePort`, not only memory storage.
+ *
+ * @param storage - Storage port under test.
+ * @param expectation - Object key and expected fields.
+ * @returns The matching object metadata.
+ * @throws Error when the object is missing or does not match.
+ */
+export declare function assertStorageObject(storage: StoragePort, expectation: StorageObjectExpectation): Promise<StorageObject>;
+/**
+ * Assert that a storage object does not exist.
+ *
+ * @param storage - Storage port under test.
+ * @param key - Object key expected to be absent.
+ * @throws Error when the object exists.
+ */
+export declare function assertNoStorageObject(storage: StoragePort, key: string): Promise<void>;
+/**
+ * Find the first outbox message matching expected fields.
+ *
+ * @param source - Memory outbox or message snapshot array.
+ * @param expectation - Partial message fields to match.
+ * @returns The first matching message, or `undefined`.
+ */
+export declare function findOutboxMessage(source: OutboxMessageAssertionSource, expectation: OutboxMessageExpectation): OutboxMessage | undefined;
+/**
+ * Find the first idempotency entry matching expected fields.
+ *
+ * @param source - Memory idempotency store or entry snapshot array.
+ * @param expectation - Partial entry fields to match.
+ * @returns The first matching entry, or `undefined`.
+ */
+export declare function findIdempotencyEntry(source: IdempotencyEntryAssertionSource, expectation: IdempotencyEntryExpectation): MemoryIdempotencyEntry | undefined;
+/**
+ * Assert that an idempotency entry exists and return it.
+ *
+ * @param source - Memory idempotency store or entry snapshot array.
+ * @param expectation - Partial entry fields to match.
+ * @returns The matching entry.
+ * @throws Error when no entry matches.
+ */
+export declare function assertIdempotencyEntry(source: IdempotencyEntryAssertionSource, expectation: IdempotencyEntryExpectation): MemoryIdempotencyEntry;
+/**
+ * Assert that no idempotency entry matches expected fields.
+ *
+ * @param source - Memory idempotency store or entry snapshot array.
+ * @param expectation - Partial entry fields to reject.
+ * @throws Error when a matching entry exists.
+ */
+export declare function assertNoIdempotencyEntry(source: IdempotencyEntryAssertionSource, expectation: IdempotencyEntryExpectation): void;
+/**
+ * Assert that a matching idempotency entry is still in progress.
+ *
+ * @param source - Memory idempotency store or entry snapshot array.
+ * @param expectation - Entry fields to match.
+ * @returns The matching in-progress entry.
+ */
+export declare function assertIdempotencyInProgress(source: IdempotencyEntryAssertionSource, expectation?: Omit<IdempotencyEntryExpectation, "status">): MemoryIdempotencyEntry;
+/**
+ * Assert that a matching idempotency entry completed.
+ *
+ * @param source - Memory idempotency store or entry snapshot array.
+ * @param expectation - Entry fields to match.
+ * @returns The matching completed entry.
+ */
+export declare function assertIdempotencyCompleted(source: IdempotencyEntryAssertionSource, expectation?: Omit<IdempotencyEntryExpectation, "status">): MemoryIdempotencyEntry;
+/**
+ * Assert that an outbox message exists and return it.
+ *
+ * @param source - Memory outbox or message snapshot array.
+ * @param expectation - Partial message fields to match.
+ * @returns The matching message.
+ * @throws Error when no message matches.
+ */
+export declare function assertOutboxMessage(source: OutboxMessageAssertionSource, expectation: OutboxMessageExpectation): OutboxMessage;
+/**
+ * Assert that no outbox message matches expected fields.
+ *
+ * @param source - Memory outbox or message snapshot array.
+ * @param expectation - Partial message fields to reject.
+ * @throws Error when a matching message exists.
+ */
+export declare function assertNoOutboxMessage(source: OutboxMessageAssertionSource, expectation: OutboxMessageExpectation): void;
+/**
+ * Assert that an outbox message is pending.
+ *
+ * @param source - Memory outbox or message snapshot array.
+ * @param expectation - Message fields to match.
+ * @returns The matching pending message.
+ */
+export declare function assertOutboxPending(source: OutboxMessageAssertionSource, expectation?: Omit<OutboxMessageExpectation, "status">): OutboxMessage;
+/**
+ * Assert that an outbox message was delivered.
+ *
+ * @param source - Memory outbox or message snapshot array.
+ * @param expectation - Message fields to match.
+ * @returns The matching delivered message.
+ */
+export declare function assertOutboxDelivered(source: OutboxMessageAssertionSource, expectation?: Omit<OutboxMessageExpectation, "status">): OutboxMessage;
+/**
+ * Assert that an outbox message is pending after at least one failed attempt.
+ *
+ * Use this for retry-scheduled assertions after `drainOutbox(...)` returns a
+ * retried count.
+ *
+ * @param source - Memory outbox or message snapshot array.
+ * @param expectation - Message fields to match.
+ * @returns The matching retry-scheduled message.
+ */
+export declare function assertOutboxRetryScheduled(source: OutboxMessageAssertionSource, expectation?: Omit<OutboxMessageExpectation, "status">): OutboxMessage;
+/**
+ * Assert that an outbox message was dead-lettered.
+ *
+ * @param source - Memory outbox or message snapshot array.
+ * @param expectation - Message fields to match.
+ * @returns The matching dead-lettered message.
+ */
+export declare function assertOutboxDeadLettered(source: OutboxMessageAssertionSource, expectation?: Omit<OutboxMessageExpectation, "status">): OutboxMessage;
+/**
+ * Assert that a drain result matches expected counts.
+ *
+ * @param result - Result returned by `drainOutbox(...)`.
+ * @param expectation - Partial count expectation.
+ * @throws Error when any supplied count differs.
+ */
+export declare function assertOutboxDrainResult(result: DrainOutboxResult, expectation: OutboxDrainResultExpectation): void;
 /**
  * Expected outcome for one policy matrix case.
  */