@yansigit/opencodex 2.31.0

package/src/lib/tool-argument-integers.ts

@@ -0,0 +1,202 @@
+// Schema-aware repair for tool arguments whose serialized representation disagrees
+// with the declared schema in a way that has exactly one faithful reading.
+//
+// Case 1 — integer fields arriving as integral floats (issue #1611).
+//
+// Grok serializes integer tool-call arguments through a float representation, so
+// `yield_time_ms: 120000` leaves the provider as `120000.0`. Codex declares those
+// fields as Rust integer types, so it rejects the call BEFORE running the tool:
+//
+//   failed to parse function arguments: invalid type: floating point `120000.0`, expected u64
+//
+// That is a hard failure, not a degradation — the model gets no result and retries
+// the same float. Nothing on the routed path reconciled argument values against the
+// declared schema, so the `.0` passed straight through.
+//
+// The boundary this file draws is INTENT, not convenience:
+//   - an integral float in an integer-typed field is a representation artifact, and
+//     `120000.0` has exactly one integer reading, so it is repaired;
+//   - `1.5` in an integer field is a genuine disagreement with the schema and is left
+//     alone so it still fails, rather than being truncated into a plausible lie.
+//
+// Case 2 — string fields arriving as bare integers (issue #1938).
+//
+// Cursor-served models emit `{"cell_id": 4}` where the schema declares
+// `{"type": "string"}`. Codex rejects the call before the tool runs (invalid type:
+// integer `4`, expected a string), and the model never self-corrects, so every such
+// call is a hard failure loop. A safely-integral JSON number in a string-declared
+// field has exactly one faithful string reading (`4` -> `"4"`), so it is repaired
+// under the same intent boundary:
+//   - only when the field declares `string` and no numeric type (a
+//     `["integer","string"]` union accepts the number as-is and is left alone);
+//   - a non-integral number (`4.5`) in a string field is a genuine disagreement and
+//     is left alone so it still fails;
+//   - beyond 2^53-1 the parsed value may differ from the serialized text, so the
+//     original bytes stay.
+//
+// Anything without a declared `integer`/`string` type is never touched.
+
+/** JSON Schema subset we need; provider tool schemas are untrusted input. */
+type SchemaNode = Record<string, unknown>;
+
+function asSchema(value: unknown): SchemaNode | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as SchemaNode
+    : undefined;
+}
+
+/** True when the node declares `integer`, including `["integer","null"]` unions. */
+function declaresInteger(schema: SchemaNode): boolean {
+  const type = schema.type;
+  if (type === "integer") return true;
+  return Array.isArray(type) && type.includes("integer");
+}
+
+/** True when the node declares `string`, including `["string","null"]` unions. */
+function declaresString(schema: SchemaNode): boolean {
+  const type = schema.type;
+  if (type === "string") return true;
+  return Array.isArray(type) && type.includes("string");
+}
+
+/** True when the node accepts a JSON number (`integer` or `number`), so a numeric
+ * value is already schema-valid and must not be rewritten into a string. */
+function declaresNumeric(schema: SchemaNode): boolean {
+  const type = schema.type;
+  if (type === "integer" || type === "number") return true;
+  return Array.isArray(type) && (type.includes("integer") || type.includes("number"));
+}
+
+/**
+ * Resolve a local `$ref` (`#/$defs/Foo`, `#/definitions/Foo`).
+ *
+ * Only same-document refs are followed: a remote ref is not fetchable here, and a
+ * schema we cannot resolve must leave its values untouched rather than guessed at.
+ */
+function resolveRef(schema: SchemaNode, root: SchemaNode, seen: Set<string>): SchemaNode | undefined {
+  const ref = schema.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/")) return schema;
+  if (seen.has(ref)) return undefined; // cyclic $ref: stop rather than recurse forever
+  seen.add(ref);
+  let node: unknown = root;
+  for (const rawSegment of ref.slice(2).split("/")) {
+    const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+    const current = asSchema(node);
+    if (!current) return undefined;
+    node = current[segment];
+  }
+  const resolved = asSchema(node);
+  return resolved ? resolveRef(resolved, root, seen) : undefined;
+}
+
+/** Composition keywords whose branches may carry the integer declaration. */
+const COMPOSITION_KEYS = ["anyOf", "oneOf", "allOf"] as const;
+
+function compositionBranches(schema: SchemaNode): SchemaNode[] {
+  const branches: SchemaNode[] = [];
+  for (const key of COMPOSITION_KEYS) {
+    const value = schema[key];
+    if (!Array.isArray(value)) continue;
+    for (const branch of value) {
+      const node = asSchema(branch);
+      if (node) branches.push(node);
+    }
+  }
+  return branches;
+}
+
+/**
+ * A JS number can only represent integers exactly up to 2^53-1. Beyond that a
+ * rewrite would emit a silently different value, so the original text stays.
+ */
+function safelyIntegral(value: number): boolean {
+  return Number.isInteger(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER;
+}
+
+interface CoerceResult {
+  value: unknown;
+  changed: boolean;
+}
+
+function coerceValue(value: unknown, schema: SchemaNode | undefined, root: SchemaNode, depth: number): CoerceResult {
+  // A hostile or deeply nested schema must not blow the stack.
+  if (depth > 64) return { value, changed: false };
+  const resolved = schema ? resolveRef(schema, root, new Set()) : undefined;
+
+  if (typeof value === "number") {
+    if (!resolved) return { value, changed: false };
+    const branches = compositionBranches(resolved);
+    const integerDeclared = declaresInteger(resolved) || branches.some(declaresInteger);
+    if (!integerDeclared && safelyIntegral(value)) {
+      // Issue #1938: a bare integer in a string-only field has exactly one faithful
+      // string reading. A field that also accepts a numeric type keeps the number.
+      const stringDeclared = declaresString(resolved) || branches.some(declaresString);
+      const numericDeclared = declaresNumeric(resolved) || branches.some(declaresNumeric);
+      if (stringDeclared && !numericDeclared) {
+        return { value: String(value), changed: true };
+      }
+    }
+    // Not an integer field, already an integer, non-integral, or unrepresentable:
+    // in every one of those cases the received value is the right thing to keep.
+    if (!integerDeclared || !safelyIntegral(value)) return { value, changed: false };
+    // `120000.0` and `120000` are the same JS number; the difference is only in the
+    // serialized text, which is repaired by re-stringifying the parsed value.
+    return { value, changed: true };
+  }
+
+  if (Array.isArray(value)) {
+    const itemSchema = resolved ? asSchema(resolved.items) : undefined;
+    let changed = false;
+    const next = value.map(entry => {
+      const result = coerceValue(entry, itemSchema, root, depth + 1);
+      if (result.changed) changed = true;
+      return result.value;
+    });
+    return changed ? { value: next, changed } : { value, changed: false };
+  }
+
+  const object = asSchema(value);
+  if (!object) return { value, changed: false };
+
+  const properties = resolved ? asSchema(resolved.properties) : undefined;
+  const additional = resolved ? asSchema(resolved.additionalProperties) : undefined;
+  let changed = false;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(object)) {
+    const childSchema = asSchema(properties?.[key]) ?? additional;
+    const result = coerceValue(entry, childSchema, root, depth + 1);
+    if (result.changed) changed = true;
+    next[key] = result.value;
+  }
+  return changed ? { value: next, changed } : { value, changed: false };
+}
+
+/**
+ * Repair integral floats in a tool-call arguments STRING against the tool's declared
+ * parameter schema.
+ *
+ * Returns the original string unchanged when there is no schema, the payload does not
+ * parse, or nothing needed repair — so an unaffected call keeps its exact bytes and
+ * this stays a no-op for every provider that already emits real integers.
+ */
+export function coerceIntegerToolArguments(
+  args: string,
+  parameters: Record<string, unknown> | undefined,
+): string {
+  if (!parameters || !args) return args;
+  // Cheap reject: a payload with no digit cannot need either repair (integral-float
+  // -> integer, or bare-integer -> string).
+  if (!/\d/.test(args)) return args;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(args);
+  } catch {
+    // Malformed or still-streaming arguments are not this function's problem; the
+    // existing paths already handle them.
+    return args;
+  }
+  const root = parameters as SchemaNode;
+  const result = coerceValue(parsed, root, root, 0);
+  if (!result.changed) return args;
+  return JSON.stringify(result.value);
+}

