Ixdtf

Ixdtf :: # (opaque)

Internet extended timestamps, rfc9557-microseconds-v1. The base timestamp uses OffsetTimestamp's four-digit Gregorian, six-fractional-digit profile. RFC 9557 sections 2–5 govern ordered annotations and offset assertions. https://www.rfc-editor.org/rfc/rfc9557.html (April 2024).

At most one leading named/numeric zone and 32 ordered key/value annotations. Limits: 4096 total UTF-8 bytes, 255 zone-name bytes, 64 key bytes, 256 value bytes. Parsing performs no provider lookup. Construction retains O(input) storage; bounded duplicate checking is O(tags squared). Serialization uses bounded repeated appends, at most O(tags * output) allocation traffic, with canonical base text and preserved annotation order/criticality. Unknown elective tags and calendar values survive serialization. Experimental keys are rejected. Elective duplicate keys select their first value; any conflicting duplicate involving a critical tag errors; identical tags are retained. Critical tags require understood processing; only u-ca=gregory is supported.

Interpretation uses a strict conflict policy even for elective zone hints. Named zones require supplied matching immutable rules; aliases require the rules' recorded requested-name provenance. No name guessing or data download. Z/-00:00 assert no local offset; numeric +00:00 does. Calendar annotations select presentation only, never reinterpret the base Gregorian fields. Interpretation uses ZoneRules.offset_at in O(transitions) and retains its actual rules. No lazy/budgeted interpretation claim is made. Snapshots expose stored results without resolving again. Non-Gregorian presentation errors. Numeric zone -00:00 denotes a fixed zero offset, serialized as +00:00. Canonical IXDTF text preserves the declaration; snapshots remain in-memory results with explicit context. No complete ISO or broader-calendar claim.

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

Decode one encoded string using this type's text parser. 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 -> (Ixdtf, state -> Try(state, err))
    where [
        encoding.encode_str : Str, state -> Try(state, err),
    ]

Encodes the canonical standard text as a string in the selected encoding; encoding failures pass through.

from_quote : Str -> Try(Ixdtf, [BadQuotedBytes(Str)])

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

profile : Str

Identifier of the supported text profile described above; it does not imply support for the entire standard.

new : Parts -> Try(Ixdtf, Error)

Validates annotations and profile limits around an already validated base timestamp. Preserves tag order and criticality without consulting zone data.

parts : Ixdtf -> Parts

Returns the retained base timestamp, optional zone and ordered annotations for inspection or checked editing.

parse : Str -> Try(Ixdtf, Error)

Parses a supported timestamp and ordered RFC 9557 annotations. Validates critical processing and limits without resolving named zones.

preferred_calendar : Ixdtf -> [None, Some(Str)]

Returns the first u-ca annotation value, if present. This is a presentation preference, not a reinterpretation of the Gregorian base timestamp.

to_text : Ixdtf -> Str

Canonical base timestamp with retained annotation order and criticality. Numeric zero zone offsets normalize to +00:00.

is_eq : Ixdtf, Ixdtf -> Bool

Compares the entire declaration, including base precision/offset intent, optional zone and ordered tags.

to_hash : Ixdtf, Hasher -> Hasher

Hashes the same declaration fields used by is_eq, so equal values are interchangeable as dictionary keys.

fact_count : Ixdtf -> U64

Bounded declaration facts preserve ordered annotations and criticality. A named zone records its context requirement without looking up rules.

fact_at : Ixdtf, U64 -> [End, Item(SemanticFact)]

Returns the zero-based semantic fact, or End when the index is outside fact_count. Facts describe meaning, not a serialized record.

to_inspect : Ixdtf -> Str

A concise semantic summary for debugging. Use the standard text encoder for storage or interchange.

resolve : Ixdtf, [None, Some(ZoneRules)] -> Try(Snapshot, ResolveError)

Strict interpretation: supplied context is required exactly for Named. Elective unknown tags are retained without acting on them. Unsupported elective calendars affect presentation, not the already supplied instant.

ZoneId : [Named(Str), Numeric(FixedOffset)]

A named zone requiring matching rules at resolution, or a fixed numeric zone offset.

Zone : { critical : Bool, identifier : ZoneId }

Zone annotation and its critical flag; a named identifier is not automatically downloaded or resolved.

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

An ordered key/value annotation and critical flag. Elective unknown values may be retained; unsupported critical processing fails.

Parts : { timestamp : OffsetTimestamp, zone : [None, Some(Zone)], tags : List(Tag) }

The base timestamp, optional zone annotation and ordered tags. Construction validates profile limits and critical-tag compatibility.

Error : [Base(Error), Malformed, Incomplete, TooLarge, TooManyAnnotations, InvalidZone, InvalidTag, ExperimentalKey, UnknownCritical, ConflictingCritical, UnsupportedCriticalCalendar]

Reports base timestamp failures, annotation syntax/limits, invalid identifiers and unsupported or conflicting critical processing.

ResolveError : [NeedsContext, UnexpectedContext, ZoneMismatch, OffsetConflict, OutsideValidity, OutOfRange]

Reports missing/unexpected context, zone-name or numeric-offset conflicts, provider validity limits and coordinate overflow.

Snapshot

Ixdtf.Snapshot :: # (opaque)

An immutable interpretation result retaining its source, actual rules and selected POSIX boundary. Accessors do not re-resolve the timestamp.

resolve : Ixdtf, [None, Some(ZoneRules)] -> Try(Snapshot, ResolveError)

Resolves under the supplied matching rules for a named zone. Fixed/no-zone declarations reject unexpected context; numeric offset conflicts are errors.

source : Snapshot -> Ixdtf

Returns the original validated IXDTF declaration retained by this interpretation.

context : Snapshot -> [None, Some(ZoneRules)]

Returns the immutable zone rules retained for named-zone interpretation, or None when no rules were needed.

boundary : Snapshot -> PosixBoundary

Returns the stored POSIX boundary without performing another offset lookup.

offset : Snapshot -> FixedOffset

Returns the offset selected during interpretation, which may differ from an unasserted base timestamp’s displayed UTC label.

presentation : Snapshot -> Try(LocalDateTime, [UnsupportedCalendar(Str)])

Read the stored Gregorian projection only when the requested preferred calendar is supported. An absent preference adds no calendar assertion.

reresolve : Snapshot, [None, Some(ZoneRules)] -> Try(Snapshot, ResolveError)

Explicitly interprets the retained source again under new context; returns a new snapshot or the same structured interpretation failures as resolve.

same_position : Snapshot, Snapshot -> Bool

Compares only resolved POSIX boundaries, ignoring differences in source declarations or interpretation context.

is_eq : Snapshot, Snapshot -> Bool

Snapshot equality includes the source and complete immutable context, even when provider labels are reused. Use same_position for axis equality. Equality/hashing visit the retained definition; getters do not.

to_hash : Snapshot, Hasher -> Hasher

Hashes the complete stored declaration and interpretation context, consistently with Snapshot.is_eq; use the boundary as a key for position-only identity.

fact_count : Snapshot -> U64

Stored interpretation evidence only: no offset lookup, resolution or presentation conversion happens while reading these facts. The local position is the stored Gregorian projection even if a different requested presentation calendar is unsupported.

fact_at : Snapshot, U64 -> [End, Item(SemanticFact)]

Returns a zero-based stored interpretation fact or End beyond fact_count. Reading evidence performs no new zone lookup.

to_inspect : Snapshot -> Str

A concise summary of stored interpretation evidence; does not re-resolve or provide a persistence representation.