OffsetTimestamp

OffsetTimestamp :: # (opaque)

Complete offset-bearing timestamps, rfc3339-microseconds-rfc9557-base-v1. RFC 3339 sections 5.6–5.8 with RFC 9557 section 2 offset semantics. Four-digit astronomical Gregorian years 0000–9999, required seconds and zero through six supplied fractional digits. This is an instant declaration, not a calendar selection of the supplied precision's width.

Z and -00:00 both mean UTC is known without asserting a local offset; canonical output uses Z. Numeric +00:00 retains its assertion. Lowercase t/z are accepted and emitted uppercase. Fractional width is preserved: .12 and .120 denote the same position but are distinct declarations.

Incomplete prefixes have valid completed fields; unfinished digit fields are checked syntactically. A trailing [ after a complete base timestamp recognizes excluded annotations without validating their grammar. Leap seconds, fractions beyond six digits and IXDTF annotations are explicitly unsupported. No rounding, zone lookup, implicit clock or full ISO claim. Parsing checks a 256-byte limit before copying; construction, conversion and formatting have constant bounded work. Native persistence is a separate format.

parser_for : encoding -> (state -> Try({ value : OffsetTimestamp, rest : state }, [InvalidOffsetTimestamp(Error), Encoding(err), ..]))
    where [
        encoding.parse_str : encoding, state -> Try({ value : Str, rest : state }, err),
    ]

Generic encodings carry canonical text, never the opaque backing record. Encoding failures remain distinct from this profile's validation errors. The encoding owns framing and its work limits; parse bounds the decoded text.

encoder_for : encoding -> (OffsetTimestamp, state -> Try(state, err))
    where [
        encoding.encode_str : Str, state -> Try(state, err),
    ]
from_quote : Str -> Try(OffsetTimestamp, [BadQuotedBytes(Str)])

Typed quoted literals use the same checked profile at compile time. Runtime interpolation remains Str followed by an explicit parse call.

new : Parts -> Try(OffsetTimestamp, Error)
parts : OffsetTimestamp -> Parts
boundary : OffsetTimestamp -> Try(PosixBoundary, [OutOfRange, ..])

This source label is UTC for UnassertedUtc and offset-local otherwise.

from_boundary : PosixBoundary, Offset, U8 -> Try(OffsetTimestamp, Error)

Explicit projection for canonical timestamp output. The requested width must represent the position exactly; this operation never rounds.

to_text : OffsetTimestamp -> Str

Validated fields need at most 32 ASCII bytes: 19 fixed, 7 fractional, and 6 for an asserted offset. Build one owned buffer rather than padded temporary strings. Formatting preserves supplied width and offset intent.

is_eq : OffsetTimestamp, OffsetTimestamp -> Bool
fact_count : OffsetTimestamp -> U64

One bounded semantic fact, retaining supplied decimal width and offset assertion. Reading facts never resolves a zone or materializes coverage.

fact_at : OffsetTimestamp, U64 -> [End, Item(SemanticFact)]
Offset : [UnassertedUtc, Asserted(FixedOffset)]
Parts : { date : GregorianDate, clock : ClockTime, fraction_digits : U8, offset : Offset }
Error : [Malformed, Incomplete, InvalidDate, InvalidTime, InvalidOffset, OutOfRange, TooLarge, UnsupportedPrecision, UnsupportedLeapSecond, UnsupportedAnnotations]