Module id

Atom Identification Constructs

This module contains the foundational types and logic for working with Atom identifiers in a cryptographically secure namespace. This enables universal, collision-resistant addressing of software packages (atoms) across sources, with end-to-end integrity from origin to content.

High-Level Vision

The system is designed to create a layered, cryptographic address space for atoms, allowing unambiguous identification and retrieval across diverse repositories or sources. At a conceptual level, this involves:

• An immutable origin identifier (e.g., a repository’s root commit hash) to anchor the namespace and ensure domain separation.
• A human-readable tag (moniker) within that origin, validated for descriptiveness and safety while enabling a vast Unicode-based character set within a single origin.
• A machine-readable id combining the origin and tag into a globally unique identifier, represented as a cryptographic hash derived from the components of the id using BLAKE3 (with the origin serving as a key in derivation), ensuring atoms with the same tag in different origins are cryptographically distinct.

These primitives, coupled with the rest of an atom’s components, enable diverse and efficient tooling capable of unambigiously indexing, querying and addressing software packages with cryptographically sound provenance meta-data from origin, to package identifier, to specific versions and their contents (e.g. via git content hashes).

Key Concepts

Atom Tags are Unicode identifiers that descriptively label atoms within an origin. They are validated to ensure they contain only safe characters and contribute to a vast address space for cryptographic disambiguation.

Atom Ids are the Rust struct coupling a tag to its origin, ultimately represented by the BLAKE3-derived hash these components, providing a cryptographically secure, collision-resistant, and stable identifier for the atom itself. This ensures disambiguation across origins without tying directly to version-specific content (which may be handled in higher layers).

Tag Validation Rules

Atom Tags are validated on construction to ensure they serve as descriptive identifiers while providing a vast character set per origin, suitable for use as the human-readable component of an atom’s cryptographic identity. This allows for meaningful Unicode characters across languages (beyond just ASCII/English) without permitting nonsensical or overly permissive content. Validation leverages Unicode general categories for letters and numbers.

Atom Tags must:

• Be valid UTF-8 encoded Unicode strings
• Not exceed 128 bytes in length (measured in UTF-8 bytes)
• Not be empty
• Start with a Unicode letter (general categories: UppercaseLetter [Lu], LowercaseLetter [Ll], TitlecaseLetter [Lt], ModifierLetter [Lm], or OtherLetter [Lo]; not a number, underscore, or hyphen)
• Contain only Unicode letters (as defined above), Unicode numbers (DecimalNumber [Nd] or LetterNumber [Nl]), hyphens (-), and underscores (_)

Usage Example

use atom::store::git::Root;
use atom::{AtomId, AtomTag, Compute, Origin};

// Create a validated atom tag
let tag = AtomTag::try_from("my-atom").unwrap();

// Create an AtomId with a Git origin
let repo = gix::open(".").unwrap();
let commit = repo
    .rev_parse_single("HEAD")
    .map(|s| repo.find_commit(s))
    .unwrap()
    .unwrap();

let id = AtomId::construct(&commit, tag).unwrap();

// Get the hash for disambiguated identification
let hash = id.compute_hash();
println!("Atom hash: {}", hash);

Structs

AtomId

The type representing all the components necessary to serve as an unambiguous identifier. Atoms consist of a human-readable Unicode identifier, as well as a root field, which varies for each store implementation. For example, Git uses the oldest commit in a repositories history.

AtomTag

A vetted String suitable for an atom’s tag field

IdHash

Represents the BLAKE3 hash of an AtomId.

Enums

Error

Errors that can occur during atom tag validation.

Traits

Compute

Trait for computing BLAKE3 hashes of AtomIds.

Origin

This trait must be implemented to construct new instances of an an AtomId. It tells the AtomId::construct constructor how to calculate the value for its root field.

Type Aliases

Name

For contexts where you want an identifier that is validated similarly to an AtomTag.