@kuralle-syrinx/core 2.1.0

package/src/audio-envelope.test.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import {
+  SYRINX_AUDIO_ENVELOPE_MAGIC,
+  assertAudioFormat,
+  assertAudioPayload,
+  decodeSyrinxAudioEnvelope,
+  encodeSyrinxAudioEnvelope,
+  hasSyrinxAudioEnvelope,
+} from "./audio-envelope.js";
+import type { SyrinxAudioEnvelopeHeader } from "./audio-envelope.js";
+import type { AudioFormat } from "./packets.js";
+
+describe("Syrinx binary audio envelope", () => {
+  it("round-trips audio metadata and payload", () => {
+    const encoded = encodeSyrinxAudioEnvelope({
+      type: "audio",
+      contextId: "turn-1",
+      sampleRateHz: 16000,
+      sequence: 3,
+      encoding: "pcm_s16le",
+      channels: 1,
+      byteLength: 4,
+      durationMs: 1,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(hasSyrinxAudioEnvelope(encoded)).toBe(true);
+    expect(decodeSyrinxAudioEnvelope(encoded)).toEqual({
+      header: {
+        type: "audio",
+        contextId: "turn-1",
+        sampleRateHz: 16000,
+        sequence: 3,
+        encoding: "pcm_s16le",
+        channels: 1,
+        byteLength: 4,
+        durationMs: 1,
+      },
+      audio: new Uint8Array([1, 2, 3, 4]),
+    });
+  });
+
+  it("rejects envelopes whose declared byte length does not match the payload", () => {
+    const encoded = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 5,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(() => decodeSyrinxAudioEnvelope(encoded)).toThrow(/byteLength/);
+  });
+
+  it("rejects odd-byte PCM16 payloads and inconsistent duration metadata", () => {
+    const oddPayload = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 3,
+    }, new Uint8Array([1, 2, 3]));
+    const wrongDuration = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 640,
+      durationMs: 200,
+    }, new Uint8Array(640));
+
+    expect(() => decodeSyrinxAudioEnvelope(oddPayload)).toThrow(/PCM16/);
+    expect(() => decodeSyrinxAudioEnvelope(wrongDuration)).toThrow(/durationMs/);
+  });
+
+  it("rejects envelopes without a valid sample rate", () => {
+    const missingSampleRate = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+    const invalidSampleRate = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 0,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(() => decodeSyrinxAudioEnvelope(missingSampleRate)).toThrow(/sampleRateHz/);
+    expect(() => decodeSyrinxAudioEnvelope(invalidSampleRate)).toThrow(/sampleRateHz/);
+  });
+
+  it("rejects malformed numeric metadata instead of silently defaulting", () => {
+    const invalidSequence = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      sequence: -1,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+    const invalidDuration = encodeMalformedSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      durationMs: 1.5,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]));
+
+    expect(() => decodeSyrinxAudioEnvelope(invalidSequence)).toThrow(/sequence/);
+    expect(() => decodeSyrinxAudioEnvelope(invalidDuration)).toThrow(/durationMs/);
+  });
+
+  it("round-trips opus-encoded envelopes without PCM16 byte alignment", () => {
+    const encoded = encodeSyrinxAudioEnvelope({
+      type: "audio",
+      contextId: "turn-opus",
+      sampleRateHz: 16000,
+      sequence: 1,
+      encoding: "opus",
+      channels: 1,
+      byteLength: 37,
+      durationMs: 20,
+    }, new Uint8Array(37));
+
+    expect(decodeSyrinxAudioEnvelope(encoded).header.encoding).toBe("opus");
+  });
+
+  it("assertAudioPayload rejects odd-byte PCM16 and empty opus/mulaw", () => {
+    const pcmFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 16000, channels: 1 };
+    expect(() => assertAudioPayload(pcmFormat, new Uint8Array([1, 2, 3]))).toThrow(/even number of bytes/);
+    expect(() => assertAudioPayload(pcmFormat, new Uint8Array())).not.toThrow();
+
+    const opusFormat: AudioFormat = { encoding: "opus", sampleRateHz: 16000, channels: 1 };
+    expect(() => assertAudioPayload(opusFormat, new Uint8Array())).toThrow(/must not be empty/);
+    expect(() => assertAudioPayload(opusFormat, new Uint8Array([1]))).not.toThrow();
+
+    const mulawFormat: AudioFormat = { encoding: "mulaw", sampleRateHz: 8000, channels: 1 };
+    expect(() => assertAudioPayload(mulawFormat, new Uint8Array())).toThrow(/must not be empty/);
+    expect(() => assertAudioPayload(mulawFormat, new Uint8Array([1, 2, 3]))).not.toThrow();
+  });
+
+  it("assertAudioFormat rejects non-mono and invalid sample rates", () => {
+    expect(() => assertAudioFormat({ encoding: "pcm_s16le", sampleRateHz: 16000, channels: 2 as 1 })).toThrow(/mono/);
+    expect(() => assertAudioFormat({ encoding: "pcm_s16le", sampleRateHz: 0, channels: 1 })).toThrow(/sampleRateHz/);
+    expect(() => assertAudioFormat({ encoding: "pcm_s16le", sampleRateHz: 1.5, channels: 1 })).toThrow(/sampleRateHz/);
+  });
+
+  it("rejects invalid envelopes before encoding them", () => {
+    expect(() => encodeSyrinxAudioEnvelope({
+      type: "audio",
+      byteLength: 4,
+    } as SyrinxAudioEnvelopeHeader, new Uint8Array([1, 2, 3, 4]))).toThrow(/sampleRateHz/);
+    expect(() => encodeSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      sequence: -1,
+      byteLength: 4,
+    }, new Uint8Array([1, 2, 3, 4]))).toThrow(/sequence/);
+    expect(() => encodeSyrinxAudioEnvelope({
+      type: "audio",
+      sampleRateHz: 16000,
+      byteLength: 5,
+    }, new Uint8Array([1, 2, 3, 4]))).toThrow(/byteLength/);
+  });
+});
+
+function encodeMalformedSyrinxAudioEnvelope(header: Record<string, unknown>, audio: Uint8Array): Uint8Array {
+  const headerBytes = new TextEncoder().encode(JSON.stringify(header));
+  const output = new Uint8Array(SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4 + headerBytes.byteLength + audio.byteLength);
+  output.set(SYRINX_AUDIO_ENVELOPE_MAGIC, 0);
+  new DataView(output.buffer, output.byteOffset, output.byteLength)
+    .setUint32(SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength, headerBytes.byteLength, true);
+  output.set(headerBytes, SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4);
+  output.set(audio, SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4 + headerBytes.byteLength);
+  return output;
+}

