jarca-ledger-mcp/docs/batches/bat-017_20260708_import-provenance-sensitive-data-policy/implementation.md

BAT-017 Implementation Evidence

• Status: implemented-awaiting-qc
• Created At (KST): 2026-07-08 11:33 KST
• Last Updated (KST): 2026-07-09T13:16:10+09:00

Implementation Summary

Slice 01 — provenance foundation, import preview/write sanitization

• Added a shared provenance policy module for source-hash labeling, allowlisted raw-payload JSON serialization, and CSV preview column filtering.
• Stopped new import preview/import write paths from exposing or persisting full local source paths for:
  • KB Bank PDF
  • Toss Bank PDF
  • Toss Securities PDF
  • SeoulPay XLSX
  • CSV preview
• Changed import_batches.filename new writes to masked-basename#source_hash_prefix.
• Minimized transactions.raw_payload for current supported import sources through explicit allowlists.
• Added targeted regression tests for path redaction and forbidden-field non-leak assertions.

Changed Files

• jarca_ledger_mcp/application/imports_service.py
• jarca_ledger_mcp/kb_bank_pdf.py
• jarca_ledger_mcp/seoulpay_xlsx.py
• jarca_ledger_mcp/toss_bank_pdf.py
• jarca_ledger_mcp/toss_securities_pdf.py
• jarca_ledger_mcp/provenance_policy.py
• tests/test_import_provenance_policy.py

Execution Evidence

• python -m pytest -q tests/test_import_provenance_policy.py
  • result: pass (.....)
• python -m ruff check jarca_ledger_mcp/application/imports_service.py jarca_ledger_mcp/kb_bank_pdf.py jarca_ledger_mcp/seoulpay_xlsx.py jarca_ledger_mcp/toss_bank_pdf.py jarca_ledger_mcp/toss_securities_pdf.py jarca_ledger_mcp/provenance_policy.py tests/test_import_provenance_policy.py
  • result: pass (All checks passed!)
• pytest -q tests/test_import_provenance_policy.py tests/test_kb_bank_pdf.py tests/test_seoulpay_xlsx.py tests/test_toss_securities_pdf.py
  • result: pass via dev-impl
• pytest -q tests/test_kb_bank_pdf.py tests/test_seoulpay_xlsx.py tests/test_toss_securities_pdf.py tests/test_service.py
  • result: pass via dev-impl
• pytest -q tests/test_import_provenance_policy.py tests/test_kb_bank_pdf.py tests/test_seoulpay_xlsx.py tests/test_toss_securities_pdf.py tests/test_service.py
  • result: pass via dev-impl
• pytest -q
  • result: pass via dev-impl

Evidence Notes

• Targeted regression confirms preview responses no longer emit full absolute paths.
• CSV preview regression confirms arbitrary raw columns such as secret_note and local_path are suppressed by default.
• Import persistence regression confirms import_batches.filename stores masked basename plus source-hash prefix rather than full paths.
• Import persistence regression confirms transactions.raw_payload stores only the source-specific allowlisted minimum fields for the implemented sources.

Residual Risks / Follow-up

• Slice 01 does not yet complete the MCP provenance exposure contract (minimal / operator-summary / debug-gated).
• Import/read surfaces beyond the new-write preview/import boundary still need review for finance-agent privacy alignment.
• Baseline docs still need BAT-017-specific updates once the exposure contract and final runtime boundary are settled.
• Existing operating DB sanitization remains intentionally out of scope and must stay in the separate follow-up Todo.

Notes

• Implementation must not use Kanban unless the user explicitly re-allows it.

Slice 02A — provenance exposure helper + tests

• Added explicit provenance exposure constants and helper APIs in jarca_ledger_mcp/provenance_policy.py for minimal, operator-summary, and debug-gated.
• Added sanitizer behavior that keeps normalized provenance fields while suppressing full paths, raw document/raw text dumps, passwords, tokens, secrets, and non-allowlisted raw payload keys.
• Added alias helpers sanitize_provenance_envelope(...) and sanitize_provenance_for_exposure(...) for bounded downstream adoption.
• Added helper-level regression coverage in tests/test_import_provenance_policy.py for exposure-level behavior and forbidden-field suppression.

