Section 33: Time, Dates, Time Zones, and Clock Semantics¶

TECHSPEC-33 — Section 33 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Time Philosophy¶

Time-related operations must have explicit and predictable semantics.

The language must prevent ambiguity between calendar dates, local times, elapsed durations, and absolute points in time.

Time must never be treated as interchangeable with an ordinary number without an explicit conversion.

2. Core Time Types¶

The standard library must provide dedicated types:

• Instant: A specific point on the global timeline.
• Date: A calendar date without a time.
• Time: A time of day without a date or time zone.
• DateTime: A date and time with an explicitly defined interpretation.
• Duration: An elapsed amount of time.
• TimeZone: A named time zone with defined historical and current rules.
• CalendarPeriod: A calendar-based period such as a month or year.

Rules: - These types must not be implicitly interchangeable. - Conversions must be explicit. - Each type must have documented precision and range. - Invalid dates and times must produce explicit failures.

3. Absolute Time and Local Time¶

An Instant represents an absolute point in time.

Local date and time representations depend on a time zone.

Rules: - Absolute instants must not depend on the machine's local time zone. - Local date and time conversions must specify a time zone. - UTC must be supported as a standard reference. - Named time zones must use maintained time-zone data. - Fixed UTC offsets must not be treated as equivalent to named time zones.

4. Daylight Saving Time¶

Local clocks can change because of daylight saving time and other regional rules.

Rules: - A local time may be ambiguous when clocks move backward. - A local time may not exist when clocks move forward. - Ambiguous local times must require an explicit resolution policy. - Nonexistent local times must produce an explicit result or follow a declared adjustment policy. - The runtime must not silently choose an interpretation.

5. Duration and Calendar Arithmetic¶

Elapsed time and calendar arithmetic are different operations.

Examples: - Adding 24 hours to an instant means adding a fixed elapsed duration. - Adding one calendar day to a local date means advancing the calendar date. - Adding one month requires a defined rule for dates that do not exist in the destination month.

Rules: - Duration arithmetic must use fixed elapsed units. - Calendar arithmetic must use calendar rules. - Month and year calculations must define invalid-date behavior. - Overflow and underflow must produce explicit failures. - Leap years and leap days must be handled according to the selected calendar.

6. Clock Access¶

Reading the system clock must be an explicit effect.

Proposed effect:

TIME.CLOCK_READ

Example:

FUNCTION currentTime() -> Result<Instant, ClockError>
    EFFECTS: TIME.CLOCK_READ
END FUNCTION

Rules: - System clock access must be declared. - Clock failures must be observable. - Clock values must not be assumed perfectly accurate. - Wall-clock time must be distinguished from monotonic time. - Monotonic clocks should be used for measuring elapsed execution time and timeouts.

7. Scheduling and Timers¶

The standard library should provide explicit scheduling APIs.

Supported operations include: - Delays. - Timeouts. - Periodic execution. - Scheduled execution. - Cancellation. - Deadline enforcement.

Rules: - Timers must have identifiable owners. - Cancellation must have defined behavior. - Periodic execution must define whether missed intervals are skipped, accumulated, or replayed. - Scheduling accuracy must be documented. - Timer completion must not be confused with successful completion of the scheduled operation.

8. Serialization and Representation¶

Time values must use documented serialization formats.

Rules: - Absolute instants should use an unambiguous standardized representation. - Time-zone identifiers must be preserved when required. - Local times without time zones must remain distinguishable from absolute instants. - Precision must not be silently lost during serialization. - Invalid or unsupported representations must produce explicit errors.

9. Compiler and Runtime Responsibilities¶

The compiler and runtime must: - Enforce time-related type distinctions. - Prevent implicit time-zone assumptions. - Distinguish elapsed-time arithmetic from calendar arithmetic. - Require explicit handling of ambiguous local times. - Enforce declared clock-access effects. - Preserve time precision and conversion semantics. - Report unsupported or invalid time operations.

10. Verification Limitations¶

The language cannot guarantee that the operating system clock is accurate or that external time sources are trustworthy.

Verification reports must distinguish: - Clock access declared. - Clock access authorized. - Clock value retrieved. - Time-zone rules applied. - Conversion completed. - Accuracy and synchronization assumptions not established.

11. Design Goal¶

An AI agent must never have to guess whether a value represents a date, local time, absolute instant, or elapsed duration.

Time calculations must behave consistently across execution targets and must expose ambiguity instead of silently choosing an interpretation.

Source and related sections¶

Source file: TECHSPEC-33.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.