package/src/audio-envelope.ts

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+
+import type { AudioFormat } from "./packets.js";
+
+export const SYRINX_AUDIO_ENVELOPE_NAME = "syrinx.audio.v1" as const;
+export const SYRINX_AUDIO_ENVELOPE_MAGIC = new Uint8Array([83, 89, 82, 88, 65, 49, 10]);
+
+export interface SyrinxAudioEnvelopeHeader {
+  readonly type: "audio";
+  readonly contextId?: string;
+  readonly sampleRateHz: number;
+  readonly sequence?: number;
+  readonly encoding?: "pcm_s16le" | "opus";
+  readonly channels?: 1;
+  readonly byteLength?: number;
+  readonly durationMs?: number;
+}
+
+export interface SyrinxAudioEnvelope {
+  readonly header: SyrinxAudioEnvelopeHeader;
+  readonly audio: Uint8Array;
+}
+
+export function assertAudioFormat(format: AudioFormat): void {
+  if (format.channels !== 1) throw new Error("audio must be mono");
+  if (!Number.isInteger(format.sampleRateHz) || format.sampleRateHz <= 0) {
+    throw new Error("sampleRateHz must be a positive integer");
+  }
+}
+
+export function assertAudioPayload(format: AudioFormat, audio: Uint8Array): void {
+  if (format.encoding === "opus") {
+    if (audio.byteLength === 0) {
+      throw new Error("opus payload must not be empty");
+    }
+    return;
+  }
+  if (format.encoding === "mulaw") {
+    if (audio.byteLength === 0) {
+      throw new Error("mulaw payload must not be empty");
+    }
+    return;
+  }
+  if (audio.byteLength % 2 !== 0) {
+    throw new Error("PCM16 payload must contain an even number of bytes");
+  }
+}
+
+export function encodeSyrinxAudioEnvelope(header: SyrinxAudioEnvelopeHeader, audio: Uint8Array): Uint8Array {
+  validateSyrinxAudioEnvelope(header, audio);
+  const headerBytes = new TextEncoder().encode(JSON.stringify(header));
+  const output = new Uint8Array(SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4 + headerBytes.byteLength + audio.byteLength);
+  output.set(SYRINX_AUDIO_ENVELOPE_MAGIC, 0);
+  new DataView(output.buffer, output.byteOffset, output.byteLength)
+    .setUint32(SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength, headerBytes.byteLength, true);
+  output.set(headerBytes, SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4);
+  output.set(audio, SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength + 4 + headerBytes.byteLength);
+  return output;
+}
+
+export function decodeSyrinxAudioEnvelope(data: Uint8Array): SyrinxAudioEnvelope {
+  if (!hasSyrinxAudioEnvelope(data)) {
+    throw new Error("Syrinx binary audio envelope magic is missing");
+  }
+
+  const headerLengthOffset = SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength;
+  if (data.byteLength < headerLengthOffset + 4) {
+    throw new Error("Syrinx binary audio envelope is truncated");
+  }
+
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const headerLength = view.getUint32(headerLengthOffset, true);
+  const headerStart = headerLengthOffset + 4;
+  const headerEnd = headerStart + headerLength;
+  if (headerLength <= 0 || headerEnd > data.byteLength) {
+    throw new Error("Syrinx binary audio envelope has an invalid header length");
+  }
+
+  const parsed = JSON.parse(new TextDecoder().decode(data.subarray(headerStart, headerEnd))) as unknown;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Syrinx binary audio envelope header must be an object");
+  }
+  const header = parsed as SyrinxAudioEnvelopeHeader;
+  const audio = data.subarray(headerEnd);
+  validateSyrinxAudioEnvelope(header, audio);
+
+  return { header, audio };
+}
+
+export function hasSyrinxAudioEnvelope(data: Uint8Array): boolean {
+  if (data.byteLength < SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength) return false;
+  for (let i = 0; i < SYRINX_AUDIO_ENVELOPE_MAGIC.byteLength; i += 1) {
+    if (data[i] !== SYRINX_AUDIO_ENVELOPE_MAGIC[i]) return false;
+  }
+  return true;
+}
+
+function validateSyrinxAudioEnvelope(header: SyrinxAudioEnvelopeHeader, audio: Uint8Array): void {
+  if (header.type !== "audio") {
+    throw new Error("Syrinx binary audio envelope type must be audio");
+  }
+  if (!isPositiveInteger(header.sampleRateHz)) {
+    throw new Error("Syrinx binary audio envelope sampleRateHz must be a positive integer");
+  }
+  if (header.encoding && header.encoding !== "pcm_s16le" && header.encoding !== "opus") {
+    throw new Error(`Unsupported Syrinx binary audio encoding: ${header.encoding}`);
+  }
+  if (header.sequence !== undefined && !isNonNegativeInteger(header.sequence)) {
+    throw new Error("Syrinx binary audio envelope sequence must be a non-negative integer");
+  }
+  if (header.durationMs !== undefined && !isNonNegativeInteger(header.durationMs)) {
+    throw new Error("Syrinx binary audio envelope durationMs must be a non-negative integer");
+  }
+  if (header.byteLength !== undefined && !isNonNegativeInteger(header.byteLength)) {
+    throw new Error("Syrinx binary audio envelope byteLength must be a non-negative integer");
+  }
+  if (header.byteLength !== undefined && header.byteLength !== audio.byteLength) {
+    throw new Error("Syrinx binary audio envelope byteLength does not match payload");
+  }
+
+  const format: AudioFormat = {
+    encoding: header.encoding === "opus" ? "opus" : "pcm_s16le",
+    sampleRateHz: header.sampleRateHz,
+    channels: header.channels ?? 1,
+  };
+  assertAudioFormat(format);
+  assertAudioPayload(format, audio);
+
+  if (format.encoding !== "opus" && header.durationMs !== undefined) {
+    const expectedDurationMs = Math.round((audio.byteLength / 2 / header.sampleRateHz) * 1000);
+    if (Math.abs(header.durationMs - expectedDurationMs) > 1) {
+      throw new Error("Syrinx binary audio envelope durationMs does not match payload and sampleRateHz");
+    }
+  }
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}

