@render-lab/media-contract

⚠️ Experimental: proof of concept. This package is part of the Render Tasks POC and is published for testing only. It is not fully tested or production ready. Task names, inputs, outputs, and behavior can change or break in any release. Pin exact versions and expect breaking changes.

The bounded media handoff contract shared by Render task packs. It is a registration-free contract library: it defines no tasks, never calls task(), holds no vendor SDK or credentials, and makes no network calls. See ADR-0022.

Why it exists

Voice, image, and video vendors exchange binary artifacts. A workflow argument or result cannot exceed the 4 MB platform limit, and copying media shapes into each vendor pack would let them drift apart and break composition. This package owns one JSON-safe vocabulary so a Replicate output URL, an ElevenLabs narration, and a Cloudinary upload all describe media the same way.

Generic byte-limit mechanism lives in @render-lab/tasks-core. This package layers media-specific policy on top: the 1 MiB inline cap and the URL / signed-PUT default handoff.

The handoff

• URL sources and signed PUT destinations are the default. Large media never enters a task boundary as bytes.
• Data URIs and base64 results are allowed only up to MAX_INLINE_MEDIA_BYTES (1,048,576 bytes) decoded. Anything larger must use a URL result or a signed PUT destination.
• Every transfer has an explicit byte limit. A task rejects an oversized source or result rather than truncating binary.

MediaSource describes task input only. Task results use MediaResult, so an expired output URL can never be mistaken for a reusable input. MediaDestination.reference is a caller-chosen, nonsecret identifier such as a storage key; uploaded results echo that reference and never the signed URL.

Exports

Constants: MAX_INLINE_MEDIA_BYTES, DEFAULT_TRANSFER_MAX_BYTES.

Types: MediaSource (UrlMediaSource | DataUriMediaSource), MediaDestination, MediaMetadata, MediaResult (UrlMediaResult | Base64MediaResult | UploadedMediaResult).

Validators: assertMediaSource, assertMediaDestination, assertInlineByteCount.

Adding a variant

Adding a new source or destination variant is a contract change: update ADR-0022 and add exhaustive handling in every consuming pack.