The selector character is drawn from the URL-safe Base64 character set defined in RFC-4648: [A-Z, a-z, 0-9, -, _]. This 64-character alphabet provides sufficient space to encode both table selection information and type codes for common primitives within a single character.

Key Components

The code-table-selector integrates with several key CESR components:

• Code Tables: The selector references specific code tables that define the mapping between character sequences and primitive types. Each code table is optimized for different primitive categories (e.g., cryptographic keys, digests, signatures).

• Derivation Codes: The selector may itself be a derivation code for common primitives, encoding both the cryptographic algorithm and the expected length of the primitive.

• Framing Codes: The selector is the first element of the framing code structure that enables self-framing primitives - primitives that contain all information needed to parse them without external delimiters.

Data Format

Character Encoding

The code-table-selector is encoded as a single Base64 URL-safe character, which represents 6 bits of information. This provides 64 possible values (2^6 = 64), allowing the selector to distinguish between:

• Multiple code table selections
• Type codes for the most common primitives with pad size 1
• Reserved values for future extensions

The Base64 URL-safe character set ensures that CESR streams can be safely transmitted through text-based protocols (HTTP headers, JSON, URLs) without requiring additional escaping or encoding.

Field Definitions

While the code-table-selector is a single character, it encodes multiple logical fields through its value:

Table Selection Field: Certain character values indicate that the parser should switch from the default code table to an alternate table. For example, specific characters might indicate:

• Default table (most common primitives)
• Large code table (extended primitive types)
• Count code table (for group framing)
• Opcode table (for stream processing instructions)

Type Code Field: When the selector character indicates the default table, the character itself serves as the type code for primitives with pad size 1. This includes some of the most frequently used primitives in KERI applications, such as certain public key types and digest algorithms.

Size and Constraints

The code-table-selector has strict size constraints that derive from CESR's 24-bit alignment requirement:

• Text Domain Size: Exactly 1 Base64 character (6 bits)
• Binary Domain Size: The selector is part of the first byte when converted to binary domain
• Alignment Contribution: The selector contributes to the overall primitive length, which must be an integer multiple of 4 characters (24 bits) in the text domain

The 24-bit alignment constraint is fundamental to CESR's composability property - the ability to convert concatenated primitives between text and binary domains without loss. Since Base64 characters encode 6 bits and bytes encode 8 bits, 24 bits (the least common multiple of 6 and 8) is the minimum alignment boundary that ensures clean conversion.

Encoding Format

The code-table-selector participates in CESR's pre-padding encoding scheme. Unlike naive Base64 encoding that uses trailing = pad characters, CESR uses leading pad bytes ("lead bytes") prepended to raw binary values before Base64 conversion. The selector character is part of the encoded representation that results from this pre-padding process.

For primitives with pad size 1, the encoding process works as follows:

1. The raw binary value requires 2 lead bytes to achieve 24-bit alignment
2. The pre-padded binary is converted to Base64, producing 4 characters
3. The first 2 characters result from the lead bytes and can be replaced with meaningful codes
4. The first character becomes the code-table-selector/type code
5. The second character provides additional type or size information
6. The remaining 2 characters encode the actual value

This encoding scheme ensures that the selector character is always present and always in the first position, enabling efficient stream parsing.

Operations

Creation and Initialization

The code-table-selector is created during the primitive serialization process when converting from the Raw Domain (where cryptographic operations occur) to the Text Domain (where streaming and transmission occur).

Serialization Process:

1. Primitive Type Determination: The serializer determines the type of primitive being encoded (e.g., Ed25519 public key, Blake3-256 digest, Ed25519 signature)

2. Pad Size Calculation: The serializer calculates the pad size required for 24-bit alignment: ps = (3 - (N mod 3)) mod 3 where N is the raw binary length in bytes

3. Code Table Selection: Based on the primitive type and pad size, the serializer selects the appropriate code table and determines the selector character

4. Selector Assignment: For primitives with pad size 1 in the default table, the selector character is assigned as the type code. For other cases, the selector indicates which code table to use for interpreting subsequent characters.

5. Stream Composition: The selector character is prepended to the encoded primitive, forming the first character of the serialized representation

Parsing and Interpretation

The code-table-selector is the first element examined during stream parsing, enabling the parser to determine how to process subsequent characters.

Parsing Process:

1. Character Extraction: The parser reads the first character from the CESR stream

2. Table Lookup: The parser uses the selector character to look up the appropriate code table. This lookup determines:

   • Whether to use the default table or switch to an alternate table
   • For default table entries, the primitive type and expected length
   • The number of additional characters to read for the complete primitive

3. Primitive Extraction: Based on the code table information, the parser extracts the exact number of characters needed for the complete primitive