package/src/conversation-event.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Conversation Event (Debug Stream)
+//
+// Normalized event type consumed by debugger UIs and the VoiceSessionRecorder.
+// Every pipeline component emits these alongside their functional packets.
+// Exposed as `session.debugEvents: ReadableStream<ConversationEvent>`.
+//
+// Design decision (per RFC Q3 resolution): events flow through the bus on
+// the Background route. If Background saturates, drops are metric'd.
+
+// =============================================================================
+// Type
+// =============================================================================
+
+export interface ConversationEvent {
+  /** Component that emitted the event: "vad", "stt", "eos", "llm", "tts", "tool", "session", "turn" */
+  readonly component: string;
+  /** Sub-type: "speech_started", "interim", "final", "delta", "first_audio", "call_started", etc. */
+  readonly type: string;
+  /** Arbitrary key-value payload. Always includes "context_id". */
+  readonly data: Readonly<Record<string, string>>;
+  /** Wall-clock time of the event in ms since epoch. */
+  readonly timestampMs: number;
+}
+
+// =============================================================================
+// Factory
+// =============================================================================
+
+/**
+ * Create a ReadableStream of ConversationEvents that is fed by a callback.
+ * Returns [stream, push] — call push(event) to enqueue, consumers read from stream.
+ */
+export function createConversationEventStream(): [
+  ReadableStream<ConversationEvent>,
+  (event: ConversationEvent) => void,
+] {
+  let controller: ReadableStreamDefaultController<ConversationEvent> | null =
+    null;
+
+  const stream = new ReadableStream<ConversationEvent>({
+    start(c) {
+      controller = c;
+    },
+    cancel() {
+      controller = null;
+    },
+  });
+
+  const push = (event: ConversationEvent): void => {
+    if (controller) {
+      try {
+        controller.enqueue(event);
+      } catch {
+        // Stream closed — drop
+      }
+    }
+  };
+
+  return [stream, push];
+}

