# Phase 1: Mutation Safety - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-03-24
**Phase:** 01-mutation-safety
**Areas discussed:** Scope validation, Concurrency model, Verification approach

---

## Scope Validation

| Option                         | Description                                                                                                                       | Selected |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Verify and close (Recommended) | Confirm \_do_replace() is partition-scoped, document the 5 non-hot-path sites as acceptable. MUT-01 already satisfied.            |          |
| Audit all sites                | Migrate every ALTER TABLE DELETE to DELETE IN PARTITION where possible, even admin scripts and kintsugi_log. Belt-and-suspenders. | ✓        |
| Hot path + sidecar only        | Verify \_do_replace() and also migrate sidecar pre-fill DELETE. Leave admin scripts as-is.                                        |          |

**User's choice:** Audit all sites
**Notes:** User wants belt-and-suspenders completeness — no unscoped DELETEs anywhere in the codebase.

---

## Concurrency Model

| Option                            | Description                                                                                                                  | Selected |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- |
| Per-partition locks (Recommended) | Dict of locks keyed by (symbol, threshold_decimal_bps). Different partitions mutate concurrently. Same partition serialized. | ✓        |
| Keep global lock                  | Current behavior. Simpler, zero risk. Workers parallel on fetch+process, serialized on write.                                |          |
| Remove lock entirely              | Let CH handle mutation ordering natively. Risk: two workers repairing same partition could queue.                            |          |

**User's choice:** Per-partition locks
**Notes:** Matches ClickHouse behavior — mutations on different partitions don't conflict.

---

## Verification Approach

| Option                                 | Description                                                                                           | Selected |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------- |
| Production kintsugi pass (Recommended) | Run normal kintsugi catchup on bigblack with 24 workers. Query system.mutations after. Real workload. | ✓        |
| Synthetic load test                    | Script spawning 24 threads on test data. More controlled but less realistic.                          |          |
| Both                                   | Synthetic first, then production. More thorough but more work.                                        |          |

**User's choice:** Production kintsugi pass
**Notes:** Real workload on bigblack is the definitive verification.

---

## Claude's Discretion

- Lock implementation details (defaultdict vs setdefault)
- Whether to add telemetry for lock contention
- Order of migration across call sites

## Deferred Ideas

None — discussion stayed within phase scope.
