TimedOccurrence

TimedOccurrence(id) :: # (opaque)

An identified nonempty appointment span derived from a timed source. Coordinate duration is a POSIX displacement, not physical SI elapsed time. Calendar duration advances the original Gregorian source label, resolves that calendar anchor with explicit policies, then adds its coordinate tail. Zero calendar movement retains the selected start without another lookup. A coordinate tail may extend beyond zone-data validity: it performs checked POSIX arithmetic and makes no claim about the final local clock label. Explicit endings use a resolved boundary or a local label with end policies. ending retains that intent; duration returns Some only for duration-based appointments and None for explicit ends. InvalidDuration also identifies an explicit end that resolves at or before the start. It does not construct the preimage of every civil label between endpoints.

validate_duration : Duration -> Try({  }, [InvalidDuration, ..])

Validate the duration's component domain without interpreting an anchor.

cursor : id, Occurrence, Duration -> Try(Cursor(id), [InvalidDuration, OutOfRange, OutsideValidity, InvalidDestination(Fields), ..])

Components must be nonnegative and at least one must be positive. Calendar work is bounded; zone interpretation resumes through collect. Existing start interpretation and its immutable rules are preserved.

cursor_with_ending : id, Occurrence, Ending -> Try(Cursor(id), [InvalidDuration, OutOfRange, OutsideValidity, InvalidDestination(Fields), ..])

Construct an appointment with a duration or explicit end. AtLocal uses the start's immutable rules and the supplied end policies. Local label order does not establish timeline order across a fold/gap. Both explicit end forms validate the resolved span, returning InvalidDuration when its end is equal to or before the selected start. AtBoundary needs no rules.

id : TimedOccurrence(id) -> id
start : TimedOccurrence(id) -> Occurrence
ending : TimedOccurrence(id) -> Ending
duration : TimedOccurrence(id) -> [None, Some(Duration)]

Explicit endpoints do not invent a duration. Query coordinate_width on the resolved span when a checked numerical width is desired.

span : TimedOccurrence(id) -> PosixSpan
calendar_anchor : TimedOccurrence(id) -> [None, Some({ source : LocalDateTime, choice : BoundaryChoice })]

The interpreted local end label, or calendar anchor before adding its tail. Explicit resolved boundaries and coordinate durations have no local anchor.

Ending : [After(Duration), AtBoundary(PosixBoundary), AtLocal(LocalEnd)]

Endpoint intent is distinct from an elapsed or calendar quantity.

LocalEnd : { source : LocalDateTime, occurrence : OccurrencePolicy, gap : [RejectGap, UseOffsetBeforeGap] }
Duration : [Coordinate(PosixDelta), Calendar(CalendarDuration)]
CalendarDuration : { delta : CalendarDelta, invalid_date : Policy, tail : PosixDelta, occurrence : OccurrencePolicy, gap : [RejectGap, UseOffsetBeforeGap] }
Batch : { segments : U64, buffered : U64, status : [Complete(TimedOccurrence(id)), Limited({ cursor : Cursor(id), reason : [WorkLimit, BufferLimit] })] }

Cursor

TimedOccurrence.Cursor(id) :: # (opaque)
collect : Cursor(id), ClassificationLimits -> Try(Batch(id), [InvalidDuration, OutOfRange, Gap, Ambiguous, AmbiguousGap, OffsetConflict, ..])