fix: reject orphan checkpoint race

[warren830]

Issue

Fixes #640

Description

A child checkpoint could pass the initial parent-done validation, pause while plugin hooks ran, then enqueue after its parent completed and marked it orphaned. The final enqueue path rechecked execution completion and checkpoint failure, but not the child's _parent_done state.

This change:

• extracts the repeated orphan rejection into _reject_if_parent_done();
• rechecks the child's orphan state in the final validation-and-enqueue region;
• holds _completion_lock and then _parent_done_lock through queue insertion, establishing a single linearization point;
• documents the global _completion_lock → _parent_done_lock order;
• keeps plugin callbacks outside both locks and avoids the parent-done lock for empty checkpoints.

Scope

This PR fixes only the already-known-child race in #640. It deliberately does not reject late-created descendants whose parent was already orphaned; that separate behavior remains tracked by #641.

Red → green

• Unchanged upstream production code: the deterministic regression failed with DID NOT RAISE OrphanedChildException.
• Patched focused test: passed.
• Repeated fresh executions: 25/25 passed.

The regression uses two threading.Event barriers and no sleeps: the child pauses in the plugin hook after initial validation, the parent completes and marks it orphaned, and the child then resumes into the final enqueue attempt.

Testing

• Repository tests: 3351 passed, 2 skipped, 5 subtests.
• Core tests: 1627 passed, 5 subtests.
• Core coverage: 98.09% (98% required).
• OpenTelemetry tests: 149 passed, 92% coverage.
• Examples: 87 passed, 2 skipped.
• Type checks: 77 core source files and 23 OpenTelemetry source files, no errors.
• Ruff format/check: core (77 files), OpenTelemetry (23 files), and examples (155 files), all passed.
• Commit lint and git diff --check: passed.

All validation used the repository-pinned Hatch 1.16.5 and Python 3.12. No AWS call or cloud resource was used.

Fork CI note

Some repository cloud/conformance workflows require AWS secrets, SAM, and live CloudFormation resources that are unavailable to fork PRs. The authoritative local unit, integration, coverage, type-check, and formatting gates above are green; any credential-gated non-required fork check should be treated as an infrastructure limitation rather than a product regression.

License

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.