Reference — Claim matrix¶
Generated from the maintainer-curated claim registry in
scripts/generate_reference_docs.py: every public claim carries its
maturity, implementation location, automated evidence, and known
limitation. Documentation must never describe an experimental,
optional, or owner action surface as universally operational.
| Public claim | Maturity | Implementation location | Automated evidence | Known limitation |
|---|---|---|---|---|
| CLI lifecycle commands | stable |
src/knovaryn/interfaces/cli/ |
tests/test_cli_conformance.py (tree snapshot + docs scan) | Local run drives one job in-process; durable multi-worker mode uses worker. |
| REST API + web console | stable |
src/knovaryn/interfaces/rest/ |
tests/test_rest_api.py, tests/test_rest_webconsole.py | Bearer-token auth only when KNOVARYN_API_TOKEN is set. |
| Python SDK (Workspace) | stable |
src/knovaryn/application/workspace.py |
tests/test_workspace_control.py | APIs may still gain parameters within the 0.x line. |
| MCP stdio server | experimental |
src/knovaryn/interfaces/mcp/server.py |
tests/mcp/, scripts/mcp_acceptance_matrix.py (4 cells: mcp 1.28.0–2.1.0), ADR-0007 | Tool surface may be reshaped before 1.0. |
| MCP streamable HTTP (authenticated) | experimental |
src/knovaryn/interfaces/mcp/server.py |
scripts/mcp_acceptance_matrix.py (both SDK majors, 4 pins), ADR-0007 | Deploy behind the bearer-token guard; not exposed by default. |
| Provenance lineage + location precision | stable |
src/knovaryn/application/, src/knovaryn/pipeline/export/gate.py |
tests/provenance/ | Precision reflects the parser: markdown/text caps at section/chunk. |
| Docling parsing (bounding-box spans) | optional |
src/knovaryn/infrastructure/docling/ |
tests marked docling; ADR-0003 resource guard |
Requires the docling extra and its runtime dependencies. |
Offline semantic validation (offline-fast) |
stable |
src/knovaryn/pipeline/quality/validators.py |
tests/semantic/ | Deterministic checks catch specific contradiction classes only. |
Certified semantic validation (certified-semantic) |
optional |
src/knovaryn/pipeline/quality/profiles.py |
tests/semantic/ benchmark corpus | Needs a reachable judge provider; unavailable judge ⇒ unverified. |
Preference pairs + certified-pairwise profile |
alpha |
src/knovaryn/pipeline/quality/validators.py |
tests/preference/ | Judge-based certification inherits provider limitations. |
| Information-gain / preference-signal gates | alpha |
src/knovaryn/pipeline/quality/ |
tests/test_validators.py | Heuristic scoring; not a quality guarantee. |
| Durable jobs (claim/heartbeat/checkpoint/resume) | stable |
src/knovaryn/pipeline/jobs/, src/knovaryn/infrastructure/database/ |
tests/chaos/, tests/deployment/ | SQLite mode is single-writer; concurrent workers need PostgreSQL. |
| PostgreSQL multi-worker queue | optional |
src/knovaryn/infrastructure/database/repositories.py (SKIP LOCKED) |
tests/deployment/test_compose_e2e.py claim-exclusivity race | Requires a deployed Postgres; SQLite dialect ignores FOR UPDATE. |
| S3-compatible artifact storage | optional |
src/knovaryn/infrastructure/artifacts/s3.py |
tests marked s3 |
Requires the s3 extra and object-store credentials. |
| Hugging Face publishing | optional |
src/knovaryn/infrastructure/publish/hf.py |
publication-gate tests (dry-run default) | Never automatic; license/privacy gate plus explicit confirmation. |
| PyPI installation | stable |
.github/workflows/publish.yml (OIDC trusted publishing) |
scripts/package_ci.py clean-env battery | First-time setup of PyPI trusted publisher is an owner action. |
| Release integrity (checksums, SBOM, notes) | stable |
scripts/release_governance.py, src/knovaryn/pipeline/export/verify_release.py |
tests/test_release_governance.py, tests/test_release_integrity.py | GitHub-side settings (labels, environments) are owner actions. |
| Docker Compose topology | stable |
deploy/docker/ |
.github/workflows/deploy-e2e.yml exact-SHA suite | Weekly/dispatch execution; always runs at release time. |
| Kubernetes manifests | alpha |
deploy/kubernetes/ |
kustomize build in CI lint path | No automated cluster E2E yet; backup/restore documented as runbook. |
| Documentation site & search metadata | stable |
mkdocs.yml, overrides/, docs/ |
ci.yml docs job (strict build + links + assets) | Search-engine indexing itself is an owner action (§7.2). |
| Benchmarks (canonical methodology + current report) | alpha |
benchmarks/run_report.py, docs/reference/benchmark-methodology.md |
benchmarks/results/0.2.1/ (3 runs, checksums, H(R1)=H(R2)=H(R3) digest equality) | Offline fake-provider framework metrics ≠ generation throughput or model quality; live-provider evidence not measured. |
| Release-bundle reproducibility (reproducible mode) | alpha |
src/knovaryn/domain/ids.py (seeded IdGenerator), benchmarks/run_report.py |
tests/test_reproducible_release_digest.py; results/0.2.1/aggregate.json digest equality | Requires seeded IDs (reproducible mode); production IDs stay unguessable UUIDv7s. |