Interface ICatalogueProvider<TCatalogue>

Namespace

EncDotNet.S100.Core

Assembly

EncDotNet.S100.Core.dll

Provides catalogue artifacts (Feature Catalogues, Portrayal Catalogues, or anything else identified by a SpecRef) to dataset processors and other pipeline consumers.

public interface ICatalogueProvider<TCatalogue> where TCatalogue : class

Type Parameters

TCatalogue

The catalogue artifact type. Concrete examples: FeatureCatalogue for the FC manager, PortrayalCatalogueProvider for the PC manager.

Remarks

The provider is identity-shaped: input is a SpecRef, output is the catalogue. The returned catalogue self-describes via its own CatalogueRef property, so the caller compares Edition against that property to decide whether the resolution is acceptable under their preferred SpecMatchPolicy. The provider deliberately does not apply fallback rules — callers explicitly say which catalogues they accept.

Implementations must be thread-safe: pipeline workers call GetCatalogueAsync(SpecRef, CancellationToken) concurrently for the same and different specs.

Properties

AvailableCatalogues

The set of CatalogueRefs for catalogues currently known to this provider. The set may grow over time as catalogues are loaded lazily; for diagnostic enumeration, prefer iterating once at a stable point in the pipeline rather than relying on real-time accuracy.

IReadOnlyCollection<CatalogueRef> AvailableCatalogues { get; }

Property Value

IReadOnlyCollection<CatalogueRef>

Methods

GetCatalogueAsync(SpecRef, CancellationToken)

Returns the catalogue for spec, or null when no catalogue is registered or the underlying source cannot be opened.

ValueTask<TCatalogue?> GetCatalogueAsync(SpecRef spec, CancellationToken cancellationToken = default)

Parameters

spec SpecRef

The catalogue identity being requested.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<TCatalogue>

GetCatalogueHashAsync(SpecRef, CancellationToken)

Returns a stable, lowercase hex SHA-256 content hash of the catalogue resolved for spec, or null when no catalogue is available.

ValueTask<string?> GetCatalogueHashAsync(SpecRef spec, CancellationToken cancellationToken = default)

Parameters

spec SpecRef

The catalogue identity being requested.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<string>

The content hash, or null when no catalogue resolves.

Remarks

The hash reflects the actual resolved content of the catalogue and every file it references — for a Feature Catalogue, the raw FC XML bytes; for a Portrayal Catalogue, the PC XML plus each referenced rule and asset file. It therefore captures runtime overrides that change a file without bumping its declared version, making it a sound cache-invalidation input.

The hash deliberately excludes anything that is not catalogue content — engine/assembly versions, the requesting dataset, and mariner / display state. Callers that key a cache on portrayal output must fold those inputs in separately.

Implementations compute the hash at most once per spec and memoize it; a successfully computed hash is stable for the provider's lifetime unless the underlying source is re-registered. A transient failure is not memoized, so a later call may retry.