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

Return the application identity carried by this appointment. Distinct source occurrences can occupy the same span.

start : TimedOccurrence(id) -> Occurrence

Return the interpreted start with its original source, selected boundary, gap evidence and immutable rules.

source : TimedOccurrence(id) -> LocalDateTime

Original local start label, including its calendar and fractional clock. A gap adjustment can project the selected boundary to a different label. This accessor performs no zone lookup or recurrence evaluation.

ending : TimedOccurrence(id) -> Ending

Return the declared ending intent: duration, explicit boundary or local endpoint with its policies.

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

Return the resolved nonempty half-open appointment span. Calendar endpoints have already been interpreted; this does not re-resolve them.

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.

to_inspect : TimedOccurrence(id) -> Str

Return a bounded diagnostic summary without advancing cursors or enumerating occurrences. Use typed accessors for application logic; this text is not a storage format.

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] }

An explicit local end label with its own fold and gap policies. These policies can differ from those used for the start.

Duration : [Coordinate(PosixDelta), Calendar(CalendarDuration)]

Choose positive coordinate displacement or calendar components with explicit end interpretation. A calendar day need not have 24 coordinate hours.

CalendarDuration : { delta : Delta, invalid_date : Policy, tail : PosixDelta, occurrence : OccurrencePolicy, gap : [RejectGap, UseOffsetBeforeGap] }

Nonnegative year/month/day components, invalid-date policy and coordinate tail, plus end fold/gap policies. At least one component or tail must be positive; the tail is applied after the calendar end is resolved.

Batch : { segments : U64, buffered : U64, status : [Complete(TimedOccurrence(id)), Limited({ cursor : Cursor(id), reason : [WorkLimit, BufferLimit] })] }

Result of interpreting one appointment ending. Complete supplies the event; Limited preserves pending interpretation and its reason.

Cursor

TimedOccurrence.Cursor(id) :: # (opaque)

Pending appointment-end interpretation retaining the already resolved start. Resume this cursor instead of selecting the start again.

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

Resolve the pending ending within zone work/storage limits. Complete returns the nonempty span; Limited retains progress. Invalid endpoints or unsupported interpretation remain structured errors.

to_inspect : Cursor(id) -> Str

Return a bounded diagnostic summary without advancing cursors or enumerating occurrences. Use typed accessors for application logic; this text is not a storage format.