@crvouga/mockingbird-service-bedrock 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1169 @@
+import { Hono } from 'hono';
+
+/**
+ * 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$1 {
+    fetch(request: Request): Promise<Response>;
+}
+
+/**
+ * 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 this clock adds to its underlying source. */
+    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;
+};
+
+/** 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;
+    private readonly namespace;
+    private readonly name;
+    constructor(sqlite: SqliteClient$1, namespace: string, name: 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;
+    }>;
+}
+
+/**
+ * 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;
+    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.
+ */
+type FaultRule = {
+    /** Stable id, so a suite can retire exactly the rule it added. */
+    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 paths starting with this prefix. Omit to match every path. */
+    pathPrefix?: 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;
+    /**
+     * 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?: number;
+    /** Response body, serialized as JSON. A string is sent as-is. */
+    body?: unknown;
+    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. */
+    delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: 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;
+    /**
+     * 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>;
+    /** From the preset this rule was expanded from, if any. */
+    preset?: 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;
+    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;
+};
+type FaultRegistry = {
+    add(rule: FaultRule): FaultRule;
+    list(): (FaultRule & {
+        remaining: number | null;
+        hits: number;
+    })[];
+    remove(id: string): boolean;
+    clear(): 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[]>;
+};
+
+/** 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;
+    /** 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;
+};
+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(): MetricsReport;
+    reset(): 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;
+    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;
+};
+
+/** 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;
+    }[];
+};
+
+/**
+ * Sequential id source persisted in SQLite. Ids are deterministic for a given
+ * sequence history (`cus_` + 14 opaque chars), so reproductions stay stable.
+ */
+declare class IdSequence {
+    private readonly sqlite;
+    private readonly namespace;
+    private readonly salt;
+    constructor(sqlite: SqliteClient$1, namespace: string, salt?: string);
+    next(prefix: string, length?: number): string;
+}
+
+/** 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 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;
+    }[];
+};
+
+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 = {
+    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. */
+    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>;
+};
+type ServiceTimelineState = Readonly<{
+    snapshot: NamespaceSnapshot;
+    clock: Readonly<ReturnType<Clock["state"]>>;
+    rngState: number;
+}>;
+type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
+type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
+    readonly name: string;
+    readonly sqlite: SqliteClient$1;
+    readonly clock: Clock;
+    readonly faults: FaultRegistry;
+    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;
+    /** 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[];
+    /** Reset one namespace, or every namespace with `"*"`. */
+    reset(namespace?: string): Promise<void>;
+    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>;
+};
+
+/** Options every provider constructor accepts. */
+type APIOptions = {
+    /** Sync SQLite client. Defaults to `@crvouga/mockingbird-service-sqlite`. */
+    sqlite?: SqliteClient$1;
+    /** 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 = 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 scripting model: the mock never generates language, it replays scripts.
+ *
+ * A script is a `match` (which model calls it answers) and a sequence of `turns`. The turn
+ * a call gets is read off the conversation itself, not from server state: it is the number
+ * of assistant messages since the member last said something (a user message with any
+ * content other than tool results). So the first call of a user turn gets turn 0, the call
+ * that resumes after a `toolResult` gets turn 1, and a new conversation starts over — with
+ * no bookkeeping that parallel workers or retries could skew.
+ *
+ * Only metadata is derived from a request (tool names, flags, a SHA-256 of the system
+ * prompt); prompt and message text are read for matching and never stored.
+ */
+/** Operations a script can answer. */
+declare const MODEL_OPERATIONS: readonly ["Converse", "ConverseStream", "InvokeModel", "InvokeModelWithBidirectionalStream", "InvokeHarness"];
+type ModelOperation = (typeof MODEL_OPERATIONS)[number];
+declare const STOP_REASONS: readonly ["end_turn", "tool_use", "max_tokens", "stop_sequence", "guardrail_intervened", "content_filtered"];
+type StopReason = (typeof STOP_REASONS)[number];
+/** Failure modes a turn (or a fault preset) can inject. */
+declare const TURN_FAULTS: readonly ["throttling", "validation", "access_denied", "model_timeout", "service_unavailable", "internal_server", "mid_stream_exception", "max_tokens", "truncated_frame", "latency"];
+type TurnFaultType = (typeof TURN_FAULTS)[number];
+type TurnFault = {
+    type: TurnFaultType;
+    /** Error / exception message. Each type has a realistic default. */
+    message?: string;
+    /** `mid_stream_exception` / `truncated_frame`: content chunks sent before the failure. Default 1. */
+    afterChunks?: number;
+    /** `mid_stream_exception`: the exception frame's type. Default `modelStreamErrorException`. */
+    exceptionType?: string;
+    /** `latency`: mock-clock milliseconds before the response starts. */
+    latencyMs?: number;
+};
+type ScriptToolUse = {
+    name: string;
+    input?: unknown;
+    /** Default: a deterministic `tooluse_…` id. */
+    toolUseId?: string;
+};
+type ScriptUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    cacheReadInputTokens?: number;
+    cacheWriteInputTokens?: number;
+};
+type ScriptTurn = {
+    /** Assistant text, streamed in `chunkSize`-character deltas. */
+    text?: string;
+    chunkSize?: number;
+    /** Mock-clock delay before each streamed chunk (TTFT and pacing tests). */
+    delayMsPerChunk?: number;
+    /** Reasoning text streamed as `reasoningContent` before the answer. */
+    reasoning?: string;
+    toolUse?: ScriptToolUse | ScriptToolUse[];
+    /** Structured output, rendered in whichever form the request asked for. */
+    json?: unknown;
+    stopReason?: StopReason;
+    /** `true`, or the trace / blocked text, for a `guardrail_intervened` turn. */
+    guardrail?: boolean | {
+        text?: string;
+        trace?: unknown;
+    };
+    usage?: ScriptUsage;
+    /** This turn only answers a call whose last user message carries this tool's result. */
+    expectToolResult?: {
+        name: string;
+    };
+    fault?: TurnFaultType | TurnFault;
+    /** Nova Sonic: the ASR transcript echoed back for a spoken user turn. */
+    userTranscript?: string;
+    /** AgentCore InvokeHarness: a tool-result delta (`[{text}|{json}]`) instead of text. */
+    toolResult?: unknown[];
+};
+type TextMatch = {
+    contains?: string;
+    regex?: string;
+    flags?: string;
+};
+type ScriptMatch = {
+    /** Glob (`*` wildcard, case-insensitive) over the decoded model id, ARN or harness ARN. */
+    modelId?: string;
+    operation?: ModelOperation | ModelOperation[];
+    lastUserText?: string | TextMatch;
+    /** SHA-256 hex of the system prompt (text blocks joined with "\n"). */
+    systemHash?: string;
+    toolsInclude?: string[];
+    /** `auto`, `any`, `none`, or a forced tool's name. */
+    toolChoice?: string;
+    hasDocument?: boolean;
+    hasImage?: boolean;
+    /** 0-based index of this call among the namespace's model calls. */
+    callIndex?: number;
+};
+type Script = {
+    id: string;
+    match?: ScriptMatch;
+    turns: ScriptTurn[];
+    /** Stop matching after this many calls (counted per namespace). */
+    times?: number;
+};
+/** Parse and validate one script; a string is the first problem found. */
+declare const parseScript: (value: unknown, index: number) => Script | string;
+
+type PlanBlock = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "reasoning";
+    text: string;
+} | {
+    kind: "toolUse";
+    toolUseId: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: "toolResult";
+    toolUseId: string;
+    content: unknown[];
+};
+type Usage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadInputTokens?: number;
+    cacheWriteInputTokens?: number;
+};
+type Plan = {
+    /** The script that answered, or `undefined` for the unscripted default. */
+    scriptId: string | undefined;
+    /** Which default answered, when unscripted: `chat`, `structured`, `classifier`, `scribe`, `titan`, `harness`, `sonic`. */
+    fallback?: string;
+    blocks: PlanBlock[];
+    stopReason: StopReason;
+    usage: Usage;
+    trace?: Record<string, unknown>;
+    fault?: TurnFault;
+    chunkSize: number;
+    delayMsPerChunk: number;
+    userTranscript?: string;
+};
+/** Bedrock's canned guardrail refusal. */
+declare const GUARDRAIL_BLOCKED_TEXT = "Sorry, the model cannot answer this question.";
+/** What an unscripted chat call says. Deliberately content-free (never an echo). */
+declare const DEFAULT_CHAT_TEXT = "OK.";
+declare const DEFAULT_CLASSIFIER: {
+    category: string;
+    confidence: number;
+};
+declare const DEFAULT_SOAP_NOTE: {
+    sections: {
+        title: string;
+        content: string;
+    }[];
+    summary: string;
+};
+
+/** Waits `ms` on the mock clock; resolves early when `signal` aborts. */
+type Sleep = (ms: number, signal?: AbortSignal) => Promise<void>;
+
+/** Per-namespace knobs, set through `PUT /__admin/settings`; cleared on reset. */
+type Settings = {
+    /** What an unscripted chat call answers. Default `"OK."`. */
+    defaultText: string;
+    /** Characters per streamed text delta when a turn gives no `chunkSize`. Default 16. */
+    chunkSize: number;
+    /** Mock-clock delay before each streamed delta when a turn gives none. Default 0. */
+    delayMsPerChunk: number;
+    /** Nova Sonic: USER audio frames that end a spoken turn without a contentEnd (0 = off). */
+    audioTurnChunks: number;
+};
+declare const DEFAULT_SETTINGS: Settings;
+/** Counts for `GET /__admin/scripts` (and `/health`): metadata only. */
+type ModelStats = {
+    calls: number;
+    scripted: number;
+    /** Calls no script answered (the defaults). */
+    unscripted: number;
+    byScript: Record<string, number>;
+    /** Unscripted calls by which default answered them. */
+    byFallback: Record<string, number>;
+    byOperation: Record<string, number>;
+};
+declare class BedrockState {
+    private readonly seed;
+    readonly scripts: Collection<Script>;
+    readonly uses: Collection<number>;
+    readonly settings: Collection<Settings>;
+    readonly stats: Collection<ModelStats>;
+    readonly ids: IdSequence;
+    constructor(sqlite: SqliteClient, namespace: string, seed: {
+        settings: Partial<Settings>;
+        scripts: readonly Script[];
+    });
+    /** Re-apply the configured settings and scripts after a reset. */
+    ensureSeeded(): void;
+    current(): Settings;
+    update(patch: Partial<Settings>): Settings;
+    list(): Script[];
+    /** Replace every script (`PUT`) or add/overwrite by id (`POST`). */
+    put(scripts: readonly Script[], replace: boolean): Script[];
+    remove(id?: string): number;
+    usesOf(id: string): number;
+    use(id: string): void;
+    /** The 0-based index of this model call in the namespace, then count it. */
+    nextCallIndex(): number;
+    record(operation: string, scriptId: string | undefined, fallback: string | undefined): void;
+    currentStats(): ModelStats;
+}
+
+/**
+ * AWS event-stream framing (`application/vnd.amazon.eventstream`), both directions.
+ *
+ * Every frame is: a 12-byte prelude (total length, headers length, CRC32 of those 8 bytes),
+ * the headers, the payload, and a CRC32 of everything before it. `@smithy/eventstream-codec`
+ * (the AWS SDKs and the AI SDK) rejects a frame whose lengths or checksums are off by one
+ * byte, so this module is exact: it is the only place a frame is built or parsed.
+ *
+ * The same codec reads what an SDK sends on a bidirectional stream. Those frames arrive
+ * wrapped in a SigV4 envelope (`:date` + `:chunk-signature` headers around the encoded
+ * inner frame); {@link unwrapSigned} opens it. The signature itself is never verified.
+ */
+/** A typed header value; plain strings encode as type 7 (string). */
+type HeaderValue = {
+    type: "boolean";
+    value: boolean;
+} | {
+    type: "byte";
+    value: number;
+} | {
+    type: "short";
+    value: number;
+} | {
+    type: "integer";
+    value: number;
+} | {
+    type: "long";
+    value: bigint;
+} | {
+    type: "binary";
+    value: Uint8Array;
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "timestamp";
+    value: Date;
+} | {
+    type: "uuid";
+    value: string;
+};
+type EventStreamMessage = {
+    headers: Record<string, HeaderValue>;
+    body: Uint8Array;
+};
+/** What {@link encodeMessage} accepts: header values may be bare strings. */
+type MessageInput = {
+    headers: Record<string, HeaderValue | string>;
+    body?: Uint8Array | string;
+};
+declare class EventStreamError extends Error {
+    constructor(message: string);
+}
+/** CRC-32 (IEEE 802.3, the one event-stream uses) of `bytes`. */
+declare const crc32: (bytes: Uint8Array) => number;
+/** One complete frame: prelude, prelude CRC, headers, payload, message CRC. */
+declare const encodeMessage: (message: MessageInput) => Uint8Array;
+/** Parse exactly one frame, checking both lengths and both checksums. */
+declare const decodeMessage: (frame: Uint8Array) => EventStreamMessage;
+/** Splits a byte stream into frames as they complete. */
+declare class FrameReader {
+    private buffer;
+    /** Add bytes; returns every frame they complete. */
+    push(chunk: Uint8Array): EventStreamMessage[];
+    /** Bytes of an incomplete frame still waiting for the rest. */
+    get pending(): number;
+}
+/**
+ * The frame inside a SigV4 event envelope (`:chunk-signature`), `null` for the empty
+ * end-of-stream envelope, or the frame itself when it is not signed.
+ */
+declare const unwrapSigned: (message: EventStreamMessage) => EventStreamMessage | null;
+/** An `event` frame whose payload is JSON (or raw bytes, for blob event payloads). */
+declare const eventFrame: (eventType: string, payload: unknown, contentType?: string) => Uint8Array;
+/** An `exception` frame, as a service raises one mid-stream. */
+declare const exceptionFrame: (exceptionType: string, body: Record<string, unknown>) => Uint8Array;
+/** An async iterator over the frames of a byte stream (a request or response body). */
+declare function readFrames(body: ReadableStream<Uint8Array> | null): AsyncGenerator<EventStreamMessage>;
+
+/**
+ * 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;
+};
+
+declare const document: OpenAPIDocument;
+type OperationId = "Converse" | "ConverseStream" | "InvokeModel" | "InvokeModelWithResponseStream" | "InvokeModelWithBidirectionalStream" | "InvokeHarness";
+type SupportedOperationId = "Converse" | "ConverseStream" | "InvokeModel" | "InvokeModelWithBidirectionalStream" | "InvokeHarness";
+declare const operationIds: readonly ["Converse", "ConverseStream", "InvokeModel", "InvokeModelWithResponseStream", "InvokeModelWithBidirectionalStream", "InvokeHarness"];
+declare const supportedOperationIds: readonly ["Converse", "ConverseStream", "InvokeModel", "InvokeModelWithBidirectionalStream", "InvokeHarness"];
+
+/**
+ * The smallest instance of a JSON Schema: what an unscripted structured-output call
+ * answers with. The model never generates language here, so a caller's schema
+ * (`Output.object`, a forced tool's `inputSchema`, `outputConfig.textFormat`) is the only
+ * thing that decides the shape, and the object always validates against it.
+ *
+ * Handles what zod-to-json-schema, the AI SDK and hand-written tool schemas emit: `type`
+ * (including `["string","null"]`), `enum`, `const`, `anyOf`/`oneOf`/`allOf`, `$ref` into
+ * `definitions`/`$defs`, required properties, array bounds and `uniqueItems`, string
+ * lengths and common formats, and numeric bounds.
+ */
+/** A value that validates against `schema` (resolved against `root` for `$ref`s). */
+declare const sampleSchema: (schema: unknown, root?: unknown, depth?: number) => unknown;
+
+/**
+ * Every named Bedrock misbehaviour our consumer branches on, switched on with
+ * `POST /__admin/faults {"preset": "<name>", "count"?: n}` (a scripted turn can carry the
+ * same `fault` for one conversation step).
+ */
+declare const BEDROCK_PRESETS: Record<string, FaultPreset>;
+type BedrockRuntimeOptions = {
+    sqlite?: SqliteClient;
+    clock?: Clock;
+    seed?: number | string;
+    adminKey?: string;
+    onLog?: (entry: RequestLog) => void;
+    settings?: Partial<Settings>;
+    /** Scripts every namespace starts with (and returns to on reset). */
+    scripts?: readonly Script[];
+};
+type BedrockRuntime = ServiceRuntime<BedrockAPI>;
+/**
+ * The Bedrock mock with Mockingbird's full service contract: `/health`, `/__admin/*`,
+ * namespaces by header, by `/ns/<name>` path prefix, or by SigV4 access key id
+ * (`PUT /__admin/credentials {"credentials": {"<AWS_ACCESS_KEY_ID>": "<namespace>"}}`),
+ * clock control (script pacing runs on it), fault presets, scripts and a request journal
+ * that records metadata only.
+ */
+declare const createRuntime: (options?: BedrockRuntimeOptions) => BedrockRuntime;
+
+declare const BEDROCK_NAMESPACE = "bedrock";
+/** A Bedrock error response: status, `x-amzn-ErrorType`, `{message}`. */
+declare const bedrockError: (status: number, type: string, message: string, requestId?: string) => Response;
+/**
+ * The namespace credential of an AWS request: its SigV4 access key id. Map it with
+ * `PUT /__admin/credentials {"credentials": {"<AWS_ACCESS_KEY_ID>": "<namespace>"}}`.
+ */
+declare const accessKeyCredential: (request: Request) => string | undefined;
+/**
+ * Wait `ms` on a (possibly frozen) mock clock: polls `now()` so a frozen clock waits until
+ * a test advances it, and a live clock waits in real time.
+ */
+declare const clockSleep: (now: () => number) => Sleep;
+/** A deterministic 1024-d (or `dims`-d) unit vector: SHA-256(inputText) in counter mode. */
+declare const titanEmbedding: (inputText: string, dims?: number) => Promise<number[]>;
+type BedrockAPIOptions = APIOptions & {
+    /** Initial per-namespace settings. */
+    settings?: Partial<Settings>;
+    /** Scripts every namespace starts with (re-applied on reset). */
+    scripts?: readonly Script[];
+    /** Wait on the mock clock. Default: real time. */
+    sleep?: Sleep;
+};
+/**
+ * Stateful, scriptable mock of Amazon Bedrock Runtime (and the AgentCore harness).
+ *
+ * It never generates language: each model call is answered by the first script whose
+ * `match` accepts it and that has a turn for this point in the conversation, or by an
+ * unscripted default (counted as `unscripted`). Every answer can be rendered as a Converse
+ * body, a ConverseStream event stream, an Anthropic Messages body, a harness stream or a
+ * Nova Sonic session.
+ */
+declare class BedrockAPI implements FetchAPI$1 {
+    readonly app: Hono;
+    readonly sqlite: SqliteClient;
+    readonly state: BedrockState;
+    private readonly service;
+    private readonly now;
+    private readonly sleep;
+    constructor(options?: BedrockAPIOptions);
+    fetch(request: Request): Promise<Response>;
+    reset(): Promise<void>;
+    scripts(): Script[];
+    putScripts(scripts: readonly Script[], replace?: boolean): Script[];
+    removeScripts(id?: string): number;
+    stats(): ModelStats;
+    private requestId;
+    private planContext;
+    /**
+     * First script with a turn for this call, else the default (which `unscripted` may
+     * replace with an operation-specific one); records stats either way.
+     */
+    private resolve;
+    /** Journal notes: metadata only (never message or prompt text). */
+    private notes;
+    private jsonBody;
+    /** A pre-stream fault as the vendor's error, or `undefined` to carry on. */
+    private preStream;
+    private eventStream;
+    private converse;
+    private invokeModel;
+    private titan;
+    private invokeHarness;
+    /** The unscripted eRx prescreen answer: eligible for clinician review. */
+    private harnessDefault;
+    private bidirectional;
+}
+
+export { BEDROCK_NAMESPACE, BEDROCK_PRESETS, BedrockAPI, DEFAULT_CHAT_TEXT, DEFAULT_CLASSIFIER, DEFAULT_SETTINGS, DEFAULT_SOAP_NOTE, EventStreamError, FrameReader, GUARDRAIL_BLOCKED_TEXT, MODEL_OPERATIONS, STOP_REASONS, TURN_FAULTS, accessKeyCredential, bedrockError, clockSleep, crc32, createRuntime, decodeMessage, document, encodeMessage, eventFrame, exceptionFrame, operationIds, parseScript, readFrames, sampleSchema, supportedOperationIds, titanEmbedding, unwrapSigned };
+export type { BedrockAPIOptions, BedrockRuntime, BedrockRuntimeOptions, EventStreamMessage, FetchAPI$1 as FetchAPI, HeaderValue, MessageInput, ModelOperation, ModelStats, OperationId, Plan, PlanBlock, Script, ScriptMatch, ScriptToolUse, ScriptTurn, ScriptUsage, Settings, SqliteClient, StopReason, SupportedOperationId, TextMatch, TurnFault, TurnFaultType, Usage };