Media Asset Lineage Protocol

Candidate: media-asset-lineage

Target owner: future-shared-package

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

Purpose

This protocol freezes the portable lineage contract for private media files before storage code moves out of this vertical template. The goal is to let future AI media products reuse a stored-file reference, source/input/output role model, private proxy boundary, cleanup miss envelope, and retention evidence shape without inheriting one product's bucket names, object-key format, download filenames, or retention promises.

This is a contract freeze only. The current R2 object-key builders, bucket bindings, route handlers, and library copy stay product-local until a second template proves the same lineage.

Shared Contract

The future media-lineage package should own schemas and validators for:

• stored media file references
• media role labels
• source-to-provider-input lineage
• provider-input-to-output lineage
• private read envelopes
• generated output collections with a primary-output compatibility alias
• cleanup miss envelopes
• retention and deletion evidence summaries

The shared contract may define role labels, reference field names, privacy expectations, and evidence summaries. It must not define bucket names, object key paths, route URLs, product filenames, public retention copy, or provider request payloads.

Stored File Reference Boundary

A portable stored-file reference can include:

• opaque file reference id
• role label
• MIME type
• byte size
• original or display filename label
• created/stored timestamp
• checksum or etag label when public-safe
• redacted storage reference label

Product adapters keep raw R2 object keys, bucket bindings, key namespaces, custom metadata, signed URLs, and concrete route paths.

Lineage Boundary

Portable lineage can describe these roles:

• source: user-provided media after source validation
• provider-input: provider-ready media derived from source
• output: generated or transformed media persisted after runtime completion

The lineage contract should support one source, optional provider input, and one or more outputs. A primary-output alias may exist for older clients, but new consumers should inspect the output collection.

Private Proxy And Cleanup Rules

Portable rules:

• browser payloads must use product-owned proxy URLs or action routes rather than storage keys
• malformed output selectors must fail closed
• delete can remove the visible row before best-effort storage cleanup when the product records cleanup misses
• cleanup miss evidence must include role, aggregate count, and redacted reference labels, not raw object keys
• retention evidence must declare source, provider-input, output, and metadata windows separately

Product adapters keep R2 reads, R2 deletes, route guards, auth/account mapping, download filenames, retention schedules, and user-facing cleanup copy.

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 role labels, redacted file references, MIME types, byte counts, output counts, cleanup statuses, retention day counts, UTC timestamps, and reviewer-owned evidence labels.

Acceptance Fixture

The product-free fixture lives at media-asset-lineage.media-fixture.json. Before extraction, the fixture must keep these constraints true:

• it references media-asset-lineage
• it names ai-media-product-kit/packages/media-lineage as the target
• it includes file-reference, lineage, private-read, cleanup-miss, retention, and output-collection stages
• it keeps product adapters separate from shared validators
• it contains no vertical product name, raw storage key, token marker, private URL, or actor identifier

Extraction Sequence

1. Keep current R2 storage adapters, proxy routes, cleanup-miss handlers, and retention service inside the product template.
2. Build or start a second AI/media product that uses the same lineage roles with different bucket names, filenames, retention windows, and public copy.
3. Move only stored-reference schemas, lineage validation, private-read envelope validation, cleanup summary validation, privacy scanning, and report formatting into the media kit.
4. Keep object-key generation, bucket bindings, storage operations, route guards, download naming, and retention policy copy inside each product.
5. Re-run both product templates end to end before claiming the extraction complete.

Non-Goals

• No shared R2 bucket ownership.
• No shared object-key namespace.
• No signed URL generation.
• No public download filename policy.
• No product retention promise.
• No migration of existing media objects without a separate data plan.