@crvouga/mockingbird-service-docker 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -10,76 +10,16 @@ interface FetchAPI$1 {
     fetch(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;
+type MountedAPI = FetchAPI & {
+    readonly prefix: string;
+    GET: FetchHandler;
+    POST: FetchHandler;
+    PUT: FetchHandler;
+    PATCH: FetchHandler;
+    DELETE: FetchHandler;
+    HEAD: FetchHandler;
+    OPTIONS: FetchHandler;
 };
-/**
- * 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;
-    }>;
-}
 
 /** A stable identifier for a point in a {@link Timeline}. */
 type CheckpointId = string;
@@ -170,6 +110,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;
+    }>;
+}
 
 /**
  * The slice of OpenAPI 3.1 (and JSON Schema 2020-12) Mockingbird understands.
@@ -361,7 +374,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 = {
@@ -397,7 +410,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;
 };
 
 /**
@@ -406,44 +422,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;
+    /**
+     * 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 (`delayMs` /
-     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
-     * the request then still reaches the service.
+     * 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
@@ -452,8 +507,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 = {
@@ -461,6 +516,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>;
@@ -485,38 +544,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;
 };
 
 /**
@@ -556,6 +777,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. */
@@ -601,6 +824,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;
@@ -615,6 +844,38 @@ 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[];
+};
+
 type AdminRequest = {
     request: Request;
     url: URL;
@@ -631,6 +892,17 @@ type AdminRoute = (request: AdminRequest) => Response | Promise<Response>;
  * `: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 = {
@@ -875,14 +1147,26 @@ type RuntimeOptions<T extends ServiceInstance> = {
     sqlite?: SqliteClient$1;
     /** Defaults to a live clock over `Date.now`. */
     clock?: Clock;
-    /** Seeds every random choice the runtime makes (fault rates). Default `0`. */
+    /** 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. */
@@ -900,7 +1184,10 @@ type RuntimeOptions<T extends ServiceInstance> = {
      * `sigV4AccessKeyId`.
      */
     credential?: (request: Request) => string | undefined;
-    /** Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. */
+    /**
+     * 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;
@@ -923,11 +1210,15 @@ type RuntimeOptions<T extends ServiceInstance> = {
 type RuntimeIO = {
     wallNow(): number;
     monotonicNow(): number;
-    sleep(ms: number): Promise<void>;
+    /** 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;
-    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>;
@@ -935,17 +1226,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. */
@@ -957,8 +1254,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. */
@@ -1271,7 +1598,7 @@ type SupportedOperationId = "ContainerList" | "ContainerCreate" | "ContainerInsp
 declare const operationIds: readonly ["ContainerList", "ContainerCreate", "ContainerInspect", "ContainerStart", "ContainerStop", "ContainerKill", "ContainerAttach", "ContainerWait", "ContainerDelete", "SystemInfo", "SystemVersion", "SystemPing", "SystemPingHead"];
 declare const supportedOperationIds: readonly ["ContainerList", "ContainerCreate", "ContainerInspect", "ContainerStart", "ContainerStop", "ContainerKill", "ContainerWait", "ContainerDelete", "SystemInfo", "SystemVersion", "SystemPing", "SystemPingHead"];
 
-type DockerRuntimeOptions = Pick<RuntimeOptions<DockerAPI>, "sqlite" | "clock" | "seed" | "adminKey" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<DockerAPIOptions, "onAttach">;
+type DockerRuntimeOptions = Pick<RuntimeOptions<DockerAPI>, "sqlite" | "clock" | "seed" | "adminKey" | "adminControls" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<DockerAPIOptions, "onAttach">;
 type DockerRuntime = ServiceRuntime<DockerAPI> & {
     close(): void;
 };