Spanfold C# API reference

static class

Spanfold

Entry point for configuring a Spanfold event pipeline.

Member	Purpose
`For<TEvent>()`	Creates an `EventPipelineBuilder<TEvent>` for the event type.

sealed class

EventPipelineBuilder<TEvent>

Top-level builder for windows, callbacks, event time, and history recording.

Member	Purpose
`Window(...)`	Adds a source window and returns a `WindowPipelineBuilder<TEvent>`.
`TrackWindow(...)`	Builds a pipeline for one state-driven source window.
`RecordWindows()`	Enables recording of open and closed windows during ingestion.
`WithEventTime(...)`	Sets the event timestamp selector.
`OnEmission(...)`	Registers a callback for emitted transitions.
`Build()`	Builds the configured `EventPipeline<TEvent>`.

sealed class

WindowPipelineBuilder<TEvent>

Builder returned after adding a window. It keeps window and roll-up concepts close together.

Member	Purpose
`Window(...)`	Adds another independent source window.
`RollUp(...)`	Adds a parent window derived from child activity.
`RecordWindows()`	Enables recorded history.
`WithEventTime(...)`	Configures timestamps.
`Build()`	Builds the pipeline.

sealed class

EventPipeline<TEvent>

Runtime pipeline that ingests events and exposes recorded history.

Member	Purpose
`History`	Recorded `WindowHistory` for direct queries, annotations, snapshots, and comparison.
`Metadata`	Configured event type and window hierarchy metadata.
`Ingest(event)`	Processes one event without source context.
`Ingest(event, source)`	Processes one event with source/lane context.
`Ingest(event, source, partition)`	Processes one event with source and partition context.
`IngestMany(events)`	Processes events sequentially.

sealed class

WindowDefinitionBuilder<TEvent>

Defines one state window: key, active predicate, segments, tags, and callbacks.

Member	Purpose
`Named(name)`	Sets the public window name.
`Key(...)`	Selects the logical key that owns state.
`ActiveWhen(...)`	Predicate that keeps the window active.
`Segment(name, ...)`	Adds a boundary-aware segment dimension.
`Tag(name, ...)`	Captures descriptive metadata when a window opens.
`OnOpened(...)` / `OnClosed(...)`	Registers transition callbacks.

sealed class

SegmentBuilder<TEvent>

Builds segment dimensions, including nested segment hierarchies.

Member	Purpose
`Value(...)`	Selects the segment value from the event.
`Child(name, ...)`	Adds a child segment under this segment.

record

WindowEmission<TEvent>

Represents an emitted window transition from ingestion.

Member	Purpose
`WindowName`, `Key`, `Event`	Identity and source event for the transition.
`Kind`	`Opened` or `Closed`.
`Source`, `Partition`	Lane and partition context.
`Segments`, `Tags`	Analytical context captured with the emission.

abstract record

WindowRecord, OpenWindow, ClosedWindow

Recorded temporal evidence created from emissions.

Member	Purpose
`WindowName`, `Key`, `Source`, `Partition`	Scope identity.
`StartPosition`, `EndPosition`	Processing-position bounds.
`StartTime`, `EndTime`	Timestamp bounds when event time is configured.
`Segments`, `Tags`	Context for filtering, grouping, and debug output.
`Id`	Stable `WindowRecordId` derived from the window identity.

sealed class

WindowHistory

Recorded open and closed windows plus query, annotation, snapshot, and comparison entry points.

Member	Purpose
`ClosedWindows` / `OpenWindows` / `Windows`	Materialized recorded history.
`Query()`	Direct read-only history query.
`SnapshotAt(horizon)`	Read-only horizon snapshot.
`Compare(name)`	Starts a staged comparison.
`Annotate(...)`	Append-only late metadata.
`CompareSources(...)`, `CompareHierarchy(...)`	Source matrix and hierarchy explanation helpers.

sealed class

WindowHistoryQuery

Filters recorded history by window, key, source/lane, partition, segment, and tag.

Member	Purpose
`Window(...)`, `Key(...)`, `Lane(...)`	Restrict query scope.
`Segment(...)`, `Tag(...)`	Require context values.
`Windows()`, `ClosedWindows()`, `OpenWindows()`	Materialize matching records.
`WindowsAt(...)`, `OpenWindowsAt(...)`	Evaluate at a horizon.
`LatestWindow()` / `LatestWindowAt(...)`	Return the latest matching record.

