# TCL-Y2K: Universal 3-Track Temporal Coordinate System & Interval Engine > **Standard Identifier:** **TCL-Y2K** (`tcl-y2k` / Time Code Layer — Year-2000 Epoch) > **Specification Version:** `1.0.0-rc1` > **Author:** Ton Luong <ton@tcl-y2k.org> > **Affiliation:** tcl-y2k.org > **Homepage / Canonical Spec:** [https://tcl-y2k.org](https://tcl-y2k.org) > **Repository:** [https://github.com/tcl-y2k/tcl-y2k](https://github.com/tcl-y2k/tcl-y2k) > **Date of Adoption:** 2026-07-04 > **Reference Epoch:** `2000-01-01T00:00:00Z` UTC (Day 0) > **Normative Framework:** RFC 2119 & RFC 5234 (ABNF) > **Core Architecture:** The Universal Triad (Semantic Expression · Deterministic B-Tree Bounds · Micro-Temporal Synchronization) --- ## 1. Scope, Purpose & Normative Language ### 1.1 Scope & Purpose This specification defines **TCL-Y2K**, a sovereign, zero-dependency, 3-track temporal coordinate system and interval query engine. It unifies human semantic ambiguity and real-world interval modeling with compiled machine speed. TCL-Y2K applies across all domains of computing: 1. **Relational & Analytical Database Engines:** High-speed composite B-Tree range scans, spatial-temporal partitioning, and $O(\log N)$ Allen Interval Algebra joins in SQLite, DuckDB, PostgreSQL, and Parquet. 2. **Enterprise & Financial Systems:** Fiscal reporting periods, SEC filing windows, bond maturities, Point-in-Time (PIT) backtesting without look-ahead bias, and corporate tenures. 3. **Universal Entity Lifespans:** Single-attribute modeling of people (`lifespan`), organizations (`tenure`), hardware lines, and software releases, eliminating fragmented DOB/DOD columns and NULL-value branching. 4. **Astronomical, Historical & Deep Time:** Symmetrical, bijective Gregorian modulo arithmetic across $\pm 10,000$ years without leap-second float drift or 2038 overflow. 5. **Real-Time & Streaming Media:** Sub-second millisecond offsets (`media_offset_ms`), broadcast SMPTE timecodes, and synchronized sensor streams. 6. **Semantic Graphs & Artificial Intelligence:** Deterministic temporal ground truth for knowledge extraction, entity relation graphs, and machine reasoning. ### 1.2 Normative Terminology (RFC 2119) The key words **"MUST"**, **"MUST NOT"**, **"REQUIRED"**, **"SHALL"**, **"SHALL NOT"**, **"SHOULD"**, **"SHOULD NOT"**, **"RECOMMENDED"**, **"MAY"**, and **"OPTIONAL"** in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). ### 1.3 Design Rationale & Historical Precedent (Informative) The selection of `2000-01-01T00:00:00Z` as the coordinate origin (Day 0) provides key mathematical and architectural advantages: 1. **Astronomical Baseline:** Aligns with the International Astronomical Union standard epoch (**IAU J2000.0**), established for planetary motion and celestial mechanics. 2. **Symmetrical Integer Horizon:** Placing zero at the turn of the millennium creates balanced, human-interpretable signed integer offsets: negative integers span the formative 20th century and ancient history; positive integers span modern computing and future horizons. 3. **Hardware & Database Precedent:** Aligns with 64-bit operating system time representations (such as Apple CoreFoundation `CFAbsoluteTime`), relational engine internal offsets (PostgreSQL `POSTGRES_EPOCH_JDATE`), and institutional quantitative time-series architectures. 4. **Elimination of Year-2038 Overflow:** By operating on signed 64-bit integer days and seconds, TCL-Y2K avoids the 32-bit Unix overflow while maintaining sub-microsecond B-Tree scan speeds. ### 1.4 Comparative Rationale: Why TCL-Y2K Extends and Supersedes Raw EDTF (Informative) The Extended Date/Time Format (EDTF / ISO 8601-2:2019) established expressive string taxonomy for archival temporal ambiguity (`?`, `~`, `%`), masked ranges (`198X`), and intervals (`/`). However, EDTF was designed primarily as a **descriptive cataloging text format** for digital libraries, creating fundamental bottlenecks in production database and software engineering: 1. **Track 1 Isolation (No Native Coordinates):** Raw EDTF provides string notation but no mathematical coordinate system. A database storing raw EDTF strings cannot perform indexed range queries without scanning every row ($O(N)$) and running regex parsers in user-space. TCL-Y2K deterministically compiles Track 1 expressions into closed integer day coordinates $[d_{\text{min}}, d_{\text{max}}]$ in Track 2, enabling sub-microsecond $O(\log N)$ composite B-Tree range scans. 2. **Filesystem & URI Hostility:** Standard EDTF mandates the slash (`/`) delimiter for intervals (e.g. `1998/2004`). In REST APIs, HTTP route parameters, S3 object keys, and local filenames, the slash acts as an active path delimiter, causing route collisions or requiring awkward URL percent-encoding (`%2F`). TCL-Y2K introduces the native, URL-safe double-dot (`..`) interval delimiter (e.g. `1998..2004`, `1955-02-24..2011-10-05`), while maintaining full backwards-compatibility with standard slashes. 3. **Absence of Interval Query Logic:** EDTF defines no relational operators between temporal spans. TCL-Y2K natively integrates **James F. Allen's 13 Temporal Interval Relations** (`tcl_overlaps`, `tcl_contains`, `tcl_within`, `tcl_precedes`, `tcl_meets`, `tcl_equals`), turning complex temporal interval queries into single-cycle CPU integer comparisons in SQL WHERE clauses. 4. **Lack of Micro-Temporal & Media Synchronization:** EDTF terminates at calendar timestamps. Modern distributed systems require synchronizing digital media, video transcripts, sensor arrays, and tick logs. TCL-Y2K incorporates Track 3 (`media_offset_ms` and sync anchors), binding macroscopic historical intervals to microscopic playback offsets in a single unified record. 5. **Namespace Safety:** Raw date strings easily collide with application keywords or other tools (such as Tool Command Language `Tcl`). TCL-Y2K establishes a typed prefix taxonomy (`tcly2k:`, `tcly2k-span:`, `tcly2k-date:`, `tcly2k-era:`), providing self-describing JSON payloads and unambiguous parsing. Therefore, TCL-Y2K is the **preferred computational architecture** for databases, search engines, APIs, and AI reasoning pipelines, losslessly ingesting EDTF while providing the compiled coordinate engine required for production scale. --- ## 2. The 3-Track Architecture ``` ┌────────────────────────────────────────────────────────────────────────────────────────┐ │ TCL-Y2K: Universal 3-Track Temporal Coordinate System │ └───────────────────────────────────────────┬────────────────────────────────────────────┘ │ ┌───────────────────────────────────┼───────────────────────────────────┐ ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ TRACK 1: SEMANTIC│ │ TRACK 2: MACRO │ │ TRACK 3: MICRO │ │ (Human & Logic) │ │ (B-Tree Bounds) │ │ (Sync Timecode) │ │ "circa 1976?" │ ────────────► │ tcl_start_day │ ─────────────► │ media_offset_ms │ │ "2024-Q3" │ │ tcl_end_day │ │ SMPTE 00:23:45 │ │ "1955..2011" │ │ [d_min, d_max] │ │ Tick Offsets │ └──────────────────┘ └──────────────────┘ └──────────────────┘ ``` 1. **Track 1: Semantic Track (Semantic Presentation & Expressive Logic):** * Expresses human, fiscal, and historical temporal ambiguity using standard ISO 8601-2 / EDTF syntax and typed `tcly2k:` prefixes (`1976?`, `2024-03~`, `1955-02-24..2011-10-05`, `2024-Q3`), accompanied by natural language display text, explicit certainty classifications, and provenance notes. 2. **Track 2: Macro Epoch Track (Machine Indexing & Coordinate Engine):** * Maps every temporal expression deterministically to signed 64-bit integer day offsets (`tcl_start_day`, `tcl_end_day`) and sub-day second offsets (`tcl_start_sec`, `tcl_end_sec`) centered on `2000-01-01T00:00:00Z`. 3. **Track 3: Micro Media Track (In-Stream Synchronization):** * Synchronizes relative playback timecodes (`media_offset_ms` or SMPTE `HH:MM:SS:FF`) to underlying digital media, sensor streams, audio/video recordings, and high-frequency trading logs. --- ## 3. Formal ABNF Grammar (Track 1) Conformant TCL-Y2K parsers **MUST** accept strings conforming to the following ABNF grammar ([RFC 5234](https://www.ietf.org/rfc/rfc5234.txt)): ```abnf tcl-expression = interval / single-date interval = single-date ( "/" / ".." ) single-date / "../" single-date / ".." single-date / single-date "/.." / single-date ".." single-date = [ prefix-approx ] ( date-year / date-month / date-day / date-time / date-semester / date-quarter / date-season / date-masked ) [ certainty ] certainty = symbol-certainty / url-certainty symbol-certainty = "?" / "~" / "%" url-certainty = "-unkn" / "-u" / "-approx" / "-a" / "-infer" / "-i" ; ? or -unkn / -u = UNCERTAIN ; ~ or -approx / -a = APPROXIMATE ; % or -infer / -i = INFERRED / UNCERTAIN-APPROXIMATE prefix-approx = "c" / "circa-" / "circa " date-year = [ "-" ] 1*6DIGIT date-month = date-year "-" 2DIGIT date-day = date-month "-" 2DIGIT date-time = date-day "T" 2DIGIT ":" 2DIGIT [ ":" 2DIGIT [ "." 1*3DIGIT ] ] [ "Z" / timezone ] timezone = ( "+" / "-" ) 2DIGIT ":" 2DIGIT date-semester = date-year "-" ( "S" / "s" / "H" / "h" ) ( "1" / "2" ) date-quarter = date-year "-Q" ( "1" / "2" / "3" / "4" ) date-season = date-year "-" ( "Spring" / "spring" / "Summer" / "summer" / "Autumn" / "autumn" / "Fall" / "fall" / "Winter" / "winter" / "21" / "22" / "23" / "24" ) date-masked = date-year-masked / date-month-masked date-year-masked = [ "-" ] 1*3DIGIT 1*3( "X" / "x" ) date-month-masked= date-year "-XX" / date-year "-xx" ``` ### 3.1 Notation Preference Hierarchy (TCL-Y2K Primary vs EDTF Secondary) Conformant TCL-Y2K systems **MUST** parse both TCL-Y2K primary notation and EDTF (ISO 8601-2) secondary notation. However, conformant emitters **SHOULD** serialize temporal coordinates using **TCL-Y2K Primary Notation** for web, database, and REST compatibility. | Temporal Domain | Preferred TCL-Y2K Primary | Secondary EDTF | Technical Rationale & Invariant | | :--- | :--- | :--- | :--- | | **Uncertainty** | **`1976-u`** / `1976-unkn` | `1976?` | The `?` character is reserved as the URI query string delimiter in RFC 3986. `1976-u` avoids unencoded query splitting bugs in HTTP GET requests and REST routes. | | **Approximation** | **`c1976`** / **`1976-a`** / `1976-approx` | `1976~` | `c1976` matches classical historian citation (*circa*); `1976-a` avoids tilde normalization issues across shell and URL environments. | | **Inferred** | **`1976-i`** / `1976-infer` | `1976%` | The `%` character triggers URI percent-decoding failures (HTTP 400 Bad Request) on modern web servers if unencoded. `1976-i` is 100% URL-safe. | | **Closed Intervals** | **`1976..1985`** | `1976/1985` | The `/` character splits REST URI path segments; `..` safely remains within a single URL route parameter. | | **Open Intervals** | **`../1984`** / **`2020-01-01..`** | `2020-01-01/..` | Avoids trailing-slash stripping by reverse proxies and CDNs. | | **Fiscal Quarters** | **`2024-Q1` .. `2024-Q4`** (interval: `2024-Q1..2024-Q4`) | `2024-21` .. `2024-24` (interval: `2024-21/2024-24`) | Human-readable and aligned with ANSI SQL and accounting conventions. | | **Semesters & Halves** | **`2024-S1`**, **`2024-H2`** | *(Non-standard)* | Native support for academic semesters and corporate financial reports. | | **Named Seasons** | **`1976-Spring`**, **`1984-Fall`** | `1976-21` | Self-documenting across archival metadata without looking up obscure ISO numeric codes. | --- ## 4. Deterministic Bounding Box Conversion Invariants Every conformant TCL-Y2K parser **MUST** compute the closed integer bounding box $[d_{\text{min}}, d_{\text{max}}]$ according to the following normative rules: ### 4.1 Resolution Bounds Table | Pattern | Input Example | `tcl_start_day` | `tcl_end_day` | Precision | Certainty | | :--- | :--- | :--- | :--- | :--- | :--- | | **Exact Year** | `1976` | `d(1976, 1, 1)` | `d(1976, 12, 31)` | `year` | `exact` | | **Uncertain Year** | `1976?` / `1976-unkn` / `1976-u` | `d(1976, 1, 1)` | `d(1976, 12, 31)` | `year` | `uncertain` | | **Approximate Year** | `1976~` / `1976-approx` / `c1976` | `d(1976, 1, 1)` | `d(1976, 12, 31)` | `year` | `approximate` | | **Inferred Year** | `1976%` / `1976-infer` / `1976-i` | `d(1976, 1, 1)` | `d(1976, 12, 31)` | `year` | `inferred` | | **Exact Month** | `2024-03` | `d(2024, 3, 1)` | `d(2024, 3, 31)` | `month` | `exact` | | **Approx Month** | `2024-03~` / `2024-03-approx` | `d(2024, 3, 1)` | `d(2024, 3, 31)` | `month` | `approximate` | | **Exact Day** | `2026-08-22` | `d(2026, 8, 22)` | `d(2026, 8, 22)` | `day` | `exact` | | **Exact Second** | `1991-09-17T23:11:04Z` | `d(1991, 9, 17)` | `d(1991, 9, 17)` | `second` | `exact` | | **Semester / Half 1**| `2024-S1` / `2024-H1` | `d(2024, 1, 1)` | `d(2024, 6, 30)` | `semester` | `exact` | | **Semester / Half 2**| `2024-S2` / `2024-H2` | `d(2024, 7, 1)` | `d(2024, 12, 31)` | `semester` | `exact` | | **Calendar Quarter** | `2024-Q3` | `d(2024, 7, 1)` | `d(2024, 9, 30)` | `quarter` | `exact` | | **Spring (Meteorological / ISO 21)** | `1976-Spring` / `1976-21` | `d(1976, 3, 1)` | `d(1976, 5, 31)` | `season` | `exact` | | **Summer (Meteorological / ISO 22)** | `1976-Summer` / `1976-22` | `d(1976, 6, 1)` | `d(1976, 8, 31)` | `season` | `exact` | | **Autumn / Fall (ISO 23)** | `1976-Autumn` / `1976-23` | `d(1976, 9, 1)` | `d(1976, 11, 30)` | `season` | `exact` | | **Winter (Meteorological / ISO 24)** | `1976-Winter` / `1976-24` | `d(1976, 12, 1)` | `d(1977, 2, 28)` | `season` | `exact` | | **Masked Decade** | `198X` / `198x` | `d(1980, 1, 1)` | `d(1989, 12, 31)` | `decade` | `inferred` | | **Masked Century** | `19XX` / `19xx` | `d(1900, 1, 1)` | `d(1999, 12, 31)` | `century` | `inferred` | | **Interval** | `1998..2004` / `1998/2004` | `d(1998, 1, 1)` | `d(2004, 12, 31)` | `day` | `exact` | | **Open Start** | `../1984` / `..1984` | `-2,147,483,648` | `d(1984, 12, 31)` | `day` | `inferred` | | **Open End** | `2020-01-01/..` / `2020-01-01..` | `d(2020, 1, 1)` | `+2,147,483,647` | `day` | `inferred` | ### 4.2 Typed & Generic Prefix Taxonomy To allow unambiguous identification, self-describing JSON fields, URL safety, and prevent namespace collision with Tool Command Language (`Tcl/Tk`), TCL-Y2K defines a normative prefix notation: ```abnf tcl-prefixed = ( generic-prefix / typed-prefix ) tcl-expression generic-prefix = "tcly2k:" / "tcl:" typed-prefix = "tcly2k-span:" / "tcly2k-date:" / "tcly2k-approx:" / "tcly2k-unkn:" / "tcly2k-infer:" / "tcly2k-fuzzy:" / "tcly2k-era:" / "tcly2k-qtr:" / "tcly2k-sem:" / "tcly2k-half:" / "tcly2k-season:" / "tcly2k-media:" ``` #### Canonical Prefixes: * **Generic Catch-All:** `tcly2k:` (e.g. `tcly2k:1955-02-24..2011-10-05`, `tcly2k:1976?`, `tcly2k:1976-approx`) * **Lifespan / Timespan:** `tcly2k-span:` (e.g. `tcly2k-span:1955-02-24..2011-10-05`, `tcly2k-span:1950-08-11..`) * **Exact Date:** `tcly2k-date:` (e.g. `tcly2k-date:1984-01-24`) * **Approximate Date:** `tcly2k-approx:` (e.g. `tcly2k-approx:1976`, `tcly2k-approx:1976-04`) * **Uncertain Date:** `tcly2k-unkn:` (e.g. `tcly2k-unkn:1976`) * **Inferred / Fuzzy Date:** `tcly2k-infer:` / `tcly2k-fuzzy:` (e.g. `tcly2k-infer:1976`) * **Decade / Century:** `tcly2k-era:` (e.g. `tcly2k-era:198X`, `tcly2k-era:198x`) * **Quarter:** `tcly2k-qtr:` (e.g. `tcly2k-qtr:2024-Q3`) * **Semester / Half:** `tcly2k-sem:` / `tcly2k-half:` (e.g. `tcly2k-sem:2024-S1`, `tcly2k-half:2024-H2`) * **Season:** `tcly2k-season:` (e.g. `tcly2k-season:1976-Spring`, `tcly2k-season:1984-Winter`) * **Media Timecode:** `tcly2k-media:#` (e.g. `tcly2k-media:1984-01-24T10:00:00Z#1425000ms`) --- ## 5. Mathematical Epoch Conversion Formulas Let Day 0 be `2000-01-01T00:00:00Z`. ### 5.1 Date to TCL Day $d(Y, M, D)$ (Gregorian to Day Offset) For any astronomical year $Y \in (-\infty, +\infty)$, month $M \in [1, 12]$, and day $D \in [1, 31]$: Let: $$Y' = Y - (M \le 2 ? 1 : 0)$$ $$era = \lfloor (Y' \ge 0 ? Y' : Y' - 399) / 400 \rfloor$$ $$yoe = Y' - era \times 400 \quad \in [0, 399]$$ $$M' = M > 2 ? M - 3 : M + 9$$ $$doy = \lfloor \frac{153 \times M' + 2}{5} \rfloor + D - 1 \quad \in [0, 365]$$ $$doe = yoe \times 365 + \lfloor yoe/4 \rfloor - \lfloor yoe/100 \rfloor + doy \quad \in [0, 146096]$$ The signed integer day offset $d$ from `2000-01-01` is: $$d = era \times 146097 + doe - 730425$$ ### 5.2 TCL Day to Date $YMD(d)$ (Day Offset to Gregorian) Let $z = d + 730425$: 1. $era = \lfloor (z \ge 0 ? z : z - 146096) / 146097 \rfloor$ 2. $doe = z - era \times 146097 \quad \in [0, 146096]$ 3. $yoe = \lfloor (doe - \lfloor doe/1460 \rfloor + \lfloor doe/36524 \rfloor - \lfloor doe/146096 \rfloor) / 365 \rfloor \quad \in [0, 399]$ 4. $y = yoe + era \times 400$ 5. $doy = doe - (365 \times yoe + \lfloor yoe/4 \rfloor - \lfloor yoe/100 \rfloor) \quad \in [0, 365]$ 6. $mp = \lfloor (5 \times doy + 2) / 153 \rfloor \quad \in [0, 11]$ 7. $day = doy - \lfloor (153 \times mp + 2) / 5 \rfloor + 1 \quad \in [1, 31]$ 8. $month = mp < 10 ? mp + 3 : mp - 9 \quad \in [1, 12]$ 9. $year = y + (month \le 2 ? 1 : 0)$ --- ## 6. Formal Allen's Interval Algebra in SQL ### 6.1 Day-Level Interval Relations Let interval $A = [A_{\text{start\_day}}, A_{\text{end\_day}}]$ and interval $B = [B_{\text{start\_day}}, B_{\text{end\_day}}]$. | Allen Relation | Semantic Meaning | SQL Boolean Expression | | :--- | :--- | :--- | | **Overlaps ($A \cap B \neq \emptyset$)** | $A$ and $B$ share any time | `A.tcl_start_day <= B.tcl_end_day AND A.tcl_end_day >= B.tcl_start_day` | | **Contains ($A \supseteq B$)** | $A$ fully encloses $B$ | `A.tcl_start_day <= B.tcl_start_day AND A.tcl_end_day >= B.tcl_end_day` | | **Within ($A \subseteq B$)** | $A$ is fully inside $B$ | `A.tcl_start_day >= B.tcl_start_day AND A.tcl_end_day <= B.tcl_end_day` | | **Precedes ($A < B$)** | $A$ ends before $B$ starts | `A.tcl_end_day < B.tcl_start_day` | | **Meets ($A \to B$)** | $A$ ends exactly when $B$ begins | `A.tcl_end_day + 1 = B.tcl_start_day` | | **Equals ($A = B$)** | Identical time window | `A.tcl_start_day = B.tcl_start_day AND A.tcl_end_day = B.tcl_end_day` | ### 6.2 Sub-Day & High-Precision Second Coordinates For sub-day and second-level precision, implementers compute continuous 64-bit integer second coordinates $T_{\text{sec}}$ from `2000-01-01T00:00:00Z`: $$T_{\text{start\_sec}} = \text{tcl\_start\_day} \times 86400 + \text{tcl\_start\_sec}$$ $$T_{\text{end\_sec}} = \text{tcl\_end\_day} \times 86400 + \text{tcl\_end\_sec}$$ For millisecond streaming / tick data with Track 3 media offset: $$T_{\text{ms}} = (\text{tcl\_start\_day} \times 86400 + \text{tcl\_start\_sec}) \times 1000 + \text{media\_offset\_ms}$$ Allen Interval Algebra over $T_{\text{sec}}$ or $T_{\text{ms}}$ operates identically using standard single-integer range predicates. --- ## 7. Canonical Database Schema (SQLite / DuckDB / PostgreSQL) Conformant relational and columnar database implementations **SHOULD** store temporal coordinates across the 3 tracks using the following canonical column layout: ```sql CREATE TABLE IF NOT EXISTS tcl_events ( id TEXT PRIMARY KEY, title TEXT NOT NULL, category TEXT NOT NULL, -- 'person' | 'entity' | 'fiscal' | 'media' | 'event' -- TRACK 1: SEMANTIC CONTEXT (HUMAN & LLM INTERFACE) expression TEXT NOT NULL, -- "tcly2k:1976?" | "1955-02-24..2011-10-05" | "2024-Q3" | "198X" display_date TEXT NOT NULL, -- "possibly 1976" | "1955-02-24 to 2011-10-05" | "Q3 2024" date_precision TEXT NOT NULL, -- 'second' | 'day' | 'month' | 'year' | 'quarter' | 'decade' | 'century' certainty TEXT NOT NULL, -- 'exact' | 'approximate' | 'uncertain' | 'inferred' temporal_notes TEXT, -- Structured context, inference methodology, or audit trail provenance_summary TEXT, -- Source registry, regulatory filing ID, or archive citation -- TRACK 2: MACRO COORDINATES (B-TREE INTEGER BOUNDS) tcl_start_day INTEGER NOT NULL, -- Signed days from 2000-01-01T00:00:00Z (e.g. -16382) tcl_end_day INTEGER NOT NULL, -- Signed days from 2000-01-01T00:00:00Z (e.g. +4295) tcl_start_sec INTEGER DEFAULT 0, -- Seconds within start day (0 to 86,399) tcl_end_sec INTEGER DEFAULT 86399, -- Seconds within end day (0 to 86,399) -- TRACK 3: MICRO MEDIA & SYNCHRONIZATION (OPTIONAL) media_offset_ms BIGINT, -- In-stream millisecond offset (e.g. 1425830) sync_anchors JSON -- Optional array of stream/sensor channels or SMPTE timecodes ); -- Essential Composite B-Tree Indexes for O(log N) Allen Interval Range Scans CREATE INDEX idx_tcl_interval ON tcl_events(tcl_start_day, tcl_end_day); CREATE INDEX idx_tcl_category_date ON tcl_events(category, tcl_start_day, tcl_end_day); ``` --- ## 8. Reference Engine Implementation (TypeScript / Bun) ```typescript // src/tcl-y2k.ts — Pure Gregorian Modulo Reference Implementation for TCL-Y2K Standard Specification export type TCLPrecision = "century" | "decade" | "year" | "semester" | "quarter" | "season" | "month" | "day" | "second"; export type TCLCertainty = "exact" | "approximate" | "uncertain" | "inferred"; export interface TCLRecord { edtf: string; displayDate: string; datePrecision: TCLPrecision; certainty: TCLCertainty; temporalNotes?: string; tStartDay: number; tEndDay: number; tStartSec: number; tEndSec: number; mediaOffsetMs?: number; } export function isLeapYear(year: number): boolean { const mod4 = ((year % 4) + 4) % 4; const mod100 = ((year % 100) + 100) % 100; const mod400 = ((year % 400) + 400) % 400; return (mod4 === 0 && mod100 !== 0) || mod400 === 0; } export function getDaysInMonth(year: number, month: number): number { if (month === 2) { return isLeapYear(year) ? 29 : 28; } return [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1]; } export function dateToTCLDay(year: number, month: number, day: number): number { let y = year; const m = month; const d = day; y -= m <= 2 ? 1 : 0; const era = ((y >= 0 ? y : y - 399) / 400) | 0; const yoe = y - era * 400; const mp = m > 2 ? m - 3 : m + 9; const doy = (((153 * mp + 2) / 5) | 0) + d - 1; const doe = yoe * 365 + ((yoe / 4) | 0) - ((yoe / 100) | 0) + doy; return era * 146097 + doe - 730425; } export function tclDayToDate(tclDay: number): { year: number; month: number; day: number } { const z = tclDay + 730425; const era = ((z >= 0 ? z : z - 146096) / 146097) | 0; const doe = (z - era * 146097) >>> 0; const yoe = ((doe - ((doe / 1460) | 0) + ((doe / 36524) | 0) - ((doe / 146096) | 0)) / 365) | 0; const y = yoe + era * 400; const doy = doe - (365 * yoe + ((yoe / 4) | 0) - ((yoe / 100) | 0)); const mp = ((5 * doy + 2) / 153) | 0; const d = doy - (((153 * mp + 2) / 5) | 0) + 1; const m = mp < 10 ? mp + 3 : mp - 9; return { year: y + (m <= 2 ? 1 : 0), month: m, day: d }; } export function parseTCL(input: string, notes?: string, mediaOffsetMs?: number): TCLRecord { let str = input.trim(); let certainty: TCLCertainty = "exact"; let extractedMediaOffset = mediaOffsetMs; // Handle prefix notation (e.g. tcly2k:, tcly2k-span:, tcly2k-date:, tcly2k-approx:, tcly2k-unkn:, tcly2k-era:, tcly2k-qtr:, tcly2k-media:, tcl:) if (str.startsWith("tcly2k-media:") || str.startsWith("tcly2k_media:")) { const withoutPrefix = str.slice(13); const [datePart, mediaPart] = withoutPrefix.split("#"); str = datePart; if (mediaPart && extractedMediaOffset === undefined) { extractedMediaOffset = parseInt(mediaPart.replace(/[^0-9]/g, ""), 10); } } else if (str.startsWith("tcly2k-approx:")) { certainty = "approximate"; str = str.slice(14); } else if (str.startsWith("tcly2k-unkn:")) { certainty = "uncertain"; str = str.slice(12); } else if (str.startsWith("tcly2k-infer:") || str.startsWith("tcly2k-fuzzy:")) { certainty = "inferred"; str = str.slice(13); } else if (str.startsWith("tcly2k-span:")) { str = str.slice(12); } else if (str.startsWith("tcly2k-date:")) { str = str.slice(12); } else if (str.startsWith("tcly2k-era:")) { str = str.slice(11); } else if (str.startsWith("tcly2k-qtr:")) { str = str.slice(11); } else if (str.startsWith("tcly2k-sem:")) { str = str.slice(11); } else if (str.startsWith("tcly2k-half:")) { str = str.slice(12); } else if (str.startsWith("tcly2k-season:")) { str = str.slice(14); } else if (str.startsWith("tcly2k:")) { str = str.slice(7); } else if (str.startsWith("tcl:")) { str = str.slice(4); } // Handle prefix approximation (e.g. c1976, circa-1976, circa 1976) if (str.startsWith("circa-") || str.startsWith("circa ")) { certainty = "approximate"; str = str.slice(6); } else if (str.startsWith("c") && str.length > 1 && (str[1] >= '0' && str[1] <= '9' || str[1] === '-')) { certainty = "approximate"; str = str.slice(1); } if (str.endsWith("%")) { certainty = "inferred"; str = str.slice(0, -1); } else if (str.endsWith("~")) { certainty = "approximate"; str = str.slice(0, -1); } else if (str.endsWith("?")) { certainty = "uncertain"; str = str.slice(0, -1); } else if (str.endsWith("-infer")) { certainty = "inferred"; str = str.slice(0, -6); } else if (str.endsWith("-approx")) { certainty = "approximate"; str = str.slice(0, -7); } else if (str.endsWith("-unkn")) { certainty = "uncertain"; str = str.slice(0, -5); } else if (str.endsWith("-i") && str.length > 2) { certainty = "inferred"; str = str.slice(0, -2); } else if (str.endsWith("-a") && str.length > 2) { certainty = "approximate"; str = str.slice(0, -2); } else if (str.endsWith("-u") && str.length > 2) { certainty = "uncertain"; str = str.slice(0, -2); } const clean = str; // 1. Open start interval (e.g. "../1984" or "..1984") if (clean.startsWith("../") || (clean.startsWith("..") && !clean.slice(2).includes(".."))) { const endPart = clean.startsWith("../") ? clean.slice(3) : clean.slice(2); const endRange = parseSingle(endPart); return { edtf: input, displayDate: `before ${formatDisplay(endPart)}`, datePrecision: "day", certainty: certainty === "exact" ? "inferred" : certainty, temporalNotes: notes, tStartDay: -2147483648, tEndDay: endRange.endDay, tStartSec: 0, tEndSec: endRange.endSec, mediaOffsetMs: extractedMediaOffset }; } // 2. Open end interval (e.g. "2020-01-01/.." or "2020-01-01..") if (clean.endsWith("/..") || (clean.endsWith("..") && !clean.slice(0, -2).includes(".."))) { const startPart = clean.endsWith("/..") ? clean.slice(0, -3) : clean.slice(0, -2); const startRange = parseSingle(startPart); return { edtf: input, displayDate: `after ${formatDisplay(startPart)}`, datePrecision: "day", certainty: certainty === "exact" ? "inferred" : certainty, temporalNotes: notes, tStartDay: startRange.startDay, tEndDay: 2147483647, tStartSec: startRange.startSec, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } // 3. Closed interval (e.g. "1998..2004" or "1998/2004" or "-0500..-0300") if (clean.includes("..") || clean.includes("/")) { const delimiter = clean.includes("..") ? ".." : "/"; const [startPart, endPart] = clean.split(delimiter); const startRange = parseSingle(startPart); const endRange = parseSingle(endPart); return { edtf: input, displayDate: `${formatDisplay(startPart)} – ${formatDisplay(endPart)}`, datePrecision: "day", certainty, temporalNotes: notes, tStartDay: startRange.startDay, tEndDay: endRange.endDay, tStartSec: startRange.startSec, tEndSec: endRange.endSec, mediaOffsetMs: extractedMediaOffset }; } // 4. Semester / Half-Year (e.g. "2024-S1", "2024-S2", "2024-H1", "2024-H2") const semesterMatch = clean.match(/^([+-]?\d+)-([SHsh])([12])$/i); if (semesterMatch) { const year = Number(semesterMatch[1]); const type = semesterMatch[2].toUpperCase(); const sem = Number(semesterMatch[3]); const startMonth = sem === 1 ? 1 : 7; const endMonth = sem === 1 ? 6 : 12; const endDayOfMonth = getDaysInMonth(year, endMonth); const startDay = dateToTCLDay(year, startMonth, 1); const endDay = dateToTCLDay(year, endMonth, endDayOfMonth); return { edtf: input, displayDate: `${type}${sem} ${year}`, datePrecision: "semester", certainty, temporalNotes: notes, tStartDay: startDay, tEndDay: endDay, tStartSec: 0, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } // 5. Calendar Quarter (e.g. "2024-Q3", "-0044-Q1") const quarterMatch = clean.match(/^([+-]?\d+)-Q([1-4])$/i); if (quarterMatch) { const year = Number(quarterMatch[1]); const q = Number(quarterMatch[2]); const startMonth = (q - 1) * 3 + 1; const endMonth = startMonth + 2; const endDayOfMonth = getDaysInMonth(year, endMonth); const startDay = dateToTCLDay(year, startMonth, 1); const endDay = dateToTCLDay(year, endMonth, endDayOfMonth); return { edtf: input, displayDate: `Q${q} ${year}`, datePrecision: "quarter", certainty, temporalNotes: notes, tStartDay: startDay, tEndDay: endDay, tStartSec: 0, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } // 6. Season (e.g. "1976-Spring", "1976-21", "1976-Summer", "1976-Autumn", "1976-Fall", "1976-Winter", "1976-24") const seasonMatch = clean.match(/^([+-]?\d+)-(Spring|Summer|Autumn|Fall|Winter|21|22|23|24)$/i); if (seasonMatch) { const year = Number(seasonMatch[1]); const rawSeason = seasonMatch[2].toLowerCase(); let seasonName = "Spring"; let startMonth = 3; let endMonth = 5; let endYear = year; if (rawSeason === "spring" || rawSeason === "21") { seasonName = "Spring"; startMonth = 3; endMonth = 5; } else if (rawSeason === "summer" || rawSeason === "22") { seasonName = "Summer"; startMonth = 6; endMonth = 8; } else if (rawSeason === "autumn" || rawSeason === "fall" || rawSeason === "23") { seasonName = "Autumn"; startMonth = 9; endMonth = 11; } else if (rawSeason === "winter" || rawSeason === "24") { seasonName = "Winter"; startMonth = 12; endMonth = 2; endYear = year + 1; } const startDay = dateToTCLDay(year, startMonth, 1); const endDay = dateToTCLDay(endYear, endMonth, getDaysInMonth(endYear, endMonth)); return { edtf: input, displayDate: `${seasonName} ${year}`, datePrecision: "season", certainty, temporalNotes: notes, tStartDay: startDay, tEndDay: endDay, tStartSec: 0, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } // 5. Masked Millennium (e.g. "1XXX", "1xxx", "2XXX") const maskedMillennium = clean.match(/^([+-]?\d+)[Xx]{3}$/); if (maskedMillennium) { const num = Number(maskedMillennium[1]); const startYear = num >= 0 ? num * 1000 : num * 1000 - 999; const endYear = num >= 0 ? num * 1000 + 999 : num * 1000; const base = num * 1000; return { edtf: input, displayDate: `${base}s millennium`, datePrecision: "century", certainty: "inferred", temporalNotes: notes, tStartDay: dateToTCLDay(startYear, 1, 1), tEndDay: dateToTCLDay(endYear, 12, 31), tStartSec: 0, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } // 6. Masked Century (e.g. "19XX", "19xx", "05XX", "-04XX") const maskedCentury = clean.match(/^([+-]?\d+)[Xx]{2}$/); if (maskedCentury) { const num = Number(maskedCentury[1]); const startYear = num >= 0 ? num * 100 : num * 100 - 99; const endYear = num >= 0 ? num * 100 + 99 : num * 100; const base = num * 100; return { edtf: input, displayDate: `${base}s century`, datePrecision: "century", certainty: "inferred", temporalNotes: notes, tStartDay: dateToTCLDay(startYear, 1, 1), tEndDay: dateToTCLDay(endYear, 12, 31), tStartSec: 0, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } // 7. Masked Decade (e.g. "198X", "198x", "004X", "-015X") const maskedDecade = clean.match(/^([+-]?\d+)[Xx]$/); if (maskedDecade) { const num = Number(maskedDecade[1]); const startYear = num >= 0 ? num * 10 : num * 10 - 9; const endYear = num >= 0 ? num * 10 + 9 : num * 10; const base = num * 10; return { edtf: input, displayDate: `${base}s decade`, datePrecision: "decade", certainty: "inferred", temporalNotes: notes, tStartDay: dateToTCLDay(startYear, 1, 1), tEndDay: dateToTCLDay(endYear, 12, 31), tStartSec: 0, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } // 8. Masked Month (e.g. "2024-XX", "2024-xx") const maskedMonth = clean.match(/^([+-]?\d+)-[Xx]{2}$/); if (maskedMonth) { const year = Number(maskedMonth[1]); return { edtf: input, displayDate: `${year}`, datePrecision: "year", certainty: "inferred", temporalNotes: notes, tStartDay: dateToTCLDay(year, 1, 1), tEndDay: dateToTCLDay(year, 12, 31), tStartSec: 0, tEndSec: 86399, mediaOffsetMs: extractedMediaOffset }; } const single = parseSingle(clean); return { edtf: input, displayDate: formatDisplay(clean, certainty), datePrecision: single.precision, certainty, temporalNotes: notes, tStartDay: single.startDay, tEndDay: single.endDay, tStartSec: single.startSec, tEndSec: single.endSec, mediaOffsetMs: extractedMediaOffset }; } function parseSingle(clean: string) { const isoMatch = clean.match(/^([+-]?\d+)-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|[+-]\d{2}:\d{2})?$/); if (isoMatch) { const year = Number(isoMatch[1]); const month = Number(isoMatch[2]); const day = Number(isoMatch[3]); let hours = Number(isoMatch[4]); let minutes = Number(isoMatch[5]); const seconds = Number(isoMatch[6]); const tz = isoMatch[7]; let dayOffset = dateToTCLDay(year, month, day); if (tz && tz !== "Z") { const sign = tz.startsWith("-") ? -1 : 1; const [tzH, tzM] = tz.slice(1).split(":").map(Number); const offsetMinutes = sign * (tzH * 60 + tzM); let totalMinutes = hours * 60 + minutes - offsetMinutes; if (totalMinutes < 0) { dayOffset -= Math.ceil(Math.abs(totalMinutes) / 1440); totalMinutes = ((totalMinutes % 1440) + 1440) % 1440; } else if (totalMinutes >= 1440) { dayOffset += Math.floor(totalMinutes / 1440); totalMinutes = totalMinutes % 1440; } hours = Math.floor(totalMinutes / 60); minutes = totalMinutes % 60; } const sec = hours * 3600 + minutes * 60 + seconds; return { startDay: dayOffset, endDay: dayOffset, startSec: sec, endSec: sec, precision: "second" as const }; } const dayMatch = clean.match(/^([+-]?\d+)-(\d{2})-(\d{2})$/); if (dayMatch) { const year = Number(dayMatch[1]); const month = Number(dayMatch[2]); const day = Number(dayMatch[3]); const d = dateToTCLDay(year, month, day); return { startDay: d, endDay: d, startSec: 0, endSec: 86399, precision: "day" as const }; } const monthMatch = clean.match(/^([+-]?\d+)-(\d{2})$/); if (monthMatch) { const year = Number(monthMatch[1]); const month = Number(monthMatch[2]); const start = dateToTCLDay(year, month, 1); const end = dateToTCLDay(year, month, getDaysInMonth(year, month)); return { startDay: start, endDay: end, startSec: 0, endSec: 86399, precision: "month" as const }; } const yearMatch = clean.match(/^([+-]?\d+)$/); if (yearMatch) { const year = Number(yearMatch[1]); const start = dateToTCLDay(year, 1, 1); const end = dateToTCLDay(year, 12, 31); return { startDay: start, endDay: end, startSec: 0, endSec: 86399, precision: "year" as const }; } throw new Error(`Invalid TCL date format: "${clean}"`); } function formatDisplay(iso: string, certainty: string = "exact"): string { const prefix = certainty === "approximate" ? "circa " : certainty === "uncertain" ? "possibly " : certainty === "inferred" ? "inferred " : ""; return `${prefix}${iso}`; } ``` --- ## 10. Author's Address ```text Ton Luong tcl-y2k.org Email: ton@tcl-y2k.org URI: https://tcl-y2k.org Repo: https://github.com/tcl-y2k/tcl-y2k ```