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.