fix: make the non-CGO Candle backend fail closed or contract-faithful
#2,491 opened on Jul 13, 2026
Repository metrics
- Stars
- (4,293 stars)
- PR merge metrics
- (PR metrics pending)
Description
Problem
The Candle Go package selects semantic-router_mock.go on Windows or whenever
CGO is disabled. That file is currently a mixture of a compile-time test double
and a runtime substitute, but it does not implement the public package's
behavioral contract. A full CGO_ENABLED=0 go test ./... run fails across
similarity, LoRA result cardinality, adapter state, guard classification, and
jailbreak classification. Before the focused audit fixes, current embedding,
multimodal, and batch-similarity APIs also returned dimensions and result counts
that the native backend would not return.
This is unsafe to leave ambiguous: downstream builds can compile successfully without the native backend and receive plausible placeholder success values.
Required invariant
Choose and enforce one explicit contract:
- A contract-faithful non-CGO implementation whose public results, errors, dimensions, top-k behavior, state lifecycle, and validation pass the same package corpus as the native build; or
- A compile-only stub that fails closed for every inference or mutation API with a typed backend-unavailable error and cannot be packaged as a working production router.
Do not return successful synthetic safety, classification, similarity, or adapter results from an unavailable backend.
Acceptance evidence
CGO_ENABLED=0 go test ./...is green with tests that cannot silently skip either the contract-faithful or fail-closed behavior.- The build and release workflows explicitly identify whether non-CGO artifacts are supported runtime artifacts or compile-only targets.
- Shared request validation (including NUL, image/audio tensor shape, image URL, target dimension, and top-k) runs under both build modes.
- Router consumer tests prove an unavailable native backend cannot produce a successful routing or safety decision.
Found during the repository-wide #2375 closure. Focused input/dimension/top-k parity is being fixed in that audit; the broader classification/state contract belongs here.