# Known limitations

These limitations apply when evaluating the qualified v1 candidate. Read the [release scope](release-status.md) for the measured profile and the [compatibility reference](reference/compatibility.md) for the exact API subset. Qualification is not a guarantee for an arbitrary topology, workload or optional integration.

## Deployment and recovery

The accepted release topology is one gateway instance using the documented v1 Compose profile. Multi-instance high availability, multi-region operation, rolling upgrades and managed Redis failover are not established by this qualification. PostgreSQL, the counter store and each gateway's journal have different recovery responsibilities.

A counter-store restart or trust-epoch change can refuse capped traffic with `budget_recovering` until the documented recovery and independent spend attestation are complete. A database backup alone cannot prove spend lost with counter state. An operator must not clear counters or restart with empty state to make refusals disappear. See [operations](operating-notes.md) and [journal epochs](operations/journal-epochs.md).

An abrupt increase in counter latency near its deadline can briefly produce `budget_unverifiable` refusals for capped traffic even when ordinary health checks still succeed. Cache Redis and counter Redis have separate clients and failure policies. Cache fail-open does not authorize budget fail-open.

## Streaming, tools and accounting

The API supports a documented Chat Completions subset. It is not a blanket implementation of every OpenAI API. Pointsman forwards supported tool-call structures; it does not execute tools.

Streamed tool-call delivery may be buffered rather than progressively emitted. Enforced whole-response output checks also require buffering and replay. This changes time to first byte and memory needs; do not promise token-by-token output for every policy/response combination.

HTTP 200 means the stream began, not that it completed or produced a good answer. Analytics uses recorded statuses while dispatch records terminal outcomes separately. A late failure cannot retract bytes already received. Cancellation before headers is not proof that the provider did no work. Estimated or provider-reported usage priced by the gateway is not an independently verified provider invoice.

## Cache correctness and capacity

Semantic similarity is approximate. Lexical checks reject some unsafe matches, including changed significant terms, but do not prove equivalent meaning or factual correctness. Applications needing strict equivalence should use exact reuse or disable reuse for those requests.

Cache capacity depends on response size, embeddings and index overhead as well as document count. A document limit larger than available memory does not protect write availability. Saturation can make store checks close L2 writes; the gateway can continue with misses while provider traffic and spend increase. Size TTL and memory for the working set and monitor write admission.

The accepted 12-hour stage observed 14 lookup and 9 asynchronous store timeouts at 50 ms, plus one FT.INFO fallback. The 24-hour stage observed 29 lookup and 19 store timeouts, with no additional FT.INFO fallback. No unexpected client outcome or accounting discrepancy was observed from them; the underlying Redis jitter/latency cause is not established. These results do not support a zero-cache-error claim.

## Adaptive routing and quality

Adaptive cost/balanced routing, LinTS, quality-guarded policies, judges/cascades and Jev remain experimental and opt-in. The default is weighted-random routing. Operational completion, latency and cost signals are not answer-quality labels. A separate coding/extraction comparison did not establish an adaptive advantage; there is no quality-preserving savings claim.

Quality evidence has a specific model version, task, rubric and validity window. A qualified candidate for one scope is not universally correct. Auxiliary experimental judge calls have a narrower identity-evidence contract than ordinary serving calls and are outside the supported default path.

The in-process cost sampler loses its learned state on gateway restart. Balanced learning uses a separate durable policy service. That service supports one worker and has no independent authentication boundary; it must remain on a private network. See [adaptive routing](design/adaptive-routing.md) and [policy service design](design/policy-service.md).

## Authorization and scope policies

Scoped administrative authorization is enabled by default. The stored scope-tree request path is separately opt-in; application requests default to the fixed organization/application/user/key policy path. Authored team controls do not become live merely because the team or its preview exists.

The current policy implementation has these boundaries:

| Area | Limit | Operational implication |
|---|---|---|
| Generic policy vocabulary | Only `allowed_models` with intersection | Use the separate limit/guardrail machinery for other controls |
| Stored `PRINCIPAL` rows | Authorable and previewable; live requests use the legacy user contribution | A principal preview is not proof of live enforcement |
| Credential rows on a tree path | Live composition takes the first matching row root-first; preview can compose several | Do not assume stacked credential rows are cumulative live restrictions |
| `enforced_on_request_path` | Reports the feature flag | Does not prove per-subject enforcement or absence of fallback |
| Compatibility fallbacks | Existing admin gates may use legacy authorization; tree policy may use the fixed calculator | Authored-only restrictions are not guaranteed during fallback |

Read [authorization design](design/authorization.md) and verify representative allowed and denied requests before relying on stored-tree policies.

## Security and configuration

Guardrails are configurable controls with false positives and false negatives, not proof against prompt injection or sensitive-data disclosure. External checks and hosted embedding/context services can receive content; evaluate their data handling separately.

Some guardrail parameters cannot safely change through a lower scope or hot-reload path. A legacy tenant override with an unrulable parameter can block a later tenant write until it is corrected. Use the supported administrative workflow and effective-policy reads.

Provider destination checks do not replace network egress isolation. Administrative access is powerful, public health/metrics endpoints disclose operational information, and a secret placed under an unrecognized extra-header name may still be stored in plaintext. See the [security posture](security.md) before exposing the gateway.

## Interpreting the evidence

All governing healthy-stage checks passed without a fault exception. A separate legacy resource diagnostic remained failed, and natural-reclaim/drain-pressure observations remained incomplete; neither was a governing acceptance dependency. Earlier failed runs remain retained. Historical full-suite test transport flakes are documented separately and are not evidence that arbitrary runtime workloads passed.

Public qualification summaries preserve these limitations while private investigation logs and execution records remain outside the documentation website.