---
phase: 03-kintsugi-parquet-trust
plan: 01
subsystem: kintsugi
tags: [parquet, crossover-tid, orphan-bar, gap-repair, stathera]

requires:
  - phase: 01-crossover-tid-utility
    provides: get_crossover_tid(symbol, date) shared utility
provides:
  - Parquet completeness gate in kintsugi repair (rejects incomplete daily files)
  - Orphan bar marking (is_orphan=True) in both Parquet and Vision repair paths
affects: [kintsugi, heartbeat, sidecar]

tech-stack:
  added: []
  patterns:
    - "Crossover TID boundary check: max(agg_trade_id) >= crossover_tid - 1"
    - "Orphan bar marking via is_orphan column on last bar in day-recompute"

key-files:
  created:
    - tests/test_kintsugi_parquet_trust.py
  modified:
    - python/opendeviationbar/kintsugi/repair.py

key-decisions:
  - "Completeness gate runs AFTER ticks are loaded (avoids double-read of Parquet file)"
  - "Crossover lookup failure (None) does NOT block repair -- graceful degradation"
  - "Module-level imports for TickStorage, get_crossover_tid, _stream_bars_with_processor for testability"

patterns-established:
  - "Crossover TID as completeness boundary: all trades up to crossover_tid - 1 belong to the current day"

requirements-completed: [TRUST-01, TRUST-02]

duration: 6min
completed: 2026-03-25
---

# Phase 03 Plan 01: Kintsugi Parquet Trust Summary

**Parquet completeness gate via crossover TID boundary check and orphan bar marking in both Parquet and Vision kintsugi repair paths**

## Performance

- **Duration:** 6 min
- **Started:** 2026-03-25T08:16:09Z
- **Completed:** 2026-03-25T08:21:40Z
- **Tasks:** 1 (TDD: RED + GREEN)
- **Files modified:** 2

## Accomplishments

- Kintsugi now verifies Parquet max(agg_trade_id) against next-day crossover TID before using Parquet as repair source
- Incomplete Parquet files (missing trailing midnight trades) fall back to Vision/REST with WARNING log
- Last bar in both Parquet and Vision repair output marked is_orphan=True (incomplete bar flushed at day boundary)
- 5 tests covering all edge cases (incomplete, complete, crossover unavailable, Parquet orphan, Vision orphan)

## Task Commits

Each task was committed atomically:

1. **Task 1 (RED): Failing tests for completeness gate and orphan marking** - `5e9a411` (test)
2. **Task 1 (GREEN): Parquet completeness gate and orphan bar marking** - `4158185` (feat)

## Files Created/Modified

- `tests/test_kintsugi_parquet_trust.py` - 5 tests: 3 for TRUST-01 completeness gate, 2 for TRUST-02 orphan marking
- `python/opendeviationbar/kintsugi/repair.py` - Completeness gate in \_try_parquet_day_replace, orphan marking in both Parquet and Vision paths

## Decisions Made

- Completeness gate runs after ticks are loaded (line ~398) to avoid double-reading the Parquet file
- Crossover lookup failure (None) proceeds with Parquet anyway with DEBUG log -- don't block repair when API is down
- Moved TickStorage, get_crossover_tid, \_stream_bars_with_processor to module-level imports for clean test patching

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None

## User Setup Required

None - no external service configuration required.

## Known Stubs

None - all code paths are fully wired to production data sources.

## Next Phase Readiness

- Completeness gate and orphan marking ready for production deployment
- No blockers for downstream phases

---

_Phase: 03-kintsugi-parquet-trust_
_Completed: 2026-03-25_
