# OpenSpec Change: enterprise-image-quantisation

- **Change ID**: enterprise-image-quantisation
- **Package**: `@suaveplan/image-quantisation`
- **Category**: media / image
- **Target path**: `packages/media/image/image-quantisation`
- **Status**: PROPOSED
- **Date**: 2026-05-21
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/image-quantisation.md`
- **Design**: ./design.md (not required for migration)
- **Spec delta**: ./specs/image-quantisation/spec.md

---

## Summary

Migrate `@suaveplan/image-quantisation` from `../suaveplan/packages/universal/image-quantisation/` into genesis at enterprise quality. Preserve the full upstream public API while adding Zod validation, structured errors, OTel instrumentation, property-based tests, and 100% coverage.

---

## Current-state audit (genesis)

The package did not exist on genesis prior to this change. This is a fresh migration.

---

## Source mapping

| Requirement | Source lines | Notes |
|---|---|---|
| Zero workspace deps | N/A | upstream used `tslib` + `image-q` only |
| OTel adapter | N/A | genesis-wide enhancement |
| Zod schemas | N/A | genesis-wide enhancement |
| `defineCodes` error registry | N/A | genesis-wide enhancement |
| 100% coverage | N/A | genesis-wide policy |
| Pool detection | upstream `src/analysis/pools.ts` | verbatim algorithm, restructured |
| Edge analysis | upstream `src/analysis/edges.ts` | verbatim algorithm, added 1×1 test |
| Complexity classification | upstream `src/analysis/classify.ts` | verbatim heuristics, clamped min colours |
| Quantisation | upstream `src/quantise/quantise.ts` | preserved `image-q` wrapper, added Zod + OTel |
| Adaptive pipeline | upstream `src/pipeline.ts` | preserved logic, added Zod + OTel |
| Spatial cleanup | upstream `src/spatial/cleanup.ts` | preserved logic, removed unreachable guard |

---

## Parity Checklist

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| `analyseComplexity` | ✅ | ✅ | |
| `detectPools` | ✅ | ✅ | |
| `poolDistribution` | ✅ | ✅ | |
| `analyseEdges` | ✅ | ✅ | |
| `colourKey` / `parseColourKey` | ✅ | ✅ | |
| `rgbDistance` / `weightedDistance` | ✅ | ✅ | |
| `quantise` | ✅ | ✅ | Added Zod validation + OTel |
| `quantiseAdaptive` | ✅ | ✅ | |
| `spatialCleanup` | ✅ | ✅ | |
| `countUniqueColours` | ✅ | ✅ | |
| `adaptivePipeline` | ✅ | ✅ | Added Zod validation + OTel |
| Zod schemas | 🚫 | ✅ | Genesis enhancement |
| OTel instrumentation | 🚫 | ✅ | Genesis enhancement |
| Structured errors | 🚫 | ✅ | Genesis enhancement |
| Property-based tests | 🚫 | ✅ | Genesis enhancement |
| 100% coverage | 🚫 | ✅ | Genesis enhancement |

---

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/image-quantisation` to enumerate.

- No dependents currently in genesis (verified by turbo ls).

---

## Deferred

None.