suaveplan/openspec/changes/barcode-batch-generator/proposal.md

# Barcode batch generator

**Package**: `@suaveplan/barcode`
**Status**: PROPOSED
**Type**: spec-conformance + feature

## Why

The 2026-05-02 audit of `@suaveplan/barcode` against legacy `packages/universal/barcode/src/` found that genesis ships only the single-call generator surface (`encode`, `renderSvg`, the per-symbology helpers, `validateBarcode`). Legacy ships a full `batch/batch-generator.ts` (`generateBatch(items, options): Promise<BatchResult>`) used by every consumer that needs to produce ten or ten-thousand barcodes in one pass — bulk-label printing, ticketing, asset registers, and inventory imports all rely on it. CLAUDE.md scopes this package as "generator only" (barcode reading is intentionally out of scope), but the batch generator is part of the generator surface, not the reader. Its absence forces every consumer to re-implement an error-isolating loop in user code, which is exactly the duplication §0a (migration parity) was written to prevent.

## What changes

- ADDED: `BatchBarcodeRequest` interface — `{ id?: string; symbology: BarcodeSymbology; value: string; options?: BarcodeOptions }`. Per-item `id` is optional; when omitted the request index is used as the result key.
- ADDED: `BatchBarcodeResult` discriminated union — `{ id: string; index: number; ok: true; result: BarcodeResult } | { id: string; index: number; ok: false; error: BarcodeError }`. Failed items carry a coded `BarcodeError`, never a bare string.
- ADDED: `BatchBarcodeOptions` interface — `{ concurrency?: number; signal?: AbortSignal; onItem?: (result: BatchBarcodeResult) => void }`. `concurrency` defaults to `1` (sequential) and is clamped to `[1, 64]`.
- ADDED: `BatchBarcodeSummary` interface — `{ total: number; succeeded: number; failed: number; durationMs: number; results: BatchBarcodeResult[] }`. `durationMs` uses an injectable `Clock` (defaults to `performance.now()` shim) so tests stay deterministic.
- ADDED: `generateBatch(requests, options?): Promise<BatchBarcodeSummary>` — produces one `BatchBarcodeResult` per input request in input order; per-item failures are isolated (a thrown encode error becomes `{ ok: false, error }`, every other item keeps generating).
- ADDED: `BatchBarcodeGenerator` class — `class BatchBarcodeGenerator { constructor(deps?: { clock?: Clock }); generate(requests, options?): Promise<BatchBarcodeSummary> }` for callers that want to inject a deterministic clock or share a generator across calls.
- ADDED: subpath export `./batch` mapping to `dist/core/batch/batch-generator.js`.
- ADDED: error code `BARCODE.BATCH_ABORTED` registered on `BARCODE_CODES`, thrown when the supplied `AbortSignal` fires before completion.

## Out of scope

- **Barcode reading / decoding** — explicitly out of scope per CLAUDE.md package description ("generator only"). Tracked separately under a future `barcode-reader-port` change if business requirements ever demand it. Not deferred for "complexity" reasons; deferred because the package contract intentionally excludes it.
- **2D symbologies (DataMatrix, PDF417, Aztec)** — not in legacy upstream either; would be its own package.
- **Streaming / async-iterable batch API** — `generateBatch` returns a single resolved summary. A streaming variant would let callers consume results as they emit (useful for very large batches, > 10 000 items). Punted because no current consumer needs it; the `onItem` callback covers the common "show progress" case.

## Source mapping

This change derives from `../suaveplan/packages/universal/barcode/src/batch/`.

| Requirement | Source lines | Notes |
|---|---|---|
| `BatchBarcodeRequest` shape | `batch/batch-generator.ts` L9-L13 | Reworded: `data` → `value`; added optional `id` |
| `BatchBarcodeResult` discriminated union | `batch/batch-generator.ts` L16-L21 | Reworded: legacy returns `{ index, result?, svg?, error?: string }`; new shape uses a discriminated union with coded `BarcodeError` instead of a string |
| `BatchBarcodeOptions` shape with `concurrency`, `signal`, `onItem` | `batch/batch-generator.ts` L24-L28 | Extended: legacy has `outputFormat` and `onProgress`; new shape replaces `onProgress` with `onItem` (richer payload), drops `outputFormat` (caller picks via `options.includeText`/SVG availability already on `BarcodeResult`), adds `concurrency` and `signal` |
| `generateBatch` function | `batch/batch-generator.ts` L42-L95 | Verbatim semantics — per-item failure isolation, sequential default, in-input-order results |
| `BatchBarcodeGenerator` class | (no source line) | New: legacy is a free function only; class is added for clock injection |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `BatchBarcodeGenerator` class with injectable `Clock` | Genesis-wide CLAUDE.md determinism rule (`enterprise/bitpacker.md` L40 "no module-scope `Date.now()`"). Legacy reads `Date.now()` implicitly through `performance.now`; genesis routes through `@suaveplan/types::Clock`. |
| `BARCODE.BATCH_ABORTED` error code on `BARCODE_CODES` | CLAUDE.md §Workflow rule 2 — every thrown error routes through `@suaveplan/error` with a stable code. Legacy throws a plain `Error("aborted")` from the loop. |
| `concurrency` clamping to `[1, 64]` | Genesis-wide guardrail — unbounded `Promise.all` over user input is a denial-of-service vector. Legacy ships sequential only (concurrency 1) so the clamp is additive. |

## Verification approach

- `src/core/batch/batch-generator.test.ts` — covers `BatchBarcodeRequest` validation, in-order results, per-item failure isolation, `concurrency` clamping, `onItem` callback invocation, abort-via-`AbortSignal`, sequential-vs-concurrent equivalence on success-only inputs.
- `src/core/batch/batch-generator.spec-conformance.test.ts` — pins injectable `Clock` (deterministic `durationMs`), Zod-validated `BatchBarcodeRequest` shape, `BARCODE.BATCH_ABORTED` error code emission, OTel counter `barcode.batch.items_total` / `barcode.batch.items_failed` recorded against an in-memory `MeterProvider`.

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/barcode` to enumerate. As of 2026-05-02 there are no in-repo dependents:

- No dependents (verified by `grep -rl "@suaveplan/barcode" /home/ubuntu/web/genesis/packages/ --include="package.json"` returning only `packages/barcode/barcode/package.json` itself).

This change is purely additive (new exports, no signature changes to existing surface), so the absence of dependents is not a risk gate.

## Migration impact

None — additive only. Existing single-call surface (`encode`, `renderSvg`, `validateBarcode`, per-symbology encoders) is unchanged. Consumers wanting batch generation opt in by importing `generateBatch` from `@suaveplan/barcode` or `@suaveplan/barcode/batch`.