# Compatibility policy

MoonCompat v0.1 uses a conservative, source-interface compatibility policy. The input is the `.mbti` generated by `moon info`, not arbitrary source text.

## Breaking changes

A change is breaking when it can invalidate source code that compiled against the base version:

| Change | Reason |
|---|---|
| Remove or rename a public function, method, type, trait, constant, error, or value | The old symbol no longer resolves |
| Change parameters, optional parameters, return type, `raise`, `async`, or generic constraints | Existing calls or function-value uses may stop type-checking |
| Remove a public field or change its type/visibility | Construction or field access may break |
| Add, remove, or change an enum variant | Exhaustive matches may stop compiling |
| Add or remove a constructor in a public error | Pattern matches and error handling may change |
| Change a trait member or trait visibility | Implementors or callers may stop compiling |
| Remove a public trait implementation | Generic code requiring that implementation may fail |
| Change a type alias target or visibility | Downstream type checking may change |
| Change the package identifier | Imports stop resolving |

Adding an optional function parameter is classified as breaking in v0.1. This is intentionally conservative because functions can be used as values and the generated public signature changes.

## Compatible changes

The following are treated as compatible:

- adding a new public function, type, trait, constant, or value;
- adding a new public trait implementation;
- changing internal implementation details that do not change `.mbti`;
- changing only comments or documentation;
- reordering fields, variants, trait members, or declarations.

## Normalization

The comparator normalizes only representation differences that do not change source-level API meaning:

- runs of ASCII whitespace collapse to one space;
- fields, variants, and trait members are sorted before comparison;
- `derive(Eq, Debug, ...)` is converted into equivalent `pub impl` identities;
- a trait moved from `derive(...)` to an explicit `pub impl` is considered unchanged;
- `Int` and `UInt` are normalized to their MoonBit aliases `Int32` and `UInt32`.

Comments and section headings in generated `.mbti` files are ignored.

## SemVer recommendation

| Result | Recommendation |
|---|---|
| Any breaking change | `major` |
| Compatible additions only | `minor` |
| No public declaration changes | `patch` |

For a pre-1.0 package, teams may still choose a different release policy. MoonCompat reports the mechanically derived recommendation and does not rewrite `moon.mod`.

## Fail-closed behavior

The parser rejects:

- a missing `package` declaration;
- an unterminated declaration block;
- unbalanced closing braces;
- a public syntax form not implemented by parser version `mbti-v1`.

This prevents an unsupported declaration from being silently excluded from the compatibility result.