Add: Worker.detach_persistent_domain public retention API

[georgebisbas]

Summary

• Adds Worker.detach_persistent_domain(handle): transfers one CommDomain
  from the current run's local journal (_RunResources.live_domains) to
  Worker-level ownership, so a caller can outlive one run's completion fence
  and dispatch many requests against the same retained domain.
• Encapsulates the domain_lock/retired/live_domains transfer as a supported
  operation on Worker, next to the existing public live_domains property.

Why

pypto's persistent distributed execution mode needs exactly this transfer,
and currently does it by reaching directly into _RunResources's private
live_domains, domain_lock, and retired fields from outside simpler.
Nothing in simpler promises that shape, so any refactor inside simpler
can silently invalidate pypto's persistent path.

Relates to hw-native-sys/pypto#2284, which documents this exact private-API
dependency and proposes moving the contract into simpler as a public
retention API. A follow-up pypto PR will migrate pypto's runtime to call
this method instead of reaching into _RunResources directly, and will be
the one to close that issue.

Testing

• tests/ut/py/test_worker/test_detach_persistent_domain.py (new, 3
  tests): transfers ownership and survives the run, keeping the handle
  reachable for close() to reclaim; raises when called outside an
  in-flight run; raises on a second detach of an already-detached
  handle.
• tests/ut/py/test_worker/test_dynamic_alloc_sim.py (existing sibling
  suite over the same Worker/CommDomainHandle machinery, 7 tests) —
  no regression.
• ruff check / ruff format / pyright clean via pre-commit.
• Hardware tests (developer, on-board) — not run from this environment.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: dd340760-fbe7-4370-bf49-f44212d86ebe

📥 Commits

Reviewing files that changed from the base of the PR and between 14e173e and 135ead5.

📒 Files selected for processing (2)

• python/simpler/worker.py
• tests/ut/py/test_worker/test_detach_persistent_domain.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The Worker class now exposes detach_persistent_domain. The method transfers a domain handle from active run resources to worker ownership. Tests cover successful transfer, cleanup during close(), missing-run errors, and stale-handle errors.

Changes

Persistent domain lifecycle

Layer / File(s)	Summary
Detach API and ownership transfer python/simpler/worker.py	Worker.detach_persistent_domain validates the active run and handle claim, removes the run-local entry, and retains the handle in the worker registry.
Lifecycle and ownership tests tests/ut/py/test_worker/test_detach_persistent_domain.py	Simulation tests verify ownership retention, worker cleanup, missing-run rejection, and stale-handle rejection.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 135ea

This change adds persistent communication-domain detachment with lifecycle validation and simulation coverage for ownership transfer, cleanup, and invalid calls. No concrete merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant Orchestrator
  participant Worker
  participant RunResources
  participant WorkerLiveDomains
  Orchestrator->>Worker: detach_persistent_domain(handle)
  Worker->>RunResources: validate active live claim
  Worker->>RunResources: remove handle
  Worker->>WorkerLiveDomains: retain handle
  Worker->>WorkerLiveDomains: reclaim handle on close()

Loading

Poem

A rabbit detaches a domain with care
The Worker keeps watch as it travels there
The run lets go, but the handle stays near
Close gathers it safely when the path is clear
Tests hop through errors and cheer peregrine-style

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 1 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding the public Worker.detach_persistent_domain retention API.
Description check	✅ Passed	The description accurately explains the new API, its ownership-transfer behavior, motivation, error cases, and test coverage. It is directly related to the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 1 files. (1 skipped: 1 too large.)

• Fix all pre-merge checks with AI

Warning

Some tools did not complete. Review the errors below.

🔧 Ruff (0.16.3)

python/simpler/worker.py

�[1;31mruff failed�[0m
�[1mCause:�[0m Required version ==0.14.8 does not match the running version 0.16.3

tests/ut/py/test_worker/test_detach_persistent_domain.py

�[1;31mruff failed�[0m
�[1mCause:�[0m Required version ==0.14.8 does not match the running version 0.16.3

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}