- **Errors**: Domain-specific error hierarchy (e.g., `TrailerCodecError`, `ValidationError`).

1. **Zod for Validation**: We use Zod for runtime schema validation but wrap it in domain-specific `ValidationError`s to avoid leaking implementation details.

- Added ValidationError codes (TRAILER_TOO_LARGE, TRAILER_NO_SEPARATOR, TRAILER_VALUE_INVALID, TRAILER_INVALID, COMMIT_MESSAGE_INVALID) for granular error diagnostics.

- `TrailerCodecService` exposes the schema bundle, parser, trailer factory, formatter hooks, and helper classes (`MessageNormalizer`, `TitleExtractor`, `BodyComposer`); see `docs/SERVICE.md` for a deeper explanation of how to customize each stage without touching the core service.

Trailer codec enforces strict validation:

| Rule | Constraint | Error Type |

|------|-----------|------------|

| **Message Size** | ≤ 5MB | `ValidationError` |

| **Title** | Must be non-empty string | `ValidationError` |

| **Trailer Key** | Alphanumeric, hyphens, underscores only (`/^[A-Za-z0-9_-]+$/`) | `ValidationError` |

| **Key Length** | ≤ 100 characters (prevents ReDoS) | `ValidationError` |

| **Trailer Value** | Must be non-empty string | `ValidationError` |

**Blank-Line Guard:** Trailers must be separated from the body by a blank line; committing without that empty line results in a `ValidationError`.

| Code | Trigger | Suggested Fix |

| `TRAILER_TOO_LARGE` | Message exceeds 5MB | Split the commit or remove content until the payload fits |

| `TRAILER_NO_SEPARATOR` | Missing blank line before trailers | Insert an empty line between the body and the trailer metadata |

| `TRAILER_VALUE_INVALID` | Trailer value contains newline characters | Remove newlines from the value before encoding |

| `TRAILER_INVALID` | Trailer key or value fails schema validation | Adjust the key/value or pass a custom schema bundle via `TrailerCodecService` |

Each code appears on the thrown `ValidationError` (`src/domain/errors/ValidationError.js`), so you can read `error.code` and `error.meta` to respond. See `API_REFERENCE.md#validation-errors` for the class signature and recommended recovery guidance for each code.

- [`docs/ADVANCED.md`](docs/ADVANCED.md) — Custom schema injection, validation overrides, and advanced integration patterns

- [`docs/PARSER.md`](docs/PARSER.md) — Step-by-step explanation of the backward-walk parser

- [`docs/MIGRATION.md`](docs/MIGRATION.md) — Notes for upgrading from earlier versions

- [`docs/PERFORMANCE.md`](docs/PERFORMANCE.md) — Micro-benchmark insights

- [`docs/RELEASE.md`](docs/RELEASE.md) — Checklist for version bumps and npm publishing

- [`docs/INTEGRATION.md`](docs/INTEGRATION.md) — Git log scripting, streaming decoder, and Git-CMS filtering recipes

- [`docs/SERVICE.md`](docs/SERVICE.md) — How `TrailerCodecService` wires schema, parser, and formatter helpers for customization

- [`API_REFERENCE.md`](API_REFERENCE.md) — Complete catalog of the public exports, their inputs/outputs, and notable knobs

- [`TESTING.md`](TESTING.md) — How to run/extend the Vitest, lint, and format scripts plus contributor tips

`decodeMessage()` returns `{ title: string, body: string, trailers: Record<string,string> }` (see `API_REFERENCE.md#encoding--decoding-helpers`). `.title` is the first commit line, `.body` trims leading/trailing blanks to provide the content between title and trailers, and `.trailers` is an object of normalized lowercase keys (empty when no trailers exist). `formatBodySegment(segment)` expects a string and returns the trimmed segment, optionally keeping a trailing newline when `keepTrailingNewline: true`. `decodeMessage()` throws `ValidationError` on malformed input instead of returning an error object, so callers should wrap calls in try/catch if they want to handle validation failures gracefully.

4. **Validate the separator**: `_validateTrailerSeparation` ensures there is a blank line before the trailers. Messages that omit the blank line now throw `ValidationError`.