storage

type MediaMetadata struct {
	// RunID identifies the test run that generated this media
	RunID string `json:"run_id"`

	// ConversationID identifies the conversation containing this media
	ConversationID string `json:"conversation_id,omitempty"`

	// SessionID identifies the session (for streaming sessions)
	SessionID string `json:"session_id,omitempty"`

	// MessageIdx is the index of the message containing this media (0-based)
	MessageIdx int `json:"message_idx"`

	// PartIdx is the index of the content part containing this media (0-based)
	PartIdx int `json:"part_idx"`

	// MIMEType is the media MIME type (e.g., "image/jpeg", "audio/mp3")
	MIMEType string `json:"mime_type"`

	// SizeBytes is the size of the media content in bytes
	SizeBytes int64 `json:"size_bytes"`

	// ProviderID identifies the provider that generated this media
	ProviderID string `json:"provider_id,omitempty"`

	// Timestamp is when the media was stored
	Timestamp time.Time `json:"timestamp"`

	// PolicyName is the retention policy to apply to this media
	PolicyName string `json:"policy_name,omitempty"`
}

type MediaStorageService interface {
	// StoreMedia stores media content and returns a storage reference.
	// The reference can be used to retrieve the media later.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - content: The media content to store (must have Data, FilePath, or URL set)
	//   - metadata: Metadata about the media for organization and policies
	//
	// Returns:
	//   - Reference that can be used to retrieve the media
	//   - Error if storage fails
	//
	// The implementation should:
	//   - Validate the content and metadata
	//   - Store the media content durably
	//   - Apply any configured policies (e.g., retention)
	//   - Return a reference that uniquely identifies the stored media
	StoreMedia(ctx context.Context, content *types.MediaContent, metadata *MediaMetadata) (Reference, error)

	// RetrieveMedia retrieves media content by its storage reference.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - reference: The storage reference returned by StoreMedia
	//
	// Returns:
	//   - MediaContent with FilePath set (Data should NOT be loaded into memory)
	//   - Error if retrieval fails or reference is invalid
	//
	// The implementation should:
	//   - Validate the reference
	//   - Return MediaContent with FilePath pointing to the stored media
	//   - NOT load the full media data into memory (caller can use GetBase64Data if needed)
	RetrieveMedia(ctx context.Context, reference Reference) (*types.MediaContent, error)

	// DeleteMedia deletes media content by its storage reference.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - reference: The storage reference to delete
	//
	// Returns:
	//   - Error if deletion fails or reference is invalid
	//
	// The implementation should:
	//   - Validate the reference
	//   - Delete the media content if not referenced elsewhere (for dedup)
	//   - Clean up any associated metadata
	//   - Handle concurrent deletions safely
	DeleteMedia(ctx context.Context, reference Reference) error

	// GetURL returns a URL that can be used to access the media.
	// For local storage, this returns a file:// URL.
	// For cloud storage, this may return a signed URL with expiration.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - reference: The storage reference
	//   - expiry: How long the URL should be valid (ignored for local storage)
	//
	// Returns:
	//   - URL string that can be used to access the media
	//   - Error if URL generation fails or reference is invalid
	GetURL(ctx context.Context, reference Reference, expiry time.Duration) (string, error)
}

type OrganizationMode string

type PolicyHandler interface {
	// ApplyPolicy applies a named policy to a media file.
	// This typically stores policy metadata alongside the media.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - filePath: Path to the media file
	//   - policyName: Name of the policy to apply (e.g., "delete-after-10min", "retain-30days")
	//
	// Returns:
	//   - Error if policy application fails or policy is unknown
	ApplyPolicy(ctx context.Context, filePath string, policyName string) error

	// EnforcePolicy scans stored media and enforces policies.
	// This is typically called periodically in the background.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//
	// Returns:
	//   - Error if enforcement fails (should log but not crash on individual file errors)
	//
	// The implementation should:
	//   - Scan media directories for policy metadata
	//   - Apply policies (e.g., delete expired files)
	//   - Log enforcement actions
	//   - Handle errors gracefully (don't stop on permission denied, etc.)
	EnforcePolicy(ctx context.Context) error
}

type Reference string