package/src/error-handler.test.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import { ErrorCategory } from "./packets.js";
+import { categorizeLlmError, categorizeSttError, categorizeTtsError, isRecoverable } from "./error-handler.js";
+
+describe("LLM error handling", () => {
+  it("treats malformed provider tool calls as retryable generation failures", () => {
+    const category = categorizeLlmError(new Error("AI SDK provider step failed: MALFORMED_FUNCTION_CALL"));
+
+    expect(category).toBe(ErrorCategory.NetworkTimeout);
+    expect(isRecoverable(category)).toBe(true);
+  });
+
+  it("treats provider 500/internal TTS failures as retryable", () => {
+    const category = categorizeTtsError(new Error("code 500: An internal error has occurred. Please retry."));
+
+    expect(category).toBe(ErrorCategory.NetworkTimeout);
+    expect(isRecoverable(category)).toBe(true);
+  });
+
+  it("maps Deepgram NET websocket close frames to recoverable connection failures", () => {
+    const category = categorizeSttError(new Error("Deepgram STT WebSocket closed unexpectedly: code=1011 reason=NET-0000"));
+
+    expect(category).toBe(ErrorCategory.NetworkTimeout);
+    expect(isRecoverable(category)).toBe(true);
+  });
+
+  it("maps provider finalization timed-out wording to recoverable timeout", () => {
+    const category = categorizeSttError(new Error("Deepgram STT Finalize timed out before speech_final/from_finalize confirmation"));
+
+    expect(category).toBe(ErrorCategory.NetworkTimeout);
+    expect(isRecoverable(category)).toBe(true);
+  });
+
+  it("maps Deepgram DATA websocket close frames to fatal input failures", () => {
+    const category = categorizeSttError(new Error("Deepgram STT WebSocket closed unexpectedly: code=1008 reason=DATA-0000"));
+
+    expect(category).toBe(ErrorCategory.InvalidInput);
+    expect(isRecoverable(category)).toBe(false);
+  });
+
+  it("maps provider concurrency-limit errors to recoverable rate-limit (G8)", () => {
+    for (const message of [
+      "Cartesia TTS provider error: concurrency limit exceeded",
+      "Too many concurrent connections",
+      "max concurrency reached",
+      "concurrency_limit_exceeded",
+    ]) {
+      const category = categorizeTtsError(new Error(message));
+      expect(category, `message: ${message}`).toBe(ErrorCategory.RateLimit);
+      expect(isRecoverable(category)).toBe(true);
+    }
+  });
+});

