DecGuard v0.1: native System One backend, real Kev and Jev validation

[suffro]

Closes the last DecGuard v0.1 release blocker: genuine end-to-end decisions through real Kev and real Jev (OpenRouter), validated in GitHub Actions on Ubuntu and macOS.

What changed

• systemone backend (built in, src/decguard/backends/systemone.py). It speaks TypeSafe's System One wire format, which is shared by self-hosted Kev (POST /v1/systemone), TypeSafe's Jev, and OpenRouter's Decisions API (POST /api/alpha/decisions). It is a thin subclass of the http backend, so it reuses the httpx client, URL and credential checks, timeouts, retries, environment-only credentials, and the rule that error bodies are never recorded. It also retries HTTP 429 and 529. No new dependency and no vendor SDK.
  • choice: labels are sent as criteria option keys. The answer's probabilities are read by option, and choice must be the most probable option.
  • noul: no labels are sent. noul is the probability of the positive (first) contract label, and the negative label gets 1 − noul.
  • score: levels are sent as the ordered criteria list. probabilities are read by level index, and the legend must echo the levels sent.
  • Answers are validated strictly and never repaired. Normalization goes through the existing DecisionResult path (exact labels, canonical order, sum within probability_tolerance).
  • Provenance: model_version is the model that answered (e.g. typesafe/jev-1.13-20260917). Per-result metadata records request_id, upstream_provider and usage (input_tokens, output_tokens, cost). The report's backend lists served_models and upstream_providers.
• Real-backend tests (tests/integration/test_real_backends.py, contracts in tests/integration/real/) with the markers real_kev and real_jev. They are skipped by default. Once selected with -m, a missing server, checkpoint or credential fails them. They assert successful decisions with valid probabilities, report generation, provenance, and that no secret appears in stdout, stderr, reports or exceptions. The last check includes a real rejected-key call (HTTP 401) with a canary key.
• Real backends workflow (.github/workflows/real-backends.yml): manual (workflow_dispatch, or the real-backends label on a PR from this repository), Python 3.13 only. It runs four jobs: REAL KEV and REAL JEV on ubuntu-latest and macos-latest. OPENROUTER_API_KEY comes from repository secrets and is passed only to the Jev test step. The Kev weights are cached by pinned revision.
• Unit tests for translation and normalization (tests/unit/test_systemone_backend.py, 36 tests).
• Docs: docs/backends.md has the systemone reference and exact Kev and Jev/OpenRouter reproduction steps. Also updated: README, CHANGELOG, docs/ci.md, the .context/ state, and a decision record.

Real backends used

	Kev	Jev
Implementation	upstream jaredpalmer/kev @ 09ff745d52a0f23954e3b0f5a608bf4c7c6aebb4, python -m kev.serve	TypeSafe Jev through OpenRouter's Decisions API
Model	jaredpalmer/kev-0.8b@9a45d25eb2ab761841196625383fa1dff0e56c1e (Kev-0.8B, the smallest current checkpoint; base Qwen/Qwen3.5-0.8B-Base)	typesafe/jev-1.13, served as typesafe/jev-1.13-20260917
Runtime	Ubuntu: CPU, torch fp32 · macOS: Apple Silicon, MLX bf16	https://openrouter.ai/api/alpha/decisions
Calls per run	3 per OS (choice, noul, score)	3 billed per OS (about $0.00001 each) + 1 rejected-key call (HTTP 401, not billed)

Jev rounds probabilities to two decimals, so the real contracts set evaluation.probability_tolerance: 0.02. The sum is still checked, never rescaled.

Evidence

Real-backend run 36067954968 on 95cc5bd:

	REAL KEV	REAL JEV
ubuntu-latest	PASS (3/3, CPU torch fp32)	PASS (4/4)
macos-latest	PASS (3/3, MLX bf16)	PASS (4/4)

Each Kev job logged serving jaredpalmer/kev-0.8b@9a45d25… on cpu via torch (float32) or … on mps via mlx (bfloat16). Each Jev decision has an OpenRouter gen-dec-… request id, upstream_provider: TypeSafe and served model typesafe/jev-1.13-20260917. Standard CI on the same commit: 36067948253. Lint, package, and Ubuntu/macOS × Python 3.11/3.12/3.13 are all green.

An earlier run (36067123735) passed all real tests, but its Kev jobs failed afterwards. A still-running uv run server held uv's cache lock, and setup-uv's post step timed out waiting for it. Fixed in 95cc5bd: the server now starts with the venv's Python and is stopped at the end of the job.

Local checks: ruff check, ruff format --check, mypy and pytest all pass (313 passed, 8 opt-in skips). uv build produces a wheel and sdist, and the clean-wheel smoke test (validate plus a real Kev decision) passes.

Not in this PR

No tag, PyPI release or GitHub release.

🤖 Generated with Claude Code