package/src/lib/translator-budget.ts

@@ -0,0 +1,400 @@
+export const TRANSLATOR_MAX_CALL_ARGUMENT_BYTES = 2 * 1024 * 1024;
+export const TRANSLATOR_MAX_TURN_BYTES = 32 * 1024 * 1024;
+export const TRANSLATOR_MAX_SSE_EVENT_BYTES = 32 * 1024 * 1024;
+export const CURSOR_MAX_CONNECT_FRAME_BYTES = 32 * 1024 * 1024;
+export const CURSOR_MAX_EFFECTIVE_CONNECT_PAYLOAD_BYTES = 16 * 1024 * 1024;
+export const CURSOR_TRANSPORT_MAX_BUFFERED_BYTES = 32 * 1024 * 1024;
+export const CURSOR_TRANSPORT_RESUME_BYTES = 16 * 1024 * 1024;
+export const CURSOR_MAX_PENDING_FRAMES = 1024;
+export const CURSOR_PENDING_FRAMES_RESUME = 512;
+export const MAX_PENDING_IMAGE_FULFILLMENTS = 64;
+export const MAX_PENDING_OAUTH_MUTATIONS = 128;
+
+export type TranslatorBufferKind =
+  | "tool_args"
+  | "retained_collectors"
+  | "live_transient"
+  | "reasoning"
+  | "item_ids"
+  | "tool_search_sources"
+  | "cursor_transport"
+  | "cursor_kv"
+  | "request_copies";
+
+export type ExternallyCappedKind = "passthrough_serialization" | "mcp_payload";
+
+export class TranslatorBudgetExceededError extends Error {
+  readonly code = "translation_buffer_limit";
+
+  constructor(readonly kind: TranslatorBufferKind, readonly limitBytes: number) {
+    super(`translator ${kind} buffer exceeded ${limitBytes} bytes`);
+    this.name = "TranslatorBudgetExceededError";
+  }
+}
+
+export function isTranslatorBudgetExceededError(error: unknown): error is TranslatorBudgetExceededError {
+  return error instanceof TranslatorBudgetExceededError
+    || (error instanceof Error && (error as { code?: unknown }).code === "translation_buffer_limit");
+}
+
+export interface TranslatorBudgetSnapshot {
+  currentBytes: number;
+  highWaterBytes: number;
+  activeCalls: number;
+  overflows: number;
+}
+
+export interface TranslatorBudgetOptions {
+  maxCallArgumentBytes?: number;
+  maxTurnBytes?: number;
+}
+
+export interface TranslatorTransientReservation {
+  commitRetained(): void;
+  release(): void;
+}
+
+export interface TranslatorBudget {
+  openCall(id: string): void;
+  closeCall(id: string): void;
+  reserveTransient(
+    bytes: number,
+    scope: { kind: TranslatorBufferKind; callId?: string },
+  ): TranslatorTransientReservation;
+  chargeRetained(delta: number, scope: { kind: TranslatorBufferKind; callId?: string }): void;
+  releaseRetained(bytes: number, scope: { kind: TranslatorBufferKind; callId?: string }): void;
+  observeAcceptedRequestCopy(bytes: number): () => void;
+  observeExternallyCapped(kind: ExternallyCappedKind, bytes: number): () => void;
+  snapshot(): TranslatorBudgetSnapshot;
+  dispose(): void;
+}
+
+const retainedEventOwnership = new WeakMap<object, { budget: TranslatorBudget; bytes: number }>();
+
+/**
+ * Charge one event appended to an incrementally materialized adapter-event batch.
+ * The newest event owns the closing array bracket; moving that byte from the old
+ * tail keeps in-order release accounting equal to the still-retained JSON array.
+ */
+export function retainTranslatedEvent<T extends object>(
+  event: T,
+  budget: TranslatorBudget,
+  previousTail?: object,
+): void {
+  if (retainedEventOwnership.has(event)) {
+    throw new Error("translated event is already retained");
+  }
+  if (previousTail === event) {
+    throw new Error("incremental translated event tail must be a distinct object");
+  }
+  const previousOwnership = previousTail === undefined
+    ? undefined
+    : retainedEventOwnership.get(previousTail);
+  if (
+    previousTail !== undefined
+    && (!previousOwnership || previousOwnership.budget !== budget || previousOwnership.bytes < 2)
+  ) {
+    throw new Error("incremental translated event tail is not retained by this budget");
+  }
+
+  const serializedBytes = Buffer.byteLength(JSON.stringify(event));
+  budget.chargeRetained(serializedBytes + (previousTail === undefined ? 2 : 1), {
+    kind: "retained_collectors",
+  });
+  if (previousOwnership) previousOwnership.bytes -= 1;
+  retainedEventOwnership.set(event, { budget, bytes: serializedBytes + 2 });
+}
+
+/**
+ * Charge a materialized adapter-event batch and attach its lease to the events themselves.
+ * A copied event array (for example terminal-guard collection) preserves the event objects, so
+ * the response builder can consume each source lease immediately after its replacement lands.
+ */
+export function retainTranslatedEventBatch<T extends object>(events: T[], budget: TranslatorBudget): void {
+  if (events.length === 0) return;
+  const serialized = events.map(event => JSON.stringify(event));
+  const totalBytes = Buffer.byteLength(`[${serialized.join(",")}]`);
+  budget.chargeRetained(totalBytes, { kind: "retained_collectors" });
+  for (let index = 0; index < events.length; index++) {
+    const delimiterBytes = index === events.length - 1 ? 2 : 1;
+    retainedEventOwnership.set(events[index]!, {
+      budget,
+      bytes: Buffer.byteLength(serialized[index]!) + delimiterBytes,
+    });
+  }
+}
+
+/** Transfer one charged adapter event to the response builder's newly materialized owner. */
+export function releaseTranslatedEvent(event: object, budget: TranslatorBudget): void {
+  const ownership = retainedEventOwnership.get(event);
+  if (!ownership || ownership.budget !== budget) return;
+  retainedEventOwnership.delete(event);
+  budget.releaseRetained(ownership.bytes, { kind: "retained_collectors" });
+}
+
+const liveBudgets = new Set<Budget>();
+let aggregateCurrentBytes = 0;
+let aggregateActiveCalls = 0;
+let aggregateHighWaterBytes = 0;
+let aggregateOverflows = 0;
+
+function normalizeBytes(bytes: number): number {
+  return Number.isFinite(bytes) && bytes > 0 ? Math.floor(bytes) : 0;
+}
+
+function observeAggregate(): void {
+  aggregateHighWaterBytes = Math.max(aggregateHighWaterBytes, aggregateCurrentBytes);
+}
+
+class Budget implements TranslatorBudget {
+  private readonly calls = new Map<string, { logicalBytes: number; physicalBytes: number }>();
+  private readonly charged = new Map<TranslatorBufferKind, number>();
+  private hardChargedBytes = 0;
+  private observedBytes = 0;
+  private currentBytes = 0;
+  private highWaterBytes = 0;
+  private overflowCount = 0;
+  private disposed = false;
+
+  constructor(
+    private readonly maxCallArgumentBytes: number,
+    private readonly maxTurnBytes: number,
+  ) {}
+
+  private chargedBytes(): number {
+    return this.hardChargedBytes;
+  }
+
+  observedCurrentBytes(): number {
+    return this.currentBytes;
+  }
+
+  private changed(): void {
+    const nextBytes = this.hardChargedBytes + this.observedBytes;
+    aggregateCurrentBytes += nextBytes - this.currentBytes;
+    this.currentBytes = nextBytes;
+    this.highWaterBytes = Math.max(this.highWaterBytes, nextBytes);
+    observeAggregate();
+  }
+
+  private reject(kind: TranslatorBufferKind, limitBytes: number): never {
+    this.overflowCount += 1;
+    aggregateOverflows += 1;
+    throw new TranslatorBudgetExceededError(kind, limitBytes);
+  }
+
+  private admit(kind: TranslatorBufferKind, bytes: number): number {
+    const admitted = normalizeBytes(bytes);
+    if (this.chargedBytes() + admitted > this.maxTurnBytes) this.reject(kind, this.maxTurnBytes);
+    return admitted;
+  }
+
+  openCall(id: string): void {
+    if (!this.calls.has(id)) {
+      this.calls.set(id, { logicalBytes: 0, physicalBytes: 0 });
+      aggregateActiveCalls += 1;
+    }
+  }
+
+  closeCall(id: string): void {
+    const call = this.calls.get(id);
+    if (!call) return;
+    this.hardChargedBytes = Math.max(0, this.hardChargedBytes - call.physicalBytes);
+    this.calls.delete(id);
+    aggregateActiveCalls = Math.max(0, aggregateActiveCalls - 1);
+    this.changed();
+  }
+
+  reserveTransient(
+    bytes: number,
+    scope: { kind: TranslatorBufferKind; callId?: string },
+  ): TranslatorTransientReservation {
+    const admitted = normalizeBytes(bytes);
+    if (scope.callId && admitted > this.maxCallArgumentBytes) {
+      this.reject("tool_args", this.maxCallArgumentBytes);
+    }
+    this.admit(scope.kind, admitted);
+    this.charged.set(scope.kind, (this.charged.get(scope.kind) ?? 0) + admitted);
+    this.hardChargedBytes += admitted;
+    this.changed();
+    let state: "reserved" | "committed" | "released" = "reserved";
+    return {
+      commitRetained: () => {
+        if (state !== "reserved") return;
+        state = "committed";
+        if (!scope.callId) return;
+        const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
+        this.charged.set(scope.kind, Math.max(0, (this.charged.get(scope.kind) ?? 0) - admitted));
+        call.logicalBytes = admitted;
+        call.physicalBytes += admitted;
+        this.calls.set(scope.callId, call);
+        this.changed();
+      },
+      release: () => {
+        if (state !== "reserved") return;
+        state = "released";
+        this.charged.set(scope.kind, Math.max(0, (this.charged.get(scope.kind) ?? 0) - admitted));
+        this.hardChargedBytes = Math.max(0, this.hardChargedBytes - admitted);
+        this.changed();
+      },
+    };
+  }
+
+  chargeRetained(delta: number, scope: { kind: TranslatorBufferKind; callId?: string }): void {
+    const admitted = normalizeBytes(delta);
+    if (scope.callId) {
+      const call = this.calls.get(scope.callId) ?? { logicalBytes: 0, physicalBytes: 0 };
+      if (call.logicalBytes + admitted > this.maxCallArgumentBytes) {
+        this.reject("tool_args", this.maxCallArgumentBytes);
+      }
+      this.admit(scope.kind, admitted);
+      call.logicalBytes += admitted;
+      call.physicalBytes += admitted;
+      this.calls.set(scope.callId, call);
+    } else {
+      this.admit(scope.kind, admitted);
+      this.charged.set(scope.kind, (this.charged.get(scope.kind) ?? 0) + admitted);
+    }
+    this.hardChargedBytes += admitted;
+    this.changed();
+  }
+
+  releaseRetained(bytes: number, scope: { kind: TranslatorBufferKind; callId?: string }): void {
+    const released = normalizeBytes(bytes);
+    if (scope.callId) {
+      const call = this.calls.get(scope.callId);
+      if (call) {
+        const actual = Math.min(released, call.physicalBytes);
+        call.physicalBytes -= actual;
+        this.hardChargedBytes = Math.max(0, this.hardChargedBytes - actual);
+      }
+    } else {
+      const current = this.charged.get(scope.kind) ?? 0;
+      const actual = Math.min(released, current);
+      this.charged.set(scope.kind, current - actual);
+      this.hardChargedBytes = Math.max(0, this.hardChargedBytes - actual);
+    }
+    this.changed();
+  }
+
+  private observe(bytes: number): () => void {
+    const observed = normalizeBytes(bytes);
+    this.observedBytes += observed;
+    this.changed();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.observedBytes = Math.max(0, this.observedBytes - observed);
+      this.changed();
+    };
+  }
+
+  observeAcceptedRequestCopy(bytes: number): () => void {
+    return this.observe(bytes);
+  }
+
+  observeExternallyCapped(_kind: ExternallyCappedKind, bytes: number): () => void {
+    return this.observe(bytes);
+  }
+
+  snapshot(): TranslatorBudgetSnapshot {
+    return {
+      currentBytes: this.observedCurrentBytes(),
+      highWaterBytes: this.highWaterBytes,
+      activeCalls: this.calls.size,
+      overflows: this.overflowCount,
+    };
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    aggregateActiveCalls = Math.max(0, aggregateActiveCalls - this.calls.size);
+    aggregateCurrentBytes = Math.max(0, aggregateCurrentBytes - this.currentBytes);
+    this.calls.clear();
+    this.charged.clear();
+    this.hardChargedBytes = 0;
+    this.observedBytes = 0;
+    this.currentBytes = 0;
+    liveBudgets.delete(this);
+    observeAggregate();
+  }
+}
+
+export function createTranslatorBudget(options: TranslatorBudgetOptions = {}): TranslatorBudget {
+  const budget = new Budget(
+    options.maxCallArgumentBytes ?? TRANSLATOR_MAX_CALL_ARGUMENT_BYTES,
+    options.maxTurnBytes ?? TRANSLATOR_MAX_TURN_BYTES,
+  );
+  liveBudgets.add(budget);
+  observeAggregate();
+  return budget;
+}
+
+export function translatorObservedBufferSnapshot(): {
+  currentBytes: number;
+  highWaterBytes: number;
+  active: number;
+} {
+  return {
+    currentBytes: aggregateCurrentBytes,
+    highWaterBytes: aggregateHighWaterBytes,
+    active: aggregateActiveCalls,
+  };
+}
+
+/** Internal diagnostics used by focused tests; never registered with app-owned memory. */
+export function translatorObservedOverflowCount(): number {
+  return aggregateOverflows;
+}
+
+/** Test-only: proves owned default budgets are disposed on every stream-death path. */
+export function translatorLiveBudgetCountForTests(): number {
+  return liveBudgets.size;
+}
+
+/** Test-only: proves no charge survives against a disposed budget (cancel race). */
+export function translatorAggregateCurrentBytesForTests(): number {
+  return aggregateCurrentBytes;
+}
+
+/** Clears process-wide translator diagnostics and disposes leaked test budgets. */
+export function resetTranslatorAggregateForTests(): void {
+  for (const budget of liveBudgets) budget.dispose();
+  aggregateCurrentBytes = 0;
+  aggregateActiveCalls = 0;
+  aggregateHighWaterBytes = 0;
+  aggregateOverflows = 0;
+}
+
+export function finalizeTranslatorBudgetResponse(response: Response, budget: TranslatorBudget): Response {
+  if (!response.body) {
+    budget.dispose();
+    return response;
+  }
+  const reader = response.body.getReader();
+  let finalized = false;
+  const finalize = () => {
+    if (finalized) return;
+    finalized = true;
+    budget.dispose();
+  };
+  return new Response(new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          finalize();
+          controller.close();
+        } else controller.enqueue(result.value);
+      } catch (error) {
+        finalize();
+        controller.error(error);
+      }
+    },
+    async cancel(reason) {
+      try { await reader.cancel(reason); } finally { finalize(); }
+    },
+  }), { status: response.status, statusText: response.statusText, headers: response.headers });
+}

