LLM Adapter Audit Checklist#

When you wrap an OpenAI-compatible LLM provider (Moonshot, DeepSeek, xAI, Together, Fireworks, OpenRouter, vLLM, anything else that exposes POST /v1/chat/completions) in a Go HTTP client, the same ten bug classes show up. They all silently degrade or break the agent — none of them crash loudly. Each was observed in production across at least one of xAI, DeepSeek, or Moonshot during a two-week audit period.

This checklist is the audit. Run it against any new adapter before shipping. Each entry is Symptom → Cause → Fix with a code shape you can grep your repo for.

Your First Temporal Workflow in Go#

This article establishes the patterns used throughout the Temporal series: dependency injection for testable activities, idempotency for safe retries, and a clean worker binary. Every subsequent article builds on these foundations.

All code lives in the companion repo at github.com/statherm/temporal-examples. For background, see Introduction to Temporal and Namespaces and Task Queues.

Project Structure#

The companion repo organizes code by domain:

temporal-examples/
  cmd/worker/main.go         # Worker binary
  cmd/starter/main.go        # Workflow starter CLI
  internal/container/
    activities.go             # Activity implementations with DI
    workflow.go               # Workflow definitions
    types.go                  # Interfaces and types
  Makefile

Workflows and Activities#

A workflow is a deterministic function that orchestrates work. It takes workflow.Context, must not perform side effects, and dispatches work through activities. Activities use standard context.Context and perform real I/O:

Testing Temporal Workflows#

Temporal workflows have a property that most distributed systems lack: determinism. A workflow function, given the same inputs and the same sequence of activity results, will always produce the same output. This makes workflows far more testable than you might expect for code that orchestrates long-running, multi-step processes.

Activities are the opposite. They talk to databases, call APIs, read files, and produce side effects. You do not want your unit tests doing any of that. The testing strategy follows directly: test workflows by mocking their activities, and test activities by injecting mock dependencies.

ARM64 Kubernetes: The QEMU Problem with Go Binaries#

If you run Kubernetes on Apple Silicon (M1/M2/M3/M4) via minikube with the Docker driver, you will eventually try to run an amd64-only container image. For most software this works through QEMU emulation. For Go binaries, it crashes hard.

The Problem#

Go’s garbage collector uses a lock-free stack (lfstack) that packs pointers with counter bits in the high bits of a 64-bit integer. QEMU’s user-mode address translation changes the effective address space layout, which breaks this packing assumption. The result:

When to Write a Custom Exporter#

The Prometheus ecosystem has exporters for most infrastructure components: node_exporter for Linux hosts, kube-state-metrics for Kubernetes objects, mysqld_exporter for MySQL, and hundreds more. You write a custom exporter when your application or service does not have a Prometheus endpoint, you need business metrics that no generic exporter can provide (revenue, signups, queue depth), or you need to adapt a non-Prometheus system that exposes metrics in a proprietary format.