# BOS Form Mapper

The Form Mapper is the authoring layer for machine-readable BOS forms. It is intentionally separate from OMRChecker and from competition scoring logic.

## Ownership

- **B360 Superadmin** is the authenticated management UI.
- **BubbleScan OMR Services (BOS)** owns form definitions, compilation, validation, registry entries, test fixtures, preprocessing, and OMR execution.
- **OMRChecker** receives compiled `template.json` files and does not contain customer scoring semantics.

## Authoring workflow

1. Upload a final PDF whose geometry is fixed and whose QR contains `BF######`.
2. BOS decodes the QR and opens or creates that form definition.
3. Define logical fields explicitly. Never infer logical grouping from a visual grid.
4. Map bubble centers visually on the PDF.
5. Validate field semantics and geometry.
6. Preview every recognition ROI before compiling.
7. Compile the editable BOS definition to OMRChecker `template.json`.
8. Mark known-answer sheets, capture scanner/phone fixtures, and run regression testing.
9. Freeze an accepted form version; geometry changes after acceptance require a new BF ID.

## Logical field types

- `required_single`: exactly one mapped value is expected.
- `optional_single`: zero or one mapped value is allowed. Blank means no mark.
- `checkbox`: one independent bubble; blank/marked are separate outcomes.
- `digit`: one 0-9 digit column. Multiple digit columns are separate logical fields.
- `control`: known calibration field, normally blank/filled/blank or another explicit expected value.

## Critical rule: visual grids do not define fields

For example, a 5-cone area drawn as five columns of `5 / 10` bubbles is **five logical fields**:

- `p1_cone_1`: blank / 5 / 10
- `p1_cone_2`: blank / 5 / 10
- `p1_cone_3`: blank / 5 / 10
- `p1_cone_4`: blank / 5 / 10
- `p1_cone_5`: blank / 5 / 10

It is not one ten-bubble field.

## Mapper UI behavior planned for B360 Superadmin

The UI should reuse the PDF-coordinate interaction pattern from the Overlay Mapper while authoring BOS-owned definitions through a service/API boundary. It should support:

- click-to-map bubble centers;
- field name, display label, field type, values, blank behavior, and multi-mark behavior;
- duplicate right/down and repeat-grid helpers;
- explicit per-field preview overlays;
- protected-ROI warnings when non-bubble artwork is too close;
- compile/validate action with readable errors;
- fixture status and regression history.

The editable mapper definition is the source of truth. Generated OMRChecker JSON is a compiled artifact and should not be hand-edited in normal use.