package/src/error-handler.ts

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Error Handler
+//
+// Categorizes errors from external service providers and determines
+// whether they are recoverable (retry with backoff) or fatal (terminate session).
+//
+// Each component (STT, TTS, LLM) has its own categorization logic.
+// The session manager uses these to decide retry vs. terminate.
+
+import { ErrorCategory, type VoiceErrorPacket } from "./packets.js";
+
+// =============================================================================
+// Error Categorization
+// =============================================================================
+
+/**
+ * Categorize an error from the STT provider.
+ *
+ * Heuristic:
+ *   - HTTP 429 → RateLimit (recoverable)
+ *   - Network errors (ECONNRESET, ETIMEDOUT, ENOTFOUND) → NetworkTimeout (recoverable)
+ *   - HTTP 401/403 → Authentication (fatal)
+ *   - HTTP 400/422 → InvalidInput (fatal)
+ *   - HTTP 402 → ResourceExhausted (fatal)
+ *   - Everything else → InternalFault (fatal)
+ */
+export function categorizeSttError(err: unknown): ErrorCategory {
+  const msg = extractMessage(err).toLowerCase();
+  const code = extractHttpStatus(err);
+
+  if (
+    code === 429 ||
+    msg.includes("rate limit") ||
+    msg.includes("rate_limit") ||
+    msg.includes("too many requests") ||
+    // Provider concurrency limits (e.g. Cartesia) — recoverable, retry with backoff.
+    msg.includes("concurrency limit") ||
+    msg.includes("concurrency_limit") ||
+    msg.includes("concurrent limit") ||
+    msg.includes("too many concurrent") ||
+    msg.includes("max concurrency") ||
+    (msg.includes("concurren") && (msg.includes("exceed") || msg.includes("limit")))
+  ) {
+    return ErrorCategory.RateLimit;
+  }
+  if (code === 401 || code === 403 || msg.includes("unauthorized") || msg.includes("forbidden")) {
+    return ErrorCategory.Authentication;
+  }
+  if (code === 400 || code === 422 || msg.includes("invalid") || msg.includes("bad request")) {
+    return ErrorCategory.InvalidInput;
+  }
+  if (msg.includes("data-000")) {
+    return ErrorCategory.InvalidInput;
+  }
+  if (code === 402 || msg.includes("payment required") || msg.includes("insufficient")) {
+    return ErrorCategory.ResourceExhausted;
+  }
+  if (
+    msg.includes("econnreset") ||
+    msg.includes("etimedout") ||
+    msg.includes("enotfound") ||
+    msg.includes("network") ||
+    msg.includes("net-000") ||
+    msg.includes("timeout") ||
+    msg.includes("timed out") ||
+    msg.includes("econnrefused") ||
+    msg.includes("socket hang up") ||
+    msg.includes("code=1011") ||
+    msg.includes("internal error has occurred") ||
+    (code !== null && code >= 500 && code <= 599)
+  ) {
+    return ErrorCategory.NetworkTimeout;
+  }
+
+  return ErrorCategory.InternalFault;
+}
+
+/**
+ * Categorize an error from the TTS provider.
+ * Same heuristic as STT — TTS providers have similar error patterns.
+ */
+export function categorizeTtsError(err: unknown): ErrorCategory {
+  return categorizeSttError(err); // Same logic applies
+}
+
+/**
+ * Categorize an error from the LLM provider.
+ *
+ * Additional LLM-specific heuristics:
+ *   - "context length exceeded" → InvalidInput (fatal)
+ *   - "content filter" / "safety" → InvalidInput (fatal)
+ */
+export function categorizeLlmError(err: unknown): ErrorCategory {
+  const msg = extractMessage(err).toLowerCase();
+
+  if (msg.includes("context length") || msg.includes("token limit") || msg.includes("too many tokens")) {
+    return ErrorCategory.InvalidInput;
+  }
+  if (msg.includes("content filter") || msg.includes("safety") || msg.includes("blocked")) {
+    return ErrorCategory.InvalidInput;
+  }
+  if (msg.includes("malformed_function_call")) {
+    return ErrorCategory.NetworkTimeout;
+  }
+
+  return categorizeSttError(err); // Base logic for HTTP errors
+}
+
+// =============================================================================
+// Recoverability
+// =============================================================================
+
+/**
+ * Returns true if the error category is recoverable (retry with backoff).
+ */
+export function isRecoverable(category: ErrorCategory): boolean {
+  return category === ErrorCategory.RateLimit || category === ErrorCategory.NetworkTimeout;
+}
+
+/**
+ * Returns true if the error packet represents a fatal error.
+ */
+export function isFatalError(pkt: VoiceErrorPacket): boolean {
+  return !pkt.isRecoverable;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function extractMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (err && typeof err === "object" && "message" in err) {
+    return String((err as { message: unknown }).message);
+  }
+  return String(err);
+}
+
+function extractHttpStatus(err: unknown): number | null {
+  if (err && typeof err === "object") {
+    const e = err as Record<string, unknown>;
+    if (typeof e.status === "number") return e.status;
+    if (typeof e.statusCode === "number") return e.statusCode;
+    if (typeof e.code === "number") return e.code;
+  }
+  return null;
+}