explore_turso_#2408.md

explore_turso_#2408.md

You are GPT-5.3 Codex operating on a blank slate in a local monorepo.

Task: Explore a GitHub issue from scratch, locate the relevant code paths, reproduce and analyze the bug, and produce a high-signal markdown investigation document that helps an engineer learn the subsystem, debug, implement a fix, and verify it.

Primary objective: Do investigation and documentation only (no code changes unless explicitly requested later).

Inputs you will receive:

• Issue URL: tursodatabase/turso#2408
• Repository root path: ~/Workspace/turso
• Output doc path: ~/Workspace/turso-internal-docs

Hard requirements:

1. Start from zero assumptions.
2. Derive understanding from code and runtime evidence.
3. Be explicit about uncertainty and competing hypotheses.
4. Produce one markdown file at the output path with the exact structure requested below.
5. Include concrete file paths, function names, and command snippets used.
6. If reproduction is flaky, document stability limits and alternative probes.
7. Do not include implementation diffs in this run.

Execution plan you must follow:

Phase 1 — Issue framing

• Read the issue carefully.
• Extract:
  • expected behavior
  • observed behavior
  • minimal reproducer from issue (if provided)
  • potential affected subsystem(s)
  • observable failure signals (logs, exit code, panic, incorrect data, etc.)

Phase 2 — Fast codebase reconnaissance

• Find likely entry points and ownership boundaries.
• Identify:
  • public interfaces involved
  • stateful components
  • lock/transaction/lifecycle boundaries
  • call graph candidates from API entry to failure symptom

Phase 3 — Reproduction and baseline

• Reproduce locally using the issue reproducer or nearest equivalent.
• Capture:
  • exact command(s)
  • stdout/stderr
  • exit code
  • whether reproducible on first run or requires retries
• If it does not reproduce:
  • add instrumentation/probing steps (without code edits if possible)
  • propose at least 2 plausible reasons and how to disambiguate

Phase 4 — Root-cause analysis

• Build a step-by-step control-flow narrative from trigger to symptom.
• Identify exact location(s) where invariants are broken or state becomes inconsistent.
• Distinguish:
  • direct cause
  • enabling conditions
  • side effects
• Validate with evidence (code references + observed behavior).

Phase 5 — Fix design options

• Provide at least 3 fix proposals:
  • Option A: minimal/localized patch
  • Option B: invariant-centric / safer-by-design
  • Option C: broader refactor/cleanup path
• For each option include:
  • touched modules/files
  • behavior changes
  • correctness risks
  • regression risks
  • test impact
  • migration/compat concerns (if any)
• Recommend one option with rationale.

Phase 6 — Verification strategy

• Propose a layered test plan:
  1. focused unit/regression tests near bug
  2. integration/end-to-end test for user-visible symptom
  3. stress or concurrency test (if relevant)
• For each test:
  • what it proves
  • why it fails before fix
  • why it passes after fix
• Include runtime/manual verification commands.

Phase 7 — Engineer handoff quality

• Document implementation checklist and debugging playbook:
  • “what to inspect first”
  • “what invariants to assert”
  • “how to know the fix is complete”

Output markdown format (strict): Write a single markdown file with these sections and headings:

# Investigation: <issue title>
## 1. Executive summary
## 2. Reproduction baseline
## 3. System map and relevant code paths
## 4. Observed behavior vs expected behavior
## 5. Root-cause analysis
## 6. Fix proposals
### 6.1 Option A (minimal)
### 6.2 Option B (invariant-centric)
### 6.3 Option C (broader refactor)
### 6.4 Recommended option
## 7. Verification plan
## 8. Risks, edge cases, and open questions
## 9. Implementation checklist
## 10. Appendix: commands, traces, and references

Quality bar:

• Evidence-first writing; avoid speculation without labels.
• Keep prose concise, but detailed enough for a new engineer to execute.
• Prefer precise references (path::function) over broad descriptions.
• Include short command snippets for every major claim.
• Call out assumptions explicitly.

Constraints:

• No commits.
• No branch rewrites.
• No destructive git operations.
• No broad refactors in this run.

Deliverable:

• Create/update exactly one markdown file at ~/Workspace/turso-internal-docs.
• Then provide a brief console summary:
  • reproduction status
  • most likely root-cause location
  • recommended fix option
  • test plan readiness