@crvouga/mockingbird-service-microsoft 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1878 @@
+/*! Adapted from vercel-labs/emulate (Apache-2.0), modified for Mockingbird. See port.json, LICENSE_EMULATE and THIRD_PARTY_NOTICES.md. */
+/*!
+ * This HTTP compatibility layer builds on Hono's API and design.
+ * https://github.com/honojs/hono
+ * Copyright (c) 2021 - present, Yusuke Wada and Hono contributors
+ * MIT license: see THIRD_PARTY_NOTICES.md in the repository and npm packages.
+ */
+type BodyInit = ConstructorParameters<typeof Response>[0];
+type HeadersInit = ConstructorParameters<typeof Headers>[0];
+type FormDataEntryValue = string | File;
+type ContentfulStatusCode = number;
+type Next = () => Promise<void>;
+type VariablesOf<E> = unknown extends E ? Record<string, any> : E extends {
+    Variables: infer V;
+} ? V : Record<string, any>;
+type HandlerResult = Response | void | Promise<Response | void>;
+type Handler<E = unknown, P extends string = string> = (c: Context<E, P>, next: Next) => HandlerResult;
+type ErrorHandler<E = unknown> = (err: unknown, c: Context<E>) => Response | Promise<Response>;
+interface HttpOptions {
+    strictRoutes?: boolean;
+    strictJson?: boolean;
+    onError?: (error: unknown, request: Request) => void;
+}
+interface RouteInfo {
+    method: string;
+    path: string;
+    source?: string;
+}
+declare class HonoRequest<P extends string = string> {
+    private readonly params;
+    private readonly strictJson;
+    readonly raw: Request;
+    readonly url: string;
+    readonly method: string;
+    readonly path: string;
+    constructor(request: Request, params: Record<string, string>, strictJson?: boolean);
+    header(): Record<string, string>;
+    header(name: string): string | undefined;
+    query(name: string): string | undefined;
+    queries(name: string): string[] | undefined;
+    param(): Record<string, string>;
+    param(name: string): string;
+    json<T = any>(): Promise<T>;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    parseBody(): Promise<Record<string, FormDataEntryValue | FormDataEntryValue[]>>;
+}
+declare class Context<E = unknown, P extends string = string> {
+    private readonly notFoundHandler;
+    readonly req: HonoRequest<P>;
+    private readonly vars;
+    private readonly responseHeaders;
+    private readonly headerOperations;
+    private readonly appliedHeaders;
+    private responseStatus;
+    constructor(request: Request, params: Record<string, string>, notFoundHandler: (c: Context<E>) => Response | Promise<Response>, strictJson?: boolean);
+    get<K extends keyof VariablesOf<E> & string>(key: K): VariablesOf<E>[K] | undefined;
+    set<K extends keyof VariablesOf<E> & string>(key: K, value: VariablesOf<E>[K]): void;
+    header(name: string, value: string, options?: {
+        append?: boolean;
+    }): void;
+    status(status: number): void;
+    json(data: unknown, status?: ContentfulStatusCode, headers?: HeadersInit): Response;
+    text(text: string, status?: ContentfulStatusCode, headers?: HeadersInit): Response;
+    html(html: string, status?: ContentfulStatusCode, headers?: HeadersInit): Response;
+    body(body: BodyInit | null, status?: ContentfulStatusCode, headers?: HeadersInit): Response;
+    redirect(location: string, status?: ContentfulStatusCode): Response;
+    notFound(): Response | Promise<Response>;
+    finalize(response: Response): Response;
+    private response;
+}
+declare class Hono<E = unknown> {
+    private readonly options;
+    constructor(options?: HttpOptions);
+    get routeTable(): RouteInfo[];
+    matchedRoute(method: string, path: string): RouteInfo | undefined;
+    private readonly middleware;
+    private readonly routes;
+    private errorHandler;
+    private notFoundHandler;
+    use<P extends string = string>(path: string, ...handlers: Handler<E, P>[]): this;
+    use(...handlers: Handler<E>[]): this;
+    on<P extends string = string>(method: string, path: string, ...handlers: Handler<E, P>[]): this;
+    get<P extends string = string>(path: string, ...handlers: Handler<E, P>[]): this;
+    post<P extends string = string>(path: string, ...handlers: Handler<E, P>[]): this;
+    put<P extends string = string>(path: string, ...handlers: Handler<E, P>[]): this;
+    patch<P extends string = string>(path: string, ...handlers: Handler<E, P>[]): this;
+    delete<P extends string = string>(path: string, ...handlers: Handler<E, P>[]): this;
+    onError(handler: ErrorHandler<E>): this;
+    notFound(handler: (c: Context<E>) => Response | Promise<Response>): this;
+    request(input: string | Request, init?: RequestInit): Promise<Response>;
+    fetch: (request: Request) => Promise<Response>;
+    private match;
+    private dispatch;
+}
+
+/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
+type SqliteValue$3 = null | number | bigint | string | Uint8Array | boolean;
+/** Mutation counters returned by {@link SqliteStatement.run}. */
+type SqliteRunResult$3 = {
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * Prepared statement bound to a {@link SqliteClient}.
+ *
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
+ */
+interface SqliteStatement$3 {
+    run(...params: SqliteValue$3[]): SqliteRunResult$3;
+    all<T = Record<string, unknown>>(...params: SqliteValue$3[]): T[];
+    get<T = Record<string, unknown>>(...params: SqliteValue$3[]): T | undefined;
+}
+/**
+ * Sync SQLite client port owned by Mockingbird.
+ *
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
+ * `bun:sqlite` instances all work when they expose this surface.
+ */
+interface SqliteClient$3 {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement$3;
+    transaction<T>(fn: () => T): T;
+}
+
+/** Every stored record carries a monotonically increasing sequence for stable ordering. */
+type Stored<T> = {
+    seq: number;
+    value: T;
+};
+type ListRecordsOptions<T> = {
+    /** Keep only records passing the predicate. */
+    where?: (value: T, seq: number) => boolean;
+    /** Sort order; default newest first. */
+    order?: "newest" | "oldest";
+};
+/**
+ * A SQLite-backed table of JSON records addressed by id. Ordering is by insertion
+ * sequence, never by id lexicographic order, so list semantics stay stable.
+ */
+declare class Collection$1<T> {
+    private readonly sqlite;
+    /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
+    readonly namespace: string;
+    /** Table name inside the namespace. Stable across resets of the rows themselves. */
+    readonly collectionName: string;
+    constructor(sqlite: SqliteClient$3, 
+    /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
+    namespace: string, 
+    /** Table name inside the namespace. Stable across resets of the rows themselves. */
+    collectionName: string);
+    private bumpCollectionSeq;
+    nextSequence(): number;
+    get(id: string): T | undefined;
+    has(id: string): boolean;
+    /** Insert a new record, assigning it the next sequence number. */
+    insert(id: string, value: T): Stored<T>;
+    /** Replace an existing record's value, keeping its position. */
+    update(id: string, value: T): Stored<T> | undefined;
+    delete(id: string): boolean;
+    /** How many records the collection holds, without reading them. */
+    count(): number;
+    list(options?: ListRecordsOptions<T>): Array<Stored<T> & {
+        id: string;
+    }>;
+}
+
+/** Options every provider constructor accepts. */
+type APIOptions = {
+    /** Sync SQLite client. Defaults to `@crvouga/mockingbird-service-sqlite`. */
+    sqlite?: SqliteClient$3;
+    /** Clock used for `created`-style fields. Default `Date.now`. */
+    now?: () => number;
+    /**
+     * Storage namespace for this instance's records. Instances sharing one SQLite
+     * client stay isolated when their namespaces differ. Defaults to the service name.
+     */
+    namespace?: string;
+};
+
+/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
+type SqliteValue$2 = null | number | bigint | string | Uint8Array | boolean;
+/** Mutation counters returned by {@link SqliteStatement.run}. */
+type SqliteRunResult$2 = {
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * Prepared statement bound to a {@link SqliteClient}.
+ *
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
+ */
+interface SqliteStatement$2 {
+    run(...params: SqliteValue$2[]): SqliteRunResult$2;
+    all<T = Record<string, unknown>>(...params: SqliteValue$2[]): T[];
+    get<T = Record<string, unknown>>(...params: SqliteValue$2[]): T | undefined;
+}
+/**
+ * Sync SQLite client port owned by Mockingbird.
+ *
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
+ * `bun:sqlite` instances all work when they expose this surface.
+ */
+interface SqliteClient$2 {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement$2;
+    transaction<T>(fn: () => T): T;
+}
+
+/*! Adapted from vercel-labs/emulate (Apache-2.0), modified for Mockingbird. See port.json, LICENSE_EMULATE and THIRD_PARTY_NOTICES.md. */
+
+interface Entity {
+    id: number;
+    created_at: string;
+    updated_at: string;
+}
+type InsertInput<T extends Entity> = Omit<T, "id" | "created_at" | "updated_at"> & {
+    id?: number;
+};
+type FilterFn<T> = (item: T) => boolean;
+type SortFn<T> = (a: T, b: T) => number;
+interface QueryOptions<T> {
+    filter?: FilterFn<T>;
+    sort?: SortFn<T>;
+    page?: number;
+    per_page?: number;
+}
+interface PaginatedResult<T> {
+    items: T[];
+    total_count: number;
+    page: number;
+    per_page: number;
+    has_next: boolean;
+    has_prev: boolean;
+}
+/** Provider entities live in the same namespace and history as every native service. */
+declare class Collection<T extends Entity> {
+    readonly store: Store;
+    readonly name: string;
+    readonly fieldNames: string[];
+    private readonly records;
+    constructor(store: Store, name: string, fields?: (keyof T)[]);
+    insert(data: InsertInput<T>): T;
+    get(id: number): T | undefined;
+    findBy(field: keyof T, value: T[keyof T] | string | number): T[];
+    findOneBy(field: keyof T, value: T[keyof T] | string | number): T | undefined;
+    update(id: number, data: Partial<T>): T | undefined;
+    delete(id: number): boolean;
+    all(): T[];
+    count(filter?: FilterFn<T>): number;
+    clear(): void;
+    query(options?: QueryOptions<T>): PaginatedResult<T>;
+}
+declare class Store {
+    readonly sqlite: SqliteClient$2;
+    readonly namespace: string;
+    readonly now: () => number;
+    readonly meta: Collection$1<unknown>;
+    private readonly collections;
+    private readonly data;
+    constructor(sqlite?: SqliteClient$2, namespace?: string, now?: () => number);
+    isoNow(): string;
+    collection<T extends Entity>(name: string, fields?: (keyof T)[]): Collection<T>;
+    getData<V>(key: string): V | undefined;
+    setData<V>(key: string, value: V): void;
+    /** Drop request caches so checkout/reset and namespace selection always read SQLite. */
+    begin(): void;
+    flush(): void;
+    reset(): void;
+}
+
+interface WebhookSubscription {
+    id: number;
+    url: string;
+    events: string[];
+    active: boolean;
+    secret?: string;
+    owner: string;
+    repo?: string;
+}
+interface WebhookDelivery$1 {
+    id: number;
+    hook_id: number;
+    event: string;
+    action?: string;
+    payload: unknown;
+    status_code: number | null;
+    delivered_at: string;
+    duration: number | null;
+    success: boolean;
+}
+interface WebhookHeaderContext {
+    event: string;
+    action?: string;
+    body: string;
+    subscription: Readonly<WebhookSubscription>;
+    deliveryId: number;
+}
+type WebhookHeaderFactory = (context: WebhookHeaderContext) => Record<string, string>;
+declare class WebhookDispatcher {
+    private readonly options;
+    private readonly records;
+    private readonly now;
+    private headerFactory;
+    constructor(options?: {
+        signal?: AbortSignal;
+        neutral?: boolean;
+        store?: Store;
+    });
+    private load;
+    private save;
+    setHeaderFactory(factory: WebhookHeaderFactory): void;
+    register(sub: Omit<WebhookSubscription, "id"> & {
+        id?: number;
+    }): WebhookSubscription;
+    unregister(id: number): boolean;
+    getSubscription(id: number): WebhookSubscription | undefined;
+    getSubscriptions(owner?: string, repo?: string): WebhookSubscription[];
+    updateSubscription(id: number, data: Partial<Pick<WebhookSubscription, "url" | "events" | "active" | "secret">>): WebhookSubscription | undefined;
+    dispatch(event: string, action: string | undefined, payload: unknown, owner: string, repo?: string): Promise<void>;
+    getDeliveries(hookId?: number): WebhookDelivery$1[];
+    clear(): void;
+}
+
+interface AuthUser {
+    login: string;
+    id: number;
+    scopes: string[];
+    installation?: AuthInstallation;
+}
+interface AuthApp {
+    appId: number;
+    slug: string;
+    name: string;
+}
+interface AuthInstallation {
+    installationId: number;
+    appId: number;
+    accountId: number;
+    accountType: "User" | "Organization";
+    permissions: Record<string, string>;
+    repositoryIds: number[];
+    repositorySelection: "all" | "selected";
+}
+type TokenMap = Map<string, AuthUser>;
+type AppEnv = {
+    Variables: {
+        authUser?: AuthUser;
+        authApp?: AuthApp;
+        authToken?: string;
+        authScopes?: string[];
+        docsUrl?: string;
+    };
+};
+interface AuthFallback {
+    login: string;
+    id: number;
+    scopes: string[];
+}
+
+/*! Adapted from vercel-labs/emulate (Apache-2.0), modified for Mockingbird. See port.json, LICENSE_EMULATE and THIRD_PARTY_NOTICES.md. */
+
+interface ServicePlugin {
+    name: string;
+    register(app: Hono<AppEnv>, store: Store, webhooks: WebhookDispatcher, baseUrl: string, tokenMap?: TokenMap): void;
+    seed?(store: Store, baseUrl: string): void;
+}
+
+interface MicrosoftSeedConfig {
+    users?: Array<{
+        email: string;
+        name?: string;
+        given_name?: string;
+        family_name?: string;
+        tenant_id?: string;
+    }>;
+    oauth_clients?: Array<{
+        client_id: string;
+        client_secret: string;
+        name: string;
+        redirect_uris: string[];
+        tenant_id?: string;
+    }>;
+}
+
+type ProviderOptions = APIOptions & {
+    baseUrl?: string;
+    tokens?: Record<string, AuthUser>;
+    fallbackUser?: AuthFallback;
+    publicNamespace?: string;
+    adminPrefix?: string;
+    /**
+     * A seeded stream of `[0, 1)` that ids and tokens are minted from, so a run replays from
+     * its seed. Default: the platform's randomness.
+     */
+    random?: () => number;
+};
+/** Portable vendor API backed by the shared namespace; it owns no separate history or listener. */
+declare class ProviderAPI {
+    readonly plugin: ServicePlugin;
+    readonly options: ProviderOptions;
+    readonly sqlite: SqliteClient$2;
+    readonly namespace: string;
+    readonly store: Store;
+    private activeApp;
+    private activeBaseUrl;
+    private readonly facade;
+    get app(): Hono<AppEnv>;
+    get routeTable(): RouteInfo[];
+    readonly tokenMap: Map<string, AuthUser>;
+    readonly webhooks: WebhookDispatcher;
+    private configured;
+    private tail;
+    constructor(plugin: ServicePlugin, options?: ProviderOptions);
+    private buildApp;
+    private initialize;
+    /** Persist seed configuration before the shared runtime captures its initial checkpoint. */
+    seed(config: unknown, apply: (store: Store, baseUrl: string, config: never) => void): void;
+    configureFixtures(config: unknown, apply: (store: Store, baseUrl: string, config: never) => void): void;
+    fetch(request: Request): Promise<Response>;
+    reset(): Promise<void>;
+}
+
+/**
+ * The slice of OpenAPI 3.1 (and JSON Schema 2020-12) Mockingbird understands.
+ * Unknown keys (including `x-*` extensions) are preserved on every object.
+ */
+type JsonPrimitive$1 = string | number | boolean | null;
+type JsonValue$1 = JsonPrimitive$1 | JsonValue$1[] | {
+    [key: string]: JsonValue$1;
+};
+type ReferenceObject$1 = {
+    $ref: string;
+    description?: string;
+    summary?: string;
+};
+type SchemaType$1 = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+type SchemaObject$1 = {
+    $ref?: string;
+    type?: SchemaType$1 | SchemaType$1[];
+    title?: string;
+    description?: string;
+    format?: string;
+    enum?: JsonValue$1[];
+    const?: JsonValue$1;
+    default?: JsonValue$1;
+    example?: JsonValue$1;
+    examples?: JsonValue$1[];
+    nullable?: boolean;
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    items?: SchemaObject$1;
+    prefixItems?: SchemaObject$1[];
+    minProperties?: number;
+    maxProperties?: number;
+    required?: string[];
+    properties?: Record<string, SchemaObject$1>;
+    additionalProperties?: boolean | SchemaObject$1;
+    propertyNames?: SchemaObject$1;
+    oneOf?: SchemaObject$1[];
+    anyOf?: SchemaObject$1[];
+    allOf?: SchemaObject$1[];
+    not?: SchemaObject$1;
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+    [extension: `x-${string}`]: unknown;
+};
+type ParameterLocation$1 = "path" | "query" | "header" | "cookie";
+type ParameterObject$1 = {
+    name: string;
+    in: ParameterLocation$1;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    style?: string;
+    explode?: boolean;
+    schema?: SchemaObject$1;
+    content?: Record<string, MediaTypeObject$1>;
+    example?: JsonValue$1;
+    [extension: `x-${string}`]: unknown;
+};
+type MediaTypeObject$1 = {
+    schema?: SchemaObject$1;
+    example?: JsonValue$1;
+    examples?: Record<string, unknown>;
+    encoding?: Record<string, unknown>;
+    [extension: `x-${string}`]: unknown;
+};
+type RequestBodyObject$1 = {
+    description?: string;
+    required?: boolean;
+    content: Record<string, MediaTypeObject$1>;
+    [extension: `x-${string}`]: unknown;
+};
+type HeaderObject$1 = {
+    description?: string;
+    required?: boolean;
+    schema?: SchemaObject$1;
+    [extension: `x-${string}`]: unknown;
+};
+type ResponseObject$1 = {
+    description: string;
+    headers?: Record<string, HeaderObject$1 | ReferenceObject$1>;
+    content?: Record<string, MediaTypeObject$1>;
+    [extension: `x-${string}`]: unknown;
+};
+type ResponsesObject$1 = Record<string, ResponseObject$1 | ReferenceObject$1>;
+type SecurityRequirementObject$1 = Record<string, string[]>;
+type OperationObject$1 = {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    parameters?: Array<ParameterObject$1 | ReferenceObject$1>;
+    requestBody?: RequestBodyObject$1 | ReferenceObject$1;
+    responses: ResponsesObject$1;
+    security?: SecurityRequirementObject$1[];
+    [extension: `x-${string}`]: unknown;
+};
+declare const HTTP_METHODS$1: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+type HttpMethod$1 = (typeof HTTP_METHODS$1)[number];
+type PathItemObject$1 = {
+    summary?: string;
+    description?: string;
+    parameters?: Array<ParameterObject$1 | ReferenceObject$1>;
+    [extension: `x-${string}`]: unknown;
+} & Partial<Record<HttpMethod$1, OperationObject$1>>;
+type SecuritySchemeObject$1 = {
+    type: "apiKey" | "http" | "oauth2" | "openIdConnect" | "mutualTLS";
+    description?: string;
+    name?: string;
+    in?: ParameterLocation$1;
+    scheme?: string;
+    bearerFormat?: string;
+    flows?: Record<string, unknown>;
+    openIdConnectUrl?: string;
+    [extension: `x-${string}`]: unknown;
+};
+type ComponentsObject$1 = {
+    schemas?: Record<string, SchemaObject$1>;
+    responses?: Record<string, ResponseObject$1>;
+    parameters?: Record<string, ParameterObject$1>;
+    requestBodies?: Record<string, RequestBodyObject$1>;
+    headers?: Record<string, HeaderObject$1>;
+    securitySchemes?: Record<string, SecuritySchemeObject$1>;
+    [extension: `x-${string}`]: unknown;
+};
+type ServerObject$1 = {
+    url: string;
+    description?: string;
+    variables?: Record<string, unknown>;
+    [extension: `x-${string}`]: unknown;
+};
+type InfoObject$1 = {
+    title: string;
+    version: string;
+    description?: string;
+    [extension: `x-${string}`]: unknown;
+};
+type OpenAPIDocument$1 = {
+    openapi: string;
+    info: InfoObject$1;
+    servers?: ServerObject$1[];
+    paths: Record<string, PathItemObject$1>;
+    components?: ComponentsObject$1;
+    security?: SecurityRequirementObject$1[];
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    [extension: `x-${string}`]: unknown;
+};
+
+declare const document: OpenAPIDocument$1;
+declare const operationIds: readonly ["GET /.well-known/openid-configuration", "GET /:tenant/v2.0/.well-known/openid-configuration", "GET /discovery/v2.0/keys", "GET /oauth2/v2.0/authorize", "GET /oauth2/v2.0/logout", "GET /oidc/userinfo", "GET /v1.0/me", "GET /v1.0/users/:id", "POST /:tenant/oauth2/token", "POST /oauth2/v2.0/authorize/callback", "POST /oauth2/v2.0/revoke", "POST /oauth2/v2.0/token"];
+declare const supportedOperationIds: readonly ["GET /.well-known/openid-configuration", "GET /:tenant/v2.0/.well-known/openid-configuration", "GET /discovery/v2.0/keys", "GET /oauth2/v2.0/authorize", "GET /oauth2/v2.0/logout", "GET /oidc/userinfo", "GET /v1.0/me", "GET /v1.0/users/:id", "POST /:tenant/oauth2/token", "POST /oauth2/v2.0/authorize/callback", "POST /oauth2/v2.0/revoke", "POST /oauth2/v2.0/token"];
+
+/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
+type SqliteValue$1 = null | number | bigint | string | Uint8Array | boolean;
+/** Mutation counters returned by {@link SqliteStatement.run}. */
+type SqliteRunResult$1 = {
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * Prepared statement bound to a {@link SqliteClient}.
+ *
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
+ */
+interface SqliteStatement$1 {
+    run(...params: SqliteValue$1[]): SqliteRunResult$1;
+    all<T = Record<string, unknown>>(...params: SqliteValue$1[]): T[];
+    get<T = Record<string, unknown>>(...params: SqliteValue$1[]): T | undefined;
+}
+/**
+ * Sync SQLite client port owned by Mockingbird.
+ *
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
+ * `bun:sqlite` instances all work when they expose this surface.
+ */
+interface SqliteClient$1 {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement$1;
+    transaction<T>(fn: () => T): T;
+}
+
+type MountedAPI = FetchAPI & {
+    readonly prefix: string;
+    GET: FetchHandler;
+    POST: FetchHandler;
+    PUT: FetchHandler;
+    PATCH: FetchHandler;
+    DELETE: FetchHandler;
+    HEAD: FetchHandler;
+    OPTIONS: FetchHandler;
+};
+
+/** A stable identifier for a point in a {@link Timeline}. */
+type CheckpointId = string;
+/** An immutable node in a timeline's checkpoint DAG. */
+type Checkpoint<T> = Readonly<{
+    id: CheckpointId;
+    branch: string;
+    parent: CheckpointId | null;
+    /** Logical time supplied by the timeline's injected clock. */
+    at: number;
+    value: T;
+}>;
+type TimelineOptions = {
+    /** Logical clock used to stamp checkpoints. Defaults to a deterministic counter. */
+    now?: () => number;
+    /** Maximum retained checkpoints. Branch heads are never collected. Default 1,000. */
+    maxCheckpoints?: number;
+    /** Customize deterministic checkpoint IDs. */
+    id?: (sequence: number) => CheckpointId;
+};
+type CommitOptions = {
+    branch?: string;
+    /** Parent checkpoint. Defaults to the selected branch's current head. */
+    parent?: CheckpointId | null;
+};
+type ForkOptions = {
+    /** Checkpoint to fork from. Defaults to the main branch's head. */
+    from?: CheckpointId;
+};
+/**
+ * Small, storage-agnostic checkpoint DAG shared by service runtimes. Its values may be immutable
+ * records, namespace images, or copy-on-write SQL engine snapshots.
+ *
+ * Values are retained by reference. Engines can therefore use persistent/COW snapshots while
+ * simpler services can use immutable values. IDs and GC order are deterministic, and all IO
+ * (the logical clock) is injected.
+ */
+declare class Timeline<T> {
+    readonly maxCheckpoints: number;
+    private readonly now;
+    private readonly makeId;
+    private readonly nodes;
+    private readonly heads;
+    /** Unreferenced nodes in the exact order they became collectible. */
+    private readonly evictable;
+    /** Branch heads plus explicit retainers. Absent means zero. */
+    private readonly references;
+    private readonly explicitPins;
+    private sequence;
+    constructor(options?: TimelineOptions);
+    /** Capture a new immutable value and move `branch` to it. */
+    commit(value: T, options?: CommitOptions): Checkpoint<T>;
+    /** Create a branch pointer without copying its checkpoint value. */
+    fork(branch: string, options?: ForkOptions): Checkpoint<T> | undefined;
+    /** Move a branch pointer to an existing checkpoint. */
+    checkout(branch: string, id: CheckpointId): Checkpoint<T>;
+    get(id: CheckpointId): Checkpoint<T>;
+    head(branch?: string): Checkpoint<T> | undefined;
+    hasBranch(branch: string): boolean;
+    branches(): Readonly<Record<string, CheckpointId>>;
+    checkpoints(): readonly Checkpoint<T>[];
+    /** Number of retained checkpoints without allocating an array. */
+    get size(): number;
+    /** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
+    retain(id: CheckpointId): Checkpoint<T>;
+    /** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
+    release(id: CheckpointId): boolean;
+    deleteBranch(branch: string): boolean;
+    /**
+     * Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
+     * commits never scan pinned nodes or the retained history. Parents are metadata rather than a
+     * storage dependency, so a retained node remains usable after pruning.
+     */
+    gc(max?: number): CheckpointId[];
+    private collect;
+    private moveHead;
+    private addReference;
+    private removeReference;
+    private assertBranch;
+}
+
+/**
+ * Anything that can answer a Fetch `Request` with a `Response`.
+ *
+ * Every Mockingbird service implements this, and every runtime adapter consumes it.
+ * It is the only contract shared across the whole graph.
+ */
+interface FetchAPI {
+    fetch(request: Request): Promise<Response>;
+}
+/** A bare function form of {@link FetchAPI}, compatible with `Bun.serve`, workerd, and Deno. */
+type FetchHandler = (request: Request) => Promise<Response>;
+
+/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
+type SqliteValue = null | number | bigint | string | Uint8Array | boolean;
+/** Mutation counters returned by {@link SqliteStatement.run}. */
+type SqliteRunResult = {
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * Prepared statement bound to a {@link SqliteClient}.
+ *
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
+ */
+interface SqliteStatement {
+    run(...params: SqliteValue[]): SqliteRunResult;
+    all<T = Record<string, unknown>>(...params: SqliteValue[]): T[];
+    get<T = Record<string, unknown>>(...params: SqliteValue[]): T | undefined;
+}
+/**
+ * Sync SQLite client port owned by Mockingbird.
+ *
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
+ * `bun:sqlite` instances all work when they expose this surface.
+ */
+interface SqliteClient {
+    exec(sql: string): void;
+    prepare(sql: string): SqliteStatement;
+    transaction<T>(fn: () => T): T;
+}
+
+/**
+ * The slice of OpenAPI 3.1 (and JSON Schema 2020-12) Mockingbird understands.
+ * Unknown keys (including `x-*` extensions) are preserved on every object.
+ */
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type ReferenceObject = {
+    $ref: string;
+    description?: string;
+    summary?: string;
+};
+type SchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+type SchemaObject = {
+    $ref?: string;
+    type?: SchemaType | SchemaType[];
+    title?: string;
+    description?: string;
+    format?: string;
+    enum?: JsonValue[];
+    const?: JsonValue;
+    default?: JsonValue;
+    example?: JsonValue;
+    examples?: JsonValue[];
+    nullable?: boolean;
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    items?: SchemaObject;
+    prefixItems?: SchemaObject[];
+    minProperties?: number;
+    maxProperties?: number;
+    required?: string[];
+    properties?: Record<string, SchemaObject>;
+    additionalProperties?: boolean | SchemaObject;
+    propertyNames?: SchemaObject;
+    oneOf?: SchemaObject[];
+    anyOf?: SchemaObject[];
+    allOf?: SchemaObject[];
+    not?: SchemaObject;
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+    [extension: `x-${string}`]: unknown;
+};
+type ParameterLocation = "path" | "query" | "header" | "cookie";
+type ParameterObject = {
+    name: string;
+    in: ParameterLocation;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    style?: string;
+    explode?: boolean;
+    schema?: SchemaObject;
+    content?: Record<string, MediaTypeObject>;
+    example?: JsonValue;
+    [extension: `x-${string}`]: unknown;
+};
+type MediaTypeObject = {
+    schema?: SchemaObject;
+    example?: JsonValue;
+    examples?: Record<string, unknown>;
+    encoding?: Record<string, unknown>;
+    [extension: `x-${string}`]: unknown;
+};
+type RequestBodyObject = {
+    description?: string;
+    required?: boolean;
+    content: Record<string, MediaTypeObject>;
+    [extension: `x-${string}`]: unknown;
+};
+type HeaderObject = {
+    description?: string;
+    required?: boolean;
+    schema?: SchemaObject;
+    [extension: `x-${string}`]: unknown;
+};
+type ResponseObject = {
+    description: string;
+    headers?: Record<string, HeaderObject | ReferenceObject>;
+    content?: Record<string, MediaTypeObject>;
+    [extension: `x-${string}`]: unknown;
+};
+type ResponsesObject = Record<string, ResponseObject | ReferenceObject>;
+type SecurityRequirementObject = Record<string, string[]>;
+type OperationObject = {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    parameters?: Array<ParameterObject | ReferenceObject>;
+    requestBody?: RequestBodyObject | ReferenceObject;
+    responses: ResponsesObject;
+    security?: SecurityRequirementObject[];
+    [extension: `x-${string}`]: unknown;
+};
+declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+type PathItemObject = {
+    summary?: string;
+    description?: string;
+    parameters?: Array<ParameterObject | ReferenceObject>;
+    [extension: `x-${string}`]: unknown;
+} & Partial<Record<HttpMethod, OperationObject>>;
+type SecuritySchemeObject = {
+    type: "apiKey" | "http" | "oauth2" | "openIdConnect" | "mutualTLS";
+    description?: string;
+    name?: string;
+    in?: ParameterLocation;
+    scheme?: string;
+    bearerFormat?: string;
+    flows?: Record<string, unknown>;
+    openIdConnectUrl?: string;
+    [extension: `x-${string}`]: unknown;
+};
+type ComponentsObject = {
+    schemas?: Record<string, SchemaObject>;
+    responses?: Record<string, ResponseObject>;
+    parameters?: Record<string, ParameterObject>;
+    requestBodies?: Record<string, RequestBodyObject>;
+    headers?: Record<string, HeaderObject>;
+    securitySchemes?: Record<string, SecuritySchemeObject>;
+    [extension: `x-${string}`]: unknown;
+};
+type ServerObject = {
+    url: string;
+    description?: string;
+    variables?: Record<string, unknown>;
+    [extension: `x-${string}`]: unknown;
+};
+type InfoObject = {
+    title: string;
+    version: string;
+    description?: string;
+    [extension: `x-${string}`]: unknown;
+};
+type OpenAPIDocument = {
+    openapi: string;
+    info: InfoObject;
+    servers?: ServerObject[];
+    paths: Record<string, PathItemObject>;
+    components?: ComponentsObject;
+    security?: SecurityRequirementObject[];
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    [extension: `x-${string}`]: unknown;
+};
+
+/**
+ * The single source of time for a service.
+ *
+ * Every timestamp a mock writes reads from here, so a suite moves time instead of
+ * sleeping: appointment windows, result delays and expiries become reachable in
+ * milliseconds. A frozen clock also makes timestamps reproducible from a seed.
+ */
+type ClockState = {
+    /** Current epoch milliseconds. */
+    now: number;
+    /** True while time does not advance on its own. */
+    frozen: boolean;
+    /** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
+    offsetMs: number;
+};
+type Clock = {
+    now(): number;
+    /** Pin the clock to an exact instant, keeping it frozen if it already was. */
+    set(epochMs: number): void;
+    /** Move the clock forward, or back with a negative delta. */
+    advance(deltaMs: number): void;
+    /** Stop time at the current instant. */
+    freeze(): void;
+    /** Resume from the current instant. */
+    unfreeze(): void;
+    /** Drop back to the underlying source, live. */
+    reset(): void;
+    state(): ClockState;
+};
+
+/**
+ * Seeded pseudo-random numbers, so anything a mock invents — ids, jitter, which
+ * request a percentage fault hits — is reproducible from a seed.
+ *
+ * mulberry32: small, fast, and stable across runtimes, which matters more here
+ * than statistical quality.
+ */
+type Rng = {
+    /** Next value in `[0, 1)`. */
+    next(): number;
+    /** Next integer in `[min, max]`. */
+    int(min: number, max: number): number;
+    /** Restart the stream from its seed. */
+    reset(): void;
+    /** Serializable engine state used by deterministic checkpoints. */
+    state(): number;
+    /** Restore a state previously returned by {@link state}. */
+    setState(state: number): void;
+    /** Restart the stream from a new seed. `reset` then returns to this seed. */
+    reseed(seed: number | string): void;
+    /** The seed the stream currently starts from. */
+    readonly seed: number;
+};
+
+/**
+ * A deliberate failure injected in front of an operation.
+ *
+ * This is how a suite reaches the vendor's failure modes without the vendor: the
+ * quota error that only appears when a shared sandbox is full, the 429 that only
+ * appears under load, the 5xx that proves a retry path works.
+ *
+ * A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
+ * it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
+ * and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
+ */
+type FaultRule = {
+    /** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
+    id: string;
+    /** Fault only this operation. Omit to match every operation. */
+    operationId?: string;
+    /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
+    method?: string;
+    /** Fault only this exact path. */
+    path?: string;
+    /** Fault only paths starting with this prefix. Omit to match every path. */
+    pathPrefix?: string;
+    /** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
+    pathPattern?: string;
+    /** Fault only requests carrying these headers. `"*"` matches any value. */
+    requestHeaders?: Record<string, string>;
+    /** Fault only requests carrying these query parameters. `"*"` matches any value. */
+    query?: Record<string, string>;
+    /**
+     * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
+     * an in-process caller usually wants, and what a parallel worker usually does not:
+     * rules added through `POST /__admin/faults` default to the calling namespace.
+     */
+    namespace?: string;
+    /** Let this many matching requests through first. */
+    after?: number;
+    /** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
+    every?: number;
+    /** Retire the rule after this many faults. Omit to keep it until removed. */
+    count?: number;
+    /** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
+    rate?: number;
+    /**
+     * Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
+     * clock when the rule was added. Listed as epoch ms.
+     */
+    from?: Instant | Duration;
+    /** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
+    until?: Instant | Duration;
+    /**
+     * Status of the injected response. Omit for a rule that only delays, times out, drops,
+     * truncates, or switches on an `effect`: the request then still reaches the service.
+     */
+    status?: number;
+    /** Response body, serialized as JSON. A string is sent as-is. */
+    body?: unknown;
+    /** Response headers. */
+    headers?: Record<string, string>;
+    /** Hold the response back this long. Listed as `delayMs`. */
+    delay?: Duration;
+    /** `delay`, in milliseconds. */
+    delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: number;
+    /** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
+    jitter?: Duration;
+    jitterMs?: number;
+    /**
+     * Never answer: hold the request this long, then drop the connection. Listed as
+     * `timeoutMs`. With virtual time the wait is spent on the mock clock.
+     */
+    timeout?: Duration;
+    timeoutMs?: number;
+    /**
+     * Drop the connection instead of answering: an in-process `fetch` rejects with a
+     * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
+     */
+    drop?: boolean;
+    /**
+     * Cut the response body off after this many bytes: the status and headers arrive, then
+     * the connection dies mid-body.
+     */
+    truncate?: number;
+    /**
+     * A named service behaviour to switch on for the matching request instead of (or
+     * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
+     * read it with `faultEffects(request)`.
+     */
+    effect?: string;
+    /** Parameters for `effect`. */
+    params?: Record<string, unknown>;
+    /** The preset this rule was expanded from, if any. */
+    fromPreset?: string;
+};
+/** A fault that fired for one request. */
+type FaultHit = {
+    id: string;
+    /** The injected response; absent when the rule only delays, drops, or sets an effect. */
+    response?: Response;
+    drop?: boolean;
+    /** Set with `drop` when the rule held the request for its `timeout` first. */
+    timeout?: boolean;
+    /** Bytes of response body to let through before the connection dies. */
+    truncate?: number;
+    effect?: {
+        name: string;
+        params: Record<string, unknown>;
+    };
+};
+/**
+ * A named, documented fault a suite switches on by name
+ * (`POST /__admin/faults {"preset": "rate_limited"}`): one or more rules, and optionally a
+ * webhook delivery fault.
+ */
+type FaultPreset = {
+    description: string;
+    rules?: Omit<FaultRule, "id">[];
+    webhook?: {
+        mode: "duplicate" | "reorder" | "drop";
+        count?: number;
+    };
+};
+/** What a request looks like to the fault matcher. */
+type FaultCandidate = {
+    operationId: string | undefined;
+    method: string;
+    path: string;
+    namespace: string;
+    /** Request headers and query, for rules that match on them. */
+    headers?: Headers;
+    query?: URLSearchParams;
+    /** The namespace clock, for `from` / `until`. Rules with a window are skipped without it. */
+    now?: number;
+    /** How to spend a delay for this request. Default: the registry's own sleep. */
+    wait?: (ms: number) => Promise<void>;
+};
+/** A stored rule and how often it was consulted. */
+type FaultListing = FaultRule & {
+    /** Faults left before the rule retires. `null` when it has no `count`. */
+    remaining: number | null;
+    /** Times the rule faulted a request. */
+    hits: number;
+    /** Requests that matched the rule, faulted or not. */
+    seen: number;
+};
+/** A namespace's own rules, with their counters, in the order they are tried. */
+type FaultSnapshot = {
+    /**
+     * `position` is how many `"*"` rules are tried before the rule, which is what its place
+     * in the order means to a request and holds in any process.
+     */
+    rules: (FaultListing & {
+        position?: number;
+    })[];
+    /** How many `fault_<n>` ids the namespace has handed out. */
+    nextId?: number;
+};
+type FaultRegistry = {
+    snapshot(namespace: string): FaultSnapshot;
+    /** Add a rule, or replace the rule with the same id in the same namespace. */
+    add(rule: FaultRule): FaultRule;
+    /** The next unused `fault_<n>` id in `namespace`. */
+    nextId(namespace: string): string;
+    /** Every rule, or the rules a namespace's requests can hit: its own and the global ones. */
+    list(namespace?: string): FaultListing[];
+    get(id: string, namespace?: string): FaultListing | undefined;
+    /** Remove a rule by id: from `namespace` (its own, then a global one), or wherever it is. */
+    remove(id: string, namespace?: string): boolean;
+    /** Remove every rule, or one namespace's own rules. */
+    clear(namespace?: string): void;
+    /** Replace a namespace's own rules with a snapshot's, wherever the snapshot was taken. */
+    restore(namespace: string, state: FaultSnapshot): void;
+    /**
+     * Every fault this request should get, in rule order, stopping at the first that answers
+     * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
+     * each matching rule's remaining uses.
+     */
+    take(candidate: FaultCandidate): Promise<FaultHit[]>;
+    /**
+     * Fire these rules at one request without storing them: no matching, no schedule, in order,
+     * stopping at the first that answers or drops. Jitter draws from the namespace's stream.
+     */
+    fire(rules: readonly FaultRule[], candidate: FaultCandidate): Promise<FaultHit[]>;
+};
+
+/**
+ * The admin controls every mock shares, as one document.
+ *
+ * The same shape is accepted in three places, and means the same thing in each:
+ *
+ * - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
+ *   `MOCKINGBIRD_ADMIN_CONTROLS`
+ * - over HTTP: `PUT /__admin/controls`
+ * - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
+ *
+ * Every control is deterministic: given the same seed, clock and requests, a mock answers
+ * the same bytes. Nothing here reads the wall clock or `Math.random`.
+ */
+/** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
+type Duration = number | string;
+/** Epoch milliseconds, or an ISO-8601 string. */
+type Instant = number | string;
+type ClockControls = {
+    /** Move the clock to this instant. */
+    now?: Instant;
+    /** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
+    frozen?: boolean;
+    /**
+     * Step the clock forward by this much before every vendor request. With a frozen clock
+     * each request still gets its own, reproducible timestamp.
+     */
+    autoAdvance?: Duration;
+};
+/** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
+type LatencyRuleInput = {
+    delay?: Duration;
+    jitter?: Duration;
+};
+type LatencyControls = LatencyRuleInput & {
+    /** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
+    operations?: Record<string, Duration | LatencyRuleInput>;
+};
+/** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
+type FaultInput = (Omit<FaultRule, "id"> & {
+    id?: string;
+}) | ({
+    preset: string;
+} & Partial<FaultRule>);
+/** Identifies a {@link SnapshotDocument}. */
+declare const SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
+/**
+ * A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
+ * `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
+ * `records` are required, so a hand-written seed file is a valid snapshot.
+ */
+type SnapshotDocument = {
+    format: typeof SNAPSHOT_FORMAT;
+    /** The service that wrote it. A snapshot is rejected by any other service. */
+    service?: string;
+    /**
+     * Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
+     * the stored text of a row that is not a plain record, and replaces `value` when present.
+     */
+    records: {
+        collection: string;
+        id: string;
+        seq?: number;
+        value?: unknown;
+        raw?: string;
+    }[];
+    /** Id counters, so the next generated id continues where the snapshot left off. */
+    sequences?: {
+        name: string;
+        kind: string;
+        value: number;
+    }[];
+    clock?: {
+        now: number;
+        frozen: boolean;
+        autoAdvanceMs?: number;
+    };
+    seed?: number | string;
+    /** Positions of the seeded random streams. */
+    rng?: {
+        state: number;
+        faults?: number;
+        latency?: number;
+    };
+    faults?: unknown;
+    latency?: unknown;
+    virtualTime?: boolean;
+};
+/** Controls for one namespace. */
+type NamespaceControls = {
+    /** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
+    seed?: number | string;
+    clock?: ClockControls;
+    /**
+     * Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
+     * wall clock: the request returns at once, the clock has moved, and the journal records
+     * the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
+     */
+    virtualTime?: boolean;
+    /** Baseline response time for every vendor request. A bare duration is its `delay`. */
+    latency?: Duration | LatencyControls;
+    faults?: readonly FaultInput[];
+    /** Start from this state instead of the service's own seed data. */
+    snapshot?: SnapshotDocument;
+};
+/** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
+type MockControls = NamespaceControls & {
+    /** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
+    credentials?: Record<string, string>;
+    /** Overrides for named namespaces. A key given here replaces the shared value. */
+    namespaces?: Record<string, NamespaceControls>;
+};
+/** A latency rule in milliseconds. */
+type LatencyRule = {
+    delayMs: number;
+    jitterMs: number;
+};
+/** Baseline latency for a namespace, normalized. */
+type LatencyState = LatencyRule & {
+    operations: Record<string, LatencyRule>;
+};
+/** What {@link controlHeaders} turns into request headers. */
+type ControlHeaderInput = {
+    namespace?: string;
+    adminKey?: string;
+    branch?: string;
+    at?: string;
+    reset?: boolean;
+    restore?: string;
+    seed?: number | string;
+    time?: Instant | Date;
+    advance?: Duration;
+    virtualTime?: boolean;
+    delay?: Duration;
+    timeout?: Duration;
+    /** A status, `"drop"`, a preset name, or a fault rule. */
+    fault?: number | string | Record<string, unknown>;
+    snapshot?: string;
+};
+
+/**
+ * One problem with a request body, at a dotted path (`patient.address.city`, `items.0.sku`).
+ * `kind` is `media_type` when the body is present but its media type is not one the operation
+ * accepts (a `415` on most vendors), `syntax` when it could not be decoded, `required` when
+ * the operation needs a body and none arrived, and `schema` for a contract violation.
+ */
+type BodyIssue = {
+    path: string;
+    message: string;
+    kind?: "media_type" | "syntax" | "required" | "schema";
+};
+
+/**
+ * What the mock received from a request it rejected, so a 4xx can be attributed after the
+ * fact (an empty body, a missing `content-type`, a schema violation) without logging the body.
+ */
+type RejectedRequest = {
+    /** The raw `content-type` header, or `null` when the request sent none. */
+    contentType: string | null;
+    /** Bytes of body received from `content-length` (`0` for none), or `null` when the client sent no length (a streamed / chunked body). */
+    bodyBytes: number | null;
+    /** The raw `transfer-encoding` header (`chunked`), or `null`. */
+    transferEncoding: string | null;
+};
+/** One handled request, as the structured log sees it. */
+type RequestLog = {
+    service: string;
+    namespace: string;
+    operationId: string | undefined;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    /** True when the path matched no operation in the contract. */
+    unmatched: boolean;
+    /** Set when a fault rule produced the response. */
+    faultId?: string;
+    /** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
+    delayMs?: number;
+    /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
+    ids?: Record<string, string>;
+    /** Set when the service created a resource the request referred to but that did not exist. */
+    adopted?: boolean;
+    /** Explicit durable acceptance, independent of response delivery. */
+    accepted?: boolean;
+    /** Checkpoint captured at explicit acceptance. */
+    checkpoint?: string;
+    /** Set on a rejection (status ≥ 400) the mock produced itself, never on a scripted fault. */
+    request?: RejectedRequest;
+    /** The validation issues behind a rejection, when the service found any. */
+    issues?: BodyIssue[];
+};
+type MetricsReport = {
+    requests: number;
+    /** Counts keyed `<operationId> <status>`. */
+    byOperation: Record<string, number>;
+    /**
+     * Paths that matched no operation, most frequent first.
+     *
+     * This is the early-warning signal: a consumer calling something the mock does
+     * not implement shows up here as a count, before it fails a suite as a 404.
+     */
+    unmatched: {
+        method: string;
+        path: string;
+        count: number;
+    }[];
+    faults: number;
+    totalDurationMs: number;
+};
+type Metrics = {
+    record(entry: RequestLog): void;
+    report(namespace?: string): MetricsReport;
+    reset(namespace?: string): void;
+};
+
+/** One journal entry: a request log stamped with when (on the mock clock) it was handled. */
+type JournalEntry = RequestLog & {
+    at: string;
+};
+type JournalQuery = {
+    /** Only this namespace. Omit for every namespace, oldest first across all of them. */
+    namespace?: string;
+    operationId?: string;
+    /** Only this HTTP method, case-insensitive. */
+    method?: string;
+    /** Only this exact path. */
+    path?: string;
+    /** Only requests this fault rule answered or shaped. */
+    faultId?: string;
+    status?: number;
+    /** Only entries at or after this instant (epoch ms). */
+    since?: number;
+    /** At most this many, the most recent kept. */
+    limit?: number;
+};
+type Journal = {
+    readonly size: number;
+    record(entry: JournalEntry): void;
+    list(query?: JournalQuery): JournalEntry[];
+    /** Forget one namespace's entries, or every namespace's. */
+    clear(namespace?: string): void;
+};
+
+/**
+ * Baseline response time, per namespace: how long every vendor request takes before any
+ * fault is considered. Jitter draws from a stream the caller owns, one per namespace and
+ * separate from the fault stream, so adding latency never shifts which requests a `rate`
+ * fault hits.
+ */
+type LatencyRegistry = {
+    get(namespace: string): LatencyState;
+    set(namespace: string, state: LatencyState): LatencyState;
+    /** Remove one namespace's latency, or every namespace's. */
+    clear(namespace?: string): void;
+    /** Milliseconds this request waits. Draws jitter, so call it once per request. */
+    take(namespace: string, operationId: string | undefined): number;
+};
+
+/** Clock state as the admin API reports it. */
+type ControlClock = ClockState & {
+    /** `now`, as ISO-8601. */
+    iso: string;
+    /** Milliseconds the clock steps before every vendor request. */
+    autoAdvanceMs: number;
+};
+/** One namespace's controls: the body of `GET /__admin/controls`. */
+type ControlState = {
+    namespace: string;
+    seed: number | string;
+    clock: ControlClock;
+    virtualTime: boolean;
+    latency: LatencyState;
+    faults: FaultListing[];
+};
+
+type AdminRequest = {
+    request: Request;
+    url: URL;
+    /** `:param` segments of the matched route. */
+    params: Record<string, string>;
+    /** Namespace the request targets: `?namespace=`, then the header, then the default. */
+    namespace: string;
+    /** Parsed JSON body, or `undefined` when there is none. */
+    body: unknown;
+};
+type AdminRoute = (request: AdminRequest) => Response | Promise<Response>;
+/**
+ * Service-specific admin routes, keyed `METHOD /path` relative to `/__admin`, with
+ * `:param` segments — e.g. `"POST /orders/:id/transition"`.
+ */
+type AdminRoutes = Record<string, AdminRoute>;
+/** What `GET /__admin/snapshots` lists for each snapshot. */
+type SnapshotInfo = {
+    id: string;
+    namespace: string;
+    /** Stored rows in the snapshot. */
+    records: number;
+    /** The namespace clock when it was taken, epoch ms. */
+    at: number;
+    /** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
+    portable: boolean;
+};
+
+/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
+type CredentialRegistry = {
+    set(credential: string, namespace: string): void;
+    get(credential: string): string | undefined;
+    remove(credential: string): boolean;
+    clear(): void;
+    entries(): {
+        credential: string;
+        namespace: string;
+    }[];
+};
+
+/**
+ * A point-in-time copy of everything a service namespace holds.
+ *
+ * All service state lives in the two core tables keyed by namespace, so a snapshot
+ * is generic: any service gets per-test rollback without knowing its own schema.
+ * Restoring is much cheaper than rebuilding a namespace from a corpus.
+ */
+type NamespaceSnapshot = {
+    namespace: string;
+    records: {
+        collection: string;
+        id: string;
+        seq: number;
+        value: string;
+    }[];
+    sequences: {
+        name: string;
+        kind: string;
+        value: number;
+    }[];
+};
+
+declare const STATE_FIELD_KINDS: readonly ["string", "number", "boolean", "null", "object", "array", "unknown"];
+type StateFieldKind = (typeof STATE_FIELD_KINDS)[number];
+/** JSON-safe annotations a bespoke admin UI may read. The default UI shows them as text. */
+type StateMeta = Readonly<Record<string, string | number | boolean | null>>;
+type StateField = {
+    name: string;
+    kind: StateFieldKind;
+    optional: boolean;
+    description?: string;
+    /** One level of nested object fields. */
+    fields?: StateField[];
+    meta?: StateMeta;
+};
+/**
+ * What a service knows about a collection before any row exists.
+ * Stored rows still appear, including fields this declaration does not mention.
+ */
+type StateDeclaration = {
+    name: string;
+    label?: string;
+    description?: string;
+    fields?: readonly StateField[];
+    meta?: StateMeta;
+};
+type StateCollectionView = {
+    name: string;
+    label: string;
+    description?: string;
+    count: number;
+    /** `mixed` when a declaration and stored rows both contribute fields. */
+    source: "declared" | "inferred" | "mixed";
+    fields: StateField[];
+    meta?: StateMeta;
+};
+/** The shape of one namespace, for an admin UI that has never seen the service before. */
+type StateView = {
+    namespace: string;
+    storageNamespace: string;
+    collections: StateCollectionView[];
+};
+
+/**
+ * A contribution the admin shell mounts beside the shared views.
+ * `panel` is author-owned markup. `sql` turns on the built-in table explorer
+ * and query runner, which call `GET /sql/tables` and `POST /sql/query`.
+ * `route` presents an admin action with the shell's prebuilt form and response view.
+ */
+type AdminExtension = {
+    kind: "route";
+    id: string;
+    title: string;
+    description?: string;
+    /** An existing admin route, including its method and any path parameters. */
+    route: string;
+    /** Initial JSON body shown in the request form. */
+    body?: unknown;
+} | {
+    kind: "panel";
+    id: string;
+    title: string;
+    description?: string;
+    html: string;
+    script?: string;
+} | {
+    kind: "sql";
+    /** DOM id suffix. Default `sql`. */
+    id?: string;
+    title?: string;
+    description?: string;
+};
+/** A panel the default admin shell mounts after the shared views. */
+type AdminPanel = {
+    /** DOM id suffix. Lowercase letters, digits, and hyphens. */
+    id: string;
+    title: string;
+    description?: string;
+    /** Markup placed inside the panel body. The service author owns it. */
+    html: string;
+    /**
+     * Function body called as `(root, api) => void` once the shell has loaded.
+     * `root` is the panel body. `api` is `{ get, send, namespace }` against `/__admin`.
+     */
+    script?: string;
+};
+/**
+ * How a service customizes the admin UI without leaving the shared shell.
+ * `panels` add views. `render` replaces the document and can call `defaultHtml()`
+ * to wrap the shared shell instead of discarding it.
+ */
+type AdminUi = {
+    panels?: readonly AdminPanel[];
+    /** First-class shell contributions. `sql` mounts the shared database explorer. */
+    extensions?: readonly AdminExtension[];
+    render?: (input: {
+        service: string;
+        defaultHtml: () => string;
+    }) => string;
+};
+
+type WebhookEndpoint = {
+    /** Stable id; generated when omitted. */
+    id?: string;
+    url: string;
+    secret?: string;
+    /** Event types to deliver; omit or include `"*"` for every type. */
+    events?: string[];
+    /** Deliver only messages whose tags include all of these (e.g. `{ account: "mso" }`). */
+    tags?: Record<string, string>;
+    /** The public URL the receiver verifies signatures against (Twilio), when it differs. */
+    signUrl?: string;
+    headers?: Record<string, string>;
+};
+type WebhookMessage = {
+    id: string;
+    namespace: string;
+    type: string;
+    body: string;
+    contentType: string;
+    tags: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Wall-clock ISO-8601 time of publication. */
+    publishedAt: string;
+};
+type WebhookAttempt = {
+    attempt: number;
+    at: string;
+    status: number | null;
+    error: string | null;
+    durationMs: number;
+    /** Exact receiver response body, when one was returned. */
+    responseBody?: string | null;
+};
+type WebhookDelivery = {
+    id: string;
+    messageId: string;
+    namespace: string;
+    type: string;
+    endpointId: string;
+    url: string;
+    state: "pending" | "delivered" | "failed" | "dropped";
+    attempts: WebhookAttempt[];
+};
+/** A delivery-level fault: what happens to the next `count` messages in a namespace. */
+type WebhookFault = {
+    mode: "duplicate" | "reorder" | "drop";
+    /** Messages affected; default 1. */
+    count?: number;
+};
+type PublishInput = {
+    namespace: string;
+    type: string;
+    /** Exact body; objects are JSON-encoded. */
+    body: string | Record<string, unknown> | unknown[];
+    /** Default `application/json`, or form-encoded when `form` is given. */
+    contentType?: string;
+    /** Form parameters, when the vendor posts `application/x-www-form-urlencoded`. */
+    form?: Record<string, string>;
+    tags?: Record<string, string>;
+    /** Message-specific delivery headers, captured as part of durable message state. */
+    headers?: Record<string, string>;
+    /** Message id; generated when omitted. */
+    id?: string;
+};
+type WebhookHub = {
+    pending(namespace: string): number;
+    snapshot(namespace: string): unknown;
+    restore(namespace: string, snapshot: unknown): void;
+    publish(input: PublishInput): WebhookMessage;
+    /** Replace a namespace's own endpoints (`PUT /__admin/webhook-endpoints`). */
+    setEndpoints(namespace: string, endpoints: WebhookEndpoint[]): WebhookEndpoint[];
+    /** The endpoints a namespace delivers to: its own, plus the global ones. */
+    endpoints(namespace: string): WebhookEndpoint[];
+    messages(namespace?: string): WebhookMessage[];
+    deliveries(namespace?: string): WebhookDelivery[];
+    replay(deliveryId: string): Promise<WebhookDelivery | undefined>;
+    /** Run every pending retry (and release held reordered messages) now, and every retry those attempts schedule, until nothing is pending. */
+    flush(): Promise<void>;
+    /** Resolve once nothing is in flight. */
+    idle(): Promise<void>;
+    fault(namespace: string, fault: WebhookFault): void;
+    clear(namespace?: string): void;
+};
+
+/** What the runtime needs from a service: a Fetch handler it can reset. */
+type ServiceInstance = FetchAPI & {
+    reset(): Promise<void>;
+};
+/** Everything an instance shares with the runtime that owns it. */
+type InstanceContext = {
+    /** Storage namespace for this instance's records. */
+    namespace: string;
+    /** The public namespace name a request selects it by. */
+    adminPrefix: string;
+    publicNamespace: string;
+    sqlite: SqliteClient;
+    clock: Clock;
+    rng: Rng;
+};
+type RuntimeOptions<T extends ServiceInstance> = {
+    /** Service name, e.g. `"junction"`. Also the default namespace's storage key. */
+    name: string;
+    /** Build the instance backing one namespace. Called once per namespace, on first use. */
+    create: (context: InstanceContext) => T;
+    /** The vendor contract, used to name each request's operation in logs, metrics and faults. */
+    document?: OpenAPIDocument;
+    /** Shared by every namespace. Defaults to a fresh `@crvouga/mockingbird-service-sqlite`. */
+    sqlite?: SqliteClient;
+    /** Defaults to a live clock over `Date.now`. */
+    clock?: Clock;
+    /** Seeds every random choice the runtime makes (fault rates, jitter). Default `0`. */
+    seed?: number | string;
+    /**
+     * Admin controls to boot with: clock, latency, faults, a starting snapshot, credential
+     * mappings and per-namespace overrides. `reset` returns a namespace to exactly this.
+     */
+    adminControls?: MockControls;
+    /** Extra `GET /__admin/health` fields, such as the loaded corpus version. */
+    describe?: () => Record<string, unknown>;
+    /** Service-specific admin routes, given the runtime so they can reach any namespace. */
+    admin?: (runtime: ServiceRuntime<T>) => AdminRoutes;
+    /** Reserved tree for every internal HTTP endpoint, UI and namespace carrier. Default /__admin. */
+    adminPrefix?: string;
+    /**
+     * A namespace's clock was moved — by `/__admin/clock`, a header, a restore, a reset, or a
+     * wait spent in virtual time. Run whatever the service schedules by that clock, so what
+     * came due is seen at once and not on the next request. Moving the base clock in process
+     * (`runtime.clock`) is the caller's own doing and is not reported here.
+     */
+    onClockChange?: (namespace: string) => void;
+    /** Invalidate transient handles before replacing an existing instance's stored state. */
+    beforeRestore?: (instance: T) => void;
+    /** Require this value in `x-mockingbird-admin-key` on admin data routes. */
+    adminKey?: string;
+    /** Structured request log sink, called once per request. */
+    onLog?: (entry: RequestLog) => void;
+    /** Requests each namespace's journal keeps (`GET /__admin/requests`). Default 1000; 0 turns it off. */
+    journalSize?: number;
+    /** Reported in the `x-mockingbird` header. Default: the bundled package's version. */
+    version?: string;
+    /**
+     * The vendor credential a request carries (API key, token, account SID, AWS access key
+     * id), for SDKs that cannot send `x-mockingbird-namespace`: a suite maps credentials to
+     * namespaces with `PUT /__admin/credentials`. See `bearerToken`, `basicAuth`,
+     * `sigV4AccessKeyId`.
+     */
+    credential?: (request: Request) => string | undefined;
+    /**
+     * Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. They join the
+     * standard presets every mock has; one with a standard name replaces it.
+     */
+    presets?: Record<string, FaultPreset>;
+    /** Outbound webhooks; adds the `/__admin/webhooks*` routes and clears on reset. */
+    webhooks?: WebhookHub;
+    /** Retained time-travel checkpoints per namespace. Default 1,000. */
+    maxCheckpoints?: number;
+    /** Injectable process IO used for observability and delays; logical service time uses `clock`. */
+    io?: Partial<RuntimeIO>;
+    /**
+     * Collections the admin UI should show even before any row exists.
+     * Stored collections are always included, whether or not they are declared.
+     * A function may describe collections that depend on the live instance.
+     */
+    state?: readonly StateDeclaration[] | ((api: T, namespace: string) => readonly StateDeclaration[]);
+    /**
+     * Panels added to the default admin UI, or a function that replaces the document.
+     * `render` receives `defaultHtml()` so a bespoke UI can wrap the shared shell.
+     */
+    adminUi?: AdminUi;
+};
+type RuntimeIO = {
+    wallNow(): number;
+    monotonicNow(): number;
+    /** Wait on the wall clock. Rejects with the signal's reason when it aborts first. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+};
+type ServiceTimelineState = Readonly<{
+    snapshot: NamespaceSnapshot;
+    /** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
+    clock: Readonly<ClockState & {
+        pinned?: boolean;
+    }>;
+    rngState: number;
+}>;
+type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
+type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
+    /** Stop package-owned lifecycle timers when a supervisor closes the runtime. */
+    stop?(): void;
+    readonly name: string;
+    /** Same-origin Fetch handler and App Router method exports, sharing this runtime. */
+    mount(prefix: string): MountedAPI;
+    readonly sqlite: SqliteClient;
+    readonly clock: Clock;
+    readonly faults: FaultRegistry;
+    /** Baseline response time per namespace. */
+    readonly latency: LatencyRegistry;
+    readonly metrics: Metrics;
+    readonly journal: Journal;
+    readonly rng: Rng;
+    readonly credentials: CredentialRegistry;
+    /** The webhook hub, when the service has outbound webhooks. */
+    readonly webhooks: WebhookHub | undefined;
+    /**
+     * A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
+     * offset and a freeze of its own, so moving one never moves another.
+     */
+    namespaceClock(namespace?: string): Clock;
+    namespaceOf(request: Request): string;
+    /** Opaque in-process checkpoint including records, controls and webhook history. */
+    fleetSnapshot(namespace: string): object;
+    fleetRestore(snapshot: unknown, namespace: string): void;
+    /** Expand a named preset into fault rules (and webhook faults) for `namespace`. */
+    applyPreset(name: string, namespace?: string, overrides?: Partial<FaultRule>): FaultRule[];
+    /** The instance behind `namespace` (the default one when omitted), created on first use. */
+    instance(namespace?: string): T;
+    /** Public names of every namespace created so far. */
+    namespaces(): string[];
+    /** Return one namespace to its boot state, or every namespace with `"*"`. */
+    reset(namespace?: string): Promise<void>;
+    /** Reset a namespace and forget it, releasing everything it held. */
+    dropNamespace(namespace: string): Promise<void>;
+    /** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
+    controls(namespace?: string): ControlState & {
+        snapshots: SnapshotInfo[];
+    };
+    /** Apply a control document to a namespace. A given key replaces that control. */
+    configure(controls: NamespaceControls, namespace?: string): ControlState & {
+        snapshots: SnapshotInfo[];
+    };
+    /** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
+    readonly snapshots: {
+        /** Capture the namespace now. Reusing a name replaces that snapshot. */
+        create(options?: {
+            name?: string;
+            namespace?: string;
+        }): SnapshotInfo;
+        list(namespace?: string): SnapshotInfo[];
+        /** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
+        export(id: string, namespace?: string): SnapshotDocument;
+        /** Store a document as a snapshot without restoring it. */
+        import(document: SnapshotDocument, options?: {
+            name?: string;
+            namespace?: string;
+        }): SnapshotInfo;
+        restore(id: string, namespace?: string): void;
+        delete(id: string, namespace?: string): boolean;
+    };
+    /** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
+    headers(input: ControlHeaderInput): Record<string, string>;
+    snapshot(namespace?: string): NamespaceSnapshot;
+    restore(snapshot: NamespaceSnapshot, namespace?: string): void;
+    /** Capture the current branch. Mutating HTTP calls do this automatically. */
+    checkpoint(namespace?: string, branch?: string): ServiceCheckpoint;
+    /** Create an isolated branch, optionally from a historical checkpoint. */
+    branch(name: string, options?: {
+        namespace?: string;
+        at?: string;
+    }): ServiceCheckpoint;
+    /** Restore a branch, clock, and PRNG to a checkpoint. */
+    checkout(checkpoint: string, options?: {
+        namespace?: string;
+        branch?: string;
+    }): void;
+    /** Inspect the retained history for a namespace. */
+    timeline(namespace?: string): Timeline<ServiceTimelineState>;
+    /** Collections in one namespace: declared shape plus what the rows actually hold. */
+    state(namespace?: string): StateView;
+};
+
+type MicrosoftRuntimeOptions = Pick<RuntimeOptions<MicrosoftAPI>, "sqlite" | "clock" | "seed" | "adminPrefix" | "adminKey" | "adminControls" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<MicrosoftAPIOptions, "fixtures" | "baseUrl" | "tokens">;
+type MicrosoftRuntime = ServiceRuntime<MicrosoftAPI>;
+declare function createRuntime(options?: MicrosoftRuntimeOptions): MicrosoftRuntime;
+
+declare const MICROSOFT_NAMESPACE = "microsoft";
+type MicrosoftAPIOptions = ProviderOptions & {
+    fixtures?: MicrosoftSeedConfig;
+};
+declare class MicrosoftAPI extends ProviderAPI {
+    private readonly fixtures;
+    constructor(options?: MicrosoftAPIOptions);
+    reset(): Promise<void>;
+}
+
+export { MICROSOFT_NAMESPACE, MicrosoftAPI, createRuntime, document, operationIds, supportedOperationIds };
+export type { MicrosoftAPIOptions, MicrosoftRuntime, MicrosoftRuntimeOptions, SqliteClient$1 as SqliteClient };