# Design overview

`moonbit-deadline` separates deterministic deadline algorithms from the
calendar data supplied by an application. The root package owns the public
types used by callers, while the CLI formats the library's structured results
for human inspection.

## Design principles

1. `Date` represents a proleptic Gregorian calendar date without time-zone or
   timestamp semantics.
2. The same date, rule and calendar always produce the same result.
3. Calendars are injected dependencies. The calculation engine does not embed
   a jurisdiction's legal conclusions or holiday policy.
4. Results retain the natural date, adjusted date and ordered calculation
   steps so applications can audit and explain a decision.
5. Public types live in the root package; parsing, arithmetic and formatting
   helpers remain implementation details unless callers need them directly.

## Calculation model

`DateRule` supports calendar days, business days, weeks, months, years and
sequences of rules. `StartDateRule` makes inclusion or exclusion of the
starting date explicit. `ExtensionPolicy` supports no adjustment, following,
modified following and preceding behavior.

`Calendar` combines a weekend policy, holiday dates, replacement workdays,
version metadata and optional provenance. Replacement workdays are evaluated
before holidays and the weekend policy, allowing an application to model
calendar-specific overrides deterministically.

The calculation result records the starting date, natural deadline, adjusted
deadline, adjustment count, boundary crossings and structured steps. The CLI
renders this result but does not duplicate the calculation algorithm.

## Boundaries and non-goals

The library provides date and calendar computation, not legal advice. It does
not decide jurisdiction, service, filing or contract interpretation. Callers
must select and review the calendar data appropriate for their use case.

The bundled China 2026 calendar is a reproducible demonstration fixture. Its
scope and source are documented in [calendar-data.md](calendar-data.md); it is
not presented as a complete legal database for every region or institution.

## Testing and portability

The implementation is pure MoonBit and is checked across wasm, wasm-gc, JS and
native targets. Core behavior is covered by black-box tests, while the CLI and
benchmark exercise the public package through realistic workflows.