Module	Role
`timeweave.tzkit`	Detect, convert, parse, list zones (read path)
`timeweave.updater`	Fetch + SHA-256 verify + cache the rules DB
`timeweave.compiler`	Fetch + verify + `zic`-compile tz source into a zoneinfo tree

Library use

import timeweave

info = timeweave.detect_timezone()
print(info["timezone"], info["utc_offset"], info["dst_active"])

result = timeweave.convert_timezone(
    "2024-03-10 02:30", ["UTC", "Asia/Tokyo"], from_zone="America/New_York"
)
print(result["instant_utc"], result["local_time_kind"])

parsed = timeweave.parse_datetime("Sun, 10 Mar 2024 07:30:00 +0000")

CLI

tzkit detect --use-ip
tzkit convert '2024-03-10 02:30' --from America/New_York --to UTC --to Asia/Tokyo
tzkit parse 'Sun, 10 Mar 2024 07:30:00 +0000'
tzkit list Europe --transitions --sort offset

tz-update check --json
tz-compile refresh --force
tz-compile status

DST policy

Wall-clock times that fall in a DST gap or fold are classified, never guessed silently:

--ambiguous earliest|latest|raise — repeated wall times (fold)
--nonexistent shift_forward|shift_backward|raise — skipped wall times (gap)

raise exits 6 so CI catches the case.

Auto-update

detect_timezone() and convert_timezone() start a non-blocking daemon-thread update check, at most once per 24h, gated by a marker file. Failures are logged and swallowed; the caller's result is never affected.

Disable it:

Variable	Effect
`TIMEWEAVE_NO_AUTO_UPDATE=1`	Disable the on-use check only
`TIMEWEAVE_OFFLINE=1`	Disable all outbound network from the package
`TIMEWEAVE_NO_NETWORK=1`	Same as `OFFLINE`
`TIMEWEAVE_AUTO_INTERVAL`	Seconds between checks (default `86400`)

Environment

Variable	Purpose
`TIMEWEAVE_SRC_URL`	Source endpoint (compiler)
`TIMEWEAVE_CHECKSUM_URL`	Published SHA-256 (default `<url>.sha256`)
`TIMEWEAVE_SIGNATURE_URL` + `TIMEWEAVE_GPG_KEYRING`	Authenticity verification
`TIMEWEAVE_ZIC_PATH`	Absolute `zic` path (trusted config only)
`TIMEWEAVE_CACHE_DIR`	Cache directory
`TZDIR`	Compiled zoneinfo tree; prepended to `zoneinfo.TZPATH` on import
`SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE`	Custom CA bundle
`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`	Standard proxy settings

Security notes

SHA-256 proves integrity, not authenticity. If the same host serves the payload and the checksum, it controls both. Set TIMEWEAVE_SIGNATURE_URL and TIMEWEAVE_GPG_KEYRING against a trusted key for real authenticity.
The compiler targets an app-owned directory by default. Writing into /usr/share/zoneinfo requires --system, needs root, and affects every process on the host. Prefer your OS's signed tzdata package for the system tree; use this module for isolated, air-gapped, or version-pinned caches.
Archive members and Zone/Link names are validated before zic runs, and compiler output is re-checked for containment afterwards.
The zic path is a fixed absolute constant, validated executable, and is never read from a network response.