# Capability Spec: barcode

**Package**: `@suaveplan/barcode`
**Version**: 0.0.0 (genesis)
**Status**: ADDED

---

## ADDED Requirements

### BC-01 — Supported formats

The package MUST implement encoders (and where image decoding applies, decoders) for Code 39, Code 93, Code 128, ITF, EAN-13, UPC-A, Data Matrix, PDF417. `VALID_FORMATS` MUST enumerate these.

### BC-02 — Encoder contract

`BarcodeGenerator.generate(data, options)` MUST validate the input characters for the chosen format, compute any required check digit (EAN-13, UPC-A, ITF via `calculateItfCheckDigit`), and return `BarcodeResult { bars, width, height, svg?, png? }`. Unsupported characters MUST throw `BARCODE.UNSUPPORTED_CHARACTER`.

### BC-03 — Reader contract

`readBarcode(image)` MUST accept `Uint8Array`, `ImageData`, `Blob`, or `File` and return `ReadResult { format, data, confidence }`. Decode failures MUST throw `BARCODE.DECODE_FAILED`.

### BC-04 — Check-digit helpers

`calculateEan13CheckDigit(digits)` and `calculateUpcaCheckDigit(digits)` MUST compute standard GTIN-13 / GTIN-12 mod-10 check digits. Round-trip tests MUST cover each.

### BC-05 — Batch

`generateBatch(items, options)` MUST return `BatchResult { succeeded, failed, total, items }`. Partial failure MUST NOT abort the batch; each failed item MUST carry its original error.

### BC-06 — Data Matrix

`encodeDataMatrix(data, options)` MUST choose the minimum square symbol size that fits the payload and emit the corresponding Reed-Solomon error-correction codewords.

### BC-07 — PDF417

`encodePdf417(data, options)` MUST accept `errorCorrectionLevel` 0–8 per the PDF417 specification. The encoder MUST emit valid start/stop patterns and row indicators.

### BC-08 — Observability

Each encode / decode MUST record `barcode.encode.total{format, outcome}` or `barcode.decode.total{format, outcome}` and the corresponding duration histogram.