SemanticFact

SemanticFact :: # (opaque)

Typed semantic observations for inspection and bounded explanation. Facts carry supplied information; constructing one does not validate a temporal declaration or bind an interpretation. Native fact visitors provide those guarantees from their validated values and snapshots. Summary is fixed-size diagnostic text (at most 256 UTF-8 bytes), without enumerating children, copying arbitrary annotations or inspecting rule data. Full renderers use kind with explicit text/work limits. No persistence format.

calendar_value_fact_at : Value, U64 -> [End, Item(SemanticFact)]

Constant-cost access through Calendar.Value.description; out-of-range is End.

new : Kind -> SemanticFact

Wrap a typed observation without validating its fields or resolving its meaning. Use native values and their fact visitors when validation guarantees are needed.

kind : SemanticFact -> Kind

Return the typed observation for custom rendering or structured inspection.

summary : SemanticFact -> Str

Produce at most 256 UTF-8 bytes of diagnostic summary without enumerating children or copying arbitrary text fields. Use Explanation for bounded detail.

is_eq : SemanticFact, SemanticFact -> Bool

Compare the complete typed observation, including its tag and stored fields.

to_inspect : SemanticFact -> Str

Return the same bounded diagnostic text as summary.

Resolution : [Year, Month, Day, Hour, Minute, Second, Fraction(U8)]

Finest supplied calendar component; Fraction carries the supplied decimal digit count.

Offset : [UnassertedUtc, Asserted(FixedOffset)]

Whether UTC was unasserted or a particular local offset was explicitly asserted.

CalendarData : { kind : [CalendarValue, QualifiedCalendarValue, EdtfDate], calendar : Calendar, fields : Fields, clock : Fields, resolution : Resolution, qualification_count : U64 }

Fields/clock carry the canonical lower label; resolution identifies which components were supplied. Lower components filled by native construction are not additional source assertions and must not be rendered as such.

TimestampData : { kind : [OffsetTimestamp, Ixdtf], local : LocalDateTime, fraction_digits : U8, offset : Offset, zone_present : Bool, annotation_count : U64 }

Stored timestamp label, fractional precision and offset assertion, plus zone/annotation counts. These fields alone do not bind a named zone.

QualificationData : { scope : [Whole, Year, Month, Day, Hour, Minute, Second, Fraction, YearMonth], qualifier : [Uncertain, Approximate, UncertainApproximate] }

One scoped uncertainty/approximation assertion, without a tolerance model.

ZoneData : { critical : Bool, identifier : [Named(Str), Numeric(FixedOffset)] }

A named or numeric zone annotation and whether its interpretation is required.

AnnotationData : { critical : Bool, key : Str, value : Str }

An annotation key/value and critical flag. Render text with explicit bounds.

PositionData : { boundary : PosixBoundary, offset : FixedOffset, local : LocalDateTime }

Local is the snapshot's stored Gregorian projection, not a claim that its preferred calendar is supported. The separate Presentation fact states that.

ContextData : { name : Str, version : Str, validity : PosixSpan, provenance : [Supplied, DatabaseSource({ requested_name : Str, canonical_name : Str, source_digest : Str, profile : Str })] }

Identity, finite validity and supplied/database provenance of retained rules. Metadata does not replace the actual immutable transition rules.

ExactIntervalData : { span : PosixSpan }

The exact half-open POSIX span of an interval.

OffsetEndpointData : { role : [Start, End], local : LocalDateTime, fraction_digits : U8, offset : Offset }

An interval endpoint label with its role, fractional precision and offset assertion.

ICalDateTimeData : { role : [Standalone, Start, End], local : LocalDateTime, form : [Utc, Local] }

An iCalendar date-time label and its UTC/local form, optionally identifying its role as a period endpoint. Local form alone supplies no zone context.

ICalDurationData : { role : [Standalone, PeriodEnding, RecurrenceEnding], days : I64, seconds : I64 }

An iCalendar duration retaining calendar days separately from coordinate seconds, with its role in the surrounding declaration.

ICalPeriodData : { form : [Utc, Local], start : LocalDateTime, ending : [Endpoint(LocalDateTime), Duration({ days : I64, seconds : I64 })] }

An iCalendar period retaining UTC/local form and the declared ending form: an explicit endpoint or separate calendar-day/second duration components.

CoverageData : { member_count : U64 }

The cached number of canonical coverage members, without enumerating them.

