suaveplan/openspec/archive/2026-05-25-enterprise-media/proposal.md

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.