Additional Changed Files (Slice 02A)

• jarca_ledger_mcp/provenance_policy.py
• tests/test_import_provenance_policy.py

Additional Execution Evidence (Slice 02A)

• Supervised impl child result
  • artifact: .stagepilot/worker-supervision/impl-20260709T030219Z/final-result.json
  • result: done (child_exit_code=0)
• python -m pytest -q tests/test_import_provenance_policy.py
  • result: pass (7 passed)
• python -m py_compile jarca_ledger_mcp/provenance_policy.py tests/test_import_provenance_policy.py
  • result: pass
• python -m ruff check jarca_ledger_mcp/provenance_policy.py tests/test_import_provenance_policy.py
  • result: initially blocked in runner environment (No module named ruff from current Python)
• Lead follow-up verification after environment check:
  • . .venv/bin/activate && python -m ruff check jarca_ledger_mcp/provenance_policy.py tests/test_import_provenance_policy.py
    • result: pass (All checks passed!)
  • . .venv/bin/activate && python -m pytest -q tests/test_import_provenance_policy.py
    • result: pass (7 passed)
  • . .venv/bin/activate && python -m py_compile jarca_ledger_mcp/provenance_policy.py tests/test_import_provenance_policy.py
    • result: pass
  • . .venv/bin/activate && python -m ruff check .
    • result: pass (All checks passed!)
  • . .venv/bin/activate && python -m pytest -q
    • result: pass (55 passed, 4 skipped)

Slice 02B — import batch read-surface wiring + baseline docs

• Wired list_ledger_import_batches(...) through the BAT-017 provenance sanitizer so default responses now return minimal provenance and scrub the raw memo field from user-facing payloads.
• Added bounded operator-summary support for import batch listing so masked filename, source-hash prefix, sheet reference, and validation summary are available only when explicitly requested.
• Added MCP adapter pass-through for provenance_exposure on list_ledger_import_batches(...).
• Added explicit debug_provenance_gate=True enforcement before debug-gated provenance can be requested from the import batch listing surface.
• Extended provenance regression coverage for:
  • default/minimal import batch responses
  • explicit operator-summary import batch responses
  • debug-gated access denial without the explicit gate and allow-path with the gate
  • MCP adapter pass-through of the exposure level
• Updated baseline docs (docs/data-model.md, docs/project-structure.md, docs/runtime-flows.md) to record the provenance envelope boundary, raw_payload=minimize, masked filename policy, and read-time exposure split.

Additional Changed Files (Slice 02B)

• docs/data-model.md
• docs/project-structure.md
• docs/runtime-flows.md
• jarca_ledger_mcp/adapters/mcp/server.py
• jarca_ledger_mcp/application/imports_service.py
• tests/test_import_provenance_policy.py

Additional Execution Evidence (Slice 02B)

• . .venv/bin/activate && python -m ruff check jarca_ledger_mcp/application/imports_service.py jarca_ledger_mcp/adapters/mcp/server.py tests/test_import_provenance_policy.py
  • result: pass (All checks passed!)
• . .venv/bin/activate && python -m pytest -q tests/test_import_provenance_policy.py
  • result: pass (11 passed)
• . .venv/bin/activate && python -m ruff check .
  • result: pass (All checks passed!)
• . .venv/bin/activate && python -m pytest -q
  • result: pass (59 passed, 4 skipped)

Updated Residual Risks / Follow-up

• Independent QC, PR creation/push, GitHub CI, and post-merge confirm-req-implemented remain pending.
• StagePilot doctor entrypoint is not present in the current workspace/runtime; this should be classified during QC as environment/tooling debt unless the lead requires a separate setup action before closure.