# Change: enterprise-media

- **Package**: `@suaveplan/media`
- **Status**: PROPOSED
- **Design**: ./design.md
- **Spec delta**: ./specs/media/spec.md
- **Upstream**: `/mnt/s/web/suaveplan/packages/universal/media` (1.1.0)
- **Enterprise audit**: `/mnt/s/web/suaveplan/enterprise/media.md`

## Why

Genesis is migrating `@suaveplan/media` from the legacy
`packages/universal/media/` checkout into the canonical
`packages/foundation/data/media/` location alongside the already-shipped
`@suaveplan/mime`. The upstream package shipped at 1.1.0 as a ~140-line
universal-tier facade over four functions — `detectMediaType` (magic
bytes), `detectMediaTypeFromName` (MIME lookup), `getMetadata`, and
`validateMedia`. The enterprise audit (`enterprise/media.md`) flagged
the gaps shared by every pre-enterprise package:

1. Hand-rolled error strings — no `@suaveplan/error` integration, no
   stable codes, no programmatic discrimination.
2. No Zod validation of `MediaConstraints` — malformed input silently
   passes through.
3. No OpenTelemetry instrumentation — production cannot measure
   detection / metadata / validation volume, latency, or error rate.
4. Magic-byte signatures hard-coded inside the implementation — no
   extension point for downstream packages to add formats like AVIF,
   HEIC, or M4A.
5. No async metadata extractor hook — width / height / duration / codec
   extraction has to happen outside the package.
6. No custom-predicate constraint — non-trivial business rules cannot
   be expressed.
7. No throwing assert variant for guard sites.
8. No filename-MIME refinement when both bytes and filename are
   available.
9. No `signatureLabel` surfacing — consumers cannot route on the exact
   matched format.

The greenfield rewrite addresses every gap while preserving every
upstream public symbol so downstream consumers continue to compile
against the same import paths.

## What changes

- **Add**: `@suaveplan/media` at version `0.1.0` under
  `packages/foundation/data/media/` with full enterprise surface — typed
  errors via `@suaveplan/error`, OTel counters + histograms,
  Zod-validated constraints, pluggable `SignatureRegistry`, async
  metadata extractor hook, custom predicate support, async + assert
  validation variants, filename + bytes MIME resolution, canonical MIME
  inference from signature label.
- **Add**: error-code namespace `MEDIA.*` with eight stable codes
  (`EMPTY_INPUT`, `INVALID_CONSTRAINTS`, `VALIDATION_FAILED`,
  `UNSUPPORTED_TYPE`, `PREDICATE_FAILED`, `DUPLICATE_SIGNATURE`,
  `METADATA_EXTRACTOR_FAILED`, `INVALID_SIGNATURE`).
- **Add**: OTel instruments — counters `media_detect_total`,
  `media_metadata_total`, `media_validate_total`, `media_error_total`
  and histograms `media_op_latency_ms`, `media_input_size_bytes`.
- **Add**: subpath exports per feature module
  (`./detection/detection`, `./metadata/metadata`,
  `./validation/validation`, `./errors/errors`,
  `./observability/observability`, `./signatures/signatures`,
  `./types`).
- **Add**: `media` to the `data` plugin in
  `scripts/folder-reorg/assignment.yml`.

## Impact

### Affected dependents

`bunx turbo ls --filter=...@suaveplan/media` — empty (media is a leaf
migration; no current genesis package depends on it).

## Parity Checklist

| Capability                                                          | Upstream | Migrated | Notes                                                                            |
| ------------------------------------------------------------------- | -------- | -------- | -------------------------------------------------------------------------------- |
| `detectMediaType(bytes)`                                            | yes      | yes      | Now routes through pluggable `SignatureRegistry`.                                |
| `detectMediaTypeFromName(filename)`                                 | yes      | yes      | Same MIME-bucket semantics; emits counter + latency.                             |
| `getMetadata(bytes, filename?)`                                     | yes      | yes      | Adds `signatureLabel`; MIME refines to filename when present.                    |
| `validateMedia(bytes, constraints, filename?)`                      | yes      | yes      | Now Zod-validated; reports MIME / minSize / minWidth / minHeight / maxDuration.  |
| `MediaType` / `MediaMetadata` / `MediaConstraints` / `MediaResult`  | yes      | yes      | Preserved; `MediaConstraints` extended with new fields.                          |
| Pluggable signatures                                                | no       | yes      | New `SignatureRegistry` class + `defaultSignatureRegistry`.                      |
| Async metadata extractor                                            | no       | yes      | New `getMetadataAsync` + `MediaMetadataExtractor` hook.                          |
| Async validation predicate                                          | no       | yes      | New `validateMediaAsync` runs `constraints.predicate`.                           |
| Throwing assert variant                                             | no       | yes      | New `assertValidMedia`.                                                          |
| Typed errors                                                        | no       | yes      | `MediaError` + `MEDIA_CODES` + per-code metadata.                                |
| OTel instrumentation                                                | no       | yes      | Four counters + two histograms.                                                  |