# BAT-007 Design

## Contract versioning design

- Active MCP success response contract version: `1.0`.
- Version format: `major.minor`.
- Runtime exposure: unexposed. MCP success payloads are not modified to add a common `contract_version` field.
- Source of truth: `docs/interface-contract.md`.
- Snapshot metadata: `tests/contract_snapshots/response_contract_v1_0.json`.

## Change classification

- Breaking / major: required key removal, required key type change, nested object/list shape change that breaks existing consumers.
- Additive / minor: optional field additions and documentation/test metadata additions that preserve existing response semantics.
- Every response-shape-changing REQ/BAT must record contract impact: none, additive minor, or breaking major.

## Contract regression design

Representative first-wave scopes:

- health/status: `service.health_check`, `service.get_ledger_db_status`
- list: `service.list_ledger_accounts`
- report: `service.get_monthly_cashflow_report`
- mutation success envelope: `service.create_ledger_account`

The pytest contract checker validates required keys and required types only. Additional keys are allowed, matching the additive policy.

Synthetic fixture policy:

- Test DB paths are created under pytest `tmp_path`.
- Fixture data uses synthetic names and amounts only.
- No operating DB path, source financial filename, password, raw payload, or real account identifier is used.

## CI design

Required-check contract job names:

- `pytest-regression`
- `dashboard-app-test`
- `dashboard-http-smoke`
- `db-safety-smoke`
- `contract-regression`
- `lint`

`.github/workflows/ci.yml` adds:

- `contract-regression`: `uv run pytest tests/test_contract_regression.py`
- `lint`: `uv run ruff check .`

Actual branch protection toggles remain external GitHub repository settings.