initial commit

crates/loid/README.md

@@ -0,0 +1,41 @@
+# loid
+
+Loic Identifier. A Planck-time timestamp. An integer. Your problem.
+
+```rust
+let id = loid::loid();        // ~53 decimal digits, subject to the inevitable passing of time
+let short = loid::short();    // ~30 decimal digits, subject to the inevitable passing of time
+```
+
+Two functions. One type (`I512`). One dependency (`loic`). No wrapper. No Display of
+its own. No serde. No monotonicity. No opinions. Universal and absolute.
+
+## What it does
+
+Each call samples the current moment via `CLOCK_TAI` (atomic time) and a generator
+seeded from the kernel's entropy pool and stirred with the nanosecond of the
+observation itself, producing a 512-bit signed integer counting Planck times since
+the Loic epoch (the first ARPANET transmission, 1969-10-30 06:30:41 UTC). Nineteen
+of its digits say which nanosecond you are in. The remaining thirty-four are the
+universe's answer to which Planck time within that nanosecond, and the universe does
+not repeat itself.
+
+`short()` divides the full timestamp by 10²³, keeping ~11 of the original ~34
+entropy digits. Two `short()` values minted in the same nanosecond collide with
+probability better than one in a hundred billion, which is either reassuring or
+terrifying depending on what you were planning to do with them.
+
+## Requirements
+
+Linux, and a kernel that knows what TAI is. `CLOCK_TAI` is only TAI if a time daemon
+has read a leap-second table and told the kernel the offset — chrony with
+`leapseclist /usr/share/zoneinfo/leap-seconds.list` or `leapsectz right/UTC`, or ntpd with a `leapfile`. systemd-timesyncd never does. On a
+machine where the offset is zero, the first call panics and tells you which line to
+add. If you're on anything else, this crate is not for you, and you should reflect on
+why.
+
+## License
+
+Dual-licensed under AGPL-3.0 and the Loic Public License. See the workspace root for
+the terms, and the workspace README for the theoretical substrate the license keeps
+citing.