@tcl-y2k/core

v1.0.0-rc2

Published

6 days ago

TCL-Y2K: Easy Date Entry for Users · Effortless Date Management in Any Database

0High
0Medium
0Low

tcl-y2k

temporal timecode edtf interval-algebra bitemporal finance sqlite duckdb y2k timeseries

TCL-Y2K: Universal 3-Track Time Code Layer

Easy Date Entry for Users · Effortless Date Management in Any Database
Specification Version: 1.0.0-rc2
Reference Epoch: 2000-01-01T00:00:00Z UTC (Day 0)
Core Architecture: The Universal Triad (Semantic Expression · Deterministic B-Tree Bounds · Micro-Temporal Synchronization)

 ┌────────────────────────────────────────────────────────────────────────────────────────┐
 │                                        TCL-Y2K                                         │
 └───────────────────────────────────────────┬────────────────────────────────────────────┘
                                             │
         ┌───────────────────────────────────┼───────────────────────────────────┐
         ▼                                   ▼                                   ▼
┌──────────────────┐               ┌──────────────────┐                ┌──────────────────┐
│ 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"     │               │ [start_day, end_day] │                │ Tick Offsets     │
└──────────────────┘               └──────────────────────┘                └──────────────────┘

1. Introducing TCL-Y2K

TCL-Y2K (Universal 3-Track Time Code Layer) is a sovereign coordinate engine format. It is easy for humans to read and write. It is easy for machines and relational databases to index and query without slow regex scans. It bridges the gap between expressive text strings and exact point-in-time timestamps. TCL-Y2K is a text format designed for natural, effortless data entry. It allows everyday users, archivists, and catalogers to enter dates exactly as they read and write them (early 1950s, 13th century, 53 BCE, c1976, 1998..2004), using intuitive, punctuation-friendly conventions that prevent input errors in search bars, web forms, and catalog databases. These properties make TCL-Y2K an ideal temporal data-entry and interchange format.

TCL-Y2K is built on three structures:

A semantic presentation track. In various systems, this is a human-readable expression of precision and certainty (1976-u, 2024-Q3, 1955-02-24..2011-10-05).
A macro epoch track. In most languages and databases, this is realized as a signed 64-bit integer bounding box of [start_day, end_day], anchored to 2000-01-01 (Day 0).
A micro media track. This represents sub-microsecond time bounds or millisecond video/audio streaming offsets (media_offset_ms).

These are universal temporal structures supported across virtually all modern databases, astronomical systems, and financial architectures. In TCL-Y2K:

A closed interval is a fixed temporal range separated by .. double dot (1976..1985).
An open start bound is a range without a known beginning (..1984).
An open end bound is a range without a known conclusion (2020-01-01..).
An exact calendar date adheres to standard ISO 8601 (YYYY-MM-DD) (e.g. 2024-03-15, 2000-01-01), parsing with zero migration churn as the baseline starting point for precise time.
A value can be a standard year (1976), fiscal quarter (2024-Q1), semester (2024-S1), or season (1984-Fall).
A year expresses uncertainty or approximation with URL-safe suffixes (1976-u, c1976, 1976-a, 198X).
A historical expression captures natural human historiographical and archival notation: ordinal centuries (13th century, 5th century BCE), sub-decade partitions (early 1950s, mid 1940s, late 1960s), plural decades (1950s), and BCE dates (53 BCE, c53 BCE, 53-03-15 BCE).
A macro epoch coordinate is a signed 64-bit integer spanning ±5.8 trillion days (±292 billion years) with sub-microsecond interval overlap logic: start_day <= B.end AND end_day >= B.start.

Excepting a few secondary EDTF compatibility details, that completely describes the engine.

2. Supported Formats & Syntax Reference

TCL-Y2K unifies modern ISO timestamps, archival historical conventions, EDTF masked wildcards, and natural language temporal periods into deterministic bounding boxes:

ISO 8601 (YYYY-MM-DD) as the Precise Baseline: Standard ISO 8601 serves as the universal foundation for exact calendar dates. TCL-Y2K natively adopts this standard, meaning exact inputs like 2024-03-15 or 2000-01-01 act as the starting point and require no conversion.
However, real-world information is frequently less exact. Human memory, historical records, and everyday planning often naturally express time as a span or an approximation—such as "circa 1976", "the 1950s", or "Q3 2024". When systems expect a precise day, recording these broader timeframes often requires defaulting to a specific date (like January 1st), which can inadvertently obscure the true, approximate nature of the original information.
TCL-Y2K builds upon ISO 8601 to capture this natural human ambiguity. It expands the standard to safely and accurately record uncertainty (1976-u), approximations (c1976), intervals (1998..2004), and natural eras (13th century)—preserving the exact level of detail known, while translating them all into clean, queryable database bounds.
Database & SQL Wildcard Safety Note: In relational databases (SQLite, PostgreSQL, MySQL, DuckDB), ? is the universal positional parameter placeholder / single-character wildcard, while % is the standard SQL LIKE multi-character wildcard (WHERE col LIKE '1976%'). Storing or querying raw EDTF strings with ? or % causes severe wildcard collisions, driver parameter binding bugs, and query escaping hazards. TCL-Y2K standardizes clean alphanumeric suffixes (1976-u for uncertain, 1976-i for inferred) to ensure 100% database wildcard safety and URL route safety.
Natural Archival Text vs. Raw EDTF: Standard EDTF relies exclusively on numeric interval notation. Because it does not process natural language text strings, catalogers must manually compute numeric slash intervals (1201/1300 for the 13th century), which can easily introduce off-by-one errors. TCL-Y2K accepts natural human text strings as first-class input and maps them deterministically to their correct cardinal day bounds.

