51 lines
1.8 KiB
Markdown
51 lines
1.8 KiB
Markdown
# 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.
|