@crvouga/mockingbird-service-slack 3.1.0 → 3.3.0

package/dist/index.d.ts

@@ -11,9 +11,9 @@ interface FetchAPI$1 {
 }
 
 /** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
-type SqliteValue$1 = null | number | bigint | string | Uint8Array | boolean;
+type SqliteValue$2 = null | number | bigint | string | Uint8Array | boolean;
 /** Mutation counters returned by {@link SqliteStatement.run}. */
-type SqliteRunResult$1 = {
+type SqliteRunResult$2 = {
     changes: number;
     lastInsertRowid: number | bigint;
 };
@@ -22,10 +22,10 @@ type SqliteRunResult$1 = {
  *
  * 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;
+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.
@@ -33,54 +33,163 @@ interface SqliteStatement$1 {
  * 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 {
+interface SqliteClient$2 {
     exec(sql: string): void;
-    prepare(sql: string): SqliteStatement$1;
+    prepare(sql: string): SqliteStatement$2;
     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";
+/** Options every provider constructor accepts. */
+type APIOptions$1 = {
+    /** Sync SQLite client. Defaults to `@crvouga/mockingbird-service-sqlite`. */
+    sqlite?: SqliteClient$2;
+    /** 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;
 };
-/**
- * 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<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$1, 
-    /** 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;
+
+interface AuthUser {
+    login: string;
+    id: number;
+    scopes: string[];
+    installation?: AuthInstallation;
+}
+interface AuthInstallation {
+    installationId: number;
+    appId: number;
+    accountId: number;
+    accountType: "User" | "Organization";
+    permissions: Record<string, string>;
+    repositoryIds: number[];
+    repositorySelection: "all" | "selected";
+}
+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 SlackUserProfile {
+    display_name: string;
+    real_name: string;
+    email: string;
+    image_48: string;
+    image_192: string;
+    title?: string;
+    phone?: string;
+    skype?: string;
+    real_name_normalized?: string;
+    display_name_normalized?: string;
+    fields?: Record<string, {
+        value: string;
+        alt?: string;
+        label?: string;
+    }>;
+    status_text?: string;
+    status_emoji?: string;
+    status_emoji_display_info?: Record<string, unknown>[];
+    status_expiration?: number;
+    avatar_hash?: string;
+    start_date?: string;
+    pronouns?: string;
+    huddle_state?: string;
+    huddle_state_expiration_ts?: number;
+    first_name?: string;
+    last_name?: string;
+    image_24?: string;
+    image_32?: string;
+    image_72?: string;
+    image_512?: string;
+}
+type SlackPresence = "active" | "away";
+type SlackTokenType = "bot" | "user" | "test";
+
+interface SlackSeedConfig {
+    port?: number;
+    team?: {
+        name?: string;
+        domain?: string;
+    };
+    users?: Array<{
+        name: string;
+        real_name?: string;
+        email?: string;
+        is_admin?: boolean;
+        profile?: Partial<SlackUserProfile>;
+        presence?: SlackPresence;
+    }>;
+    channels?: Array<{
+        name: string;
+        topic?: string;
+        purpose?: string;
+        is_private?: boolean;
+    }>;
+    bots?: Array<{
+        name: string;
+    }>;
+    oauth_apps?: Array<{
+        app_id?: string;
+        client_id: string;
+        client_secret: string;
+        name: string;
+        redirect_uris: string[];
+        scopes?: string[] | string;
+        user_scopes?: string[] | string;
+        bot_id?: string;
+        bot_user_id?: string;
+        bot_name?: string;
+    }>;
+    tokens?: Array<{
+        token: string;
+        type?: SlackTokenType;
+        user?: string;
+        user_id?: string;
+        scopes?: string[] | string;
+        app_id?: string;
+        client_id?: string;
+        team_id?: string;
+        bot_id?: string;
+        bot_user_id?: string;
+        authed_user_id?: string;
+    }>;
+    incoming_webhooks?: Array<{
+        channel: string;
+        label?: string;
     }>;
+    strict_scopes?: boolean;
+    signing_secret?: string;
 }
 
+type ProviderOptions = APIOptions$1 & {
+    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;
+};
+
+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. */
@@ -170,6 +279,79 @@ declare class Timeline<T> {
 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$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;
+}
+
+/** 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<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$1, 
+    /** 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 = {
@@ -196,7 +378,7 @@ type ClockState = {
     now: number;
     /** True while time does not advance on its own. */
     frozen: boolean;
-    /** Milliseconds this clock adds to its underlying source. */
+    /** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
     offsetMs: number;
 };
 type Clock = {
@@ -232,7 +414,10 @@ type Rng = {
     state(): number;
     /** Restore a state previously returned by {@link state}. */
     setState(state: number): void;
-    seed: number;
+    /** 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;
 };
 
 /**
@@ -241,44 +426,83 @@ type Rng = {
  * 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. */
+    /** 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;
     /**
-     * Status of the injected response. Omit for a rule that only delays (`delayMs` /
-     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
-     * the request then still reaches the service.
+     * 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>;
-    /** Retire the rule after this many faults. Omit to keep it until removed. */
-    count?: number;
-    /** Fault this fraction of matching requests, `0`–`1`. Default `1`. */
-    rate?: number;
-    /** Hold the response back this long, to exercise timeouts. */
+    /** 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
@@ -287,8 +511,8 @@ type FaultRule = {
     effect?: string;
     /** Parameters for `effect`. */
     params?: Record<string, unknown>;
-    /** From the preset this rule was expanded from, if any. */
-    preset?: string;
+    /** The preset this rule was expanded from, if any. */
+    fromPreset?: string;
 };
 /** A fault that fired for one request. */
 type FaultHit = {
@@ -296,6 +520,10 @@ type FaultHit = {
     /** 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>;
@@ -320,38 +548,200 @@ type FaultCandidate = {
     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 = {
-    isolateNamespaces(): void;
-    snapshot(namespace: string): {
-        rules: (FaultRule & {
-            remaining: number | null;
-            hits: number;
-            position: number;
-        })[];
-        rngState: number;
-    };
+    snapshot(namespace: string): FaultSnapshot;
+    /** Add a rule, or replace the rule with the same id in the same namespace. */
     add(rule: FaultRule): FaultRule;
-    list(): (FaultRule & {
-        remaining: number | null;
-        hits: number;
-    })[];
-    remove(id: string): boolean;
-    clear(): void;
-    restore(namespace: string, state: {
-        rules: (FaultRule & {
-            remaining: number | null;
-            hits: number;
-            position: number;
-        })[];
-        rngState: number;
-    }): void;
+    /** 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;
 };
 
 /**
@@ -391,6 +781,8 @@ type RequestLog = {
     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. */
@@ -436,6 +828,12 @@ 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;
@@ -450,6 +848,50 @@ type Journal = {
     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[];
+};
+
+/** 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;
@@ -604,7 +1046,10 @@ type ServiceInstance = FetchAPI & {
 };
 type ServiceTimelineState = Readonly<{
     snapshot: NamespaceSnapshot;
-    clock: Readonly<ReturnType<Clock["state"]>>;
+    /** `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>;
@@ -612,17 +1057,23 @@ 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$1;
     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;
-    /** Enable independent namespace clocks and PRNGs before serving a fleet. */
-    isolateNamespaces(): void;
+    /**
+     * 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. */
@@ -634,8 +1085,38 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
     instance(namespace?: string): T;
     /** Public names of every namespace created so far. */
     namespaces(): string[];
-    /** Reset one namespace, or every namespace with `"*"`. */
+    /** 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. */
@@ -1019,22 +1500,24 @@ type OpenAPIDocument = {
 };
 
 declare const document: OpenAPIDocument;
-type OperationId = "PostIncomingWebhook" | "ChatPostMessage" | "ChatUpdate" | "ChatPostEphemeral" | "ChatGetPermalinkGet" | "ChatGetPermalink" | "ReactionsAdd" | "ReactionsRemove" | "ReactionsGetGet" | "ReactionsGet" | "AuthTestGet" | "AuthTest" | "ConversationsJoin" | "UsersInfoGet" | "UsersInfo" | "UsersLookupByEmailGet" | "UsersLookupByEmail" | "FilesInfoGet" | "FilesInfo" | "ViewsOpen" | "AppsConnectionsOpen";
-type SupportedOperationId = "PostIncomingWebhook" | "ChatPostMessage" | "ChatUpdate" | "ChatPostEphemeral" | "ChatGetPermalinkGet" | "ChatGetPermalink" | "ReactionsAdd" | "ReactionsRemove" | "ReactionsGetGet" | "ReactionsGet" | "AuthTestGet" | "AuthTest" | "ConversationsJoin" | "UsersInfoGet" | "UsersInfo" | "UsersLookupByEmailGet" | "UsersLookupByEmail" | "FilesInfoGet" | "FilesInfo" | "ViewsOpen" | "AppsConnectionsOpen";
-declare const operationIds: readonly ["PostIncomingWebhook", "ChatPostMessage", "ChatUpdate", "ChatPostEphemeral", "ChatGetPermalinkGet", "ChatGetPermalink", "ReactionsAdd", "ReactionsRemove", "ReactionsGetGet", "ReactionsGet", "AuthTestGet", "AuthTest", "ConversationsJoin", "UsersInfoGet", "UsersInfo", "UsersLookupByEmailGet", "UsersLookupByEmail", "FilesInfoGet", "FilesInfo", "ViewsOpen", "AppsConnectionsOpen"];
-declare const supportedOperationIds: readonly ["PostIncomingWebhook", "ChatPostMessage", "ChatUpdate", "ChatPostEphemeral", "ChatGetPermalinkGet", "ChatGetPermalink", "ReactionsAdd", "ReactionsRemove", "ReactionsGetGet", "ReactionsGet", "AuthTestGet", "AuthTest", "ConversationsJoin", "UsersInfoGet", "UsersInfo", "UsersLookupByEmailGet", "UsersLookupByEmail", "FilesInfoGet", "FilesInfo", "ViewsOpen", "AppsConnectionsOpen"];
+type OperationId = "PostIncomingWebhook" | "ChatPostMessage" | "ChatUpdate" | "ChatPostEphemeral" | "ChatGetPermalinkGet" | "ChatGetPermalink" | "ReactionsAdd" | "ReactionsRemove" | "ReactionsGetGet" | "ReactionsGet" | "AuthTestGet" | "AuthTest" | "ConversationsJoin" | "UsersInfoGet" | "UsersInfo" | "UsersLookupByEmailGet" | "UsersLookupByEmail" | "FilesInfoGet" | "FilesInfo" | "ViewsOpen" | "AppsConnectionsOpen" | "GET /" | "GET /api/files.list" | "POST /api/files.list" | "GET /api/pins.list" | "POST /api/pins.list" | "GET /api/users.getPresence" | "POST /api/users.getPresence" | "GET /api/users.profile.get" | "POST /api/users.profile.get" | "GET /files-pri/:fileId/:filename" | "GET /oauth/v2/authorize" | "POST /api/bookmarks.add" | "POST /api/bookmarks.edit" | "POST /api/bookmarks.list" | "POST /api/bookmarks.remove" | "POST /api/bots.info" | "POST /api/chat.delete" | "POST /api/chat.deleteScheduledMessage" | "POST /api/chat.meMessage" | "POST /api/chat.scheduleMessage" | "POST /api/chat.scheduledMessages.list" | "POST /api/conversations.archive" | "POST /api/conversations.close" | "POST /api/conversations.create" | "POST /api/conversations.history" | "POST /api/conversations.info" | "POST /api/conversations.invite" | "POST /api/conversations.kick" | "POST /api/conversations.leave" | "POST /api/conversations.list" | "POST /api/conversations.mark" | "POST /api/conversations.members" | "POST /api/conversations.open" | "POST /api/conversations.rename" | "POST /api/conversations.replies" | "POST /api/conversations.setPurpose" | "POST /api/conversations.setTopic" | "POST /api/conversations.unarchive" | "POST /api/files.completeUploadExternal" | "POST /api/files.delete" | "POST /api/files.getUploadURLExternal" | "POST /api/oauth.v2.access" | "POST /api/pins.add" | "POST /api/pins.remove" | "POST /api/team.info" | "POST /api/users.list" | "POST /api/users.profile.set" | "POST /api/users.setPresence" | "POST /api/views.generateTriggerId" | "POST /api/views.publish" | "POST /api/views.push" | "POST /api/views.update" | "POST /oauth/v2/authorize/callback" | "POST /upload/v1/:fileId";
+type SupportedOperationId = "PostIncomingWebhook" | "ChatPostMessage" | "ChatUpdate" | "ChatPostEphemeral" | "ChatGetPermalinkGet" | "ChatGetPermalink" | "ReactionsAdd" | "ReactionsRemove" | "ReactionsGetGet" | "ReactionsGet" | "AuthTestGet" | "AuthTest" | "ConversationsJoin" | "UsersInfoGet" | "UsersInfo" | "UsersLookupByEmailGet" | "UsersLookupByEmail" | "FilesInfoGet" | "FilesInfo" | "ViewsOpen" | "AppsConnectionsOpen" | "GET /" | "GET /api/files.list" | "POST /api/files.list" | "GET /api/pins.list" | "POST /api/pins.list" | "GET /api/users.getPresence" | "POST /api/users.getPresence" | "GET /api/users.profile.get" | "POST /api/users.profile.get" | "GET /files-pri/:fileId/:filename" | "GET /oauth/v2/authorize" | "POST /api/bookmarks.add" | "POST /api/bookmarks.edit" | "POST /api/bookmarks.list" | "POST /api/bookmarks.remove" | "POST /api/bots.info" | "POST /api/chat.delete" | "POST /api/chat.deleteScheduledMessage" | "POST /api/chat.meMessage" | "POST /api/chat.scheduleMessage" | "POST /api/chat.scheduledMessages.list" | "POST /api/conversations.archive" | "POST /api/conversations.close" | "POST /api/conversations.create" | "POST /api/conversations.history" | "POST /api/conversations.info" | "POST /api/conversations.invite" | "POST /api/conversations.kick" | "POST /api/conversations.leave" | "POST /api/conversations.list" | "POST /api/conversations.mark" | "POST /api/conversations.members" | "POST /api/conversations.open" | "POST /api/conversations.rename" | "POST /api/conversations.replies" | "POST /api/conversations.setPurpose" | "POST /api/conversations.setTopic" | "POST /api/conversations.unarchive" | "POST /api/files.completeUploadExternal" | "POST /api/files.delete" | "POST /api/files.getUploadURLExternal" | "POST /api/oauth.v2.access" | "POST /api/pins.add" | "POST /api/pins.remove" | "POST /api/team.info" | "POST /api/users.list" | "POST /api/users.profile.set" | "POST /api/users.setPresence" | "POST /api/views.generateTriggerId" | "POST /api/views.publish" | "POST /api/views.push" | "POST /api/views.update" | "POST /oauth/v2/authorize/callback" | "POST /upload/v1/:fileId";
+declare const operationIds: readonly ["PostIncomingWebhook", "ChatPostMessage", "ChatUpdate", "ChatPostEphemeral", "ChatGetPermalinkGet", "ChatGetPermalink", "ReactionsAdd", "ReactionsRemove", "ReactionsGetGet", "ReactionsGet", "AuthTestGet", "AuthTest", "ConversationsJoin", "UsersInfoGet", "UsersInfo", "UsersLookupByEmailGet", "UsersLookupByEmail", "FilesInfoGet", "FilesInfo", "ViewsOpen", "AppsConnectionsOpen", "GET /", "GET /api/files.list", "POST /api/files.list", "GET /api/pins.list", "POST /api/pins.list", "GET /api/users.getPresence", "POST /api/users.getPresence", "GET /api/users.profile.get", "POST /api/users.profile.get", "GET /files-pri/:fileId/:filename", "GET /oauth/v2/authorize", "POST /api/bookmarks.add", "POST /api/bookmarks.edit", "POST /api/bookmarks.list", "POST /api/bookmarks.remove", "POST /api/bots.info", "POST /api/chat.delete", "POST /api/chat.deleteScheduledMessage", "POST /api/chat.meMessage", "POST /api/chat.scheduleMessage", "POST /api/chat.scheduledMessages.list", "POST /api/conversations.archive", "POST /api/conversations.close", "POST /api/conversations.create", "POST /api/conversations.history", "POST /api/conversations.info", "POST /api/conversations.invite", "POST /api/conversations.kick", "POST /api/conversations.leave", "POST /api/conversations.list", "POST /api/conversations.mark", "POST /api/conversations.members", "POST /api/conversations.open", "POST /api/conversations.rename", "POST /api/conversations.replies", "POST /api/conversations.setPurpose", "POST /api/conversations.setTopic", "POST /api/conversations.unarchive", "POST /api/files.completeUploadExternal", "POST /api/files.delete", "POST /api/files.getUploadURLExternal", "POST /api/oauth.v2.access", "POST /api/pins.add", "POST /api/pins.remove", "POST /api/team.info", "POST /api/users.list", "POST /api/users.profile.set", "POST /api/users.setPresence", "POST /api/views.generateTriggerId", "POST /api/views.publish", "POST /api/views.push", "POST /api/views.update", "POST /oauth/v2/authorize/callback", "POST /upload/v1/:fileId"];
+declare const supportedOperationIds: readonly ["PostIncomingWebhook", "ChatPostMessage", "ChatUpdate", "ChatPostEphemeral", "ChatGetPermalinkGet", "ChatGetPermalink", "ReactionsAdd", "ReactionsRemove", "ReactionsGetGet", "ReactionsGet", "AuthTestGet", "AuthTest", "ConversationsJoin", "UsersInfoGet", "UsersInfo", "UsersLookupByEmailGet", "UsersLookupByEmail", "FilesInfoGet", "FilesInfo", "ViewsOpen", "AppsConnectionsOpen", "GET /", "GET /api/files.list", "POST /api/files.list", "GET /api/pins.list", "POST /api/pins.list", "GET /api/users.getPresence", "POST /api/users.getPresence", "GET /api/users.profile.get", "POST /api/users.profile.get", "GET /files-pri/:fileId/:filename", "GET /oauth/v2/authorize", "POST /api/bookmarks.add", "POST /api/bookmarks.edit", "POST /api/bookmarks.list", "POST /api/bookmarks.remove", "POST /api/bots.info", "POST /api/chat.delete", "POST /api/chat.deleteScheduledMessage", "POST /api/chat.meMessage", "POST /api/chat.scheduleMessage", "POST /api/chat.scheduledMessages.list", "POST /api/conversations.archive", "POST /api/conversations.close", "POST /api/conversations.create", "POST /api/conversations.history", "POST /api/conversations.info", "POST /api/conversations.invite", "POST /api/conversations.kick", "POST /api/conversations.leave", "POST /api/conversations.list", "POST /api/conversations.mark", "POST /api/conversations.members", "POST /api/conversations.open", "POST /api/conversations.rename", "POST /api/conversations.replies", "POST /api/conversations.setPurpose", "POST /api/conversations.setTopic", "POST /api/conversations.unarchive", "POST /api/files.completeUploadExternal", "POST /api/files.delete", "POST /api/files.getUploadURLExternal", "POST /api/oauth.v2.access", "POST /api/pins.add", "POST /api/pins.remove", "POST /api/team.info", "POST /api/users.list", "POST /api/users.profile.set", "POST /api/users.setPresence", "POST /api/views.generateTriggerId", "POST /api/views.publish", "POST /api/views.push", "POST /api/views.update", "POST /oauth/v2/authorize/callback", "POST /upload/v1/:fileId"];
 
 /**
  * Every named Slack misbehaviour our consumers branch on, switched on with
  * `POST /__admin/faults {"preset": "<name>"}` (add `count` to limit it, `params` to tune it).
  */
 declare const SLACK_PRESETS: Record<string, FaultPreset>;
-type SlackRuntimeOptions = {
+type SlackRuntimeOptions = Pick<SlackAPIOptions, "fixtures" | "baseUrl" | "tokens"> & {
     sqlite?: SqliteClient;
     clock?: Clock;
     seed?: number | string;
     adminPrefix?: string;
     adminKey?: string;
+    /** Admin controls to boot with: clock, latency, faults, seed, a starting snapshot. */
+    adminControls?: MockControls;
     onLog?: (entry: RequestLog) => void;
     settings?: Partial<Settings>;
 };
@@ -1047,7 +1530,8 @@ type SlackRuntime = ServiceRuntime<SlackAPI>;
 declare const createRuntime: (options?: SlackRuntimeOptions) => SlackRuntime;
 
 declare const SLACK_NAMESPACE = "slack";
-type SlackAPIOptions = APIOptions & {
+type SlackAPIOptions = APIOptions & Pick<ProviderOptions, "tokens" | "baseUrl" | "publicNamespace" | "adminPrefix" | "random"> & {
+    fixtures?: SlackSeedConfig;
     /** Initial per-namespace settings (workspace identity, accepted tokens, strict channels). */
     settings?: Partial<Settings>;
     /**
@@ -1071,11 +1555,14 @@ declare class SlackAPI implements FetchAPI$1 {
     readonly app: Hono;
     readonly sqlite: SqliteClient;
     readonly state: SlackState;
+    private tail;
+    private readonly expansion;
     private readonly service;
     private readonly now;
     private readonly namespaceName;
     constructor(options?: SlackAPIOptions);
     fetch(request: Request): Promise<Response>;
+    private handleFetch;
     reset(): Promise<void>;
     /** Every message in the outbox, oldest first. */
     messages(): SlackMessage[];