# Design

## Goals

MoonCIDR models IP addresses, CIDR networks, ranges, and access rules as
small MoonBit value types. The public API is deterministic and has no runtime
dependency, which keeps it suitable for command-line, server, and Wasm use.

## Core Invariants

- IPv4 addresses are stored as one unsigned 32-bit value.
- IPv6 addresses are stored as two unsigned 64-bit values.
- Network constructors always clear host bits before storing an address.
- Parsing returns structured errors; malformed input is never accepted silently.
- Collection-returning accessors return copies so callers cannot mutate state.

## Policy Evaluation

ACL policies use ordered, first-match evaluation. A rule can target one IPv4
address, an inclusive range, or a CIDR network. If no rule matches, the
policy's explicit default decision is returned. Deny-by-default is recommended
for access-control use, and narrow deny exceptions must precede broad allows.

## Failure and Resource Limits

Subnet enumeration is capped at 4096 results to avoid accidental large
allocations. Single-subnet lookup uses 64-bit counting so large prefix
differences cannot overflow before validation. IPv4 range summarization handles
the complete address space explicitly because its size is 2^32.

## Compatibility Boundaries

The ACL text parser is IPv4-focused. IPv6 parsing accepts full and
double-colon-compressed forms but not embedded IPv4 notation or zone IDs.
Network sets use linear scans and are intended for small and medium policy sets.

## Verification

Core behavior is covered by executable tests for valid input, malformed input,
ordering, normalization, overflow boundaries, full-range summarization, and
report generation. CI runs strict check, test, format, interface, and example
commands from a clean checkout.