truf-server/openspec/changes/resolve-ambiguous-key-providers/specs/zai-key-validation/spec.md

ADDED Requirements

Requirement: ZAI findings produce keycheck candidates

The scanner SHALL create ZAI keycheck candidates for detector-qualified zai-..., compatible sk-..., and bounded dotted ZAI/Zhipu key forms.

Scenario: Existing ZaiGLM detector finding

• WHEN the ZaiGLM custom detector emits a bounded API credential
• THEN candidate extraction SHALL preserve its finding attribution and route it to ZAI or the ambiguous resolver according to persisted provider evidence

Requirement: ZAI validation proves generation availability

The ZAI checker SHALL authenticate with a model-list request and SHALL require a bounded one-token glm-5.2 generation probe before classifying a credential as valid and alive.

Scenario: Global ZAI credential

• WHEN the global ZAI /models endpoint accepts the credential and the bounded generation probe succeeds
• THEN the checker SHALL record a valid authenticated ZAI result with bounded model and probe metadata

Scenario: China Zhipu credential

• WHEN the global endpoint rejects a credential but the configured China endpoint accepts it and its bounded generation probe succeeds
• THEN the checker SHALL record the credential as ZAI with the successful endpoint region

Scenario: Model listing succeeds but generation is unavailable

• WHEN /models authenticates the credential but the generation probe reports quota, balance, permission, transient, or inconclusive failure
• THEN the checker SHALL preserve the authenticated ZAI match but SHALL NOT classify the credential as valid or write it to the alive set

Scenario: Model listing omits GLM 5.2

• WHEN /models authenticates the credential but does not advertise glm-5.2
• THEN the checker SHALL still probe the fixed glm-5.2 target and SHALL NOT substitute another model

Requirement: ZAI responses are classified by protocol evidence

The checker SHALL classify HTTP status and documented ZAI business error codes without treating inconclusive failures as invalid credentials.

Scenario: Authentication rejected

• WHEN ZAI returns HTTP 401 or an authentication-failure business code
• THEN the attempt SHALL be classified as a definitive provider mismatch or dead direct credential

Scenario: Authenticated balance or plan restriction

• WHEN ZAI returns a provider-specific balance, usage-plan, or permission response during model listing or the generation probe
• THEN the attempt SHALL be marked as belonging to ZAI with the corresponding limited, no-balance, or restricted status

Scenario: Network or server failure

• WHEN the request fails in transit or ZAI returns a server error
• THEN the checker SHALL classify the attempt as retryable rather than dead

Requirement: ZAI participates in normal runtime accounting

The ZAI checker SHALL use the existing PostgreSQL lease, result, current-state, projection, and summary infrastructure.

Scenario: Scheduled ZAI work exists

• WHEN the unified keycheck scheduler detects claimable ZAI candidates
• THEN it SHALL launch the ZAI checker with the same authority and bounded-slice controls used for other providers