Decision Receipts for OpenAI-Compatible Route Changes (September 2026)

[chawkian]

Pricing/status note checked during the September 25, 2026 run: https://aiwave.live/api/v1/pricing returned HTTP 200 with 56 public model rows, currency USD, unit per_1m_text_tokens, checked=2026-09-10, updated_at=2026-09-18, and pricing version 83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5. The live route-pricing endpoint https://aiwave.live/api/pricing returned HTTP 200 with success=true, 73 route rows, pricing version a42d372ccf0b5dd13ecf71203521f9d2, and group ratios default=1, vip=0.9. The public status metrics endpoint was generated at 2026-09-25T04:35:01+00:00.

I have been thinking about a small missing artifact in OpenAI-compatible SDK release workflows: the route decision receipt.

A route decision record explains why a team changed a model, provider, retry policy, output cap, or billing assumption. A decision receipt is narrower. It is the machine-readable evidence that the SDK actually used the intended decision inputs at release time.

That distinction matters because the client call can look unchanged:

client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    max_tokens=600,
)

The route behind that call may still have changed in several ways. The model alias may resolve differently. The price snapshot may have moved. A key may use a different billing group. A route may have incomplete capability evidence. A status page may be current while leaving success-rate fields unpublished because the failure denominator is not complete.

I would like SDK examples to emit a small receipt for the decision inputs, not just the final response:

{
  "decision_id": "support-summary-route-2026-09-25",
  "client_shape": "openai.chat.completions",
  "model": "deepseek-v4-flash",
  "base_url": "https://aiwave.live/v1",
  "pricing_snapshot": {
    "url": "https://aiwave.live/api/v1/pricing",
    "checked": "2026-09-10",
    "updated_at": "2026-09-18",
    "version": "83f77abde81ee3a096a672ed959ccc096f5d37a45c177ae8e03229456b5415a5"
  },
  "route_table": {
    "version": "a42d372ccf0b5dd13ecf71203521f9d2",
    "billing_group": "default",
    "group_multiplier": 1
  },
  "status_snapshot": {
    "generated_at": "2026-09-25T04:35:01+00:00"
  },
  "release_gate": {
    "max_output_tokens": 600,
    "max_retry_attempts": 1,
    "rollback_model": "deepseek-v4-flash"
  },
  "redacted": true
}

This is not meant to expose prompts, credentials, user IDs, or private request bodies. It is meant to make the boring release assumptions reviewable.

For example, today's public AIWave rate card lists deepseek-v4-flash at $0.638 input, $0.0202884 cache-hit input, and $1.914 output per 1M text-token units, effective 2026-08-27. It also lists glm-5-turbo at $1.80 input, $0.4800006 cache-hit input, and $5.40 output, effective 2026-08-27. Those are useful facts for a cost gate, but they should not be silently reused as capability proof or uptime proof.

The receipt lets CI ask more precise questions:

Was the pricing snapshot checked inside the release window?
Did the SDK use the expected base_url and model ID?
Is the billing-group multiplier explicit?
Are nullable status fields handled as unknown, not zero?
Is there a named rollback model and output cap?

I like this pattern because it keeps the SDK honest without turning every route change into a heavy process. Most teams already have the pieces: a price source, a status source, a model fixture, a retry policy, and a rollback note. The receipt just keeps them together.

It also gives support a cleaner incident starting point. Instead of asking "what changed?" after a cost or behavior surprise, the first question becomes "which receipt was attached to the release?"

The tradeoff is deciding where the receipt lives. My current preference is to keep it beside SDK fixtures first, then promote the stable fields into shared tooling only after a few real incidents or rollbacks prove which fields matter.

Discussion question: should OpenAI-compatible SDKs standardize a minimal decision-receipt schema, or is this better left as a project-local fixture beside each route test?