docs/adr/0001-verified-ocr-aware-quantization.md

ADR-0001: Build a Verified Checkpoint from BF16 and Publish Fail-Closed

Status: Accepted
Date: 2026-07-20

Context

The project currently references sahilchachra/unlimited-ocr-mxfp8-mlx as its weight source. That checkpoint is already MXFP8. Re-uploading it with different configuration or pipeline files improves runtime behavior but is not a new weight optimization.

The existing repository also contains sensitivity and mixed-precision scripts, but measured overrides have not been generated and the legacy upload workflow does not require proof that candidate weights differ from the source.

Decision

We will:

1. Use the upstream Baidu BF16 checkpoint as the only valid source for sensitivity analysis and final conversion.
2. Use the Sahil MXFP8 checkpoint only as a comparative reference.
3. Generate the precision map from measured group-level OCR deltas.
4. Preserve high-risk optical and routing components in BF16 by default.
5. Quantize eligible language-tower linear modules to block-float MXFP8 with group size 32.
6. Select the native unlimited-ocr MLX backend so R-SWA uses its bounded ring/sliding cache rather than a legacy DeepSeek-OCR fallback.
7. Generate a signed-by-content release manifest containing hashes, versions, metrics, and explicit pass/fail gates.
8. Make publication fail-closed: no approved manifest means no upload.
9. Publish under a new, provenance-clear repository: AutomatosX/AX-Unlimited-OCR-3B-MoE-MLX-MXFP8.

Sensitivity policy

A module group is retained in BF16 when any of these conditions is true:

• CER delta is greater than 0.02 absolute.
• Digit-CER delta is greater than 0.02 absolute.
• Table-score degradation is greater than 0.01 absolute.
• The group could not be measured reliably.
• It belongs to the protected optical/routing set.

Concrete exact-path overrides take precedence over wildcard MXFP8 rules.

Alternatives considered

Repackage the Sahil checkpoint

Rejected as the primary release path. It is useful for runtime tooling, but its weights are not an AutomatosX optimization.

Re-quantize the Sahil checkpoint

Rejected. Quantizing already quantized weights compounds error and prevents a clean BF16 comparison.

Uniform MXFP8 from BF16

Rejected as the final product because it does not use OCR sensitivity evidence. It remains a useful control candidate.

Per-layer exhaustive search

Deferred. It provides finer control but multiplies evaluation cost. Group-level analysis is the first release; the data contract keeps concrete module paths so a later release can promote individual layers.

Publish first and benchmark later

Rejected. It would recreate the current ambiguity and allow unsupported claims.

Consequences

Positive:

• The published checkpoint is demonstrably distinct and reproducible.
• Quality claims are tied to recorded evidence.
• Runtime improvements and weight improvements are clearly separated.
• A broken or incomplete benchmark cannot accidentally publish a model.

Negative:

• Release requires a representative evaluation dataset and Metal-capable Mac.
• Sensitivity analysis is compute intensive.
• Conservative BF16 retention may produce a larger model than uniform MXFP8.
• A failed R-SWA or accuracy gate intentionally delays publication.