Initial Commit

openspec/archive/2026-05-21-enterprise-image-quantisation/proposal.md

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