Concepts

Core concepts

defineIdFamily validates a trusted family declaration and returns one codec for each declared kind. Each codec has a branded TypeScript ID type, a Zod schema for an untrusted string boundary, and parse and is methods for a string that has already been decoded. Version 1 IDs have the form <prefix>_<21 lowercase base36 characters>. Parsing does not trim, decode, case-fold, or normalize the input. A rejected parse returns bounded metadata and a reason. It does not return the rejected value.

IDs do not declare database uniqueness, relationships, permissions, or entity lifecycle. The domain that declares a family owns those rules and any bounded collision retry.

The root also exports replayKey, correlationKey, and createCorrelationSequence. A replay key is a UUIDv7 for one command. Retain it across an ambiguous retry. A correlation key is a UUIDv4 for transport or provider correlation. A correlation sequence starts at 1 for one connection and throws when it reaches safe-integer exhaustion. None of these keys is a durable domain identity.

words() chooses a candidate name from Cairn’s exported adjective and noun lists. It does not keep a registry or promise uniqueness. Callers choose a word count that fits their collision requirements.