namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;

/// <summary>
/// CentralUI read-accessor over the named JSON-Schema library for surfaces
/// that need to RESOLVE <c>{"$ref":"lib:Name"}</c> pointers — chiefly the schema-driven
/// value-entry forms. It exposes the library as a name → schema-JSON map (and the
/// equivalent single-name lookup) so the value form can plug the resolved schema text
/// into <c>InboundApiSchema.Parse(json, name =&gt; query.Resolve(name))</c> exactly the
/// way the deploy-time / runtime resolvers do.
/// </summary>
/// <remarks>
/// This is the READ counterpart of <see cref="ISchemaLibraryService"/> (the authoring /
/// mutation facade). Reads do not need the guard-running ManagementActor path, so this
/// accessor is backed by <c>ISharedSchemaRepository</c> over a fresh DI scope (mirroring
/// the AuditLog / KPI query services), keeping it off the circuit-scoped DbContext.
/// </remarks>
public interface ISchemaLibraryQueryService
{
    /// <summary>
    /// Returns the whole library as a name → schema-JSON map (name-keyed, ordinal
    /// comparison — the same key the <c>lib:Name</c> resolver matches on).
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task resolving to the name → schema-JSON map (empty when the library is empty).</returns>
    Task<IReadOnlyDictionary<string, string>> GetSchemaMapAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Returns the schema JSON for a single named library entry, or <c>null</c> when no
    /// entry by that name exists. Suitable directly as the <c>resolveRef</c> seam's
    /// per-name lookup.
    /// </summary>
    /// <param name="name">The library entry name (the part after the <c>lib:</c> scheme prefix).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task resolving to the entry's schema JSON, or <c>null</c> if not found.</returns>
    Task<string?> ResolveAsync(string name, CancellationToken cancellationToken = default);
}
