using System.Collections.ObjectModel;
using System.Text.Json.Serialization;

namespace Jellyfin.Plugin.JRay.Models;

/// <summary>
/// Root object of a scene-actor-extraction "truth" file
/// (<c>schema_version</c> 2). See SPEC.md §1.
/// </summary>
/// <remarks>
/// JRay <b>owns</b> this format; the extraction pipeline is its producer and the
/// public server carries a derived envelope. Because three repos ship
/// independently, breaking changes are batched into one coordinated
/// <c>schema_version</c> bump rather than made piecemeal.
///
/// <para>
/// <b>This is the v2 shape, and v1 is gone rather than deprecated.</b> The bump
/// removed <c>anneal_sec</c>, moved <c>sample_fps</c> into
/// <see cref="TruthExtraction"/>, added <see cref="TruthCut"/>, and turned
/// <c>scenes</c> from float pairs into <see cref="TruthScene"/> objects carrying
/// belief and route. Nothing here reads a v1 file: see
/// <see cref="Services.TruthSchema"/> for why that is a decision rather than an
/// omission.
/// </para>
/// </remarks>
// TRACES: JR-001, JR-002 | SR-003
public class TruthFile
{
    /// <summary>
    /// Gets or sets the schema version of this file. Only
    /// <see cref="Services.TruthSchema.SupportedVersion"/> is accepted.
    /// </summary>
    [JsonPropertyName("schema_version")]
    public int SchemaVersion { get; set; }

    /// <summary>
    /// Gets or sets the source media path at extraction time (informational).
    /// </summary>
    /// <remarks>
    /// Stripped on contribution (JR-034): it is a contributor's directory
    /// layout, which is nobody else's business and identifies them.
    /// </remarks>
    [JsonPropertyName("movie")]
    public string Movie { get; set; } = string.Empty;

    /// <summary>
    /// Gets or sets extraction provenance, or <c>null</c> when the producer
    /// recorded none.
    /// </summary>
    [JsonPropertyName("extraction")]
    public TruthExtraction? Extraction { get; set; }

    /// <summary>
    /// Gets or sets which encode the timings apply to, or <c>null</c> when the
    /// producer recorded none.
    /// </summary>
    [JsonPropertyName("cut")]
    public TruthCut? Cut { get; set; }

    /// <summary>
    /// Gets the list of actors in the film, each with their scene-presence windows.
    /// </summary>
    [JsonPropertyName("actors")]
    [JsonObjectCreationHandling(JsonObjectCreationHandling.Populate)]
    public Collection<TruthActor> Actors { get; } = new();
}