@mpgd/platform 0.22.0 → 0.23.0

package/dist/notifications-conformance.d.ts

@@ -0,0 +1,529 @@
+import { type CancelNotificationReminderInput, type LocalNotificationEntry, type LocalNotificationRequest, type NotificationCapabilities, type NotificationConsentRecord, type NotificationDeliveryContent, type NotificationDeliveryOutcome, type NotificationDeliveryProviderEntry, type NotificationDeployment, type NotificationEndpointRegistration, type NotificationNotice, type NotificationNoticeIdentity, type NotificationNoticeSettings, type NotificationPermissionState, type NotificationProvider, type NotificationRuntime, type NotificationTemplateData, type NotificationTopicDeclaration, type NotificationTopicMapping, type SetNotificationReminderInput } from './notifications.js';
+import { notificationConformanceDefaultLocale, type NotificationConformanceDeliverInput, type NotificationConformanceEndpointFixture, type NotificationConformanceHostFixture, type NotificationConformanceInstallationFixture, type NotificationConformanceProfile, type NotificationConformanceProfileLimits, type NotificationConformancePromptResult, type NotificationConformanceRejectionReason, type NotificationConformanceTapInput, type NotificationConformanceVector } from './notifications-vectors.js';
+/**
+* Notifications v2 conformance runner (RFC "Conformance vectors") with the
+* in-memory reference pieces every vector needs: a fake clock; a fake host
+* with its fixture `NotificationProvider`; a fake backend that keeps sessions,
+* consent records, endpoints, server reminders, notices, and an idempotency
+* ledger, and applies the pure policy gate before every provider call; and the
+* reference notifications runtime the runner drives as the `game` actor. Pure
+* in-process code: no Phaser, DOM, network, or SDK imports. Nothing here sends
+* a real notification or grants anything.
+*
+* A P-phase provider runs the same vectors by supplying `createProvider`; the
+* runner reads the provider's capabilities and skips, with a reason, every
+* vector whose `appliesTo` they do not satisfy.
+*/
+export { notificationConformanceDefaultLocale };
+/** The evidence schema the fake host attaches to a host-rendered agreement. */
+export declare const notificationConformanceAgreementSchema = "fixture.host-agreement.v1";
+/** The fake session's installation id. */
+export declare const notificationConformanceInstallationId = "installation-1";
+/** Seconds a first `rate-limited` provider answer defers the send by when it names no delay. */
+export declare const notificationConformanceRetryAfterSeconds = 60;
+/** Seconds the fake ledger's claim lease lasts; an `ambiguous` answer keeps the claim this long. */
+export declare const notificationConformanceLeaseSeconds = 300;
+/** An operation the vector did not script; it fails the vector with its message. */
+export declare class NotificationConformanceScriptError extends Error {
+  readonly name = "NotificationConformanceScriptError";
+}
+export interface NotificationConformanceClock {
+  /** RFC 3339 timestamp of the fake "now", in the canonical form. */
+  now(): string;
+  set(at: string): void;
+  advance(seconds: number): void;
+}
+export declare function createNotificationConformanceClock(initial: string): NotificationConformanceClock;
+export interface NotificationConformanceLocalOperation {
+  readonly op: 'schedule' | 'replace' | 'cancel';
+  readonly key: string;
+  readonly topic: string;
+  readonly fireAt?: string;
+  /** Local reminders are always inexact. */
+  readonly exact?: boolean;
+}
+/** The `host` actor: what the vector scripts on the device or host side. */
+export interface NotificationConformanceHostActor {
+  queuePrompt(result: NotificationConformancePromptResult): void;
+  setPermission(state: NotificationPermissionState): void;
+  issueEndpoint(endpoint: NotificationConformanceEndpointFixture): void;
+  /** The player completes the action the host waited for, such as logging in. */
+  completeAction(): void;
+  tap(input: NotificationConformanceTapInput): void;
+  /** A process restart: provider listeners and buffered events go, host state stays. */
+  restart?(): void;
+  /** Calls that reached the host prompt API. */
+  readonly prompts: number;
+  /** Native local-notification calls, in order. */
+  readonly localOperations: readonly NotificationConformanceLocalOperation[];
+  /** Pending local notifications, read when the provider has no `listLocal`. */
+  readonly localPending?: readonly LocalNotificationEntry[];
+  /** The backend's send-time read for a `permission.serverReadable` provider (Devvit `isOptedIn`). */
+  readServerPermission?(input: {
+    readonly player: string;
+    readonly topic: string;
+  }): NotificationPermissionState | Promise<NotificationPermissionState>;
+}
+export interface NotificationConformanceHost extends NotificationConformanceHostActor {
+  readonly provider: NotificationProvider;
+  readonly localPending: readonly LocalNotificationEntry[];
+  /** Every `scheduleLocal` request the provider received, in order. */
+  readonly localRequests: readonly LocalNotificationRequest[];
+  restart(): void;
+  readServerPermission(input: {
+    readonly player: string;
+    readonly topic: string;
+  }): NotificationPermissionState;
+}
+export interface CreateNotificationConformanceHostInput {
+  readonly profile: NotificationConformanceProfile;
+  readonly catalog: readonly NotificationTopicDeclaration[];
+  readonly host?: NotificationConformanceHostFixture;
+  /** The device zone a registration reports. */
+  readonly timeZone?: string;
+}
+/**
+* The fake host and its fixture provider (RFC "Vector format", fake defaults).
+*
+* - States start at `prompt` for `os` and `game` prompts, unreadable `host`
+*   prompts read `unknown`, an unsupported profile answers `unsupported`, and a
+*   topic whose mapping needs no agreement reads `granted` and never prompts. A
+*   game-rendered consent is one boolean, as Devvit's `isOptedIn`: opted in
+*   reads `granted`, otherwise `prompt`.
+* - `actionRequired` holds the provider in `availability: 'action-required'`
+*   with `requiredAction: 'login'` until `completeAction`.
+* - A prompt consumes the next `queuePrompt` result and fails the vector when
+*   none is queued. A `denied` answer reports `prompt-with-rationale` while
+*   denials remain under `permission.promptLimit`, `blocked` once they are used
+*   up, and `denied` without a limit; `dismissed` leaves the state and counts
+*   no denial; `host-terms-declined` reaches the prompt and answers
+*   `action-required` with `requiredAction: 'host-settings'`. An unreadable
+*   host still reports the state its prompt just decided.
+* - Registrations carry the device permission and zone, never an installation
+*   id; `issueEndpoint` after the provider's first subscriber emits
+*   `endpoint-changed`. Events before the first subscriber are buffered for
+*   it, and a tap is `cold` before that subscriber and `warm` after. A
+*   listener's error fails the host call that delivered the event, after every
+*   listener ran.
+*/
+export declare function createNotificationConformanceHost(input: CreateNotificationConformanceHostInput): NotificationConformanceHost;
+/**
+* The registry entry the fake backend derives for a provider (RFC "Vector
+* format"): purposes, addressing, content, and permission fields from its
+* capabilities; `expiry` and `actions` for a free-form device provider; `link`
+* for `host-link` opens; per-recipient limits from `perUserPerDay` and
+* `perUserPerMinute`, the daily one first; and no `rate`. `undefined` for a
+* provider without remote delivery.
+*/
+export declare function notificationConformanceRegistryEntry(input: {
+  readonly provider: string;
+  readonly capabilities: NotificationCapabilities;
+  readonly limits?: NotificationConformanceProfileLimits;
+}): NotificationDeliveryProviderEntry | undefined;
+/** An authenticated game-services session; its installation id is the session's, never a request's. */
+export interface NotificationConformanceSession {
+  readonly id: string;
+  readonly player: string;
+  readonly installationId: string;
+}
+/** What setting a server reminder answers: stored, or the gate step 3 to 5 refusal. */
+export type NotificationConformanceReminderSetStatus = 'scheduled' | 'replaced' | 'permission-required' | 'request-missing' | 'preference-off' | 'advertising-consent-missing';
+export type NotificationConformanceNoticeChannel = 'in-game' | 'push' | 'other';
+/** The backend surface the runtime calls for the authenticated session. */
+export interface NotificationConformanceBackendClient {
+  /** The authenticated session; `undefined` before authentication and after the session ends. */
+  session(): NotificationConformanceSession | undefined;
+  /** Calls `listener` whenever a session starts; returns the unsubscribe. */
+  onAuthenticated(listener: (session: NotificationConformanceSession) => void): () => void;
+  /** Appends a record for the session's player; the backend stamps `at` with its own clock. */
+  recordConsent(record: NotificationConsentRecord): Promise<void>;
+  /** The session player's consent records, oldest first. */
+  listConsent(): Promise<readonly NotificationConsentRecord[]>;
+  /**
+  * Binds a device registration to the session's installation and player, or
+  * keeps a platform-user registration's locale and zone for the player.
+  */
+  registerEndpoint(registration: NotificationEndpointRegistration): Promise<void>;
+  /**
+  * Unbinds the session's installation from `player`, the player whose
+  * session sent the unbind; an installation another player took over since
+  * stays bound.
+  */
+  unregisterEndpoint(input: {
+    readonly provider: string;
+    readonly player: string;
+  }): Promise<void>;
+  /** Checks gate steps 3 to 5, then stores or replaces the session player's reminder with this key. */
+  setReminder(input: SetNotificationReminderInput): Promise<NotificationConformanceReminderSetStatus>;
+  /** Whether a pending reminder with this key, or a waiting send of one, existed. */
+  cancelReminder(input: CancelNotificationReminderInput): Promise<boolean>;
+  /** The session player's listed notices; none unless the deployment applies the Korean rules. */
+  listNotices(): Promise<readonly NotificationNotice[]>;
+  /**
+  * Records a notice given to the session's player, named by its identity
+  * fields, while that notice is listed; recording one that is not listed
+  * changes nothing.
+  */
+  recordNotice(input: NotificationNoticeIdentity & {
+    readonly channel: NotificationConformanceNoticeChannel;
+  }): Promise<void>;
+}
+export type NotificationConformanceStoredConsent = NotificationConsentRecord & {
+  readonly player: string;
+};
+export interface NotificationConformanceEndpoint {
+  readonly provider: string;
+  readonly kind: 'fcm-token' | 'fcm-installation';
+  readonly value: string;
+  readonly environment?: 'production' | 'sandbox';
+  readonly installationId: string;
+  /** The device permission the latest registration reported. */
+  readonly permission: NotificationPermissionState;
+  readonly player: string;
+  readonly status: 'valid' | 'invalid';
+  readonly locale?: string;
+  readonly timeZone?: string;
+  readonly lastRegisteredAt: string;
+  /** The session that registered the endpoint; its end unbinds it. */
+  readonly session?: string;
+}
+/** One outcome answered or stored for a send key, in order. */
+export type NotificationConformanceDelivery = NotificationDeliveryOutcome & {
+  readonly idempotencyKey: string;
+  readonly topic: string;
+  readonly player: string;
+  readonly at: string;
+};
+export interface NotificationConformanceProviderCall {
+  /** The ledger key: the send key, or `<key>:<installation id>` for a device endpoint. */
+  readonly idempotencyKey: string;
+  readonly sendKey: string;
+  readonly provider: string;
+  readonly topic: string;
+  readonly player: string;
+  /** The device address value, for device addressing. */
+  readonly address?: string;
+  readonly mapping?: NotificationTopicMapping;
+  /** The send's link, else the mapping's. */
+  readonly link?: string;
+  readonly content: NotificationDeliveryContent;
+  readonly expiresAt?: string;
+  readonly templateData?: NotificationTemplateData;
+  readonly data?: Readonly<Record<string, string>>;
+  readonly at: string;
+}
+export interface NotificationConformanceServerReminder {
+  readonly player: string;
+  readonly key: string;
+  readonly topic: string;
+  readonly fireAt: string;
+  readonly templateData?: NotificationTemplateData;
+  readonly link?: string;
+}
+/** A notice given to a player: which notice, how, and when. */
+export interface NotificationConformanceNoticeRecord extends NotificationNoticeIdentity {
+  readonly player: string;
+  readonly channel: NotificationConformanceNoticeChannel;
+  /** When it was given. */
+  readonly at: string;
+}
+/** A queued answer of the server-side delivery provider (RFC "Provider answers"). */
+export type NotificationConformanceProviderResult = {
+  readonly status: 'accepted';
+} | {
+  readonly status: 'unregistered';
+} | {
+  readonly status: 'rate-limited';
+  readonly retryAfterSeconds?: number;
+} | {
+  readonly status: 'rejected';
+  readonly reason: NotificationConformanceRejectionReason;
+} | {
+  readonly status: 'ambiguous';
+};
+export interface NotificationConformanceBackend extends NotificationConformanceBackendClient {
+  /** Starts a new session for `player` on the fake installation and tells the listeners. */
+  authenticate(player: string): NotificationConformanceSession;
+  /** Ends the current session; the endpoints it registered are unbound. */
+  revokeSession(): void;
+  /** Binds another installation of the default player (the `backend.registerEndpoint` action). */
+  registerInstallation(input: NotificationConformanceInstallationFixture): void;
+  /** One send through the idempotency ledger, the policy gate, and the delivery provider. */
+  deliver(input: NotificationConformanceDeliverInput): Promise<NotificationDeliveryOutcome>;
+  queueProviderResult(result: NotificationConformanceProviderResult): void;
+  /** Processes every due server reminder, stored send, and notice, earliest first. */
+  runScheduler(): Promise<void>;
+  /** The provider's registry entry; `undefined` when the provider has no remote delivery. */
+  readonly entry: NotificationDeliveryProviderEntry | undefined;
+  readonly consent: readonly NotificationConformanceStoredConsent[];
+  readonly endpoints: readonly NotificationConformanceEndpoint[];
+  readonly deliveries: readonly NotificationConformanceDelivery[];
+  readonly providerCalls: readonly NotificationConformanceProviderCall[];
+  readonly reminders: readonly NotificationConformanceServerReminder[];
+  /** Every player's listed notices, ordered by `dueBy` and then `kind`. */
+  readonly notices: readonly (NotificationNotice & {
+    readonly player: string;
+  })[];
+  readonly noticesGiven: readonly NotificationConformanceNoticeRecord[];
+}
+export interface CreateNotificationConformanceBackendInput {
+  /** The delivery provider's registry entry; `undefined` for a provider without remote delivery. */
+  readonly entry: NotificationDeliveryProviderEntry | undefined;
+  readonly catalog: readonly NotificationTopicDeclaration[];
+  readonly clock: Pick<NotificationConformanceClock, 'now'>;
+  readonly deployment?: NotificationDeployment;
+  /**
+  * The catalog's `notices` block as is: the topic consent notice pushes go
+  * out through, and their copy, which follows the catalog's rules
+  * (`notificationNoticeCopyIssues` with `defaultLocale`). Without it the
+  * scheduler sends no notice.
+  */
+  readonly notices?: NotificationNoticeSettings;
+  readonly defaultLocale: string;
+  /** The recipient of a `deliver` without a `player`, and the owner of `registerInstallation`. */
+  readonly defaultPlayer: string;
+  /** The host's answer at send time; required for a server-readable provider. */
+  readonly readServerPermission?: (input: {
+    readonly player: string;
+    readonly topic: string;
+  }) => NotificationPermissionState | Promise<NotificationPermissionState>;
+}
+/**
+* The fake backend (RFC "Server").
+*
+* - Sessions: each `authenticate` starts a new session on the fake
+*   installation, and `revokeSession` ends it and unbinds the endpoints it
+*   registered. Consent records, registrations, reminders, and notices belong
+*   to the session's player. The backend stamps each record's `at` with its
+*   own clock, strictly after the player's previous record, so a record's
+*   kind and time name it, and so does each notice that reports on it. It
+*   records a notice only while that notice is listed, so a retried or early
+*   call changes nothing, and a pushed notice the game gave while the push
+*   waited is not sent again. Notices go out through `notices.topic` only on
+*   a target that declares it; a target that delivers advertising under the
+*   Korean rules must declare it, as the catalog validator requires, and
+*   `notices.copy` must follow the catalog's rules.
+* - Endpoints: a device endpoint is keyed by provider and installation, keeps
+*   the latest address, permission, and `lastRegisteredAt`, and moves with the
+*   installation to a newly authenticated player. An address is unique per
+*   provider, a dead address stays dead until the installation reports a new
+*   one, and an endpoint not refreshed for 60 days counts as missing. A
+*   platform-user provider resolves the authenticated identity and keeps the
+*   player's locale and zone.
+* - Sends: a send is validated (input bounds, reserved prefixes), bound to
+*   its fingerprint (`NOTIFICATIONS_IDEMPOTENCY_CONFLICT` for another request),
+*   and answered from its key state: `delivered` with `alreadyProcessed`, the
+*   stored `deferred` result, or `in-flight`. A new key runs the gate for each
+*   recipient (every valid endpoint in installation-id order, each under
+*   `<key>:<installation id>`, or the platform identity) and calls the
+*   provider for the allowed ones. The send is `delivered` when any recipient
+*   accepted, else `in-flight`, `deferred` (the earliest), a provider's
+*   refusal, a policy refusal, and last an unresolved recipient. Only
+*   delivered, deferred, and in-flight rows are stored.
+* - Provider answers come from `queueProviderResult`, `accepted` when none is
+*   queued: `unregistered` invalidates the endpoint; `rate-limited` defers by
+*   `retryAfterSeconds` (60 when absent), then by doubling delays without
+*   jitter, never past 24 hours after the first, and then gives up;
+*   `rejected` is not stored, and with
+*   `agreement` appends a `host-agreement` record of `denied` from the
+*   provider; `ambiguous` keeps the claim for the 300-second lease.
+* - The scheduler processes due server reminders (as `reminder:` sends), due
+*   stored rows (deferred ones, and in-flight ones of scheduled sends or
+*   device endpoints after the lease, replayed through the gate without the
+*   key lookup), and, under the Korean rules, every unrecorded notice from the
+*   Asia/Seoul date seven days before it is due (as a `notice:` send of the
+*   notice topic in the variant of `notices.copy` it is listed with, filled
+*   with `{{consentDate}}`, and recorded with channel `push` once delivered),
+*   earliest first and within the registry entry's `rate`. Only a provider
+*   that can carry a notice (`notificationProviderCarriesNotices`) sends one,
+*   and never with its mapping's own text; a notice that cannot render is
+*   not tried again. A direct caller replays its own in-flight platform send
+*   after the lease. Keys are kept for 30 days after their last change.
+* - The notice topic is the scheduler's: `deliver` and `setReminder` through
+*   it throw `NOTIFICATIONS_INVALID_INPUT`.
+* - Setting or cancelling a reminder drops its sends' rows that still wait
+*   (deferred) or are in flight, so neither is replayed; a send the provider
+*   may already have accepted cannot be recalled. A send's limits count the
+*   player's other sends, never an earlier delivery of the same send to
+*   another endpoint. A send the gate cannot evaluate as asked (such as missing
+*   template data) answers `NOTIFICATIONS_INVALID_INPUT` directly and fails
+*   once when scheduled; any other failure, such as a host read that throws,
+*   is retried on the next run, and one failing item never stops the others.
+*/
+export declare function createNotificationConformanceBackend(input: CreateNotificationConformanceBackendInput): NotificationConformanceBackend;
+export interface NotificationConformanceRuntime extends NotificationRuntime {
+  /**
+  * Subscribes to the provider and to authentication, compares the provider
+  * with its registry entry, and reconciles pending local reminders. Provider
+  * events are buffered for the game's first listener.
+  */
+  start(): Promise<void>;
+  /** Drops listeners, buffered events, and both subscriptions. */
+  stop(): void;
+  /** Waits for event-driven work (records, registrations, local reminders) and rethrows its first failure. */
+  runUntilIdle(): Promise<void>;
+}
+/** What the runtime keeps across restarts. */
+export interface NotificationConformanceRuntimeStorage {
+  /** The last registration the backend acknowledged. */
+  registration?: NotificationConformancePersistedRegistration;
+  /** Set by `unregister()`; `register()` or the next authentication clears it. */
+  unbound?: boolean;
+}
+export interface NotificationConformancePersistedRegistration {
+  readonly registration: NotificationEndpointRegistration;
+  readonly player: string;
+  readonly session: string;
+  readonly at: string;
+}
+export interface CreateNotificationConformanceRuntimeInput {
+  readonly provider: NotificationProvider;
+  readonly backend: NotificationConformanceBackendClient;
+  /** The provider's topics, each with this target's mapping. */
+  readonly catalog: readonly NotificationTopicDeclaration[];
+  readonly clock: Pick<NotificationConformanceClock, 'now'>;
+  /** The deployment's zone, for local quiet hours while the device has registered none. */
+  readonly timeZone: string;
+  readonly defaultLocale: string;
+  /** The device locale for local reminder copy; defaults to `defaultLocale`. */
+  readonly locale?: string;
+  /** Survives restarts; a fresh object when absent. */
+  readonly storage?: NotificationConformanceRuntimeStorage;
+  /**
+  * The backend's registry entry for this provider. When the provider's
+  * capabilities disagree with it at start, every call throws
+  * `NOTIFICATIONS_CONFIGURATION_REQUIRED`.
+  */
+  readonly registryEntry?: NotificationDeliveryProviderEntry;
+}
+/**
+* The reference notifications runtime (RFC "Runtime"): the provider composed
+* with the backend for the authenticated session.
+*
+* - Reads return the provider snapshot. A topic the host reads `unknown`
+*   takes the latest record, `sources` says which answered, and a
+*   game-rendered consent that is not opted in reads `prompt` until a
+*   decision is recorded and `denied` after it. A topic whose mapping needs no
+*   agreement reads `granted`. A read that observes a changed decided state
+*   records it, and every read still answers when the backend cannot.
+* - Reads, requests, and revocations take each topic once, however often it
+*   is listed.
+* - Requests throw `NOTIFICATIONS_USER_GESTURE_REQUIRED` without a gesture on
+*   a gesture-only provider. An unsupported provider answers `unavailable`, a
+*   provider in `action-required` answers that with its `requiredAction`, an
+*   undeclared or unmapped topic answers `unavailable`, a topic that needs no
+*   agreement answers `already-granted`, and a topic the host reads `blocked`
+*   answers `blocked`, all without reaching the host; every other topic
+*   reaches the prompt.
+* - Records: decided states that differ from the latest record of their kind
+*   and scope, never `dismissed` or `action-required` answers. Device
+*   providers write none (the endpoint holds the permission), other app-scope
+*   providers write `delivery-permission`, and topic-scope providers write
+*   `host-agreement` with the host evidence, plus a `topic-preference` of
+*   `granted` when the player accepts a `requested` topic's agreement.
+*   Per-send acceptances are appended every time. A record belongs to the
+*   player signed in when the call or event began: one observed before
+*   authentication waits for it (only the latest per kind and scope), and one
+*   observed for a player waits for that player's session. A player action
+*   (`setTopicPreference`, `setAdvertisingConsent`) needs an authenticated
+*   player and throws `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` without one, as
+*   does every other backend call (a server reminder, `reminders.cancel`'s
+*   server part, and `notices`). A backend call belongs to the player signed
+*   in when it began and is refused when another player signed in since. A
+*   record the backend would refuse is dropped and its error surfaces.
+* - Registrations: the provider's registration goes to the backend at
+*   authentication, on `register()`, on `endpoint-changed` (a rotated device
+*   address, or a platform user's changed locale or zone), and when a read
+*   or request, or a revocation, changes the device's decided permission; and
+*   at start and on reads once the last one the backend acknowledged is older
+*   than 7 days. An identical one for the same player and session is skipped
+*   for 7 days, except on `register()`. `unregister()` unbinds the
+*   installation from the player signed in when it was called and cancels the
+*   pending local reminders, even when the unbind fails, and nothing binds it
+*   again, across restarts, until `register()` or the next authentication.
+* - Reminders: one key across both routes, and `cancel` removes it from each
+*   route that has it. Local ones pass the client gate steps (permission,
+*   then the topic preference from the backend, then quiet hours, which move
+*   them or refuse a topic that is not deferrable, then the topic's daily
+*   cap); server ones are checked and stored by the backend. Turning a topic off cancels its local
+*   reminders, a known permission other than granted cancels them, and start,
+*   authentication, and every backend read reconcile them with the catalog
+*   (a topic that no longer takes the local route loses its reminders), the
+*   latest preference, and permission.
+* - Game listeners run after the runtime's own handling of an event; a
+*   listener that throws stops neither the others nor the runtime, and its
+*   error surfaces from `runUntilIdle`, as do failures of background work:
+*   the first one, or an `AggregateError` that counts them all. `stop()` and
+*   a later `start()` buffer events for the next first subscriber again.
+*/
+export declare function createNotificationConformanceRuntime(input: CreateNotificationConformanceRuntimeInput): NotificationConformanceRuntime;
+export interface NotificationConformanceHarness {
+  readonly provider: NotificationProvider;
+  /**
+  * Handles `host` steps and counts prompts and local operations. A vector
+  * that scripts the host, or expects `prompts` or `local.operations` (or
+  * `local.pending` from a provider without `listLocal`), fails without it.
+  */
+  readonly host?: NotificationConformanceHostActor;
+  /**
+  * The evidence schema this provider attaches to a host agreement. Vector
+  * expectations naming the fixture schema `fixture.host-agreement.v1` match
+  * it instead.
+  */
+  readonly hostAgreementEvidenceSchema?: string;
+}
+export interface NotificationConformanceContext {
+  readonly vector: NotificationConformanceVector;
+  readonly profile: NotificationConformanceProfile;
+  readonly catalog: readonly NotificationTopicDeclaration[];
+  readonly clock: NotificationConformanceClock;
+  readonly player: string;
+  /** The device zone, which the provider registers. */
+  readonly timeZone: string;
+}
+export interface NotificationConformanceRunOptions {
+  /** Supplies a provider over the caller's fake SDK; defaults to the fake host's fixture provider. */
+  readonly createProvider?: (context: NotificationConformanceContext) => NotificationConformanceHarness | Promise<NotificationConformanceHarness>;
+  /**
+  * The backend's and the runtime's default locale;
+  * `notificationConformanceDefaultLocale` when absent. A vector's
+  * `notices.copy` must include it, or the vector fails at `backend`.
+  */
+  readonly defaultLocale?: string;
+}
+export interface NotificationConformanceFailure {
+  readonly path: string;
+  readonly expected: unknown;
+  readonly actual: unknown;
+}
+export type NotificationConformanceVectorStatus = 'passed' | 'failed' | 'skipped';
+export interface NotificationConformanceVectorResult {
+  readonly vector: string;
+  /** `skipped` vectors did not run; `passed` is false and `reason` says why. */
+  readonly status: NotificationConformanceVectorStatus;
+  readonly passed: boolean;
+  readonly failures: readonly NotificationConformanceFailure[];
+  readonly reason?: string;
+}
+export declare function createNotificationConformanceHarness(context: NotificationConformanceContext): NotificationConformanceHarness;
+/** Why `vector` does not apply to a provider with `capabilities`, or `undefined` when it runs. */
+export declare function notificationConformanceSkipReason(vector: NotificationConformanceVector, capabilities: NotificationCapabilities): string | undefined;
+/**
+* Runs one vector: reads the provider's capabilities and skips the vector when
+* they do not satisfy `appliesTo`, executes every step (a step's `returns` is
+* matched as a subset, its `throws` by `code`), lets the runtime settle after
+* each, then matches `expect`. Lists match exactly in length and order with
+* only the listed fields of each item asserted, a field set to `null` asserts
+* that it is absent, and timestamps compare as instants. Any unscripted
+* operation fails the vector at the step that needed it.
+*
+* The backend's registry entry is derived from the provider's own
+* capabilities and the profile's limits. A `setReminder` step that expects a
+* local `permission-required` also calls the provider's `scheduleLocal`
+* directly: it must answer `permission-required` without prompting or
+* scheduling. With `options.createProvider`, the fixture provider id and the
+* fixture agreement evidence schema in `returns` and `expect` match the
+* provider under test's own id and `hostAgreementEvidenceSchema`.
+*/
+export declare function runNotificationConformanceVector(vector: NotificationConformanceVector, options?: NotificationConformanceRunOptions): Promise<NotificationConformanceVectorResult>;
+export declare function runNotificationConformanceVectors(vectors: readonly NotificationConformanceVector[], options?: NotificationConformanceRunOptions): Promise<readonly NotificationConformanceVectorResult[]>;