sealed class

WindowHistorySnapshot

Read-only view of recorded history at an explicit horizon.

Member	Purpose
`Horizon`	The point used to evaluate open and closed windows.
`Query()`	Starts a `WindowSnapshotQuery` over snapshot records.

records

WindowAnnotation and WindowAnnotationTarget

Append-only metadata attached after a window opens or closes.

Member	Purpose
`Name`, `Value`, `KnownAt`	Annotation payload and point-in-time safety.
`Revision`	Append order for repeated annotation names.
`WindowAnnotationTarget.From(window)`	Stable target based on the window start identity.

sealed class

WindowComparisonBuilder

Staged comparison flow for target, against, scope, normalization, comparator selection, and execution.

var result = pipeline.History
    .Compare("Provider QA")
    .Target("provider-a", s => s.Source("provider-a"))
    .Against("provider-b", s => s.Source("provider-b"))
    .Within(scope => scope.Window("DeviceOffline"))
    .Using(c => c.Overlap().Residual().Missing())
    .Run();

Member	Purpose
`Target(...)`, `Against(...)`	Select comparison sides.
`AgainstCohort(...)`	Compare against a derived cohort side.
`Within(...)`	Set scope.
`Normalize(...)`	Set temporal normalization policy.
`Using(...)`	Select comparator row families.
`Prepare()`, `Run()`, `RunLive(...)`	Materialize stages or execute comparison.

sealed class

ComparisonSelectorBuilder

Creates serializable or runtime selectors for target and comparison sides.

Member	Purpose
`WindowName(...)`, `Key(...)`, `Source(...)`	Select by identity.
`Sources(...)`	Select multiple source identities.
`Partition(...)`	Select a partition.
`PositionRange(...)`, `TimeRange(...)`	Select temporal ranges.
`Runtime(...)`	Creates a runtime-only predicate selector.

sealed class

ComparisonCohortBuilder and CohortActivity

Collapses several sources into one derived comparison side before comparators run.

Member	Purpose
`Sources(...)`	Declares cohort members.
`Activity(CohortActivity)`	Sets when the cohort is active.
`CohortActivity.Any()` / `All()` / `None()`	Basic activity rules.
`AtLeast(n)`, `AtMost(n)`, `Exactly(n)`	Threshold rules.

sealed class

ComparisonNormalizationBuilder

Makes temporal policies explicit before alignment.

Member	Purpose
`RequireClosedWindows()`	Rejects open windows for historical comparison.
`ClipOpenWindowsTo(horizon)`	Clips open windows to a live horizon.
`OnPosition()` / `OnEventTime()`	Selects processing-position or timestamp analysis.
`KnownAtPosition(...)` / `KnownAt(...)`	Prevents future leakage.

sealed class

ComparisonComparatorBuilder

Selects result row families.

Member	Purpose
`Overlap()`	Both sides active.
`Residual()`	Target active without comparison coverage.
`Missing()`	Comparison active without target coverage.
`Coverage()`	Coverage rows and summaries.
`Gap()`, `SymmetricDifference()`, `Containment()`	Additional shape and invariant checks.
`LeadLag(...)`, `AsOf(...)`	Transition timing drift and point-in-time lookup.

sealed class

ComparisonResult

Structured comparison artifact containing diagnostics, stages, rows, summaries, finality, and metadata.

Member	Purpose
`Prepared`, `Aligned`	Comparison stages when execution reached them.
`OverlapRows`, `ResidualRows`, `MissingRows`	Core row families.
`CoverageRows`, `GapRows`, `LeadLagRows`, `AsOfRows`	Additional row families.
`Diagnostics`	Validation and execution diagnostics.
`RowFinalities`	Final or provisional status for live rows.
`IsValid`	True when no error diagnostics are present.

Spanfold.Episodes · .NET preview

Episode builders and extensions

Forms occurrence sets from recorded windows or compares two formed sets.

