Concepts

Cairn gives Fungi packages typed, opaque identifiers, temporary command and correlation keys, and candidate word names. Use it so you do not have to hand-roll your own ID format and parser. The package provides these values and their parsing rules. The calling domain owns persistence, uniqueness, authorization, and lifecycle policy.

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, deterministicReplayKey, correlationKey, and createCorrelationSequence. replayKey() mints a UUIDv7 for one command; retain it across an ambiguous retry. await deterministicReplayKey(domain, parts) derives the same replay-key brand using Web Crypto SHA-256 and length-prefixed tuple encoding in Node, browsers and Workers. Supply a stable host-owned domain and the complete authority scope and stored command identity so a restart derives the same key. 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.