ident

Documentation

Overview

Package ident mints and formats the 16-byte UUIDv7 identifiers used for specs, instances, and tokens (operator decision 2026-07-28: all ids are UUIDv7 where reasonable; bytes on the wire, canonical string at CLI/log boundaries).

Index

• func Namespace() []byte
• func NewV5(name string) []byte
• func NewV7() []byte
• func NodeUUID(nodeID string) []byte
• func Parse(s string) ([]byte, error)
• func SpecUUID(name string) []byte
• func String(b []byte) string

Functions

func Namespace

func Namespace() []byte

Namespace returns the silo's UUIDv5 namespace as raw bytes.

func NewV5

func NewV5(name string) []byte

NewV5 derives a stable identity from a name. Unlike NewV7, the result depends on nothing but the name: every node, every cluster, and every restart computes the same UUID for the same name, with no store lookup and no leader round-trip.

Use it for identities that ARE their name - a spec's operator-facing handle, a node's id. Do NOT use it for per-occurrence identities: instances and tokens must be unique per occurrence, and the lifecycle FSM's tombstones are append-only forever, so a re-admitted instance reusing a retired UUID would collide with its own tombstone. Those stay UUIDv7.

func NewV7

func NewV7() []byte

NewV7 mints a UUIDv7 as raw bytes. UUIDv7 is time-ordered, so ids sort by mint time - a property audit trails rely on.

func NodeUUID

func NodeUUID(nodeID string) []byte

NodeUUID is the stable identity of a cluster node, derived from its node id. Nodes have no minted UUID of their own; this gives the capability scheme a scope to name them by.

func Parse

func Parse(s string) ([]byte, error)

Parse converts a canonical UUID string back to 16 raw bytes.

func SpecUUID

func SpecUUID(name string) []byte

SpecUUID is the stable identity of an agent spec, derived from its operator-facing name.

func String

func String(b []byte) string

String renders 16 raw bytes in canonical UUID form. Anything that is not exactly 16 bytes renders empty - callers treat that as absent.