Initial Commit

openspec/specs/emblem-solver/spec.md

@@ -0,0 +1,441 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: emblem-solver (emblem-solver)
+
+**Package**: `@suaveplan/emblem-solver`
+**Status**: SHIPPED
+
+> Every requirement below carries a `**Verified by:**` line at authoring time. No exceptions.
+
+## ADDED Requirements
+
+### Requirement: Stable error code registry
+
+The package SHALL expose `EMBLEM_SOLVER_CODES` created via
+`defineCodes("EMBLEM_SOLVER", [...] as const)` containing exactly the codes
+`INVALID_GRID`, `INVALID_OPTIONS`, `INVALID_PIXEL`. The registry MUST be
+frozen and each value MUST be the namespaced string
+(`EMBLEM_SOLVER.INVALID_GRID`, …).
+
+#### Scenario: registry shape is frozen
+
+- **WHEN** a consumer reads `EMBLEM_SOLVER_CODES`
+- **THEN** the returned object MUST contain all three expected keys with
+  namespaced string values and MUST be `Object.isFrozen`.
+
+**Verified by:** `src/errors/errors.test.ts::"EMBLEM_SOLVER_CODES exposes all three codes"`
+
+---
+
+### Requirement: EmblemSolverError extends SuaveplanError
+
+The package SHALL export `EmblemSolverError extends SuaveplanError<EmblemSolverCode>`.
+Constructing `new EmblemSolverError(EMBLEM_SOLVER_CODES.INVALID_GRID, "msg")`
+MUST yield an instance whose `.code === "EMBLEM_SOLVER.INVALID_GRID"`, whose
+`.message === "msg"`, and which satisfies `instanceof EmblemSolverError`
+AND `instanceof Error`. A `cause` passed in options MUST be preserved.
+
+#### Scenario: round-trips through cause chain
+
+- **WHEN** an `EmblemSolverError` is constructed with `cause: new Error("inner")`
+- **THEN** `error.cause` MUST return the original error and
+  `error.code` MUST preserve the namespaced code.
+
+**Verified by:** `src/errors/errors.test.ts::"EmblemSolverError preserves code and cause"`
+
+---
+
+### Requirement: ConvertOptions Zod validation
+
+The package SHALL expose `ConvertOptionsSchema` (Zod) accepting
+`layerOrder` (enum: `auto | area-desc | area-asc | island-aware | perimeter-desc`,
+default `auto`), `maxPermutations` (integer ≥ 1, default `40320`), and
+optional `rng` (`() => number`). The schema MUST reject unknown keys
+(strict). `convert()` MUST call `safeParse` and on failure throw
+`EmblemSolverError(INVALID_OPTIONS)` whose message embeds the Zod issue list.
+
+#### Scenario: rejects unknown option
+
+- **WHEN** `convert(pixels, w, h, { wibble: 1 } as never)` is invoked
+- **THEN** the call MUST throw `EmblemSolverError` whose `.code` equals
+  `EMBLEM_SOLVER.INVALID_OPTIONS`.
+
+#### Scenario: rejects non-positive maxPermutations
+
+- **WHEN** `convert(pixels, w, h, { maxPermutations: 0 })` is invoked
+- **THEN** the call MUST throw `EmblemSolverError(INVALID_OPTIONS)`.
+
+**Verified by:** `src/schemas/schemas.test.ts::"ConvertOptionsSchema rejects unknown keys"` AND `src/converter/converter.test.ts::"throws INVALID_OPTIONS on bad option"`
+
+---
+
+### Requirement: Grid input validation
+
+The `convert()` entry point SHALL throw
+`EmblemSolverError(EMBLEM_SOLVER_CODES.INVALID_GRID)` when `width ≤ 0`,
+`height ≤ 0`, or `pixels.length !== width * height`. The
+`parseRGBABuffer()` entry point SHALL throw the same error when the supplied
+`Uint8Array` length is not exactly `width * height * 4`.
+
+#### Scenario: width/height mismatch
+
+- **WHEN** `convert([], 2, 2)` is invoked with empty pixels
+- **THEN** the call MUST throw `EmblemSolverError` whose `.code` equals
+  `EMBLEM_SOLVER.INVALID_GRID`.
+
+#### Scenario: buffer length mismatch
+
+- **WHEN** `parseRGBABuffer(new Uint8Array(3), 2, 2)` is invoked
+- **THEN** the call MUST throw `EmblemSolverError(INVALID_GRID)`.
+
+**Verified by:** `src/converter/converter.test.ts::"throws INVALID_GRID on dimension mismatch"` AND `src/io/parse/parse.test.ts::"throws INVALID_GRID on buffer length mismatch"`
+
+---
+
+### Requirement: Public type surface
+
+The package SHALL export the following types verbatim from the package root:
+`RGBA`, `Rect`, `Island`, `ColourAnalysis`, `ColourLayer`, `ConvertOptions`,
+`ConvertResult`, `GridAnalysis`, `Rng`, `EmblemSolverCode`. The shapes MUST
+match the upstream contract (`RGBA.a: 0 | 1`, `Rect: {x,y,w,h}`,
+`Island.pixels: Set<number>`, `ColourAnalysis` includes
+`density`/`fragmentation`/`bounds`/`islands`).
+
+#### Scenario: type re-exports are present
+
+- **WHEN** a TypeScript consumer imports the type set above
+- **THEN** type-checking MUST succeed against the documented shapes.
+
+**Verified by:** `src/types/types.md` AND `src/converter/converter.test.ts::"ConvertResult exposes all documented fields"`
+
+---
+
+### Requirement: Pixel-grid analysis with 4-connected islands
+
+The package SHALL expose `analyseGrid(pixels, width, height)` which produces
+a `GridAnalysis` containing `width`, `height`, `opaquePixels` (a
+`Set<number>` of packed indices), `colourGroups` (a `Map<string, Set<number>>`
+keyed by `"r,g,b"`), and `colourAnalysis` (a `Map<string, ColourAnalysis>`)
+where each entry reports `totalPixels`, `bounds`, `density = pixels / bbox area`,
+`fragmentation = islands / pixels`, and the full `islands` list discovered via
+4-connected BFS flood-fill.
+
+#### Scenario: detects two disjoint islands
+
+- **WHEN** `analyseGrid` runs on a grid where one colour appears in two
+  blocks separated by transparency
+- **THEN** that colour's `islands.length` MUST equal `2`.
+
+#### Scenario: diagonals are not connected
+
+- **WHEN** `analyseGrid` runs on a `[[1,0],[0,1]]` grid
+- **THEN** the only colour's `islands.length` MUST equal `2`.
+
+**Verified by:** `src/grid/analyse/analyse.test.ts::"detects two islands separated by transparency"` AND `src/grid/analyse/analyse.test.ts::"treats diagonal pixels as separate islands (4-connected)"`
+
+---
+
+### Requirement: RGBA buffer + indexed grid IO
+
+The package SHALL expose `parseRGBABuffer(buf, w, h)` returning `RGBA[]` of
+length `w*h` where `a` is quantised to `0 | 1` at the threshold `byte ≥ 128`.
+It SHALL also expose `fromIndexedGrid(grid, palette)` returning
+`{ pixels, width, height }` from a `number[][]` palette map. Index `0` MUST
+map to a fully-transparent pixel (`a === 0`). Indices not present in the
+palette MUST also produce a transparent pixel.
+
+#### Scenario: alpha quantisation rounds half-up
+
+- **WHEN** `parseRGBABuffer` reads a byte with `a = 128`
+- **THEN** the resulting `RGBA.a` MUST equal `1`; for `a = 127` it MUST be `0`.
+
+#### Scenario: indexed grid maps palette correctly
+
+- **WHEN** `fromIndexedGrid([[1,0],[0,2]], {1:r, 2:g})` is called
+- **THEN** result `pixels[0]` MUST be the `r`-colour with `a===1`,
+  `pixels[1]` MUST be transparent, and `pixels[3]` MUST be the `g`-colour.
+
+**Verified by:** `src/io/parse/parse.test.ts::"parseRGBABuffer quantises alpha"` AND `src/io/parse/parse.test.ts::"fromIndexedGrid maps palette indices to RGBA pixels"`
+
+---
+
+### Requirement: Dual-axis histogram maximal-rectangles
+
+The package SHALL expose a `dualAxisMaximalRects(available, rows, cols)`
+solver that enumerates every distinct maximal-rectangle candidate in the
+opaque-pixel grid by combining a normal histogram sweep and a transposed
+sweep. Duplicates MUST be deduplicated by their `(x,y,w,h)` key.
+
+#### Scenario: solid 3x3 produces the full rect
+
+- **WHEN** the input is a 3×3 all-`true` grid
+- **THEN** the returned set MUST include `{x:0,y:0,w:3,h:3}`.
+
+**Verified by:** `src/solver/histogram/histogram.test.ts::"includes the full grid rect for a solid grid"`
+
+---
+
+### Requirement: Strip decomposition picks the smaller axis
+
+The package SHALL expose `stripDecomposition(required, rows, cols)` that
+computes maximal horizontal strips (and the transposed vertical variant)
+where same-extent + adjacent runs merge, and returns whichever orientation
+yields fewer rects.
+
+#### Scenario: tall vertical strip beats horizontal runs
+
+- **WHEN** the required mask is a single column of height `5`
+- **THEN** the returned strips MUST contain exactly one rect of width `1` and height `5`.
+
+**Verified by:** `src/solver/strip/strip.test.ts::"single column produces one vertical strip"`
+
+---
+
+### Requirement: Enhanced greedy set-cover with three-key tiebreak
+
+The package SHALL expose `enhancedGreedyCover(candidates, required, w, h)`
+that selects rects to cover the required mask using a deterministic score
+of `covered*1000 + efficiency*100 + proximity*10`. When no rect overlaps the
+remaining uncovered pixels, the function MUST fall back to emitting 1×1 rects
+for the residual.
+
+#### Scenario: empty required returns no rects
+
+- **WHEN** all entries of `required` are `false`
+- **THEN** `enhancedGreedyCover` MUST return an empty array.
+
+**Verified by:** `src/solver/greedy/greedy.test.ts::"returns empty array when nothing is required"`
+
+---
+
+### Requirement: Per-island independent cover
+
+The package SHALL expose `perIslandCover(islands, candidates, w, h)` that
+runs `enhancedGreedyCover` independently on each island's local required
+mask, restricting candidates to those that touch the island.
+
+#### Scenario: independent covers don't span islands
+
+- **WHEN** two 2×2 islands are separated by transparency
+- **THEN** `perIslandCover` MUST produce at least two rects, one per island,
+  and no rect MUST span the transparent gap.
+
+**Verified by:** `src/solver/greedy/greedy.test.ts::"covers two islands without spanning the gap"`
+
+---
+
+### Requirement: Layer-ordering search
+
+The package SHALL expose `getStaticOrdering(analysis, strategy)` for the
+strategies `area-desc`, `area-asc`, `island-aware`, `perimeter-desc`, and
+`permutations<T>(arr)` implementing Heap's algorithm yielding `n!`
+permutations including the identity, and `factorial(n)` returning the
+mathematical factorial with `factorial(0) === factorial(1) === 1`.
+
+#### Scenario: permutations yields n! arrays in total
+
+- **WHEN** `permutations(["a","b","c"])` is fully iterated
+- **THEN** the iteration MUST emit exactly `6` arrays.
+
+#### Scenario: factorial agrees with the definition
+
+- **WHEN** `factorial(5)` is called
+- **THEN** the return value MUST equal `120`.
+
+**Verified by:** `src/solver/ordering/ordering.test.ts::"permutations yields n! arrays"` AND `src/solver/ordering/ordering.test.ts::"factorial matches the standard definition"`
+
+---
+
+### Requirement: Multi-strategy layer processor
+
+The package SHALL expose `processLayerMultiStrategy(key, ownPixels,
+analysis, earlierPixels)` that runs the four covering strategies
+(dual-axis-histogram + greedy, per-island, strip decomposition where it
+fully covers, and a merge pass on the best so far) and returns the rect
+list with the smallest cardinality.
+
+#### Scenario: returns a valid cover
+
+- **WHEN** the layer processor runs on the upstream `cross3x3` fixture's
+  red pixels
+- **THEN** the returned rect list MUST cover every required red pixel and
+  MUST contain at most `2` rects.
+
+**Verified by:** `src/solver/layer/layer.test.ts::"cross3x3 produces at most 2 rects"`
+
+---
+
+### Requirement: Adjacent-rect merge optimisation
+
+The package SHALL expose `mergeAdjacentRects(rects, available)` which
+combines edge-sharing same-extent rect pairs into a single larger rect
+provided the merged span is fully `available`. The function MUST iterate
+until no further merge is possible.
+
+#### Scenario: two adjacent unit squares merge
+
+- **WHEN** `mergeAdjacentRects([{0,0,1,1},{1,0,1,1}], all-available)` runs
+- **THEN** the output MUST be exactly `[{0,0,2,1}]`.
+
+**Verified by:** `src/optimizer/merge/merge.test.ts::"merges two horizontally adjacent unit squares"`
+
+---
+
+### Requirement: Overlap optimiser
+
+The package SHALL expose `optimiseOverlap(rects, required, available, rows,
+cols)` that (1) merges pairs whose bbox is fully available and whose union
+covers no more than the original required pixels, (2) extends a rect to
+subsume another while remaining inside `available`, and (3) replaces a
+triple of rects with a 2-rect cross/T/L pattern when one exists.
+
+#### Scenario: cross 3x3 reduces to two rects
+
+- **WHEN** `convert` runs on the upstream `cross3x3` fixture
+- **THEN** `ConvertResult.totalRects` MUST be at most `2`.
+
+**Verified by:** `src/optimizer/overlap/overlap.test.ts::"reduces a 3-rect L to 2 rects"` AND `src/converter/converter.test.ts::"cross 3x3 reduces to <=2 rects"`
+
+---
+
+### Requirement: Cross-layer redundancy elimination
+
+The package SHALL expose `eliminateRedundant(layers, width, height)` which,
+given a list of `ColourLayer` objects, removes any rect whose pixels are
+either fully occluded by higher-z layers (of any colour) or already covered
+by sibling rects in the same layer.
+
+#### Scenario: fully-occluded rect is removed
+
+- **WHEN** layer 0 contains a 4×4 red rect at (0,0) and layer 1 contains a
+  4×4 blue rect at (0,0)
+- **THEN** after `eliminateRedundant` layer 0 MUST have zero rects.
+
+**Verified by:** `src/optimizer/redundancy/redundancy.test.ts::"removes a fully-occluded rect"`
+
+---
+
+### Requirement: SVG emission
+
+The package SHALL expose `buildSVG(layers, width, height)` returning a string
+that begins with `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 W H"
+shape-rendering="crispEdges">` and ends with `</svg>`, contains one `<rect>`
+per layer-rect with `fill="rgb(r,g,b)"`, and renders layers in `zIndex`
+ascending order.
+
+#### Scenario: empty layer list produces an empty viewBox svg
+
+- **WHEN** `buildSVG([], 4, 4)` is invoked
+- **THEN** the result MUST contain `viewBox="0 0 4 4"` and zero `<rect>` tags.
+
+**Verified by:** `src/svg/build/build.test.ts::"empty layers yields a rect-free svg"`
+
+---
+
+### Requirement: Public `convert()` orchestrator
+
+The package SHALL expose `convert(pixels, width, height, options?)`. The
+function MUST (1) parse `options` via `ConvertOptionsSchema`, (2) call
+`analyseGrid`, (3) early-return an empty result for fully-transparent input,
+(4) explore orderings (exhaustive for `colourCount! ≤ maxPermutations`;
+heuristics + ≤ 1000 RNG-driven samples otherwise), (5) pick the ordering
+with the smallest `totalRects`, (6) emit the SVG via `buildSVG`, and (7)
+return `{ svg, layers, totalRects, naiveRects, ratio, orderingUsed,
+orderingsEvaluated, colourAnalysis }`.
+
+#### Scenario: chessboard 8x8 ≤ 33 rects
+
+- **WHEN** `convert` runs on the upstream `chessboard8x8` fixture
+- **THEN** `result.totalRects ≤ 33`.
+
+#### Scenario: solid grid produces exactly one rect
+
+- **WHEN** `convert` runs on a 4×4 solid-red grid
+- **THEN** `result.totalRects === 1`.
+
+#### Scenario: fully transparent grid produces zero rects
+
+- **WHEN** `convert` runs on a 4×4 fully-transparent grid
+- **THEN** `result.totalRects === 0` and `result.layers` MUST be empty.
+
+#### Scenario: shield emblem 32x32 compresses > 50x
+
+- **WHEN** `convert` runs on the upstream `shieldEmblem32` fixture
+- **THEN** `result.ratio > 50`.
+
+**Verified by:** `src/converter/converter.test.ts::"chessboard 8x8: ≤33 rects"` AND `src/converter/converter.test.ts::"solid colour 4x4 = 1 rect"` AND `src/converter/converter.test.ts::"fully transparent = 0 rects"` AND `src/converter/converter.test.ts::"shield emblem 32x32 ratio > 50"`
+
+---
+
+### Requirement: Injectable Rng for deterministic auto-ordering
+
+`convert()` SHALL accept an optional `rng: () => number` in its options. The
+heuristics-plus-sampling branch (entered when `colourCount! > maxPermutations`)
+MUST consume the injected `rng` for every Fisher–Yates shuffle step, falling
+back to `Math.random` only when no `rng` is supplied. The same seeded `rng`
+MUST yield byte-identical `ConvertResult.svg` across runs.
+
+#### Scenario: seeded rng yields deterministic output
+
+- **WHEN** `convert` runs twice on the same > 8-colour fixture with the same
+  seeded mulberry32 `rng`
+- **THEN** the two `ConvertResult.svg` strings MUST be identical.
+
+**Verified by:** `src/converter/converter.test.ts::"seeded rng yields deterministic auto output"`
+
+---
+
+### Requirement: OpenTelemetry instrumentation
+
+`convert()` SHALL emit an OTel counter
+`emblem_solver.convert.total` (incremented once per call) and a histogram
+`emblem_solver.convert.duration_ms` (one observation per call, unit `ms`).
+Instruments MUST be created lazily on first call (no module-load side
+effects) using `metrics.getMeter("@suaveplan/emblem-solver")`.
+
+#### Scenario: no instrument is registered before the first call
+
+- **WHEN** the module is imported but `convert` has not been called
+- **THEN** internal `counter`/`histogram` references MUST remain `undefined`.
+
+#### Scenario: first call registers both instruments
+
+- **WHEN** `convert` is invoked once
+- **THEN** the internal `counter` and `histogram` MUST be defined and the
+  counter MUST have been incremented by `1`.
+
+**Verified by:** `src/telemetry/telemetry.test.ts::"instruments are lazily registered"` AND `src/telemetry/telemetry.test.ts::"convert increments counter and records duration"`
+
+---
+
+### Requirement: Tree-shakeable subpath exports
+
+The package's `package.json` SHALL expose `./types`, `./errors`,
+`./schemas`, `./grid`, `./io`, `./svg`, `./solver`, and `./optimizer`
+subpath exports in addition to the root entry, each pointing at a feature
+barrel. `sideEffects` MUST be `false`.
+
+#### Scenario: each subpath is importable
+
+- **WHEN** a consumer imports `@suaveplan/emblem-solver/errors`
+- **THEN** the import MUST resolve and expose `EmblemSolverError` and
+  `EMBLEM_SOLVER_CODES`.
+
+**Verified by:** `src/errors/errors.test.ts::"errors subpath barrel re-exports the public surface"`
+
+---
+
+### Requirement: Property-based coverage correctness
+
+A property test SHALL assert that for arbitrary single-colour pixel grids
+generated via `fast-check`, the `convert()` output satisfies: (a) every
+opaque pixel in the input is covered by at least one rect in the
+corresponding layer, and (b) no rect's footprint extends beyond the grid
+bounds.
+
+#### Scenario: random solid-colour grid round-trip
+
+- **WHEN** `fast-check` generates 50 random grids of width/height in `[1, 12]`
+- **THEN** every required pixel MUST be covered by at least one rect.
+
+**Verified by:** `src/converter/converter.test.ts::"property: every opaque pixel is covered"`