AI Provider Runtime Contract Protocol

Candidate: ai-provider-runtime-contract

Target owner: future-shared-package

Target package: ai-media-product-kit/packages/runtime

Purpose

This protocol freezes the portable runtime contract for image and media providers before any provider code moves out of this vertical template. The goal is to let future AI media products reuse the same descriptor, input policy, result normalization, provider readiness, and canary evidence shape without inheriting one product's prompts, model choices, public copy, or provider credentials.

This is a contract freeze only. Runtime adapters stay product-local until a second AI or media template proves the same lifecycle with different product identity and model configuration.

Shared Contract

The future media runtime package should own schemas and validators for:

• provider descriptors
• provider capability flags
• media input policies
• completed result envelopes
• submitted async job envelopes
• pending collection envelopes
• provider failure categories
• provider readiness and canary evidence summaries

The shared contract may define result kinds, capability labels, media policy field names, public failure categories, and secret-free evidence shapes. It must not define provider SDK calls, model request bodies, prompt builders, provider credentials, account bindings, public plan packaging, or product copy.

Provider Descriptor Boundary

A portable descriptor can include:

• provider id and display name
• model label or model family label
• runtime adapter id
• capability flags for collection, webhook completion, multiple outputs, and gateway logging
• input policy for accepted MIME types, maximum bytes, maximum dimension, transport, encoded request cap, output MIME type, and output quality
• readiness labels for matrix, smoke, and canary reports

Product adapters keep:

• concrete model ids and version pins
• provider SDK clients and credentials
• provider-specific input mapping
• prompt and negative-prompt construction
• environment variable names and Wrangler target shape
• provider selection copy

Runtime Result Boundary

The shared runtime can normalize these result shapes:

• completed: one or more media outputs with public-safe metadata
• submitted: an async provider job reference plus optional poll hint
• pending: collection did not finish yet plus optional poll hint
• failed: a public failure category separated from provider response bodies

Browser payloads and release evidence must not expose raw provider execution ids, gateway metadata, storage keys, private URLs, request payloads, image bytes, or token values.

Product Adapters

Each product template keeps adapters for:

• building provider requests
• mapping provider outputs into normalized output envelopes
• classifying provider-specific errors
• collecting async jobs or verifying webhooks
• running provider canaries against product-owned fixtures
• deciding whether provider canary evidence is launch-blocking or deferred

Adapters emit normalized runtime and evidence envelopes into the shared contract. The shared package validates and reports; it does not call providers.

Privacy Rules

The shared validators must reject artifacts containing:

• API tokens, bearer tokens, webhook secrets, or provider credentials
• raw actor, user, account, workspace, provider job, or owner ids
• R2 object keys, provider input keys, output keys, or signed URLs
• raw provider response bodies, gateway metadata, image bytes, or private URLs
• product prompt text, preset copy, or public visual identity

Artifacts may include provider labels, capability flags, public failure categories, aggregate output counts, byte counts, MIME types, public model family labels, redacted references, and reviewer-owned evidence labels.

Acceptance Fixture

The product-free fixture lives at ai-provider-runtime-contract.media-fixture.json. Before extraction, the fixture must keep these constraints true:

• it references ai-provider-runtime-contract
• it names ai-media-product-kit/packages/runtime as the target
• it includes descriptor, input-policy, result-envelope, collection, and readiness stages
• it keeps product adapters separate from shared validators
• it contains no vertical product name, prompt text, raw provider id, storage key, token marker, or actor identifier

Extraction Sequence

1. Keep current provider descriptors, runtime adapters, and canaries inside the product template.
2. Build or start a second AI/media product that uses the same descriptor and result envelope with different model configuration and public identity.
3. Move only descriptor validation, input-policy validation, result envelope validation, failure category normalization, evidence privacy scanning, and report formatting into the media kit.
4. Keep provider SDK calls, model payload mapping, prompt builders, product presets, environment variables, and route composition inside each product.
5. Re-run both product templates end to end before claiming the extraction complete.

Non-Goals

• No generic third-party provider plugin marketplace.
• No provider credential storage.
• No automatic model selection.
• No prompt registry.
• No public product copy.
• No claim that a provider is staging-proven without real canary evidence.