package/src/lib/upstream-http-version.ts

@@ -0,0 +1,57 @@
+import type { OcxProviderConfig, UpstreamHttpVersion } from "../types";
+
+/** True when a provider explicitly selected the HTTP/1.1 compatibility path. */
+export function isPinnedHttp1(version: UpstreamHttpVersion | undefined): boolean {
+  return version === "http1.1" || version === "h1";
+}
+
+/**
+ * Bun's fetch accepts a non-standard `protocol` init to pin the HTTP version
+ * (BunFetchRequestInit.protocol). The DOM lib types do not include it, so the
+ * value is represented through a RequestInit cast at this shared boundary.
+ */
+const UPSTREAM_HTTP_VERSION_PROTOCOL: Record<Exclude<UpstreamHttpVersion, "auto">, string> = {
+  "http1.1": "http1.1",
+  h1: "h1",
+  http2: "http2",
+  h2: "h2",
+};
+
+/** Raised before I/O when a fixed Bun HTTP-version pin cannot apply to the target URL. */
+export class UpstreamHttpVersionTargetError extends Error {
+  readonly code = "upstream_http_version_target";
+
+  constructor(readonly observedProtocol: string) {
+    super(`upstream HTTP version pin requires an HTTPS target (received ${observedProtocol})`);
+    this.name = "UpstreamHttpVersionTargetError";
+  }
+}
+
+/** Attach Bun's `protocol` pin for one explicit version value. */
+export function withUpstreamHttpVersionValue(
+  input: Parameters<typeof globalThis.fetch>[0],
+  init: RequestInit | undefined,
+  version: UpstreamHttpVersion | undefined,
+): RequestInit | undefined {
+  if (!version || version === "auto") return init;
+  // Bun's protocol pin requires an https: target. An explicit fixed-version request must fail
+  // locally when the pin cannot be honored instead of silently negotiating another transport.
+  const target = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+  let targetUrl: URL;
+  try {
+    targetUrl = new URL(target);
+  } catch {
+    throw new UpstreamHttpVersionTargetError("unparseable");
+  }
+  if (targetUrl.protocol !== "https:") throw new UpstreamHttpVersionTargetError(targetUrl.protocol);
+  return { ...(init ?? {}), protocol: UPSTREAM_HTTP_VERSION_PROTOCOL[version] } as RequestInit;
+}
+
+/** Attach Bun's `protocol` pin when the provider opted into a fixed HTTP version. */
+export function withUpstreamHttpVersion(
+  input: Parameters<typeof globalThis.fetch>[0],
+  init: RequestInit | undefined,
+  provider: Pick<OcxProviderConfig, "upstreamHttpVersion">,
+): RequestInit | undefined {
+  return withUpstreamHttpVersionValue(input, init, provider.upstreamHttpVersion);
+}