jarca-ledger-mcp/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md

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.