initial commit

crates/loid/Cargo.toml

@@ -0,0 +1,26 @@
+# The LOID generator: a Planck-time timestamp with entropy in its
+# sub-nanosecond digits, offered as an identifier — two functions, an
+# integer, and a refusal to be a UUID. Published under the workspace's one
+# version; the registry metadata below is what it shows.
+[package]
+name = "loid"
+version.workspace = true
+edition = "2024"
+authors.workspace = true
+repository.workspace = true
+license-file.workspace = true
+description = "Loic Identifier. A Planck-time timestamp with hardware entropy in its sub-nanosecond digits. An integer. Your problem."
+readme = "README.md"
+keywords = ["identifier", "planck", "arpanet", "not-a-uuid", "your-problem"]
+categories = ["date-and-time"]
+
+# The one dependency: the calendar itself, at the workspace's single stated
+# version. A LOID is an instant that has been asked to serve as a name, and
+# an instant is the library's to make.
+[dependencies]
+loic.workspace = true
+
+# The library target, named and placed explicitly rather than inferred.
+[lib]
+name = "loid"
+path = "src/lib.rs"

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.

crates/loid/src/lib.rs

@@ -0,0 +1,149 @@
+//! # LOID — Loic Identifier
+//!
+//! Two functions. One type. No opinions, beyond the several that follow.
+//!
+//! A LOID is a Planck-time timestamp drawn from the Loic Calendar's quantum
+//! observation pipeline—the mask-free half of it, the collapse without the
+//! question. Each invocation of `loid()` collapses the sub-nanosecond
+//! superposition of the present moment into a unique 512-bit signed
+//! integer—deterministic in its upper digits (the atomic clock, read through
+//! `CLOCK_TAI`), entropic in its lower digits (a per-thread generator seeded
+//! from the kernel's pool and stirred by the timing of the observation
+//! itself), and unreasonably large by any conventional metric, being a count
+//! of Planck times since the first transmission between networked machines
+//! and therefore some fifty-three digits long before it has finished
+//! introducing itself.
+//!
+//! The shortened variant, `short()`, amputates the lowest 23 decimal orders
+//! of magnitude via integer division, retaining ~11 digits of quantum
+//! entropy from the original ~34. The result is still an `I512`. It is still
+//! your problem. The workspace README lists this crate among the four as the
+//! one with no wrapper type and no opinions; the second claim was
+//! aspirational.
+//!
+//! ## What This Is Not
+//!
+//! - Not monotonic. Two calls within the same nanosecond may produce values
+//!   in either order, because the entropy that fills the nanosecond makes no
+//!   promises about sequence—it makes exactly one promise, uniformity, and
+//!   uniformity is the opposite of order. Across nanoseconds the atomic
+//!   clock is doing its best, and atomic clocks, when disciplined over a
+//!   network, have been known to step. If you need monotonicity, enforce it
+//!   yourself. The universe doesn't care, and per the workspace README,
+//!   section 1.3, does not even agree with itself about simultaneity.
+//!
+//! - Not a UUID. Not a ULID. Not a KSUID. Not a Snowflake. Not any of the
+//!   carefully-engineered identifier schemes designed by reasonable people
+//!   for reasonable systems, with their version nibbles and their variant
+//!   bits and their sixty-four-bit ambitions. This is a raw Planck timestamp
+//!   with entropy spliced into its sub-nanosecond residue—the Loic Public
+//!   License, Section 10, lists "generating unique identifiers from quantum
+//!   observations of the sub-nanosecond void" among the permitted uses, and
+//!   this crate is that permission exercised and nothing more. What you do
+//!   with it is, as noted above, your problem.
+//!
+//! - Not wrapped. There is no newtype, no `Display` of its own, no `FromStr`
+//!   of its own, no serde. The output is `I512`, which already has
+//!   `to_string()` and `from_str()`. The rest is ceremony, and ceremony is
+//!   not shipped here; a caller who wants an instant with methods on it
+//!   wants `loic::LoicInstant`, which is where these two functions get
+//!   theirs.
+//!
+//! - Not tested here. Every test would have to call `now()`, and `now()`
+//!   refuses machines whose kernel does not know what TAI is (see below), so
+//!   a test suite would pass or fail according to your time daemon rather
+//!   than this crate. The arithmetic is `loic`'s and is tested there, where
+//!   it is checked against a naive formula at twice the width; there is
+//!   nothing in these two functions to test that is not either that
+//!   arithmetic or the kernel.
+//!
+//! ## Usage
+//!
+//! ```rust,no_run
+//! let id = loid::loid();       // full Planck timestamp (~53 digits)
+//! let short_id = loid::short(); // truncated by 10^23 (~30 digits)
+//! ```
+
+#![warn(clippy::pedantic)]
+
+/// The one type. Re-exported from `loic`, which re-exports it from `bnum`,
+/// so that a caller who names `loid::I512` and a caller who names
+/// `loic::I512` are naming the same integer and not two integers that
+/// merely agree—a distinction the type system enforces and a reader may
+/// safely forget, which is the best kind of distinction. Five hundred and
+/// twelve bits, signed, of which a fresh identifier uses about a hundred
+/// and seventy-five.
+pub use loic::I512;
+
+/// Procures a fresh Loic Identifier: the full Planck timestamp of this
+/// instant, as an integer, with nothing wrapped around it.
+///
+/// Each call observes the current moment through the Loic Calendar's
+/// dual-source temporal pipeline—atomic time for the deterministic
+/// component, entropy seeded from the kernel's pool and stirred by the
+/// observation's own timing for the sub-nanosecond quantum residue—and
+/// returns the resulting `I512`, copied out of the instant it came in,
+/// since the instant has nothing else to offer an identifier.
+///
+/// The value contains approximately 19 deterministic digits (from
+/// `CLOCK_TAI`, encoding which nanosecond you are in) and 34 entropic digits
+/// (from the seeded generator, collapsing the sub-nanosecond superposition
+/// of roughly 10³⁴ Planck-scale coordinates into one), totaling roughly 53
+/// decimal digits. The two are not added but concatenated: the nanosecond
+/// occupies the high digits and the collapse the low ones, and the whole is
+/// one integer counting Planck times since the Whisper, not a pair of
+/// numbers wearing a single type. Whether this degree of precision is
+/// necessary, useful, or sane is a question this crate declines to
+/// entertain, and the Loic Public License, Section 2, declines on its
+/// behalf.
+///
+/// # Panics
+///
+/// Panics under the same three conditions as `loic::LoicInstant::now()`, of
+/// which it is the thinnest possible wrapper: if `CLOCK_TAI` is unavailable,
+/// if the kernel's entropy pool cannot furnish the generator's seed, or—once
+/// per process, on the first call—if the kernel reports a TAI offset of
+/// zero, which means `CLOCK_TAI` has been `CLOCK_REALTIME` in a name tag all
+/// along. The first two do not occur on any Linux of the kernel generation
+/// the calendar requires. The third occurs on most of them, until chrony or
+/// ntpd is told where the leap-second table is; the panic message says which
+/// line to add, and the workspace README, section 1.2, says why it matters.
+/// On other operating systems, you should not be here, and the compiler will
+/// already have said so.
+#[inline]
+#[must_use = "A Loic Identifier minted and discarded — the universe collapsed thirty-four digits of superposition for an integer nobody kept, and it will not collapse them the same way twice."]
+pub fn loid() -> I512 {
+    *loic::LoicInstant::now().planck()
+}
+
+/// Procures a shortened Loic Identifier: the full timestamp divided by
+/// 10²³, by one 512-bit division that truncates toward zero.
+///
+/// This function observes the full instant exactly as `loid()` does—
+/// generating the full 34 digits of quantum entropy—and only then truncates
+/// 23 of them away, through `loic::LoicInstant::shortened()`. The ordering
+/// matters: one does not generate 11 digits of entropy directly. One
+/// generates 34 and discards 23, because the generator draws uniformly at a
+/// fixed granularity of one Planck time and truncating post-hoc preserves
+/// the statistical properties of the original quantum observation, whereas
+/// a generator asked for eleven digits would be answering a question about
+/// a coarser superposition that the calendar does not recognise.
+///
+/// The result retains approximately 11 digits of entropy, sufficient to
+/// distinguish simultaneous observations with high probability. "High
+/// probability" here means "better than one in a hundred billion," which is
+/// either reassuring or terrifying depending on your failure mode
+/// tolerance, and which the calendar notes is a great deal better than the
+/// odds most calendars offer two events in the same second.
+///
+/// # Panics
+///
+/// Same conditions as `loid()`, for the same reason: the observation is the
+/// same. The truncation itself cannot fail; integer division by a power of
+/// ten is the one operation in this workspace that has never had an
+/// opinion.
+#[inline]
+#[must_use = "A shortened Loic Identifier minted and discarded — twenty-three digits were amputated to make it convenient, and it was still not kept, which suggests convenience was not the obstacle."]
+pub fn short() -> I512 {
+    loic::LoicInstant::now().shortened()
+}