Initial server source import
This commit is contained in:
sashatrask
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-16
|
||||
@@ -0,0 +1,78 @@
|
||||
## Context
|
||||
|
||||
The scanner already persists exact and ambiguous routing hints for overlapping Qwen, DeepSeek, and Kimi `sk-...` findings. Provider workers, however, claim service-specific candidates and reject any hint that is not exactly their own service, so an ambiguous candidate can be repeatedly left unconsumed and quarantined. A ZAI detector already exists, but candidate extraction and a ZAI keychecker do not.
|
||||
|
||||
The authoritative runtime uses PostgreSQL candidate leases and transactional result completion. Compatibility JSONL and status files are projections and must not control routing.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Resolve one ambiguous credential sequentially across only its compatible providers.
|
||||
- Stop at the first response that proves the credential belongs to a provider.
|
||||
- Persist the successful result under the provider that recognized the credential.
|
||||
- Add direct ZAI extraction plus model-list authentication and a minimal generation/billing probe through the global and China APIs.
|
||||
- Preserve fenced candidate completion, capacity accounting, and restart safety.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Redesign credential storage or secret-retention policy.
|
||||
- Probe every supported provider for every unknown string.
|
||||
- Run provider probes for one ambiguous credential in parallel.
|
||||
- Automatically retry credentials whose current status is configured as terminal.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Use one virtual resolver candidate
|
||||
|
||||
Findings with a single strong provider hint continue to produce that provider's existing candidate. Findings with an ambiguous generic-key hint produce one `provider_resolver` candidate, deduplicated by credential within a staged scan bundle. The resolver owns one normal PostgreSQL lease and invokes compatible provider adapters in order, avoiding sibling candidates and cross-worker races.
|
||||
|
||||
This is preferred to enqueueing one active candidate per provider because the latter requires new coordination state, can spend quota concurrently, and complicates exact queue-capacity release.
|
||||
|
||||
### Keep route selection bounded and deterministic
|
||||
|
||||
Persisted provider evidence limits the compatible set. The default fallback order is `deepseek,zai,qwen,kimi`; a provider identified by the originating detector is moved to the front when it belongs to the compatible set. The order is configurable, deduplicated, and never expanded beyond the supported generic-key provider set.
|
||||
|
||||
Provider-specific formats such as `sk-sp-...`, `zai-...`, and ZAI's dotted key form remain direct routes when the finding evidence is unambiguous.
|
||||
|
||||
### Normalize adapter outcomes
|
||||
|
||||
Each adapter returns its existing detailed status plus a resolver outcome:
|
||||
|
||||
- `match`: a successful authenticated response or provider-specific account/quota response proves ownership.
|
||||
- `no_match`: the provider definitively rejects the credential as invalid.
|
||||
- `retry`: network, server, generic rate-limit, malformed, or otherwise inconclusive responses.
|
||||
|
||||
The resolver continues past `no_match` and may continue past `retry` to find a later positive match. If no provider matches, any retryable attempt keeps the result unresolved; only an all-`no_match` route is exhausted.
|
||||
|
||||
### Reassign a matched candidate during fenced completion
|
||||
|
||||
When a resolver result names a matched provider, `complete_keycheck_candidate` obtains or creates the canonical credential row for that provider, reassigns the leased candidate to it, and writes the result/current state under the matched service in the same transaction. The existing provider-key fingerprint, event fence, projection reservation, and capacity accounting remain unchanged. No schema migration is required.
|
||||
|
||||
Legacy Qwen, DeepSeek, or Kimi candidates carrying an ambiguous persisted hint delegate to the same resolver so explicitly retried old candidates do not return to the unconsumed quarantine loop.
|
||||
|
||||
### Authenticate ZAI through model listing and prove usability
|
||||
|
||||
The ZAI adapter first calls authenticated `GET /models` on `https://api.z.ai/api/paas/v4` and `https://open.bigmodel.cn/api/paas/v4`, then sends a one-token `POST /chat/completions` probe to the fixed `glm-5.2` target. A key is `VALID` only when that probe succeeds. Model-list authentication still proves provider ownership when the probe reports quota, balance, permission, model access, or transient failures, but those outcomes are persisted outside the alive set. HTTP, documented ZAI business codes, and bounded message markers distinguish invalid authentication, recognized quota/balance restrictions, rate limits, permission restrictions, and transient failures.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [A transient response from an early provider could hide a later match if probing stopped] -> Continue through the bounded compatible set while retaining the transient outcome if nobody matches.
|
||||
- [The same text could theoretically be valid at more than one compatible gateway] -> Deterministic first-match ordering is explicit and recorded with all preceding attempts.
|
||||
- [All-provider fallback increases requests for weak-context findings] -> Restrict it to detector-qualified generic-key formats and one sequential resolver candidate.
|
||||
- [Existing quarantined candidates are not silently mutated] -> Make legacy candidates resolver-aware; operators can explicitly retry affected quarantine records through the existing review path.
|
||||
- [Provider API behavior may change] -> Keep ZAI endpoints configurable and cover response classification with mocked regression tests.
|
||||
- [The usability probe consumes provider resources] -> Request one output token from one deterministic chat model and stop after the first conclusive authenticated endpoint.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Deploy extraction, resolver, ZAI adapter, runner registration, and transactional service reassignment together.
|
||||
2. Restart the supervised runtime so the lifecycle code manifest and service registry are rebuilt atomically.
|
||||
3. Verify new ambiguous candidates are owned by `provider_resolver` and matched rows are projected under the actual provider.
|
||||
4. Explicitly retry only relevant legacy provider-routing quarantine records after the new behavior is active.
|
||||
|
||||
Rollback requires stopping the runtime and restoring the previous code/config manifest. No database schema rollback is needed.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None.
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
Generic `sk-...` credentials can match several supported providers, while the current exact-hint routing leaves ambiguous findings unconsumed and can eventually quarantine them without testing a compatible provider. The keycheck pipeline needs ordered provider resolution and ZAI coverage so a credential is attributed to the first provider that positively recognizes it.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add durable, sequential resolution for credentials whose format or finding context permits multiple providers.
|
||||
- Distinguish provider mismatch from authenticated match and retryable probe failure.
|
||||
- Stop remaining provider attempts after the first positive match while retaining auditable attempt outcomes.
|
||||
- Add a ZAI provider checker with a minimal generation/billing probe and include ZAI in compatible generic-key routing.
|
||||
- Keep explicit single-provider findings on their existing direct validation path.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `ambiguous-provider-resolution`: Ordered, durable validation of one ambiguous credential across compatible providers until one positively matches or all definitive routes are exhausted.
|
||||
- `zai-key-validation`: Extraction, probing, classification, persistence, and runtime registration for ZAI API credentials.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects scanner provider hints, keycheck candidate extraction, PostgreSQL queue/schema operations, provider checker orchestration, status projection, runtime configuration, and lifecycle authority manifests.
|
||||
- Adds a ZAI checker module using the existing HTTP and PostgreSQL keycheck infrastructure; model-list authentication alone does not qualify a key as alive.
|
||||
- Requires regression coverage for route ordering, retry behavior, atomic match resolution, candidate deduplication, and ZAI response classification; the existing free-form service and credential tables require no schema migration.
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
## 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
|
||||
@@ -0,0 +1,49 @@
|
||||
## 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
|
||||
@@ -0,0 +1,27 @@
|
||||
## 1. Routing And Candidate Extraction
|
||||
|
||||
- [x] 1.1 Extend provider evidence and persisted hints to include ZAI and weak-context generic-key ambiguity.
|
||||
- [x] 1.2 Route ambiguous findings to one deduplicated `provider_resolver` candidate while preserving direct strong-provider candidates.
|
||||
- [x] 1.3 Add bounded ZAI key formats and `ZaiGLM` service extraction.
|
||||
|
||||
## 2. Resolver And ZAI Checker
|
||||
|
||||
- [x] 2.1 Implement shared deterministic provider resolution with match, no-match, and retry outcomes.
|
||||
- [x] 2.2 Add the PostgreSQL `provider_resolver` checker and legacy ambiguous-candidate delegation.
|
||||
- [x] 2.3 Add the ZAI `/models` authentication checker with global/China endpoint and business-code classification.
|
||||
- [x] 2.4 Require a bounded ZAI generation/billing probe before assigning `VALID`, while preserving authenticated non-alive outcomes.
|
||||
- [x] 2.5 Pin the ZAI usability probe to `glm-5.2` without model-list fallback.
|
||||
|
||||
## 3. Transactional Persistence And Runtime
|
||||
|
||||
- [x] 3.1 Reassign a positively matched resolver candidate to the canonical provider credential during fenced completion.
|
||||
- [x] 3.2 Register resolver and ZAI services, capabilities, status projections, configuration, and lifecycle runtime behavior.
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [x] 4.1 Add extraction, route ordering, short-circuit, retry, ZAI classification, and service-reassignment regression tests.
|
||||
- [x] 4.2 Run targeted and existing keycheck/scanner test suites with bytecode writes disabled.
|
||||
- [x] 4.3 Restart the supervised runtime and verify READY status plus live resolver/ZAI queue behavior.
|
||||
- [x] 4.4 Add regression coverage for successful generation, no-balance, limited, restricted, and inconclusive ZAI probes.
|
||||
- [x] 4.5 Run the affected suites and verify the supervised runtime plus one live ZAI recheck.
|
||||
- [x] 4.6 Verify the fixed `glm-5.2` target with regression tests and one live recheck.
|
||||
Reference in New Issue
Block a user