truf-server/openspec/changes/resolve-ambiguous-key-providers/specs/ambiguous-provider-resolution/spec.md

ADDED Requirements

Requirement: Ambiguous credentials use one sequential resolver

The system SHALL represent one ambiguous credential occurrence as one leased resolver candidate and SHALL probe only the compatible provider set in deterministic order.

Scenario: Weak generic-key context

• WHEN a detector-qualified generic sk-... finding has no single strong provider attribution
• THEN the system SHALL enqueue one resolver candidate rather than independently active candidates for every compatible provider

Scenario: Strong provider attribution

• WHEN a finding has one strong provider-specific format or context signal
• THEN the system SHALL retain the direct provider route without invoking unrelated provider adapters

Requirement: Resolver outcomes control progression

The resolver SHALL distinguish positive match, definitive provider mismatch, and retryable uncertainty.

Scenario: Provider rejects credential

• WHEN a provider definitively reports invalid authentication for an ambiguous credential
• THEN the resolver SHALL record that attempt and continue to the next compatible provider

Scenario: Provider response is inconclusive

• WHEN a provider attempt fails because of a network error, server error, or otherwise inconclusive response
• THEN the resolver SHALL NOT classify that attempt as a definitive provider mismatch

Scenario: All providers reject credential

• WHEN every compatible provider definitively rejects the credential
• THEN the resolver SHALL record an exhausted unresolved result after the final attempt

Requirement: First positive match terminates resolution

The resolver SHALL stop after the first response that proves the credential belongs to a provider.

Scenario: Later provider recognizes credential

• WHEN earlier providers reject a credential and a later provider positively recognizes it
• THEN the resolver SHALL stop without calling subsequent providers and SHALL retain the ordered attempt evidence

Requirement: Matched result uses actual provider authority

A positively resolved candidate SHALL be completed transactionally under the provider that recognized it.

Scenario: Resolver candidate matches another service

• WHEN a leased resolver candidate receives a positive ZAI result
• THEN the same fenced transaction SHALL associate the candidate and current state with the canonical ZAI credential and project the result as service zai

Scenario: Completion loses its lease fence

• WHEN the candidate lease no longer matches during provider reassignment
• THEN no result, current-state update, or partial service reassignment SHALL be committed

Requirement: Legacy ambiguous candidates remain recoverable

Existing generic-provider candidates with persisted ambiguous routing evidence SHALL use the resolver when explicitly retried.

Scenario: Retried legacy Qwen candidate

• WHEN an old Qwen candidate carries an ambiguous generic-provider hint and is retried
• THEN the Qwen worker SHALL delegate it to the shared resolver instead of leaving it unconsumed again