@yanlinglabs/winter-provider-conformance 0.0.2

package/dist/fakes/server.d.ts

@@ -0,0 +1,143 @@
+/** One request the fake received, recorded BEFORE any route ran. */
+export interface RecordedRequest {
+    method: string;
+    /** Path only -- the host is always `127.0.0.1:<ephemeral>` and would make an assertion port-dependent. */
+    path: string;
+    /** The full URL search string, so a test can assert on query parameters (`api-version`, `key`, …) without re-parsing. */
+    search: string;
+    /** REDACTED: an `authorization`/`x-api-key`/`api-key` value is replaced with its scheme plus `***`. */
+    headers: Record<string, string>;
+    /** The raw body text, or `""`. Bodies are NOT redacted: an adapter's own request body is what a serialization assertion is about, and it never carries a credential (every credential rides a header). */
+    body: string;
+}
+export interface FakeRoute {
+    /** Matched against the request PATH exactly, or as a prefix when it ends in `*`. */
+    path: string;
+    method?: string;
+    handler: (req: Request, recorded: RecordedRequest) => Response | Promise<Response>;
+}
+export interface FakeServer {
+    /** `http://127.0.0.1:<port>` -- what a `ConnectionProfile.baseUrl` points at. */
+    url: string;
+    /** Every request received, in order. The ground truth. */
+    requests: RecordedRequest[];
+    close(): Promise<void>;
+}
+export interface StartFakeOptions {
+    routes: FakeRoute[];
+    /**
+     * Answers any path no route matched. Defaults to a 404 whose body names the path -- an explicit
+     * failure a test can assert on, rather than a hang or a confusing connection reset.
+     */
+    fallback?: (req: Request, recorded: RecordedRequest) => Response | Promise<Response>;
+    /** How long `close()` waits before reporting the server would not stop. Default 2000 ms. */
+    closeDeadlineMs?: number;
+}
+/**
+ * Starts a loopback fake.
+ *
+ * ALWAYS close it in a `finally`. A leaked fake keeps a port and an event loop alive for the rest of
+ * the process, which is how one careless test makes an unrelated one flaky.
+ */
+export declare function startFake(opts: StartFakeOptions): Promise<FakeServer>;
+/** Runs `fn` against a fake and ALWAYS closes it. The shape every lane's fixture should use, so a leaked fake is not something anyone has to remember. */
+export declare function withFake<T>(opts: StartFakeOptions, fn: (fake: FakeServer) => Promise<T>): Promise<T>;
+/** One server-sent event as a family fake scripts it. `event` is omitted for a data-only frame. */
+export interface SseFrame {
+    event?: string;
+    data: string;
+    /** Milliseconds to wait BEFORE writing this frame -- the primitive behind the slow-stream scenario. */
+    delayMs?: number;
+}
+export interface SseResponseOptions {
+    status?: number;
+    headers?: Record<string, string>;
+    /**
+     * END the stream after `dropAfter` frames, WITHOUT the family's terminating event.
+     *
+     * The mid-stream-drop primitive, and its exact meaning is worth stating because a weaker reading
+     * would make it useless. What an SSE adapter can actually observe is "the byte stream ended before
+     * the terminator arrived" -- that is the failure a dropped upstream connection produces, and it is
+     * what this reproduces. What it deliberately does NOT do is call `controller.error()`: measured
+     * against Bun's own client, an errored server-side stream is indistinguishable from a truncated one
+     * (`res.text()` returns the frames written so far and does not throw) while ALSO surfacing an
+     * unhandled error that fails the runner for the wrong reason. So the primitive gives the honest,
+     * observable half, and a scenario asserts on the absent terminator rather than on an exception.
+     */
+    dropAfter?: number;
+}
+/**
+ * An SSE response from a scripted frame list.
+ *
+ * FINITE BY CONSTRUCTION, and Task 2 recorded why that matters: an infinitely-pulling loopback fake
+ * hangs the RUNNER rather than failing the test, because its own event loop keeps pumping into a
+ * torn-down connection. Every stream this helper produces ends -- by running out of frames, or by
+ * the deliberate drop.
+ */
+export declare function sseResponse(frames: SseFrame[], opts?: SseResponseOptions): Response;
+/** A JSON response. */
+export declare function jsonResponse(value: unknown, status?: number, headers?: Record<string, string>): Response;
+/** An error status WITH headers -- the shape a `Retry-After` / `anthropic-ratelimit-*` / `x-ratelimit-*` scenario needs. */
+export declare function errorResponse(status: number, body: unknown, headers?: Record<string, string>): Response;
+/**
+ * A redirect, for the endpoint-policy scenarios.
+ *
+ * `absolute` is what makes a CROSS-ORIGIN redirect expressible: the policy's own rule is that
+ * credentials are never forwarded across an origin change and a redirect carrying a request BODY is
+ * refused outright, and neither can be exercised with a same-origin relative `Location`.
+ */
+export declare function redirectResponse(location: string, status?: 301 | 302 | 307 | 308): Response;
+/**
+ * A response that never finishes writing, for the STALL scenario.
+ *
+ * Bounded by `holdMs` so it cannot outlive the test that started it, whatever the client does. The
+ * stall watchdog under test fires long before this does; the bound exists so a BROKEN watchdog fails
+ * the test on a timeout it can explain rather than hanging the runner.
+ *
+ * THE TIMER IS CANCELLED WHEN THE CONSUMER TEARS THE STREAM DOWN, and the reason is worth stating
+ * because getting it wrong was a cross-lane defect rather than a local one. A stall scenario ONLY
+ * ever ends by the consumer cancelling -- the watchdog fires long before `holdMs` by construction --
+ * so the "consumer cancelled first" path is the NORMAL path here, not an edge case. An unconditional
+ * `setTimeout(() => controller.close())` then fired against an already-closed controller and threw
+ * `TypeError: Invalid state: Controller is already closed` from a bare timer callback, which Bun
+ * attributes to WHICHEVER TEST HAPPENS TO BE RUNNING when it lands. It took down this package's own
+ * `corpus/runner.test.ts` and unrelated adapter cases in two separate lanes, purely by timing.
+ *
+ * Belt AND braces, deliberately: `cancel()` clears the timer, and the flag guards the close anyway --
+ * a stream can also be errored or closed by a path that never calls `cancel()`, and this helper is
+ * frozen spine that six lanes build on.
+ */
+export declare function stalledResponse(holdMs?: number): Response;
+/** One scripted answer, keyed by the MODEL ID the request asked for. */
+export type ScenarioResponder = (recorded: RecordedRequest, attempt: number) => Response | Promise<Response>;
+export interface ScenarioTableOptions {
+    /**
+     * Reads the model id out of a request. Family-specific -- OpenAI Responses and Anthropic Messages
+     * both put it in the JSON body, Gemini puts it in the PATH -- so each lane supplies its own rather
+     * than this base guessing.
+     */
+    modelOf: (recorded: RecordedRequest) => string | undefined;
+    /** modelId -> the scripted answer. A responder receives the 1-based ATTEMPT count for that model, so a retry scenario is a single entry rather than a stateful closure per test. */
+    scenarios: Record<string, ScenarioResponder | Response[]>;
+    /** Answers a model id with no entry. Defaults to a 400 naming the id -- a loud, assertable failure. */
+    unknownModel?: ScenarioResponder;
+}
+/**
+ * Builds a route handler from a MODEL-KEYED table.
+ *
+ * Keying on the model id is what lets one fake serve a whole corpus: a scenario picks its behaviour
+ * by asking for `"stall-model"` or `"retry-then-200"` instead of every case needing its own server,
+ * its own port and its own teardown. The ATTEMPT counter is per model, so "529 then 200" is one
+ * two-element array rather than a closure a test has to reset.
+ */
+export declare function scenarioTable(opts: ScenarioTableOptions): (req: Request, recorded: RecordedRequest) => Response | Promise<Response>;
+/** The requests whose path matches, for an assertion that does not want to count a health probe. */
+export declare function requestsTo(fake: FakeServer, path: string): RecordedRequest[];
+/**
+ * True when NO request the fake received carries `needle` anywhere -- headers or body.
+ *
+ * The negative every hermeticity and opacity assertion needs: "the marker appeared in no request
+ * body" is exactly how capture (H) proved the sidecar was never sent to a model, and the same shape
+ * proves an adapter never replayed opaque state across a domain.
+ */
+export declare function noRequestContains(fake: FakeServer, needle: string): boolean;