3. Multi-Runtime Implementations

4. Quickstart & Usage

A. CLI Utility

# Parse human temporal expression
./src/cli.ts parse "1976-u" --notes "MOS 6502 Week 42 date code"

# Generate SQL insert row
./src/cli.ts sql "1984-01-24" --id "mac-debut" --title "Macintosh Debut" --category "hardware"

# Ingest JSON/JSONL timeline archive
./src/cli.ts ingest sample_transcripts.jsonl --out database_rows.json

# Convert signed TCL day offset back to Gregorian date
./src/cli.ts to-date -10957 # -> 1970-01-01

B. SQLite C Extension & Allen's Interval Algebra

-- Load extension
.load build/sqlite3_tcl.dylib

-- Create timeline table with B-Tree indices
CREATE TABLE timeline (
  id TEXT PRIMARY KEY,
  title TEXT,
  edtf TEXT,
  tcl_start_day INTEGER,
  tcl_end_day INTEGER
);
CREATE INDEX idx_timeline_range ON timeline(tcl_start_day, tcl_end_day);

-- Insert records using native UDFs
INSERT INTO timeline VALUES
  ('evt1', 'Apple II Era', '1976..1985', tcl_start_day('1976..1985'), tcl_end_day('1976..1985')),
  ('evt2', 'Macintosh Debut', '1984-01-24', tcl_start_day('1984-01-24'), tcl_end_day('1984-01-24'));

-- Allen's Interval Algebra: Query all events overlapping the 1980s decade
SELECT * FROM timeline
WHERE tcl_overlaps(tcl_start_day, tcl_end_day, tcl_start_day('198X'), tcl_end_day('198X'));

C. WebAssembly in JavaScript / Bun / Node

import { readFileSync } from "fs";

const wasmBuffer = readFileSync("dist/tcl_y2k.wasm");
const { instance } = await WebAssembly.instantiate(wasmBuffer, {});
const wasm = instance.exports;

// Calculate signed day offset from Y2K epoch:
const day = wasm.date_to_tcl_day(1970n, 1, 1); // -> -10957n

D. Python

from tcl_y2k import parse_tcl, tcl_overlaps

record = parse_tcl("1976-u")
print(record.t_start_day, record.t_end_day) # -> -8766, -8401

# Allen algebra comparison:
overlaps = tcl_overlaps(-8766, -8401, -7305, -3653)

E. Rust Zero-Allocation Crate (`#![no_std]`)

use tcl_y2k::{parse_tcl, tcl_contains, Certainty};

let jobs = parse_tcl("tcly2k:1955-02-24..2011-10-05").unwrap();
assert_eq!(jobs.t_start_day, -16382);
assert_eq!(jobs.t_end_day, 4295);

// Check if Macintosh Debut (-5821) occurred during Steve Jobs' lifetime:
assert!(tcl_contains(jobs.t_start_day, jobs.t_end_day, -5821, -5821));

F. DuckDB Parquet Analytical Macros

-- Load macros
.read duckdb/tcl_y2k.sql

-- Query millions of Parquet events with zero date-parsing overhead:
SELECT id, title
FROM 'events.parquet'
WHERE tcl_overlaps(tcl_start_day, tcl_end_day, -7305, -3653); -- The 1980s Tech Boom

5. Build, Test & Quality Verification

# 1. Compile native SQLite extension and WebAssembly binary:
make all

# 2. Run TypeScript reference & SQLite test suites (170 tests):
bun test

# 3. Run Rust `#![no_std]` test suite & benchmark (13.5M ops/sec):
cargo test --release --manifest-path crates/tcl-y2k/Cargo.toml -- --nocapture

# 4. Run Python conformance test suite:
python3 python/test_tcl.py

# 5. Run 1M Parquet DuckDB OLAP Benchmark:
bun run bench/duckdb_bench.ts

# 6. Quality 91 Sentinel Audit:
.forge/scripts/audit.sh

6. Specification & Conformance Vectors

The formal normative definition of the 3-Track Coordinate System, bounding invariants, SQL query semantics, and polyglot reference engines:

Interactive Online Reader (Rendered & Raw): https://tcl-y2k.org/spec.html (docs/spec.html)
Normative Markdown Definition: docs/specs/tcl-y2k-specification.md
83 Conformance Vectors (.json): docs/specs/tcl-y2k-conformance-vectors.json

Author & Governance

Author: Ton Luong <[email protected]>
Organization: tcl-y2k.org
Canonical Specification: https://tcl-y2k.org
Repository: https://github.com/tcl-y2k/tcl-y2k

License

MIT / Open Standard Specification.