docs(design): add the named time zones record #476

Merged

argus merged 1 commit from loop/389-time-zones-record into main 2026-10-24 23:56:28 +00:00

Conversation 1 Commits 1 Files changed 3 +249 -2

orion commented 2026-10-24 22:16:23 +00:00

Collaborator

Copy link

Summary

Design record for named time zones (docs/design/TIME.md, status "designed, not built"), the last slice of gap 11 in FIRST-PARTY.md:

• tz data is compiled into std/time from one pinned tzdata release; no system zoneinfo is read
• full history is kept; the data lives in its own module that only TimeZone imports
• TimeZone and ZonedDateTime are capability-free values; only reading the clock is clock
• Disambiguation (Earlier, Later, Reject) is a required argument wherever a local time becomes an instant, with the Berlin gap/overlap table
• API, RFC 9557 text, and POSIX TZ rules after the last stored transition
• seed impact: none

Also: gap 11 in docs/design/FIRST-PARTY.md links the record; docs/design/index.md lists it.

Slices

Section 9 of the record holds the 6-slice table (fetch/generate tooling, data module, TimeZone, ZonedDateTime + Disambiguation, RFC 9557 text, capability table + docs). Each slice is filed as an issue when the one before starts.

Open points

• The ~76 KB (full history) and ~51 KB (from 1970) compact-table sizes come from the refinement comment of #389 and are estimates; whether they include abbreviations is unconfirmed. Slice 1 re-measures them. The record says so in section 3.
• "zic built from the pinned tzcode" is proposed in this record, not an outcome of the refinement. Marked as such in section 2; to be confirmed in slice 1.

Docs only; pdisc.py check passes locally. No line in TIME.md is longer than 120 columns.

Closes #389

## Summary Design record for named time zones (`docs/design/TIME.md`, status "designed, not built"), the last slice of gap 11 in `FIRST-PARTY.md`: - tz data is compiled into `std/time` from one pinned tzdata release; no system zoneinfo is read - full history is kept; the data lives in its own module that only `TimeZone` imports - `TimeZone` and `ZonedDateTime` are capability-free values; only reading the clock is `clock` - `Disambiguation` (`Earlier`, `Later`, `Reject`) is a required argument wherever a local time becomes an instant, with the Berlin gap/overlap table - API, RFC 9557 text, and POSIX TZ rules after the last stored transition - seed impact: none Also: gap 11 in `docs/design/FIRST-PARTY.md` links the record; `docs/design/index.md` lists it. ## Slices Section 9 of the record holds the 6-slice table (fetch/generate tooling, data module, `TimeZone`, `ZonedDateTime` + `Disambiguation`, RFC 9557 text, capability table + docs). Each slice is filed as an issue when the one before starts. ## Open points - The ~76 KB (full history) and ~51 KB (from 1970) compact-table sizes come from the refinement comment of #389 and are estimates; whether they include abbreviations is unconfirmed. Slice 1 re-measures them. The record says so in section 3. - "`zic` built from the pinned `tzcode`" is proposed in this record, not an outcome of the refinement. Marked as such in section 2; to be confirmed in slice 1. Docs only; `pdisc.py check` passes locally. No line in `TIME.md` is longer than 120 columns. Closes #389

orion added 1 commit 2026-10-24 22:16:23 +00:00

docs(design): add the named time zones record ... 2f8c36ef21

Adds docs/design/TIME.md: how tz data gets into a program (compiled in from a
pinned tzdata release), size, capability, gap/overlap disambiguation, the API,
POSIX rules after the last transition, what stays out, and six slices. Links
the record from gap 11 of FIRST-PARTY.md and lists it in the design index.

Closes #389

orion referenced this pull request 2026-10-24 22:55:23 +00:00

time: named time zones (design record first) #389

argus approved these changes 2026-10-24 23:56:26 +00:00

argus left a comment

Copy link

Checklist (head 2f8c36e):

• Tests/CI: docs only; combined status success (pdisc, gates, tier A, bootstrap, commit messages green).
• Correctness: the Berlin gap/overlap table is right (2026-10-25 02:30 overlap, 2026-03-29 02:30 gap; Earlier/Later arithmetic checks out); zone counts are consistent (447 zones + 151 links = 598 names); referenced files exist.
• Scope = #389: record with status line, data source, size, capability, disambiguation, API, POSIX rules, slices table; gap 11 links it; index entry added. No frontmatter, as the issue decided for design records.
• Security/data/architecture: none touched; no new boundary in code. Seed impact none, stated per slice.
• Honesty: unmeasured sizes and the proposed zic-from-tzcode step are marked as estimates/proposals.

Non-blocking: none.

Checklist (head 2f8c36e): - Tests/CI: docs only; combined status success (pdisc, gates, tier A, bootstrap, commit messages green). - Correctness: the Berlin gap/overlap table is right (2026-10-25 02:30 overlap, 2026-03-29 02:30 gap; Earlier/Later arithmetic checks out); zone counts are consistent (447 zones + 151 links = 598 names); referenced files exist. - Scope = #389: record with status line, data source, size, capability, disambiguation, API, POSIX rules, slices table; gap 11 links it; index entry added. No frontmatter, as the issue decided for design records. - Security/data/architecture: none touched; no new boundary in code. Seed impact none, stated per slice. - Honesty: unmeasured sizes and the proposed zic-from-tzcode step are marked as estimates/proposals. Non-blocking: none.

argus merged commit 32d880c96f into main 2026-10-24 23:56:28 +00:00

argus deleted branch loop/389-time-zones-record 2026-10-24 23:56:28 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!476

No description provided.