[ClayMav]

Summary

Document that cursor.attach() transfers event delivery on SQL sessions that support attachment, while its duplicate guard only protects one connection. Other live connections can reattach or cancel the execution, so callers must coordinate the handoff.

This is the approved documentation follow-up to #95 and Simon's ownership and cancellation comments. It updates the README and public method docstring.

Related Issues

WBC-1934

Verification

• uv run pre-commit run --all-files: all hooks passed.
• Compared the cursor module's Python AST with main after removing docstrings: implementation unchanged.
• Checked the wording against driver cursor close/reuse and reconnect, and SQL-session ownership/cancellation at commit 79eb0e2.
• Independent review found the transfer wording needed qualification for older SQL sessions that ignore attach. Added that qualification in both places; no substantive findings remain.

Runtime tests were not rerun locally for documentation changes. CI passed on Python 3.10 through 3.14, hosted pre-commit passed, and Salty reviewed with no findings on a1dce3e5179faa4a617d0974b599b27734ace893.

---

Requester Checklist

• I have self-reviewed my own code
• I have added/updated tests that prove my fix/feature works
• I have included visual proof (screenshot, video, or test output) if applicable
• All CI checks are passing
• PR size is S/M, OR I have justified the size and added a walkthrough
• I have updated documentation if needed

Visual Proof

Cursor implementation AST unchanged after excluding docstrings: PASS

Size Justification (if L/XL)

N/A, 11 added documentation lines.

---

Reviewer Checklist

• Requester checklist above is complete
• All CI checks are passing
• Tests adequately cover the changes

Implemented by GPT-6.1 Sol through T3 Code's Codex harness, with an independent agent review.

[ClayMav]

@salty-hambot review

[salty-hambot]

Reviewed by Salty Hambot 🤖🧂 at a1dce3e

No issues found.
_{💰 $0.0835 · 71.4k in / 1.3k out tokens · ⏱️ 12.4s · us.openai.gpt-6-sol high, prompt coverage-v1
💬 To request a re-review, comment @salty-hambot review}