{
  "slug": "sdk/parity",
  "title": "SDK Parity & Divergence",
  "description": "Intentional API differences across the four Cuitty SDKs.",
  "url": "https://cuitty.com/docs/sdk/parity",
  "markdown_url": "https://cuitty.com/docs/sdk/parity.md",
  "json_url": "https://cuitty.com/docs/sdk/parity.json",
  "frontmatter": {
    "title": "SDK Parity & Divergence",
    "description": "Intentional API differences across the four Cuitty SDKs.",
    "order": 5,
    "section": "SDK",
    "updatedAt": "2026-04-28"
  },
  "headings": [
    {
      "depth": 1,
      "slug": "sdk-parity--divergence",
      "text": "SDK Parity & Divergence"
    },
    {
      "depth": 2,
      "slug": "capability-matrix",
      "text": "Capability matrix"
    },
    {
      "depth": 2,
      "slug": "things-that-are-the-same-across-all-four-sdks",
      "text": "Things that ARE the same across all four SDKs"
    },
    {
      "depth": 2,
      "slug": "where-to-find-authoritative-behavior",
      "text": "Where to find authoritative behavior"
    }
  ],
  "body_markdown": "# SDK Parity & Divergence\n\nThe Cuitty SDKs share a wire protocol but each takes the idiomatic shape of its language. This page documents the intentional differences.\n\n## Capability matrix\n\n| Feature | TypeScript | Python | Go | Rust |\n| --- | --- | --- | --- | --- |\n| Async-first | Implicit (Promise) | Sync (async on roadmap) | Sync, ctx-aware | Async (Tokio) |\n| Plugin model | `client.use(plugin)` | `client.audit`, `client.logs` | `client.Audit`, `client.Logs` | `client.audit()`, `client.logs()` |\n| Path B retry | Yes (5xx + 429) | Yes (5xx + 429) | Yes (5xx + 429) | Yes (5xx + 429) |\n| Idempotency keys | Yes (UUID v4) | Yes | Yes | Yes |\n| Hono adapter | Yes | n/a | n/a | n/a |\n| Pino bridge | Yes | n/a (stdlib logging adapter on roadmap) | n/a (slog) | n/a (tracing) |\n| Concurrency-safe | Yes | Yes | Yes | Yes (Arc-cloned client) |\n\n## Things that ARE the same across all four SDKs\n\n- Wire format: identical JSON bodies for the same logical event\n- Idempotency: UUID v4 in `X-Idempotency-Key` header on every Path B batch\n- Retry: 3 attempts, exponential backoff (250 ms → 1 s → 4 s)\n- 4xx behavior: drop with warn log, no retry\n- 429 behavior: honor `Retry-After`\n- Auth: `Authorization: Bearer <api_key>` plus `X-Project-Id`\n- Batch triggers: ≥1000 events or ≥1 MiB or ≥250 ms idle\n- Close semantics: `close()` flushes pending events synchronously\n\nIf your code depends on something that's the same across SDKs but isn't on this list, it might still be safe — but it's not promised. Open an issue and we'll add it (or document why it's not promised).\n\n## Where to find authoritative behavior\n\nThe wire protocol is documented in [`packages/wire-protocol/openapi.yaml`](https://gitlab.com/cuitty/wire-protocol/openapi.yaml). The SDK-specific READMEs document divergences from that protocol in their \"Spec Drift\" sections.\n\nLive SDK-by-SDK benchmarks: [https://benchmarks.cuitty.com/sdks](https://benchmarks.cuitty.com/sdks).",
  "links_out": [
    "https://gitlab.com/cuitty/wire-protocol/openapi.yaml",
    "https://benchmarks.cuitty.com/sdks"
  ]
}