4. Domain Conversion: If needed, the parser converts the text domain representation to binary or raw domain for cryptographic verification

5. Stream Advancement: The parser advances to the next primitive in the stream, which begins with its own code-table-selector

This parsing process enables self-framing - each primitive contains all information needed to parse it without external delimiters or length fields.

Verification and Validation

The code-table-selector participates in several verification processes:

Stream Integrity Verification:

• The selector must be a valid Base64 URL-safe character
• The selector must map to a defined entry in the code table registry
• The primitive length indicated by the selector must align with 24-bit boundaries
• The complete primitive (selector + value) must be parseable without errors

Type Validation:

• The selector indicates the expected primitive type (key, digest, signature, etc.)
• Subsequent processing can verify that the primitive value is valid for its type
• For example, a selector indicating an Ed25519 public key should be followed by exactly 32 bytes of key material

Composability Verification:

• The selector ensures that primitives maintain proper alignment for text-binary conversion
• Round-trip conversion (text → binary → text) must preserve the selector character
• Concatenated primitives must remain separable after domain conversion

Usage Context

Protocol Integration

The code-table-selector is used throughout the KERI protocol stack and related technologies:

KERI Key Event Logs (KEL):

• Every key event message in a KEL contains CESR-encoded primitives
• Inception events include public keys with selector-prefixed encoding
• Rotation events include next key digests with selector-prefixed encoding
• Interaction events include seals and anchors with selector-prefixed encoding

ACDC Credentials (ACDC):

• SAID (Self-Addressing Identifier) fields use selector-prefixed digests
• Issuer and issuee AIDs use selector-prefixed identifiers
• Signature attachments use selector-prefixed signature primitives
• Schema identifiers use selector-prefixed SAIDs

OOBI Discovery (OOBI):

• Out-Of-Band Introduction messages include selector-prefixed AIDs
• Endpoint URLs are associated with selector-prefixed identifiers
• Witness and watcher identifiers use selector-prefixed encoding

Transaction Event Logs (TEL):

• Registry identifiers use selector-prefixed encoding
• Credential status events include selector-prefixed SAIDs
• Backers and registrars use selector-prefixed AIDs

Lifecycle Management

The code-table-selector has a simple lifecycle tied to the primitive it prefixes:

Creation: The selector is assigned during primitive serialization based on the primitive type and pad size

Transmission: The selector is transmitted as the first character of the primitive in CESR streams

Storage: The selector is stored as part of the primitive representation in databases, files, and logs

Parsing: The selector is read and interpreted during stream parsing to determine primitive boundaries

Verification: The selector is validated during cryptographic verification to ensure proper primitive typing

Archival: The selector remains part of the primitive representation in long-term storage, ensuring future parseability

The selector does not have independent lifecycle events - it is always part of a larger primitive and shares that primitive's lifecycle.

Related Structures

The code-table-selector interacts with several related CESR structures:

Derivation Codes: The selector may itself be a derivation code that indicates the cryptographic algorithm used to derive a key or digest. For example, a selector character might indicate "Ed25519 public key" or "Blake3-256 digest."

Count Codes: For group framing, the selector may indicate a count code table that provides information about the number of primitives in a group. This enables efficient parsing of primitive groups without scanning the entire group.

Framing Codes: The selector is the first component of a framing code - a code that delineates the number of characters or bytes that can be extracted atomically from a stream.

Code Tables: The selector references specific code tables that define the mapping between character sequences and primitive types. CESR maintains multiple code tables optimized for different primitive categories.

Primitives: The selector prefixes primitives - serialized values associated with cryptographic operations including digests, salts, seeds, private keys, public keys, and signatures.

Stream Processing Context

The code-table-selector enables several critical stream processing capabilities:

Cold Start Parsing: A parser can begin processing a CESR stream at any primitive boundary by reading the selector character. This enables efficient stream processing without requiring the parser to scan from the beginning of the stream.

Multiplexing: Multiple CESR streams can be multiplexed into a single stream, with each primitive maintaining its selector. Demultiplexing is straightforward because each primitive is self-framing.

Pipelining: CESR streams can be processed in a pipelined fashion, with different stages operating on different primitives concurrently. The selector enables each stage to quickly determine primitive boundaries.

Partial Parsing: Applications can parse only the primitives they need from a stream by examining selectors and skipping primitives that are not relevant. This enables efficient filtering and routing of CESR streams.

Error Recovery: If a parser encounters an invalid primitive, it can attempt to resynchronize by scanning for the next valid selector character. This provides some resilience to stream corruption.

Version Management

The code-table-selector participates in CESR's version management through the CESR-version mechanism:

Version Specification: A special count code can specify the version of all CESR code tables in a given stream or stream section. This version information affects how selectors are interpreted.

Backward Compatibility: New versions of CESR may introduce new selector characters or redefine existing ones. The version specification ensures that parsers interpret selectors according to the correct version.

Forward Compatibility: Reserved selector values enable future extensions without breaking existing parsers. Parsers encountering unknown selectors can skip the primitive or signal an error.

Performance Considerations

The code-table-selector design has significant performance implications:

Single-Character Lookup: The selector enables primitive type determination with a single character lookup, minimizing parsing overhead.

No Scanning Required: Unlike delimited formats that require scanning for delimiters, the selector provides immediate information about primitive boundaries.

Cache-Friendly: The selector enables predictable memory access patterns, improving CPU cache utilization during stream processing.

Minimal Overhead: The selector adds only 1 character (6 bits) of overhead per primitive, which is minimal compared to alternative framing schemes.

Efficient Conversion: The selector participates in CESR's efficient text-binary conversion, which operates on 24-bit aligned blocks without bit-level manipulation.

These performance characteristics make CESR suitable for high-throughput applications such as witness pools processing thousands of key events per second or watcher networks synchronizing large KERLs.

Implementation Considerations

Implementing code-table-selector support requires careful attention to several technical details:

Code Table Registry: Implementations must maintain a registry of code tables that maps selector characters to primitive types and lengths. This registry must be version-aware to support multiple CESR versions.

Selector Validation: Implementations must validate that selector characters are valid Base64 URL-safe characters and map to defined code table entries. Invalid selectors should trigger appropriate error handling.

Alignment Verification: Implementations must verify that primitives maintain 24-bit alignment. The selector contributes to this alignment, and implementations must ensure that the complete primitive (selector + value) has a length that is an integer multiple of 4 characters.

Domain Conversion: Implementations must correctly handle selector characters during text-binary domain conversion. The selector must be preserved during round-trip conversion to maintain primitive parseability.

Stream Parsing: Implementations must use the selector to drive stream parsing logic, extracting the correct number of characters for each primitive based on the selector's code table entry.

Error Recovery: Implementations should provide mechanisms for recovering from invalid selectors, such as scanning for the next valid selector character or signaling a stream error.

These implementation considerations are critical for ensuring interoperability between different CESR implementations and maintaining the protocol's security and reliability properties.

When converting between text and binary domains, the selector must be preserved:

Text to Binary: The selector character (6 bits) becomes part of the first byte in binary representation. Implementations must correctly pack the selector bits with subsequent value bits.

Binary to Text: The first byte (containing selector bits) must be correctly unpacked to reconstruct the selector character.

Round-trip conversion (text → binary → text) MUST preserve the selector character exactly. This is critical for maintaining CESR's composability property.

Performance Optimization

For high-performance implementations:

• Precompute code tables: Build lookup tables at initialization rather than computing on each parse
• Use switch statements: For selector dispatch, use switch/case statements rather than dictionary lookups where possible
• Minimize allocations: Reuse buffers for primitive extraction rather than allocating new strings/arrays
• Batch processing: Process multiple primitives in a single pass when possible
• SIMD operations: For binary domain conversion, use SIMD instructions to process multiple bytes in parallel

Error Recovery

Implementations should provide mechanisms for recovering from invalid selectors:

def parse_with_recovery(stream: str) -> list:
    primitives = []
    pos = 0
    
    while pos < len(stream):
        try:
            prim, new_pos = parse_primitive(stream, pos)
            primitives.append(prim)
            pos = new_pos
        except ValueError as e:
            # Log error
            logger.warning(f"Invalid primitive at {pos}: {e}")
            # Attempt to find next valid selector
            pos = find_next_selector(stream, pos + 1)
            if pos == -1:
                break  # No more valid selectors
    
    return primitives

Testing Requirements

Implementations must test:

• All selector characters: Verify correct parsing for every defined selector
• Table switching: Verify correct behavior when selectors indicate alternate tables
• Invalid selectors: Verify appropriate error handling for undefined selectors
• Alignment: Verify 24-bit alignment is maintained for all primitives
• Round-trip conversion: Verify text → binary → text preserves selectors
• Concatenation: Verify multiple primitives can be concatenated and parsed correctly
• Version compatibility: Verify correct behavior across different CESR versions

Security Considerations

The selector is part of the security-critical parsing path:

• Bounds checking: Always verify that reading the selector and subsequent characters does not exceed stream bounds
• Integer overflow: Verify that primitive length calculations do not overflow
• Resource exhaustion: Limit the number of primitives parsed from a single stream to prevent DoS attacks
• Validation before use: Always validate the selector before using it to index into code tables or extract primitives