CoverageMemberData : { index : U64, span : PosixSpan }

One canonical coverage span and its zero-based member index.

CivilBoundaryData : { source : LocalDateTime, policy : [RequireUnique, First, Last, MatchingOffset(FixedOffset)], boundary : PosixBoundary, offset : FixedOffset }

A retained civil label and occurrence policy with the resulting POSIX coordinate and actual offset.

CivilSelectionData : { start : LocalDateTime, end : LocalDateTime, member_count : U64 }

The original half-open civil selection and its complete coverage member count.

LocalSelectionData : { start : LocalDateTime, end : LocalDateTime }

The requested half-open civil bounds; this fact does not assert completed coverage.

SelectionEvaluationData : { status : [Complete, Limited([WorkLimit, BufferLimit])], segments : U64, buffered : U64 }

Evaluation completeness, segment work for the batch, and retained member count. A Limited status must not be interpreted as empty coverage.

Weekday : [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]

Named weekdays for recurrence selectors and week-start metadata.

RecurrenceAnchor : [Date(GregorianDate), Local(LocalDateTime)]

A date-only or local date-time recurrence anchor, preserving its coordinate domain.

RecurrenceFrequency : [Daily, Weekly, Monthly, Yearly, Hourly, Minutely, Secondly]

The declared recurrence period unit; it does not specify elapsed spacing.

RecurrenceData : { kind : [DateRecurrence, TimedRecurrence], anchor : RecurrenceAnchor, frequency : RecurrenceFrequency, interval : I64, week_start : [None, Some(Weekday)], selector_count : U64, inclusion_count : U64, exclusion_count : U64 }

Stored recurrence anchor, frequency, interval, week start and declaration counts. Reading this metadata does not generate occurrences.

RecurrenceEnd : [Forever, Count(U64), UntilDate(GregorianDate), UntilLocal(LocalDateTime), UntilBoundary(PosixBoundary)]

The rule termination and its domain. Count limits generated candidates before exclusions; it is not a promised emitted-result count.

Selector : [Month(U8), MonthDay(I8), YearDay(I16), WeekNo(I8), Weekday({ ordinal : I8, weekday : Weekday }), SetPosition(I16), Hour(U8), Minute(U8), Second(U8), Microsecond(U32)]

One effective recurrence selector, including normalized clock defaults. These facts do not preserve whether a default appeared in source text.

RecurrenceExceptionData : { kind : [Inclusion, Exclusion], source : RecurrenceAnchor }

One explicit inclusion or exclusion in the recurrence source-label domain.

RecurrencePolicyData : { context : [Required, FixedUtc], occurrence : [CallerSupplied, First], gap : [CallerSupplied, UseOffsetBeforeGap] }

The context and occurrence/gap policy required or fixed by a declaration.

ICalTimedRuleData : { mode : [Utc, Floating, Zoned], period_count : U64 }

The iCalendar rule mode and explicit period count, before schedule evaluation.

Kind : [RecurrenceBoundaryExclusion(PosixBoundary), RecurrenceDescription(RecurrenceData), RecurrenceTermination(RecurrenceEnd), RecurrenceSelector(Selector), RecurrenceException(RecurrenceExceptionData), RecurrencePolicy(RecurrencePolicyData), ICalTimedRuleDescription(ICalTimedRuleData), CoverageDescription(CoverageData), CoverageMember(CoverageMemberData), CivilBoundaryDescription(CivilBoundaryData), CivilSelectionDescription(CivilSelectionData), LocalSelectionDescription(LocalSelectionData), SelectionEvaluation(SelectionEvaluationData), ExactIntervalDescription(ExactIntervalData), OffsetEndpoint(OffsetEndpointData), ICalDateTimeDescription(ICalDateTimeData), ICalDurationDescription(ICalDurationData), ICalPeriodDescription(ICalPeriodData), CalendarDescription(CalendarData), TimestampDescription(TimestampData), Qualification(QualificationData), Requirement([ZoneContext, UncertaintyModel]), ZoneAnnotation(ZoneData), Annotation(AnnotationData), ResolvedPosition(PositionData), Context(ContextData), Presentation([Gregorian, UnsupportedCalendar(Str)])]

Typed observations of declarations, requirements, interpretation results and evaluation status. Pattern-match these data for custom bounded presentation; a fact is not a validated temporal value or an interchange envelope.