Module id

Atom Identification Constructs

This module provides foundational types for creating and managing atom identifiers within a cryptographically secure namespace. It enables universal, collision-resistant addressing of software packages (atoms), ensuring end-to-end integrity from origin to content.

High-Level Vision

The system establishes a layered, cryptographic address space for atoms, facilitating unambiguous identification and retrieval across diverse repositories. This is achieved through:

• An immutable origin identifier (e.g., a repository’s root commit hash) to anchor the namespace.
• A human-readable label (moniker) that is validated for descriptiveness and safety.
• A machine-readable id that combines the origin and label into a globally unique identifier, represented as a BLAKE3-derived cryptographic hash.

These primitives support robust tooling for indexing, querying, and addressing software packages with verifiable provenance.

Key Concepts

• Atom Labels: Unicode identifiers that label atoms within an origin. They are validated to ensure they contain only safe, descriptive characters.
• Atom Ids: A struct coupling a label to its origin, represented by a BLAKE3-derived hash. This provides a secure, collision-resistant, and stable identifier for the atom.

Label Validation Rules

Atom labels must adhere to the following rules, which are based on the Unicode Standard Annex #31 for Unicode Identifier and Pattern Syntax.

• The input string is first normalized to NFKC (Normalization Form KC).
• The normalized string must not exceed 128 bytes in length.
• The normalized string must not be empty.
• The first character must be a character with the XID_Start property.
• All subsequent characters must have the XID_Continue property, with one exception: the hyphen (-) is allowed.

In this sense atom labels are a superset of UAX #31 with an explicit exception for -. Tags are also a superset of labels for purposes of meta-data and allow : and . as additional separators. The explicit hierarchy is: Identifier ⊂ Label ⊂ Tag.

Usage Example

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

// Create a validated atom label.
let label = Label::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, label).unwrap();

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

Modules

private 🔒

Structs

AtomDigest

Represents the BLAKE3 hash of an AtomId.

AtomId

A struct that couples an atom’s label to its origin.

Identifier

A type like Label implementing UAX #31 precisely (no exception for -)

Label

A validated string suitable for use as an atom’s label.

Tag

A type like Label but with exceptions for : and . characters for metadata tags

Enums

Error

An enumeration of errors that can occur during atom label validation.

Constants

ID_MAX 🔒

Traits

Compute

A trait for computing the BLAKE3 hash of an AtomId.

Origin

A trait for constructing new instances of an AtomId.

VerifiedName 🔒

A trait representing the unambiguous rules to validate and construct an identifier. The default implementations are the rules used for atom labels described in the top-level module documentation, but can be modified to allow for some flexibility, e.g. tags have identical rules with the exception of allowing : as an additional allowed separator.

Type Aliases

Name

A type alias for label in contexts where the term Label is confusing.