Namespace DotBoxD.Plugins.Indexing

Classes

EventIndexKeyAttribute

Marks an event property the host keeps a dispatch index for. DotBoxD owns predicate lowering and exposes index metadata on the plugin manifest (IndexedPredicates); this attribute is how a host declares which of those property paths it can actually serve from an equality/range bucket. EventIndexMatcher<TEvent> reads it (once, with a compiled getter) and ignores manifest predicates whose path is not an index key, leaving them to the verified IR.

Promoted to the framework as the first-class declaration surface (issue #50) so any host can opt into index-based prefiltering without reimplementing the matcher. It stays purely declarative: a property the host does not mark is simply never served from the index.

EventIndexMatcher<TEvent>

A host's compiled view of a subscription's IndexedPredicate metadata — the "compile the metadata into whatever dispatch/index structure is natural for the runtime" half of issue #47, promoted to the framework by issue #50. It keeps only the predicates whose Path is an EventIndexKeyAttribute property of TEvent (the fields the host indexes) and evaluates them cheaply against an event through precompiled property getters — no per-event reflection, so the index never costs more than it saves.

Because every kept predicate is a necessary AND condition of the real predicate, CouldMatch(TEvent) returning false is always a safe reject; returning true means the event passed the cheap index and the host should still run the verified IR unless the manifest reported full coverage. Conversely, the matcher never rejects on a comparison it cannot soundly decide (a value whose type cannot be reconciled to the property, a null reference, or an ordering it cannot evaluate): such a leaf is dropped or passed through so the verified IR stays the authority. This keeps the invariant "index-reject ⇒ verified-IR-reject" intact even for hand-built or imported manifests whose ValueType disagrees with the property's CLR type.

EventIndexRegistry

A first-class, reusable host dispatch index (issue #50). A host registers a subscription kernel together with its generated IndexedPredicates; the registry recomputes them from verified IR and compiles them into an EventIndexMatcher<TEvent> (precompiled getters, no per-event reflection) and, when the host publishes an event, runs the cheap index check before entering the sandbox. Events the index rejects never reach the verified IR; survivors are dispatched to InstalledKernel as the correctness authority — the verified ShouldHandle still runs after a matching index check because package-supplied coverage metadata is not trusted across the manifest boundary.

This is the "register a subscription and get index-based prefiltering without writing your own matcher" surface. Subscriptions whose predicates touch no indexed field are rejected by Register<TEvent>(IPluginEventAdapter<TEvent>, InstalledKernel, IReadOnlyList<IndexedPredicate>, bool) (returns false) so the host can leave them on its broad pipeline.

Structs

EventIndexStats

Prefilter diagnostics for an EventIndexRegistry: how many indexed checks ran (Considered), how many events the index rejected before any sandbox entry (Prefiltered), and how many survived to the verified IR (Dispatched). Considered == Prefiltered + Dispatched holds once publishing is quiescent; a snapshot taken while Publish<TEvent>(TEvent, CancellationToken) is running concurrently may observe an in-flight increment between the three reads.