Public type or member	Purpose
`WindowHistoryEpisodeExtensions.FormEpisodes(WindowHistory, string)`	Starts an `EpisodeFormationBuilder`.
`WindowHistoryEpisodeExtensions.CompareEpisodes(WindowHistory, string)`	Starts an `EpisodeComparisonBuilder`.
`EpisodeFormationBuilder.From(Func<ComparisonSelectorBuilder, ComparisonSelector>)`	Selects source windows for one episode set.
`EpisodeFormationBuilder.Within(Func<ComparisonScopeBuilder, ComparisonScope>)`	Sets the named window scope and temporal axis.
`EpisodeFormationBuilder.Normalize(Func<ComparisonNormalizationBuilder, ComparisonNormalizationBuilder>)`	Sets temporal normalization before stitching.
`EpisodeFormationBuilder.StitchGapsUpTo(long)` / `StitchGapsUpTo(TimeSpan)`	Sets side-local processing-position or timestamp stitching.
`EpisodeFormationBuilder.Build()`, `Run()`, `RunLive(TemporalPoint)`	Builds a plan or materializes an `EpisodeSet`.
`EpisodeComparisonBuilder.Target(string, Func<ComparisonSelectorBuilder, ComparisonSelector>)`	Selects and names the target side.
`EpisodeComparisonBuilder.Against(string, Func<ComparisonSelectorBuilder, ComparisonSelector>)`	Selects and names the against side.
`EpisodeComparisonBuilder.Within(Func<ComparisonScopeBuilder, ComparisonScope>)`	Applies one scope to both sides.
`EpisodeComparisonBuilder.Normalize(Func<ComparisonNormalizationBuilder, ComparisonNormalizationBuilder>)`	Applies one normalization policy to both sides.
`EpisodeComparisonBuilder.StitchGapsUpTo(long)` / `StitchGapsUpTo(TimeSpan)`	Sets the shared side-local formation tolerance.
`EpisodeComparisonBuilder.RelateWithin(long)` / `RelateWithin(TimeSpan)`	Sets the cross-side relation tolerance.
`EpisodeComparisonBuilder.Build()`, `Run()`, `RunLive(TemporalPoint)`	Builds a plan or materializes an `EpisodeComparisonResult`.

Spanfold.Episodes

Episode plans and policies

Public type	Public contract
`EpisodeFormationPlan`	`Name`, `Selector`, `Scope`, `Normalization`, and `Formation`.
`EpisodeFormationPolicy`	Construct with `(TemporalAxis, long stitchToleranceMagnitude)`; exposes `TimeAxis` and `StitchToleranceMagnitude`.
`EpisodeComparisonPlan`	`Name`, side names and selectors, `Scope`, `Normalization`, `Formation`, and `Relation`.
`EpisodeRelationPolicy`	Construct with `(TemporalAxis, long toleranceMagnitude)`; exposes `TimeAxis` and `ToleranceMagnitude`.

Spanfold.Episodes

Episode domain and relation graph

Public type	Public contract
`EpisodeId`	Deterministic episode identifier with `Value`.
`EpisodeFragment`	`Window`, normalized `Range`, `Finality`, and `RecordId`.
`Episode`	`Id`, identity fields, `TimeAxis`, authoritative `Fragments`, `Envelope`, `Finality`, and active, elapsed, and internal-gap magnitudes.
`EpisodeSet`	`Name`, `Plan`, ordered `Episodes`, `Summary`, and optional `EvaluationHorizon`.
`EpisodeRelationKind`	`OneToOne`, `Split`, `Merge`, `Complex`, `UnmatchedTarget`, and `UnmatchedAgainst`.
`EpisodeRelationMetrics`	Active magnitudes, overlap and coverage ratios, intersection-over-union, minimum gap, and directional timing and magnitude deltas.
`EpisodeRelation`	`Kind`, complete target and against episode lists, `Metrics`, and `Finality`.
`EpisodeComparisonResult`	`Name`, `Plan`, both episode sets, exhaustive `Relations`, neutral `Summary`, and optional `EvaluationHorizon`.

Spanfold.Episodes

Episode summaries and analysis extensions

Public type or member	Purpose
`EpisodeDistributionSummary`	Count, minimum, mean, median, nearest-rank 95th percentile, and maximum.
`EpisodeSetSummary`	Episode and fragment counts, finality, fragmentation rates, and active, elapsed, and internal-gap distributions.
`EpisodeComparisonSummary`	Neutral target/against match, relation, bias, coverage, overlap, and one-to-one delta metrics.
`EpisodeReferenceScorecard`	Explicit reference/detection counts plus recall, precision, and F1.
`EpisodeAnalysisExtensions.RelationsOfKind(EpisodeComparisonResult, EpisodeRelationKind)`	Returns relation components with one classification.
`UnmatchedTargetEpisodes(EpisodeComparisonResult)`, `UnmatchedAgainstEpisodes(EpisodeComparisonResult)`	Returns the unmatched episodes for one side.
`AsReference(EpisodeComparisonResult)`	Interprets target episodes as references and against episodes as detections.

