API.md

# libgsml3parser - Full API Reference

> Version 0.18.0 | C++20 | Zero heap allocation on hot path | No external dependencies

## Table of Contents

1. [Getting Started](#1-getting-started)
2. [Core Types](#2-core-types)
3. [Bit-Level I/O](#3-bit-level-io)
4. [Parser Configuration](#4-parser-configuration)
5. [L3 Header Parsing](#5-l3-header-parsing)
6. [Message Variants](#6-message-variants)
7. [Parser and Serializer API](#7-parser-and-serializer-api)
8. [Visitor Helpers](#8-visitor-helpers)
9. [Bitstream I/O](#9-bitstream-io)
10. [Arena Allocator](#10-arena-allocator)
11. [Procedure Types](#11-procedure-types)
12. [Response Builder](#12-response-builder)
13. [LAPDm Protocol](#13-lapdm-protocol)
14. [Protocol Dispatcher](#14-protocol-dispatcher)
15. [Builder Pattern](#15-builder-pattern)
16. [Enum Formatters](#16-enum-formatters)
17. [Data Types](#17-data-types)
18. [Enumerations](#18-enumerations)
19. [Protocol Types](#19-protocol-types)
20. [Common Information Elements](#20-common-information-elements)
21. [Radio Resource Messages](#21-radio-resource-messages)
22. [Mobility Management Messages](#22-mobility-management-messages)
23. [Call Control Messages](#23-call-control-messages)
24. [Supplementary Services Messages](#24-supplementary-services-messages)
25. [GPRS Mobility Management Messages](#25-gprs-mobility-management-messages)
26. [GPRS Session Management Messages](#26-gprs-session-management-messages)
27. [SMS Messages](#27-sms-messages)
28. [Broadcast Call Control Messages](#28-broadcast-call-control-messages)
29. [Group Call Control Messages](#29-group-call-control-messages)
30. [Location Services Messages](#30-location-services-messages)
31. [Packet Domain Supplementary Services (PDSS) Messages](#31-packet-domain-supplementary-services-pdss-messages)
32. [Test Procedure PD Messages](#32-test-procedure-pd-messages)
33. [MSContext - Per-Subscriber State](#33-mscontext-per-subscriber-state)
34. [Timer Framework](#34-timer-framework)
35. [Transaction Framework](#35-transaction-framework)
36. [Protocol State Machines](#36-protocol-state-machines)
37. [Channel Pool - Logical Channel Management](#37-channel-pool-logical-channel-management)
38. [FlatHandler - Zero-Overhead Callbacks](#38-flathandler-zero-overhead-callbacks)
39. [ShardedChannelPool - Thread-Safe Channel Pool](#39-shardedchannelpool-thread-safe-channel-pool)
40. [InlineFramer - Zero-Copy Frame Extraction](#40-inlineframer-zero-copy-frame-extraction)
41. [ZeroCopyStreamProcessor - Zero-Copy Stream Parsing](#41-zerocopystreamparser-zero-copy-stream-parsing)
42. [Subscriber Registry - Subscriber Session Management](#42-subscriber-registry-subscriber-session-management)
43. [RSL Types - A-bis RSL Type Definitions](#43-rsl-types-abis-rsl-type-definitions)
44. [RSL Parser - A-bis RSL Message Parsing](#44-rsl-parser-abis-rsl-message-parsing)
45. [RSL Builder - A-bis RSL Message Construction](#45-rsl-builder-abis-rsl-message-construction)
46. [Procedure Framework - Protocol Procedure Base Class](#46-procedure-framework-protocol-procedure-base-class)
47. [Procedure Runner - Concurrent Procedure Manager](#47-procedure-runner-concurrent-procedure-manager)
48. [Typed External Data - Strongly-Typed External Data Structures](#48-typed-external-data-strongly-typed-external-data-structures)
49. [ProcedureStateMixin - CRTP Mixin for Common Procedure Code](#49-procedurestatemixin-crtp-mixin-for-common-procedure-code)
50. [Procedure Orchestrator - Chained Protocol Procedures](#50-procedure-orchestrator-chained-protocol-procedures)
51. [Location Update Procedure](#51-location-update-procedure)
52. [Authentication Procedure](#52-authentication-procedure)
53. [Call Setup MO Procedure](#53-call-setup-mo-procedure)
54. [Call Setup MT Procedure](#54-call-setup-mt-procedure)
55. [Channel Assignment Procedure](#55-channel-assignment-procedure)
56. [Ciphering Mode Procedure](#56-ciphering-mode-procedure)
57. [Paging Procedure](#57-paging-procedure)
58. [Handover Procedure](#58-handover-procedure)
59. [Call Release Procedure](#59-call-release-procedure)
60. [IMSI Detach Procedure](#60-imsi-detach-procedure)
61. [Performance Optimizations Summary](#61-performance-optimizations-summary)
62. [C API (gsml3parser_c.h)](#62-c-api-gsml3parser_ch)
63. [FFI Bindings (Python / Go / Rust)](#63-ffi-bindings-python--go--rust)

---

## 1. Getting Started

### Build Requirements

| Requirement | Minimum Version |
|-------------|-----------------|
| C++ Compiler | MSVC 2022 (17.x), GCC 13+, or Clang with a C++20 `std::format`-capable standard library |
| CMake | 3.20+ |
| Standard Library | C++20 (`std::variant`, `std::span`, concepts, `std::format`) |

### Build

```bash
mkdir build && cd build
cmake .. -DBUILD_TESTS=ON -DBUILD_EXAMPLES=ON
cmake --build . --config Release --parallel
```

CMake options:

| Option | Default | Description |
|--------|---------|-------------|
| `BUILD_SHARED_LIBS` | OFF | Build shared library instead of static |
| `BUILD_TESTS` | OFF | Build unit tests (Google Test 1.14+) |
| `BUILD_EXAMPLES` | OFF | Build example programs |
| `ENABLE_FUZZING` | OFF | Build libFuzzer targets in `fuzz/` (requires Clang/LLVM; no-op with a status message on MSVC) |
| `ENABLE_ASAN` | OFF | AddressSanitizer for Debug builds (MSVC 17.8+) |

### CMake Integration

```cmake
find_package(gsml3parser REQUIRED)
target_link_libraries(myapp PRIVATE gsml3parser::parser)
```

Or as a subdirectory:

```cmake
add_subdirectory(libgsml3parser)
target_link_libraries(myapp PRIVATE gsml3parser::parser)
```

### Umbrella Header

Include everything with a single header:

```cpp
#include <gsml3parser/gsml3parser.hpp>
```

### Stack Modules for BTS Development

The stack-module headers under `gsml3parser/stack/` provide high-level primitives for building a software Base Transceiver Station (BTS) on top of the L3 parser:

| Module | Header | Purpose |
|--------|--------|---------|
| **MSContext** | `stack/ms_context.h` | Per-subscriber state: identity, channel, flags (≤ 256 bytes, zero allocations) |
| **Timer Framework** | `stack/l3_timer.h` | Protocol timers with built-in default durations for the 19 named GSM/GPRS timers (other IDs accept a custom duration); TimerManager with callback/span-based tick (zero heap) |
| **Transaction Framework** | `stack/transaction.h` | Request-response correlation: O(1) TI lookup for CC/SS, PD+MTI scan for others |
| **Protocol State Machines** | `stack/state_machine.h` | RR/MM/CC FSM skeletons with switch-based O(1) dispatch |
| **Channel Pool** | `stack/channel_pool.h` | Logical channel allocation/release, RA decoding, VEA support |

All stack modules follow the same design principles: zero heap allocations on hot paths, fixed-size internal storage, and one-instance-per-MS thread model. See [`doc/bts_architecture.md`](bts_architecture.md) for the complete architecture guide and scaling recommendations.

```cpp
// Minimal BTS setup using stack modules:
#include <gsml3parser/gsml3parser.hpp>

using namespace gsml3parser;

auto ctx     = MSContext::createWithTMSI(0x12345678u);
TimerManager timers;
TransactionManager transactions;
RRStateMachine rrFsm;
ChannelPool channels;

// Register channels, start timers, process messages...
channels.addChannel({ChannelType::SDCCHType, 0, 0, 100});
timers.start(L3TimerId::T3101);
rrFsm.setState(RRStateMachine::State::IDLE);
```

---

## 2. Core Types

### ParseError

**File:** `gsml3parser/expected.h`

Structured error type with zero heap allocation for short messages (SSO up to 47 characters).

```cpp
struct ParseError {
    enum class Code : uint8_t {
        Ok, TruncatedInput, InvalidPD, InvalidMTI,
        LengthMismatch, InvalidIE, InvalidValue, UnsupportedFeature,
        SourceExhausted
    };
    static constexpr std::size_t InlineCapacity = 47;
    Code code{Code::Ok};
    size_t bitPosition{};
    std::string_view message{};   // SSO-backed inline storage for messages up to 47 chars
    [[nodiscard]] constexpr bool failed() const noexcept;
};
```

| Member | Description |
|--------|-------------|
| `code` | Error classification enum (`Ok` through `SourceExhausted`) |
| `bitPosition` | Bit offset in input where the error occurred |
| `message` | Human-readable error description, stored inline (zero heap allocation for messages up to 47 characters) |
| `failed()` | Returns `true` if `code != Ok` |

`SourceExhausted` is returned by stream framing when the byte source reached EOF without a complete frame.

### Expected<T>

**File:** `gsml3parser/expected.h`

Result type that holds either a success value of type `T` or a `ParseError`. Wraps `std::variant<T, ParseError>`.

```cpp
template<typename T>
class Expected {
public:
    [[nodiscard]] static Expected hold(T value);
    [[nodiscard]] static Expected error(ParseError e);
    [[nodiscard]] constexpr bool has_value() const;
    [[nodiscard]] T& value() &;
    [[nodiscard]] const T& value() const&;
    [[nodiscard]] T&& value() &&;
    [[nodiscard]] const ParseError& error() const;
    [[nodiscard]] explicit operator bool() const;
    [[nodiscard]] T& operator*();
    [[nodiscard]] const T& operator*() const;

    template<typename F> [[nodiscard]] auto map(F&&) && -> Expected<...>;
    template<typename F> [[nodiscard]] auto and_then(F&&) && -> ...;
};
```

| Method | Description |
|--------|-------------|
| `hold(value)` | Create from success value |
| `error(err)` | Create from error |
| `has_value()` | Check for success |
| `value()` | Get the success value (throws on error) |
| `error()` | Get the error (throws on success) |
| `operator bool()` | Implicit conversion: `true` = has value |
| `operator*()` | Dereference to get value |
| `map(f)` | Transform success value, propagate error |
| `and_then(f)` | Chain Expected-producing calls |

**Expected<void>** specialization for operations that only succeed or fail:

```cpp
template<>
class Expected<void> {
public:
    [[nodiscard]] static Expected hold();
    [[nodiscard]] static Expected error(ParseError e);
    [[nodiscard]] constexpr bool has_value() const;
    [[nodiscard]] explicit operator bool() const;
    // map and and_then also available
};
```

**Usage example:**

```cpp
auto msg = parseL3Hex("060D00");

if (msg) {
    std::cout << messageName(*msg) << "\n";
} else {
    std::cerr << msg.error().message << "\n";
}

// Composition with map
auto name = msg.map([](const ParsedMessage& m) {
    return messageName(m);
});

// Chaining with and_then
auto roundTripped = msg.and_then(writeL3Hex)
    .and_then(parseL3Hex);
```

---

## 3. Bit-Level I/O

### BitReader

**File:** `gsml3parser/bitreader.h`

Bounds-checked, MSB-first bit reader over a byte buffer. No heap allocation.

```cpp
class BitReader {
public:
    constexpr BitReader(const uint8_t* buf, size_t nbits);
    [[nodiscard]] Expected<uint32_t> readField(unsigned nbits) &;
    [[nodiscard]] uint32_t peekField(unsigned nbits) const &;
    [[nodiscard]] bool hasMore() const noexcept;
    [[nodiscard]] size_t remainingBits() const noexcept;
    [[nodiscard]] size_t position() const noexcept;
    void alignToOctet();
    [[nodiscard]] Expected<void> readBytes(uint8_t* out, size_t count) &;
};
```

| Method | Description |
|--------|-------------|
| `readField(nbits)` | Read `nbits` bits, advance position. Returns error if past end. |
| `peekField(nbits)` | Read without advancing. `nbits` is clamped to 32 (return type is `uint32_t`), so requesting more than 32 bits is safe (no undefined behavior). Returns 0 when no bits are available (empty/null buffer) or for out-of-bounds bits. |
| `hasMore()` | True if more bits available |
| `remainingBits()` | Number of unread bits remaining |
| `position()` | Current bit position |
| `alignToOctet()` | Round up to next byte boundary |
| `readBytes(out, count)` | Read whole bytes into buffer. Optimized for aligned reads. |

**Bit ordering:** MSB-first within each octet (bit 7 is read first).

> **Safety notes:** `peekField(nbits)` clamps `nbits` to 32 (its return type is
> `uint32_t`), so requesting more than 32 bits is safe and never triggers undefined
> behavior. When no bits are available (empty or null buffer), `peekField` returns 0
> instead of performing a negative shift. `readField(nbits)` rejects `nbits > 32` with an
> error and reads at most the bits that remain.

### BitWriter

**File:** `gsml3parser/bitwriter.h`

MSB-first bit writer over a byte buffer. No heap allocation.

```cpp
class BitWriter {
public:
    constexpr BitWriter(uint8_t* buf, size_t nbits);
    void writeField(uint32_t value, unsigned nbits);
    void writeOctet(uint8_t v);
    void writeBytes(const uint8_t* data, size_t count);
    void alignToOctet();
    [[nodiscard]] size_t position() const noexcept;
};
```

| Method | Description |
|--------|-------------|
| `writeField(value, nbits)` | Write top `nbits` of `value`, MSB-first |
| `writeOctet(v)` | Write a single byte |
| `writeBytes(data, count)` | Write a sequence of bytes |
| `alignToOctet()` | Pad with zeros to next byte boundary |
| `position()` | Current bit position written |

**Usage example:**

```cpp
uint8_t buf[64] = {};
BitWriter writer(buf, sizeof(buf) * 8);

writer.writeField(0x06, 4);  // PD
writer.writeField(0x0D, 8);  // MTI
// ... write message body ...
size_t bitsWritten = writer.position();
```

---

## 4. Parser Configuration

### ParserConfig

**File:** `gsml3parser/parser_config.h`

Immutable, thread-safe parser configuration. No mutex, no atomic operations. Pure data struct.

```cpp
struct ParserConfig {
    LogLevel logLevel{LogLevel::WARNING};
    bool requireFullConsumption{false};

    [[nodiscard]] LogLevel getLogLevel() const noexcept;
    [[nodiscard]] ParserConfig withLogLevel(LogLevel lvl) const noexcept;
    [[nodiscard]] ParserConfig withStrictFraming(bool v) const noexcept;
};
```

| Member / method | Description |
|--------|-------------|
| `logLevel` | Log level (default `WARNING`) |
| `requireFullConsumption` | When true, `parseL3()` returns `LengthMismatch` if the message does not consume the entire input; default is lenient (trailing bytes ignored) |
| `getLogLevel()` | Current log level |
| `withLogLevel(lvl)` | Return new config with changed log level |
| `withStrictFraming(v)` | Return new config with strict framing on/off |

The struct is reserved for future parser options (log level and similar). It intentionally carries no per-PD handler table: all 13 protocol domains are parsed by the built-in domain parsers in `parseL3()`.

**Thread safety:** Safe for concurrent read access from any number of threads. Builder methods return new instances - the original is never modified.

**Usage example:**

```cpp
ParserConfig cfg;
cfg = cfg.withLogLevel(LogLevel::ERR);

// Parse with config - no mutex acquired
auto result = parseL3Hex("060D", cfg);
```

---

## 5. L3 Header Parsing

### L3Header

**File:** `gsml3parser/l3header.h`

Decoded L3 protocol header fields.

```cpp
struct L3Header {
    L3PD pd;       // Protocol Discriminator
    int mti{};     // Message Type Indicator
    unsigned ti{}; // Transaction Identifier (CC/SS)
    bool tif{};    // TI Flag (short RR messages)
    [[nodiscard]] bool isValid() const;
};
```

### parseL3Header()

Parse a 2-byte L3 header from raw data.

```cpp
Expected<L3Header> parseL3Header(std::span<const uint8_t> data);
```

Returns `TruncatedInput` error if fewer than 2 bytes provided. Returns `InvalidPD` for reserved PD values (0x02, 0x04, 0x07, 0x0D).

**Decoding rules** (TS 24.007 Table 11.3 / TS 44.018 L3 protocol header):
- Byte 0: `(TI << 5) | (TIF << 4) | PD` — the PD occupies the LOW nibble (bits 3-0), TI is bits 7-5, TIF is bit 4. TI is meaningful for the dialog domains CC/SS/BCC/GCC.
- Byte 1: raw MTI octet
- MM / CC / SS / BCC / GCC: `mti = raw & 0x3F` (6-bit messageType in the low bits; the two high NSD bits are informational and not exposed)
- GMM / SMS / SM / LS / EXTENDED / TESTPROC: `mti = raw` (full 8-bit messageType)
- RR: `mti = raw`; with TIF=1 (short messages) the five-bit code sits in the low bits of octet 1, the high three bits are reserved and masked away: `mti = kRRTifShortBase | (raw & 0x1F)`

---

## 6. Message Variants

### Domain Variants

**File:** `gsml3parser/message_types.h`

Each protocol domain has a `std::variant` type that holds all message types for that domain:

```cpp
using RRM      = std::variant< /* 98 RR types */ >;
using MMM      = std::variant< /* 21 MM types */ >;
using CCM      = std::variant< /* 21 CC types */ >;
using SSM      = std::variant< /* 3 SS types */ >;
using GMM      = std::variant< /* 23 GMM types */ >;
using SM       = std::variant< /* 24 SM types */ >;
using SMS      = std::variant< /* 5 SMS CP types */ >;
using BCCM     = std::variant< /* 8 BCC types */ >;
using GCCM     = std::variant< /* 8 GCC types */ >;
using LSM      = std::variant< /* 2 LS types */ >;
using PDSS1M   = std::variant<L3PDSS1Message>;
using EXTENDED = std::variant<L3ExtendedMessage>;
using TESTPROC = std::variant<L3TestProcedureMessage>;
```

### ParsedMessage

The top-level variant that wraps all domains:

```cpp
using ParsedMessage = std::variant<RRM, MMM, CCM, SSM, GMM, SM, SMS, BCCM, GCCM, LSM, PDSS1M, EXTENDED, TESTPROC>;
```

Stored on the stack - no heap allocation. `sizeof(ParsedMessage) = 400` bytes on 64-bit (bounded `< 8192` via `static_assert`). The variant spans 13 protocol domains.

**Usage:**

```cpp
auto msg = parseL3Hex("060D00");
if (msg) {
    const ParsedMessage& parsed = *msg;

    // Visit all alternatives
    std::visit([](const auto& domain) {
        std::visit([](const auto& concrete) {
            using T = std::decay_t<decltype(concrete)>;
            // Process concrete message type T
        }, domain);
    }, parsed);
}
```

---

## 7. Parser and Serializer API

**File:** `gsml3parser/parser.h`

### parseL3()

Parse a complete L3 message from raw bytes.

```cpp
Expected<ParsedMessage> parseL3(std::span<const uint8_t> data, const ParserConfig& cfg = {});
```

| Parameter | Description |
|-----------|-------------|
| `data` | Raw L3 message bytes (header + body) |
| `cfg` | Parser configuration (optional, defaults to empty) |

Returns `Expected<ParsedMessage>` - the parsed variant on success, or `ParseError` on failure.

Handles short messages automatically: 1-byte Channel Request and 4-byte Handover Access.

### parseL3Hex()

Parse a complete L3 message from a hex-encoded string.

```cpp
Expected<ParsedMessage> parseL3Hex(std::string_view hex, const ParserConfig& cfg = {});
```

Whitespace in the hex string is ignored.

### writeL3()

Serialize a ParsedMessage to raw bytes.

```cpp
Expected<size_t> writeL3(const ParsedMessage& msg, uint8_t* out, size_t maxlen);
```

Returns number of bytes written on success. Returns `InvalidValue` error if buffer too small.

### writeL3Hex()

Serialize a ParsedMessage to a hex-encoded string.

```cpp
Expected<std::string> writeL3Hex(const ParsedMessage& msg);
```

Uses inline encoding with lookup table - no `std::ostringstream` or `std::iomanip`.

### writeL3Bytes()

Serialize a ParsedMessage to a `std::vector<uint8_t>` of raw bytes (header + body). Returns bytes ready for `LAPDmEntity.sendUI()`/`sendData()` and over-the-air transmission.

```cpp
Expected<std::vector<uint8_t>> writeL3Bytes(const ParsedMessage& msg);
```

| Return | Description |
|--------|-------------|
| `std::vector<uint8_t>` | Raw L3 bytes, ready for LAPDmEntity.sendUI()/sendData() or direct transmission |

**Usage:**

```cpp
auto msg = parseL3Hex("060D00");
if (msg) {
    auto bytes = writeL3Bytes(*msg);
    if (bytes) {
        // bytes->data() is ready for LAPDmEntity.sendUI()/sendData()
    }
}
```

### Round-trip Pattern

```cpp
auto original = parseL3Hex("060D00");   // RR Channel Release, cause 0
if (original) {
    auto hex = writeL3Hex(*original);
    if (hex) {
        auto reparsed = parseL3Hex(*hex);
        // reparsed should hold the same message type with the same fields
    }
}
```

---

## 8. Visitor Helpers

**File:** `gsml3parser/visitor.h`

### tryGet<T>()

Compile-time typed access - no `dynamic_cast` needed.

```cpp
template<typename T> const T* tryGet(const ParsedMessage& msg);
template<typename T> T* tryGet(ParsedMessage& msg);
```

Returns pointer to the concrete type if the variant holds it, or `nullptr` otherwise. If `T` is not in the correct domain variant, `if constexpr` prevents instantiation of invalid `std::get_if`.

**Usage:**

```cpp
auto msg = parseL3Hex("060D00");
if (msg) {
    if (auto* cr = tryGet<L3ChannelRelease>(*msg)) {
        std::cout << "Cause: " << static_cast<int>(cr->cause()) << "\n";
    }
}
```

### messageName()

Returns a human-readable name for the message type.

```cpp
std::string_view messageName(const ParsedMessage& msg);
```

### messagePD()

Returns the Protocol Discriminator of the message.

```cpp
L3PD messagePD(const ParsedMessage& msg);
```

### messageMTI()

Returns the Message Type Indicator value (for RR short messages this is ≥ 0x100, matching `L3Header::mti`).

```cpp
int messageMTI(const ParsedMessage& msg);
```

### messageTI()

Returns the Transaction Identifier for CC/SS dialog messages. Returns 0 for non-dialog message types where TI does not apply.

```cpp
uint8_t messageTI(const ParsedMessage& msg);
```

---

## 9. Bitstream I/O

### ByteSource

**File:** `gsml3parser/bitstream/byte_source.h`

Abstract interface for byte sources.

```cpp
class ByteSource {
public:
    virtual ~ByteSource() = default;
    [[nodiscard]] virtual size_t read(uint8_t* buf, size_t maxSize) = 0;
    [[nodiscard]] virtual bool atEof() const { return false; }
};
```

`read()` returns bytes actually read (0 = no data right now). `atEof()` is true only when the source is exhausted and will never produce more bytes. Sources may block.

### SpanByteSource

Reads from a contiguous memory span. Non-blocking.

```cpp
class SpanByteSource : public ByteSource {
public:
    explicit SpanByteSource(std::span<const uint8_t> data);
    [[nodiscard]] size_t read(uint8_t* buf, size_t maxSize) override;
    [[nodiscard]] size_t remaining() const noexcept;
};
```

### FileByteSource

Reads from a C `FILE*`. Takes ownership and closes on destruction.

```cpp
class FileByteSource : public ByteSource {
public:
    explicit FileByteSource(FILE* f);
    ~FileByteSource();
    // Non-copyable, non-movable
    [[nodiscard]] size_t read(uint8_t* buf, size_t maxSize) override;
};
```

### RingBuffer

Lock-free-ish ring buffer for producer/consumer streaming.

```cpp
class RingBuffer : public ByteSource {
public:
    explicit RingBuffer(size_t capacity = 262144);
    size_t write(const uint8_t* data, size_t len);
    [[nodiscard]] size_t available() const noexcept;
    [[nodiscard]] size_t freeSpace() const noexcept;
    [[nodiscard]] size_t read(uint8_t* buf, size_t maxSize) override;
};
```

| Method | Description |
|--------|-------------|
| `write(data, len)` | Non-blocking write. Returns bytes accepted. Returns 0 if full. |
| `available()` | Bytes available for reading |
| `freeSpace()` | Free slots in the buffer |
| `read(buf, maxSize)` | Read up to `maxSize` bytes |

**Thread safety:** Single-producer, single-consumer is fully safe without locks. Uses `std::atomic` with acquire/release ordering for correct behaviour on weakly-ordered architectures (ARM, PowerPC). On x86-64 (TSO) the compiler emits plain loads/stores - zero overhead. Multi-producer or multi-consumer requires external synchronization.

### L3Framer

**File:** `gsml3parser/bitstream/framer.h`

Extracts L3 frames from a raw byte stream.

```cpp
struct FrameConfig {
    bool useL2Length{true};        // Use L2 length octet for framing (default)
    size_t maxMessageLength{4096}; // Safety limit
    size_t minHeaderLength{2};     // Minimum bytes for L3 header
};

class L3Framer {
public:
    explicit L3Framer(ByteSource& source, FrameConfig cfg = {});
    [[nodiscard]] Expected<ExtractedFrame> nextFrame();
    void skip(size_t nbytes);
    [[nodiscard]] size_t buffered() const noexcept;
};
```

| Method | Description |
|--------|-------------|
| `nextFrame()` | Extract next frame. Returns `TruncatedInput` when more data needed. |
| `skip(nbytes)` | Skip N bytes for error recovery |
| `buffered()` | Bytes buffered but not yet consumed |

**Framing modes:**

- **L2 length mode** (`useL2Length = true`, default): each frame is preceded by a single length octet. Deterministic; what production LAPDm / A-bis paths provide.
- **Header-based mode** (`useL2Length = false`, opt-in): the frame length is derived from PD + MTI for all 13 protocol domains (the PD is the low nibble of octet 0; MM/CC/NC-SS/GCC/BCC take the six low bits of octet 1 as the MTI, RR short messages with TIF set map to `kRRTifShortBase | code`, GMM/SMS/SM/LS and the PDSS1/PDSS2/test PDs use the raw 8-bit MTI). Fixed-body messages are framed exactly from a single compile-time table (`bitstream/frame_lengths.h`, cross-checked by `tests/test_frame_lengths.cpp`): RR RRStatus, ClassmarkEnquiry, HandoverFailure, AssignmentComplete, HandoverComplete, AssignmentFailure; MM CMServiceAccept, CMServiceReject, CMServiceAbort, MMAbort, MMStatus; CC CCStatus, CCNotify; BCC CallConfirmed, ConnectAcknowledge; GCC CallConfirmed. Every other message (SI, SMS, Setup with IEs, ...) is framed by a boundary heuristic: scan forward for the next plausible L3 header within `maxMessageLength` bytes (O(L), resume-cached across fills); a boundary candidate must carry one of the thirteen TS-valid protocol discriminators in the low nibble of octet 0 (GCC 0x00, BCC 0x01, CC 0x03, MM 0x05, RR 0x06, GMM 0x08, SMS 0x09, SM 0x0A, NC-SS 0x0B, LCS 0x0C, PDSS1 0x0D, PDSS2 0x0E, TestProcedure 0x0F) to avoid false boundaries inside variable bodies. The heuristic is UNRELIABLE on real variable-length streams — message bodies frequently contain bytes whose low nibble is a valid PD — use L2 length mode for deterministic framing. At source EOF the tail is emitted as the final frame and validated by the parser.

### L3StreamProcessor

**File:** `gsml3parser/bitstream/stream_processor.h`

High-throughput streaming parser with statistics tracking.

```cpp
class L3StreamProcessor {
public:
    L3StreamProcessor(ByteSource& source, ParserConfig cfg = {}, FrameConfig fcfg = {});
    // Owning variant: takes ownership of the source (kept alive until the processor is destroyed).
    L3StreamProcessor(std::unique_ptr<ByteSource> source, ParserConfig cfg = {}, FrameConfig fcfg = {});
    template<typename F>
        requires std::is_invocable_v<F, const ParsedMessage&>
    bool processOne(F&& handler);
    void processUntilEOF(FrameHandler& handler);
    void processN(size_t count, FrameHandler& handler);
    [[nodiscard]] const StreamStats& stats() const;
    void resetStats();
};
```

| Method | Description |
|--------|-------------|
| `processOne(handler)` | Non-blocking: process one frame if available. Returns true if processed. |
| `processUntilEOF(handler)` | Blocking: process all frames until source exhausted |
| `processN(count, handler)` | Process exactly N frames (or until EOF) |
| `stats()` | Running statistics |
| `resetStats()` | Reset all counters |

### FrameHandler

Callback interface for processed frames.

```cpp
class FrameHandler {
public:
    virtual ~FrameHandler() = default;
    virtual void onFrame(const ParsedMessage& msg, const ExtractedFrame& raw) = 0;
    virtual void onError(const ParseError& err, std::span<const uint8_t> rawData) {}
    virtual void onStats(const StreamStats& stats) {}
};
```

### StreamStats

Running statistics for stream processing.

```cpp
struct StreamStats {
    uint64_t totalBytes{}, totalFrames{}, parsedOk{}, parseErrors{};
    uint64_t idlePolls{}, sourceExhausted{}, unsupportedPD{};
    uint64_t rrMessages{}, mmMessages{}, ccMessages{}, ssMessages{};
    uint64_t gmmMessages{}, smMessages{}, smsMessages{};
    uint64_t bccMessages{}, gccMessages{}, lsMessages{};
    uint64_t extendedMessages{}, testprocMessages{};
};
```

### L3StreamBuilder

Fluent builder for `L3StreamProcessor`.

```cpp
class L3StreamBuilder {
public:
    L3StreamBuilder& source(ByteSource& src);
    L3StreamBuilder& source(std::span<const uint8_t> data);
    L3StreamBuilder& sourceFile(const char* path);
    L3StreamBuilder& logLevel(LogLevel lvl);
    L3StreamBuilder& useL2Length(bool v);
    L3StreamBuilder& maxMessageLength(size_t v);
    L3StreamBuilder& ringBufferSize(size_t v);
    [[nodiscard]] std::unique_ptr<L3StreamProcessor> build();
    [[nodiscard]] bool hasFileError() const noexcept;
};
```

**Usage:**

```cpp
auto processor = L3StreamBuilder()
    .sourceFile("capture.bin")
    .useL2Length(true)
    .logLevel(LogLevel::WARNING)
    .build();

MyHandler handler;
processor->processUntilEOF(handler);
```

---

## 10. Arena Allocator

**File:** `gsml3parser/arena.h`

Simple bump allocator for high-throughput batch parsing.

```cpp
class Arena {
public:
    explicit Arena(size_t initialCapacity = 4096);
    void* allocate(size_t bytes, size_t alignment = alignof(std::max_align_t));
    void reset();
    [[nodiscard]] size_t remaining() const;
    [[nodiscard]] size_t used() const;
    [[nodiscard]] size_t capacity() const;
};
```

| Method | Description |
|--------|-------------|
| `allocate(bytes, alignment)` | Bump-allocate with specified alignment. Returns `nullptr` on failure. |
| `reset()` | Reclaim all memory; every pointer obtained from this arena becomes invalid. |
| `remaining()` | Remaining capacity without allocation. Use to decide when to reset. |
| `used()` | Bytes consumed since last reset |
| `capacity()` | Total buffer size |

**Thread safety:** NOT thread-safe. Each thread must use its own Arena instance.

---

## 11. Procedure Types

**File:** `gsml3parser/stack/procedure_types.h`
**Namespace:** `gsml3parser::procedure`
**Spec:** 3GPP TS 24.008 (MM/CC procedures), TS 04.08 (RR procedures)

Foundation types for the Procedure Framework. Defines procedure type identifiers, lifecycle states, and result structures used by `ProcedureRunner` to manage protocol-level message exchanges.

### ProcedureType

Protocol procedure types mapped to 3GPP specification chapters:

| Value | Name | Spec Reference | Description |
|-------|------|----------------|-------------|
| `0x01` | `LocationUpdate` | TS 24.008 4.4.1 | Normal/IMSI-attached location updating |
| `0x02` | `Authentication` | TS 24.008 4.4.2 | Authentication and ciphering key setup |
| `0x03` | `CipheringMode` | TS 24.008 4.4.3 / TS 04.08 9.1.37 | Ciphering activation |
| `0x04` | `CallSetup_MO` | TS 24.008 6.1 | Mobile Originated Call setup |
| `0x05` | `CallSetup_MT` | TS 24.008 6.1 | Mobile Terminated Call setup |
| `0x06` | `ChannelAssignment` | TS 04.08 9.1.2 / 9.1.35 | Channel assignment procedure |
| `0x07` | `Handover` | TS 04.08 9.1.40 | Handover command and completion |
| `0x08` | `Paging` | TS 04.08 9.1.25 | Network-initiated paging of MS |
| `0x09` | `CMServiceRequest` | TS 24.008 4.7 | CM service request procedure |
| `0x0A` | `IMSIDetach` | TS 24.008 4.4.6 | IMSI detach procedure |
| `0x0B` | `CallRelease` | TS 24.008 6.1 | Call release (disconnect -> release complete) |
| `0x0C` | `PeriodicLocationUpdate` | TS 24.008 4.4.1 | Periodic location updating |
| `0xFF` | `Unknown` | — | Unrecognized or unsupported procedure |

### ProcedureState

Lifecycle states for a managed procedure instance:

| State | Description |
|-------|-------------|
| `Initiated` | Procedure started; awaiting first protocol message |
| `InProgress` | Active message exchange in progress |
| `WaitingExternal` | Blocked on external data (RAND from AuC, BSC decision, etc.) |
| `Completed` | Procedure finished successfully |
| `Failed` | Procedure terminated with an error condition |
| `TimedOut` | Procedure exceeded its allowed duration without completion |

### ProcedureResult

Terminal result structure for completed or failed procedures:

```cpp
struct ProcedureResult {
    ProcedureType type{ProcedureType::Unknown};
    ProcedureState state{ProcedureState::Initiated};
    std::string_view reason{};  // "ok", "timeout", "reject", etc.
};

static_assert(sizeof(ProcedureResult) <= 64);
```

### Helper Functions

| Function | Description |
|----------|-------------|
| `procedureTypeName(ProcedureType)` | Human-readable name for logging (returns "?" for Unknown) |
| `procedureStateName(ProcedureState)` | Human-readable state name for logging |

**Thread safety:** All types are trivially copyable and safe for concurrent read.
**Memory:** `sizeof(ProcedureResult) <= 64` bytes (cache-friendly).

---

## 12. Response Builder

**File:** `gsml3parser/stack/response_builder.h`
**Namespace:** `gsml3parser`
**Spec:** 3GPP TS 04.08 (message formats), TS 24.008 (procedure context)

Factory for building L3 response messages. Used after the FSM returns a `SendResponse` action to generate the corresponding protocol message. Each method provides two overloads: a vector-returning version for convenience and a span-writing version for zero-heap-allocation high-throughput paths.

### Design Pattern

```
FSM.processMessage(msg) -> SMResult{action: SendResponse, nextState: X}
  |
  v
ResponseBuilder::build<Method>(params) -> bytes
  |
  v
sendToMS(bytes)
```

### RR Responses

| Method | Response Message | Spec |
|--------|-----------------|------|
| `buildImmediateAssignment(channel, ta, requestRef?)` | ImmediateAssignment | TS 04.08 9.1.19 |
| `buildAssignmentCommand(channel, mode?)` | AssignmentCommand | TS 04.08 9.1.2 |
| `buildChannelRelease(cause?)` | ChannelRelease | TS 04.08 9.1.7 |
| `buildCipheringModeCommand(algo)` | CipheringModeCommand | TS 04.08 9.1.9 |
| `buildPhysicalInformation(ta)` | PhysicalInformation | TS 04.08 9.1.12 |

### MM Responses

| Method | Response Message | Spec |
|--------|-----------------|------|
| `buildCMServiceAccept()` | CM Service Accept | TS 04.08 9.2.5 |
| `buildCMServiceReject(cause?)` | CM Service Reject | TS 04.08 9.2.6 |
| `buildIdentityRequest(type)` | IdentityRequest | TS 04.08 9.2.10 |
| `buildAuthenticationRequest(rand)` | AuthenticationRequest | TS 04.08 9.2.2 |
| `buildLocationUpdatingAccept(lai, newTmsi?)` | LocationUpdatingAccept | TS 04.08 9.2.13 |
| `buildLocationUpdatingReject(cause)` | LocationUpdatingReject | TS 04.08 9.2.14 |
| `buildTMSIReallocationCommand(lai, tmsi)` | TMSIReallocationCommand | TS 04.08 9.2.17 |

### CC Responses

| Method | Response Message | Spec |
|--------|-----------------|------|
| `buildCallProceeding(ti)` | CallProceeding | TS 04.08 9.3.3 |
| `buildAlerting(ti)` | Alerting | TS 04.08 9.3.1 |
| `buildConnect(ti)` | Connect | TS 04.08 9.3.5 |
| `buildConnectAcknowledge(ti)` | ConnectAcknowledge | TS 04.08 9.3.6 |
| `buildDisconnect(ti, cause)` | Disconnect | TS 04.08 9.3.7 |
| `buildRelease(ti, cause)` | Release | TS 04.08 9.3.19 |
| `buildReleaseComplete(ti)` | ReleaseComplete | TS 04.08 9.3.19 |

### RR Paging & Handover Responses

| Method | Response Message | Spec |
|--------|-----------------|------|
| `buildPagingRequestType1(identity)` | PagingRequestType1 | TS 04.08 9.1.25 |
| `buildPagingRequestType2(identity)` | PagingRequestType2 | TS 04.08 9.1.25 |
| `buildPagingRequestType3(identity)` | PagingRequestType3 | TS 04.08 9.1.25 |
| `buildHandoverCommand(channel)` | HandoverCommand | TS 04.08 9.1.40 |

### CC Setup Response

| Method | Response Message | Spec |
|--------|-----------------|------|
| `buildSetup(calledNumber, ti)` | Setup | TS 24.008 9.3.2 |

### Token-Based Response Building

| Method | Description |
|--------|-------------|
| `buildResponseFromToken(token, out, session)` | Build response bytes from `ResponseToken` + session context into pre-allocated buffer (zero heap allocation). Dispatches to the appropriate `buildXxx()` method based on token value. Returns byte count or -1 on error. `session` is required: every response parameter is read from the session's `ResponseContext` (see below). The method returns -1 when a required parameter is missing instead of fabricating a value. |
| `buildSetupZeroAlloc(out, digits, len, ti)` | Build a CC Setup directly from a fixed-size BCD digit buffer (zero heap allocation). Used by the hot path; the `std::string`-based `buildSetup` overload remains for cold-path callers. |

### ResponseContext — Single Source of Response Parameters

**File:** `gsml3parser/stack/response_context.h`

Per-session parameters required to construct protocol responses. The active procedure populates it as it progresses (via `feed()` / `feedExternalTyped()`); `ResponseBuilder::buildResponseFromToken()` consumes it to build the exact bytes to transmit. This makes the session the single source of truth for response parameters and eliminates fabricated/hardcoded values on the response path.

```cpp
struct ResponseContext {
    // Authentication (TS 24.008 10.5.1.21)
    std::array<uint8_t, 16> rand{};   // 128-bit RAND in wire order
    bool hasRand{false};
    // Call Control (TS 24.008 9.3)
    uint8_t ti{0};
    CCCause ccCause{CCCause::Normal_Call_Clearing};
    std::array<char, 20> calledNumber{};
    uint8_t calledNumberLen{0};
    bool hasCalledNumber{false};
    // Mobility Management (TS 24.008 9.2)
    MMRejectCause mmCause{MMRejectCause::Zero};
    std::optional<uint32_t> newTmsi;
    // Radio Resource (TS 04.08 9.1)
    L3ChannelDescription channel{};
    bool hasChannel{false};
    uint8_t cipherAlgo{0};
    bool hasCipherAlgo{false};
    // Paging (TS 04.08 9.1.25)
    L3MobileIdentity identity{};
    bool hasIdentity{false};
    // Handover (TS 04.08 9.1.40)
    L3ChannelDescription hoChannel{};
    bool hasHoChannel{false};

    void reset() noexcept;   // clear all pending parameters
};
```

- **Ownership:** one instance per `SubscriberSession`, stored inline as `session->response` (`sizeof(ResponseContext) <= 160` bytes, fixed arrays, zero heap).
- **Population rule:** each procedure writes the parameters it learns (RAND from `AuthChallenge`, new TMSI / reject cause from `VLRDecision`, channel from a channel request, TI + called number from a `Setup`, etc.) before returning a `SendResponseWithToken` result.
- **Reset rule:** the context is reset when a new procedure chain starts (`ProcedureRunner::feed()` auto-creation, `ProcedureOrchestrator::feed()` new-chain detection) and on `ProcedureOrchestrator::cancelAll()`. It is deliberately NOT reset when a chain terminates (`onProcedureCompleted`/`onProcedureFailed`/`endChain()`), because the caller may still build the response from the returned token after the procedure has terminated.
- **Missing-parameter rule:** `buildResponseFromToken()` returns -1 if the token requires a parameter that is not present (e.g. `hasRand == false` for `AuthenticationRequest`), never a fabricated value.

**Thread safety:** NOT thread-safe. One instance per session, single-threaded.

### Zero-Allocation Usage with Arena

```cpp
Arena arena(65536);
auto* buf = static_cast<uint8_t*>(arena.allocate(512));
int n = ResponseBuilder::buildCMServiceAccept({buf, 512});
if (n > 0) sendToMS(buf, n);
```

**Thread safety:** All methods are stateless and safe for concurrent use.
**Memory:** Vector overloads allocate one `std::vector` per call; span overloads write directly into caller-provided buffers with zero heap cost.

---

## 13. LAPDm Protocol

**Files:** `gsml3parser/lapdm_frame.h`, `gsml3parser/lapdm_entity.h`
**Namespace:** `gsml3parser::lapdm` (frame types), `gsml3parser` (entity)
**Spec:** GSM 04.06 / 3GPP TS 45.006

Full LAPDm protocol implementation with frame encoding/decoding, state machine, I-frame segmentation/reassembly, T200 timer with retransmission, and contention resolution. Zero-allocation callbacks follow the FlatHandler pattern.

### LAPDm Frame Types

**File:** `gsml3parser/lapdm_frame.h`

#### LAPDmControlFormat

Frame format discriminator (GSM 04.06 4.4):

| Value | Description |
|-------|-------------|
| `I_Format` | Information frame — carries user data with sequence numbers |
| `S_Format` | Supervisory frame — RR, REJ for flow control |
| `U_Format` | Unnumbered frame — UI, SABME, UA, DM, DISC |

#### LAPDmUFrameType

Unnumbered frame types (TS 44.064). Control octets are selected from the
canonical table, index [type][P/F]:

| Value | P/F=0 | P/F=1 | Description |
|-------|-------|-------|-------------|
| `UI` | `0x03` | `0x13` | Unnumbered Information — unacknowledged data |
| `SABME` | `0x2F` | `0x3F` | Set Asynchronous Balanced Mode Extended — link establishment |
| `DM` | `0x0F` | `0x1F` | Disconnected Mode — reject when no link available |
| `DISC` | `0x43` | `0x53` | Disconnect — normal link release |
| `UA` | `0x63` | `0x73` | Unnumbered Acknowledgement — response to SABME/DISC |

#### LAPDmSFrameType

Supervisory frame types (TS 44.064): the two-bit S function code in bits 3:2
of the control octet, with the low two bits fixed to `01`:

| Value | Code | Canonical Octet (NR=0, P/F=0) | Description |
|-------|------|-------------------------------|-------------|
| `RR` | `00` | `0x01` | Receive Ready — acknowledges I-frames up to NR-1 |
| `RNR` | `01` | `0x05` | Receive Not Ready — no response required |
| `REJ` | `10` | `0x09` | Reject — requests retransmission from NR |

#### Field Structures

All field encode/decode methods are `constexpr` for compile-time evaluation:

| Struct | Purpose | Spec |
|--------|---------|------|
| `LAPDmAddressField` | `[Spare+LPD(7:5)=0][SAPI(4:2)][C/R(1)][EA(0)]` | TS 44.064 frame header |
| `LAPDmIControlField` | `[NR(7:5)][P/F(4)][NS(3:1)][Fixed(0)=0]` | TS 44.064 I-format |
| `LAPDmSControlField` | `[NR(7:5)][P/F(4)][S(3:2)][Fixed(1:0)=01]` | TS 44.064 S-format |
| `LAPDmLengthField` | `[L(5:2)][M(1)][Fixed(0)=1]` — the header octet of every frame | TS 44.064 format B |

Every format-B frame is exactly three header octets (address, control, header
octet) plus the info field when present; S-frames and DM/DISC frames carry no
info (L=0). The M bit is 1 while further segments of the same message follow
and 0 on the final or only segment.

#### LAPDmFrame

Non-owning, zero-copy view over the input buffer. The `info` span points into the original buffer passed to `decode()`. Never store as a class member.

```cpp
struct LAPDmFrame {
    LAPDmAddressField address;   // SAPI (0/3), C/R, EA
    LAPDmControlFormat format;   // I_Format / S_Format / U_Format
    LAPDmIControlField iCtrl;    // I-frames: NR, NS, P/F
    uint8_t nr;                  // S-frames: receive sequence number
    LAPDmSFrameType sType;       // S-frames: RR / RNR / REJ
    LAPDmUFrameType uType;       // U-frames: UI / SABME / DM / DISC / UA
    bool pf;                     // Poll/Final (S and U frames)
    bool more;                   // M bit: 1 = further segments follow
    std::span<const uint8_t> info; // zero-copy payload

    SAPI sapi() const noexcept;
    bool isCommand() const noexcept;
    bool hasInfo() const noexcept;
    size_t infoSize() const noexcept;
    static Expected<LAPDmFrame> decode(std::span<const uint8_t> data);
};
```

#### Frame Factory Functions

All factory functions are `constexpr`:

| Function | Description | Spec |
|----------|-------------|------|
| `makeUIFrame(sapi, command, info)` | Unnumbered Information frame | GSM 04.06 5.2.1 |
| `makeSABMEFrame(sapi, command, info)` | Link establishment (with optional payload) | GSM 04.06 5.4.1 |
| `makeUAFrame(sapi, pf, info)` | Unnumbered Acknowledgement | GSM 04.06 5.4.1.2 |
| `makeDMFrame(sapi, pf)` | Disconnected Mode response | GSM 04.06 5.4.6 |
| `makeDISCFrame(sapi, command)` | Normal link release | GSM 04.06 5.4.4 |
| `makeIFrame(sapi, command, nr, ns, pf, more, info)` | Information frame with segmentation (`more` = M bit) | TS 44.064 I-format |
| `makeRRFrame(sapi, nr, pf)` | Receive Ready supervisory | TS 44.064 S-format |
| `makeRNRFrame(sapi, nr, pf)` | Receive Not Ready supervisory | TS 44.064 S-format |
| `makeREJFrame(sapi, nr, pf)` | Reject supervisory | TS 44.064 S-format |

#### Encoding Functions

| Function | Description |
|----------|-------------|
| `encodeFrame(frame)` | Serialize to `std::vector<uint8_t>` (heap allocation) |
| `encodeFrameToBuffer(frame, out, outSize)` | Zero-allocation encode into pre-allocated buffer |

**Usage:**

```cpp
using namespace gsml3parser::lapdm;

// Encode a UI frame for SAPI0 (RR Channel Release: PD in the low nibble)
uint8_t l3Data[] = {0x06, 0x0D, 0x41};
auto uiFrame = makeUIFrame(SAPI::SAPI0, true, std::span(l3Data));
auto encoded = encodeFrame(uiFrame);

// Decode received frame (zero-copy)
auto decoded = LAPDmFrame::decode(std::span(encoded));
if (decoded && decoded->format == LAPDmControlFormat::U_Format &&
    decoded->uType == LAPDmUFrameType::UI) {
    // Process payload from decoded->info
}
```

### LAPDmEntity -- Full Protocol State Machine

**File:** `gsml3parser/lapdm_entity.h`

#### LAPDmState

Protocol states (GSM 04.06 3.5.2):

| State | Description |
|-------|-------------|
| `Unused` | Initial state before `open()` |
| `LinkReleased` | No link, idle |
| `AwaitingEstablish` | Waiting for UA response to SABME |
| `AwaitingRelease` | Waiting for UA response to DISC |
| `LinkEstablished` | Normal data transfer (ABM mode) |
| `ContentionResolution` | Contention resolution phase (SAPI0 only) |

#### LAPDmChannelProfile

Channel-specific parameters:

```cpp
struct LAPDmChannelProfile {
    size_t n201;        // Max I-frame payload in octets
    unsigned n200;      // Max retransmissions
    uint32_t t200Ms;    // T200 timer in milliseconds

    static LAPDmChannelProfile SDCCH(); // n201=20, n200=23, t200=900ms
    static LAPDmChannelProfile SACCH(); // n201=18, n200=5,  t200=3600ms
    static LAPDmChannelProfile FACCH(); // n201=20, n200=34, t200=900ms
    static LAPDmChannelProfile FACCH_LM(); // n201=20, n200=29, t200=900ms
};
```

| Channel | N201 (octets) | N200 (retries) | T200 (ms) | Max timeout |
|---------|---------------|----------------|-----------|-------------|
| SDCCH   | 20            | 23             | 900       | 20.7s       |
| SACCH   | 18            | 5              | 3600      | 18.0s       |
| FACCH   | 20            | 34             | 900       | 30.6s       |
| FACCH_LM | 20           | 29             | 900       | 26.1s       |

#### Callback Types

Zero-allocation callbacks (FlatHandler-style):

```cpp
using L3ReceiveFn = void (*)(SAPI sapi, Primitive prim, std::span<const uint8_t> l3Data, void* ctx);
using L1TransmitFn = void (*)(std::span<const uint8_t> frameBytes, void* ctx);
```

#### LAPDmEntity Public API

| Method | Description | Spec |
|--------|-------------|------|
| `LAPDmEntity(profile, l3Cb, l1Cb, ctx)` | Construct with callbacks | — |
| `open(sapi, commandBit)` | Transition to LinkReleased | GSM 04.06 3.5.2 |
| `receiveFrame(frameBytes)` | Process incoming frame through FSM | GSM 04.06 5.x |
| `sendUI(sapi, l3Data)` | Send unacknowledged UI frame | GSM 04.06 5.2.1 |
| `sendData(l3Data)` | Queue and send acknowledged I-frames (segmented; k=1, segments flow as ACKs arrive) | GSM 04.06 5.5.2 |
| `sendSABME()` | Initiate link establishment | GSM 04.06 5.4.1 |
| `sendDISC()` | Initiate normal link release | GSM 04.06 5.4.4 |
| `hardRelease()` | Immediate transition to LinkReleased | — |
| `tickT200(elapsed)` | Advance T200 timer, triggers retransmission | GSM 04.06 4.3.2 |
| `state()` | Current protocol state | — |
| `sapi()` | Configured SAPI | — |
| `isEstablished()` | True if LinkEstablished or ContentionResolution | — |
| `framesSent()` / `framesReceived()` / `retransmissions()` | Protocol counters | — |
| `hasOutstandingFrame()` | True if I-frame awaiting ACK (k=1) | GSM 04.06 4.3.1 |
| `resetStats()` | Reset all statistics | — |

#### State Transition Diagram

```
Unused ──open()──> LinkReleased
                 │  ^
          SABME  │  │ DISC/UA
           from   │  │
            MS    │  │
                  ▼  │
         AwaitingEstablish ──UA──> LinkEstablished
                  │                      │
             T200 expiry                  │ sendDISC()
                  │                      ▼
                  ▼             AwaitingRelease ──UA──> LinkReleased
             LinkReleased                          │
                                                 T200 expiry
                                                      ▼
                                                 LinkReleased
```

#### Establishment, Contention and Timer Behaviour

LAPDm behaviour rules (TS 51.010-1 / GSM 04.06 section 5):

| Situation | Behaviour |
|-----------|-----------|
| SABME command with P/F clear | Ignored on every SAPI (GSM 04.06 §5.4.1.2) |
| Initial SABME command (P/F set) carrying a payload | Accepted on any SAPI: L3_ESTABLISH_INDICATION delivered, answered by a UA echoing the payload with F mirroring the command; the link enters the contention-resolution state on SAPI 0 and is established directly on every other SAPI |
| Initial SABME command (P/F set) without information (L = 0) | Accepted on any SAPI: L3_ESTABLISH_INDICATION delivered, answered by a plain UA with F mirroring the command; the link enters LinkEstablished |
| UA while awaiting establishment | Only F set is accepted (F cleared is ignored): the entity enters LinkEstablished and delivers L3_ESTABLISH_CONFIRM |
| DM while awaiting establishment | Only F set is processed: T200 is restarted, the retransmission loop continues and L3_RELEASE_INDICATION is delivered — the link is not released |
| T200 expiry on an unacknowledged I-frame | The outstanding I-frame is retransmitted with P/F set and the current V(R) in N(R); N(S) is unchanged |
| N(R) received in any I/S frame | Any N(R) value is accepted: V(A) := N(R); when V(A) equals V(S) the retransmission counter is reset and T200 is stopped (window k=1) |

#### Performance Characteristics

| Metric | Value |
|--------|-------|
| `sizeof(LAPDmEntity)` | < 512 bytes (enforced by `static_assert`) |
| Heap allocations | Zero on `receiveFrame()` hot path |
| Callbacks | Raw function pointer + void* ctx — zero heap per instance |
| Dynamic buffers | `mPendingInfo` (outstanding I-frame payload, rebuilt on retransmission), `mTxBuf` (TX encode buffer, reused after first send), `mReassemblyBuffer` (bounded at 4 KB), `mTxQueue` (TX segment queue) — all lazy-allocated |
| Thread safety | NOT thread-safe; one instance per SAPI per logical channel |

**Usage:**

```cpp
#include <gsml3parser/lapdm_entity.h>

using namespace gsml3parser;

// Callbacks (static functions for zero-allocation)
static void onL3(SAPI sapi, Primitive prim, std::span<const uint8_t> data, void* ctx) {
    // Handle L3 message delivery
}
static void onL1(std::span<const uint8_t> frame, void* ctx) {
    // Send encoded frame to PHY/radio layer
}

// Create entity for SDCCH channel
auto profile = LAPDmChannelProfile::SDCCH();
LAPDmEntity entity(profile, onL3, onL1, nullptr);

entity.open(SAPI::SAPI0, true); // BTS side (command bit = true)

// Send unacknowledged UI data
uint8_t l3Data[] = {0x60, 0x0D, 0x00};
entity.sendUI(SAPI::SAPI0, std::span(l3Data));

// In event loop: tick T200 timer periodically
entity.tickT200(std::chrono::milliseconds(100));
```

---

## 14. Protocol Dispatcher

**File:** `gsml3parser/dispatcher.h`

Callback-based message routing for BTS-style protocol handling. Dispatches incoming L3 messages to registered type-specific handlers using O(1) fixed-array lookup on PD+MTI keys (no hash map, no heap allocation for handler storage).

### MessageHandler

The `MessageHandler` alias is `FlatHandler` — a two-word (fn pointer + ctx, 16 bytes on 64-bit) callback type that avoids `std::function`'s virtual dispatch and potential heap allocation.

```cpp
using MessageHandler = FlatHandler;
```

To create handlers from lambdas, use the factory functions:

| Factory | Use Case | Allocation |
|---------|----------|------------|
| `makeHandler(lambda)` | Non-capturing lambdas (stateless callables only; function pointers are rejected at compile time) | Zero (compile-time resolved) |
| `makeSharedHandler(lambda)` | Capturing lambdas | Heap allocation (shared_ptr managed) |
| `FlatHandler{fn, ctx}` constructor | Plain function pointers with a user context | Zero |

### ProtocolDispatcher

```cpp
class ProtocolDispatcher {
public:
    ProtocolDispatcher() = default;
    ~ProtocolDispatcher();

    void registerHandler(L3PD pd, int mti, MessageHandler handler);
    void registerDomainHandler(L3PD pd, MessageHandler handler);
    void setFallbackHandler(MessageHandler handler);
    void dispatch(const ParsedMessage& msg, void* context = nullptr);
    bool dispatchRaw(std::span<const uint8_t> data, void* context = nullptr);
    void registerTIHandler(uint8_t ti, MessageHandler handler);
    void dispatchWithTI(const ParsedMessage& msg, void* context = nullptr);
};
```

| Method | Description | Complexity |
|--------|-------------|------------|
| `registerHandler(pd, mti, h)` | Register handler for a specific PD + MTI combination | O(1) array index |
| `registerDomainHandler(pd, h)` | Catch-all handler for all messages in a PD domain | O(1) array index |
| `setFallbackHandler(h)` | Global fallback for unregistered message types | O(1) |
| `dispatch(msg, ctx)` | Route a parsed message to the matching handler | O(1) array lookup |
| `dispatchRaw(data, ctx)` | Parse raw bytes and dispatch in one call | O(1) + parse cost |
| `registerTIHandler(ti, h)` | Register handler by Transaction Identifier (CC/SS) | O(1) array index |
| `dispatchWithTI(msg, ctx)` | Dispatch with TI awareness for CC/SS messages | O(1) TI lookup |

**Internal storage:** `std::array<std::array<MessageHandler, 136>, 16>` — fixed ~35 KB handler table, no heap allocations.

**Dispatch priority:** Specific handler (PD+MTI) -> Domain handler (PD) -> Fallback handler.

**Thread safety:** NOT thread-safe. Each thread should create its own `ProtocolDispatcher` instance.

**Usage:**

```cpp
gsml3parser::ProtocolDispatcher dispatcher;

// Non-capturing lambda: use makeHandler (zero allocation)
dispatcher.registerHandler(gsml3parser::L3PD::RadioResource, 0x0D,
    gsml3parser::makeHandler([](const gsml3parser::ParsedMessage& msg, void*) {
        // Handle channel release...
    }));

// Capturing lambda: use makeSharedHandler (heap allocation)
int counter = 0;
dispatcher.registerDomainHandler(gsml3parser::L3PD::RadioResource,
    gsml3parser::makeSharedHandler([&counter](const gsml3parser::ParsedMessage& msg, void*) {
        std::cout << "RR message: " << gsml3parser::messageName(msg) << "\n";
        ++counter;
    }));

// Dispatch parsed message
auto msg = gsml3parser::parseL3Hex("060d00");
if (msg) dispatcher.dispatch(*msg);

// Or dispatch raw bytes directly
uint8_t data[] = {0x06, 0x0D, 0x00};
dispatcher.dispatchRaw(std::span<const uint8_t>(data));
```

---

## 15. Builder Pattern

Every L3 message type provides a fluent `Builder` interface for constructing messages from scratch. Each message class exposes a static `builder()` factory method that returns a builder with chainable setters matching the message's Information Elements, and a `build()` method that returns the constructed message object.

### General API

```cpp
// Each message type follows this pattern:
struct L3SomeMessage {
    static Builder builder();
    // ...
};

// Builder has chainable setters and build():
auto msg = L3SomeMessage::builder()
    .field1(value1)
    .field2(value2)
    .optionalField(value3)
    .build();
```

### Builder Coverage

Builder patterns are implemented for all message types across all 13 protocol domains:

| Domain | Messages with Builder |
|--------|----------------------|
| **RR** | All 98 types (Paging, System Information SI1–SI23 + Type 2quater, Handover, Assignment, Ciphering, DTM/Packet, etc.) |
| **MM** | All 21 types (Location Updating, Authentication, Identity, CM Service, MM Abort, TMSI Reallocation) |
| **CC** | All 21 types (Setup, Notify, Connect, Disconnect, Release, DTMF, Hold, Facility, Progress, etc.) |
| **GMM** | All 23 types (Attach, Detach, RA Update, Service Request, P-TMSI Reallocation, Auth+Ciphering, GMM Identity, etc.) |
| **SM** | All 24 types (Activate/Deactivate/Modify PDP Context, Secondary/MBMS contexts, Notification) |
| **SMS** | 5 CP-layer L3 messages in the variant (CP-DATA/CP-ACK/CP-ERROR/CP-STATUS/CP-SUBMIT) plus the RP payload classes (RPData/RPAck/RPError/RPSMMA) and TP PDUs (Deliver/Submit/StatusReport/Command) |
| **BCC** | All 8 types |
| **GCC** | All 8 types |
| **LS** | Both types |
| **SS** | Facility, Register, Release Complete |
| **PDSS1** | `L3PDSS1Message` (builder takes `mti()` + `body()`) |
| **PDSS2 (Extended)** | `L3ExtendedMessage` (builder takes `mti()` + `body()`) |
| **TestProcedure** | `L3TestProcedureMessage` (builder takes `mti()` + `body()`) |

### Example - Building an Immediate Assignment

```cpp
using namespace gsml3parser;

auto msg = L3ImmediateAssignment::builder()
    .channelDescription(L3ChannelDescription(TDMA_SDCCH8_0, 0, 1, 100))
    .timingAdvance(L3TimingAdvance(32))
    .build();

// Wrap in ParsedMessage and serialize
ParsedMessage pm{RRM{std::move(msg)}};
auto bytes = writeL3Bytes(pm);
```

### Example - Building a Paging Request Type 2

```cpp
auto msg = L3PagingRequestType2::builder()
    .addTMSI(0x12345678, ChannelType::SDCCHType)   // up to 2 TMSIs
    .build();

ParsedMessage pm{RRM{std::move(msg)}};
auto hex = writeL3Hex(pm);
```

### Example - Building a Setup (CC) Message

```cpp
auto msg = L3Setup::builder()
    .calledPartyNumber(L3CalledPartyBCDNumber("1234567890"))
    .bearerCapability(L3BearerCapability{})
    .build();

ParsedMessage pm{CCM{std::move(msg)}};
```

---

## 16. Enum Formatters

**File:** `gsml3parser/enum_formatters.h`

`std::formatter` specializations for gsml3parser protocol enums, enabling use with `std::format`. Each specialization delegates to the corresponding `operator<<(ostream&, T)`.

### Supported Enums

The 19 `std::formatter` specializations below all format through `std::ostream <<`, which the library declares/defines for every listed enum (cause-code enums stream their `*2Str()` names):

| Enum | Domain | `std::format` | Name helper |
|------|--------|---------------|-------------|
| `LogLevel` | Parser config | Yes | — |
| `L3PD` | Protocol Discriminator | Yes | — |
| `Primitive` | Interlayer Primitives | Yes | — |
| `SAPI` | Service Access Point | Yes | — |
| `MobileIDType` | Identity types | Yes | — |
| `TypeOfNumber` | Numbering | Yes | — |
| `NumberingPlan` | Numbering | Yes | — |
| `ChannelType` | RR channels | Yes | — |
| `GSMAlphabet` | Text encoding | Yes | — |
| `RRCause` | RR cause codes | Yes | `RRCause2Str()` |
| `MMRejectCause` | MM reject causes | Yes | `MMRejectCause2Str()` |
| `CMServiceAbortCause` | CM service abort causes | Yes | `CMServiceAbortCause2Str()` |
| `CCCause` | CC cause codes (Q.931) | Yes | `CCCause2Str()` |
| `CCCauseLocation` | CC cause location | Yes | — |
| `BSSCause` | BSSMAP cause codes | Yes | `BSSCause2Str()` |
| `CCMessageType` | CC message type IDs | Yes | — |
| `GMMPTMSIType` | GMM P-TMSI type | Yes | — |
| `L3ProgressIndicator::Location` | CC Progress nested enum | Yes | — |
| `L3ProgressIndicator::Progress` | CC Progress nested enum | Yes | — |

### Usage

```cpp
#include <gsml3parser/enum_formatters.h>

auto msg = gsml3parser::parseL3Hex("060D00");
if (msg) {
    std::string line = std::format("PD: {}", gsml3parser::messagePD(*msg));
    // line == "PD: RadioResource"

    if (auto* cr = gsml3parser::tryGet<gsml3parser::L3ChannelRelease>(*msg)) {
        std::string s = std::format("Cause: {}", cr->cause());  // "Cause: Normal_Event"
    }
}
```

---

## 17. Data Types

**File:** `gsml3parser/types.h`

### L3PD - Protocol Discriminator

```cpp
enum class L3PD : int8_t {
    GroupCallControl = 0x00, BroadcastCallControl = 0x01,
    CallControl = 0x03, MobilityManagement = 0x05,
    RadioResource = 0x06, GPRSMobilityManagement = 0x08,
    SMS = 0x09, GPRSSessionManagement = 0x0a,
    NonCallSS = 0x0b, Location = 0x0c,
    PacketDomainSupplementaryServices1 = 0x0d,
    PacketDomainSupplementaryServices2 = 0x0e, TestProcedure = 0x0f,
    Undefined = -1
};
```

### Primitive - Interlayer Primitives

```cpp
enum class Primitive : uint8_t {
    L2_DATA, L3_DATA, L3_DATA_CONFIRM, L3_UNIT_DATA,
    L3_ESTABLISH_REQUEST, L3_ESTABLISH_INDICATION,
    L3_ESTABLISH_CONFIRM, L3_RELEASE_REQUEST,
    L3_RELEASE_CONFIRM, L3_HARDRELEASE_REQUEST,
    MDL_ERROR_INDICATION, L3_RELEASE_INDICATION,
    PH_CONNECT, HANDOVER_ACCESS
};
```

### SAPI - Service Access Point Indicator

```cpp
enum class SAPI : uint8_t {
    SAPI0 = 0, SAPI3 = 3, Undefined = 16
};
```

SAPI values 0 and 3 only are defined on the Um interface (TS 44.064);
`Undefined` is the sentinel reported for any other three-bit address value.

### MobileIDType

```cpp
enum class MobileIDType : uint8_t {
    NoID = 0, IMSI = 1, IMEI = 2, IMEISV = 3, TMSI = 4
};
```

### TypeOfNumber

```cpp
enum class TypeOfNumber : uint8_t {
    Unknown = 0, International = 1, National = 2,
    NetworkSpecific = 3, ShortCode = 4,
    Alphanumeric = 5, Abbreviated = 6
};
```

### NumberingPlan

```cpp
enum class NumberingPlan : uint8_t {
    Unknown = 0, E164 = 1, X121 = 3, F69 = 4,
    National = 8, Private = 9, ERMES = 10
};
```

### ChannelType

```cpp
enum class ChannelType : uint8_t {
    SCHType, FCCHType, BCCHType, CCCHType, RACHType,
    SACCHType, CBCHType, SDCCHType, FACCHType, TCHFType,
    TCHHType, AnyTCHType, PDTCHCS1Type, PDTCHCS2Type,
    PDTCHCS3Type, PDTCHCS4Type, LoopbackFullType,
    LoopbackHalfType, AnyDCCHType, UndefinedCHType
};
```

### TypeAndOffset — Five-Bit Channel Codes

The `TypeAndOffset` codes (TS 44.018 section 9.2.3, shared with the RSL channel number of TS 48.058
section 9.3.1) are carried in RR channel descriptions:

| Bits | Value | Meaning |
|------|-------|---------|
| `00000` | 0 (`TDMA_MISC`) | invalid; also the not-initialized sentinel |
| `00001` | 1 (`TDMA_Bm_ACCH`) | TCH/F or TCH/H ACCH (Bm) |
| `0001s` | 2–3 (`TDMA_LM_0/1`) | Lm sub-slot s |
| `001ss` | 4–7 (`TDMA_SDCCH4_0..3`) | SDCCH/4 sub-slot ss |
| `01sss` | 8–15 (`TDMA_SDCCH8_0..7`) | SDCCH/8 sub-slot sss |
| `10000` / `10001` / `10010` | 16 / 17 / 18 | BCCH / RACH / PCH + AGCH (`TDMA_BCCH`, `TDMA_RACH`, `TDMA_PCH_AGCH`) |
| `11000` / `11001` / `11010` | 24 / 25 / 26 | PDCH, CBCH/4, CBCH/8 (vendor extensions) |
| `11101` | 29 | VAMOS Bm ACCH (`TDMA_VAMOS_BM`) |
| `1111s` | 30–31 | VAMOS Lm sub-slot s (`TDMA_VAMOS_LM_0/1`) |

Helpers: `channelCodeLm(sub)`, `channelCodeSdcch4(sub)`, `channelCodeSdcch8(sub)`.
`L3ChannelDescription2::initialized()` is true for any non-zero code.

### GSMAlphabet

```cpp
enum class GSMAlphabet : uint8_t {
    ALPHABET_7BIT, ALPHABET_8BIT, ALPHABET_UCS2
};
```

---

## 18. Enumerations

**File:** `gsml3parser/enums.h`

### RRCause - RR Cause Codes

3GPP TS 24.008 10.5.2.31. Values: `Normal_Event`, `Unspecified`, `Channel_Unacceptable`, `Timer_Expired`, `No_Activity_On_The_Radio`, `Preemptive_Release`, `Handover_Impossible`, `Channel_Mode_Unacceptable`, `Frequency_Not_Implemented`, `Call_Already_Cleared`, and protocol error codes.

```cpp
const char* RRCause2Str(RRCause cause);
```

### MMRejectCause - MM Reject Cause Codes

3GPP TS 24.008 10.5.3.6. Values: `IMSI_Unknown_In_HLR`, `Illegal_MS`, `IMSI_Unknown_In_VLR`, `IMEI_Not_Accepted`, `Illegal_ME`, `PLMN_Not_Allowed`, `Location_Area_Not_Allowed`, `Roaming_Not_Allowed_In_LA`, `Network_Failure`, `MAC_Failure`, `Congestion`, and protocol error codes.

```cpp
const char* MMRejectCause2Str(MMRejectCause cause);
```

### CCCause - CC Cause Codes

3GPP TS 24.008 10.5.4.11 / ISDN Q.931. Values: `Unassigned_Number`, `No_Route_To_Destination`, `Normal_Call_Clearing`, `User_Busy`, `Call_Rejected`, `No_Channel_Available`, `Network_Out_Of_Order`, `Requested_Facility_Not_Subscribed`, and 40+ more.

```cpp
const char* CCCause2Str(CCCause cause);
```

### CCCauseLocation

Indicates where the cause originated: `User`, `Private_Serving_Local`, `Public_Serving_Local`, `Transit`, `Public_Serving_Remote`, `Private_Serving_Remote`, `International`, `Beyond_Inter_Networking`.

### BSSCause - BSS Cause Codes

3GPP TS 48.008 3.2.2.5. Values: `Radio_Interface_Failure`, `Uplink_Quality`, `Downlink_Quality`, `Handover_Successful`, `Better_Cell`, `No_Radio_Resource_Available`, `CCCH_Overload`, and more.

```cpp
const char* BSSCause2Str(BSSCause cause);
```

---

## 19. Protocol Types

**File:** `gsml3parser/protocol_types.h`

Bounded protocol field types that enforce spec-defined ranges at compile time.

### Bounded<T, Min, Max>

Template for range-checked scalar values:

```cpp
template<typename T, T Min, T Max>
struct Bounded {
    T value{Min};
    constexpr explicit Bounded(T v);
    [[nodiscard]] constexpr T get() const noexcept;
    [[nodiscard]] constexpr operator T() const noexcept;
    Bounded& operator=(T v) & noexcept;
    static constexpr T min();
    static constexpr T max();
};
```

### Common Bounded Types

| Type | Range | Description |
|------|-------|-------------|
| `Arfcn` | 0–4095 | Absolute Radio Frequency Channel Number (12 bits, TS 44.018 10.5.2.5) |
| `Bsic` | 0–63 | Base Station Identity Code (6 bits) |
| `TimingAdvanceValue` | 0–63 | Timing Advance (6 bits) |
| `Ncc` | 0–7 | Network Color Code (3 bits) |
| `Bcc` | 0–7 | Base Station Color Code (3 bits) |
| `Tsc` | 0–7 | Training Sequence Code (3 bits) |
| `Hsn` | 0–7 | Hopping Sequence Number (3 bits) |
| `Maio` | 0–63 | MAIO (Multiframe Offset, 6 bits) |
| `TimeslotNumber` | 0–15 | TDMA timeslot (4 bits) |
| `CellIdentity` | 0–65535 | Cell Identity (16 bits) |
| `Lac` | 0–65535 | Location Area Code (16 bits) |
| `Cksn` | 0–7 | Ciphering key sequence number (3 bits) |
| `CiValue` | 0–15 | Bounded 4-bit field value |

---

## 20. Common Information Elements

**File:** `gsml3parser/common/l3common.h`

All IEs are plain value types with a static `Expected<T> parse(BitReader&)`, `write(BitWriter&) const`, and `text(std::ostream&) const` method (plus typed accessors and, where applicable, a constexpr `lengthV()`). No virtual base class, no RTTI.

### L3MobileIdentity

Mobile station identifier (TMSI, IMSI, IMEI, IMEISV).

Value part per TS 24.008 section 9.1.3.x: the first octet packs
[first digit(4) | odd-count(1) | identity type(3)] — the odd-count bit is set when the
digit count is odd; for TMSI it is the spare 'F' nibble, a zero bit and type '100'B
(first octet `0xF4`). Subsequent digit pairs follow as [next digit or 'F' fill | current
digit]. Length: 1 + nDigits/2 octets (integer division) for digit identities, 5 for TMSI,
1 for NoID.

| Method | Description |
|--------|-------------|
| `L3MobileIdentity(uint32_t tmsi)` | Construct from TMSI |
| `L3MobileIdentity(std::string_view digits)` | Construct from digit string (IMSI/IMEI) |
| `type()` | Returns `MobileIDType` enum |
| `digits()` | Returns digit string view |
| `tmsi()` | Returns TMSI value |

### L3LocationAreaIdentity

PLMN packed as BCD octets followed by the 16-bit LAC (TS 24.008 section 10.5.1.3):

| Octet | Nibbles |
|-------|---------|
| 1 | MCC digit 2 \| MCC digit 1 |
| 2 | MNC digit 3 ('F' fill for a two-digit MNC) \| MCC digit 3 |
| 3 | MNC digit 2 \| MNC digit 1 |
| 4–5 | LAC (big-endian) |

MCC is always three digits; MNC is two or three digits. `mcc()`/`mnc()` return the
digits in natural order. `L3RoutingAreaIdentification` (GMM elements) is the same PLMN +
LAC plus one RAC octet — six octets total.

| Method | Description |
|--------|-------------|
| `L3LocationAreaIdentity(mcc, mnc, lac)` | Construct from components (BCD MCC/MNC strings + 16-bit LAC) |
| `mcc()`, `mnc()`, `lac()` | Accessor methods (PLMN as integers, LAC 0–65535) |

### L3CellIdentity

2-byte cell identifier.

### L3CellChannelDescription / L3BCCHFrequencyList

Sixteen-octet variable-length BCCH frequency list form (TS 44.018 section 10.5.2.1b):
`[header(7)][base ARFCN(10)][presence bitmap(111)]` — no length field and no leading spare bits; bit
*i* of the presence map (counted from the bit immediately after the base) marks the presence of ARFCN
`base + 1 + i`. The builder takes an ARFCN list (`std::span<const uint16_t>`), emits header `'1000111'B`
with the smallest ARFCN as base and the bitmap; parse accepts any seven-bit header form and keeps the
raw sixteen octets for lossless re-emit. Used by the SI1 cell channel description and Frequency
Redefinition; `L3BCCHFrequencyList` / `L3FrequencyList` are aliases of the same codec for the SI2,
SI2bis, SI2ter, SI5, SI5bis and SI5ter frequency lists.

### L3NeighbourCellDescription

Sixteen-bit record: [ARFCN(10)][BSIC(6)] with the BSIC packed as [NCC(3)|BCC(3)] (TS 44.018 section
10.5.2.1b); `lengthV() == 2`. The repeated records form the neighbour-cell lists of SI7, SI8 and
SI17-20.

### L3MobileStationClassmark1/2/3

MS classmark with power class, voice support, frequency bands, and optional GPRS extensions.

### L3ChannelDescription / L3ChannelDescription2

Logical channel type + TDMA frame number + timeslot + ARFCN.

### L3BCCHFrequencyList

List of BCCH carrier frequencies with NCC information.

### L3CellSelectionParameters

RxLevAccessMin, CellBarred, CAC, ACs for GPRS.

### L3RACHControlParameters

Max retransmissions (2 bits), TX integer (4 bits), the cell-barred-access and RE
bits, and the 16-bit access class bitmap: bit i corresponds to access class i
(i = 0..15), low octet first on the wire; a set bit bars the corresponding
class, emergency calls use access class 10 (TS 44.018 section 10.5.2.29).

### L3MeasurementResults

Serving cell RxLev/RxQual + up to 7 neighbor cell measurements.

### L3PowerCommand / L3PowerCommandAndAccessType

Absolute or relative power control command with optional access type.

### L3TimingAdvance

6-bit timing advance value (0–63), one wire octet: [spare(2)=0 | TA(6)];
for 0–63 the octet equals the value (TS 44.018 section 10.5.2.40).

### L3CipheringModeSetting / L3CipheringModeResponse

The Ciphering Mode Command body is one octet: the response — spare(3)|cR(1)
(IMEISV inclusion flag) — in the high half-octet, then the setting — algorithm(3)|sC(1)
— in the low half-octet, so the start-ciphering flag sits in the lowest bit of the octet
(TS 44.018 section 9.2.24).

### L3MultiRateConfiguration

AMR codec set and mode set negotiation.

### L3ControlChannelDescription

Control channel description IE (TS 44.018 section 10.5.2.11): MSC R99, ATT, BS AG
BLKS RES, CCCH CONF, SI22 indicator, CBQ3, BS PA MFRMS and T3212.

### L3CellDescription, L3HandoverReference

Cell parameters and handover reference for handover procedures.

---

## 21. Radio Resource Messages

**File:** `gsml3parser/rr/l3rrmessages.h` - 98 message types in the `RRM` variant (PD=0x06).

Each message is a plain struct with:
- `static Expected<Self> parse(BitReader&)`
- `write(BitWriter&) const`
- `mti() const` -> dispatch MTI (RR short/SACCH messages report values ≥ 0x100, matching `L3Header::mti`)
- `text(std::ostream&) const` -> human-readable output
- `static Builder builder()` + `build()` -> fluent construction (see §15)

RR short messages (TIF set) carry the standard L3 header — octet 0 = 0x16 for TI=0 — and their five-bit codes map to dispatch MTIs from `kRRTifShortBase` (`kRRTifShortBase + code`); codes not assigned by TS 44.018 Table 10.4.2 (code 3 and codes 14–31) map to empty dispatcher slots and are rejected as InvalidMTI. The two length-framed messages with no header (`L3ChannelRequest` 1 B, `L3HandoverAccess` 4 B) use internal MTIs above that range (0x181, 0x182) so a wire short frame can never be misclassified as one of them; they are recognized by frame length on RACH.

### Short Messages (no standard L3 header)

| Message | Size | Description |
|---------|------|-------------|
| `L3ChannelRequest` | 1 byte | RACH access: single-octet request reference (RA) |
| `L3HandoverAccess` | 4 bytes | 27-bit payload + five reserved bits (TS 44.018); the payload is kept as an opaque value |

### Paging Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3PagingRequestType1` | 0x21 | DL | First octet [channelNeeded(4)\|pageMode(4)] (channel needed packed second\|first), MobileIdentity (LV) [+ optional second ID (TLV 0x17)] |
| `L3PagingRequestType2` | 0x22 | DL | First octet [channelNeeded(4)\|pageMode(4)], two raw TMSIs (8 bytes) [+ optional third identity (TLV 0x17)] |
| `L3PagingRequestType3` | 0x24 | DL | First octet [channelNeeded(4)\|pageMode(4)], four raw TMSIs (16 bytes) |
| `L3PagingResponse` | 0x27 | UL | First octet [spare(4)\|CKSN(4)], Classmark2 (LV, three to seven value octets), MobileIdentity (LV) |

### System Information Messages

| Message | MTI | Description |
|---------|-----|-------------|
| `L3SystemInformationType1` | 0x19 | Cell channel description (sixteen-octet variable-length BCCH frequency list form, TS 44.018 §10.5.2.1b), RACH control parameters (3 octets), [rest octet]; body 19–20 octets |
| `L3SystemInformationType2` | 0x1a | BCCH freq list (sixteen-octet bitmap form), NCC permitted, RACH control |
| `L3SystemInformationType2bis` | 0x02 | BCCH freq list (sixteen-octet bitmap form) + RACH control, [rest octets 0–1] |
| `L3SystemInformationType2ter` | 0x03 | BCCH freq list (sixteen-octet bitmap form), [rest octets 0–4] |
| `L3SystemInformationType3` | 0x1b | Cell desc, BA list type 1, rest octets |
| `L3SystemInformationType4` | 0x1c | LAI, CI, cell selection, RACH control, rest octets |
| `L3SystemInformationType5` | 0x1d | BA list type 2 (sixteen-octet frequency list form) |
| `L3SystemInformationType5bis` | 0x05 | Extended BA list (GPRS, sixteen-octet frequency list form) |
| `L3SystemInformationType5ter` | 0x06 | BA list with GPRS cell options (sixteen-octet frequency list form) |
| `L3SystemInformationType6` | 0x1e | CI, LAI, SACCH cell options, NCC permitted |
| `L3SystemInformationType7` | 0x1f | BA list type 3 |
| `L3SystemInformationType8` | 0x18 | NCC permitted (SACCH) |
| `L3SystemInformationType9` | 0x04 | CI, cell selection, BCCH cell options |
| `L3SystemInformationType13` | 0x00 | Rest-octets record only: typed GPRS mobile allocation / cell options / power-control parameters (variable length, padded to the octet boundary) |
| `L3SystemInformationType2quater` | 0x07 | Extended BCCH freq list, RACH ctrl params, CBCH description (raw body) |
| `L3SystemInformationType16` | 0x3d | CI, cell selection (SACCH) |
| `L3SystemInformationType17` | 0x3e | NCC permitted (SACCH extended) |

### Dedicated Channel Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3ChannelRelease` | 0x0D | DL | Cause [+ GPRS resumption] |
| `L3ImmediateAssignment` | 0x3F | DL | dedicated mode/TBF + page mode, channel description, request reference, timing advance, [mobile allocation (LV)], [start time (TLV 0x7C: two value octets packing T1(5)/T3(6)/T2(5))] |
| `L3ImmediateAssignmentExtended` | 0x39 | DL | Extended immediate assignment |
| `L3ImmediateAssignmentReject` | 0x3A | DL | First octet [spare(4)\|pageMode(4)] + exactly four (request reference, wait indication) pairs — fewer supplied pairs padded by repeating the last one; body 17 octets |
| `L3AdditionalAssignment` | 0x3B | DL | Additional channel assignment |
| `L3PhysicalInformation` | 0x2D | DL | Timing advance command |
| `L3AssignmentCommand` | 0x2E | DL | Channel desc, mode, power command |
| `L3AssignmentComplete` | 0x29 | UL | Cause |
| `L3AssignmentFailure` | 0x2F | UL | Cause |
| `L3HandoverCommand` | 0x2B | DL | Cell desc, channel desc2, HO ref, power, sync |
| `L3HandoverComplete` | 0x2C | UL | Cause |
| `L3HandoverFailure` | 0x28 | UL | Cause |
| `L3RRStatus` | 0x12 | UL | Cause |
| `L3ClassmarkChange` | 0x16 | UL | Classmark2 (LV, three to seven value octets) [+ Classmark3 (TLV 0x20)] |
| `L3ClassmarkEnquiry` | 0x13 | DL | Empty body |
| `L3MeasurementReport` | 0x15 | UL | RxLev/RxQual + neighbors |
| `L3CipheringModeCommand` | 0x35 | DL | One octet: high nibble [spare(3)\|cR(1)], low nibble [algorithm(3)\|sC(1)] — start-ciphering in the low bit (TS 44.018 §9.2.24) |
| `L3CipheringModeComplete` | 0x32 | UL | No fixed fields (optional MEI kept opaque) |
| `L3ChannelModeModify` | 0x10 | DL | Channel desc + mode [+ multi-rate] |
| `L3ChannelModeModifyAcknowledge` | 0x17 | UL | Channel desc + mode |
| `L3GPRSSuspensionRequest` | 0x34 | UL | TLLI (V, four octets), RAI (V, six octets), suspension cause [+ service support (TV, IEI 0x01, one value octet)]; body 11 or 13 octets |
| `L3ApplicationInformation` | 0x38 | DL/UL | First octet [flags(4)\|protocolId(4)] (flags: spare\|CR\|first segment\|last segment), data length octet, then the RRLP data bytes |

### Configuration Change Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3ConfigurationChangeCommand` | 0x30 | DL | [ChanDesc] [PowerCmd] |
| `L3ConfigurationChangeAcknowledge` | 0x31 | UL | Empty body |
| `L3ConfigurationChangeReject` | 0x33 | UL | Cause |

### Partial Release Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3PartialRelease` | 0x0a | DL | ChannelDescription |
| `L3PartialReleaseComplete` | 0x0f | UL | Empty body |

### Extended Measurement Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3ExtendedMeasurementReport` | 0x36 | UL | MeasurementResults (16 octets) |
| `L3ExtendedMeasurementOrder` | 0x37 | DL | Variable-length data |

### Frequency Redefinition

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3FrequencyRedefinition` | 0x14 | DL | CellChannelDescription (sixteen-octet variable BCCH frequency list form) + RACHControlParameters |

### Notification Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3NotificationNCH` | 0x20 | DL | Variable-length data (CBCH) |
| `L3NotificationResponse` | 0x26 | UL | Variable-length data |

### VGCS/VBS Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3VGCSUplinkGrant` | 0x09 | DL | Request reference (three octets) + timing advance (one octet); body 4 octets |
| `L3UplinkRelease` | 0x0e | DL | RR cause (one octet) |
| `L3UplinkBusy` | 0x2a | DL | All information elements optional — a header-only frame is valid; present IEs kept as an opaque tail for lossless re-emit |

### Data Indication Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3TalkerIndication` | 0x11 | DL | Classmark2 (LV, three to seven value octets) + mobile identity (LV) [+ CKSN (TV, IEI 0x0B, one value octet)] |
| `L3PriorityUplinkRequest` | 0x66 | UL | Estimated cause (one octet) + [token(4)\|reduced GCR(4)] (one octet) + mobile identity (LV) |
| `L3DataIndication` | 0x67 | DL | TMSI (four octets) + application data (nine octets) + data identifier (one octet); body 14 octets |
| `L3DataIndication2` | 0x68 | DL | TMSI (four octets) + reduced GCR (four bits, zero-padded to its octet) + application data (nine octets) + data identifier (one octet); body 15 octets |

### DTM and Packet Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3DTMAssignmentFailure` | 0x48 | UL | Cause |
| `L3DTMReject` | 0x49 | DL | Empty body |
| `L3DTMRequest` | 0x4A | UL | Empty body |
| `L3PacketAssignment` | 0x4B | DL | ChannelDescription + TimingAdvance |
| `L3ImmediatePacketAssignment` | 0x69 | DL | Opaque variable value part (DTM packet channel) |
| `L3DTMAssignmentCommand` | 0x4C | DL | Empty body |
| `L3DTMInformation` | 0x4D | UL | Empty body |
| `L3PacketInformation` | 0x4E | DL | Empty body |

### Inter-RAT Classmark Change Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3UTRANClassmarkChange` | 0x60 | UL | Variable-length classmark |
| `L3CDMA2000ClassmarkChange` | 0x62 | UL | Variable-length classmark |
| `L3IntersysToUTRANHOCommand` | 0x63 | DL | Variable-length HO data |
| `L3IntersysToCDMA2000HOCommand` | 0x64 | DL | Variable-length HO data |
| `L3GERANIUClassmarkChange` | 0x65 | UL | Variable-length classmark |

### Additional System Information Messages

| Message | MTI | Description |
|---------|-----|-------------|
| `L3SystemInformationType14` | 0x01 | CellIdentity + CellSelectionParameters |
| `L3SystemInformationType15` | 0x43 | Empty body |
| `L3SystemInformationType18` | 0x40 | RACHControl + CellChannelDescriptions |
| `L3SystemInformationType19` | 0x41 | RACHControl + CellChannelDescriptions |
| `L3SystemInformationType20` | 0x42 | RACHControl + CellChannelDescriptions |
| `L3SystemInformationType13alt` | 0x44 | Empty body |
| `L3SystemInformationType2n` | 0x45 | Empty body |
| `L3SystemInformationType21` | 0x46 | Empty body |
| `L3SystemInformationType22` | 0x47 | Empty body |
| `L3SystemInformationType23` | 0x4f | Empty body |

### SACCH Short Messages (TIF=1)

These carry the standard L3 header with TIF set (octet 0 = 0x16 for TI=0); the five-bit code in
octet 1 maps to the internal dispatch MTI `kRRTifShortBase + code` (codes not assigned by TS 44.018
Table 10.4.2 — code 3 and codes 14–31 — have no class).

| Message | MTI | Description |
|---------|-----|-------------|
| `L3SystemInformationType10` | 0x100 | CI + LAI + CellOptions + CellSelectionParameters (code '00000'B) |
| `L3SystemInformationType10bis` | 0x10A | CI + LAI + CellOptions + CellSelectionParameters (code '01010'B) |
| `L3SystemInformationType10ter` | 0x10B | CI + LAI + CellOptions + CellSelectionParameters (code '01011'B) |
| `L3NotificationFACCH` | 0x101 | FACCH notification (code '00001'B) |
| `L3UplinkFree` | 0x102 | FACCH uplink free (code '00010'B) |
| `L3EnhancedMeasurementRepUL` | 0x104 | FACCH measurement report UL (code '00100'B) |
| `L3MeasurementInfoDL` | 0x105 | FACCH measurement info DL (code '00101'B) |
| `L3VBSVGCSRecon` | 0x106 | VBS/VGCS reconfiguration (code '00110'B) |
| `L3VBSVGCSRecon2` | 0x107 | VBS/VGCS reconfiguration 2 (code '00111'B) |
| `L3VGCSAddInfo` | 0x108 | VGCS additional info (code '01000'B) |
| `L3VGCSMSInfo` | 0x109 | VGCS MS info (code '01001'B) |
| `L3VGCSSNeighCellInfo` | 0x10C | VGCS neighbor cell info (code '01100'B) |
| `L3NotifyAppData` | 0x10D | Notify application data (code '01101'B) |

---

## 22. Mobility Management Messages

**File:** `gsml3parser/mm/l3mmmessages.h` - 21 message types in the `MMM` variant (PD=0x05).

### MM Information Elements

**File:** `gsml3parser/mm/l3mmelements.h`

| IE | Description |
|----|-------------|
| `L3CMServiceType` | CM service type code (MO call, emergency, SMS, etc.) |
| `L3RejectCauseIE` | MM reject cause value |
| `L3NetworkName` | PLMN network name (GSM alphabet encoded) |
| `L3TimeZoneAndTime` | Local/UTC time with timezone offset |
| `L3RAND` | 128-bit authentication challenge |
| `L3SRES` | 32-bit authentication response |

### MM Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3IMSIDetachIndication` | 0x01 | UL | Classmark1 (V, one value octet, no length) + mobile identity (LV) |
| `L3LocationUpdatingAccept` | 0x02 | DL | LAI [+ new MobileIdentity] |
| `L3LocationUpdatingReject` | 0x04 | DL | Reject cause |
| `L3LocationUpdatingRequest` | 0x08 | UL | Update type + follow-on + CKSN (one octet: [lu(2)][spare(1)][FOP(1)][CKSN(3)][reserved(1)]), LAI (V, five octets), classmark1 (V, one octet, no length), mobile identity (LV) |
| `L3CMServiceAccept` | 0x21 | DL | Empty body |
| `L3CMServiceReject` | 0x22 | DL | Reject cause |
| `L3CMServiceAbort` | 0x23 | DL | No value part (TS 24.008 9.2.7) |
| `L3CMServiceRequest` | 0x24 | UL | One octet: CKSN(3)\|reserved(1) high half-octet, CM service type(4) low half-octet; classmark2 (LV), mobile identity (LV), optional IEs opaque |
| `L3CMReestablishmentRequest` | 0x28 | UL | One octet: CKSN(3)\|spare(5) in the low bits; classmark2 (LV, three to seven value octets), mobile identity (LV) [+ LAI (TLV 0x13)] |
| `L3MMAbort` | 0x29 | DL/UL | No value part (TS 24.008) |
| `L3IdentityResponse` | 0x19 | UL | MobileIdentity |
| `L3IdentityRequest` | 0x18 | DL | Identity type (IMSI/IMEI) |
| `L3MMInformation` | 0x32 | DL | Network name, time zone, ciphering mode |
| `L3TMSIReallocationCommand` | 0x1A | DL | LAI (V, five octets, not length-prefixed) + new mobile identity (LV); no further value part (TS 24.008 §9.2.17) |
| `L3TMSIReallocationComplete` | 0x1B | UL | Empty body |
| `L3MMStatus` | 0x31 | UL/DL | Cause + spare |
| `L3AuthenticationRequest` | 0x12 | DL | CKSN (high half-octet of the first octet, three bits) + RAND (16 octets); optional authentication parameters kept opaque |
| `L3AuthenticationResponse` | 0x14 | UL | SRES (32-bit) |
| `L3AuthenticationReject` | 0x11 | DL | Empty body |
| `L3AuthenticationFailure` | 0x1C | UL | Reject cause (bare octet) + optional IEI 0x22 TLV with the 16-octet AUTS (TS 24.008 9.2.3a/10.5.3.6) |
| `L3CMServicePrompt` | 0x25 | DL | One octet spare(2)|SAPI(2)|PD(4) of the requested CM protocol (TS 24.008 9.2.5a/10.5.1.10a) |

---

## 23. Call Control Messages

**File:** `gsml3parser/cc/l3ccmessages.h` - 21 message types in the `CCM` variant (PD=0x03, dialog protocol — header carries TI).

### CC Information Elements

**File:** `gsml3parser/cc/l3ccelements.h`

| IE | IEI | Format | Description |
|----|-----|--------|-------------|
| `L3BearerCapability` | 0x04 | TLV | Bearer capability (coding, mode, rate) |
| `L3BackupBearerCapability` | 0x7c | TLV | Backup bearer capability |
| `L3SupportedCodecList` | 0x40 | TLV | AMR codec set and mode preferences |
| `L3BCDDigits` | - | V | BCD-encoded digit string utility |
| `L3CalledPartyBCDNumber` | 0x5e | TLV | Called party number |
| `L3CallingPartyBCDNumber` | 0x5c | TLV | Calling party number |
| `L3ConnectedNumber` | 0x9c | TLV | Connected party number (GSM 04.08 10.5.4.7) |
| `L3RedirectingNumber` | 0x74 | TLV | Redirecting number (TS 24.008 10.5.4.13) |
| `L3SubAddress` | 0x5d/0x6d/0x9b | TLV | Calling (0x5d, Setup), called (0x6d) and connected (0x9b, Connect) party sub-address (TS 24.008 10.5.4.3) |
| `L3CauseElement` | 0x08 | TLV | CC cause (length 2; TS 24.008 §10.5.1.2): value octets `[0x60\|location(4)][0x80\|cause(7)]` |
| `L3CallState` | - | V | Call state flags (speech, DTMF, hold, etc.) |
| `L3ProgressIndicator` | 0x1e | TV | Progress indicator: in SETUP/CONNECT/ALERTING/Call Proceeding a one-octet value `[location(4)\|progress(4)]` after the IEI; in the CC PROGRESS body an LV of two octets `[0xE0\|location][0x80\|progress]` |
| `L3KeypadFacility` | 0x2c | TV | DTMF digit indicator |
| `L3Signal` | 0x34 | TV | Signal type indicator (GSM 04.08 10.5.4.23) |
| `L3RepeatIndicator` | 0x0d | TV | Repeat count for keypad DTMF |
| `L3CLIRSuppression` | 0xa1 | T | CLIR suppression — type T: the identifier octet is the whole encoding, no value part (TS 24.008 10.5.4.16) |
| `L3CLIRInvocation` | 0xa2 | T | CLIR invocation — type T: the identifier octet is the whole encoding, no value part (TS 24.008 10.5.4.17) |
| `L3NetworkCCCapabilities` | 0x2f | TLV | Network CC capabilities (TS 24.008 10.5.4.15) |
| `L3LowLayerCompatibility` | 0x7c | TLV | Low layer compatibility (TS 24.008 10.5.4.14) |
| `L3HighLayerCompatibility` | 0x7d | TLV | High layer compatibility (TS 24.008 10.5.4.14) |
| `L3UserUser` | 0x7e | TLV | User-User information element (TS 24.008 10.5.4.27) |
| `L3Priority` | 0x88 | TV | Priority level and request flag (TS 24.008 10.5.4.19) |
| `L3StreamIdentifier` | 0x2d | TLV | VBS/VGCS stream identifier, one-octet value part (TS 24.008 10.5.4.29) |
| `L3AllowedActions` | 0x92 | TLV | Allowed actions bitmask (TS 24.008 10.5.4.2) |
| `L3CCCapabilities` | 0x15 | TLV | CC capabilities (TS 24.008 10.5.4.4) |
| `L3SupServFacilityIE` | 0x1c | TLV | Supplementary service facility data |
| `L3SupServVersionIndicator` | 0x7f | V/TLV | SS version indicator: value-only class carried as a TLV with a one-octet value part (TS 24.008 10.5.4.24) |

#### IE Encoding Formats

- **V (Value-only):** No IEI octet; length is fixed by spec
- **T (Type only):** the IEI octet is the whole encoding — no value part
- **TV (Type-Value):** IEI octet + fixed-size value (typically 1 octet)
- **TLV (Type-Length-Value):** IEI octet + length octet + variable-length value
- **LV (Length-Value):** Length octet + value (IEI known from context)

### CC Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3Setup` | 0x05 | UL | CalledParty [+ CallingParty, BearerCapability, SupportedCodecs, Signal, SubAddress, LowLayerCompat, HighLayerCompat, UserUser, CLIRSuppression, CLIRInvocation, CCCapabilities, StreamIdentifier, Facility, SSVersion] |
| `L3EmergencySetup` | 0x0e | UL | Emergency call setup (no called party) |
| `L3CallProceeding` | 0x02 | DL | [+ BearerCapability×2, ProgressIndicator, Priority, NetworkCCCapabilities] |
| `L3Alerting` | 0x01 | DL | [+ Facility, ProgressIndicator, UserUser, SSVersion] |
| `L3Connect` | 0x07 | UL | [+ ProgressIndicator, ConnectedNumber, ConnectedSubAddress, UserUser, StreamIdentifier] |
| `L3ConnectAcknowledge` | 0x0f | DL | Empty body |
| `L3CCNotify` | 0x3e | MT | Notify: single cause octet (TS 24.008) |
| `L3CallConfirmed` | 0x08 | DL | [+ BearerCapability, SupportedCodecs, Cause, UserUser] |
| `L3Disconnect` | 0x25 | UL | Cause as a length-value element without an identifier (first body octet = value length, two value octets: CCCause + CCCauseLocation) |
| `L3Release` | 0x2d | DL/UL | [+ Cause, Facility, SSVersion] |
| `L3ReleaseComplete` | 0x2a | DL/UL | [+ Cause, Facility, SSVersion] |
| `L3StartDTMF` | 0x35 | UL | KeypadFacility digit |
| `L3StopDTMF` | 0x31 | UL | Empty body |
| `L3StopDTMFAcknowledge` | 0x32 | DL | Empty body |
| `L3StartDTMFAcknowledge` | 0x36 | DL | KeypadFacility digit |
| `L3StartDTMFReject` | 0x37 | DL | Cause |
| `L3Facility` | 0x3a | DL/UL | CC Facility — SS facility data container (TS 24.008 9.3.21) |
| `L3Hold` | 0x18 | UL | Empty body |
| `L3HoldReject` | 0x1a | DL | Cause |
| `L3CCStatus` | 0x3d | DL/UL | Cause as a length-value element without an identifier (first body octet = value length, two value octets) + call state (one octet); four-octet body |
| `L3Progress` | 0x03 | DL | Progress indicator LV (`[0x02][0xE0\|location][0x80\|progress]`; TS 24.008 §9.3.17) |

#### CC Message Type Identifiers

MTI values are the 6-bit messageType field (GSM 04.08 Table 10.3). In the L3 header byte 1, the actual encoding is `(mti << 2) | nsd` where `nsd` (Not Significant Data) is 2 bits.

| MTI | Message | Spec Section |
|-----|---------|-------------|
| 0x01 | Alerting | TS 24.008 9.3.1 |
| 0x02 | Call Proceeding | TS 24.008 9.3.3 |
| 0x03 | Progress | TS 24.008 9.3.17 |
| 0x05 | Setup | TS 24.008 9.3.2 |
| 0x07 | Connect | TS 24.008 9.3.5 |
| 0x08 | Call Confirmed | TS 24.008 9.3.2 |
| 0x0e | Emergency Setup | TS 24.008 9.3.8 |
| 0x0f | Connect Acknowledge | TS 24.008 9.3.6 |
| 0x18 | Hold | TS 24.008 9.3.23 |
| 0x1a | Hold Reject | TS 24.008 9.3.24 |
| 0x25 | Disconnect | TS 24.008 9.3.7 |
| 0x2a | Release Complete | TS 24.008 9.3.19 |
| 0x2d | Release | TS 24.008 9.3.19 |
| 0x31 | Stop DTMF | TS 24.008 9.3.25 |
| 0x32 | Stop DTMF Acknowledge | TS 24.008 9.3.25 |
| 0x35 | Start DTMF | TS 24.008 9.3.25 |
| 0x36 | Start DTMF Acknowledge | TS 24.008 9.3.25 |
| 0x37 | Start DTMF Reject | TS 24.008 9.3.25 |
| 0x3a | Facility | TS 24.008 9.3.21 |
| 0x3d | CC Status | TS 24.008 9.3.19 |
| 0x3e | Notify | TS 24.008 |

---

## 24. Supplementary Services Messages

**File:** `gsml3parser/ss/l3ssmessages.h` - 3 message types in the `SSM` variant.

All three carry an SS-Data body (TS 24.078 / GSM 04.80): a TCAP-style component container
`[component tag(1)][component length(1)][component]` with tags Invoke=0xA1, ReturnResult=0xA2,
ReturnError=0xA3, Reject=0xA4; the component is parsed further by `L3FacilityOpCode` / `L3USSDData`
below and re-emitted losslessly from its raw bytes. The header carries TI like other dialog messages.

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3SupServFacilityMessage` | 0x3a | DL/UL | SS facility data (SS-Data component container — see `L3FacilityOpCode` below) |
| `L3SupServRegisterMessage` | 0x3b | DL/UL | Registration request/response |
| `L3SupServReleaseCompleteMessage` | 0x2a | DL/UL | SS release complete |

### SS Operation Codes

**File:** `gsml3parser/cc/l3ccelements.h`

TCAP operation codes as defined in GSM TS 04.80 section 4.5.

```cpp
enum class SSOpCode : uint8_t {
    RegisterSS = 0x0A,       EraseSS = 0x0B,
    ActivateSS = 0x0C,       DeactivateSS = 0x0D,
    InterrogateSS = 0x0E,    NotifySS = 0x10,
    RegisterPassword = 0x11, GetPassword = 0x12,
    ProcessUSSData = 0x13,   ForwardCheckSSInd = 0x26,
    ProcessUSSReq = 0x3B,    USSRequest = 0x3C,
    USSNotify = 0x3D,        ForwardCUGInfo = 0x78,
    SplitMPTY = 0x79,        RetrieveMPTY = 0x7A,
    HoldMPTY = 0x7B,         BuildMPTY = 0x7C,
    ForwardChargeAdvice = 0x7D
};

std::string_view ssOpCodeName(SSOpCode code);
```

### SS Error Codes

TCAP error codes as defined in GSM TS 04.80 section 4.5.

```cpp
enum class SSErrorCode : uint8_t {
    UnknownSubscriber = 0x01,       IllegalSubscriber = 0x09,
    BearerServiceNotProvisioned = 0x0A, TeleserviceNotProvisioned = 0x0B,
    IllegalEquipment = 0x0C,        CallBarred = 0x0D,
    IllegalSSOperation = 0x10,      SSErrorStatus = 0x11,
    SSNotAvailable = 0x12,          SSSubscriptionViolation = 0x13,
    SSIncompatibility = 0x14,       FacilityNotSupported = 0x15,
    AbsentSubscriber = 0x1B,        SystemFailure = 0x22,
    DataMissing = 0x23,             UnexpectedDataValue = 0x24,
    PWRegistrationFailure = 0x25,   NegativePWCheck = 0x26,
    NumPWAttemptsViolation = 0x2B,  UnknownAlphabet = 0x47,
    USSDBusy = 0x48,                MaxMPTYParticipants = 0x7E,
    ResourcesNotAvailable = 0x7F
};

std::string_view ssErrorCodeName(SSErrorCode code);
```

### L3FacilityOpCode - TCAP Component Parser

Parses the TCAP component from raw SS Facility data (TS 24.078; GSM 04.80,
TCAP components per ITU-T X.690). The facility body is a single component
container:

```
[component tag(1)][component length(1)][component body]
```

with tags Invoke=0xA1, ReturnResult=0xA2, ReturnError=0xA3, Reject=0xA4. The
invoke component body is `[02 01 <invokeId>][02 01 <operationCode>][30 <len> {
parameters }]`, where the parameters are a sequence of `[04 <len> <data…>]`
octet-string elements (the operation arguments). The body is stored raw, so
any component form re-emits losslessly:

```cpp
class L3FacilityOpCode {
public:
    enum SSComponent : uint8_t {
        Invoke = 0xA1,    ReturnResult = 0xA2,
        ReturnError = 0xA3, Reject = 0xA4
    };

    static Expected<L3FacilityOpCode> parse(const std::string& facilityData);

    // Component builders (the length octets are computed automatically).
    static L3FacilityOpCode invoke(int8_t invokeId, SSOpCode op, std::span<const uint8_t> params);
    static L3FacilityOpCode returnResult(int8_t invokeId, std::span<const uint8_t> result = {});
    static L3FacilityOpCode returnError(int8_t invokeId, SSErrorCode err);
    static L3FacilityOpCode reject(SSErrorCode err);

    SSComponent component() const;
    int8_t invokeId() const;
    SSOpCode operationCode() const;          // Invoke components
    std::span<const uint8_t> params() const; // raw BER bytes after [30 <len>]
    bool hasErrorCode() const;
    SSErrorCode errorCode() const;           // ReturnError/Reject components
    const std::vector<uint8_t>& body() const;
    void write(BitWriter& bw) const;
    size_t lengthV() const;                  // 2 + body size
    void text(std::ostream& os) const;
};
```

| Method | Description |
|--------|-------------|
| `parse(facilityData)` | Parse the TCAP component container from raw Facility IE data (tag and length are validated against the data) |
| `component()` | Returns Invoke/ReturnResult/ReturnError/Reject |
| `invokeId()` | TCAP invoke identifier parsed from the body (0 when absent) |
| `operationCode()` | SS operation code of an invoke component |
| `params()` | Raw BER parameters following the `[30 <len>]` sequence header |
| `errorCode()` | SS error code of a return-error or reject component |
| `body()` | Component body without the tag and length octets |

**Usage:**

```cpp
// Parse a Facility message to extract the TCAP operation code.
auto msg = parseL3Hex("eb 3a 0a a1 08 02 01 01 02 01 3c 30 00");
if (msg) {
    if (auto* fac = tryGet<L3SupServFacilityMessage>(*msg)) {
        auto fc = L3FacilityOpCode::parse(fac->getMapComponents());
        if (fc) {
            // fc->component() == Invoke, fc->operationCode() == USSRequest
        }
    }
}
```

### L3USSDData - USSD Message IE

Parses USSD-specific content from SS Facility data. Handles GSM 7-bit alphabet encoding and UCS2.

```cpp
class L3USSDData {
public:
    enum Alphabet : uint8_t {
        DefaultAlphabet = 0,  ExtendedCIDAlphabet = 1,
        ShiftGSMtoUCS2 = 4,   UCS2 = 6
    };

    static Expected<L3USSDData> parse(const std::string& facilityData, SSOpCode opCode);

    int8_t invokeId() const;
    SSOpCode opCode() const;
    uint8_t dcs() const;
    Alphabet alphabet() const;
    unsigned language() const;
    const std::vector<uint8_t>& rawUssdString() const;
    bool isResult() const;
    void write(BitWriter& bw) const;
    size_t lengthV() const;
    void text(std::ostream& os) const;

    std::string decodeUssdString() const;
    static std::vector<uint8_t> encodeUssdString(const std::string& text);
};
```

| Method | Description |
|--------|-------------|
| `parse(facilityData, opCode)` | Parse USSD from TCAP parameter bytes |
| `invokeId()` | TCAP invoke ID |
| `opCode()` | USSD op code (USSRequest, USSNotify, ProcessUSSData, etc.) |
| `dcs()` | Data Coding Scheme (GSM 02.90 §4.1.1) |
| `alphabet()` | Alphabet type from DCS low nibble |
| `language()` | Language indicator from DCS high nibble |
| `rawUssdString()` | Raw GSM 7-bit or UCS2 encoded bytes |
| `isResult()` | True for USS-Notify (network response) |
| `decodeUssdString()` | Decode to human-readable string |
| `encodeUssdString(text)` | Encode text to GSM 7-bit packed bytes |

**Usage:**

```cpp
// Encode a USSD string
auto encoded = L3USSDData::encodeUssdString("*#100#");

// Parse USSD from Facility data
auto ussd = L3USSDData::parse(facilityBytes, SSOpCode::USSRequest);
if (ussd) {
    std::string text = ussd->decodeUssdString();  // e.g. "*#100#"
}
```

**GSM 7-bit encoding:** The encoder packs characters into 7-bit frames per GSM 03.38, producing compact byte sequences suitable for USSD transport over the SS Facility IE.

---

## 25. GPRS Mobility Management Messages

**File:** `gsml3parser/gmm/l3gmmmessages.h` - 23 message types in the `GMM` variant.
**Spec:** 3GPP TS 44.068 section 9.5, Table 10.4a.
**PD:** `0x08` (GPRSMobilityManagement).

### GMM Information Elements

**File:** `gsml3parser/gmm/l3gmmelements.h`

| IE | IEI | Format | Description |
|----|-----|--------|-------------|
| `L3PDPContextStatus` | 0x32 | TLV | PDP context activation bitmap (16 contexts) |
| `L3T3302Timer` | 0x1b | TLV | T3302 timer value (GPRS Timer 2 encoding) |
| `L3MSNetworkCapability` | - | V | MS network capability bit string |
| `L3RoutingAreaIdentification` | - | V | MCC/MNC BCD(3) + LAC(2) + RAC(1) = 6 octets |
| `L3DRXParameter` | - | V | DRX parameter: split PG cycle code + DRX cycle length/timer, two value octets without an identifier (TS 44.068 section 9.5) |
| `L3GMMCKSN` | - | bit-field | Ciphering key sequence number (3 bits) |
| `L3GMMCauseIE` | - | V | GMM cause value octet without an identifier; the first body octet of reject, failure and status messages (TS 44.068 section 9.5) |
| `L3AuthRAND` | 0x21 | TV | 128-bit authentication challenge (value-only class; the IEI octet is written by the message) |
| `L3AuthRES` | 0x22 | TV | 32-bit authentication response (value-only class; the IEI octet is written by the message) |
| `L3AuthFailureParam` | 0x30 | TLV | AUTS failure parameter (variable) |
| `L3PTMSISignature` | 0x19 | TV | P-TMSI signature (3 value octets; the IEI octet is written by the message) |
| `L3GMMStatusCause` | - | V | GMM status cause octet |

### GMM Enums

| Enum | Values | Description |
|------|--------|-------------|
| `GMMCause` | 27 codes | GMM cause values (ReqAccepted, GprsNotAllowed, PLMN_Not_Allowed, MAC_Failure, etc.) |
| `GMMAttachType` | 2 values | GPRSAttach, CombinedGPRSAndIMSIAttach |
| `GMMUpdateType` | 4 values | RAUpdated, CombinedRALAUpdated, CombinedRALAWithImsiAttach, PeriodicUpdating |
| `GMMDetachTypeMO` | 3 values | GPRS, IMSI, CombinedGPRSIMSI (MS-originated) |
| `GMMDetachTypeMT` | 3 values | ReattachRequired, ReattachNotRequired, IMSIDetach (MT-originated) |
| `GMMPTMSIType` | 2 values | Native, Mapped |

### GMM Messages

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3AttachRequest` | 0x01 | UL | MS network capability (LV), attach type + forL3 + GPRS CKSN (one octet), DRX parameter (V, two octets), mobile identity (LV), old RAI (V, six octets), MS radio access capability (LV) |
| `L3AttachAccept` | 0x02 | DL | Leading part of three octets — first octet [attachResult(3)\|spare(1)\|forceToStandby(1)\|updateTimer(2)\|radioPriority(1)] plus two raw leading octets — RAI (V, six octets) [+ P-TMSI signature (TV, IEI 0x19, three octets)] [+ P-TMSI (TLV 0x18)]; additional IEs kept opaque |
| `L3AttachComplete` | 0x03 | UL | Empty body |
| `L3AttachReject` | 0x04 | DL | GMM cause (value octet); optional IEs kept opaque |
| `L3DetachRequest` | 0x05 | Bidir | First octet: detach type in the three low bits + power-off flag (MO, bit 3) or force-to-standby (MT, bit 4); [P-TMSI (TLV 0x18)], [cause (TV, IEI 0x25)] |
| `L3DetachAccept` | 0x06 | Bidir | Force-to-standby flag |
| `L3RoutingAreaUpdateRequest` | 0x08 | UL | Update type + forL3 + GPRS CKSN (one octet), old RAI (V, six octets), MS radio access capability (LV) |
| `L3RoutingAreaUpdateAccept` | 0x09 | DL | Leading part of two octets — first octet [forceToStandby(1)\|updateResult(3)\|raUpdateTimer(2)\|spare(2)] (no radio-priority field) plus one raw leading octet — RAI (V, six octets) [+ P-TMSI signature (TV, IEI 0x19, three octets)] [+ P-TMSI (TLV 0x18)]; additional IEs kept opaque |
| `L3RoutingAreaUpdateComplete` | 0x0a | UL | Empty body |
| `L3RoutingAreaUpdateReject` | 0x0b | DL | GMM cause (value octet); optional IEs kept opaque |
| `L3ServiceRequest` | 0x0c | UL | One octet: GPRS CKSN(3)\|spare(1) low half-octet, service type(3)\|spare(1) high half-octet; then P-TMSI (LV) |
| `L3ServiceAccept` | 0x0d | DL | [PDP context status] |
| `L3ServiceReject` | 0x0e | DL | GMM cause, [T3346 timer] |
| `L3P_TMSIReallocationCommand` | 0x10 | DL | First octet [PTMSI_Type(1)\|spare(3)\|forceToStandby(1)\|spare(4)], RAI (V, six octets), [allocated P-TMSI (TLV 0x18)]; additional IEs kept opaque |
| `L3P_TMSIReallocationComplete` | 0x11 | UL | Empty body |
| `L3AuthenticationAndCipheringRequest` | 0x12 | DL | First octet [ciphering algorithm(3)\|spare(1)\|IMEISV request(1)\|force to standby(1)\|spare(2)], second octet [AC reference number(4)\|spare(4)], RAND (TV, IEI 0x21, sixteen value octets) |
| `L3AuthenticationAndCipheringResponse` | 0x13 | UL | First octet [AC reference number(4)\|spare(4)], RES (TV, IEI 0x22, four value octets) |
| `L3AuthenticationAndCipheringReject` | 0x14 | DL | Empty body |
| `L3GMMIdentityRequest` | 0x15 | DL | One octet [spare(5)\|identityType(3)] |
| `L3GMMIdentityResponse` | 0x16 | UL | Mobile identity |
| `L3AuthenticationAndCipheringFailure` | 0x1c | UL | GMM cause, AUTS failure parameter |
| `L3GMMStatus` | 0x20 | Bidir | GMM cause |
| `L3GMMInformation` | 0x21 | DL | Network information |

---

## 26. GPRS Session Management Messages

**File:** `gsml3parser/sm/l3smmessages.h` - 24 message types in the `SM` variant.
**Spec:** 3GPP TS 44.068 section 9.5, Table 10.4a.
**PD:** `0x0a` (GPRSSessionManagement).

### SM Information Elements

**File:** `gsml3parser/sm/l3smelements.h`

| IE | IEI | Format | Description |
|----|-----|--------|-------------|
| `L3PDPAddress` | - | LV/TLV | PDP type-and-address: value = [PDP type number(1)][address length(1)][address] — 4 = IETF IPv4, 6 = IETF IPv6; positional in the activate request, TLV length equals the whole value size (six for IPv4) |
| `L3QoS` | - | LV | QoS profile: type + up to 18 element types; positional length octet, no identifier |
| `L3AccessPointName` | 0x28 | TLV | APN string (UTF-8 encoded) |
| `L3ProtocolConfigOptions` | 0x27 | TLV | Protocol config options (e.g. IPCP=0xC029 for IPv4) |
| `L3SMCauseIE` | - | V | SM cause value octet without an identifier; the first body octet of reject, failure and status messages (TS 44.068 section 9.5) |
| `L3BackOffTimer` | - | TV | Back-off timer; not modelled as a typed body field — kept in the message's opaque additional-IE sequence |
| `L3PDPHandle` | - | bit-field | PDP context identifier (4 bits, 0–15) |
| `L3TearDownIndicator` | 0x09 | TV | Tear-down indicator: identifier nibble '1001'B + flag + spare bits (TS 44.068 section 10.5.6.10) |

The request type (TS 44.068 section 10.5.6.17) is carried in one octet: the high nibble
'1010'B identifies the IE and the low nibble holds the value; typed accessors
`hasRequestType()`/`requestType()` consume it on the activate request.
| `L3TMGI` | 0x42 | TLV | Temporary Mobile Group Identity: PLMN(3) + ServiceID(2) + SessionID(1) |

### SM Enums

| Enum | Values | Description |
|------|--------|-------------|
| `PDPType` | 3 values | IPv4 = 4, IPv6 = 6, Unknown = 0xFF (sentinel) |
| `QoSType` | 3 values | Requested, Default, Teardown |
| `QoSElementType` | 18 values | QoSClass, MaxBitRate UL/DL, Delay, DeliveryOrder, SopClass, ResidualErrorRate, PeakThroughput, MeanThroughput, TrafficClass, GuaranteedBitRate, SRB rate, GPRS/External Priority |
| `SMCause` | 18 values | SM cause values (ReqAccepted, Unsupported_PDP_Address_Type, Service_Opcode_NotSupported, Multicast_Context_Ack/Reject/Deactivate, Invalid_Flow_Desc, Multicast_PDP_No_Bearer, PDP_Auth_Failed_Primary/Secondary_PDN, plus the common protocol-error codes 95–111) |

### SM Messages - Primary PDP Context

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3ActivatePDPContextRequest` | 0x41 | UL | NSAPI and LLC SAPI (two octets: [NSAPI(4)|spare(4)][LLC SAPI(4)|spare(4)]), requested QoS (LV), requested PDP address (LV), APN (TLV 0x28), [PCO (TLV 0x27)], [request type (0xAx)] |
| `L3ActivatePDPContextAccept` | 0x42 | DL | PDP handle, [PDP address], QoS, [PCO] |
| `L3ActivatePDPContextReject` | 0x43 | DL | SM cause (value octet); optional IEs kept opaque |
| `L3DeactivatePDPContextRequest` | 0x46 | Bidir | SM cause (value octet), [tear-down indicator (TV 0x09)], [PCO (TLV 0x27)] |
| `L3DeactivatePDPContextAccept` | 0x47 | Bidir | PDP handle |
| `L3ModifyPDPContextRequest` | 0x48 | DL | PDP handle, QoS, [PCO] |
| `L3ModifyPDPContextAccept` | 0x49 | UL | PDP handle, QoS, [PCO] |
| `L3ModifyPDPContextReject` | 0x4c | Bidir | PDP handle, SM cause, [Back-off timer] |
| `L3SMStatus` | 0x55 | Bidir | SM cause |

### SM Messages - Request PDP Context Activation (Net-initiated)

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3RequestPDPContextActivation` | 0x44 | DL | PDP handle, [PDP address], APN, QoS, [PCO] |
| `L3RequestPDPContextActivationReject` | 0x45 | UL | PDP handle, SM cause |

### SM Messages - Bidirectional Modify (MS-initiated variants)

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3ModifyPDPContextRequestMS` | 0x4A | UL | PDP handle, QoS, [PCO] |
| `L3ModifyPDPContextAcceptNet` | 0x4B | DL | PDP handle, QoS, [PCO] |

### SM Messages - Secondary PDP Context

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3ActivateSecondaryPDPContextRequest` | 0x4D | DL | PDP handle, [PDP address], APN, QoS, [PCO] |
| `L3ActivateSecondaryPDPContextAccept` | 0x4E | UL | PDP handle, [PDP address], QoS, [PCO] |
| `L3ActivateSecondaryPDPContextReject` | 0x4F | UL | PDP handle, SM cause |

### SM Messages - MBMS Context

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3ActivateMBMSContextRequest` | 0x56 | UL | TMGI, QoS, [PCO] |
| `L3ActivateMBMSContextAccept` | 0x57 | DL | PDP handle, QoS, [PCO] |
| `L3ActivateMBMSContextReject` | 0x58 | DL | SM cause |
| `L3RequestMBMSContextActivation` | 0x59 | DL | TMGI, QoS, [PCO] |
| `L3RequestMBMSContextActivationReject` | 0x5A | UL | SM cause |

### SM Messages - Network-Initiated Secondary & Notification

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3RequestSecondaryPDPContextActivation` | 0x5B | DL | PDP handle, [PDP address], APN, QoS, [PCO] |
| `L3RequestSecondaryPDPContextActivationReject` | 0x5C | UL | PDP handle, SM cause |
| `L3SMNotification` | 0x5D | DL | PDP handle |

---

## 27. SMS Messages

**File:** `gsml3parser/sms/l3smsmessages.h` - 5 CP messages in the `SMS` variant; `gsml3parser/sms/l3smselements.h` - RP and TP types.
**Spec:** 3GPP TS 24.011 sections 7-8, 3GPP TS 23.040 (CP/RP/TP layers); 3GPP TS 24.008 Table 10.6a (SMS control part).
**PD:** `0x09` (SMS).

The SMS layer uses a three-level encapsulation: L3 header -> CP message -> RP message -> TP PDU. Only CP-DATA/CP-ACK/CP-ERROR/CP-STATUS/CP-SUBMIT are defined for the SMS PD (TS 24.011); other MTI values are not assigned.

### CP Cause Codes

| Code | Meaning |
|------|---------|
| `Unspecified` | Unspecified error |
| `CpusNotSupported` | CUPS not supported |
| `NoRPLPDU` | No RPLPDU present |
| `UnknownRPMessageType` | Unknown RP message type |
| `InvalidRPMessageReference` | Invalid message reference |
| `RPUserBusy` | RP user busy |
| `UnknownRPOriginatorAddress` | Unknown originator |
| `UnknownRPDestinationAddress` | Unknown destination |
| `RPLinkNotAvailable` | RP link not available |
| `NoRPResponse` | No RP response |

### Control Part (CP) Messages

| Message | CP-MTI | Direction | Description |
|---------|--------|-----------|-------------|
| `L3CPData` | 0x01 | Bidir | Length + RPDU (wraps relay or TP layer) |
| `L3CPAck` | 0x04 | Bidir | Acknowledgement, no body |
| `L3CPErr` | 0x10 | Bidir | CP cause value (7-bit + extension bit) |
| `L3CPStatus` | 0x12 | MT | TP-OI, MTI type, [message reference] |
| `L3CPSMT` | 0x13 | MT | Length + RPDU (Short Message to Telephony) |

### Relay Part (RP) Messages

| Message | RP-MTI (MO/MT) | Description |
|---------|----------------|-------------|
| `L3RPData` | 0 / 1 | Relay data: [originator addr], [destination addr], user data |
| `L3RPAck` | 2 / 3 | Relay acknowledgement: message reference |
| `L3RPError` | 4 / 5 | Relay error: message reference + cause |
| `L3RPSMMA` | 6 / 7 | Short message memory available |

### Transport Part (TP) Elements

**File:** `gsml3parser/sms/l3smselements.h`

The first TP-DU header octet packs (bit positions in the octet value, TS 23.040 §9.1.2)
`TP-MTI(2)|MMS/RD(1)|VPF(2)|SRI/SRR(1)|UDHI(1)|RP(1)`; the TP user data length counts septets for the
GSM 7-bit alphabet and octets otherwise.

| Type | TP-MTI | Description |
|------|--------|-------------|
| `L3TPDeliver` | 0x00 | MT delivery: MMS, SRI, UDHI, RP flags, OA, PID, DCS, [SCTS], UDL, user data |
| `L3TPSubmit` | 0x01 | MO submission: RD, VPF, SRR, UDHI, RP flags, MR, DA, PID, DCS, [validity period — one (VPF=1), seven (VPF=2) or ten (VPF=3) octets, preserved verbatim], UDL, user data |
| `L3TPStatusReport` | 0x02 | Status report (wire MTI '10'B in the network→mobile direction): MR, DA, PID, DCS, SCTS, STS |
| `L3TPCommand` | 0x02 | Command (same wire MTI '10'B in the mobile→network direction): MR, PID, DCS, CMD, [address] |

### TP Enums

| Enum | Values | Description |
|------|--------|-------------|
| `TPDCS` | 3 values | Default_Alphabet (0x00, GSM 7-bit), Default_8bit (0x04), UCS2 (0x08) — full DCS octets; any octet is representable and is interpreted by `decodeSmsDcs()` (TS 23.040: alphabet, compression flag, message class) |
| `TPPID` | 23 values | GSM 03.40 protocol identifiers: Default, GSM, X121, Telex, LandLine, SS7_DestinationAccess, TeX_Page, Packet_Switched_64k, TeX_Information, Packet_Switched_1200, SS7_Telephone_User, SS7_Telelex_User, SS7_Direct_Connection, SS7_MAP, SNA, X400_FTAM, Telematic_Application, SCF_Access, H323_Video, Internet_ST_FIP, CAP, SS7_SCCP, X25_Packet_Switched |

### TP Information Elements

| IE | Description |
|----|-------------|
| `L3TPAddress` | TP-DA/TP-OA: length octet = number of digits, then the TON/NPI octet and packed BCD digits (first digit in the low nibble of the first digit octet, 'F'-filled when odd) |
| `TPSCTimeStamp` | Service centre time stamp: year, month, day, hour, minute, second, timezone (7 octets) |

### GSM 7-bit Alphabet Robustness

`decodeGSMChar()` (in `gsml3parser/gsm_common.h`) maps a 7-bit code point into the GSM 7-bit default
alphabet: a 127-code-point table mapped to ISO-8859-1 (TS 23.038). Digits occupy code points 47–56,
uppercase 64–89, lowercase 96–121; accented characters fill 122–126. Code points at or beyond the
default range are mapped to the space character per the robustness policy. `encodeGSMChar()` scans the
same table for the code point of a given ISO-8859-1 character and falls back to space when absent. The
RACH transmission-parameter tables (`RACHSpreadSlots`, `RACHWaitSParam`, `RACHWaitSParamCombined` in
`gsml3parser/gsm_common.h`) are indexed by the broadcast Tx integer (0–15) per TS 44.018 section 10.5.2.29.

---

## 28. Broadcast Call Control Messages

**File:** `gsml3parser/bcc/l3bccmessages.h` - 8 message types in the `BCCM` variant.
**Spec:** 3GPP TS 44.018 sections 9.6, Table 10.4.3.
**PD:** `0x01` (BroadcastCallControl).

L3 header encoding matches CC: Byte 0 = `(TI << 5) | (TIF << 4) | PD` with the PD in the low nibble (TS 24.007 Table 11.3). Byte 1 carries the 6-bit messageType in its low bits, plus the 2-bit NSD in the high bits.

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3BCCSetup` | 0x00 | MO | Broadcast call setup with TI + opaque body |
| `L3BCCProceeding` | 0x01 | MT | Network proceeding indication |
| `L3BCCCallConfirmed` | 0x04 | MT | Call confirmed |
| `L3BCCConnect` | 0x05 | MT | Broadcast call connected |
| `L3BCCDisconnect` | 0x06 | MO | Broadcast call disconnect |
| `L3BCCRelease` | 0x07 | MT | Broadcast call release |
| `L3BCCConnectAcknowledge` | 0x09 | Bidir | Connect acknowledged |
| `L3BCCReleaseComplete` | 0x0a | Bidir | Release complete |

Each message stores the body as an opaque octet sequence for basic infrastructure parsing. No normative
reference templates exist for this block, so parsing is best-effort and bit-level conformance is not
claimed. The `ti()` accessor returns the Transaction Identifier.

---

## 29. Group Call Control Messages

**File:** `gsml3parser/gcc/l3gccmessages.h` - 8 message types in the `GCCM` variant.
**Spec:** 3GPP TS 44.018 sections 9.7, Table 10.4.4.
**PD:** `0x00` (GroupCallControl).

L3 header encoding matches CC: Byte 0 = `(TI << 5) | (TIF << 4) | PD` with the PD in the low nibble (TS 24.007 Table 11.3). Byte 1 carries the 6-bit messageType in its low bits, plus the 2-bit NSD in the high bits.

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3GCCSetup` | 0x00 | MO | Group call setup with TI + opaque body |
| `L3GCCProceeding` | 0x01 | MT | Network proceeding indication |
| `L3GCCAcknowledge` | 0x02 | MT | Group call acknowledgement |
| `L3GCCCallConfirmed` | 0x03 | MT | Call confirmed |
| `L3GCCConnect` | 0x05 | MT | Group call connected |
| `L3GCCDisconnect` | 0x06 | MO | Group call disconnect |
| `L3GCCRelease` | 0x07 | MT | Group call release |
| `L3GCCReleaseComplete` | 0x0a | Bidir | Release complete |

Each message stores the body as an opaque octet sequence for basic infrastructure parsing. No normative
reference templates exist for this block, so parsing is best-effort and bit-level conformance is not
claimed. The `ti()` accessor returns the Transaction Identifier.

---

## 30. Location Services Messages

**File:** `gsml3parser/ls/l3lsmessages.h` - 2 message types in the `LSM` variant.
**Spec:** 3GPP TS 44.031 / TS 24.027 / TS 24.028.
**PD:** `0x0c` (Location).

Location Services messages carry mobile location service parameters between the MS and the network. Both message types store their body as a raw octet sequence, with parse/write handling the L3 header dispatch. No normative reference templates exist for this block, so parsing is best-effort and bit-level conformance is not claimed.

| Message | MTI | Direction | Description |
|---------|-----|-----------|-------------|
| `L3LocationServiceRequest` | 0x01 | Bidir | Location service request parameters (raw body) |
| `L3LocationServiceProviderMessage` | 0x02 | Bidir | Location service provider data (raw body) |

---

## 31. Packet Domain Supplementary Services (PDSS) Messages

**Files:** `gsml3parser/pdss1/l3pdss1messages.h` - 1 passthrough type in the `PDSS1M` variant;
`gsml3parser/extended/l3extendedmessages.h` - 1 passthrough type in the `EXTENDED` variant.
**Spec:** GSM 04.08 §10.2 (TS 24.007 Table 11.3).
**PDs:** `0x0d` (PacketDomainSupplementaryServices1), `0x0e` (PacketDomainSupplementaryServices2).

Both packet-domain supplementary service discriminators are valid pass-through domains: the classes
capture the raw MTI from the L3 header and store the remaining body as an opaque octet sequence, so
messages of these PDs parse without error and re-emit losslessly. `L3PDSS1Message` serves PD=0x0d and
`L3ExtendedMessage` serves PD=0x0e (the class/file names keep the historical "extended" spelling).

| Method | Description |
|--------|-------------|
| `mti()` | Returns the parsed MTI value |
| `pd()` | Returns `L3PD::PacketDomainSupplementaryServices1` / `...Services2` respectively |
| `body()` | Raw body bytes |
| `parse(br, parsedMti)` | Static factory; takes pre-parsed MTI |
| `write(bw)` | Serializes body octets |
| `text(os)` | Human-readable dump of MTI and body |

---

## 32. Test Procedure PD Messages

**File:** `gsml3parser/testproc/l3testproceduremessages.h` - 1 placeholder type in the `TESTPROC` variant.
**Spec:** GSM 04.08 §10.2.
**PD:** `0x0f` (TestProcedure).

The Test Procedure PD provides infrastructure for test procedure messages used in network testing scenarios. The `L3TestProcedureMessage` class captures the raw MTI from the L3 header and stores the remaining body as an opaque octet sequence, allowing forward-compatible parsing of test procedure messages.

| Method | Description |
|--------|-------------|
| `mti()` | Returns the parsed MTI value |
| `pd()` | Returns `L3PD::TestProcedure` |
| `body()` | Raw body bytes |
| `parse(br, parsedMti)` | Static factory; takes pre-parsed MTI |
| `write(bw)` | Serializes body octets |
| `text(os)` | Human-readable dump of MTI and body |

---

## 33. MSContext - Per-Subscriber State

MSContext aggregates all state associated with a single mobile station: identity (TMSI/IMSI), channel assignment, classmark, location area, and protocol-layer flags (ciphering, registration, authentication). This is the primary object through which a BTS tracks each subscriber.

**Header:** `#include <gsml3parser/stack/ms_context.h>`

### Performance Characteristics

| Property | Value |
|----------|-------|
| `sizeof(MSContext)` | ≤ 256 bytes (enforced by `static_assert`) |
| Heap allocations | **Zero** - all fields stored inline |
| Hot path methods | O(1), no virtual dispatch, no heap |
| Thread safety | NOT thread-safe. One instance per MS, single-thread access |

Fields are ordered by access frequency: hot fields (identity, channel, flags) first, cold fields (LAI, classmark) last. This layout minimizes cache line misses for the typical message processing path.

### Factory Methods

| Method | Description |
|--------|-------------|
| `MSContext::createWithTMSI(uint32_t tmsi)` | Create context with TMSI identity |
| `MSContext::createWithIMSI(std::string_view imsiDigits)` | Create context with IMSI identity |

### Identity API

| Method | Description |
|--------|-------------|
| `identity()` | Returns `const L3MobileIdentity&` - current primary identity |
| `setTMSI(uint32_t tmsi)` | Update or set TMSI |
| `setIMSI(std::string_view digits)` | Update or set IMSI |

### Channel Assignment API

| Method | Description |
|--------|-------------|
| `channelType()` | Returns current `ChannelType` (or `UndefinedCHType`) |
| `assignChannel(type, trx, ts, arfcn)` | Assign a logical channel with physical parameters |
| `releaseChannel()` | Release channel, resets to `UndefinedCHType` |
| `trxNumber()` | Returns transceiver index |
| `timeslot()` | Returns TDMA timeslot number |
| `arfcn()` | Returns ARFCN value |

### State Flags API

| Method | Description |
|--------|-------------|
| `isCiphered()` / `setCiphered(bool)` | Ciphering active state |
| `isRegistered()` / `setRegistered(bool)` | Location update completed |
| `isAuthenticated()` / `setAuthenticated(bool)` | Authentication performed |
| `timingAdvance()` / `setTimingAdvance(uint8_t)` | Timing advance value (0-63) |
| `classmark()` / `setClassmark(cm)` | MS Classmark 1 storage |
| `lai()` / `setLAI(lai)` | Location Area Identity storage |

### Example

```cpp
#include <gsml3parser/stack/ms_context.h>

using namespace gsml3parser;

// Create context for a known MS
auto ctx = MSContext::createWithTMSI(0x12345678u);

// Assign SDCCH channel after RACH handling
ctx.assignChannel(ChannelType::SDCCHType, /*trx=*/0, /*ts=*/0, /*arfcn=*/125);

// After authentication procedure completes
ctx.setAuthenticated(true);
ctx.setCiphered(true);

// Store classmark received in CM Service Request
L3MobileStationClassmark1 cm;
ctx.setClassmark(cm);

// After location update
L3LocationAreaIdentity lai("262", "42", 1234);
ctx.setLAI(lai);
ctx.setRegistered(true);
```

---

## 34. Timer Framework

The timer framework provides GSM Layer 3 protocol timers as defined in 3GPP TS 24.008 and TS 44.018. It includes timer identifiers, a single-timer class, and a manager that tracks up to 32 concurrent timers per MS using fixed-size arrays (zero heap allocation).

**Header:** `#include <gsml3parser/stack/l3_timer.h>`

### L3TimerId Enumerations

| Timer ID | Default Duration | Description | Spec Reference |
|----------|-----------------|-------------|----------------|
| `T3101` | 3000ms | CM service request retransmission | 3GPP TS 24.008 10.5.4 |
| `T3102` | 3000ms | Identity response retransmission | 3GPP TS 24.008 10.5.6 |
| `T3103` | 5000ms | Location updating request retransmission | 3GPP TS 24.008 10.5.12 |
| `T3106` | 3000ms | Authentication response retransmission | 3GPP TS 24.008 10.5.18 |
| `T3108` | 3000ms | TMSI reallocation complete retransmission | 3GPP TS 24.008 10.5.23 |
| `T3109` | 30000ms | Paging response retransmission (etom × 5s) | 3GPP TS 24.008 10.5.26 |
| `T3111` | 3000ms | CM reestablishment request retransmission | 3GPP TS 24.008 10.5.34 |
| `T3112` | 3000ms | IMSI detach indication retransmission | 3GPP TS 24.008 10.5.36 |
| `T3113` | 3000ms | MM status retransmission | 3GPP TS 24.008 10.5.38 |
| `T3310` | 5000ms | GPRS attach request retransmission | 3GPP TS 24.008 10.5.76 |
| `T3311` | 30000ms | Routing area update retransmission (etor × 5s) | 3GPP TS 24.008 10.5.78 |
| `T3312` | 3000ms | P-TMSI reallocation complete retransmission | 3GPP TS 24.008 10.5.80 |
| `T3314` | 3000ms | GPRS service request retransmission | 3GPP TS 24.008 10.5.84 |
| `T3315` | 3000ms | Authentication and ciphering resp retransmission | 3GPP TS 24.008 10.5.86 |
| `T3320` | 3000ms | Activate PDP context request retransmission | 3GPP TS 24.008 10.5.96 |
| `T3321` | 3000ms | Deactivate PDP context request retransmission | 3GPP TS 24.008 10.5.98 |
| `T3322` | 3000ms | Modify PDP context request retransmission | 3GPP TS 24.008 10.5.100 |
| `T3334` | 3000ms | GMM status retransmission | 3GPP TS 24.008 10.5.112 |
| `T3395` | 3000ms | Packet reservation request retransmission | 3GPP TS 24.008 10.5.130 |

### Free Functions

| Function | Description |
|----------|-------------|
| `l3TimerDefault(L3TimerId)` | Returns the default duration for a timer ID (O(1) lookup) |
| `l3TimerName(L3TimerId)` | Returns human-readable timer name (e.g. "T3101") |

### L3Timer Class

Single timer instance with start/stop/expired semantics.

| Method | Description |
|--------|-------------|
| `L3Timer(id)` | Construct with default expiry from spec |
| `L3Timer(id, expiry)` | Construct with custom expiry duration |
| `start()` | Start or restart the timer; returns true if first start |
| `stop()` | Stop the timer without firing |
| `tick(delta)` | Advance by delta; returns true if expired |
| `isRunning()` | Returns true if timer is currently running |
| `remaining()` | Returns remaining time (zero if not running) |
| `id()` | Returns the timer's L3TimerId |
| `expiry()` | Returns the configured expiry duration |
| `reconfigure(id, expiry)` | Stop and re-arm with a new timer ID / expiry (no heap allocation) |

### TimerManager Class

Manages up to 32 named timers for one MS context using fixed-size arrays.

| Method | Description |
|--------|-------------|
| `start(id)` | Start timer with default expiry; returns true if first start |
| `start(id, expiry)` | Start timer with custom expiry |
| `stop(id)` | Stop a specific timer |
| `stopAll()` | Stop all running timers |
| `tick(delta, callback)` | Advance all timers; invoke callback for each expired (zero allocation) |
| `tick(delta, span)` | Advance all timers; fill pre-allocated span with expired IDs |
| `isRunning(id)` | Check if a specific timer is running |
| `remaining(id)` | Get remaining time for a specific timer |
| `get(id)` | Get the L3Timer object for direct access |
| `runningCount()` | Number of currently running timers |
| `setOwner(void*)` | Set the owning object reported to the active-change observer |
| `setOnActiveChange(fn, ctx)` | Register a zero-alloc observer fired on 0->>0 / >0->0 running-timer transitions |

### Performance Characteristics

| Metric | Value |
|--------|-------|
| Memory footprint | `sizeof(TimerManager)` = 1,080 bytes on 64-bit (32 × 32-byte `L3Timer` slots + per-slot init flags + owner/observer words) |
| Heap allocations | **Zero** - all storage is `std::array`; observer is a plain fn pointer + context |
| `tick()` complexity | O(32) = constant, iterates fixed array |
| `start()` / `stop()` | O(1) - direct index into array (plus O(32) running-count check for active-change detection) |
| Thread safety | NOT thread-safe. One instance per MS, single-thread access |

### Example

```cpp
#include <gsml3parser/stack/l3_timer.h>

using namespace gsml3parser;

// --- Callback-based tick (no heap allocation) ---
TimerManager tm;
tm.start(L3TimerId::T3101);  // CM service request, default 3s
tm.start(L3TimerId::T3106, 5000ms); // custom expiry

// In event loop, advance time:
tm.tick(std::chrono::milliseconds(100), [](L3TimerId expiredId) {
    // Handle timer expiry - retransmit or abort procedure
    handleExpired(expiredId);
});

// --- Span-based tick (caller provides buffer) ---
std::array<L3TimerId, 32> expired;
size_t n = tm.tick(std::chrono::milliseconds(500), expired);
for (size_t i = 0; i < n; ++i) {
    handleExpired(expired[i]);
}

// Check individual timer state
if (tm.isRunning(L3TimerId::T3101)) {
    auto remaining = tm.remaining(L3TimerId::T3101);
    // ...
}
```

---

## 35. Transaction Framework

The transaction framework provides request-response correlation for L3 messaging. It tracks outgoing requests and matches incoming responses using either TI (Transaction Identifier) for CC/SS protocols or PD+MTI for other protocol discriminators.

### Overview

| Component | Description |
|-----------|-------------|
| `Transaction` | Single transaction metadata: PD, MTI, TI, timer ID, state |
| `TransactionManager` | Manages up to 16 concurrent transactions per MS |
| `TransactionState` | Pending, Completed, Expired, Cancelled |

### Matching Semantics

| Protocol Discriminator | Matching Strategy | Complexity |
|------------------------|-------------------|------------|
| `CallControl` (PD=0x03) | TI-based lookup via `mTiIndex[8]` | O(1) |
| `NonCallSS` (PD=0x0b) | TI-based lookup via `mTiIndex[8]` | O(1) |
| All other PDs | PD + MTI comparison | O(K), K at most 16 |

### API Reference

#### TransactionState

```cpp
enum class TransactionState : uint8_t {
    Pending,      // Waiting for response
    Completed,    // Response received successfully
    Expired,      // Timer expired, no response
    Cancelled     // Manually cancelled
};
```

#### Transaction

```cpp
class Transaction {
public:
    Transaction(L3PD pd, int mti, uint8_t ti, L3TimerId timerId);

    L3PD requestPD() const noexcept;
    int requestMTI() const noexcept;
    uint8_t ti() const noexcept;
    L3TimerId timerId() const noexcept;
    TransactionState state() const noexcept;

    void complete() noexcept;
    void expire() noexcept;
    void cancel() noexcept;

    // Match with TI (for CC/SS protocols)
    bool matches(const ParsedMessage& msg, uint8_t ti) const;

    // Match without TI (for non-CC/SS protocols)
    bool matches(const ParsedMessage& msg) const;

    std::chrono::steady_clock::time_point createdAt() const noexcept;
};
```

#### TransactionManager

```cpp
class TransactionManager {
public:
    TransactionManager() = default;

    // Create a new pending transaction. Returns unique ID or nullopt if full.
    std::optional<uint32_t> create(L3PD pd, int mti, uint8_t ti, L3TimerId timerId);

    // Get transaction by ID. Returns nullptr if not found or not pending.
    Transaction* get(uint32_t id) noexcept;

    // Match with L3 header (full TI support for CC/SS).
    Transaction* match(const L3Header& header, const ParsedMessage& msg);

    // Match without header (PD+MTI scan only).
    Transaction* match(const ParsedMessage& msg);

    // Expire all pending transactions with the given timer ID.
    void onTimerExpired(L3TimerId timerId) noexcept;

    // Remove finished transactions. Returns count removed.
    size_t cleanup() noexcept;

    size_t pendingCount() const noexcept;
    size_t totalCount() const noexcept;
};
```

### Usage Example

```cpp
#include <gsml3parser/stack/transaction.h>

TransactionManager tm;

// BTS sends Setup, expects Connect
auto txId = tm.create(L3PD::CallControl, L3Setup::MTI, /*ti=*/1, L3TimerId::T3101);
// Start timer T3101...

// Later: response arrives
auto header = parseL3Header(incomingBytes).value();
auto msg = parseL3(incomingBytes.subspan(2)).value();

Transaction* tx = tm.match(header, msg);
if (tx) {
    // Correlated with our Setup request!
    tx->complete();
    // Stop timer T3101...
}

// Timer expiry handler:
tm.onTimerExpired(L3TimerId::T3101);
tm.cleanup();
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| `sizeof(Transaction)` | <= 48 bytes |
| Max concurrent transactions | 16 per MS |
| CC/SS match() complexity | O(1) via TI index |
| Non-CC/SS match() complexity | O(K), K at most 16 (MAX_TRANSACTIONS) |
| Heap allocations | None (std::array storage) |
| Thread safety | NOT thread-safe; one instance per MS |

---

## 36. Protocol State Machines

**File:** `gsml3parser/stack/state_machine.h` - FSM base class and RR/MM/CC skeleton implementations.
**Spec:** 3GPP TS 24.008 Chapters 4-6 (RR, MM, CC procedures).

The state machine framework provides a base class for protocol state machines with message and timer event processing, plus concrete skeleton implementations for the three main GSM Layer 3 sublayers: Radio Resource (RR), Mobility Management (MM), and Call Control (CC).

### SMAction - State Machine Actions

| Action | Description |
|--------|-------------|
| `None` | Stay in current state, no side effect |
| `Transition` | Move to the next state specified by `nextState` |
| `SendResponse` | Transition and signal that a response message should be built externally |
| `Reject` | Signal that a reject/status message should be sent; stay in current state |
| `ReleaseChannel` | Signal that the logical channel should be released |
| `PushSubstate` | Push a sub-state machine onto the stack (for nested procedures) |
| `PopSubstate` | Pop back to the parent state machine |

### SMResult - Processing Result

The `SMResult` struct is returned from every `processMessage()` and `processTimer()` call:

```cpp
struct SMResult {
    SMAction action{SMAction::None};
    std::optional<int> nextState;
    bool causesTransition() const noexcept;
};
```

**Important:** `SMResult` does NOT contain `ParsedMessage`. The FSM returns action + next state; the caller builds response messages externally via Builder API. `sizeof(SMResult) <= 16 bytes`.

### ProtocolStateMachine - Base Class

```cpp
class ProtocolStateMachine {
public:
    virtual ~ProtocolStateMachine() = default;
    void setState(int state);
    int state() const;
    SMResult processMessage(const ParsedMessage& msg);
    SMResult processTimer(L3TimerId timerId);
    virtual std::string_view debugName() const = 0;

protected:
    virtual SMResult handle_message_impl(int state, const ParsedMessage& msg) = 0;
    virtual SMResult handle_timer_impl(int state, L3TimerId timerId) = 0;
};
```

### RRStateMachine States

| State | Description |
|-------|-------------|
| `IDLE` | No dedicated channel assigned |
| `CHANNEL_REQUESTED` | RACH received, waiting for AGCH |
| `CHANNEL_ASSIGNED` | Immediate Assignment sent, waiting for SABM |
| `LINK_ESTABLISHED` | LAPDm link established (UA received) |
| `WAITING_MM` | Waiting for MM procedure (CM Service Request) |
| `ACTIVE` | Full communication on DCCH |
| `CIPHER_MODE` | Ciphering mode procedure in progress |
| `HANDOVER` | Handover procedure in progress |
| `CHANNEL_RELEASE` | Channel release in progress |

**Default RR transitions:** (a `SendResponse` action marks states where a response should be built externally; e.g. IDLE+ChannelRequest responds with ImmediateAssignment/ChannelRelease per application policy, ACTIVE+ChannelRelease re-sends the release)
```
IDLE + ChannelRequest            -> CHANNEL_REQUESTED  (SendResponse)
CHANNEL_ASSIGNED + PagingResponse-> WAITING_MM
LINK_ESTABLISHED + (any MM msg)  -> WAITING_MM
WAITING_MM + CMServiceAccept     -> ACTIVE
WAITING_MM + CMServiceRequest    -> ACTIVE             (SendResponse)
ACTIVE + CC Setup                -> ACTIVE             (SendResponse, stay)
ACTIVE + ChannelRelease          -> CHANNEL_RELEASE    (SendResponse)
ACTIVE + HandoverCommand         -> HANDOVER
CIPHER_MODE + CipherModeComplete -> ACTIVE
CHANNEL_RELEASE                  -> ReleaseChannel action (no state change)
T3109 expiry (CHANNEL_ASSIGNED or WAITING_MM) -> CHANNEL_RELEASE
```

### MMStateMachine States

| State | Description |
|-------|-------------|
| `DEREGISTERED`    | MS not registered in VLR |
| `SERVICE_REQUEST` | CM Service Request received |
| `WAITING_IDENTITY`| Identity Request sent, awaiting response |
| `IDENTITY_VERIFIED`| IMSI/TMSI known and verified |
| `AUTHENTICATION`  | Authentication Request sent, awaiting response |
| `AUTHENTICATED`   | Authentication complete |
| `LOCATION_UPDATE` | Location Updating in progress |
| `REGISTERED`      | Fully registered, ready for calls |

**Default MM transitions:** (`SendResponse` = build a response externally, e.g. Identity Request on entering IDENTITY_VERIFIED)
```
DEREGISTERED + CMServiceRequest       -> WAITING_IDENTITY  (SendResponse)
SERVICE_REQUEST + IdentityResponse    -> IDENTITY_VERIFIED (SendResponse)
WAITING_IDENTITY + IdentityResponse   -> IDENTITY_VERIFIED (SendResponse)
IDENTITY_VERIFIED + AuthResponse      -> AUTHENTICATED     (SendResponse)
AUTHENTICATION + AuthResponse         -> AUTHENTICATED     (SendResponse)
AUTHENTICATED + LocationUpdatingReq   -> LOCATION_UPDATE
LOCATION_UPDATE + CMServiceAccept     -> REGISTERED        (SendResponse)
T3101/T3102 expiry (SERVICE_REQUEST or WAITING_IDENTITY)  -> DEREGISTERED
T3106 expiry (AUTHENTICATION)         -> DEREGISTERED
```

Non-MM PDs always return `SMAction::None`.

### CCStateMachine States

| State | Description |
|-------|-------------|
| `IDLE`                | No call in progress |
| `SETUP_RECEIVED`      | Setup message received |
| `PROCEEDING`          | Call Proceeding sent |
| `ALERTING`            | Alerting sent |
| `CONNECT`             | Connect received |
| `ACTIVE`              | Bidirectional speech path established |
| `DISCONNECT_RECEIVED` | Disconnect received |
| `RELEASE`             | Release in progress |

**Default CC transitions:** (`SendResponse` = build a response externally; auto-transitions fire on any routed message in that state)
```
IDLE + Setup                 -> SETUP_RECEIVED
SETUP_RECEIVED               -> PROCEEDING           (auto, SendResponse: Call Proceeding)
PROCEEDING + Alerting        -> ALERTING             (SendResponse: Alerting ack per application policy)
ALERTING + Connect           -> CONNECT              (SendResponse: Connect)
CONNECT + CallConfirmed      -> ACTIVE
ACTIVE + Disconnect          -> DISCONNECT_RECEIVED  (SendResponse)
ACTIVE + ConnectAcknowledge  -> ACTIVE               (stay, no-op)
DISCONNECT_RECEIVED          -> RELEASE              (auto, SendResponse: Release)
RELEASE + Release            -> IDLE                 (SendResponse)
T3101 expiry (SETUP_RECEIVED/PROCEEDING/ALERTING) -> IDLE
```

Non-CC PDs always return `SMAction::None`.

### Usage Example

```cpp
#include <gsml3parser/stack/state_machine.h>

// Use the default RR state machine
RRStateMachine rrFsm;
rrFsm.setState(RRStateMachine::State::IDLE);

// Process incoming messages
auto msg = parseL3(buffer).value();
SMResult result = rrFsm.processMessage(msg);

if (result.action == SMAction::Transition) {
    int newState = result.nextState.value();
    // Handle state change, build response messages as needed
}

// Custom FSM: inherit and override specific transitions
class MyRRFSM : public RRStateMachine {
protected:
    SMResult handle_message_impl(int state, const ParsedMessage& msg) override {
        if (state == State::ACTIVE && messagePD(msg) == L3PD::MobilityManagement) {
            return {SMAction::SendResponse, static_cast<int>(State::CIPHER_MODE)};
        }
        return RRStateMachine::handle_message_impl(state, msg);
    }
};
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| `sizeof(SMResult)` | <= 16 bytes (static-asserted) |
| Message dispatch | O(1): PD gate + per-state message-type tests; RR `ACTIVE` uses a `switch(mti)` jump table for its four handled MTIs |
| Heap allocations | None on hot path |
| Virtual dispatch | Only at the base-class level (`processMessage` -> `handle_message_impl`) |
| Thread safety | NOT thread-safe; one instance per MS |

---

## 37. Channel Pool - Logical Channel Management

**File:** `gsml3parser/stack/channel_pool.h`

Manages a pool of logical channels for BTS operation. Provides O(1) channel allocation via per-type free-lists, Request Reference (RA) decoding from RACH bursts, and Very Early Assignment (VEA) fallback logic.

### ChannelDescriptor

Describes a logical channel with type, transceiver index, timeslot, and ARFCN.

```cpp
struct ChannelDescriptor {
    ChannelType type{ChannelType::UndefinedCHType};
    uint8_t trxNumber{};
    uint8_t timeslot{};
    uint16_t arfcn{};
    bool operator==(const ChannelDescriptor&) const = default;
};
```

### decodeChannelNeeded()

Decodes the Request Reference (RA) byte from a RACH burst into the required channel type, following GSM 04.08 Table 9.9.

```cpp
ChannelType decodeChannelNeeded(uint8_t ra, bool neci = false, bool vea = false);
```

| Parameter | Description |
|-----------|-------------|
| `ra` | 8-bit Request Reference from Channel Request message |
| `neci` | Non-Extended Channel Indicator (reserved for future extended decoding) |
| `vea` | Very Early Assignment enabled; when true, MO calls get TCH directly |

**Establishment cause mapping (bits 6-5 of RA):**

| Bits 6-5 | Cause | Channel (VEA=off) | Channel (VEA=on) |
|----------|-------|-------------------|-------------------|
| `00` | MO Call | SDCCH | TCHF |
| `01` | Emergency Call | TCHF | TCHF |
| `10` | Answer to Paging | TCHF | TCHF |
| `11` | Location Updating | SDCCH | SDCCH |

### isLocationUpdatingRequest()

```cpp
bool isLocationUpdatingRequest(uint8_t ra, bool neci = false);
```

Returns `true` when establishment cause bits (6-5) equal `11`.

### ChannelPool

```cpp
class ChannelPool {
public:
    void addChannel(ChannelDescriptor desc);
    std::optional<ChannelDescriptor> allocate(ChannelType type);
    bool release(const ChannelDescriptor& desc);
    bool removeChannel(const ChannelDescriptor& desc);
    bool isFree(const ChannelDescriptor& desc) const;
    size_t freeCount(ChannelType type) const;
    size_t totalCount() const;
    size_t allocatedCount(ChannelType type) const;
    std::optional<ChannelDescriptor> allocateVEA(uint8_t ra);
    std::vector<ChannelDescriptor> freeChannels(ChannelType type) const;
};
```

| Method | Description | Complexity |
|--------|-------------|------------|
| `addChannel(desc)` | Register a channel (cold path, init time) | O(1) amortized |
| `allocate(type)` | Pop from per-type free-list | O(1) |
| `release(desc)` | Return channel to free-list | O(1) find/erase (per-type unordered_set) + O(1) push |
| `removeChannel(desc)` | Permanently remove from pool | O(1) if allocated; O(N) free-list scan if free (cold path) |
| `isFree(desc)` | Check if channel is available | O(N) |
| `freeCount(type)` | Number of free channels of type | O(1) |
| `totalCount()` | Total channels (free + allocated) | O(T) |
| `allocatedCount(type)` | In-use channels of type | O(1) |
| `allocateVEA(ra)` | VEA: try TCH, fall back SDCCH | O(1) |
| `freeChannels(type)` | List all free channels (diagnostic) | O(1) copy |

### VEA Procedure

Very Early Assignment (GSM 05.08) skips the intermediate SDCCH assignment for MO calls:

```cpp
ChannelPool pool;
pool.addChannel({ChannelType::TCHFType, 1, 0, 200});
pool.addChannel({ChannelType::SDCCHType, 0, 0, 100});

// RA=0x00 (MO call): VEA allocates TCHF directly
auto ch = pool.allocateVEA(0x00);
// ch->type == ChannelType::TCHFType

// After TCH exhausted, falls back to SDCCH
pool.allocate(ChannelType::TCHFType); // consume the TCH
auto fallback = pool.allocateVEA(0x00);
// fallback->type == ChannelType::SDCCHType
```

### Usage Example

```cpp
#include <gsml3parser/stack/channel_pool.h>

using namespace gsml3parser;

// Initialize channel pool at BTS startup
ChannelPool pool;
pool.addChannel({ChannelType::SDCCHType, 0, 0, 100});
pool.addChannel({ChannelType::TCHFType, 1, 0, 200});
pool.addChannel({ChannelType::TCHFType, 1, 1, 201});

// Handle incoming Channel Request on RACH
uint8_t ra = 0x03; // establishment cause from RACH burst
ChannelType needed = decodeChannelNeeded(ra, false, true);

auto ch = pool.allocate(needed);
if (ch) {
    // Build ImmediateAssignment with allocated channel
    // Send to MS...
}

// After call completed, release the channel
pool.release(*ch);
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| `sizeof(ChannelDescriptor)` | 6 bytes |
| `sizeof(ChannelPool)` | ~3.5 KB (two `std::array[..., kMaxChannelTypes=32]` buckets; per-type `vector` free-lists + `unordered_set` allocated sets) |
| allocate() complexity | O(1) - vector pop_back on free-list |
| release() complexity | O(1) - unordered_set find/erase on allocated set + free-list push |
| Heap allocations | Amortized O(1) on hot path (allocate/release). addChannel() grows internal vectors; the allocated set may rehash as channels are allocated. |
| Thread safety | NOT thread-safe; caller must provide synchronization for multi-threaded access |

---

## 38. FlatHandler - Zero-Overhead Callbacks

**File:** `gsml3parser/flat_handler.h`

`FlatHandler` is the zero-overhead callback type used throughout the dispatcher and procedure layers. Each instance is exactly two machine words (16 bytes on 64-bit, `static_assert`-ed), compared to 40+ bytes for `std::function`. Invocations use direct function pointer calls — no virtual dispatch, no type erasure overhead.

### FlatHandler Struct

```cpp
struct FlatHandler {
    using Callback = void (*)(const ParsedMessage*, void*);

    Callback fn{nullptr};
    void* ctx{nullptr};

    constexpr FlatHandler() noexcept = default;
    constexpr FlatHandler(Callback f, void* c) noexcept;

    // Copy/move and assignment are RAII: a shared handler's refcount is
    // bumped on copy and released on overwrite/destruction (bad_alloc-safe).
    void operator()(const ParsedMessage& msg, void* userCtx = nullptr) const;
    void release() noexcept;          // drop one shared reference; resets to empty
    explicit operator bool() const noexcept;
};

static_assert(sizeof(FlatHandler) == 2 * sizeof(void*), "FlatHandler must be exactly two pointers");
```

| Method | Description | Complexity |
|--------|-------------|------------|
| `operator()(msg, userCtx)` | Invoke handler. Raw handlers call `fn(&msg, userCtx ?: ctx)`; shared handlers dispatch through their holder with the caller's context. | O(1) single indirect call |
| `release()` | Drop one shared reference (no-op for raw handlers), reset to empty | O(1) |
| `operator bool` | True if fn is not nullptr | O(1) |

Registration semantics in `ProtocolDispatcher`: re-registering a slot replaces the previous handler; its shared storage, if any, is released automatically through the RAII copy/move operations. There is no removal API — overwrite the slot with an empty handler or the new one.

### Factory Functions

#### makeHandler (Zero Allocation)

For non-capturing lambdas (stateless callables):

```cpp
template<typename F>
    requires (std::is_invocable_v<F, const ParsedMessage&, void*> &&
              std::is_default_constructible_v<F> &&
              !std::is_pointer_v<F> &&
              !std::is_function_v<std::decay_t<F>>)
FlatHandler makeHandler(F) noexcept;
```

No heap allocation. The lambda is converted to a function pointer at compile time.
Function pointers and function types are rejected: a default-constructed
function pointer is null and would crash on the first invocation. For plain
function pointers with a user context, use the constructor directly:
`FlatHandler h{myFunction, myCtx};`

#### makeSharedHandler (Heap Allocation)

For capturing lambdas:

```cpp
template<typename F>
    requires std::is_invocable_v<F, const ParsedMessage&, void*>
FlatHandler makeSharedHandler(F f);
```

Stores the capturing lambda in a `shared_ptr`-controlled heap allocation. The `shared_ptr` is accessible through the handler's `ctx` pointer.

#### destroySharedHandler

```cpp
void destroySharedHandler(FlatHandler& h);
```

Destroys the heap allocation created by `makeSharedHandler`. Call when replacing or removing a handler to avoid memory leaks. Safe to call on empty handlers. The `ProtocolDispatcher` destructor calls this automatically for all registered handlers.

### Usage Example

```cpp
#include <gsml3parser/flat_handler.h>

// Non-capturing: zero allocation
FlatHandler h1 = makeHandler([](const ParsedMessage& msg, void*) {
    std::cout << messageName(msg) << "\n";
});
h1(parsedMsg);

// Capturing: heap allocation via shared_ptr
int count = 0;
FlatHandler h2 = makeSharedHandler([&count](const ParsedMessage& msg, void*) {
    ++count;
});
h2(parsedMsg);
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| `sizeof(FlatHandler)` | 16 bytes (two pointers) vs 40+ bytes for std::function |
| Invocation overhead | Single indirect call vs virtual dispatch + type erasure |
| Default construction | Zero-cost (nullptr, nullptr) |

---

## 39. ShardedChannelPool - Thread-Safe Channel Pool

**File:** `gsml3parser/stack/sharded_channel_pool.h`

Thread-safe sharded channel pool for high-concurrency BTS scenarios. Partitions channels across N shards using a hash of the channel descriptor. Each shard has its own `std::shared_mutex`, so threads operating on different shards never contend.

### Template Parameter

```cpp
template<int N = 16>
class ShardedChannelPool;
```

| Parameter | Constraint | Description |
|-----------|------------|-------------|
| `N` | Power of two, ≥ 2 | Number of shards (commonly 4, 8, 16, or 32) |

Explicit template instantiations are provided for N = 4, 8, 16, and 32.

### API

```cpp
void addChannel(ChannelDescriptor desc);
[[nodiscard]] std::optional<ChannelDescriptor> allocate(ChannelType type);
bool release(const ChannelDescriptor& desc);
[[nodiscard]] size_t freeCount(ChannelType type) const;
[[nodiscard]] size_t totalCount() const;

// Public for distribution tests: the same bit-packed finalizer used to
// select the owning shard, keyed by (type, trx, timeslot, arfcn).
static constexpr uint32_t hashDescriptor(const ChannelDescriptor& desc) noexcept;
```

| Method | Description | Complexity | Lock Type |
|--------|-------------|------------|-----------|
| `addChannel(desc)` | Add channel to the hashed shard | O(1) hash + lock | Exclusive |
| `allocate(type)` | Round-robin shard start, then remaining shards (fallback) | O(N) worst case | Exclusive per shard |
| `release(desc)` | Return channel to its shard | O(1) hash + lock | Exclusive |
| `freeCount(type)` | Total free across all shards | O(N) | Shared |
| `totalCount()` | Total channels across all shards | O(N) | Shared |

### Hash Function

The shard index is computed from `(type, trxNumber, timeslot, arfcn)` via the bit-packed `hashDescriptor()` finalizer and a bitmask (`hash & (N-1)`). This ensures:
- O(1) computation (no modulo division)
- Deterministic: same channel always maps to same shard
- Even distribution for typical BTS channel layouts

### Allocation Strategy

`allocate(type)` does not know which channel will be taken, only its type, so the descriptor hash cannot be used for routing. Instead it starts probing from a **round-robin shard** (an atomic counter masked by `N-1`), which spreads lock contention evenly across shards instead of concentrating it on shard 0, then falls back to the remaining shards. The fallback is required because channels are hash-distributed across shards at `addChannel()` time, so a free channel of the requested type may reside in any shard. Complexity is O(N) in the worst case (all shards probed), typically terminating on the first or second shard.

### Thread Safety

All public methods are thread-safe. Multiple threads can concurrently call `allocate()`, `release()`, `addChannel()` etc. Read-only operations use shared locks (`std::shared_lock`) for better concurrency.

**Performance:** With N=16 or N=32 and millions of channels, expected contention is negligible when the hash distributes work evenly.

### Usage Example

```cpp
#include <gsml3parser/stack/sharded_channel_pool.h>
#include <thread>

using namespace gsml3parser;

ShardedChannelPool<16> pool;

// Pre-populate channels
for (int trx = 0; trx < 4; ++trx) {
    for (int ts = 0; ts < 16; ++ts) {
        pool.addChannel({ChannelType::SDCCHType, static_cast<uint8_t>(trx),
                         static_cast<uint8_t>(ts), 100 + trx * 16 + ts});
    }
}

// Concurrent allocation from multiple threads
std::vector<std::thread> workers;
for (int i = 0; i < 8; ++i) {
    workers.emplace_back([&pool]() {
        auto ch = pool.allocate(ChannelType::SDCCHType);
        if (ch) {
            // Use channel...
            pool.release(*ch);
        }
    });
}
for (auto& t : workers) t.join();
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| `sizeof(ShardedChannelPool<16>)` | 16 × sizeof(ChannelPool + shared_mutex) |
| Hash computation | O(1) bitmask, no division |
| Contention | Only when two threads hash to the same shard |

---

## 40. InlineFramer - Zero-Copy Frame Extraction

**File:** `gsml3parser/bitstream/inline_framer.h` (header-only)

Zero-copy L3 frame extractor for contiguous memory buffers. Unlike `L3Framer` which reads from a `ByteSource` and copies data into an internal buffer, `InlineFramer` operates directly on the caller's `std::span`, yielding non-owning views into the original data with zero allocations.

### API

```cpp
class InlineFramer {
public:
    constexpr InlineFramer() noexcept = default;
    explicit InlineFramer(std::span<const uint8_t> data, bool useL2Length = true);

    [[nodiscard]] std::optional<std::span<const uint8_t>> nextFrame() noexcept;
    [[nodiscard]] constexpr size_t remaining() const noexcept;
    void reset() noexcept;
    void setMaxFrameLength(size_t len) noexcept;
    [[nodiscard]] constexpr size_t resyncSkips() const noexcept;  // corrupt L2 length octets skipped during resync
};
```

| Method | Description | Complexity |
|--------|-------------|------------|
| `nextFrame()` | Extract next frame as a non-owning span into the original data; `nullopt` when exhausted. Corrupt L2 length octets (0 or > maxFrameLength) are skipped and counted by `resyncSkips()`. | O(1) for L2 length, O(L) for header-based scanning |
| `remaining()` | Unconsumed bytes | O(1) |
| `reset()` | Reset to beginning of buffer (also clears the resync counter) | O(1) |
| `setMaxFrameLength(len)` | Upper bound on frame size (default 4096) | — |
| `resyncSkips()` | Number of corrupt length octets skipped so far | O(1) |

### Framing Modes

| Mode | Description |
|------|-------------|
| **L2 length** (`useL2Length=true`, default) | Each frame preceded by a single length octet. Deterministic; required for production streams. |
| **Header-based** (`useL2Length=false`, opt-in) | Frame length derived from PD+MTI fixed-length table, or next-header scanning for variable-length messages (heuristic — see above). |

### Usage Example

```cpp
#include <gsml3parser/bitstream/inline_framer.h>

// Buffer with L2-framed data: [len][msg...][len][msg...]
std::vector<uint8_t> buffer = {3, 0x06, 0x0D, 0x00, 2, 0x05, 0x21};

InlineFramer framer(std::span{buffer}, true /* L2 length mode */);

while (auto frame = framer.nextFrame()) {
    // 'frame' is a span into the original buffer — zero copies!
    auto msg = parseL3(*frame);
    if (msg) {
        std::cout << messageName(*msg) << "\n";
    }
}
```

### Thread Safety

NOT thread-safe. One instance per buffer, single-threaded use. Safe for concurrent use when each thread has its own `InlineFramer` instance operating on separate memory regions.

---

## 41. ZeroCopyStreamProcessor - Zero-Copy Stream Parsing

**File:** `gsml3parser/bitstream/zero_copy_processor.h` (header-only)

Zero-copy L3 stream processor for contiguous buffers. Parses L3 messages directly from a memory span without any intermediate copying. Ideal for high-throughput scenarios where data arrives in large contiguous chunks (e.g., memory-mapped files, DMA buffers).

### API

```cpp
class ZeroCopyStreamProcessor {
public:
    explicit ZeroCopyStreamProcessor(std::span<const uint8_t> data, bool useL2Length = true);

    [[nodiscard]] std::optional<ParsedMessage> nextMessage();

    template<typename F>
        requires std::is_invocable_v<F, const ParsedMessage&>
    void forEach(F&& handler);

    [[nodiscard]] const StreamStats& stats() const noexcept;
    void resetStats() noexcept;
    [[nodiscard]] size_t remaining() const noexcept;
    void reset() noexcept;
};
```

| Method | Description |
|--------|-------------|
| `nextMessage()` | Parse next L3 message. Returns `std::nullopt` when buffer exhausted or parse error. |
| `forEach(handler)` | Bulk process all remaining messages, invoking handler for each. |
| `stats()` | Access accumulated stream statistics (frame count, per-PD counts, errors). |
| `remaining()` | Unconsumed bytes in the buffer. |
| `reset()` | Reset to beginning of buffer. |

### Usage Example

```cpp
#include <gsml3parser/bitstream/zero_copy_processor.h>

std::vector<uint8_t> data = { /* L2-framed L3 messages */ };

ZeroCopyStreamProcessor proc(std::span{data}, true);

// Iterate one by one
while (auto msg = proc.nextMessage()) {
    std::cout << messageName(*msg) << "\n";
}

// Or bulk process with forEach
proc.reset();
size_t count = 0;
proc.forEach([&count](const ParsedMessage& msg) {
    (void)msg;
    ++count;
});
std::cout << "Parsed " << count << " messages\n";
```

### Performance

Zero-copy parsing avoids the `memcpy` overhead of `L3StreamProcessor`'s internal buffering. For large contiguous buffers, expect 2-5x speedup depending on frame sizes and CPU cache characteristics.

### Thread Safety

NOT thread-safe. Safe for concurrent use when each thread has its own instance operating on separate memory regions.

---

## 42. Subscriber Registry - Subscriber Session Management

**File:** `gsml3parser/stack/subscriber_registry.h`

Manages per-subscriber sessions for software BTS implementations. Each session aggregates MSContext, RR/MM/CC state machines, timers, transactions, and a ProcedureRunner into a single object indexed by TMSI, IMSI, and LAPDm link.

### SubscriberSession

Aggregates all per-MS state:

| Member | Type | Purpose |
|--------|------|---------|
| `context` | `MSContext` | Identity, channel, flags (≤256B) |
| `rrSM` | `RRStateMachine` | Radio Resource FSM |
| `mmSM` | `MMStateMachine` | Mobility Management FSM |
| `ccSM` | `CCStateMachine` | Call Control FSM |
| `timers` | `TimerManager` | Protocol timers (≤32 concurrent) |
| `transactions` | `TransactionManager` | Request-response correlation |
| `procedures` | `ProcedureRunner` | Active protocol procedures |
| `response` | `ResponseContext` | Parameters for building protocol responses (populated by the active procedure; consumed by `ResponseBuilder::buildResponseFromToken`) |
| `channel` | `optional<ChannelDescriptor>` | Current channel assignment |
| `lapdmLink` | `uint8_t` | LAPDm link ID for routing |
| `assignedTmsi` | `uint32_t` | TMSI key in the owning registry (set by `createByTMSI`/`createByIMSI`; 0 = not owned) |

Size: `sizeof(SubscriberSession) < 4096 bytes`, all components inline.

### SubscriberRegistry API

Storage: the TMSI and LAPDm-link indexes use a flat open-addressing
hash table (`stack/flat_map.h`, inline entries, no per-node heap
allocation); the IMSI index is a transparent-lookup `unordered_map`
(owned `std::string` keys, cold path). Call `reserve()` at startup
when the subscriber scale is known.

```cpp
// Create sessions by identity.
SubscriberSession* createByTMSI(uint32_t tmsi);
SubscriberSession* createByIMSI(std::string_view imsi);

// Lookup by any index.
SubscriberSession* findByTMSI(uint32_t tmsi) noexcept;
SubscriberSession* findByIMSI(std::string_view imsi) noexcept;
SubscriberSession* findByLink(uint8_t trx, uint8_t ts, uint8_t lapdmLink) noexcept;

// Channel management (maintains link index).
void assignChannel(SubscriberSession* session, ChannelDescriptor desc, uint8_t lapdmLink);
void releaseChannel(SubscriberSession* session);

// Lifecycle.
// remove() is O(1): it derives the TMSI key from session->assignedTmsi and
// looks it up directly (no linear scan over all sessions).
bool remove(SubscriberSession* session) noexcept;
void clear() noexcept;
size_t count() const noexcept;

// Pre-size the flat TMSI/link indexes (one-time, cold path).
void reserve(size_t expectedSessions);

// Timer management.
// tickAllTimers() is O(active): it ticks only sessions with at least one running
// timer (active-timer index), not all sessions. Sessions register/unregister
// themselves automatically when their first timer starts / last timer stops.
// Each event carries the owning session pointer; the session's TransactionManager
// is notified of the expiry.
size_t tickAllTimers(std::chrono::milliseconds delta, std::span<TimerExpiry> expiredOut);

// Iterate all sessions (guaranteed single visit).
template<typename F> void forEach(F&& callback);
```

### ShardedSubscriberRegistry

Thread-safe variant that partitions sessions across N shards (power of two, >= 2; explicit instantiations provided for N = 4, 8, 16, 32). Each shard is a `SubscriberRegistry` guarded by its own `std::shared_mutex`; shard selection is a MurmurHash3-fmix32 TMSI hash masked with `N-1`.

```cpp
ShardedSubscriberRegistry<16> registry;  // default template argument is N = 16

// Thread-safe operations.
auto* s1 = registry.createByTMSI(0x12345678);        // exclusive shard lock, nullptr on duplicate TMSI
auto* s2 = registry.findByTMSI(0x12345678);          // shared shard lock
registry.remove(s1);                                 // O(1) via session->assignedTmsi

// Read-guarded access: findLocked() holds the shard's shared lock for the
// guard's lifetime (safe against concurrent readers; do not modify while held).
auto locked = registry.findLocked(0x12345678);       // {SubscriberSession* session, SharedGuard guard}
if (locked.session) use(*locked.session);            // shard stays read-locked here

// Exclusive access for multi-step modification:
auto shard = registry.lockForTMSI(0x12345678);       // {SubscriberRegistry& registry, UniqueGuard guard}
```

| Method | Notes |
|--------|-------|
| `createByTMSI(tmsi)` | nullptr if the TMSI already exists |
| `findByTMSI` / `findByIMSI` / `findByLink(trx, ts, lapdmLink)` | raw session pointer; IMSI and link lookups scan all shards (cold path) |
| `findLocked(tmsi)` / `lockForTMSI(tmsi)` | RAII `LockedSession` / `LockedShard` guards |
| `reserve(expectedSessions)` | pre-sizes each shard's flat indexes (`expected/N + 1`) |
| `forEach(callback)` | visits every session exactly once, shard by shard |
| `tickAllTimers(delta, expiredOut)` / `tickAllProcedures(delta)` | per-shard O(active) ticks; returns total events/failures |
| `remove(session)` | O(1) via `session->assignedTmsi`; returns false for unknown/removed sessions (the plain `SubscriberRegistry::clear()` emergency shutdown has no sharded equivalent) |

**Warning:** the shard mutexes are non-recursive — never call a locking API while holding a guard from `findLocked`/`lockForTMSI` on the same shard.

### Example

```cpp
SubscriberRegistry registry;
auto* session = registry.createByTMSI(0x12345678);

// Assign channel when MS seizes SDCCH.
ChannelDescriptor ch{ChannelType::SDCCHType, 0, 5, 100};
registry.assignChannel(session, ch, /*lapdmLink=*/3);

// Route incoming message to session via link.
auto* target = registry.findByLink(0, 5, 3);

// Tick all timers.
std::array<TimerExpiry, 256> expired;
size_t n = registry.tickAllTimers(100ms, expired);

// Clean up when procedure completes.
registry.remove(session);
```

---

## 43. RSL Types - A-bis RSL Type Definitions

**Header:** `include/gsml3parser/abis/rsl_types.h`
**Source:** `src/abis/rsl_types.cpp`
**3GPP:** TS 48.058 (A-bis interface)

Defines all RSL enumerations and structures for A-bis message parsing and construction.

### First Octet and Message Groups

The first octet of an RSL frame is `(message group << 1) | transparent` (TS 48.058 9.1): the high
seven bits carry the message group and bit 0 is the transparent indication flag (set when the frame
carries L3 as-is, e.g. RLL DATA_*). The second octet is a single global message type shared by all
groups; the remaining octets are information elements.

| Enum | Group | Description |
|------|-------|-------------|
| `RSLDiscriminator::Rll` | `0x01` | Radio Link Layer (L3 data transport) |
| `RSLDiscriminator::DedicatedChannel` | `0x04` | DCHAN - dedicated channel control |
| `RSLDiscriminator::CommonChannel` | `0x06` | CCHAN - common channel control |
| `RSLDiscriminator::TrxManagement` | `0x08` | Transceiver-level management (TS 48.058 8.6: RF_RES_IND = 0x19, SACCH_FILL = 0x1A, OVERLOAD = 0x1B, ERROR_REPORT = 0x1C) |
| `RSLDiscriminator::Lcs` | `0x10` | Location Services (TS 48.058 8.7: LOCATION_INFO = 0x41) |
| `RSLDiscriminator::IPAccess` | `0x3F` | ip.access vendor-specific |

Helpers: `rslFirstOctet(disc, transparent)` encodes the first octet; `decodeRslFirstOctet(octet)`
decodes it (group 0 and groups above 0x3F are rejected); `rslGroupToDiscriminator(group)` maps a raw
7-bit group to the enum.

### RLL Message Types (TS 48.058 8.3)

| Enum | Value | Description |
|------|-------|-------------|
| `RSLL3MessageType::DataReq` | `0x01` | DATA_REQ: numbered L3 data for the MS (L3Info TL16V IE) |
| `RSLL3MessageType::DataInd` | `0x02` | DATA_IND: numbered L3 data from the MS |
| `RSLL3MessageType::ErrorInd` | `0x03` | ERROR_IND: LAPDm link-layer error report |
| `RSLL3MessageType::EstReq` | `0x04` | EST_REQ: radio link establishment request |
| `RSLL3MessageType::EstConf` | `0x05` | EST_CONF: radio link establishment confirm |
| `RSLL3MessageType::EstInd` | `0x06` | EST_IND: radio link establishment indication |
| `RSLL3MessageType::RelReq` | `0x07` | REL_REQ: radio link release request |
| `RSLL3MessageType::RelConf` | `0x08` | REL_CONF: radio link release confirm |
| `RSLL3MessageType::RelInd` | `0x09` | REL_IND: radio link release indication |
| `RSLL3MessageType::UnitDataReq` | `0x0A` | UNIT_DATA_REQ: unnumbered (connectionless) L3 transfer |
| `RSLL3MessageType::UnitDataInd` | `0x0B` | UNIT_DATA_IND: unnumbered L3 transfer |
| `RSLL3MessageType::SuspReq / SuspConf / ResReq / ReconReq` | `0x0C–0x0F` | Vendor extensions (suspension, resume, reconversion) |

### DCHAN Message Types (TS 48.058 8.4)

| Enum | Value | Description |
|------|-------|-------------|
| `RSLDChanMessageType::ChanActiv` | `0x21` | CHAN_ACTIV: channel activation (CHN_ACT) |
| `RSLDChanMessageType::ChanActivAck` | `0x22` | CHAN_ACTIV_ACK: activation acknowledgment |
| `RSLDChanMessageType::ChanActivNack` | `0x23` | CHAN_ACTIV_NACK: activation rejection (RSLErrorCause) |
| `RSLDChanMessageType::ConnFail` | `0x24` | CONN_FAIL: connection failure (RSLErrorCause) |
| `RSLDChanMessageType::DeactivateSacch` | `0x25` | DEACTIVATE_SACCH |
| `RSLDChanMessageType::EncrCmd` | `0x26` | ENCR_CMD: encryption command (RSLEncryptionInfo IE) |
| `RSLDChanMessageType::HandoDet` | `0x27` | HANDO_DET: handover detection (AccessDelay IE) |
| `RSLDChanMessageType::MeasRes` | `0x28` | MEAS_RES: measurement result |
| `RSLDChanMessageType::ModeModifyReq` | `0x29` | MODE_MODIFY_REQ |
| `RSLDChanMessageType::ModeModifyAck` | `0x2A` | MODE_MODIFY_ACK |
| `RSLDChanMessageType::ModeModifyNack` | `0x2B` | MODE_MODIFY_NACK (RSLErrorCause) |
| `RSLDChanMessageType::PhyContextReq` | `0x2C` | PHY_CONTEXT_REQ |
| `RSLDChanMessageType::PhyContextConf` | `0x2D` | PHY_CONTEXT_CONF |
| `RSLDChanMessageType::RfChanRel` | `0x2E` | RF_CHAN_REL: RF channel release |
| `RSLDChanMessageType::MsPowerControl` | `0x2F` | MS_POWER_CONTROL (MSPower IE) |
| `RSLDChanMessageType::BsPowerControl` | `0x30` | BS_POWER_CONTROL (BSPower IE) |
| `RSLDChanMessageType::PreprocConfig` | `0x31` | PREPROC_CONFIG (codec pre-configuration) |
| `RSLDChanMessageType::PreprocMeasRes` | `0x32` | PREPROC_MEAS_RES |
| `RSLDChanMessageType::RfChanRelAck` | `0x33` | RF_CHAN_REL_ACK |
| `RSLDChanMessageType::SacchInfoModify` | `0x34` | SACCH_INFO_MODIFY |
| `RSLDChanMessageType::TalkerDet` | `0x35` | TALKER_DET (VBS/VGCS) |
| `RSLDChanMessageType::ListenerDet` | `0x36` | LISTENER_DET (VBS/VGCS) |
| `RSLDChanMessageType::RemoteCodecConfRep` | `0x37` | REMOTE_CODEC_CONF_REP |
| `RSLDChanMessageType::RtdRep` | `0x38` | RTD_REP (round-trip delay) |
| `RSLDChanMessageType::PreHandoNotif` | `0x39` | PRE_HANDO_NOTIF |
| `RSLDChanMessageType::MrCodecModReq / Ack / Nack / Per` | `0x3A–0x3D` | MR codec modification request/ack/nack/permanent |
| `RSLDChanMessageType::TfoRep` | `0x3E` | TFO_REP (transparent voice) |
| `RSLDChanMessageType::TfoModReq` | `0x3F` | TFO_MOD_REQ |

### CCHAN Message Types (TS 48.058 8.5)

| Enum | Value | Description |
|------|-------|-------------|
| `RSLCChanMessageType::BcchInfo` | `0x11` | BCCH_INFO: system information (FullBCCHInfo LV IE) |
| `RSLCChanMessageType::CcchLoadInd` | `0x12` | CCCH_LOAD_IND: CCCH load report |
| `RSLCChanMessageType::ChanRqd` | `0x13` | CHAN_RQD: channel required (ReqReference + AccessDelay IEs) |
| `RSLCChanMessageType::DeleteInd` | `0x14` | DELETE_IND: delete indication (FullImmAssInfo IE) |
| `RSLCChanMessageType::PagingCmd` | `0x15` | PAGING_CMD: paging command (L3Info TL16V IE) |
| `RSLCChanMessageType::ImmediateAssignCmd` | `0x16` | IMMEDIATE_ASSIGN_CMD |
| `RSLCChanMessageType::SmsBcReq` | `0x17` | SMS_BC_REQ: SMS broadcast request |
| `RSLCChanMessageType::ChanConf` | `0x18` | CHAN_CONF (vendor extension) |
| `RSLCChanMessageType::SmsBcCmd` | `0x1D` | SMS_BC_CMD: SMS broadcast command (L3Info TL16V IE) |
| `RSLCChanMessageType::CbchLoadInd` | `0x1E` | CBCH_LOAD_IND |
| `RSLCChanMessageType::NotCmd` | `0x1F` | NOT_CMD |

### TRX Management Message Types (TS 48.058 8.6)

| Enum | Value | Description |
|------|-------|-------------|
| `RSLTrxMessageType::RfResourceIndication` | `0x19` | RF_RES_IND: transceiver RF resource report |
| `RSLTrxMessageType::SacchFilling` | `0x1A` | SACCH_FILL |
| `RSLTrxMessageType::OverloadIndication` | `0x1B` | OVERLOAD |
| `RSLTrxMessageType::ErrorReport` | `0x1C` | ERROR_REPORT |

### LCS Message Types (TS 48.058 8.7)

| Enum | Value | Description |
|------|-------|-------------|
| `RSLLcsMessageType::LocationInformation` | `0x41` | LOCATION_INFO: location services information |

### Information Elements

`RSL_IE` defines the TS 48.058 section 9.x IE type codes (0x1D is not allocated). Every code has a
fixed encoding class via `rslIeEncoding()`:

- **TV** (type + fixed value, no length octet; value sizes in parentheses):
  ChanNr 0x01 (2), LinkIdent 0x02 (1), ActType 0x03 (1), BSPower 0x04 (1),
  FrameNumber 0x08 (2), HandoRef 0x09 (1), L1Info 0x0A (2), MSPower 0x0D (1), PagingGroup 0x0E (1),
  PagingLoad 0x0F (2), AccessDelay 0x11 (1), ReqReference 0x13 (3), ReleaseMode 0x14 (1),
  StartngTime 0x17 (2), TimingAdvance 0x18 (1), MeasResNr 0x1B (1), MsgId 0x1C (1),
  SysInfoType 0x1E (1), MSTimingOffset 0x25 (1), ChanNeeded 0x28 (1), CbCmdType 0x29 (1),
  CbchLoadInfo 0x2D (1), and the ip.access vendor extensions with a defined value size —
  Remote/Local IP 0xF0/0xF5 (4), Remote/Local port and Connection ID 0xF1/0xF3/0xF8 (2) and
  RTP payload types, speech mode and RTP CSD format 0xF2/0xF4/0xF9/0xFC (1);
- **TL16V** (type + 16-bit big-endian length + value, for payloads above 255 bytes):
  `L3Info` 0x0B only — the L3 payload carrier for RLL DATA_*/UNIT_DATA_* and CCHAN paging/SMS commands;
- **LV** (type + 8-bit length + value): all remaining codes — in particular ChanIdent 0x05,
  ChanMode 0x06 (four value octets), EncrInfo 0x07, MSIdentity 0x0C, PyhsContext 0x10,
  RachLoad 0x12 (explicit length octet 0x06, then the three big-endian u16 counters, section 9.3.18),
  ResourceInfo 0x15, RlmCause 0x16, UplinkMeas 0x19 (three value octets, optional vendor supplementary
  bytes appended raw), Cause 0x1A, MSPowerParam 0x1F, BSPowerParam 0x20, PreprocParam 0x21,
  PreprocMeas 0x22, ImmAssInfo 0x23, SmscbInfo 0x24, ErrMsg 0x26, FullBCCHInfo 0x27,
   SmscbMsg 0x2A, FullImmAssInfo 0x2B, SacchInfo 0x2C, the group-call/NCH EMLPP UIC main-channel MR
   codec RTD TFO and LLP APDU codes 0x2E–0x3C — plus the vendor extensions 0x60–0x63 (Osmo), the
   ip.access connection statistics 0xF6 (explicit length octet 0x1C, then seven big-endian u32
   counters) and the ip.access codes without a defined value size — 0xE0, 0xE1, 0xE2, 0xF7, 0xFA,
   0xFB, 0xFD and 0xFE of the IPAccess group 0xE0–0xFE — and unknown codes (decoding them as LV
   keeps malformed frames parseable without desynchronizing the IE list).

`RSLErrorCause` (TS 48.058 section 9.3.26) carries NACK/failure reasons; the code space contains
reserved gaps that must not be emitted on the wire (`isRslErrorCause()` validates an octet):

| Category | Values |
|----------|--------|
| Radio link failure | `RadioIfFail=0x00`, `RadioLinkFail=0x01`, `HandoverAccFail=0x02`, `TalkerAccFail=0x03`, `OmIntervention=0x07`, `NormalUnspec=0x0F`, `TMsrfpciExp=0x18` |
| BTS/TRX failure | `EquipmentFail=0x20`, `RrUnavail=0x21`, `TerrChFail=0x22`, `CcchOverload=0x23`, `AcchOverload=0x24`, `ProcessorOverload=0x25`, `BtsNotEquipped=0x27`, `RemoteTrauFailure=0x28`, `NotifOverflow=0x29` |
| Service unavailable | `ResUnavail=0x2F`, `TranscUnavail=0x30`, `ServOptUnavail=0x3F`, `EncrUnimpl=0x40`, `ServOptUnimpl=0x4F` |
| Channel/IPA failure | `RchAlrActvAlloc=0x50`, `IpaRchNotActvAlloc=0x51`, `IpaConnInvalid=0x52`, `IpaConnInUse=0x53`, `IpaConnAlreadyExists=0x54` |
| Protocol error | `InvalidMessage=0x5F`, `MsgDiscr=0x60`, `MsgType=0x61`, `MsgSeq=0x62`, `IeError=0x63`, `MandIeError=0x64`, `OptIeError=0x65`, `IeNonexist=0x66`, `IeLength=0x67`, `IeContent=0x68`, `Proto=0x6F` |
| Interworking | `Interworking=0x7F` |

Helpers `rslDiscriminatorName()`, `rslIEName()`, and `rslErrorCauseName()` return `std::string_view`
names for logging. The RLM Cause IE (0x16) is a separate LV encoding of radio link management causes
and is not part of this enum.

### Structures

- **`RSLChannelNumber`** - Channel Number IE value coding (TS 48.058 §9.3.1): `value = (code << 3) | timeslot`.
  Static methods: `encode(code, tn)`, `getCBits()`, `getTimeslot()`, `isDedicated()`. Channel codes:
  `BmAcch=0x01` ('00001'B), `Lm=0x02` (+ sub-channel 0/1, VAMOS), `Sdcch4=0x04` (+ sub 0..3),
  `Sdcch8=0x08` (+ sub 0..7), `Bcch=0x10`, `Rach=0x11`, `PchAgch=0x12`, `Pdch=0x18`, `Cbch4=0x19`,
  `Cbch8=0x1A`, `VamosBm=0x1D` (vendor extensions).
- **`RSLChannelMode`** - 4-byte Channel Mode IE value (TS 48.058 section 9.3.6): `dtx`, `spdInd`,
  `chanRateType`, `valueOctet`; `sizeof == 4`. Methods: `dtxDownlink()`, `dtxUplink()`,
  `isSignalling()`, `isSpeech()`, `isData()`. Speed indicator: `Speech=0x01`, `Data=0x02`,
  `Signalling=0x03`; channel rate types include `Sdcch=0x01`, `TchF=0x08`, `TchH=0x09`,
  `TchFBdMslot=0x0A`, `TchFDlMslot=0x1A`, `TchFGroup=0x18`, `TchHGroup=0x19`,
  `TchFBcast=0x28`, `TchHBcast=0x29` and the VAMOS vendor extensions. Octet layout:
  octet 1 = [reserved(6)|DTX_d(1)|DTX_u(1)], octet 2 = speed indicator, octet 3 = channel rate
  type, octet 4 = speech coding algorithm (speech) / opaque data rate code (data) / 0x00
  (signalling); the parser accepts exactly four value octets.
- **`RSLUplinkMeas`** - Uplink Measurements IE value part (TS 48.058 section 9.3.25): three octets —
  [RFU(1)|DTX_d(1)|rxlev_full(6)], [reserved(2)|rxlev_sub(6)], [reserved(2)|rxq_full(3)|rxq_sub(3)];
  a longer value appends vendor supplementary measurement information, kept raw (not decoded).
- **`RSLFrameNumber`** - Frame Number / Starting Time IE value part (TS 48.058 section 9.3.8): two
  octets packing t1p(5)|t3(6)|t2(5). The builder takes an absolute TDMA frame number (0..42431) and
  encodes `t1p = (fn/1326) % 32`, `t3 = fn % 51`, `t2 = fn % 26`; the inverse composition back to an
  absolute frame number is not unique, so the parser returns the three fields as-is.
- **`RSLEncryptionInfo`** - algorithmId + key span for A5 ciphering (algorithm identifier: 1=A5/0 … 8=A5/7).

### Helper Functions

- `rslFirstOctet(disc, transparent)` -> uint8_t (first-octet encoding)
- `decodeRslFirstOctet(octet)` -> optional<{group, transparent}>
- `rslGroupToDiscriminator(group)` -> optional<RSLDiscriminator>
- `rslIeEncoding(iei)` / `rslIeTvValueSize(iei)` — encoding class and TV value size of an IE code
- `rslDiscriminatorName(disc)` -> string_view
- `rslIEName(ie)` -> string_view
- `rslErrorCauseName(cause)` -> string_view

---

## 44. RSL Parser - A-bis RSL Message Parsing

**Header:** `include/gsml3parser/abis/rsl_parser.h`
**Source:** `src/abis/rsl_parser.cpp`
**3GPP:** TS 48.058 (A-bis interface)

Zero-heap-allocation parser for A-bis RSL messages. Extracts L3 payloads from RLL and control messages.

### `RSLParsedMessage`

Fixed-size result struct (560 bytes on 64-bit, zero heap allocation — all spans point into the caller's input buffer, which must outlive the struct). Contains:
- `discriminator`, `transparent`, `msgType`, `chanNr`, `linkId` (RLL only) — header fields
- `l3Payload` - extracted L3 bytes (span into original buffer; empty when the message carries none)
- `informationElements[MAX_IE=32]` + `ieCount`, and `ies()` span accessors - parsed TLV/TV IEs with `type`, 16-bit `len` (so TL16V L3 payloads over 255 bytes work), and non-owning `val` pointers into the original buffer
- `rawData` - full message span for debugging

L3 payload sources: RLL `DataReq/DataInd/UnitDataReq/UnitDataInd` via the first `L3Info` (0x0B) TL16V IE; CCHAN/DCHAN messages likewise via `L3Info`; fallback to `FullBCCHInfo` (0x27).

### `RSLParser::parse(data)`

Parse raw RSL bytes into structured message. Returns `Expected<RSLParsedMessage>`.
Validates discriminator, header size, and TLV boundaries.

### `RSLParser::extractL3(parsed)`

Return L3 payload from parsed message. Returns `optional<span<const uint8_t>>`.

### `RSLParser::findIE(parsed, ieType)`

Find IE by type code. Returns pointer or nullptr.

### `RSLParser::getChannelMode(parsed)`

Extract the four-octet Channel Mode IE value (TS 48.058 section 9.3.6). Returns
`optional<RSLChannelMode>`; nullopt when the ChanMode IE is missing or not exactly four octets.

### `RSLParser::getUplinkMeas(parsed)`

Decode the Uplink Measurements IE of MEAS_RES (TS 48.058 section 9.3.25). Returns
`optional<RSLUplinkMeas>` (dtxDownlink, rxlevFull, rxlevSub, rxqFull, rxqSub); nullopt when the IE is
missing or shorter than its three value octets — a longer value (vendor supplementary information)
decodes its first three octets only.

### `RSLParser::getFrameNumber(parsed)`

Decode the Frame Number / Starting Time IE of a message carrying it (e.g. CHAN_ACTIV_ACK; TS 48.058
section 9.3.8). Returns `optional<RSLFrameNumber>` with the t1p/t3/t2 fields; nullopt when the IE is
missing or not its two value octets.

### `RSLParser::getEncryptionInfo(parsed)`

Extract encryption parameters from ENCR_CMD. Returns `optional<RSLEncryptionInfo>`.

---

## 45. RSL Builder - A-bis RSL Message Construction

**Header:** `include/gsml3parser/abis/rsl_builder.h`
**Source:** `src/abis/rsl_builder.cpp`
**3GPP:** TS 48.058 (A-bis interface)

Constructs serialized RSL messages for BTS->BSC communication. Every method has both vector and span overloads for zero-allocation building.

### RLL Messages

The transparent flag is set on RLL data frames (`buildDataReq`/`buildDataInd`/`buildUnitDataReq`/
`buildUnitDataInd`) and cleared by all DCHAN/CCHAN control builders (TS 48.058 9.1).
`buildDataReq`/`buildUnitDataReq` produce BSC->BTS-style frames (useful for testing/loopback of the parser).

- `buildDataReq(chanNr, linkId, l3Payload)` - Encapsulate L3 in DATA_REQ
- `buildDataInd(chanNr, linkId, l3Payload)` - Encapsulate L3 in DATA_IND
- `buildUnitDataReq(chanNr, linkId, l3Payload)` - Unnumbered (connectionless) L3 data, BSC->BTS
- `buildUnitDataInd(chanNr, linkId, l3Payload)` - Unnumbered (connectionless) L3 data

### DCHAN Messages

- `buildChanActivAck(chanNr, frameNumber)` - Channel activation acknowledgment; `frameNumber` is the
  absolute TDMA frame number (0..42431), encoded as the starting-time fields t1p/t3/t2 (TS 48.058)
- `buildChanActivNack(chanNr, cause)` - Channel activation rejection
- `buildRFChanRelAck(chanNr)` - RF channel release acknowledgment
- `buildConnFail(chanNr, cause)` - Connection failure report
- `buildMeasRes(chanNr, measNr, rxlevFull, rxlevSub, rxqFull, rxqSub, dtxDownlink, l1Info)` -
  Measurement results: Uplink Measurements IE with the canonical three value octets (rxlev fields are
  six bits, rxqual fields three bits; extra high bits are discarded)
- `buildHandoDet(chanNr, accessDelay)` - Handover detection

### CCHAN Messages

- `buildPCHLoadInd(pagingLoad)` - CCCH_LOAD_IND for the PCH (TS 48.058 section 8.5.2): channel number
  PCH+AGCH tn 0 (0x90) plus the Paging Load IE (TV, two-octet big-endian value)
- `buildRACHLoadInd(rachTotal, rachBusy, rachAccess)` - CCCH_LOAD_IND for the RACH (TS 48.058 section
  8.5.2): channel number RACH tn 0 (0x88) plus the RACH Load IE (LV: type, length 0x06, three
  big-endian u16 counters per section 9.3.18)
- `buildChanRqd(chanNr, reqRef, accessDelay)` - Channel required from RACH
- `buildDeleteInd(chanNr, fullImmAssInfo)` - Immediate assignment deletion

### Span Overloads

Every method has a `static int buildXxx(std::span<uint8_t> out, ...)` overload that writes directly into a pre-allocated Arena buffer, returning byte count or -1 on error.

---

## 46. Procedure Framework - Protocol Procedure Base Class

**File:** `gsml3parser/stack/procedure.h`
**Namespace:** `gsml3parser`
**Spec:** 3GPP TS 24.008 (procedure lifecycle), TS 04.08

Abstract base class for protocol procedures and the ResponseSink callback mechanism. Each procedure encapsulates a complete GSM Layer 3 protocol flow with its own internal state machine, timers, and message sequence logic. BTS applications feed incoming L3 messages via `feed()`, receive external data via `feedExternalTyped()`, and manage timeouts via `tick()`.

### ResponseSink

Zero-overhead callback type for building protocol responses without heap allocation on the hot path (`gsml3parser/stack/response_sink.h`):

```cpp
struct ResponseSink {
    using Callback = void (*)(SMAction, const ParsedMessage&, const SubscriberSession*, void*);
    Callback fn{nullptr};
    void* ctx{nullptr};
    // RAII copy/move with atomic refcounting for capturing lambdas
    void operator()(SMAction action, const ParsedMessage& msg, const SubscriberSession* session) const;
    explicit operator bool() const noexcept;
};

static_assert(sizeof(ResponseSink) == 2 * sizeof(void*)); // 16 bytes on 64-bit

template<typename F>
ResponseSink makeResponseSink(F f); // wraps a capturing callable (one heap allocation at creation)
```

The BTS application provides this callback when calling `Procedure::feed()`. Inside the callback, invoke `ResponseBuilder` and write bytes into a pre-allocated buffer (Arena).

The sink is an observability hook, not the response-building mechanism itself: it is invoked only from `feed()` with the real incoming message. `feedExternalTyped()` never invokes the sink — on that path the response to send is signaled by the `ResponseToken` in the returned `ProcedureStepResult`.

**Performance:** `ResponseSink` is exactly two machine words (16 bytes) with direct function-pointer invocation — no virtual dispatch, no type erasure, no per-call heap allocation. Capturing lambdas are wrapped with `makeResponseSink()` (one heap allocation at creation, shared by all copies via an atomic refcount); stateless callbacks use the zero-allocation two-argument constructor `ResponseSink{fn, ctx}`.

### ResponseToken

Enum that indicates which L3 message type the caller should build when `ProcedureStepResult.action == SendResponseWithToken`. Used with `ResponseBuilder::buildResponseFromToken()` to generate response bytes in a pre-allocated Arena buffer (zero heap allocation).

```cpp
enum class ResponseToken : uint8_t {
    None = 0,
    // RR responses:
    ImmediateAssignment, AssignmentCommand, ChannelRelease,
    CipheringModeCommand, PhysicalInformation, HandoverCommand,
    PagingRequestType1, PagingRequestType2, PagingRequestType3,
    // MM responses:
    CMServiceAccept, CMServiceReject, IdentityRequest,
    AuthenticationRequest, LocationUpdatingAccept, LocationUpdatingReject,
    TMSIReallocationCommand,
    // CC responses:
    CallProceeding, Alerting, Connect, ConnectAcknowledge,
    Disconnect, Release, ReleaseComplete, Setup,
};
```

| Token | Message | Spec |
|-------|---------|------|
| `ImmediateAssignment` | ImmediateAssignment | TS 04.08 9.1.19 |
| `AssignmentCommand` | AssignmentCommand | TS 04.08 9.1.2 |
| `ChannelRelease` | ChannelRelease | TS 04.08 9.1.7 |
| `CipheringModeCommand` | CipheringModeCommand | TS 04.08 9.1.9 |
| `PhysicalInformation` | PhysicalInformation | TS 04.08 9.1.12 |
| `HandoverCommand` | HandoverCommand | TS 04.08 9.1.40 |
| `PagingRequestType1/2/3` | PagingRequestType1/2/3 | TS 04.08 9.1.25 |
| `CMServiceAccept` | CM Service Accept | TS 04.08 9.2.5 |
| `CMServiceReject` | CM Service Reject | TS 04.08 9.2.6 |
| `IdentityRequest` | IdentityRequest | TS 04.08 9.2.10 |
| `AuthenticationRequest` | AuthenticationRequest | TS 04.08 9.2.2 |
| `LocationUpdatingAccept` | LocationUpdatingAccept | TS 04.08 9.2.13 |
| `LocationUpdatingReject` | LocationUpdatingReject | TS 04.08 9.2.14 |
| `TMSIReallocationCommand` | TMSIReallocationCommand | TS 04.08 9.2.17 |
| `CallProceeding` | CallProceeding | TS 04.08 9.3.3 |
| `Alerting` | Alerting | TS 04.08 9.3.1 |
| `Connect` | Connect | TS 04.08 9.3.5 |
| `ConnectAcknowledge` | ConnectAcknowledge | TS 04.08 9.3.6 |
| `Disconnect` | Disconnect | TS 04.08 9.3.7 |
| `Release` | Release | TS 04.08 9.3.19 |
| `ReleaseComplete` | ReleaseComplete | TS 04.08 9.3.19 |
| `Setup` | Setup | TS 24.008 9.3.2 |

**Memory:** `sizeof(ResponseToken) == 1` byte (uint8_t). Fits inline in `ProcedureStepResult` without exceeding the 32-byte budget.

### ProcedureStepResult

Terminal result from each procedure step:

```cpp
struct ProcedureStepResult {
    enum class Action : uint8_t {
        Continue,               ///< Procedure continues; awaiting next message
        SendResponseWithToken,  ///< Build response using responseToken + ResponseBuilder
                                 ///< (kept even when the procedure terminates in this step)
        WaitingExternal,        ///< Needs external data (RAND from AuC, BSC decision)
        Completed,              ///< Procedure finished successfully (no response pending)
        Failed                  ///< Procedure terminated with an error (no response pending)
    };

    Action action{Action::Continue};
    ResponseToken responseToken{ResponseToken::None};  ///< Which message to build when action == SendResponseWithToken
    procedure::ProcedureResult finalResult{};  ///< Sole terminal indicator
};

static_assert(sizeof(ProcedureStepResult) <= 32);
```

| Field | Type | Description |
|-------|------|-------------|
| `action` | `Action` (uint8_t) | What the caller should do next |
| `responseToken` | `ResponseToken` (uint8_t) | Which L3 message to build; valid when `action == SendResponseWithToken` |
| `finalResult` | `ProcedureResult` | Sole terminal indicator; `state` is Completed/Failed/TimedOut when the procedure is done |

**Response/terminal rule:** if a procedure must send a response, `action == SendResponseWithToken` is ALWAYS the case — even when the procedure reaches a terminal state in the same step. The terminal state is reported exclusively through `finalResult` (state == Completed/Failed). Caller contract:

1. if `action == SendResponseWithToken` → build the response from `responseToken` (`ResponseBuilder::buildResponseFromToken`);
2. if `finalResult.state` is terminal (Completed/Failed/TimedOut) → release the procedure.

A result may therefore carry both a token to build and a terminal `finalResult` (e.g. LocationUpdate VLR-accept: `action == SendResponseWithToken`, `responseToken == LocationUpdatingAccept`, `finalResult.state == Completed`).

**Memory:** `sizeof(ProcedureStepResult) <= 32` bytes. The `responseToken` field (1 byte) names the response to build, keeping the struct within the cache-line budget for millions of concurrent calls.

### Procedure Base Class

Abstract interface that all concrete procedures implement:

| Method | Description |
|--------|-------------|
| `type()` | Returns the `procedure::ProcedureType` identifier |
| `state()` | Returns the current `procedure::ProcedureState` |
| `feed(msg, session, sink)` | Process an incoming L3 message; returns step result |
| `matches(msg)` | Report whether this procedure accepts the given message (PD + MTI). Used by `ProcedureRunner` for precise routing when several procedures are active; base implementation returns `false` |
| `feedExternalTyped(data, session, sink)` | Provide typed external data (`AuthChallenge`, `VLRDecision`, etc.); resume procedure. `session` (nullable) lets the procedure populate the session's `ResponseContext` with the parameters the resulting response needs |
| `tick(delta)` | Advance procedure timers; may return `Failed` on timeout |
| `cancel()` | Explicitly abort the procedure |

**Thread safety:** NOT thread-safe. One instance per logical procedure, single-thread access.
**Memory:** Zero heap allocations for state. Pre-allocated buffers for RAND/SRES data.

### Usage Example

```cpp
#include <gsml3parser/stack/procedure.h>

using namespace gsml3parser;

auto proc = ProcedureFactory::createLocationUpdate();
auto result = proc->feed(incomingMsg, session,
    makeResponseSink([](SMAction action, const ParsedMessage& msg, const SubscriberSession* sess) {
        // Build response via ResponseBuilder into Arena buffer
    }));

if (result.action == ProcedureStepResult::Action::Completed) {
    std::cout << "Procedure finished: " << result.finalResult.reason << "\n";
}
```

---

## 47. Procedure Runner - Concurrent Procedure Manager

**File:** `gsml3parser/stack/procedure_runner.h`
**Namespace:** `gsml3parser`
**Spec:** 3GPP TS 24.008 (procedure orchestration)

Manages concurrent protocol procedures for a single subscriber. Routes incoming L3 messages to the correct active procedure based on Protocol Discriminator (PD), auto-creates new procedures when no matching procedure is active, and automatically cleans up completed/failed procedure slots for reuse.

### ProcedureRunner API

```cpp
class ProcedureRunner {
public:
    ProcedureRunner() = default;

    /// Feed incoming L3 message; routes to active procedure or starts new one.
    /// Routing: the first active procedure whose matches(msg) returns true
    /// receives the message (disambiguates procedures sharing a PD, e.g.
    /// CallRelease vs CallSetup_MO); if none matches, the message is routed by
    /// PD and a new procedure is auto-created when no slot for that PD exists.
    ProcedureStepResult feed(const ParsedMessage& msg, SubscriberSession* session,
                                ResponseSink sink);

    /// Feed typed external data to an active procedure by type.
    /// @p session is passed through to the procedure so it can populate the
    /// session's ResponseContext with the response parameters it learns.
    ProcedureStepResult feedExternalTyped(procedure::ProcedureType type,
                                              SubscriberSession* session,
                                              const ExternalData& data,
                                              ResponseSink sink = {});

    /// Tick all active procedures; auto-cleans terminal slots.
    size_t tickAll(std::chrono::milliseconds delta);

    /// Get active procedure by type, or nullptr.
    [[nodiscard]] Procedure* getActive(procedure::ProcedureType type) noexcept;

    /// Number of currently active procedures.
    [[nodiscard]] size_t activeCount() const noexcept;

    /// Cancel all active procedures and free their slots.
    void cancelAll() noexcept;

    // Zero-alloc active-change observer (same pattern as TimerManager): fired on
    // the 0 -> >0 / >0 -> 0 crossings of activeCount from feed()/feedExternalTyped()
    // /tickAll()/cancelAll(), letting an owner (e.g. SubscriberRegistry) maintain
    // its O(active) tick index without per-message bookkeeping.
    void setOwner(void* owner) noexcept;
    void setOnActiveChange(void (*fn)(void* owner, void* ctx, bool active), void* ctx) noexcept;
};
```

`SubscriberSession::procedures` is wired to the owning `SubscriberRegistry` through these observers, which is what makes `tickAllProcedures()` O(active) instead of O(all sessions).

| Method | Description | Slot Cleanup |
|--------|-------------|--------------|
| `feed(msg, session, sink)` | Route message to active procedure (via `matches()`, then PD fallback) or auto-create. Starting a new procedure resets the session's `ResponseContext` | Auto-frees on Completed/Failed |
| `feedExternalTyped(type, session, data, sink)` | Send typed external data (`ExternalData` variant) by ProcedureType; `session` (nullable) is forwarded to the procedure for `ResponseContext` population | Auto-frees on Completed/Failed |
| `tickAll(delta)` | Advance all timers; returns count of Failed procedures | Auto-frees terminal slots |
| `getActive(type)` | Lookup running procedure | None |
| `activeCount()` | Count active slots | None |
| `cancelAll()` | Cancel and free all slots | Frees all |

**Internal storage:** Fixed `std::array<ProcedureSlot, 8>` — no heap allocation for the runner itself. Procedures are heap-allocated via `unique_ptr`.

### ProcedureFactory

Static factory for creating specific procedure instances:

| Factory Method | Returns | Spec |
|----------------|---------|------|
| `createLocationUpdate()` | `LocationUpdateProcedure` | TS 24.008 4.4.1 |
| `createAuthentication()` | `AuthenticationProcedure` | TS 24.008 4.4.2 |
| `createCipheringMode(algo)` | `CipheringModeProcedure` | TS 24.008 4.4.3 |
| `createCallSetupMO()` | `CallSetupMOPercedure` | TS 24.008 6.1 |
| `createCallSetupMT(number)` | `CallSetupMTProcedure` | TS 24.008 6.1 |
| `createChannelAssignment(type)` | `ChannelAssignmentProcedure` | TS 04.08 9.1.2 |
| `createPaging(identity)` | `PagingProcedure` | TS 04.08 9.1.25 |
| `createHandover(target)` | `HandoverProcedure` | TS 04.08 9.1.40 |
| `createCallRelease(ti, cause)` | `CallReleaseProcedure` | TS 24.008 6.1 |
| `createIMSIDetach()` | `IMSIDetachProcedure` | TS 24.008 4.4.6 |

### Usage Example

```cpp
#include <gsml3parser/stack/procedure_runner.h>

using namespace gsml3parser;

SubscriberRegistry registry;
auto* session = registry.createByTMSI(0x12345678);
ProcedureRunner runner;

// Feed incoming message — procedure auto-created and started.
Arena arena(65536);
auto result = runner.feed(incomingMsg, session,
    [&](SMAction action, const ParsedMessage& msg, const SubscriberSession* sess) {
        uint8_t buf[512];
        int n = ResponseBuilder::buildCMServiceAccept({buf, sizeof(buf)});
        if (n > 0) sendToMS(buf, n);
    });

// Feed typed external decision from VLR (session lets the procedure record
// newTmsi/rejectCause into session->response for the Accept/Reject build).
VLRDecision vlr{true, 0x87654321u, MMRejectCause::Zero};
runner.feedExternalTyped(procedure::ProcedureType::LocationUpdate, session, vlr);

// Tick timers every 100ms.
size_t failed = runner.tickAll(std::chrono::milliseconds(100));
```

---

## 48. Typed External Data - Strongly-Typed External Data Structures

**File:** `gsml3parser/stack/typed_external_data.h`
**Namespace:** `gsml3parser`
**Spec:** 3GPP TS 24.008 (authentication, location update), TS 04.08 (paging, ciphering)

Replaces the opaque `std::span<const uint8_t>` parameter with named, self-documenting structures. Each structure corresponds to a specific type of external data that a BTS application feeds into a procedure via `feedExternalTyped()`. All structures are small (≤ 64 bytes) and passed by const reference to avoid copies.

### AuthChallenge

Authentication challenge data from AuC. Contains RAND (128-bit per TS 24.008) and expected SRES for verification.

```cpp
struct AuthChallenge {
    std::array<uint8_t, 16> rand{};       // 128-bit RAND per GSM spec
    std::array<uint8_t, 4> expectedSres{}; // Expected signed response
};
static_assert(sizeof(AuthChallenge) <= 32);
```

### VLRDecision

VLR decision for location update accept/reject. When accept is true, optional newTmsi may be assigned to the MS. When accept is false, rejectCause indicates the reason.

```cpp
struct VLRDecision {
    bool accept{false};
    std::optional<uint32_t> newTmsi;
    MMRejectCause rejectCause{MMRejectCause::Zero};
};
```

### PagingTrigger

Trigger data for network-initiated paging. Contains the mobile identity to page and the target channel type.

```cpp
struct PagingTrigger {
    L3MobileIdentity identity;
    ChannelType targetChannel{ChannelType::SDCCHType};
};
```

### CipheringParameters

Ciphering activation parameters. `algorithmSelector` determines the ciphering algorithm (0=A5/0, 1=A5/1, etc.).

```cpp
struct CipheringParameters {
    uint8_t algorithmSelector{0};
    bool enableCiphering{true};
};
static_assert(sizeof(CipheringParameters) <= 16);
```

### HandoverTarget

Handover target cell and channel description. Used by the network to instruct MS to switch to a new channel.

```cpp
struct HandoverTarget {
    L3ChannelDescription channel;
    L3CellDescription cell;
};
```

### ExternalData Variant

Unified variant for all external data types. Always pass by `const&` to avoid copying the variant (~64 bytes).

```cpp
using ExternalData = std::variant<
    AuthChallenge,
    VLRDecision,
    PagingTrigger,
    CipheringParameters,
    HandoverTarget
>;
```

### Usage Example

```cpp
#include <gsml3parser/stack/typed_external_data.h>

// Feed authentication challenge from AuC:
AuthChallenge chal{};
std::memcpy(chal.rand.data(), aucRand, 16);
std::memcpy(chal.expectedSres.data(), aucSres, 4);
auto result = orchestrator.feedExternalTyped(chal);

// Feed VLR accept decision:
VLRDecision vlr{true, 0x12345678u, MMRejectCause::Zero};
auto result2 = orchestrator.feedExternalTyped(vlr);
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| `sizeof(AuthChallenge)` | ≤ 32 bytes |
| `sizeof(CipheringParameters)` | ≤ 16 bytes |
| `sizeof(ExternalData)` | ~64 bytes (dominated by largest alternative) |
| Heap allocations | Zero when passed by const reference |

---

## 49. ProcedureStateMixin - CRTP Mixin for Common Procedure Code

**File:** `gsml3parser/stack/procedure_state_mixin.h` (header-only template)
**Namespace:** `gsml3parser`
**Spec:** 3GPP TS 24.008 - Procedure lifecycle and timer management

CRTP mixin that eliminates ~50 lines of duplicated code per procedure (`transitionTo`, `fail`, `complete`, `startTimer`, `stopTimer`, `tick`, `cancel`). Each derived procedure inherits from both `Procedure` and `ProcedureStateMixin<XxxProcedure, State>` via multiple inheritance.

### Template Signature

```cpp
template<typename Derived, typename StateEnum>
class ProcedureStateMixin {
protected:
    StateEnum mCurrentState{};
    procedure::ProcedureState mProcState{procedure::ProcedureState::Initiated};
    std::chrono::milliseconds mTimerRemaining{0};
    L3TimerId mCurrentTimer{L3TimerId::Unknown};
    bool mTimerRunning{false};

    void transitionTo(StateEnum s);
    void fail(std::string_view reason);
    void complete();
    void startTimer(L3TimerId id, std::chrono::milliseconds duration);
    void stopTimer() noexcept;

public:
    [[nodiscard]] ProcedureStepResult doTick(std::chrono::milliseconds delta);
    void doCancel() noexcept;
};
```

### Derived Class Hooks

Each procedure that uses the mixin must implement three private hooks:

| Hook | Called By | Purpose |
|------|-----------|---------|
| `doTransitionTo(State s)` | `transitionTo()` | Map internal state to `ProcedureState` |
| `doFail(std::string_view reason)` | `fail()`, `doTick()` (timeout) | Transition to FAILED state |
| `doComplete()` | `complete()` | Transition to COMPLETED state |

### Usage Pattern

```cpp
class LocationUpdateProcedure : public Procedure,
                                 public ProcedureStateMixin<LocationUpdateProcedure, State> {
public:
    [[nodiscard]] ProcedureStepResult tick(std::chrono::milliseconds delta) override {
        return static_cast<ProcedureStateMixin<LocationUpdateProcedure, State>&>(*this).doTick(delta);
    }
    void cancel() noexcept override {
        static_cast<ProcedureStateMixin<LocationUpdateProcedure, State>&>(*this).doCancel();
    }
private:
    void doTransitionTo(State s) { /* map State -> ProcedureState */ }
    void doFail(std::string_view reason) { mCurrentState = State::FAILED; }
    void doComplete() { mCurrentState = State::COMPLETED; }
};
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| Code size reduction | ~50 lines per procedure eliminated |
| Memory overhead | ~20 bytes per procedure instance (state + timer fields) |
| Runtime overhead | Zero — all methods resolved at compile time via CRTP |
| Header-only | Yes — no .cpp file needed |

---

## 50. Procedure Orchestrator - Chained Protocol Procedures

**File:** `gsml3parser/stack/procedure_orchestrator.h` / `gsml3parser/stack/procedure_orchestrator.cpp`
**Namespace:** `gsml3parser`
**Spec:** 3GPP TS 24.008 - Compound procedure chains (Location Update, Call Setup)

Manages compound procedure chains such as Location Update (CMServiceRequest -> Identity -> Authentication -> CipheringMode -> LocationUpdate) and Call Setup MO (CMServiceRequest -> CallSetupMO). The orchestrator owns a single active `Procedure` at any time, transitions between phases based on procedure outcomes, and updates the `SubscriberSession` FSM states to stay in sync.

**Does NOT store `ParsedMessage` (400-byte variant on 64-bit) internally.** Instead stores the last `ResponseToken` and provides `buildPendingResponse()` for zero-allocation response building. `sizeof(ProcedureOrchestrator)` is 72 bytes (app-owned, one instance per subscriber).

### API

```cpp
class ProcedureOrchestrator {
public:
    ProcedureOrchestrator() = default;

    [[nodiscard]] ProcedureStepResult feed(const ParsedMessage& msg, SubscriberSession* session);
    [[nodiscard]] ProcedureStepResult feedExternalTyped(const ExternalData& data, ResponseSink sink = {});
    size_t tickAll(std::chrono::milliseconds delta);
    void cancelAll() noexcept;

    [[nodiscard]] Procedure* activeProcedure() noexcept;
    [[nodiscard]] const Procedure* activeProcedure() const noexcept;
    [[nodiscard]] ResponseToken lastResponseToken() const noexcept;
    [[nodiscard]] ResponseToken takeRetransmissionToken();  // consume-on-read drain
    [[nodiscard]] int buildPendingResponse(std::span<uint8_t> out,
                                              const SubscriberSession* session) const;
    [[nodiscard]] procedure::ProcedureType chainPhase() const noexcept;
};
```

| Method | Description |
|--------|-------------|
| `feed(msg, session)` | Feed incoming L3 message; orchestrator auto-chains sub-procedures. The orchestrator keeps the session and forwards it to the active procedure (including `feedExternalTyped`), so procedures can populate `session->response`. Non-trigger messages return `{Action::Continue}` while no chain is active. Sub-procedure results are returned as-is: a `Completed`/`Failed` `finalResult` may therefore report a sub-procedure finishing while the chain has already advanced to its next phase |
| `feedExternalTyped(data, sink)` | Feed typed external data to the active chain (AuthChallenge, VLRDecision, CipheringParameters, PagingTrigger, HandoverTarget); the stored session is passed to the procedure for `ResponseContext` population |
| `tickAll(delta)` | Tick the inline-phase timer and the active procedure's timer. LocationUpdate phase: T3103 (5 s), expiry is terminal (`TimedOut`, chain cancelled). IdentityVerification phase: T3102 (3 s) — expiry re-queues the `IdentityRequest` retransmission token (see `takeRetransmissionToken()`) up to 3 times; the 4th expiry fails the chain. Returns the count of failures |
| `takeRetransmissionToken()` | Drain (consume-on-read) the token queued by a phase-timer retransmission, or `ResponseToken::None`. The event loop builds it with `ResponseBuilder::buildResponseFromToken(token, buf, session)` |
| `cancelAll()` | Cancel the active procedure, stop the phase timer, clear any queued retransmission token, and reset the session's `ResponseContext` |
| `activeProcedure()` | Get the current active procedure, or nullptr when in an inline phase |
| `lastResponseToken()` | Get the last response token generated by the chain |
| `buildPendingResponse(out, session)` | Build the response for `mLastToken` (the token from the most recent `SendResponseWithToken` result) into a pre-allocated buffer (zero heap allocation); returns -1 when no token is pending or a parameter is missing. Note: retransmission tokens are NOT `mLastToken` — build those via `buildResponseFromToken` directly with the returned token |
| `chainPhase()` | Get the chain type (ProcedureType, `Unknown` when idle) |

**Chain triggers:** the orchestrator starts a chain only for these messages — MM `CMServiceRequest` with service type Location Updating or MO Call; MM `IMSIDetachIndication`; CC `Disconnect`. Every other CM service type (SMS, emergency, ...) is ignored (`feed()` returns `Continue` and the application owns that message).

**Identity phase semantics:** entered when the session has no TMSI. The initial `IdentityRequest` is queued immediately on the retransmission channel; while the chain awaits an `IdentityResponse`, any `feed()` returns `SendResponseWithToken(IdentityRequest)` and restarts the 3 s T3102 window (retransmitted up to 3 times by `tickAll()`, after which the chain times out). Once the `IdentityResponse` arrives, the chain transitions to Authentication and that `feed()` returns `Continue` — no further Identity Requests are sent.

**Chain lifecycle (auto-reset on terminal state):** when a chain reaches a terminal state (`finalResult.state` is `Completed`/`Failed`/`TimedOut`), the orchestrator automatically returns to the idle state, so the next `feed()` starts a fresh chain — no `cancelAll()` call is needed between chains. `cancelAll()` remains available for explicit aborts. The session's `ResponseContext` is reset when a new chain starts (never between the terminal result and the caller's response build), so stale parameters (RAND, TI, channel) cannot leak across chains.

### Supported Chains

Auto-chains currently triggered by the detector:

| Chain (trigger) | Phases | Terminal event |
|-----------------|--------|----------------|
| Location Update (CMServiceRequest, LU service type) | CMServiceAccept -> Authentication *or* IdentityVerification (TMSI absent) -> CipheringMode (CipheringParameters) -> LocationUpdate (VLRDecision; T3103 5 s) | VLR accept/reject (`LocationUpdatingAccept` / `LocationUpdatingReject`), or T3103/identity timeouts |
| Call Setup MO (CMServiceRequest, MO call service type) | CMServiceAccept -> `CallSetupMOPercedure` (§53) | procedure Completed (`"call_active"`), Failed, or T3101 timeout |
| IMSI Detach (IMSI Detach Indication) | inline single phase: sends CM Service Accept | completed (`"imsi_detach_accept"`); MM FSM -> DEREGISTERED |
| Call Release (CC Disconnect) | inline single phase: records TI + cause, sends CC Release | completed (`"release_sent"`); CC FSM -> RELEASE |

`ChainPhase` additionally defines `CallSetupMT`, `ChannelAssignment`, `Paging`, and `Handover` values, and `createProcedureForPhase()` can construct those procedures — the current detector does not auto-start these chains. Drive them individually via `ProcedureFactory` / `ProcedureRunner` (session-owned) instead.

### Usage Example

```cpp
#include <gsml3parser/stack/procedure_orchestrator.h>

using namespace gsml3parser;

ProcedureOrchestrator orchestrator;
auto result = orchestrator.feed(incomingMsg, session);

if (result.action == ProcedureStepResult::Action::SendResponseWithToken) {
    uint8_t buf[512];
    int n = orchestrator.buildPendingResponse({buf, sizeof(buf)}, session);
    if (n > 0) sendToRadio(buf, n);
}

// Feed external data when procedure enters WaitingExternal:
if (result.action == ProcedureStepResult::Action::WaitingExternal) {
    AuthChallenge chal{};
    // ... fill chal from AuC ...
    auto r2 = orchestrator.feedExternalTyped(chal);
}
```

### Performance Characteristics

| Metric | Value |
|--------|-------|
| Heap allocations during feed() | Zero (uses unique_ptr for current procedure only) |
| ParsedMessage storage | None — stores only ResponseToken (1 byte) |
| Thread safety | NOT thread-safe; one instance per subscriber chain |

---

## 51. Location Update Procedure

**File:** `gsml3parser/stack/procedures/location_update.h`
**Spec:** 3GPP TS 24.008 4.4.1

Full location updating flow with identity check, optional authentication, VLR/BSC decision via `feedExternalTyped(VLRDecision, session)`, and TMSI reallocation. On the VLR decision the procedure records `newTmsi`/`rejectCause` into `session->response` so the Accept/Reject can be built from real parameters.

### State Machine

| State | Trigger | Next State | Response |
|-------|---------|------------|----------|
| `INIT` | Any MM or RR message | `IDENTITY_CHECK` | — |
| `IDENTITY_CHECK` | TMSI known | `AUTH_CHECK` | — |
| `IDENTITY_CHECK` | TMSI unknown | `REQUEST_IDENTITY` | `buildIdentityRequest(IMSI)` |
| `REQUEST_IDENTITY` | IdentityResponse | `AUTH_CHECK` | — |
| `AUTH_CHECK` | AuthChallenge already fed (`mHasRand`) | `SEND_AUTH` (T3106 started) | `buildAuthenticationRequest(rand)` |
| `AUTH_CHECK` | No RAND fed (auth skipped) | `LU_REQUEST` | — |
| `SEND_AUTH` | Any message | `WAIT_AUTH` | — |
| `WAIT_AUTH` | AuthenticationResponse, SRES matches | `LU_REQUEST` | — |
| `WAIT_AUTH` | AuthenticationResponse, SRES missing/invalid or mismatch (MAC_Failure) | `SEND_REJECT` (Failed terminal) | `buildLocationUpdatingReject(MAC_Failure)` |
| `LU_REQUEST` | — | `WAITING_EXTERNAL` | — (forward to VLR) |
| `WAITING_EXTERNAL` | feedExternalTyped: accept | `SEND_ACCEPT` | `buildLocationUpdatingAccept(lai, newTmsi)` |
| `WAITING_EXTERNAL` | feedExternalTyped: reject | `SEND_REJECT` | `buildLocationUpdatingReject(cause)` |
| Any | Timer expired | `FAILED` | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mRandBuffer` | `array<uint8_t, 16>` | Pre-allocated RAND from AuC (128-bit per TS 24.008) |
| `mExpectedSRES` | `array<uint8_t, 4>` | Expected SRES for verification |
| `mLAI` | `L3LocationAreaIdentity` | LAI from MSContext |
| `mNewTmsi` | `optional<uint32_t>` | New TMSI assignment from VLR |

SRES verification is big-endian: `expectedSres[0]` is the MSB, matching the TS 24.008 10.5.1.22 SRES IE encoding.

### Timers

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3106` | 3000ms | Authentication phase (WAIT_AUTH) |
| `T3103` | 5000ms | VLR decision wait (LU_REQUEST/WAITING_EXTERNAL) |

---

## 52. Authentication Procedure

**File:** `gsml3parser/stack/procedures/authentication.h`
**Spec:** 3GPP TS 24.008 4.4.2

Standalone authentication exchange: receives RAND+SRES from AuC via `feedExternalTyped(AuthChallenge, session)`, sends AuthenticationRequest, verifies MS response. The received RAND is copied into `session->response.rand` (`hasRand = true`) so the AuthenticationRequest is built from the real AuC RAND, never a fabricated one.

### State Machine

| State | Trigger | Next State | Response |
|-------|---------|------------|----------|
| `INIT` | feedExternalTyped (AuthChallenge) | `SEND_AUTH_REQ` | — |
| `SEND_AUTH_REQ` | — | `WAIT_RESPONSE` (T3106 started) | `buildAuthenticationRequest(rand)` |
| `WAIT_RESPONSE` | AuthenticationResponse | `VERIFY_SRES` | — |
| `VERIFY_SRES` | SRES matches | `COMPLETED` | — |
| `VERIFY_SRES` | SRES mismatch | `FAILED` | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mRandBuffer` | `array<uint8_t, 16>` | RAND from AuC (128-bit per TS 24.008) |
| `mExpectedSRES` | `array<uint8_t, 4>` | Expected SRES for comparison |

### Timer

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3106` | 3000ms | Authentication response wait |

---

## 53. Call Setup MO Procedure

**File:** `gsml3parser/stack/procedures/call_setup_mo.h`
**Spec:** 3GPP TS 24.008 6.1

Mobile-Originated Call establishment: CMServiceAccept through Setup, Proceeding, TCH assignment, Alerting, Connect, to Active speech path.

### State Machine

Each row emits the listed response token while processing the listed state (the transition to "Next State" happens on the *next* feed step unless a trigger message is named):

| State | Trigger | Next State | Response emitted in this step |
|-------|---------|------------|-------------------------------|
| `INIT` | CMServiceRequest (MO call) | `SERVICE_ACCEPT` | `buildCMServiceAccept()` |
| `SERVICE_ACCEPT` | any feed | `WAIT_SETUP` | — |
| `WAIT_SETUP` | CC Setup (T3101 started, TI recorded to `session->response`) | `PROCEEDING` | `buildCallProceeding(ti)` |
| `PROCEEDING` | any feed (T3101 started) | `ASSIGN_TCH` | `buildAssignmentCommand(channel)` |
| `ASSIGN_TCH` | any feed | `WAIT_ASSIGN_COMPLETE` | — |
| `WAIT_ASSIGN_COMPLETE` | RR AssignmentComplete | `ALERTING` | `buildAlerting(ti)` |
| `ALERTING` | any feed | `CONNECT` | `buildConnect(ti)` |
| `CONNECT` | any feed | `ACTIVE` | `buildConnectAcknowledge(ti)` |
| `ACTIVE` | CC ConnectAcknowledge | `COMPLETED` (`"call_active"`) | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mTI` | `uint8_t` | Transaction Identifier from Setup |

### Timers

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3101` | 3000ms | Call setup phases (Setup, Assignment) |

---

## 54. Call Setup MT Procedure

**File:** `gsml3parser/stack/procedures/call_setup_mt.h`
**Spec:** 3GPP TS 24.008 6.1

Mobile-Terminated Call establishment: page the MS (up to 3 attempts, T3109 5 s each), assign an SDCCH, deliver CC Setup, wait for CallConfirmed, assign TCH, then walk the same MO-style dialog (Alerting/Connect/ConnectAcknowledge) to the Active speech path.

Started by any `feedExternalTyped(...)` call while in `INIT` — it does not inspect the payload. The paged identity is taken from `session->context.identity()` and recorded into `session->response` (`hasIdentity`), so the page is always built from the subscriber's real identity; the dialed number (`mCalledNumber`, from the constructor) is exposed on the session when Setup is emitted (max 19 BCD digits + terminator).

### State Machine

| State | Trigger | Next State | Response emitted in this step |
|-------|---------|------------|-------------------------------|
| `INIT` | any `feedExternalTyped()` (T3109 5 s started) | `PAGE` | `PagingRequestType1` token |
| `PAGE` | any routed feed (T3109 running) | `WAIT_PAGE_RESPONSE` | `PagingRequestType1` token |
| `WAIT_PAGE_RESPONSE` | RR PagingResponse | `ASSIGN_SDCCH` | `buildImmediateAssignment(channel)` |
| `WAIT_PAGE_RESPONSE` | T3109 expiry, attempts < 3 | retry (T3109 restarted) | — (no further page types; the page is re-sent as Type1 on the next routed message) |
| `WAIT_PAGE_RESPONSE` | T3109 expiry, attempts == 3 | `FAILED` (`"timer_expired"`) | — |
| `ASSIGN_SDCCH` | any routed feed | `SEND_SETUP` | `buildSetup(calledNumber, ti)` |
| `SEND_SETUP` | any routed feed (T3101 3 s started) | `WAIT_CONFIRMED` | `buildSetup(calledNumber, ti)` |
| `WAIT_CONFIRMED` | CC CallConfirmed (timer stopped) | `ASSIGN_TCH` | — |
| `ASSIGN_TCH` | any routed feed (T3101 3 s started) | `WAIT_ASSIGN_COMPLETE` | `buildAssignmentCommand(channel)` |
| `WAIT_ASSIGN_COMPLETE` | RR AssignmentComplete | `ALERTING` | `buildAlerting(ti)` |
| `ALERTING` | any routed feed | `CONNECT` | `buildConnect(ti)` |
| `CONNECT` | any routed feed | `ACTIVE` | `buildConnectAcknowledge(ti)` |
| `ACTIVE` | CC ConnectAcknowledge | `COMPLETED` (`"call_active"`) | — |

`matches()` routes exactly: RR PagingResponse/AssignmentComplete, CC CallConfirmed/ConnectAcknowledge.

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mCalledNumber` | `std::string` | Dialed number for Setup message |
| `mTI` | `uint8_t` | Transaction Identifier |
| `mPageAttempt` | `uint8_t` | Current paging attempt (max 3, `MAX_PAGE_ATTEMPTS`) |

### Timers

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3109` | 5000ms per attempt | Paging response wait (up to 3 attempts, then failure) |
| `T3101` | 3000ms | Setup confirmation and TCH assignment waits |

---

## 55. Channel Assignment Procedure

**File:** `gsml3parser/stack/procedures/channel_assignment.h`
**Spec:** 3GPP TS 04.08 9.1.2 / 9.1.35

Channel assignment: receives ChannelRequest or PagingResponse, sends ImmediateAssignment, waits for MS to seize the channel.

### State Machine

| State | Trigger | Next State | Response |
|-------|---------|------------|----------|
| `INIT` | ChannelRequest/PagingResponse | `ALLOCATE_CHANNEL` | — |
| `ALLOCATE_CHANNEL` | pool.allocate(type) | `SEND_IMMEDIATE_ASSIGNMENT` | — |
| `SEND_IMMEDIATE_ASSIGNMENT` | — | `WAIT_SEIZURE` (T3101 started) | `buildImmediateAssignment(channel, ta)` |
| `WAIT_SEIZURE` | First L3 msg on new channel | `COMPLETED` | — |
| `WAIT_SEIZURE` | T3101 expired | `FAILED` (release channel) | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mTargetType` | `ChannelType` | Target channel type to assign |

### Timer

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3101` | 3000ms | Channel seizure wait |

---

## 56. Ciphering Mode Procedure

**File:** `gsml3parser/stack/procedures/ciphering_mode.h`
**Spec:** 3GPP TS 24.008 4.4.3 / TS 04.08 9.1.37

Short procedure to activate ciphering: receives algorithm and key via `feedExternalTyped(CipheringParameters, session)`, sends CipheringModeCommand, waits for CipheringModeComplete from MS. The algorithm selector is recorded into `session->response.cipherAlgo`.

### State Machine

| State | Trigger | Next State | Response |
|-------|---------|------------|----------|
| `INIT` | feedExternalTyped (CipheringParameters) | `SEND_COMMAND` | — |
| `SEND_COMMAND` | — | `WAIT_COMPLETE` | `buildCipheringModeCommand(algo)` |
| `WAIT_COMPLETE` | CipheringModeComplete | `COMPLETED` | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mCipherAlgo` | `uint8_t` | Algorithm ID (0=A5/0, 1=A5/1, etc.) |

### Timer

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3101` | 3000ms | Waiting for CipheringModeComplete after the command is sent (mix-in timer; expiry fails the procedure with `"timer_expired"`) |

---

## 57. Paging Procedure

**File:** `gsml3parser/stack/procedures/paging.h`
**Spec:** 3GPP TS 04.08 9.1.25

Network-initiated paging of MS with up to 3 attempts (Type1, then Type2, then Type3), each page followed by a T3109 wait (5 s). The procedure never auto-triggers — it is started with `feedExternalTyped(PagingTrigger)`; the first page is always `PagingRequestType1`, and the paged identity from the trigger is recorded into `session->response` (`hasIdentity`). The only message `matches()` routes to this procedure is RR `L3PagingResponse`, which completes it (`"page_response_received"`) when awaited — so a retransmission page (State::SEND_PAGE2/3) is emitted on the next routed feed after a T3109 expiry.

### State Machine

| State | Trigger | Next State | Response |
|-------|---------|------------|----------|
| `INIT` | feedExternalTyped (PagingTrigger) | `SEND_PAGE1` | — |
| `SEND_PAGE1` | — | `WAIT_PAGE1` (T3109 started) | PagingRequestType1 |
| `WAIT_PAGE1` | T3109 expired | `SEND_PAGE2` | — |
| `SEND_PAGE2` | — | `WAIT_PAGE2` (T3109 restarted) | PagingRequestType2 |
| `WAIT_PAGE2` | T3109 expired | `SEND_PAGE3` | — |
| `SEND_PAGE3` | — | `WAIT_PAGE3` (T3109 restarted) | PagingRequestType3 |
| `WAIT_PAGE3` | PagingResponse | `COMPLETED` (`"page_response_received"`) | — |
| `WAIT_PAGE3` | T3109 expired | `FAILED` (`"no_page_response"`) | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mIdentity` | `L3MobileIdentity` | Identity to page (from the `PagingTrigger`, also stored in the procedure constructor) |
| `mPageAttempt` | `uint8_t` | Current attempt (max 3, `MAX_PAGE_ATTEMPTS`) |

### Timer

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3109` | 5000ms per attempt | Paging response wait (3 attempts, then failure) |

---

## 58. Handover Procedure

**File:** `gsml3parser/stack/procedures/handover.h`
**Spec:** 3GPP TS 04.08 9.1.40

Handover: receives target channel via `feedExternalTyped(HandoverTarget, session)`, sends HandoverCommand, waits for HandoverComplete or HandoverFailure from MS. The target channel is recorded into `session->response.hoChannel`. After completion, updates MSContext with new channel assignment.

### State Machine

| State | Trigger | Next State | Response |
|-------|---------|------------|----------|
| `INIT` | feedExternalTyped (HandoverTarget) | `SEND_HO_CMD` | — |
| `SEND_HO_CMD` | — | `WAIT_HO_COMPLETE` (T3101 started) | `buildHandoverCommand(target)` |
| `WAIT_HO_COMPLETE` | HandoverComplete | `COMPLETED` | — |
| `WAIT_HO_COMPLETE` | HandoverFailure | `FAILED` | — |
| `WAIT_HO_COMPLETE` | T3101 expired | `FAILED` | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mTargetChannel` | `L3ChannelDescription` | Target channel for handover |

---

## 59. Call Release Procedure

**File:** `gsml3parser/stack/procedures/call_release.h` / `call_release.cpp`
**Spec:** 3GPP TS 24.008 6.1

Call release procedure for terminating an active call: BTS sends the CC clear command (`Disconnect` with its TI + cause), waits for the MS's `Release`, then completes by sending `ReleaseComplete`. Created via `ProcedureFactory::createCallRelease(ti, cause)`; `matches()` accepts CC Disconnect or CC Release (so a runner routes these precisely instead of shadowing a same-PD CallSetup_MO). On every feed, the procedure's TI and cause are exposed on `session->response` so both tokens build with real values.

### State Machine

| State | Trigger | Next State | Response emitted in this step |
|-------|---------|------------|-------------------------------|
| `INIT` | any CC message | `SEND_DISCONNECT` | — |
| `SEND_DISCONNECT` | (fall-through from INIT, T3101 12 s started) | `WAIT_RELEASE` | `buildDisconnect(ti, cause)` via `ResponseToken::Disconnect` |
| `WAIT_RELEASE` | CC Release from MS (terminal, `"release_complete_sent"`) | `COMPLETED` | `buildReleaseComplete(ti)` via `ResponseToken::ReleaseComplete` |
| any non-terminal state | T3101 expired (mix-in timer) | `FAILED` (`"timer_expired"`) | — |

### Internal State

| Member | Type | Purpose |
|--------|------|---------|
| `mTI` | `uint8_t` | Transaction Identifier used in the release dialog |
| `mCause` | `CCCause` | CC cause code sent with the Disconnect |

### Timer

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3101` | 12000ms | Release wait |

---

## 60. IMSI Detach Procedure

**File:** `gsml3parser/stack/procedures/imsi_detach.h` / `imsi_detach.cpp`
**Spec:** 3GPP TS 24.008 4.4.6

Standalone IMSI detach procedure (for use via `ProcedureRunner`; the orchestrator instead runs an inline one-step detach on MM IMSIDetachIndication, see §50): on the MS's IMSI Detach Indication the BTS sends CM Service Accept and waits for any follow-up MM message; a T3112 expiry fails the procedure.

### State Machine

| State | Trigger | Next State | Response emitted in this step |
|-------|---------|------------|-------------------------------|
| `INIT` | any MM message | `SEND_CM_SERVICE_ACCEPT` | — |
| `SEND_CM_SERVICE_ACCEPT` | (fall-through, T3112 5 s started) | `WAIT_DETACH_COMPLETE` | `buildCMServiceAccept()` via `ResponseToken::CMServiceAccept` |
| `WAIT_DETACH_COMPLETE` | any MM message (terminal, `"detach_complete"`) | `COMPLETED` | — |
| `WAIT_DETACH_COMPLETE` | T3112 expired (mix-in timer) | `FAILED` (`"timer_expired"`) | — |

### Timer

| Timer | Default | Used During |
|-------|---------|-------------|
| `T3112` | 5000ms | Detach confirmation wait |

---

## 61. Performance Optimizations Summary

The following optimizations have been applied to achieve high-throughput, low-latency L3 parsing at scale:

### Fixed-Array Handler Tables (ProtocolDispatcher)

Dispatch is a direct index into `std::array<std::array<MessageHandler, 136>, 16>` — no hash computation, node allocation, or pointer chasing on the hot path. The handler table is ~35 KB (35,216 B with domain/TI/fallback slots) and stays L2-cache resident.

### FlatHandler (Zero-Overhead Callbacks)

`FlatHandler` is a two-word struct (fn + ctx) with direct function-pointer calls. Factory functions `makeHandler()` (stateless lambdas) and `makeSharedHandler()` (capturing lambdas, shared_ptr-backed) provide ergonomic wrapping.

### ResponseSink (Zero-Overhead Procedure Callbacks)

`ResponseSink` is a two-word struct (16 bytes) with direct function-pointer calls, used by `Procedure::feed()` and the runner/orchestrator. `makeResponseSink()` wraps capturing lambdas with one heap allocation at creation (refcounted, shared by copies); invocation is allocation-free.

### Fixed-Array Channel Pool

`ChannelPool` uses `std::array<std::vector<ChannelDescriptor>, 32>` (free-lists) + `std::array<std::unordered_set<ChannelDescriptor>, 32>` (allocated tracking) instead of `std::unordered_map<ChannelType, vector>`. O(1) direct index lookup, O(1) `allocate()` (vector pop_back) and O(1) `release()` (unordered_set find/erase).

### ShardedChannelPool (Thread-Safe Concurrency)

`ShardedChannelPool<N>` partitions channels across N shards with per-shard `std::shared_mutex`. Enables near-linear scaling with thread count when the hash distributes work evenly.

### RingBuffer Bitmask Optimization

Ring buffer index wrap-around uses `idx & mMask` (1 CPU cycle) instead of `idx % mCapacity` (20-80 CPU cycles). Capacity is rounded up to the next power of two; one slot is sacrificed for full/empty distinction (standard lock-free ring buffer pattern).

### Zero-Copy Stream Processing

`InlineFramer` and `ZeroCopyStreamProcessor` operate directly on caller-owned memory spans, eliminating intermediate buffer copies. `L3StreamProcessor::processOne()` is now a template method, allowing compiler inlining of the handler lambda.

### Template-Based processOne

`L3StreamProcessor::processOne(F&& handler)` is a template method with C++20 concepts constraint. The compiler can inline and optimize the handler call, eliminating `std::function` type-erasure overhead for this hot path.

---

## 62. C API (gsml3parser_c.h)

A stable C ABI over the C++20 library for FFI consumers (C, Python
ctypes/cffi, Rust, Go). One C89-clean header
(`include/gsml3parser/gsml3parser_c.h`) + one implementation
(`src/c_api.cpp`); no C++ types cross the boundary.

### Scope

| Layer | C API |
|-------|-------|
| Core L3 | `gsml3_parse_l3` / `gsml3_parse_l3_hex` / `gsml3_parse_l3_into` (all 216 message types), `gsml3_message_name/pd/mti/ti/size/dump`, `gsml3_message_write/hex`, `gsml3_config` |
| A-bis RSL | `gsml3_rsl_parse` + accessors (IE/L3 views into the handle's copy) + 14 `gsml3_rsl_build_*` |
| LAPDm | `gsml3_lapdm_frame_decode` (zero-copy) + `gsml3_lapdm_entity` (full FSM, fn+user callbacks) |
| BTS stack | `gsml3_registry` (plain + sharded {4,8,16,32}), borrowed `gsml3_session` (`assigned_tmsi`, timers, transactions), O(active) ticks, channel assignment/release with link index |
| Orchestrator | `gsml3_orchestrator_feed/feedExternal*/tick/build_response/required_size/take_retransmit/cancel_all/chain_phase` + 21 `gsml3_response_build_*` + `gsml3_response_required_size` |
| Typed access | Curated message set: 67 `gsml3_msg_*` typed getters + 44 `gsml3_build_*` typed L3 builders (RR/MM/CC/SMS/SS), plus 21 stateless `gsml3_response_build*` factories |
| Error model | `gsml3_last_error()` / `gsml3_last_error_code()`, `gsml3_abi_version()`, `enum gsml3_error` incl. `GSML3_ERR_BUFFER_TOO_SMALL` / `GSML3_ERR_UNSUPPORTED` / `GSML3_ERR_DUPLICATE` / `GSML3_ERR_INTERNAL` |

### ABI rules

- **Handles.** Owned handles (`gsml3_config`, `gsml3_message`,
  `gsml3_rsl`, `gsml3_registry`, `gsml3_orchestrator`,
  `gsml3_lapdm_entity`) are created by `gsml3_*_new()`/`gsml3_parse_*()`
  and released by the matching `gsml3_*_free()` (NULL-safe).
  `gsml3_session` is a **borrowed** pointer-sized handle owned by the
  registry (zero allocations on create/find; valid until the session is
  removed or the registry is freed). Sessions created from an IMSI are
  keyed by an auto-assigned TMSI — read it with
  `gsml3_session_assigned_tmsi()` (the identity getter stays IMSI).
  Channel assignment and release require the session to be owned by the
  given registry: a foreign or unowned session is rejected with
  `GSML3_ERR_INVALID_ARG` and left untouched.
- **Errors.** Handle-returning functions return NULL; action functions
  return `enum gsml3_error` codes; serializers return bytes written
  (0 = error / buffer too small); orchestrator step results carry the
  code in `gsml3_step_result.error`. Details: `gsml3_last_error()`
  (thread-local message, `""` when none) and
  `gsml3_last_error_code()` (machine-readable class). Every function
  that performs an operation clears any pending error on entry, so a
  successful call always leaves `GSML3_OK`; the release functions
  (`gsml3_*_free`) and the state observers never modify the pending
  error. Read them right after a failed call and copy the string if
  needed longer. A serializer that fails with
  `GSML3_ERR_BUFFER_TOO_SMALL` simply needs a larger buffer: the exact
  size is queryable up front via `gsml3_message_size()` for parsed
  messages, `gsml3_orchestrator_required_size()` for the pending
  response, and `gsml3_response_required_size()` for any token response
  (no guessing and no string comparison required). A duplicate key
  (`GSML3_ERR_DUPLICATE`) is distinguished from an unsupported
  operation flavor (`GSML3_ERR_UNSUPPORTED`, e.g. `clear` /
  `create_by_imsi` on a sharded registry).
- **Validation.** Integer parameters that mirror C++ enums (causes, SAPI,
  channel types, timer IDs, response tokens, ...) and digit strings
  (IMSI, called-party numbers, LAI components) are range-checked at the
  boundary, as are fixed-width frame fields (timeslot number and time
   slot code 0..7, ARFCN 0..4095 (twelve-bit field), timing advance 0..63,
   request-reference
  timings): invalid values fail with `GSML3_ERR_INVALID_ARG` (or NULL / 0)
  and are never truncated into a frame; the reserved TMSI 0 is rejected by
  session keying and by every builder that carries a TMSI. No digit string
  is ever truncated silently.
- **Strings.** `const char*` results (names, last error) are static /
  thread-local — do not free. `char*` results (`gsml3_message_hex`,
  `gsml3_message_dump`) — free with `gsml3_free()`.
- **Buffers.** All serializers write into the caller's buffer
  (`uint8_t* out, size_t maxlen`) — zero heap allocation on the hot
  path. The timer-expiry array of `gsml3_registry_tick_timers()` need not
  be pre-zeroed: every written event is fully initialized.
- **Threading.** Stateless functions are thread-safe. Owned handles are
  single-thread. A registry with `shard_count > 0` makes its
  registry-mediated calls thread-safe (per-shard locks); direct
  `gsml3_session_*` access runs WITHOUT the registry lock in either
  flavor and is the caller's to synchronize: keep one thread per session
  and never use a session concurrently with `gsml3_registry_remove()` of
  it. LAPDm entity callbacks fire synchronously inside receive/send:
  transmit or copy within them, and do not free the owning entity from
  its own callbacks.
- **ABI versioning.** `GSML3_ABI_VERSION` (header) / `gsml3_abi_version()`
  identify this C ABI revision; compare it at startup when linking
  against a prebuilt binary of another build.
- **C89.** The header compiles as strict C89..C17
  (`gcc`/`clang -std=cNN -pedantic-errors -Werror`, MSVC `/TC /W4 /WX`)
  and as C++20; CI enforces this matrix. `tests/c_api_c89_check.c` is the
  reference for consuming the API from plain C.

### Usage example

```c
#include <gsml3parser/gsml3parser_c.h>

int main(void) {
    /* Parse one L3 message from hex. */
    gsml3_message* msg = gsml3_parse_l3_hex("60 0D 00", NULL);
    if (!msg) return 1;
    printf("%s (PD=%d, MTI=0x%02X)\n",
           gsml3_message_name(msg), gsml3_message_pd(msg),
           gsml3_message_mti(msg));
    gsml3_message_free(msg);

    /* High-throughput streaming: one reused handle per thread.
     * gsml3_parse_l3_into reparses in place (zero extra allocation
     * for typical messages); on error the handle keeps its previous
     * content. */
    gsml3_message* hot = gsml3_parse_l3_hex("60 0D 00", NULL);
    if (hot) {
        /* for each frame (buf, len):
           if (gsml3_parse_l3_into(hot, buf, len, NULL) == GSML3_OK) {
               ... use gsml3_message_name(hot) ...
           } */
        gsml3_message_free(hot);
    }

    /* A-bis RSL frame. */
    /* gsml3_rsl* rsl = gsml3_rsl_parse(frame, frame_len);
       const uint8_t* l3 = gsml3_rsl_l3(rsl, &l3_len); ... */

    return 0;
}
```

### Build

The C header is installed with the package
(`install(DIRECTORY include/gsml3parser ...)`); link against the
`gsml3parser` target (static or shared). For shared builds the
`GSML3PARSER_SHARED` definition is propagated automatically
(dllexport/dllimport / default visibility). On MSVC the DLL also
exports its internal C++ symbols so that first-party in-repo tests can
link against them; only the `gsml3_*` C ABI is the stable external
interface of the shared library.

---

## 63. FFI Bindings (Python / Go / Rust)

The C ABI (§62) is consumed through three first-party bindings in `bindings/`,
all of which are stdlib/zero-dependency and cover the same behavioral surface:
the Python binding registers `argtypes`/`restype` for every function in
`gsml3parser_c.h` (enforced by `test_api_surface.py`); the Go and Rust v1
surface covers the core/config/message, A-bis RSL, LAPDm, registry/session and
orchestrator/response functions of §62 plus the typed L3 builders
`gsml3_build_cm_service_request` and `gsml3_build_setup` (the curated
`gsml3_msg_*` typed getters stay in the Python binding).

### Ownership and threading

- Owned handles (`gsml3_config/message/rsl/lapdm_entity/registry/orchestrator`)
  are wrapped with RAII: Python `close()` + context manager + guarded `__del__`,
  Go `Close()` (idempotent), Rust `Drop` (`NonNull` fields, take-pattern). The
  release order in a stack teardown is always entity → orchestrator → registry.
- A session is BORROWED (owned by its registry) in every binding: no free call,
  and wrappers refuse to touch the pointer after the registry closes.
- Owned handles are single-thread per the C ABI. The Rust `GsmL3Stack` is
  `Send` (ownership moves) but intentionally not `Sync` (shared access would
  allow unsynchronized concurrent calls on one entity); Python/Go stacks follow
  the same contract.

### Callback model

LAPDm entity callbacks fire SYNCHRONOUSLY inside C calls and receive spans that
are valid only during the callback. All three bindings therefore use the same
queue model: the callback copies the payload (zero-copy read — ctypes
`string_at`, Go `unsafe.Slice`, Rust `slice::from_raw_parts`) into a lock-
guarded queue and makes no FFI call; the stack drains the queues after the C
call returns, then parses, feeds the orchestrator and emits response frames.
Context is restored from `void* user` via (Python) a `_CallbackContext`
structure kept alive in `GsmL3Stack._c_cb_keepalive` (CFUNCTYPE objects are
GC-protected there), (Go) a `cgo.Handle` read inside the exported bridge, and
(Rust) an `Arc<TrampolineState>` behind `Box::into_raw`, reclaimed exactly once
with `Box::from_raw` after the entity is freed.

### Errors and NULL

Failed calls raise a typed error carrying the C code plus a synchronous copy of
the thread-local message (`GsmL3Error` / Go `*Error` / Rust `GsmL3Error`).
Wrapper-level validation rejects empty/nil input before the FFI boundary for
calls where NULL is not part of the contract; the C-documented NULL-safe entry
points (metadata sentinels, `*_free`, entity stats) pass NULL through and are
covered by `*_NullSafety` tests in each language.

### Versioning

The product version lives in the `VERSION` file at the repository root: one
semver line, no `v` prefix, UTF-8 without BOM — the single source of truth for
every release (the repository has no published releases; the version is bumped
in place from release to release). CMake reads it into `PROJECT_VERSION`
(which feeds `gsml3_version()` through the `GSML3PARSER_VERSION` definition),
the Python package derives both its build-time metadata and runtime
`__version__` from the same file, and the Cargo manifests carry matching
literals that the unified gate rejects on drift (`manifest version check`).
The Go module carries no product version by design. Changing the release
version means editing `VERSION` — nothing else.

### Build and test

The unified gate builds the shared core into `build_bindings/` (flattened to
`build_bindings/bin/`) and runs all three bindings:

```sh
pwsh scripts/verify_bindings.ps1            # core lib + python + go + rust
pwsh scripts/verify_bindings.ps1 -Only go   # single language, reuse with -SkipLib
```

Environment overrides: `GSML3PARSER_LIBRARY` (Python, explicit library path),
`GSML3PARSER_LIB_DIR` (Rust `build.rs`, Python fallback). On Windows the DLL is
discovered via `PATH`; on Linux via `LD_LIBRARY_PATH`. CI runs the same script
on `ubuntu-latest` and `windows-latest` (`.github/workflows/bindings.yml`).
Per-language quickstarts live in [`bindings/README.md`](../bindings/README.md).

---

## Conformance Notes

The library implements encodings defined by:

| Standard | Scope | Coverage |
|----------|-------|----------|
| **GSM 04.06 / 3GPP TS 44.064** | LAPDm protocol for Um interface (format B on dedicated channels) | `LAPDmFrame` zero-copy decode, `LAPDmEntity` full state machine (SABME/UA/DISC), I-frame segmentation/reassembly, T200 retransmission, contention resolution |
| **GSM 04.08 / 3GPP TS 24.008** | Mobile radio interface L3 protocol | RR (98), MM (21), CC (21), GMM (23), SM (24), SMS (5 CP-layer messages) message parsing and generation; SS (3), PDSS1/PDSS2 and Test-Procedure PD passthroughs |
| **GSM 04.07 / 3GPP TS 24.007** | Information element encoding rules | V, TV, TLV, LV formats; H/L rest octet padding (0x2B); bit ordering |
| **GSM 04.80 / 3GPP TS 24.080** | Supplementary services on mobile | Facility, Register, Release Complete messages; SSOpCode/SSErrorCode enums; L3FacilityOpCode TCAP parser; L3USSDData IE |
| **GSM 02.90 / 3GPP TS 23.038** | USSD alphabet and encoding | GSM 7-bit default/extended alphabet, UCS2, DCS handling in L3USSDData |
| **3GPP TS 44.018** | Group call and broadcast call control | GCC (PD=0x00): 8 messages; BCC (PD=0x01): 8 messages (TI-carrying dialog, opaque bodies) |
| **3GPP TS 24.011 / GSM 04.11** | SMS over mobile radio interface | CP layer (5 messages), RP layer (4 messages), TP PDUs (Deliver, Submit, StatusReport, Command) |
| **3GPP TS 23.040 / GSM 03.40** | SMS TPDU formatting and encoding | TP address, TP-DCS, TP-PID, TP-SCTS, GSM 7-bit alphabet |
| **3GPP TS 44.031 / TS 24.027/24.028** | Location services on mobile radio | LSM: L3LocationServiceRequest, L3LocationServiceProviderMessage |
| **GSM 04.08 §10.2** | Packet Domain Supplementary Services and Test Procedure PDs | PDSS1M (PD=0x0d), EXTENDED/PDSS2 (PD=0x0e) and TESTPROC (PD=0x0f) raw-body passthrough parsing |