Release 0.8.1: completion cap and safe provider failures

[xeonvs]

Summary

• Added: optional OCR_LLM_MAX_COMPLETION_TOKENS, unset by default, with protocol-specific request-body mapping and fail-closed collision handling.
• Fixed: ocr-ci configure and ocr-ci preflight now share one provider-neutral URL/protocol/header/body owner; classified OCR provider failures produce bounded toolkit-authored GitLab guidance.
• Changed: protected validation now has one owner per boundary. All five OS/Python jobs still run the complete suite, one job owns coverage, Build artifacts owns package smoke, and protected-main TestPyPI owns development publication/readback.
• Removed: duplicate PR coverage instrumentation, duplicate package construction in CI quality, generic post-merge reruns of reviewed source checks, and duplicate quality/dependency audit inside TestPyPI development.
• Privacy: retry diagnostics admit only closed class/phase/status/outcome facts. Raw provider/model data, bodies, codes/messages, IDs, paths, warnings, credentials, stderr, and failed-result findings stay private.
• Unchanged: OCR remains 1.9.10; receipt v5, DLP, telemetry, review outcomes, severity, findings, posting transactions, approval policy, PR security/package gates, TestPyPI provenance/readback, release-PR checks, and the complete stable-release workflow are unchanged.

Release scope

• toolkit target: 0.8.1
• qualified OCR target: 1.9.10
• tracked issues: Canonicalize LLM provider endpoints and publish actionable safe failure diagnostics #129, Expose an optional protocol-aware LLM completion cap #130, and Deduplicate protected CI and release validation stages #132
• exact feature head: 4bfd9fc760143cb707c43aeca4f56db2a3096c13
• exact tree: 4e1e8578b328666ac8c24201e0bd3635c42d5b4f
• status: Draft pending exact-head hosted checks

Operator contract

• openai maps the cap to llm.extra_body.max_completion_tokens.
• openai-responses maps it to max_output_tokens.
• anthropic maps it to max_tokens.
• An equal JSON integer in OCR_LLM_EXTRA_BODY is deduplicated; a conflicting or non-integer field fails configuration.
• /models.max_completion_tokens is not used to choose the cap.
• A safe 429 note treats throttling, spending limits, and requested-output cost reservation as possibilities; it may suggest 4096 without claiming that the cap caused the failure.
• Runtime 404 remains endpoint-or-model-not-found because raw provider text is not trusted to distinguish endpoint from model.

Validation ownership

• Pull requests: five complete functional OS/Python jobs; coverage and four risk floors on Ubuntu Python 3.14; unchanged quality, Security, CodeQL, Dependency Review, and Build artifacts checks.
• Protected main: deterministic TestPyPI development artifact, Twine/smoke, Trusted Publishing, provenance, bounded registry readback, and exact installs. General source and dependency checks are not repeated.
• Release PR: the same protected pre-merge checks remain required.
• Post-merge stable Release: exact authorization, quality, dependency audit, package build, provenance, TestPyPI/PyPI readback, supported-Python installs, tag, immutable Release, and receipt remain unchanged.

The live main ruleset was read back before push: required check contexts and strict protected-head policy still match the unchanged job names.

Exact OCR wire evidence

The official Darwin arm64 OCR 1.9.10 asset was checksum-verified as c626347bafcdbf25cf058af403d16568a3a9ffa1814046ff7c9d1e6becaf60d2 and executed in an isolated no-LLM local-gateway probe through the production configuration path:

• unset cap observed max_completion_tokens=58888;
• explicit cap observed max_completion_tokens=4096;
• the temporary binary, HOME, configuration, repository, result, and receipt paths were removed.

Local validation

• Exact head 4bfd9fc: scripts/quality.sh check passed 1,231 tests + 306 subtests; 86.13% combined branch coverage; risk groups 84% / 82% / 85% / 87% against floors 80 / 80 / 85 / 85; Ruff, mypy, and Bandit passed.
• Focused workflow contract: 46 tests; YAML parsing for all five edited workflows; unchanged required check names; Towncrier 0.8.1 draft and git diff --check passed.
• uv lock --check, OCR manifest validation, and checksum-verified Gitleaks 8.24.3 passed.
• The preceding provider implementation head 53c6374 had byte-identical wheel/sdist builds plus clean Python 3.12-3.14 installs. The workflow-only maintenance commit deliberately does not claim those bytes for the new head; the exact-head Build artifacts check is the package owner.
• Overall provider-boundary, privacy, DLP/approval, telemetry, rollback, validation-ownership, documentation, and public-diff review completed.

Remaining lifecycle

Wait for every hosted check on this exact head. Evidence-driven fixes must pass the same commit gate. After protected feature merge, verify the TestPyPI development build, then prepare the separate protected Release v0.8.1 PR and complete stable registry/GitHub/provenance reconciliation before closing #129, #130, #132, or milestone v0.8.1.