Live finality is relative to the explicit evaluation horizon. It does not imply watermark or late-record completeness.

static class

ComparisonExportExtensions

Deterministic export helpers for plans and results.

Member	Purpose
`ExportJson()`	Stable JSON for plans or results.
`ExportJsonLines()`	Lazy JSON Lines for result rows.
`ExportMarkdown()`	Deterministic Markdown explanation.
`ExportDebugHtml()`	Self-contained visual comparison document.
`ExportLlmContext()`	Agent-readable JSON with instructions, summary, Markdown orientation, full result data, and row documents.
`AuditBundleWriter.Write(...)`	Atomic, integrity-verifiable audit bundle output in the optional Spanfold.Artifacts package.

readonly record struct

TemporalPoint

Explicit point on a temporal axis.

Member	Purpose
`ForPosition(long)`	Processing-position point.
`ForTimestamp(DateTimeOffset, clock)`	Timestamp point.
`CompareTo(...)`, `IsBefore(...)`, `IsAfter(...)`	Axis-safe comparison helpers.

readonly record struct

TemporalRange

Half-open range used by windows, aligned segments, and result rows.

Member	Purpose
`Closed(start, end)`	Known-ended range.
`Open(start)`	Open range for ongoing windows.
`WithEffectiveEnd(...)`	Clips or evaluates the range at an effective end.
`GetPositionLength()`, `GetTimeDuration()`	Measures range magnitude.
`Overlaps(...)`, `Contains(...)`	Range predicates.

sealed class

LaneLivenessTracker

Converts sparse observations into liveness signals that can be recorded as ordinary windows.

Member	Purpose
`ForLanes(...)`	Creates a deterministic tracker for expected lanes.
`Observe(lane, observedAt)`	Records that a lane reported.
`Check(horizon)`	Emits silence or recovery signals at a horizon.
`LaneLivenessSignal`	Event shape for recording silence windows.

Spanfold.Testing sealed class

WindowHistoryFixtureBuilder

Builds compact recorded histories for comparator and contract tests.

Member	Purpose
`AddClosedWindow(...)`	Adds a closed fixture window.
`AddOpenWindow(...)`	Adds an open fixture window.
`Build()`	Creates a `WindowHistory` fixture.

Spanfold.Testing static class

SpanfoldAssert

Framework-neutral assertions for comparison artifacts.

Member	Purpose
`IsValid(...)`	Asserts that a comparison result has no error diagnostics.
`HasNoDiagnostics(...)`	Asserts that no diagnostics were emitted.
`HasDiagnostic(...)`	Returns a matching diagnostic code or fails.
`HasRowCount(...)`	Asserts an expected row count for a named row family.

Spanfold.Testing static class

SpanfoldSnapshot

Snapshot helpers for deterministic JSON and Markdown artifacts.

Member	Purpose
`Normalize(...)`	Normalizes line endings, trailing whitespace, and deterministic record IDs.
`AssertEqual(...)`	Compares two normalized snapshot strings.

Spanfold for .NET.

Spanfold

EventPipelineBuilder<TEvent>

WindowPipelineBuilder<TEvent>

EventPipeline<TEvent>

WindowDefinitionBuilder<TEvent>

SegmentBuilder<TEvent>

WindowEmission<TEvent>

WindowRecord, OpenWindow, ClosedWindow

WindowHistory

WindowHistoryQuery

WindowHistorySnapshot

WindowAnnotation and WindowAnnotationTarget

WindowComparisonBuilder

ComparisonSelectorBuilder

ComparisonCohortBuilder and CohortActivity

ComparisonNormalizationBuilder

ComparisonComparatorBuilder

ComparisonResult

Episode builders and extensions

Episode plans and policies

Episode domain and relation graph

Episode summaries and analysis extensions

ComparisonExportExtensions

TemporalPoint

TemporalRange

LaneLivenessTracker

WindowHistoryFixtureBuilder

SpanfoldAssert

SpanfoldSnapshot