jarca-ledger-mcp/docs/batches/bat-007_20260630_mcp-response-contract-ci-versioning/design.md

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.