Dates, Time Zones, and Calendars

Pathrule2 Rules • 3 Memories • 1 Skill

Most date bugs come from representing different concepts with the same timestamp: a birthday is not an instant, a meeting time needs a zone, a recurring local schedule crosses daylight-saving changes, and a billing date follows calendar rules rather than fixed durations. This pattern constrains temporal type choice and serialization, records scheduling and display ownership, and provides edge-case tests for zone transitions, month boundaries, locale, and ambiguous local times. It complements internationalization by focusing on temporal meaning and arithmetic; localization still owns language and presentation, while this pattern decides what moment or calendar value is being formatted.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

test-temporal-edge-cases

src/

domain/

Choose the temporal type from the business meaning

Serialize temporal values without ambiguity

Display timezone belongs to the user or record context

Calendar arithmetic follows product rules

scheduling/

Recurring schedules are generated in their named zone

Rules

Choose the temporal type from the business meaning/src/domainhighstrictRepresent instants, date-only values, local date-times, durations, and zoned schedules separately instead of coercing all of them into timestamps.

1	A universal timestamp preserves one moment but destroys other meanings. Date-only and wall-clock values can shift when forced through UTC, while an instant without its scheduling zone cannot reproduce the intended local recurrence.
2
3	- Use an instant for an event that happened at one point on the global timeline, such as creation, payment authorization, or log time.
4	- Use a date-only value for birthdays, holidays, and due dates whose meaning is a calendar day independent of timezone.
5	- Use a local date-time plus an IANA timezone identifier for future appointments and recurring schedules whose wall-clock time must remain stable in that place.
6	- Use a duration for elapsed time and explicit calendar operations for months or years; do not assume every day, month, or year has a fixed number of seconds.
7
8	See /src/scheduling for the adjacent decision or procedure that completes this constraint.

Serialize temporal values without ambiguity/src/domainhighstrictUse explicit machine formats, preserve offsets or zones where required, and reject inputs that omit meaning the domain needs.

1	Human-readable date strings are locale-dependent and runtime parsers accept different subsets. A payload that relies on an implicit local zone or ambiguous day and month order can map to different values on different machines.
2
3	- Serialize instants in a standard timestamp format with an explicit offset, and normalize storage according to the domain contract rather than the current machine timezone.
4	- Serialize date-only values as date-only text and never append a midnight offset merely to reuse an instant column or parser.
5	- Carry the named zone separately for future wall-clock schedules; an offset alone cannot describe later daylight-saving rules.
6	- Parse through an explicit library or schema and reject ambiguous, out-of-range, nonexistent, or unsupported values with a field-specific error.
7
8	See /tests/time for the adjacent decision or procedure that completes this constraint.

Memories

Recurring schedules are generated in their named zone/src/schedulingAdvance the local calendar rule first, then resolve each occurrence to an instant using an explicit ambiguity policy.

1	Adding a fixed duration to the previous occurrence changes local clock time across daylight-saving transitions. The recurrence rule must live in local calendar space, with the zone applied to each generated occurrence.
2
3	- Store the recurrence definition, local time, named zone, start boundary, and any product-specific end or exception rules.
4	- Generate the next local calendar occurrence before converting it to an instant for delivery, storage, or comparison.
5	- Define what happens when a local time does not exist or occurs twice: skip, shift, choose earlier, choose later, or require user confirmation.
6	- Keep generated occurrence identity stable so a scheduler can retry without creating two jobs for the same logical recurrence.
7
8	See /tests/time for the rule or workflow that puts this decision into practice.

Display timezone belongs to the user or record context/src/domainFormat an instant only after selecting the intended viewer, organization, event, or source zone and locale.

1	Converting every timestamp to the server zone or browser default creates inconsistent reports and notifications. The correct display zone is a product decision, not a runtime convenience.
2
3	- Resolve timezone from an explicit user or organization preference when presenting viewer-relative activity.
4	- Use the event or location zone when the local wall time is part of the record, such as a flight, appointment, or store opening.
5	- Include zone or offset in displays where two viewers may compare times or where daylight-saving ambiguity matters.
6	- Keep formatting at the presentation boundary and preserve the underlying instant or calendar value for sorting, filtering, and API transport.
7
8	See /src/scheduling for the rule or workflow that puts this decision into practice.

Calendar arithmetic follows product rules/src/domainDefine end-of-month, leap-day, business-day, and inclusive-boundary behavior instead of inheriting a library's convenient default.

1	Adding one month to a date near the end of a month has several defensible outcomes, and billing or compliance logic often needs one specific answer. The same ambiguity appears in leap years and inclusive date ranges.
2
3	- Document whether month addition clamps to the last valid day, skips an invalid occurrence, or preserves an end-of-month convention.
4	- Define leap-day anniversaries and yearly renewals explicitly for non-leap years rather than accepting silent rollover.
5	- Represent date ranges with clear inclusive or exclusive boundaries and use the same convention in database queries and user-facing copy.
6	- Keep business calendars, holidays, and working-hour rules as versioned domain data when they affect money or obligations.
7
8	See /tests/time for the rule or workflow that puts this decision into practice.

Skills

test-temporal-edge-cases/rootExercise temporal logic across zones, daylight-saving transitions, month ends, leap years, locales, and runtime boundaries.

1	---
2	name: test-temporal-edge-cases
3	description: Test date, timezone, recurrence, or calendar behavior before changing a schedule or serialized contract.
4	---
5
6	# Test Temporal Edge Cases
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Freeze the clock and run the same case with process and browser defaults set to several distant timezones, including a zone without daylight-saving changes.
11	2. Test the transition into and out of daylight-saving time, including nonexistent and repeated local wall-clock values under the declared policy.
12	3. Exercise month end, year end, leap day, minimum and maximum supported dates, and inclusive range boundaries.
13	4. Round-trip API and database serialization for instants, date-only values, local date-times, named zones, and offsets without relying on host parsing.
14	5. Render representative locales and zones, then verify sorting and comparisons use the underlying value rather than formatted text.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often store date-only values as midnight UTC, add fixed hours to advance calendar days, discard the source timezone of a schedule, or parse ambiguous strings differently across clients.

Built for Product teams handling appointments, deadlines, travel, billing dates, notifications, or global collaboration.

Keeps your assistant from:

Moving a birthday to the prior day after timezone conversion
Scheduling a recurring event one hour late after a clock change
Parsing a date string differently in server and browser runtimes
Calculating month boundaries with fixed-duration arithmetic

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25