# BAT-016 Design: Review decision persistence and reconciliation workbench

## Design Status
- Status: draft
- Owner: delivery-runner to complete with dev-impl input before implementation.

## Required Design Decisions
1. Persistence schema
   - Define exact columns, indexes, uniqueness/idempotency keys, and schema migration path for `review_decisions` and `reconciliation_sessions`.
   - Define whether target payload is JSON text and how sensitive content is minimized.
2. State model
   - Map UI labels to internal `status` and `decision_type` values from REQ-020.
   - Define allowed transitions for pending/decided/held/needs_recheck/ignored.
3. Application contracts
   - Define additive fields returned by review queue, reconciliation report, and uncategorized workbench services.
   - Define compatibility expectations for existing MCP and Streamlit consumers.
4. MCP tool contracts
   - Define names, arguments, responses, error handling, and non-goals for review decision/session tools.
   - Explicitly exclude destructive delete/reset operations.
5. Streamlit interaction model
   - Define minimum UI actions, confirmation patterns, and feedback messages.
6. Verification design
   - Define fixtures and representative scenarios for persistence round-trip, contract compatibility, dashboard behavior, and DB safety.

## Initial Recommendation
Use a common decision envelope with fields aligned to REQ-020 and target-specific payload fields stored as minimal JSON. Use reconciliation sessions as account/basis-date close records and allow review decisions to target either a session or a specific item.

## Design Completion Criteria
- Schema and state transitions are explicit enough for dev-impl to implement without product reinterpretation.
- MCP and Streamlit contracts are additive and testable.
- Verification scenarios map directly to REQ-020 AC 1-10.