Class LayeredAnnotationStore

Namespace
Kuestenlogik.Bowire.Semantics
Assembly
Kuestenlogik.Bowire.dll

The composed annotation store: a session-scope InMemoryAnnotationLayer at user priority, a user-local JSON file, a project-local JSON file, and a plugin-hints callback. Implements the resolution priority pinned by the ADR (User > Plugin > Auto) so callers get the effective answer from one call.

public sealed class LayeredAnnotationStore : IAnnotationStore
Inheritance
LayeredAnnotationStore
Implements
Inherited Members

Remarks

Phase 1 of the frame-semantics framework does not yet wire detectors in, so the Auto layer is an explicit InMemoryAnnotationLayer that detector code in Phase 2 can populate without reshaping the store.

The plugin-hints surface is a Func<T1, T2, TResult> rather than an IBowireSchemaHints reference so the store stays decoupled from the plugin registry — wiring up the callback against the actual BowireProtocolRegistry happens in AddBowire(IServiceCollection).

Constructors

LayeredAnnotationStore(InMemoryAnnotationLayer, JsonFileAnnotationLayer?, JsonFileAnnotationLayer?, InMemoryAnnotationLayer, Func<string, string, IEnumerable<Annotation>>)

Construct a store from explicit layers.

public LayeredAnnotationStore(InMemoryAnnotationLayer userSessionLayer, JsonFileAnnotationLayer? userFileLayer, JsonFileAnnotationLayer? projectFileLayer, InMemoryAnnotationLayer autoDetectorLayer, Func<string, string, IEnumerable<Annotation>> pluginHints)

Parameters

userSessionLayer InMemoryAnnotationLayer

Required. The in-memory layer at user priority — manual session edits that have not yet been escalated to a file.

userFileLayer JsonFileAnnotationLayer

Optional. User-local JSON file. Pass null to opt out of user-scope persistence (e.g. hardened deployments).

projectFileLayer JsonFileAnnotationLayer

Optional. Project-local JSON file. Pass null when no project hint file exists.

autoDetectorLayer InMemoryAnnotationLayer

Required. Phase-2 detector output lands here. Pass an empty layer in Phase 1.

pluginHints Func<string, string, IEnumerable<Annotation>>

Required. Callback that returns plugin-supplied annotations for a given (serviceId, methodId) pair. The framework calls it lazily during GetEffective(AnnotationKey) and EnumerateEffective().

Properties

AutoDetectorLayer

In-memory layer at Auto priority. Phase-2 detectors will populate this; Phase 1 leaves it empty.

public InMemoryAnnotationLayer AutoDetectorLayer { get; }

Property Value

InMemoryAnnotationLayer

ProjectFileLayer

Project-local JSON-file layer at User priority — files versioned alongside source code (bowire.schema-hints.json at the repo root). May be null when no project file is configured.

public JsonFileAnnotationLayer? ProjectFileLayer { get; }

Property Value

JsonFileAnnotationLayer

UserFileLayer

User-local JSON-file layer at User priority. Backs ~/.bowire/schema-hints.json in the default AddBowire(IServiceCollection) wiring. May be null when the host opts out of user persistence entirely.

public JsonFileAnnotationLayer? UserFileLayer { get; }

Property Value

JsonFileAnnotationLayer

UserSessionLayer

In-memory layer at User priority. Manual right-click edits that have not yet been promoted to disk live here for the session lifetime.

public InMemoryAnnotationLayer UserSessionLayer { get; }

Property Value

InMemoryAnnotationLayer

Methods

EnumerateEffective()

Enumerate every effective annotation across the configured layers. One entry per AnnotationKey, each carrying the resolved SemanticTag and the AnnotationSource that supplied it.

public IEnumerable<Annotation> EnumerateEffective()

Returns

IEnumerable<Annotation>

GetEffective(AnnotationKey)

Resolve the effective semantic tag for key, applying the priority rule: the highest-source non-empty annotation wins. Returns null when no source claims the key at all.

public SemanticTag? GetEffective(AnnotationKey key)

Parameters

key AnnotationKey

Returns

SemanticTag

Remarks

A user-supplied None is a real value, not the absence of one — it returns None, suppressing any lower-priority proposal. Only the genuine "no source claims this key" case returns null.

GetEffectiveSource(AnnotationKey)

Resolve the AnnotationSource that supplied the effective tag for key. Returns None when no source claims the key. Useful for the UI to badge an annotation as "(auto)", "(plugin)", or "(user)".

public AnnotationSource GetEffectiveSource(AnnotationKey key)

Parameters

key AnnotationKey

Returns

AnnotationSource