package/dist/fakes/vertex.d.ts

@@ -0,0 +1,60 @@
+import { type FakeRoute, type RecordedRequest } from "./server.js";
+import { type GeminiFakeOptions } from "./gemini.js";
+/** A keypair for one test run. NEVER committed: this generates a fresh one every call. */
+export declare function generateTestKeyPair(): Promise<{
+    privateKeyPem: string;
+    publicKey: CryptoKey;
+}>;
+/** One assertion the token endpoint verified, recorded so a test can assert on its claims. */
+export interface VerifiedAssertion {
+    header: Record<string, unknown>;
+    claims: Record<string, unknown>;
+}
+export interface VertexFakeOptions extends GeminiFakeOptions {
+    /** The public half of the in-test keypair. The token route verifies every assertion against it. */
+    publicKey: CryptoKey;
+    project: string;
+    location: string;
+    /** The `aud` every assertion must carry -- the fake's own token URL. */
+    tokenUri: string;
+    /** Filled in as assertions are verified. The evidence a claim assertion reads. */
+    verified: VerifiedAssertion[];
+    /** The access token the exchange mints. Distinctive so a "never logged" negative is meaningful. */
+    accessToken?: string;
+    /** `expires_in`, in seconds. `0` scripts a token that is already expired, for the cache fixture. */
+    expiresIn?: number;
+    /** Rejects every exchange, for the credential-failure fixture. */
+    rejectExchange?: boolean;
+}
+/** The default access token. `test-...` by the lane's own rule; distinctive so `noRequestContains` means something. */
+export declare const VERTEX_TEST_ACCESS_TOKEN = "test-vertex-access-token-1";
+/** The token URL a fixture points a service-account JSON's `token_uri` at. */
+export declare function vertexTokenUrl(fakeUrl: string): string;
+/**
+ * The Vertex routes: the token endpoint plus the location-scoped model paths.
+ *
+ * The model path is prefix-matched under `/v1/projects/...` because the model id and the method are
+ * both IN the path. `assertVertexPath` is what checks it is the exact shape ruling R6-A names.
+ *
+ * IT APPLIES THE GEMINI FAKE'S OWN BODY VALIDATORS (Lane B r4 carry). This route duplicated the
+ * model path and validated NOTHING, so the two merge pins and the round-3 decoration pin on this
+ * transport bit only via direct `roles`/`parts` assertions — a wire shape Vertex would reject was
+ * invisible here while the identical shape 400'd on the Gemini route. The adapters share one wire
+ * mapping; the fakes now share the invariants that mapping has to satisfy.
+ */
+export declare function vertexFakeRoutes(opts: VertexFakeOptions): FakeRoute[];
+/**
+ * Asserts the request landed on the EXACT location-endpoint path ruling R6-A names, and carried a
+ * bearer token rather than an api key.
+ *
+ * The authorization value is checked in its REDACTED form -- the base replaces a credential header's
+ * material as it records, so `Bearer ***` proves both that the adapter authenticated and that the
+ * redaction ran.
+ */
+export declare function assertVertexRequest(recorded: RecordedRequest, expected: {
+    project: string;
+    location: string;
+    model: string;
+    method?: string;
+    search?: string;
+}): void;

package/dist/fakes/xai-oauth.d.ts

@@ -0,0 +1,2 @@
+export { startXaiOauthFake } from "@yanlinglabs/winter-provider-runtime/testing";
+export type { XaiOauthFake, XaiOauthFakeOptions, XaiRecordedRequest } from "@yanlinglabs/winter-provider-runtime/testing";