Initial Commit

openspec/archive/2026-04-19-enterprise-barcode/specs/barcode/spec.md

@@ -0,0 +1,41 @@
+# 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.