Compare commits
No commits in common. "wkt/wg_pyroute2_read" and "main" have entirely different histories.
wkt/wg_pyr
...
main
|
|
@ -1,38 +0,0 @@
|
||||||
# Docs TODOs
|
|
||||||
|
|
||||||
## Auto-sync README code examples with source
|
|
||||||
|
|
||||||
The `docs/README.rst` has inline code blocks that
|
|
||||||
duplicate actual example files (e.g.
|
|
||||||
`examples/infected_asyncio_echo_server.py`). Every time
|
|
||||||
the public API changes we have to manually sync both.
|
|
||||||
|
|
||||||
Sphinx's `literalinclude` directive can pull code directly
|
|
||||||
from source files:
|
|
||||||
|
|
||||||
```rst
|
|
||||||
.. literalinclude:: ../examples/infected_asyncio_echo_server.py
|
|
||||||
:language: python
|
|
||||||
:caption: examples/infected_asyncio_echo_server.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Or to include only a specific function/section:
|
|
||||||
|
|
||||||
```rst
|
|
||||||
.. literalinclude:: ../examples/infected_asyncio_echo_server.py
|
|
||||||
:language: python
|
|
||||||
:pyobject: aio_echo_server
|
|
||||||
```
|
|
||||||
|
|
||||||
This way the docs always reflect the actual code without
|
|
||||||
manual syncing.
|
|
||||||
|
|
||||||
### Considerations
|
|
||||||
- `README.rst` is also rendered on GitHub/PyPI which do
|
|
||||||
NOT support `literalinclude` - so we'd need a build
|
|
||||||
step or a separate `_sphinx_readme.rst` (which already
|
|
||||||
exists at `docs/github_readme/_sphinx_readme.rst`).
|
|
||||||
- Could use a pre-commit hook or CI step to extract code
|
|
||||||
from examples into the README for GitHub rendering.
|
|
||||||
- Another option: `sphinx-autodoc` style approach where
|
|
||||||
docstrings from the actual module are pulled in.
|
|
||||||
|
|
@ -1,125 +0,0 @@
|
||||||
# `RuntimeVars` env-var lift — design plan
|
|
||||||
|
|
||||||
Status: **draft, awaiting user edits**
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
|
|
||||||
Consolidate the sprawl of pytest CLI flags + ad-hoc env vars +
|
|
||||||
hardcoded fixture defaults into a *single* env-var-encoded
|
|
||||||
runtime-vars envelope, with a typed in-memory representation
|
|
||||||
(`tractor.runtime._state.RuntimeVars`) as the sole source of
|
|
||||||
truth.
|
|
||||||
|
|
||||||
## Why now
|
|
||||||
|
|
||||||
- `--tpt-proto`, `--spawn-backend`, `--diag-on-hang`,
|
|
||||||
`--diag-capture-delay` and (soon) `TRACTOR_REG_ADDR` etc. are
|
|
||||||
proliferating. Each adds a parsing seam.
|
|
||||||
- `tests/devx/test_debugger.py` invokes example scripts as
|
|
||||||
separate subprocesses; they currently can't see the
|
|
||||||
fixture-allocated `reg_addr` at all (root cause of why
|
|
||||||
parametrizing devx scripts on `reg_addr` is on your TODO).
|
|
||||||
- Concurrent pytest sessions on the same host collide on
|
|
||||||
shared defaults (the `registry@1616` race we just fixed is
|
|
||||||
one symptom; per-session unique addr is the structural
|
|
||||||
fix).
|
|
||||||
- `tractor.runtime._state.RuntimeVars: Struct` is already
|
|
||||||
defined and **unused** — its docstring even says it
|
|
||||||
"should be utilized as possible for future calls."
|
|
||||||
|
|
||||||
## Design
|
|
||||||
|
|
||||||
### Module: `tractor/_testing/_rtvars.py`
|
|
||||||
|
|
||||||
Lifted from `modden.runtime.env`, ~50 LOC, no new deps.
|
|
||||||
|
|
||||||
```python
|
|
||||||
_TRACTOR_RT_VARS_OSENV: str = '_TRACTOR_RT_VARS'
|
|
||||||
|
|
||||||
def dump_rtvars(rtvars: RuntimeVars|dict) -> tuple[str, str]:
|
|
||||||
'''str-serialize via `str(dict)` — ast.literal_eval-able'''
|
|
||||||
|
|
||||||
def load_rtvars(env: dict) -> RuntimeVars:
|
|
||||||
'''ast.literal_eval the env-var value, hydrate to struct'''
|
|
||||||
|
|
||||||
def get_rtvars(proc: psutil.Process|None = None) -> RuntimeVars:
|
|
||||||
'''read the var from a target proc's env (or current)'''
|
|
||||||
|
|
||||||
def update_rtvars(
|
|
||||||
rtvars: RuntimeVars|dict|None = None,
|
|
||||||
update_osenv: bool|dict = True,
|
|
||||||
) -> tuple[str, str]:
|
|
||||||
'''mutate + re-encode + (optionally) write to os.environ'''
|
|
||||||
```
|
|
||||||
|
|
||||||
### Encoding choice: `str(dict)` + `ast.literal_eval`
|
|
||||||
|
|
||||||
Pros:
|
|
||||||
- stdlib only
|
|
||||||
- handles all the types tractor's tests need: `str`, `int`,
|
|
||||||
`float`, `bool`, `None`, `list`, `tuple`, `dict`
|
|
||||||
- human-readable in the env (greppable, inspectable via
|
|
||||||
`cat /proc/<pid>/environ | tr '\0' '\n'`)
|
|
||||||
|
|
||||||
Cons:
|
|
||||||
- non-stdlib types (msgspec Structs, `Path`, custom classes)
|
|
||||||
must be lowered first — fine for the test fixture set
|
|
||||||
- not stable across Python versions for esoteric repr cases
|
|
||||||
(we don't hit any)
|
|
||||||
|
|
||||||
Alternatives considered:
|
|
||||||
- **msgpack**: adds a dep + binary form is ungreppable
|
|
||||||
- **json**: doesn't preserve tuples (becomes lists), which is
|
|
||||||
a common type for `reg_addr`
|
|
||||||
- **toml/yaml**: heavier deps, no real benefit
|
|
||||||
|
|
||||||
### `RuntimeVars` becomes the single source of truth
|
|
||||||
|
|
||||||
The legacy `_runtime_vars: dict[str, Any]` global in
|
|
||||||
`runtime/_state.py` becomes a *cached view* of a
|
|
||||||
`RuntimeVars` singleton instance:
|
|
||||||
|
|
||||||
- `get_runtime_vars()` returns either the struct or a
|
|
||||||
`.to_dict()` view depending on caller's preference
|
|
||||||
- `set_runtime_vars(...)` validates against the struct schema
|
|
||||||
- spawn-time SpawnSpec sends the struct (already does
|
|
||||||
conceptually — just gets typed)
|
|
||||||
- `__setattr__` `breakpoint()` debug instrumentation gets
|
|
||||||
removed (unrelated cleanup, mentioned in conversation)
|
|
||||||
|
|
||||||
### Migration path
|
|
||||||
|
|
||||||
**Phase 0** *(prep)*: strip the stray `breakpoint()` from
|
|
||||||
`RuntimeVars.__setattr__`.
|
|
||||||
|
|
||||||
**Phase 1**: land `_rtvars.py` as a leaf module, used only by
|
|
||||||
test infra. Subprocess-spawned scripts in `tests/devx/`
|
|
||||||
read `_TRACTOR_RT_VARS` on startup → reconstruct
|
|
||||||
`RuntimeVars` → call `tractor.open_root_actor(**rtvars.as_kwargs())`.
|
|
||||||
Concurrent runs become deterministic-isolated because each
|
|
||||||
session writes a unique `_registry_addrs` into the env.
|
|
||||||
|
|
||||||
**Phase 2**: migrate runtime callers (`_state.get_runtime_vars`,
|
|
||||||
spawn `SpawnSpec`, `Actor.async_main`) to operate on the
|
|
||||||
struct directly, with the dict as a compat view that gets
|
|
||||||
deprecated.
|
|
||||||
|
|
||||||
**Phase 3** *(structural)*: per-session bindspace subdir
|
|
||||||
`/run/user/<uid>/tractor/<session_uuid>/` — encoded in the
|
|
||||||
rt-vars envelope, picked up by every subactor automatically.
|
|
||||||
Obsoletes the entire bindspace-leak warning class.
|
|
||||||
|
|
||||||
## Open design questions (user input wanted)
|
|
||||||
|
|
||||||
- (placeholder for your edits)
|
|
||||||
- (placeholder)
|
|
||||||
- (placeholder)
|
|
||||||
|
|
||||||
## Out-of-scope for this lift
|
|
||||||
|
|
||||||
- Anything in `modden.runtime.env` related to `Spawn`,
|
|
||||||
`WmCtl`, `Wks` — that's a workspace orchestration layer,
|
|
||||||
not an env-var helper. We only lift the four utility
|
|
||||||
functions + the var name constant.
|
|
||||||
- Switching to msgpack/json — explicitly chosen against
|
|
||||||
above.
|
|
||||||
|
|
@ -1,42 +0,0 @@
|
||||||
{
|
|
||||||
"permissions": {
|
|
||||||
"allow": [
|
|
||||||
"Bash(cp .claude/*)",
|
|
||||||
"Read(.claude/**)",
|
|
||||||
"Read(.claude/skills/run-tests/**)",
|
|
||||||
"Write(.claude/**/*commit_msg*)",
|
|
||||||
"Write(.claude/git_commit_msg_LATEST.md)",
|
|
||||||
"Skill(run-tests)",
|
|
||||||
"Skill(close-wkt)",
|
|
||||||
"Skill(open-wkt)",
|
|
||||||
"Skill(prompt-io)",
|
|
||||||
"Bash(date *)",
|
|
||||||
"Bash(git diff *)",
|
|
||||||
"Bash(git log *)",
|
|
||||||
"Bash(git status)",
|
|
||||||
"Bash(git remote:*)",
|
|
||||||
"Bash(git stash:*)",
|
|
||||||
"Bash(git mv:*)",
|
|
||||||
"Bash(git rev-parse:*)",
|
|
||||||
"Bash(test:*)",
|
|
||||||
"Bash(ls:*)",
|
|
||||||
"Bash(grep:*)",
|
|
||||||
"Bash(find:*)",
|
|
||||||
"Bash(ln:*)",
|
|
||||||
"Bash(cat:*)",
|
|
||||||
"Bash(mkdir:*)",
|
|
||||||
"Bash(gh pr:*)",
|
|
||||||
"Bash(gh api:*)",
|
|
||||||
"Bash(gh issue:*)",
|
|
||||||
"Bash(UV_PROJECT_ENVIRONMENT=py* uv sync:*)",
|
|
||||||
"Bash(UV_PROJECT_ENVIRONMENT=py* uv run:*)",
|
|
||||||
"Bash(echo EXIT:$?:*)",
|
|
||||||
"Bash(echo \"EXIT=$?\")",
|
|
||||||
"Read(/tmp/**)"
|
|
||||||
],
|
|
||||||
"deny": [],
|
|
||||||
"ask": []
|
|
||||||
},
|
|
||||||
"prefersReducedMotion": false,
|
|
||||||
"outputStyle": "default"
|
|
||||||
}
|
|
||||||
|
|
@ -1,225 +0,0 @@
|
||||||
# Commit Message Style Guide for `tractor`
|
|
||||||
|
|
||||||
Analysis based on 500 recent commits from the `tractor` repository.
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
Write commit messages that are technically precise yet casual in
|
|
||||||
tone. Use abbreviations and informal language while maintaining
|
|
||||||
clarity about what changed and why.
|
|
||||||
|
|
||||||
## Subject Line Format
|
|
||||||
|
|
||||||
### Length and Structure
|
|
||||||
- Target: ~50 chars with a hard-max of 67.
|
|
||||||
- Use backticks around code elements (72.2% of commits)
|
|
||||||
- Rarely use colons (5.2%), except for file prefixes
|
|
||||||
- End with '?' for uncertain changes (rare: 0.8%)
|
|
||||||
- End with '!' for important changes (rare: 2.0%)
|
|
||||||
|
|
||||||
### Opening Verbs (Present Tense)
|
|
||||||
|
|
||||||
Most common verbs from analysis:
|
|
||||||
- `Add` (14.4%) - wholly new features/functionality
|
|
||||||
- `Use` (4.4%) - adopt new approach/tool
|
|
||||||
- `Drop` (3.6%) - remove code/feature
|
|
||||||
- `Fix` (2.4%) - bug fixes
|
|
||||||
- `Move`/`Mv` (3.6%) - relocate code
|
|
||||||
- `Adjust` (2.0%) - minor tweaks
|
|
||||||
- `Update` (1.6%) - enhance existing feature
|
|
||||||
- `Bump` (1.2%) - dependency updates
|
|
||||||
- `Rename` (1.2%) - identifier changes
|
|
||||||
- `Set` (1.2%) - configuration changes
|
|
||||||
- `Handle` (1.0%) - add handling logic
|
|
||||||
- `Raise` (1.0%) - add error raising
|
|
||||||
- `Pass` (0.8%) - pass parameters/values
|
|
||||||
- `Support` (0.8%) - add support for something
|
|
||||||
- `Hide` (1.4%) - make private/internal
|
|
||||||
- `Always` (1.4%) - enforce consistent behavior
|
|
||||||
- `Mk` (1.4%) - make/create (abbreviated)
|
|
||||||
- `Start` (1.0%) - begin implementation
|
|
||||||
|
|
||||||
Other frequent verbs: `More`, `Change`, `Extend`, `Disable`, `Log`,
|
|
||||||
`Enable`, `Ensure`, `Expose`, `Allow`
|
|
||||||
|
|
||||||
### Backtick Usage
|
|
||||||
|
|
||||||
Always use backticks for:
|
|
||||||
- Module names: `trio`, `asyncio`, `msgspec`, `greenback`, `stackscope`
|
|
||||||
- Class names: `Context`, `Actor`, `Address`, `PldRx`, `SpawnSpec`
|
|
||||||
- Method names: `.pause_from_sync()`, `._pause()`, `.cancel()`
|
|
||||||
- Function names: `breakpoint()`, `collapse_eg()`, `open_root_actor()`
|
|
||||||
- Decorators: `@acm`, `@context`
|
|
||||||
- Exceptions: `Cancelled`, `TransportClosed`, `MsgTypeError`
|
|
||||||
- Keywords: `finally`, `None`, `False`
|
|
||||||
- Variable names: `tn`, `debug_mode`
|
|
||||||
- Complex expressions: `trio.Cancelled`, `asyncio.Task`
|
|
||||||
|
|
||||||
Most backticked terms in tractor:
|
|
||||||
`trio`, `asyncio`, `Context`, `.pause_from_sync()`, `tn`,
|
|
||||||
`._pause()`, `breakpoint()`, `collapse_eg()`, `Actor`, `@acm`,
|
|
||||||
`.cancel()`, `Cancelled`, `open_root_actor()`, `greenback`
|
|
||||||
|
|
||||||
### Examples
|
|
||||||
|
|
||||||
Good subject lines:
|
|
||||||
```
|
|
||||||
Add `uds` to `._multiaddr`, tweak typing
|
|
||||||
Drop `DebugStatus.shield` attr, add `.req_finished`
|
|
||||||
Use `stackscope` for all actor-tree rendered "views"
|
|
||||||
Fix `.to_asyncio` inter-task-cancellation!
|
|
||||||
Bump `ruff.toml` to target py313
|
|
||||||
Mv `load_module_from_path()` to new `._code_load` submod
|
|
||||||
Always use `tuple`-cast for singleton parent addrs
|
|
||||||
```
|
|
||||||
|
|
||||||
## Body Format
|
|
||||||
|
|
||||||
### General Structure
|
|
||||||
- 43.2% of commits have no body (simple changes)
|
|
||||||
- Use blank line after subject
|
|
||||||
- Max line length: 67 chars
|
|
||||||
- Use `-` bullets for lists (28.0% of commits)
|
|
||||||
- Rarely use `*` bullets (2.4%)
|
|
||||||
|
|
||||||
### Section Markers
|
|
||||||
|
|
||||||
Use these markers to organize longer commit bodies:
|
|
||||||
- `Also,` (most common: 26 occurrences)
|
|
||||||
- `Other,` (13 occurrences)
|
|
||||||
- `Deats,` (11 occurrences) - for implementation details
|
|
||||||
- `Further,` (7 occurrences)
|
|
||||||
- `TODO,` (3 occurrences)
|
|
||||||
- `Impl details,` (2 occurrences)
|
|
||||||
- `Notes,` (1 occurrence)
|
|
||||||
|
|
||||||
### Common Abbreviations
|
|
||||||
|
|
||||||
Use these freely (sorted by frequency):
|
|
||||||
- `msg` (63) - message
|
|
||||||
- `bg` (37) - background
|
|
||||||
- `ctx` (30) - context
|
|
||||||
- `impl` (27) - implementation
|
|
||||||
- `mod` (26) - module
|
|
||||||
- `obvi` (17) - obviously
|
|
||||||
- `tn` (16) - task name
|
|
||||||
- `fn` (15) - function
|
|
||||||
- `vs` (15) - versus
|
|
||||||
- `bc` (14) - because
|
|
||||||
- `var` (14) - variable
|
|
||||||
- `prolly` (9) - probably
|
|
||||||
- `ep` (6) - entry point
|
|
||||||
- `OW` (5) - otherwise
|
|
||||||
- `rn` (4) - right now
|
|
||||||
- `sig` (4) - signal/signature
|
|
||||||
- `deps` (3) - dependencies
|
|
||||||
- `iface` (2) - interface
|
|
||||||
- `subproc` (2) - subprocess
|
|
||||||
- `tho` (2) - though
|
|
||||||
- `ofc` (2) - of course
|
|
||||||
|
|
||||||
### Tone and Style
|
|
||||||
|
|
||||||
- Casual but technical (use `XD` for humor: 23 times)
|
|
||||||
- Use `..` for trailing thoughts (108 occurrences)
|
|
||||||
- Use `Woops,` to acknowledge mistakes (4 subject lines)
|
|
||||||
- Don't be afraid to show personality while being precise
|
|
||||||
|
|
||||||
### Example Bodies
|
|
||||||
|
|
||||||
Simple with bullets:
|
|
||||||
```
|
|
||||||
Add `multiaddr` and bump up some deps
|
|
||||||
|
|
||||||
Since we're planning to use it for (discovery)
|
|
||||||
addressing, allowing replacement of the hacky (pretend)
|
|
||||||
attempt in `tractor._multiaddr` Bp
|
|
||||||
|
|
||||||
Also pin some deps,
|
|
||||||
- make us py312+
|
|
||||||
- use `pdbp` with my frame indexing fix.
|
|
||||||
- mv to latest `xonsh` for fancy cmd/suggestion injections.
|
|
||||||
|
|
||||||
Bump lock file to match obvi!
|
|
||||||
```
|
|
||||||
|
|
||||||
With section markers:
|
|
||||||
```
|
|
||||||
Use `stackscope` for all actor-tree rendered "views"
|
|
||||||
|
|
||||||
Instead of the (much more) limited and hacky `.devx._code`
|
|
||||||
impls, move to using the new `.devx._stackscope` API which
|
|
||||||
wraps the `stackscope` project.
|
|
||||||
|
|
||||||
Deats,
|
|
||||||
- make new `stackscope.extract_stack()` wrapper
|
|
||||||
- port over frame-descing to `_stackscope.pformat_stack()`
|
|
||||||
- move `PdbREPL` to use `stackscope` render approach
|
|
||||||
- update tests for new stack output format
|
|
||||||
|
|
||||||
Also,
|
|
||||||
- tweak log formatting for consistency
|
|
||||||
- add typing hints throughout
|
|
||||||
```
|
|
||||||
|
|
||||||
## Special Patterns
|
|
||||||
|
|
||||||
### WIP Commits
|
|
||||||
Rare (0.2%) - avoid committing WIP if possible
|
|
||||||
|
|
||||||
### Merge Commits
|
|
||||||
Auto-generated (4.4%), don't worry about style
|
|
||||||
|
|
||||||
### File References
|
|
||||||
- Use `module.py` or `.submodule` style
|
|
||||||
- Rarely use `file.py:line` references (0 in analysis)
|
|
||||||
|
|
||||||
### Links
|
|
||||||
- GitHub links used sparingly (3 total)
|
|
||||||
- Prefer code references over external links
|
|
||||||
|
|
||||||
## Footer
|
|
||||||
|
|
||||||
The default footer should credit `claude` (you) for helping generate
|
|
||||||
the commit msg content:
|
|
||||||
|
|
||||||
```
|
|
||||||
(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
|
|
||||||
[claude-code-gh]: https://github.com/anthropics/claude-code
|
|
||||||
```
|
|
||||||
|
|
||||||
Further, if the patch was solely or in part written
|
|
||||||
by `claude`, instead add:
|
|
||||||
|
|
||||||
```
|
|
||||||
(this patch was generated in some part by [`claude-code`][claude-code-gh])
|
|
||||||
[claude-code-gh]: https://github.com/anthropics/claude-code
|
|
||||||
```
|
|
||||||
|
|
||||||
## Summary Checklist
|
|
||||||
|
|
||||||
Before committing, verify:
|
|
||||||
- [ ] Subject line uses present tense verb
|
|
||||||
- [ ] Subject line ~50 chars (hard max 67)
|
|
||||||
- [ ] Code elements wrapped in backticks
|
|
||||||
- [ ] Body lines ≤67 chars
|
|
||||||
- [ ] Abbreviations used where natural
|
|
||||||
- [ ] Casual yet precise tone
|
|
||||||
- [ ] Section markers if body >3 paragraphs
|
|
||||||
- [ ] Technical accuracy maintained
|
|
||||||
|
|
||||||
## Analysis Metadata
|
|
||||||
|
|
||||||
```
|
|
||||||
Source: tractor repository
|
|
||||||
Commits analyzed: 500
|
|
||||||
Date range: 2019-2025
|
|
||||||
Analysis date: 2026-02-08
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
(this style guide was generated by [`claude-code`][claude-code-gh]
|
|
||||||
analyzing commit history)
|
|
||||||
|
|
||||||
[claude-code-gh]: https://github.com/anthropics/claude-code
|
|
||||||
|
|
@ -1,297 +0,0 @@
|
||||||
---
|
|
||||||
name: conc-anal
|
|
||||||
description: >
|
|
||||||
Concurrency analysis for tractor's trio-based
|
|
||||||
async primitives. Trace task scheduling across
|
|
||||||
checkpoint boundaries, identify race windows in
|
|
||||||
shared mutable state, and verify synchronization
|
|
||||||
correctness. Invoke on code segments the user
|
|
||||||
points at, OR proactively when reviewing/writing
|
|
||||||
concurrent cache, lock, or multi-task acm code.
|
|
||||||
argument-hint: "[file:line-range or function name]"
|
|
||||||
allowed-tools:
|
|
||||||
- Read
|
|
||||||
- Grep
|
|
||||||
- Glob
|
|
||||||
- Task
|
|
||||||
---
|
|
||||||
|
|
||||||
Perform a structured concurrency analysis on the
|
|
||||||
target code. This skill should be invoked:
|
|
||||||
|
|
||||||
- **On demand**: user points at a code segment
|
|
||||||
(file:lines, function name, or pastes a snippet)
|
|
||||||
- **Proactively**: when writing or reviewing code
|
|
||||||
that touches shared mutable state across trio
|
|
||||||
tasks — especially `_Cache`, locks, events, or
|
|
||||||
multi-task `@acm` lifecycle management
|
|
||||||
|
|
||||||
## 0. Identify the target
|
|
||||||
|
|
||||||
If the user provides a file:line-range or function
|
|
||||||
name, read that code. If not explicitly provided,
|
|
||||||
identify the relevant concurrent code from context
|
|
||||||
(e.g. the current diff, a failing test, or the
|
|
||||||
function under discussion).
|
|
||||||
|
|
||||||
## 1. Inventory shared mutable state
|
|
||||||
|
|
||||||
List every piece of state that is accessed by
|
|
||||||
multiple tasks. For each, note:
|
|
||||||
|
|
||||||
- **What**: the variable/dict/attr (e.g.
|
|
||||||
`_Cache.values`, `_Cache.resources`,
|
|
||||||
`_Cache.users`)
|
|
||||||
- **Scope**: class-level, module-level, or
|
|
||||||
closure-captured
|
|
||||||
- **Writers**: which tasks/code-paths mutate it
|
|
||||||
- **Readers**: which tasks/code-paths read it
|
|
||||||
- **Guarded by**: which lock/event/ordering
|
|
||||||
protects it (or "UNGUARDED" if none)
|
|
||||||
|
|
||||||
Format as a table:
|
|
||||||
|
|
||||||
```
|
|
||||||
| State | Writers | Readers | Guard |
|
|
||||||
|---------------------|-----------------|-----------------|----------------|
|
|
||||||
| _Cache.values | run_ctx, moc¹ | moc | ctx_key lock |
|
|
||||||
| _Cache.resources | run_ctx, moc | moc, run_ctx | UNGUARDED |
|
|
||||||
```
|
|
||||||
|
|
||||||
¹ `moc` = `maybe_open_context`
|
|
||||||
|
|
||||||
## 2. Map checkpoint boundaries
|
|
||||||
|
|
||||||
For each code path through the target, mark every
|
|
||||||
**checkpoint** — any `await` expression where trio
|
|
||||||
can switch to another task. Use line numbers:
|
|
||||||
|
|
||||||
```
|
|
||||||
L325: await lock.acquire() ← CHECKPOINT
|
|
||||||
L395: await service_tn.start(...) ← CHECKPOINT
|
|
||||||
L411: lock.release() ← (not a checkpoint, but changes lock state)
|
|
||||||
L414: yield (False, yielded) ← SUSPEND (caller runs)
|
|
||||||
L485: no_more_users.set() ← (wakes run_ctx, no switch yet)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key trio scheduling rules to apply:**
|
|
||||||
- `Event.set()` makes waiters *ready* but does NOT
|
|
||||||
switch immediately
|
|
||||||
- `lock.release()` is not a checkpoint
|
|
||||||
- `await sleep(0)` IS a checkpoint
|
|
||||||
- Code in `finally` blocks CAN have checkpoints
|
|
||||||
(unlike asyncio)
|
|
||||||
- `await` inside `except` blocks can be
|
|
||||||
`trio.Cancelled`-masked
|
|
||||||
|
|
||||||
## 3. Trace concurrent task schedules
|
|
||||||
|
|
||||||
Write out the **interleaved execution trace** for
|
|
||||||
the problematic scenario. Number each step and tag
|
|
||||||
which task executes it:
|
|
||||||
|
|
||||||
```
|
|
||||||
[Task A] 1. acquires lock
|
|
||||||
[Task A] 2. cache miss → allocates resources
|
|
||||||
[Task A] 3. releases lock
|
|
||||||
[Task A] 4. yields to caller
|
|
||||||
[Task A] 5. caller exits → finally runs
|
|
||||||
[Task A] 6. users-- → 0, sets no_more_users
|
|
||||||
[Task A] 7. pops lock from _Cache.locks
|
|
||||||
[run_ctx] 8. wakes from no_more_users.wait()
|
|
||||||
[run_ctx] 9. values.pop(ctx_key)
|
|
||||||
[run_ctx] 10. acm __aexit__ → CHECKPOINT
|
|
||||||
[Task B] 11. creates NEW lock (old one popped)
|
|
||||||
[Task B] 12. acquires immediately
|
|
||||||
[Task B] 13. values[ctx_key] → KeyError
|
|
||||||
[Task B] 14. resources[ctx_key] → STILL EXISTS
|
|
||||||
[Task B] 15. 💥 RuntimeError
|
|
||||||
```
|
|
||||||
|
|
||||||
Identify the **race window**: the range of steps
|
|
||||||
where state is inconsistent. In the example above,
|
|
||||||
steps 9–10 are the window (values gone, resources
|
|
||||||
still alive).
|
|
||||||
|
|
||||||
## 4. Classify the bug
|
|
||||||
|
|
||||||
Categorize what kind of concurrency issue this is:
|
|
||||||
|
|
||||||
- **TOCTOU** (time-of-check-to-time-of-use): state
|
|
||||||
changes between a check and the action based on it
|
|
||||||
- **Stale reference**: a task holds a reference to
|
|
||||||
state that another task has invalidated
|
|
||||||
- **Lifetime mismatch**: a synchronization primitive
|
|
||||||
(lock, event) has a shorter lifetime than the
|
|
||||||
state it's supposed to protect
|
|
||||||
- **Missing guard**: shared state is accessed
|
|
||||||
without any synchronization
|
|
||||||
- **Atomicity gap**: two operations that should be
|
|
||||||
atomic have a checkpoint between them
|
|
||||||
|
|
||||||
## 5. Propose fixes
|
|
||||||
|
|
||||||
For each proposed fix, provide:
|
|
||||||
|
|
||||||
- **Sketch**: pseudocode or diff showing the change
|
|
||||||
- **How it closes the window**: which step(s) from
|
|
||||||
the trace it eliminates or reorders
|
|
||||||
- **Tradeoffs**: complexity, perf, new edge cases,
|
|
||||||
impact on other code paths
|
|
||||||
- **Risk**: what could go wrong (deadlocks, new
|
|
||||||
races, cancellation issues)
|
|
||||||
|
|
||||||
Rate each fix: `[simple|moderate|complex]` impl
|
|
||||||
effort.
|
|
||||||
|
|
||||||
## 6. Output format
|
|
||||||
|
|
||||||
Structure the full analysis as:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
## Concurrency analysis: `<target>`
|
|
||||||
|
|
||||||
### Shared state
|
|
||||||
<table from step 1>
|
|
||||||
|
|
||||||
### Checkpoints
|
|
||||||
<list from step 2>
|
|
||||||
|
|
||||||
### Race trace
|
|
||||||
<interleaved trace from step 3>
|
|
||||||
|
|
||||||
### Classification
|
|
||||||
<bug type from step 4>
|
|
||||||
|
|
||||||
### Fixes
|
|
||||||
<proposals from step 5>
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tractor-specific patterns to watch
|
|
||||||
|
|
||||||
These are known problem areas in tractor's
|
|
||||||
concurrency model. Flag them when encountered:
|
|
||||||
|
|
||||||
### `_Cache` lock vs `run_ctx` lifetime
|
|
||||||
|
|
||||||
The `_Cache.locks` entry is managed by
|
|
||||||
`maybe_open_context` callers, but `run_ctx` runs
|
|
||||||
in `service_tn` — a different task tree. Lock
|
|
||||||
pop/release in the caller's `finally` does NOT
|
|
||||||
wait for `run_ctx` to finish tearing down. Any
|
|
||||||
state that `run_ctx` cleans up in its `finally`
|
|
||||||
(e.g. `resources.pop()`) is vulnerable to
|
|
||||||
re-entry races after the lock is popped.
|
|
||||||
|
|
||||||
### `values.pop()` → acm `__aexit__` → `resources.pop()` gap
|
|
||||||
|
|
||||||
In `_Cache.run_ctx`, the inner `finally` pops
|
|
||||||
`values`, then the acm's `__aexit__` runs (which
|
|
||||||
has checkpoints), then the outer `finally` pops
|
|
||||||
`resources`. This creates a window where `values`
|
|
||||||
is gone but `resources` still exists — a classic
|
|
||||||
atomicity gap.
|
|
||||||
|
|
||||||
### Global vs per-key counters
|
|
||||||
|
|
||||||
`_Cache.users` as a single `int` (pre-fix) meant
|
|
||||||
that users of different `ctx_key`s inflated each
|
|
||||||
other's counts, preventing teardown when one key's
|
|
||||||
users hit zero. Always verify that per-key state
|
|
||||||
(`users`, `locks`) is actually keyed on `ctx_key`
|
|
||||||
and not on `fid` or some broader key.
|
|
||||||
|
|
||||||
### `Event.set()` wakes but doesn't switch
|
|
||||||
|
|
||||||
`trio.Event.set()` makes waiting tasks *ready* but
|
|
||||||
the current task continues executing until its next
|
|
||||||
checkpoint. Code between `.set()` and the next
|
|
||||||
`await` runs atomically from the scheduler's
|
|
||||||
perspective. Use this to your advantage (or watch
|
|
||||||
for bugs where code assumes the woken task runs
|
|
||||||
immediately).
|
|
||||||
|
|
||||||
### `except` block checkpoint masking
|
|
||||||
|
|
||||||
`await` expressions inside `except` handlers can
|
|
||||||
be masked by `trio.Cancelled`. If a `finally`
|
|
||||||
block runs from an `except` and contains
|
|
||||||
`lock.release()`, the release happens — but any
|
|
||||||
`await` after it in the same `except` may be
|
|
||||||
swallowed. This is why `maybe_open_context`'s
|
|
||||||
cache-miss path does `lock.release()` in a
|
|
||||||
`finally` inside the `except KeyError`.
|
|
||||||
|
|
||||||
### Cancellation in `finally`
|
|
||||||
|
|
||||||
Unlike asyncio, trio allows checkpoints in
|
|
||||||
`finally` blocks. This means `finally` cleanup
|
|
||||||
that does `await` can itself be cancelled (e.g.
|
|
||||||
by nursery shutdown). Watch for cleanup code that
|
|
||||||
assumes it will run to completion.
|
|
||||||
|
|
||||||
### Unbounded waits in cleanup paths
|
|
||||||
|
|
||||||
Any `await <event>.wait()` in a teardown path is
|
|
||||||
a latent deadlock unless the event's setter is
|
|
||||||
GUARANTEED to fire. If the setter depends on
|
|
||||||
external state (peer disconnects, child process
|
|
||||||
exit, subsequent task completion) that itself
|
|
||||||
depends on the current task's progress, you have
|
|
||||||
a mutual wait.
|
|
||||||
|
|
||||||
Rule: **bound every `await X.wait()` in cleanup
|
|
||||||
paths with `trio.move_on_after()`** unless you
|
|
||||||
can prove the setter is unconditionally reachable
|
|
||||||
from the state at the await site. Concrete recent
|
|
||||||
example: `ipc_server.wait_for_no_more_peers()` in
|
|
||||||
`async_main`'s finally (see
|
|
||||||
`ai/conc-anal/subint_forkserver_test_cancellation_leak_issue.md`
|
|
||||||
"probe iteration 3") — it was unbounded, and when
|
|
||||||
one peer-handler was stuck the wait-for-no-more-
|
|
||||||
peers event never fired, deadlocking the whole
|
|
||||||
actor-tree teardown cascade.
|
|
||||||
|
|
||||||
### The capture-pipe-fill hang pattern (grep this first)
|
|
||||||
|
|
||||||
When investigating any hang in the test suite
|
|
||||||
**especially under fork-based backends**, first
|
|
||||||
check whether the hang reproduces under `pytest
|
|
||||||
-s` (`--capture=no`). If `-s` makes it go away
|
|
||||||
you're not looking at a trio concurrency bug —
|
|
||||||
you're looking at a Linux pipe-buffer fill.
|
|
||||||
|
|
||||||
Mechanism: pytest replaces fds 1,2 with pipe
|
|
||||||
write-ends. Fork-child subactors inherit those
|
|
||||||
fds. High-volume error-log tracebacks (cancel
|
|
||||||
cascade spew) fill the 64KB pipe buffer. Child
|
|
||||||
`write()` blocks. Child can't exit. Parent's
|
|
||||||
`waitpid`/pidfd wait blocks. Deadlock cascades up
|
|
||||||
the tree.
|
|
||||||
|
|
||||||
Pre-existing guards in `tests/conftest.py` encode
|
|
||||||
this knowledge — grep these BEFORE blaming
|
|
||||||
concurrency:
|
|
||||||
|
|
||||||
```python
|
|
||||||
# tests/conftest.py:258
|
|
||||||
if loglevel in ('trace', 'debug'):
|
|
||||||
# XXX: too much logging will lock up the subproc (smh)
|
|
||||||
loglevel: str = 'info'
|
|
||||||
|
|
||||||
# tests/conftest.py:316
|
|
||||||
# can lock up on the `_io.BufferedReader` and hang..
|
|
||||||
stderr: str = proc.stderr.read().decode()
|
|
||||||
```
|
|
||||||
|
|
||||||
Full post-mortem +
|
|
||||||
`ai/conc-anal/subint_forkserver_test_cancellation_leak_issue.md`
|
|
||||||
for the canonical reproduction. Cost several
|
|
||||||
investigation sessions before catching it —
|
|
||||||
because the capture-pipe symptom was masked by
|
|
||||||
deeper cascade-deadlocks. Once the cascades were
|
|
||||||
fixed, the tree tore down enough to generate
|
|
||||||
pipe-filling log volume → capture-pipe finally
|
|
||||||
surfaced. Grep-note for future-self: **if a
|
|
||||||
multi-subproc tractor test hangs, `pytest -s`
|
|
||||||
first, conc-anal second.**
|
|
||||||
|
|
@ -1,241 +0,0 @@
|
||||||
# PR/Patch-Request Description Format Reference
|
|
||||||
|
|
||||||
Canonical structure for `tractor` patch-request
|
|
||||||
descriptions, designed to work across GitHub,
|
|
||||||
Gitea, SourceHut, and GitLab markdown renderers.
|
|
||||||
|
|
||||||
**Line length: wrap at 72 chars** for all prose
|
|
||||||
content (Summary bullets, Motivation paragraphs,
|
|
||||||
Scopes bullets, etc.). Fill lines *to* 72 — don't
|
|
||||||
stop short at 50-65. Only raw URLs in
|
|
||||||
reference-link definitions may exceed this.
|
|
||||||
|
|
||||||
## Template
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
<!-- pr-msg-meta
|
|
||||||
branch: <branch-name>
|
|
||||||
base: <base-branch>
|
|
||||||
submitted:
|
|
||||||
github: ___
|
|
||||||
gitea: ___
|
|
||||||
srht: ___
|
|
||||||
-->
|
|
||||||
|
|
||||||
## <Title: present-tense verb + backticked code>
|
|
||||||
|
|
||||||
### Summary
|
|
||||||
- [<hash>][<hash>] Description of change ending
|
|
||||||
with period.
|
|
||||||
- [<hash>][<hash>] Another change description
|
|
||||||
ending with period.
|
|
||||||
- [<hash>][<hash>] [<hash>][<hash>] Multi-commit
|
|
||||||
change description.
|
|
||||||
|
|
||||||
### Motivation
|
|
||||||
<1-2 paragraphs: problem/limitation first,
|
|
||||||
then solution. Hard-wrap at 72 chars.>
|
|
||||||
|
|
||||||
### Scopes changed
|
|
||||||
- [<hash>][<hash>] `pkg.mod.func()` — what
|
|
||||||
changed.
|
|
||||||
* [<hash>][<hash>] Also adjusts
|
|
||||||
`.related_thing()` in same module.
|
|
||||||
- [<hash>][<hash>] `tests.test_mod` — new/changed
|
|
||||||
test coverage.
|
|
||||||
|
|
||||||
<!--
|
|
||||||
### Cross-references
|
|
||||||
Also submitted as
|
|
||||||
[github-pr][] | [gitea-pr][] | [srht-patch][].
|
|
||||||
|
|
||||||
### Links
|
|
||||||
- [relevant-issue-or-discussion](url)
|
|
||||||
- [design-doc-or-screenshot](url)
|
|
||||||
-->
|
|
||||||
|
|
||||||
(this pr content was generated in some part by
|
|
||||||
[`claude-code`][claude-code-gh])
|
|
||||||
|
|
||||||
[<hash>]: https://<service>/<owner>/<repo>/commit/<hash>
|
|
||||||
[claude-code-gh]: https://github.com/anthropics/claude-code
|
|
||||||
|
|
||||||
<!-- cross-service pr refs (fill after submit):
|
|
||||||
[github-pr]: https://github.com/<owner>/<repo>/pull/___
|
|
||||||
[gitea-pr]: https://<host>/<owner>/<repo>/pulls/___
|
|
||||||
[srht-patch]: https://git.sr.ht/~<owner>/<repo>/patches/___
|
|
||||||
-->
|
|
||||||
```
|
|
||||||
|
|
||||||
## Markdown Reference-Link Strategy
|
|
||||||
|
|
||||||
Use reference-style links for ALL commit hashes
|
|
||||||
and cross-service PR refs to ensure cross-service
|
|
||||||
compatibility:
|
|
||||||
|
|
||||||
**Inline usage** (in bullets):
|
|
||||||
```markdown
|
|
||||||
- [f3726cf9][f3726cf9] Add `reg_err_types()`
|
|
||||||
for custom exc lookup.
|
|
||||||
```
|
|
||||||
|
|
||||||
**Definition** (bottom of document):
|
|
||||||
```markdown
|
|
||||||
[f3726cf9]: https://github.com/goodboy/tractor/commit/f3726cf9
|
|
||||||
```
|
|
||||||
|
|
||||||
### Why reference-style?
|
|
||||||
- Keeps prose readable without long inline URLs.
|
|
||||||
- All URLs in one place — trivially swappable
|
|
||||||
per-service.
|
|
||||||
- Most git services auto-link bare SHAs anyway,
|
|
||||||
but explicit refs guarantee it works in *any*
|
|
||||||
md renderer.
|
|
||||||
- The `[hash][hash]` form is self-documenting —
|
|
||||||
display text matches the ref ID.
|
|
||||||
- Cross-service PR refs use the same mechanism:
|
|
||||||
`[github-pr][]` resolves via a ref-link def
|
|
||||||
at the bottom, trivially fillable post-submit.
|
|
||||||
|
|
||||||
## Cross-Service PR Placeholder Mechanism
|
|
||||||
|
|
||||||
The generated description includes three layers
|
|
||||||
of cross-service support, all using native md
|
|
||||||
reference-links:
|
|
||||||
|
|
||||||
### 1. Metadata comment (top of file)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
<!-- pr-msg-meta
|
|
||||||
branch: remote_exc_type_registry
|
|
||||||
base: main
|
|
||||||
submitted:
|
|
||||||
github: ___
|
|
||||||
gitea: ___
|
|
||||||
srht: ___
|
|
||||||
-->
|
|
||||||
```
|
|
||||||
|
|
||||||
A YAML-ish HTML comment block. The `___`
|
|
||||||
placeholders get filled with PR/patch numbers
|
|
||||||
after submission. Machine-parseable for tooling
|
|
||||||
(e.g. `gish`) but invisible in rendered md.
|
|
||||||
|
|
||||||
### 2. Cross-references section (in body)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
<!--
|
|
||||||
### Cross-references
|
|
||||||
Also submitted as
|
|
||||||
[github-pr][] | [gitea-pr][] | [srht-patch][].
|
|
||||||
-->
|
|
||||||
```
|
|
||||||
|
|
||||||
Commented out at generation time. After submitting
|
|
||||||
to multiple services, uncomment and the ref-links
|
|
||||||
resolve via the stubs at the bottom.
|
|
||||||
|
|
||||||
### 3. Ref-link stubs (bottom of file)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
<!-- cross-service pr refs (fill after submit):
|
|
||||||
[github-pr]: https://github.com/goodboy/tractor/pull/___
|
|
||||||
[gitea-pr]: https://pikers.dev/goodboy/tractor/pulls/___
|
|
||||||
[srht-patch]: https://git.sr.ht/~goodboy/tractor/patches/___
|
|
||||||
-->
|
|
||||||
```
|
|
||||||
|
|
||||||
Commented out with `___` number placeholders.
|
|
||||||
After submission: uncomment, replace `___` with
|
|
||||||
the actual number. Each service-specific copy
|
|
||||||
fills in all services' numbers so any copy can
|
|
||||||
cross-reference the others.
|
|
||||||
|
|
||||||
### Post-submission file layout
|
|
||||||
|
|
||||||
```
|
|
||||||
pr_msg_LATEST.md # latest draft (skill root)
|
|
||||||
msgs/
|
|
||||||
20260325T002027Z_mybranch_pr_msg.md # timestamped
|
|
||||||
github/
|
|
||||||
42_pr_msg.md # github PR #42
|
|
||||||
gitea/
|
|
||||||
17_pr_msg.md # gitea PR #17
|
|
||||||
srht/
|
|
||||||
5_pr_msg.md # srht patch #5
|
|
||||||
```
|
|
||||||
|
|
||||||
Each `<service>/<num>_pr_msg.md` is a copy with:
|
|
||||||
- metadata `submitted:` fields filled in
|
|
||||||
- cross-references section uncommented
|
|
||||||
- ref-link stubs uncommented with real numbers
|
|
||||||
- all services cross-linked in each copy
|
|
||||||
|
|
||||||
This mirrors the `gish` skill's
|
|
||||||
`<backend>/<num>.md` pattern.
|
|
||||||
|
|
||||||
## Commit-Link URL Patterns by Service
|
|
||||||
|
|
||||||
| Service | Pattern |
|
|
||||||
|-----------|-------------------------------------|
|
|
||||||
| GitHub | `https://github.com/<o>/<r>/commit/<h>` |
|
|
||||||
| Gitea | `https://<host>/<o>/<r>/commit/<h>` |
|
|
||||||
| SourceHut | `https://git.sr.ht/~<o>/<r>/commit/<h>` |
|
|
||||||
| GitLab | `https://gitlab.com/<o>/<r>/-/commit/<h>` |
|
|
||||||
|
|
||||||
## PR/Patch URL Patterns by Service
|
|
||||||
|
|
||||||
| Service | Pattern |
|
|
||||||
|-----------|-------------------------------------|
|
|
||||||
| GitHub | `https://github.com/<o>/<r>/pull/<n>` |
|
|
||||||
| Gitea | `https://<host>/<o>/<r>/pulls/<n>` |
|
|
||||||
| SourceHut | `https://git.sr.ht/~<o>/<r>/patches/<n>` |
|
|
||||||
| GitLab | `https://gitlab.com/<o>/<r>/-/merge_requests/<n>` |
|
|
||||||
|
|
||||||
## Scope Naming Convention
|
|
||||||
|
|
||||||
Use Python namespace-resolution syntax for
|
|
||||||
referencing changed code scopes:
|
|
||||||
|
|
||||||
| File path | Scope reference |
|
|
||||||
|---------------------------|-------------------------------|
|
|
||||||
| `tractor/_exceptions.py` | `tractor._exceptions` |
|
|
||||||
| `tractor/_state.py` | `tractor._state` |
|
|
||||||
| `tests/test_foo.py` | `tests.test_foo` |
|
|
||||||
| Function in module | `tractor._exceptions.func()` |
|
|
||||||
| Method on class | `.RemoteActorError.src_type` |
|
|
||||||
| Class | `tractor._exceptions.RAE` |
|
|
||||||
|
|
||||||
Prefix with the package path for top-level refs;
|
|
||||||
use leading-dot shorthand (`.ClassName.method()`)
|
|
||||||
for sub-bullets where the parent module is already
|
|
||||||
established.
|
|
||||||
|
|
||||||
## Title Conventions
|
|
||||||
|
|
||||||
Same verb vocabulary as commit messages:
|
|
||||||
- `Add` — wholly new feature/API
|
|
||||||
- `Fix` — bug fix
|
|
||||||
- `Drop` — removal
|
|
||||||
- `Use` — adopt new approach
|
|
||||||
- `Move`/`Mv` — relocate code
|
|
||||||
- `Adjust` — minor tweak
|
|
||||||
- `Update` — enhance existing feature
|
|
||||||
- `Support` — add support for something
|
|
||||||
|
|
||||||
Target 50 chars, hard max 70. Always backtick
|
|
||||||
code elements.
|
|
||||||
|
|
||||||
## Tone
|
|
||||||
|
|
||||||
Casual yet technically precise — matching the
|
|
||||||
project's commit-msg style. Terse but every bullet
|
|
||||||
carries signal. Use project abbreviations freely
|
|
||||||
(msg, bg, ctx, impl, mod, obvi, fn, bc, var,
|
|
||||||
prolly, ep, etc.).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
(this format reference was generated by
|
|
||||||
[`claude-code`][claude-code-gh])
|
|
||||||
[claude-code-gh]: https://github.com/anthropics/claude-code
|
|
||||||
|
|
@ -1,255 +0,0 @@
|
||||||
# Tractor Test Harness Reference
|
|
||||||
|
|
||||||
This repository-local file supplements the canonical [`/run-tests` skill][1]
|
|
||||||
from the [`ai.skillz` repository][2]. Its deployer links the shared `SKILL.md`
|
|
||||||
into both
|
|
||||||
`.claude/skills/run-tests/` and `.opencode/skills/run-tests/` while preserving
|
|
||||||
this project-owned reference:
|
|
||||||
|
|
||||||
```text
|
|
||||||
bash /path/to/ai.skillz/scripts/deploy.sh run-tests /path/to/tractor --provider all --method symlink
|
|
||||||
```
|
|
||||||
|
|
||||||
Keep shared environment permission, process-signal safety, target selection,
|
|
||||||
failure inspection, and result reporting policy in the deployed `SKILL.md`.
|
|
||||||
|
|
||||||
[1]: https://github.com/baudco/ai.skillz/blob/2d4896ca7e38fe2cb3090cdefc7245be4241a6d2/skills/run-tests/SKILL.md
|
|
||||||
[2]: https://github.com/baudco/ai.skillz
|
|
||||||
|
|
||||||
## Project And Environment
|
|
||||||
|
|
||||||
- Project/import: `tractor`
|
|
||||||
- Test root: `tests/`
|
|
||||||
- Supported Python: `>=3.13,<3.15`
|
|
||||||
- Runner: pytest `>=9.0.3`
|
|
||||||
- Test dependencies: the `dev` group includes the `testing` group
|
|
||||||
- CI uses uv's default `.venv`; the Nix flake uses `py313`.
|
|
||||||
- Run from the repository root so pytest loads `pyproject.toml`.
|
|
||||||
- Do not use `default.nix` as current test-environment authority; it still
|
|
||||||
selects unsupported Python 3.12.
|
|
||||||
|
|
||||||
Environment directory naming is not a harness invariant. Use an already
|
|
||||||
verified active project environment when available. Otherwise, use an
|
|
||||||
existing uv environment without syncing it:
|
|
||||||
|
|
||||||
```text
|
|
||||||
uv run --frozen --no-sync python -c 'import pathlib, sys, tractor; root = pathlib.Path.cwd().resolve(); mod = pathlib.Path(tractor.__file__).resolve(); print(sys.executable); print(mod); assert mod.is_relative_to(root)'
|
|
||||||
```
|
|
||||||
|
|
||||||
After module moves or collection failures, check collection with:
|
|
||||||
|
|
||||||
```text
|
|
||||||
uv run --frozen --no-sync pytest --collect-only -q tests/
|
|
||||||
```
|
|
||||||
|
|
||||||
Collection is not a mandatory precursor to every narrow run. Ask before
|
|
||||||
provisioning or changing an environment.
|
|
||||||
|
|
||||||
Before trusting CLI-selected runtime settings, inspect
|
|
||||||
`TRACTOR_SPAWN_METHOD` and `TRACTOR_LOGLEVEL`. They override the spawn method
|
|
||||||
and runtime log level passed by callers, so report active values with test
|
|
||||||
results rather than claiming the CLI flags alone selected the runtime.
|
|
||||||
|
|
||||||
## Pytest Configuration And Commands
|
|
||||||
|
|
||||||
`pyproject.toml` configures:
|
|
||||||
|
|
||||||
- `testpaths = ["tests"]` and `--rootdir=./tests`;
|
|
||||||
- importlib import mode;
|
|
||||||
- the `tractor._testing.pytest` plugin;
|
|
||||||
- xonsh plugin disablement;
|
|
||||||
- `--show-capture=no` and `--capture=fd`.
|
|
||||||
|
|
||||||
Do not silently add `-x`, `--tb=short`, or `--no-header`; those are not
|
|
||||||
project defaults. In a verified active environment, replace `uv run
|
|
||||||
--frozen --no-sync pytest` below with `python -m pytest`.
|
|
||||||
|
|
||||||
```text
|
|
||||||
# Full suite
|
|
||||||
uv run --frozen --no-sync pytest tests/
|
|
||||||
|
|
||||||
# Narrow file
|
|
||||||
uv run --frozen --no-sync pytest tests/test_local.py
|
|
||||||
|
|
||||||
# Exact node
|
|
||||||
uv run --frozen --no-sync pytest tests/discovery/test_registrar.py::test_reg_then_unreg
|
|
||||||
|
|
||||||
# Keyword selection
|
|
||||||
uv run --frozen --no-sync pytest tests/ -k 'cancel and not slow'
|
|
||||||
|
|
||||||
# Previous failures
|
|
||||||
uv run --frozen --no-sync pytest --lf
|
|
||||||
```
|
|
||||||
|
|
||||||
After verifying that the no-sync environment is current, these pytest
|
|
||||||
arguments match the Linux TCP CI row:
|
|
||||||
|
|
||||||
```text
|
|
||||||
CI=1 uv run --frozen --no-sync pytest tests/ -rsx --spawn-backend=trio --tpt-proto=tcp --capture=fd
|
|
||||||
```
|
|
||||||
|
|
||||||
## Plugin Options And Matrices
|
|
||||||
|
|
||||||
Supported spawn backends:
|
|
||||||
|
|
||||||
- `trio` (default)
|
|
||||||
- `mp_spawn`
|
|
||||||
- `mp_forkserver`
|
|
||||||
|
|
||||||
Do not advertise `subint`, `subint_forkserver`, or
|
|
||||||
`main_thread_forkserver` as runnable backends. Supported transports are
|
|
||||||
`tcp` (default) and `uds`. Run one transport per pytest session.
|
|
||||||
`mp_forkserver` and UDS are POSIX-only.
|
|
||||||
|
|
||||||
Other Tractor plugin options include:
|
|
||||||
|
|
||||||
- `--tpdb` / `--debug-mode`
|
|
||||||
- `--ll` / `--loglevel`
|
|
||||||
- `--tl` / `--tractor-loglevel`
|
|
||||||
- `--enable-stackscope`
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
```text
|
|
||||||
uv run --frozen --no-sync pytest tests/ipc/ --tpt-proto=uds
|
|
||||||
uv run --frozen --no-sync pytest tests/test_spawning.py --spawn-backend=mp_spawn
|
|
||||||
uv run --frozen --no-sync pytest tests/test_spawning.py --spawn-backend=mp_forkserver --capture=sys
|
|
||||||
```
|
|
||||||
|
|
||||||
CI currently exercises Python 3.13 with the `trio` backend: TCP and UDS on
|
|
||||||
Linux and macOS, plus an informational TCP row on Windows whose pytest step
|
|
||||||
uses `continue-on-error`.
|
|
||||||
|
|
||||||
## Registry And Transport Isolation
|
|
||||||
|
|
||||||
Tests requesting the `reg_addr` fixture use addresses randomized per session:
|
|
||||||
an unreserved unprivileged loopback port for TCP or a unique socket name under
|
|
||||||
the platform runtime directory for UDS. A TCP collision remains possible.
|
|
||||||
|
|
||||||
The runtime fallback remains `127.0.0.1:1616` or `registry@1616.sock`.
|
|
||||||
Inspect that fallback only when the selected test intentionally uses runtime
|
|
||||||
defaults or a failure identifies that address. Do not perform a mandatory
|
|
||||||
`:1616` preflight or assume UDS sockets live under `/tmp`.
|
|
||||||
|
|
||||||
## Capture And Hang Diagnosis
|
|
||||||
|
|
||||||
Normal capture is `fd`. Use `--capture=sys` with `mp_forkserver`; some tests
|
|
||||||
switch to `capsys`, but the harness does not enforce that suite-wide.
|
|
||||||
|
|
||||||
For a suspected capture interaction, compare only the exact node:
|
|
||||||
|
|
||||||
```text
|
|
||||||
uv run --frozen --no-sync pytest <node> --capture=sys
|
|
||||||
uv run --frozen --no-sync pytest <node> -s
|
|
||||||
```
|
|
||||||
|
|
||||||
Treat `-s` as a diagnostic comparison, not a pass-equivalent workaround. Do
|
|
||||||
not use it to reinterpret an ordinary captured pass. Interactive `--tpdb` or
|
|
||||||
`tractor.pause()` sessions are different: they require a real TTY and disabled
|
|
||||||
capture, normally `-s`.
|
|
||||||
|
|
||||||
Do not add a global pytest timeout. `fail_after_w_trace` is Trio-cooperative;
|
|
||||||
`afk_alarm_w_trace` is a POSIX main-thread `SIGALRM` hard backstop and can
|
|
||||||
raise asynchronously. Use the latter only as a last resort, not as a generally
|
|
||||||
Trio-safe timeout replacement.
|
|
||||||
|
|
||||||
For live task-tree diagnosis:
|
|
||||||
|
|
||||||
```text
|
|
||||||
uv run --frozen --no-sync python -c 'import stackscope'
|
|
||||||
uv run --frozen --no-sync pytest <node> --enable-stackscope --capture=sys
|
|
||||||
kill -USR1 <pytest-pid>
|
|
||||||
```
|
|
||||||
|
|
||||||
The import check and pytest command must use the same environment. Do not send
|
|
||||||
SIGUSR1 if the import fails or setup warns that stackscope or SIGUSR1 is
|
|
||||||
unavailable: without the installed handler, SIGUSR1 normally terminates the
|
|
||||||
target process. Signal a subactor only after separately confirming that it
|
|
||||||
installed the same handler.
|
|
||||||
|
|
||||||
Stackscope appends dumps to `/tmp/tractor-stackscope-<pid>.log`, including when
|
|
||||||
pytest capture hides terminal output. SIGUSR1 stackscope is unavailable on
|
|
||||||
Windows and degrades to a no-op there.
|
|
||||||
|
|
||||||
When a trace guard actually fires and snapshot capture succeeds, it writes
|
|
||||||
under `$XDG_CACHE_HOME/tractor/hung-dumps/`, falling back beneath
|
|
||||||
`~/.cache/tractor/hung-dumps/`, and prints an end-of-session index. A normal
|
|
||||||
non-timeout run creates no snapshot.
|
|
||||||
|
|
||||||
## Cleanup And `tractor-reap`
|
|
||||||
|
|
||||||
On Linux, normal pytest teardown discovers surviving descendants through
|
|
||||||
`/proc`, sends SIGINT, waits three seconds, then escalates survivors to
|
|
||||||
SIGKILL. It does not sweep shared memory and cannot run if pytest never reaches
|
|
||||||
fixture teardown.
|
|
||||||
|
|
||||||
Process discovery is a no-op off Linux. UDS PID liveness also depends on
|
|
||||||
`/proc`; on macOS, recognized PID-named sockets can therefore be classified as
|
|
||||||
dead without proof. The session-scoped autouse fixture currently passes those
|
|
||||||
candidates directly to `reap_uds()` at teardown. Do not treat its non-Linux
|
|
||||||
classification as proof of orphanhood or run concurrent live Tractor sessions
|
|
||||||
against the same UDS bindspace.
|
|
||||||
|
|
||||||
Use the CLI in inspection-only mode first:
|
|
||||||
|
|
||||||
`--shm` and `--shm-only` are Linux/FreeBSD-only and raise
|
|
||||||
`NotImplementedError` elsewhere. On other platforms, use the UDS-only command.
|
|
||||||
|
|
||||||
```text
|
|
||||||
uv run --frozen --no-sync scripts/tractor-reap -n
|
|
||||||
uv run --frozen --no-sync scripts/tractor-reap --parent <pytest-pid> -n
|
|
||||||
uv run --frozen --no-sync scripts/tractor-reap --shm --uds -n
|
|
||||||
uv run --frozen --no-sync scripts/tractor-reap --uds-only -n
|
|
||||||
```
|
|
||||||
|
|
||||||
Direct `scripts/tractor-reap` execution is acceptable only after verifying its
|
|
||||||
`python3` shebang resolves the intended project environment.
|
|
||||||
|
|
||||||
Review every candidate before requesting a mutating run:
|
|
||||||
|
|
||||||
- default orphan mode is not repository-scoped;
|
|
||||||
- `--parent` trusts the supplied PID and can include non-Tractor children;
|
|
||||||
- `--shm` scans all current-user candidate files, not just Tractor-named
|
|
||||||
files;
|
|
||||||
- `--uds` treats `registry@1616.sock` as removable even if a live default UDS
|
|
||||||
registrar uses it.
|
|
||||||
|
|
||||||
Dry-run output prints only the initially matched root PIDs. A mutating run can
|
|
||||||
recursively expand those roots to additional descendants when `psutil` is
|
|
||||||
available. Inspect the descendant process tree separately; `-n` is not exact
|
|
||||||
signal-set parity and does not by itself authorize signaling unseen children.
|
|
||||||
|
|
||||||
The canonical skill owns signaling and unlinking authorization.
|
|
||||||
|
|
||||||
## Test Layout And Change Mapping
|
|
||||||
|
|
||||||
| Changed area | Run first |
|
|
||||||
|---|---|
|
|
||||||
| `tractor/runtime/_runtime.py`, `_state.py`, `tractor/_root.py` | `tests/test_local.py`, `tests/test_root_runtime.py`, `tests/test_runtime.py`, `tests/test_rpc.py` |
|
|
||||||
| `tractor/runtime/_portal.py`, `_rpc.py` | `tests/test_rpc.py`, `tests/test_cancellation.py` |
|
|
||||||
| `tractor/runtime/_supervise.py` | `tests/test_cancellation.py`, `tests/test_spawning.py` |
|
|
||||||
| `tractor/discovery/` | `tests/discovery/`, `tests/test_local.py` |
|
|
||||||
| `tractor/ipc/` | `tests/ipc/`, `tests/test_2way.py`, `tests/test_shm.py` as relevant |
|
|
||||||
| `tractor/spawn/` | `tests/test_spawning.py`, `tests/discovery/test_multi_program.py`, `tests/test_cancellation.py` |
|
|
||||||
| `tractor/_context.py`, `_streaming.py` | `tests/test_context_stream_semantics.py`, `tests/test_advanced_streaming.py`, `tests/test_legacy_one_way_streaming.py` |
|
|
||||||
| `tractor/to_asyncio.py` | `tests/test_infected_asyncio.py`, `tests/test_root_infect_asyncio.py` |
|
|
||||||
| `tractor/msg/` | `tests/msg/` |
|
|
||||||
| `tractor/devx/` | `tests/devx/`; debugger tests use pexpect and are comparatively slow |
|
|
||||||
| `tractor/_exceptions.py` | `tests/test_remote_exc_relay.py`, `tests/test_reg_err_types.py`, `tests/test_inter_peer_cancellation.py`, `tests/test_cancellation.py`, `tests/msg/` |
|
|
||||||
|
|
||||||
Current subdirectories include `discovery/`, `ipc/`, `msg/`, `devx/`, and
|
|
||||||
`trionics/`. There is no `tests/spawn/` directory.
|
|
||||||
|
|
||||||
## Expected Outcomes
|
|
||||||
|
|
||||||
Do not maintain a blanket known-flaky exemption list. Classify only current
|
|
||||||
explicit skip or xfail marks and exact expected signatures. Notable tracked
|
|
||||||
outcomes include:
|
|
||||||
|
|
||||||
- duplicate-name `n_dups=4` and `n_dups=8` variants in
|
|
||||||
`tests/discovery/test_multi_program.py` are non-strict xfails;
|
|
||||||
- `tests/test_ringbuf.py` is module-skipped;
|
|
||||||
- some documentation examples have explicit macOS-CI skips.
|
|
||||||
|
|
||||||
A generic `TooSlowError` or `pexpect.TIMEOUT` is not enough to classify a
|
|
||||||
failure as pre-existing.
|
|
||||||
|
|
@ -1,18 +1,10 @@
|
||||||
name: CI
|
name: CI
|
||||||
|
|
||||||
# NOTE distilled from,
|
|
||||||
# https://github.com/orgs/community/discussions/26276
|
|
||||||
on:
|
on:
|
||||||
# any time a new update to 'main'
|
# any time someone pushes a new branch to origin
|
||||||
push:
|
push:
|
||||||
branches:
|
|
||||||
- main
|
|
||||||
|
|
||||||
# for on all (forked) PRs to repo
|
# Allows you to run this workflow manually from the Actions tab
|
||||||
# NOTE, use a draft PR if you just want CI triggered..
|
|
||||||
pull_request:
|
|
||||||
|
|
||||||
# to run workflow manually from the "Actions" tab
|
|
||||||
workflow_dispatch:
|
workflow_dispatch:
|
||||||
|
|
||||||
jobs:
|
jobs:
|
||||||
|
|
@ -37,12 +29,7 @@ jobs:
|
||||||
run: uv build --sdist --python=3.13
|
run: uv build --sdist --python=3.13
|
||||||
|
|
||||||
- name: Install sdist from .tar.gz
|
- name: Install sdist from .tar.gz
|
||||||
# XXX must install under py3.13 (matching the build's
|
run: python -m pip install dist/*.tar.gz
|
||||||
# `--python=3.13`); the runner's default `python` is 3.12
|
|
||||||
# which our `requires-python = ">=3.13"` now rejects.
|
|
||||||
run: |
|
|
||||||
uv venv --python 3.13
|
|
||||||
uv pip install dist/*.tar.gz
|
|
||||||
|
|
||||||
# ------ type-check ------
|
# ------ type-check ------
|
||||||
# mypy:
|
# mypy:
|
||||||
|
|
@ -87,49 +74,24 @@ jobs:
|
||||||
# run: mypy tractor/ --ignore-missing-imports --show-traceback
|
# run: mypy tractor/ --ignore-missing-imports --show-traceback
|
||||||
|
|
||||||
|
|
||||||
testing:
|
testing-linux:
|
||||||
name: '${{ matrix.os }} Python${{ matrix.python-version }} spawn_backend=${{ matrix.spawn_backend }} tpt_proto=${{ matrix.tpt_proto }}'
|
name: '${{ matrix.os }} Python ${{ matrix.python }} - ${{ matrix.spawn_backend }}'
|
||||||
timeout-minutes: 16
|
timeout-minutes: 10
|
||||||
runs-on: ${{ matrix.os }}
|
runs-on: ${{ matrix.os }}
|
||||||
# Windows support is nascent: its full test suite remains
|
|
||||||
# informational, while setup and the `import tractor` smoke below
|
|
||||||
# are hard signals. Promote the test step to required once the
|
|
||||||
# suite is green.
|
|
||||||
|
|
||||||
strategy:
|
strategy:
|
||||||
fail-fast: false
|
fail-fast: false
|
||||||
matrix:
|
matrix:
|
||||||
os: [
|
os: [ubuntu-latest]
|
||||||
ubuntu-latest,
|
python-version: ['3.13']
|
||||||
macos-latest,
|
|
||||||
windows-latest,
|
|
||||||
]
|
|
||||||
python-version: [
|
|
||||||
'3.13',
|
|
||||||
# '3.14',
|
|
||||||
]
|
|
||||||
spawn_backend: [
|
spawn_backend: [
|
||||||
'trio',
|
'trio',
|
||||||
# 'mp_spawn',
|
# 'mp_spawn',
|
||||||
# 'mp_forkserver',
|
# 'mp_forkserver',
|
||||||
# ?TODO^ is it worth it to get these running again?
|
|
||||||
#
|
|
||||||
# - [ ] next-gen backends, on 3.13+
|
|
||||||
# https://github.com/goodboy/tractor/issues/379
|
|
||||||
# 'subinterpreter',
|
|
||||||
# 'subint',
|
|
||||||
]
|
]
|
||||||
tpt_proto: [
|
|
||||||
'tcp',
|
|
||||||
'uds',
|
|
||||||
]
|
|
||||||
exclude:
|
|
||||||
# UDS is POSIX-only; Windows has no `AF_UNIX` so the
|
|
||||||
# backend is intentionally unavailable there.
|
|
||||||
- os: windows-latest
|
|
||||||
tpt_proto: 'uds'
|
|
||||||
|
|
||||||
steps:
|
steps:
|
||||||
|
|
||||||
- uses: actions/checkout@v4
|
- uses: actions/checkout@v4
|
||||||
|
|
||||||
- name: 'Install uv + py-${{ matrix.python-version }}'
|
- name: 'Install uv + py-${{ matrix.python-version }}'
|
||||||
|
|
@ -155,28 +117,8 @@ jobs:
|
||||||
- name: List deps tree
|
- name: List deps tree
|
||||||
run: uv tree
|
run: uv tree
|
||||||
|
|
||||||
# hard signal for the Windows import-safety fix: `import
|
|
||||||
# tractor` must succeed everywhere, and `HAS_UDS` reflects
|
|
||||||
# platform capability (False on Windows, True on POSIX).
|
|
||||||
- name: 'Smoke: import tractor'
|
|
||||||
run: uv run python -c "import sys; import tractor; from tractor.ipc._uds import HAS_UDS; assert sys.platform != 'win32' or not HAS_UDS; print('import tractor OK | HAS_UDS=', HAS_UDS)"
|
|
||||||
|
|
||||||
- name: Run tests
|
- name: Run tests
|
||||||
# Actor/PTY scheduling on macOS can fail a different
|
run: uv run pytest tests/ --spawn-backend=${{ matrix.spawn_backend }} -rsx
|
||||||
# timing-sensitive node between otherwise-green runs. Retry
|
|
||||||
# only that matrix leg; deterministic failures still fail
|
|
||||||
# after the final attempt.
|
|
||||||
continue-on-error: ${{ matrix.os == 'windows-latest' }}
|
|
||||||
run: >
|
|
||||||
uv run
|
|
||||||
pytest
|
|
||||||
tests/
|
|
||||||
-rsx
|
|
||||||
--spawn-backend=${{ matrix.spawn_backend }}
|
|
||||||
--tpt-proto=${{ matrix.tpt_proto }}
|
|
||||||
--capture=fd
|
|
||||||
--reruns=${{ matrix.os == 'macos-latest' && 2 || 0 }}
|
|
||||||
--reruns-delay=1
|
|
||||||
|
|
||||||
# XXX legacy NOTE XXX
|
# XXX legacy NOTE XXX
|
||||||
#
|
#
|
||||||
|
|
|
||||||
|
|
@ -1,63 +0,0 @@
|
||||||
name: docs
|
|
||||||
|
|
||||||
# build sphinx docs on every PR + push to main;
|
|
||||||
# deploy to gh-pages only from main pushes.
|
|
||||||
# (see goodboy/tractor#123 for the original ask)
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches:
|
|
||||||
- main
|
|
||||||
pull_request:
|
|
||||||
# to run workflow manually from the "Actions" tab
|
|
||||||
workflow_dispatch:
|
|
||||||
|
|
||||||
# needed by actions/deploy-pages
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
pages: write
|
|
||||||
id-token: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build:
|
|
||||||
name: 'sphinx build'
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Install latest uv
|
|
||||||
uses: astral-sh/setup-uv@v6
|
|
||||||
|
|
||||||
# NOTE, no `d2` bin is installed in CI (yet) so
|
|
||||||
# the pre-rendered + committed SVGs under
|
|
||||||
# `docs/_diagrams/` are used as-is; see
|
|
||||||
# `docs/_ext/d2diagrams.py` for the fallback
|
|
||||||
# policy.
|
|
||||||
- name: Build html docs
|
|
||||||
run: |
|
|
||||||
uv sync --no-dev --group docs
|
|
||||||
uv run --no-dev --group docs make -C docs html
|
|
||||||
|
|
||||||
- name: Upload pages artifact
|
|
||||||
uses: actions/upload-pages-artifact@v3
|
|
||||||
with:
|
|
||||||
path: docs/_build/html
|
|
||||||
|
|
||||||
deploy:
|
|
||||||
name: 'deploy to gh-pages'
|
|
||||||
if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
|
|
||||||
needs: build
|
|
||||||
# serialize deploys but NEVER cancel an in-flight one
|
|
||||||
# mid-upload; queue the next instead (scoped to this job so
|
|
||||||
# PR builds can't cancel a production deploy).
|
|
||||||
concurrency:
|
|
||||||
group: 'pages'
|
|
||||||
cancel-in-progress: false
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
environment:
|
|
||||||
name: github-pages
|
|
||||||
url: ${{ steps.deployment.outputs.page_url }}
|
|
||||||
steps:
|
|
||||||
- name: Deploy
|
|
||||||
id: deployment
|
|
||||||
uses: actions/deploy-pages@v4
|
|
||||||
|
|
@ -102,333 +102,3 @@ venv.bak/
|
||||||
|
|
||||||
# mypy
|
# mypy
|
||||||
.mypy_cache/
|
.mypy_cache/
|
||||||
|
|
||||||
# all files under
|
|
||||||
.git/
|
|
||||||
|
|
||||||
# require very explicit staging for anything we **really**
|
|
||||||
# want put/kept in repo.
|
|
||||||
notes_to_self/
|
|
||||||
snippets/
|
|
||||||
|
|
||||||
# ------- AI shiz -------
|
|
||||||
# `ai.skillz` symlinks,
|
|
||||||
# (machine-local, deploy via deploy-skill.sh)
|
|
||||||
.claude/skills/py-codestyle
|
|
||||||
.claude/skills/close-wkt
|
|
||||||
.claude/skills/plan-io
|
|
||||||
.claude/skills/prompt-io
|
|
||||||
.claude/skills/resolve-conflicts
|
|
||||||
.claude/skills/inter-skill-review
|
|
||||||
|
|
||||||
# /open-wkt specifics
|
|
||||||
.claude/skills/open-wkt
|
|
||||||
.claude/wkts/
|
|
||||||
claude_wkts
|
|
||||||
|
|
||||||
# /code-review-changes specifics
|
|
||||||
.claude/skills/code-review-changes
|
|
||||||
# review-skill ephemeral ctx (per-PR, single-use)
|
|
||||||
.claude/review_context.md
|
|
||||||
.claude/review_regression.md
|
|
||||||
|
|
||||||
# /pr-msg specifics
|
|
||||||
.claude/skills/pr-msg/*
|
|
||||||
# repo-specific
|
|
||||||
!.claude/skills/pr-msg/format-reference.md
|
|
||||||
# XXX, so u can nvim-telescope this file.
|
|
||||||
# !.claude/skills/pr-msg/pr_msg_LATEST.md
|
|
||||||
|
|
||||||
# /commit-msg specifics
|
|
||||||
# - any commit-msg gen tmp files
|
|
||||||
.claude/*_commit_*.md
|
|
||||||
.claude/*_commit*.txt
|
|
||||||
.claude/skills/commit-msg/*
|
|
||||||
!.claude/skills/commit-msg/style-duie-reference.md
|
|
||||||
|
|
||||||
# use prompt-io instead?
|
|
||||||
.claude/plans
|
|
||||||
|
|
||||||
# nix develop --profile .nixdev
|
|
||||||
.nixdev*
|
|
||||||
|
|
||||||
# :Obsession .
|
|
||||||
Session.vim
|
|
||||||
|
|
||||||
# `gish` local `.md`-files
|
|
||||||
# TODO? better all around automation!
|
|
||||||
# -[ ] it'd be handy to also commit and sync with wtv git service?
|
|
||||||
# -[ ] everything should be put under a `.gish/` no?
|
|
||||||
gitea/
|
|
||||||
gh/
|
|
||||||
|
|
||||||
# ------ macOS ------
|
|
||||||
# Finder metadata
|
|
||||||
**/.DS_Store
|
|
||||||
|
|
||||||
# LLM conversations that should remain private
|
|
||||||
docs/conversations/
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:run-tests
|
|
||||||
/.claude/skills/run-tests/SKILL.md
|
|
||||||
# END ai.skillz: direct:symlink:claude:run-tests
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:run-tests
|
|
||||||
/.opencode/skills/run-tests/SKILL.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:run-tests
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:run-tests
|
|
||||||
/.opencode/commands/run-tests.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:run-tests
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:gish
|
|
||||||
/.claude/skills/gish
|
|
||||||
# END ai.skillz: direct:symlink:claude:gish
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:gish
|
|
||||||
/.opencode/skills/gish
|
|
||||||
# END ai.skillz: direct:symlink:opencode:gish
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:resolve-conflicts
|
|
||||||
/.claude/skills/resolve-conflicts
|
|
||||||
# END ai.skillz: direct:symlink:claude:resolve-conflicts
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:resolve-conflicts
|
|
||||||
/.opencode/skills/resolve-conflicts
|
|
||||||
# END ai.skillz: direct:symlink:opencode:resolve-conflicts
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:git-mgmt
|
|
||||||
/.claude/skills/git-mgmt
|
|
||||||
# END ai.skillz: direct:symlink:claude:git-mgmt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:git-mgmt
|
|
||||||
/.opencode/skills/git-mgmt
|
|
||||||
# END ai.skillz: direct:symlink:opencode:git-mgmt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: runtime:open-wkt
|
|
||||||
/wkts/
|
|
||||||
# END ai.skillz: runtime:open-wkt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:open-wkt
|
|
||||||
/.claude/skills/open-wkt
|
|
||||||
# END ai.skillz: direct:symlink:claude:open-wkt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:open-wkt
|
|
||||||
/.opencode/skills/open-wkt
|
|
||||||
# END ai.skillz: direct:symlink:opencode:open-wkt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:close-wkt
|
|
||||||
/.claude/skills/close-wkt
|
|
||||||
# END ai.skillz: direct:symlink:claude:close-wkt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:close-wkt
|
|
||||||
/.opencode/skills/close-wkt
|
|
||||||
# END ai.skillz: direct:symlink:opencode:close-wkt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: runtime:code-review
|
|
||||||
.ai/code-review/reports/
|
|
||||||
# END ai.skillz: runtime:code-review
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:code-review
|
|
||||||
/.claude/skills/code-review
|
|
||||||
# END ai.skillz: direct:symlink:claude:code-review
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:code-review
|
|
||||||
/.opencode/skills/code-review
|
|
||||||
# END ai.skillz: direct:symlink:opencode:code-review
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:code-nav-refs
|
|
||||||
/.claude/skills/code-nav-refs
|
|
||||||
# END ai.skillz: direct:symlink:claude:code-nav-refs
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:code-nav-refs
|
|
||||||
/.opencode/skills/code-nav-refs
|
|
||||||
# END ai.skillz: direct:symlink:opencode:code-nav-refs
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: runtime:code-review-changes
|
|
||||||
.claude/review_context.md
|
|
||||||
.claude/review_regression.md
|
|
||||||
.claude/review_replies/
|
|
||||||
# END ai.skillz: runtime:code-review-changes
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:code-review-changes
|
|
||||||
/.claude/skills/code-review-changes
|
|
||||||
# END ai.skillz: direct:symlink:claude:code-review-changes
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:code-review-changes
|
|
||||||
/.opencode/skills/code-review-changes
|
|
||||||
# END ai.skillz: direct:symlink:opencode:code-review-changes
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: runtime:commit-msg
|
|
||||||
.claude/skills/commit-msg/msgs/
|
|
||||||
.claude/git_commit_msg_LATEST.md
|
|
||||||
# END ai.skillz: runtime:commit-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:commit-msg
|
|
||||||
/.claude/skills/commit-msg/SKILL.md
|
|
||||||
# END ai.skillz: direct:symlink:claude:commit-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:commit-msg
|
|
||||||
/.opencode/skills/commit-msg/SKILL.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:commit-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:commit-plan
|
|
||||||
/.claude/skills/commit-plan
|
|
||||||
# END ai.skillz: direct:symlink:claude:commit-plan
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:commit-plan
|
|
||||||
/.opencode/skills/commit-plan
|
|
||||||
# END ai.skillz: direct:symlink:opencode:commit-plan
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:dep-supersede-scan
|
|
||||||
/.claude/skills/dep-supersede-scan
|
|
||||||
# END ai.skillz: direct:symlink:claude:dep-supersede-scan
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:dep-supersede-scan
|
|
||||||
/.opencode/skills/dep-supersede-scan
|
|
||||||
# END ai.skillz: direct:symlink:opencode:dep-supersede-scan
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:harness-perf
|
|
||||||
/.claude/skills/harness-perf
|
|
||||||
# END ai.skillz: direct:symlink:claude:harness-perf
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:harness-perf
|
|
||||||
/.opencode/skills/harness-perf
|
|
||||||
# END ai.skillz: direct:symlink:opencode:harness-perf
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:inter-skill-review
|
|
||||||
/.claude/skills/inter-skill-review
|
|
||||||
# END ai.skillz: direct:symlink:claude:inter-skill-review
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:inter-skill-review
|
|
||||||
/.opencode/skills/inter-skill-review
|
|
||||||
# END ai.skillz: direct:symlink:opencode:inter-skill-review
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:opencode-cleaning
|
|
||||||
/.claude/skills/opencode-cleaning
|
|
||||||
# END ai.skillz: direct:symlink:claude:opencode-cleaning
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:opencode-cleaning
|
|
||||||
/.opencode/skills/opencode-cleaning
|
|
||||||
# END ai.skillz: direct:symlink:opencode:opencode-cleaning
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:plan-io
|
|
||||||
/.claude/skills/plan-io
|
|
||||||
# END ai.skillz: direct:symlink:claude:plan-io
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:plan-io
|
|
||||||
/.opencode/skills/plan-io
|
|
||||||
# END ai.skillz: direct:symlink:opencode:plan-io
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: runtime:pr-msg
|
|
||||||
.claude/skills/pr-msg/msgs/
|
|
||||||
.claude/skills/pr-msg/pr_msg_LATEST.md
|
|
||||||
# END ai.skillz: runtime:pr-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:pr-msg
|
|
||||||
/.claude/skills/pr-msg/SKILL.md
|
|
||||||
/.claude/skills/pr-msg/references
|
|
||||||
/.claude/skills/pr-msg/scripts
|
|
||||||
# END ai.skillz: direct:symlink:claude:pr-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:pr-msg
|
|
||||||
/.opencode/skills/pr-msg/SKILL.md
|
|
||||||
/.opencode/skills/pr-msg/references
|
|
||||||
/.opencode/skills/pr-msg/scripts
|
|
||||||
# END ai.skillz: direct:symlink:opencode:pr-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:prompt-io
|
|
||||||
/.claude/skills/prompt-io
|
|
||||||
# END ai.skillz: direct:symlink:claude:prompt-io
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:prompt-io
|
|
||||||
/.opencode/skills/prompt-io
|
|
||||||
# END ai.skillz: direct:symlink:opencode:prompt-io
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:py-codestyle
|
|
||||||
/.claude/skills/py-codestyle
|
|
||||||
# END ai.skillz: direct:symlink:claude:py-codestyle
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:py-codestyle
|
|
||||||
/.opencode/skills/py-codestyle
|
|
||||||
# END ai.skillz: direct:symlink:opencode:py-codestyle
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: runtime:taken-export
|
|
||||||
.ai/taken/exports/
|
|
||||||
# END ai.skillz: runtime:taken-export
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:taken-export
|
|
||||||
/.claude/skills/taken-export
|
|
||||||
# END ai.skillz: direct:symlink:claude:taken-export
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:taken-export
|
|
||||||
/.opencode/skills/taken-export
|
|
||||||
# END ai.skillz: direct:symlink:opencode:taken-export
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:claude:yt-url-lookup
|
|
||||||
/.claude/skills/yt-url-lookup
|
|
||||||
# END ai.skillz: direct:symlink:claude:yt-url-lookup
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:yt-url-lookup
|
|
||||||
/.opencode/skills/yt-url-lookup
|
|
||||||
# END ai.skillz: direct:symlink:opencode:yt-url-lookup
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:gish
|
|
||||||
/.opencode/commands/gish.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:gish
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:resolve-conflicts
|
|
||||||
/.opencode/commands/resolve-conflicts.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:resolve-conflicts
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:git-mgmt
|
|
||||||
/.opencode/commands/git-mgmt.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:git-mgmt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:open-wkt
|
|
||||||
/.opencode/commands/open-wkt.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:open-wkt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:close-wkt
|
|
||||||
/.opencode/commands/close-wkt.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:close-wkt
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:code-review
|
|
||||||
/.opencode/commands/code-review.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:code-review
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:code-review-changes
|
|
||||||
/.opencode/commands/code-review-changes.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:code-review-changes
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:commit-msg
|
|
||||||
/.opencode/commands/commit-msg.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:commit-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:commit-plan
|
|
||||||
/.opencode/commands/commit-plan.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:commit-plan
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:dep-supersede-scan
|
|
||||||
/.opencode/commands/dep-supersede-scan.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:dep-supersede-scan
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:harness-perf
|
|
||||||
/.opencode/commands/harness-perf.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:harness-perf
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:opencode-cleaning
|
|
||||||
/.opencode/commands/opencode-cleaning.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:opencode-cleaning
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:pr-msg
|
|
||||||
/.opencode/commands/pr-msg.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:pr-msg
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:taken-export
|
|
||||||
/.opencode/commands/taken-export.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:taken-export
|
|
||||||
|
|
||||||
# BEGIN ai.skillz: direct:symlink:opencode:command:yt-url-lookup
|
|
||||||
/.opencode/commands/yt-url-lookup.md
|
|
||||||
# END ai.skillz: direct:symlink:opencode:command:yt-url-lookup
|
|
||||||
|
|
|
||||||
1
NEWS.rst
1
NEWS.rst
|
|
@ -78,7 +78,6 @@ Bug Fixes
|
||||||
for ``asyncio``-side errors to not propagate due to a race condition.
|
for ``asyncio``-side errors to not propagate due to a race condition.
|
||||||
|
|
||||||
The implementation fix summary is:
|
The implementation fix summary is:
|
||||||
|
|
||||||
- add state to signal the end of the ``trio`` side task to be
|
- add state to signal the end of the ``trio`` side task to be
|
||||||
read by the ``asyncio`` side and always cancel any ongoing
|
read by the ``asyncio`` side and always cancel any ongoing
|
||||||
task in such cases.
|
task in such cases.
|
||||||
|
|
|
||||||
|
|
@ -1,281 +0,0 @@
|
||||||
# `fork()` in a multi-threaded program — execution-side vs. memory-side of the same coin
|
|
||||||
|
|
||||||
A reference doc for readers who've encountered one of two
|
|
||||||
opposite-sounding framings of POSIX `fork()` semantics in a
|
|
||||||
multi-threaded program and are confused by the other.
|
|
||||||
|
|
||||||
This is a sibling to
|
|
||||||
`subint_fork_blocked_by_cpython_post_fork_issue.md` — that
|
|
||||||
doc covers a CPython-level refusal of fork-from-subint;
|
|
||||||
this one covers the more general POSIX layer, since
|
|
||||||
tractor's main-thread forkserver design rests on it.
|
|
||||||
|
|
||||||
## TL;DR
|
|
||||||
|
|
||||||
POSIX `fork()` only preserves the *calling* thread as a
|
|
||||||
runnable thread in the child — every other thread in the
|
|
||||||
parent simply never executes another instruction in the
|
|
||||||
child. trio's docs call this "leaked"; tractor's
|
|
||||||
`_main_thread_forkserver.py` docstring calls it "gone".
|
|
||||||
Both are correct: "gone" is the *execution* side (no
|
|
||||||
scheduler entry, no instructions retired), "leaked" is the
|
|
||||||
*memory* side (the dead threads' stacks and per-thread
|
|
||||||
heap structures still ride into the child's address space
|
|
||||||
as orphaned COW pages with no owner and no cleanup hook).
|
|
||||||
Same POSIX reality, two halves of the same coin.
|
|
||||||
|
|
||||||
## The two framings
|
|
||||||
|
|
||||||
[python-trio/trio#1614][trio-1614] (the canonical "trio +
|
|
||||||
fork" hazards thread) puts it this way:
|
|
||||||
|
|
||||||
> If you use `fork()` in a process with multiple threads,
|
|
||||||
> all the other thread stacks are just leaked: there's
|
|
||||||
> nothing else you can reasonably do with them.
|
|
||||||
|
|
||||||
`tractor.spawn._main_thread_forkserver`'s module docstring
|
|
||||||
(specifically the "What survives the fork? — POSIX
|
|
||||||
semantics" section) puts it this way:
|
|
||||||
|
|
||||||
> POSIX `fork()` only preserves the *calling* thread as a
|
|
||||||
> runnable thread in the child. Every other thread in the
|
|
||||||
> parent — trio's runner thread, any `to_thread` cache
|
|
||||||
> threads, anything else — never executes another
|
|
||||||
> instruction post-fork.
|
|
||||||
|
|
||||||
A reader bouncing between the two can be forgiven for
|
|
||||||
asking: well, *which* is it — leaked or gone?
|
|
||||||
|
|
||||||
The answer is "yes". They're describing the same POSIX
|
|
||||||
behavior from two different angles:
|
|
||||||
|
|
||||||
- trio is talking about the **bytes** the dead threads
|
|
||||||
leave behind — stacks, TLS slots, per-thread arena
|
|
||||||
metadata — and the fact that nothing in the child can
|
|
||||||
drive them forward, free them, or even safely walk
|
|
||||||
them. That's a memory leak in the strict sense: held
|
|
||||||
but unreachable.
|
|
||||||
- tractor is talking about the **execution** side
|
|
||||||
relevant to the forkserver design: which threads
|
|
||||||
retire instructions in the child? Exactly one — the
|
|
||||||
one that called `fork()`. Everything else, regardless
|
|
||||||
of the bytes left behind, is dead in a scheduler
|
|
||||||
sense.
|
|
||||||
|
|
||||||
Neither framing is wrong; they're just answering
|
|
||||||
different questions.
|
|
||||||
|
|
||||||
## POSIX `fork()` in a multi-threaded program — what actually happens
|
|
||||||
|
|
||||||
Per POSIX (and concretely on Linux glibc), the contract
|
|
||||||
of `fork()` in a multi-threaded process is:
|
|
||||||
|
|
||||||
1. The kernel creates a new process whose virtual
|
|
||||||
address space is a COW copy of the parent's. *All*
|
|
||||||
pages map across — code, heap, every thread's stack,
|
|
||||||
every malloc arena, every mmap region.
|
|
||||||
2. Of the parent's N threads, exactly **one** is
|
|
||||||
reified in the child as a runnable kernel task: the
|
|
||||||
thread that called `fork()`. The other N-1 threads
|
|
||||||
have *no* corresponding task in the child kernel. They
|
|
||||||
were never scheduled, never `clone()`d for the child,
|
|
||||||
never exist as runnable entities.
|
|
||||||
3. Their **memory artifacts** — pthread stacks, TLS,
|
|
||||||
`pthread_t` structures, glibc per-thread arena
|
|
||||||
bookkeeping — are still mapped in the child's address
|
|
||||||
space, because (1) duplicates *everything* page-wise.
|
|
||||||
They sit there as inert COW bytes.
|
|
||||||
4. The kernel does not clean those bytes up. There is no
|
|
||||||
"phantom-thread cleanup" pass post-fork. The kernel
|
|
||||||
doesn't know which mapped pages "belonged to" which
|
|
||||||
thread — at the kernel level mappings are
|
|
||||||
process-scoped, not thread-scoped.
|
|
||||||
5. The surviving thread (the caller of `fork()`) cannot
|
|
||||||
safely access those leaked bytes either. Any state
|
|
||||||
they encoded — held mutexes, in-flight syscalls,
|
|
||||||
half-updated invariants — is frozen at whatever
|
|
||||||
instant the parent's fork-syscall observed it. Some
|
|
||||||
of those mutexes may even still be locked from the
|
|
||||||
child's POV (the canonical "fork-in-multithreaded-
|
|
||||||
program-deadlocks" hazard; see `man pthread_atfork`).
|
|
||||||
|
|
||||||
So: from the kernel's PoV, the child has one thread.
|
|
||||||
From the address-space's PoV, the child has all the
|
|
||||||
parent's bytes — including the corpses of the N-1 dead
|
|
||||||
threads' stacks. Both true simultaneously.
|
|
||||||
|
|
||||||
## Why trio says "leaked"
|
|
||||||
|
|
||||||
trio's framing makes sense from the parent's
|
|
||||||
PoV, looking at *what those threads were doing*. In a
|
|
||||||
running `trio.run()` process you typically have:
|
|
||||||
|
|
||||||
- The trio runner thread itself — owns the `selectors`
|
|
||||||
epoll fd, the signal-wakeup-fd, the run-queue.
|
|
||||||
- Threadpool worker threads (`trio.to_thread`'s cache)
|
|
||||||
— blocked in `wait()` on the threadpool's work
|
|
||||||
condvar.
|
|
||||||
- Whatever other ad-hoc threads the application
|
|
||||||
started.
|
|
||||||
|
|
||||||
Each of those threads owns *real work-state*: epoll
|
|
||||||
registrations, file descriptors held in
|
|
||||||
soon-to-be-completed reads, half-released locks, posted
|
|
||||||
but unconsumed wakeups. After fork, that state is still
|
|
||||||
encoded in the child's memory. None of it is invalid in
|
|
||||||
a well-formed-bytes sense. It's just that:
|
|
||||||
|
|
||||||
- The thread that was driving it is gone.
|
|
||||||
- Nothing else in the child knows the layout well
|
|
||||||
enough to take over.
|
|
||||||
- Even if it did, the kernel objects backing the work
|
|
||||||
(epoll fd, signalfd) have separate post-fork
|
|
||||||
semantics that don't compose with userland trio
|
|
||||||
state.
|
|
||||||
|
|
||||||
So the bytes are *held* (they're in the child's
|
|
||||||
address space, they count against RSS, they survive
|
|
||||||
until something clobbers them), and they're
|
|
||||||
*unreachable* in any meaningful sense — no thread can
|
|
||||||
safely drive them forward. That is the textbook
|
|
||||||
definition of a leak.
|
|
||||||
|
|
||||||
trio's quote is reminding the user that `fork()` from a
|
|
||||||
multi-threaded process is a one-way memory hazard:
|
|
||||||
whatever those threads were doing, that work-state is
|
|
||||||
now garbage you happen to still be carrying.
|
|
||||||
|
|
||||||
## Why tractor says "gone"
|
|
||||||
|
|
||||||
tractor's `_main_thread_forkserver` framing is concerned
|
|
||||||
with a different question: *which thread executes in the
|
|
||||||
child, and is it safe?*
|
|
||||||
|
|
||||||
The forkserver design rests on POSIX's "calling thread
|
|
||||||
is the sole survivor" guarantee. We pick that calling
|
|
||||||
thread very deliberately: a dedicated worker that has
|
|
||||||
provably never entered trio. So the thread that *does*
|
|
||||||
run in the child is one whose locals, TLS, and stack
|
|
||||||
contain nothing trio-related. Trio's runner thread —
|
|
||||||
the one that owned the epoll fd and the run-queue — is
|
|
||||||
*gone* from the child in the execution sense. It will
|
|
||||||
never run another instruction. The fact that its stack
|
|
||||||
bytes still exist in the child's address space (the
|
|
||||||
"leaked" view) is irrelevant to the forkserver, because
|
|
||||||
nothing in the child reads or writes those pages.
|
|
||||||
|
|
||||||
So when the docstring says "Every other thread … is
|
|
||||||
gone the instant `fork()` returns in the child", it's
|
|
||||||
being precise about the surface that matters for the
|
|
||||||
backend: scheduler-level liveness. Nothing schedules
|
|
||||||
those threads ever again. Whether their bytes are
|
|
||||||
hanging around is a separate (and, for the design,
|
|
||||||
non-load-bearing) fact.
|
|
||||||
|
|
||||||
## Cross-table
|
|
||||||
|
|
||||||
The same tabular layout the `_main_thread_forkserver`
|
|
||||||
docstring uses, expanded with a fourth "what handles
|
|
||||||
it" column:
|
|
||||||
|
|
||||||
| thread | parent | child (executing) | child (memory) | what handles it |
|
|
||||||
|---------------------|-----------|-------------------|------------------------------|-----------------------------|
|
|
||||||
| forkserver worker | continues | sole survivor | live stack | runs the child's bootstrap |
|
|
||||||
| `trio.run()` thread | continues | not running | leaked stack (zombie bytes) | overwritten by child's fresh `trio.run()` |
|
|
||||||
| any other thread | continues | not running | leaked stack (zombie bytes) | overwritten / GC'd / clobbered by `exec()` if used |
|
|
||||||
|
|
||||||
The "child (executing)" column is the *execution* side
|
|
||||||
of the coin — what tractor cares about. The "child
|
|
||||||
(memory)" column is the *memory* side — what trio
|
|
||||||
cares about.
|
|
||||||
|
|
||||||
The "what handles it" column is the deliberate punchline
|
|
||||||
of the design: nothing has to handle the leaked bytes
|
|
||||||
*explicitly*. They get clobbered by ordinary forward
|
|
||||||
progress in the child:
|
|
||||||
|
|
||||||
- The fresh `trio.run()` the child boots up allocates
|
|
||||||
its own stack, scheduler, and run-queue, which over
|
|
||||||
time overlaps and overwrites the inherited zombie
|
|
||||||
pages.
|
|
||||||
- Python's GC walks live objects only; the dead-thread
|
|
||||||
Python frames aren't reachable from any
|
|
||||||
`PyThreadState`, so they get freed at the next
|
|
||||||
collection cycle.
|
|
||||||
- If the child eventually `exec()`s, the entire address
|
|
||||||
space is replaced and the leak vanishes.
|
|
||||||
|
|
||||||
## What this means for the forkserver design
|
|
||||||
|
|
||||||
The crucial point is that **the design doesn't and
|
|
||||||
*can't* prevent the leak**. There is no userland fix
|
|
||||||
for COW thread stacks. The kernel hands the child a
|
|
||||||
duplicated address space; that's what `fork()` *is*. No
|
|
||||||
amount of pre-fork hookery, `pthread_atfork()`
|
|
||||||
gymnastics, or post-fork cleanup can un-COW the dead
|
|
||||||
threads' pages without unmapping them, and unmapping
|
|
||||||
arbitrary regions of a duplicated address space is
|
|
||||||
neither portable nor safe.
|
|
||||||
|
|
||||||
What the design *does* ensure is the orthogonal
|
|
||||||
property: the survivor thread is one that doesn't need
|
|
||||||
any of that leaked state to function. Concretely:
|
|
||||||
|
|
||||||
- Survivor is the forkserver worker thread.
|
|
||||||
- That worker has provably never imported, called into,
|
|
||||||
or held any reference to `trio`. (Enforced by keeping
|
|
||||||
the worker's lifecycle entirely in
|
|
||||||
`_main_thread_forkserver.py` and never letting trio
|
|
||||||
task-state cross into it.)
|
|
||||||
- So the leaked pages — trio runner stack, threadpool
|
|
||||||
caches, etc. — are inert relative to the survivor.
|
|
||||||
No code path in the child references them.
|
|
||||||
- The child then boots its own fresh `trio.run()`,
|
|
||||||
which allocates new state in new pages. Over the
|
|
||||||
child's lifetime the COW'd zombie pages get
|
|
||||||
overwritten, GC'd, or (if the child eventually
|
|
||||||
`exec()`s) discarded wholesale.
|
|
||||||
|
|
||||||
The "leak" is real but inert. It costs RSS until
|
|
||||||
clobbered; it doesn't cost correctness. That's exactly
|
|
||||||
the property the forkserver pattern is built on, and
|
|
||||||
it's also why the design needs the "calling thread is
|
|
||||||
trio-free" precondition to be airtight: if the survivor
|
|
||||||
were a trio thread, it *would* try to drive the leaked
|
|
||||||
trio state, and the leak would no longer be inert.
|
|
||||||
|
|
||||||
## See also
|
|
||||||
|
|
||||||
- `tractor/spawn/_main_thread_forkserver.py` — module
|
|
||||||
docstring's "What survives the fork? — POSIX
|
|
||||||
semantics" section is the in-tree, code-adjacent
|
|
||||||
prose this doc expands on. The cross-table here is a
|
|
||||||
fourth-column expansion of the table there.
|
|
||||||
|
|
||||||
- [python-trio/trio#1614][trio-1614] — the trio issue
|
|
||||||
with the "leaked" framing, and the canonical thread
|
|
||||||
for trio + `fork()` hazards more broadly.
|
|
||||||
|
|
||||||
- [`subint_fork_blocked_by_cpython_post_fork_issue.md`](./subint_fork_blocked_by_cpython_post_fork_issue.md)
|
|
||||||
— sibling analysis covering CPython's *post-fork*
|
|
||||||
hooks (`PyOS_AfterFork_Child`,
|
|
||||||
`_PyInterpreterState_DeleteExceptMain`) and why
|
|
||||||
fork-from-non-main-subint is a CPython-level hard
|
|
||||||
refusal. Complementary axis: this doc is about POSIX
|
|
||||||
semantics; that doc is about the CPython runtime
|
|
||||||
layer that runs *after* POSIX `fork()` returns in
|
|
||||||
the child.
|
|
||||||
|
|
||||||
- `man pthread_atfork(3)` — canonical "fork in a
|
|
||||||
multithreaded process is dangerous" reference.
|
|
||||||
Especially the rationale section, which is the
|
|
||||||
closest thing to a normative statement of "the
|
|
||||||
surviving thread cannot safely use anything the dead
|
|
||||||
threads were touching."
|
|
||||||
|
|
||||||
- `man fork(2)` (Linux) — "Other than [the calling
|
|
||||||
thread], … no other threads are replicated …"
|
|
||||||
paragraph is the kernel-side statement of the
|
|
||||||
execution-side framing this doc opens with.
|
|
||||||
|
|
||||||
[trio-1614]: https://github.com/python-trio/trio/issues/1614
|
|
||||||
|
|
@ -1,463 +0,0 @@
|
||||||
# `_ria_nursery` removal plan (issue #477 follow-up)
|
|
||||||
|
|
||||||
Goal: drop the secondary "run-in-actor" spawn nursery (and
|
|
||||||
friends) from `ActorNursery`/spawn internals, now that
|
|
||||||
`tractor.to_actor.run()` delivers one-shot semantics purely on
|
|
||||||
the daemon-spawn + portal primitives.
|
|
||||||
|
|
||||||
## Verified machinery map (2026-07-02, wkt @ a34aaf98)
|
|
||||||
|
|
||||||
The entire mechanism is 4 files:
|
|
||||||
|
|
||||||
- `runtime/_supervise.py`
|
|
||||||
- `ActorNursery.__init__(.., ria_nursery, ..)` stores
|
|
||||||
`._ria_nursery` (:202, :238); sole read is
|
|
||||||
`run_in_actor()` passing `nursery=self._ria_nursery`
|
|
||||||
(:442) into `start_actor()`'s `nursery:
|
|
||||||
trio.Nursery|None` escape-hatch param (:305, :367).
|
|
||||||
- `._cancel_after_result_on_exit: set` (:244) marks ria
|
|
||||||
portals (:457).
|
|
||||||
- `_open_and_supervise_one_cancels_all_nursery()` nests
|
|
||||||
`da_nursery` (:609) around `ria_nursery` (:622); the
|
|
||||||
`finally:` at the ria->da boundary (:747-766) raises
|
|
||||||
collected `errors` (single exc or BEG).
|
|
||||||
- `runtime/_portal.py`
|
|
||||||
- `._expect_result_ctx` (:112) set by `_submit_for_result()`
|
|
||||||
(:142, sole caller `run_in_actor()`); consumed by
|
|
||||||
`wait_for_result()` (:167) + deprecated `result()` (:220).
|
|
||||||
The `None` branch (:184-196) returns the `NoResult`
|
|
||||||
sentinel (`_exceptions.py:1164`).
|
|
||||||
- `spawn/_spawn.py`
|
|
||||||
- `exhaust_portal()` (:129): awaits
|
|
||||||
`portal.wait_for_result()`, CATCHES+RETURNS any exc
|
|
||||||
(never raises).
|
|
||||||
- `cancel_on_completion()` (:177): `exhaust_portal()` ->
|
|
||||||
on exc-result stash `errors[uid] = result` (:203) ->
|
|
||||||
ALWAYS `portal.cancel_actor()` (:218).
|
|
||||||
- `spawn/_trio.py` (:195-222) + `spawn/_mp.py` (:187-213),
|
|
||||||
identical shape: after shielded
|
|
||||||
`await an._join_procs.wait()`, open a per-child local
|
|
||||||
nursery; IFF `portal in an._cancel_after_result_on_exit`
|
|
||||||
start `cancel_on_completion` alongside `soft_kill()`; when
|
|
||||||
`soft_kill` returns first, `nursery.cancel_scope.cancel()`
|
|
||||||
reaps the result-waiter.
|
|
||||||
|
|
||||||
## The load-bearing semantic (already-deferred errors)
|
|
||||||
|
|
||||||
Remote ria-child errors NEVER raise into `ria_nursery`:
|
|
||||||
|
|
||||||
1. reaper tasks only START after `_join_procs.set()` (block
|
|
||||||
exit or the inner error handler),
|
|
||||||
2. `exhaust_portal` swallows the exc into a return value,
|
|
||||||
3. `cancel_on_completion` stashes it in `errors` + cancels
|
|
||||||
that child,
|
|
||||||
4. the ria->da `finally:` re-raises collected `errors` (and
|
|
||||||
`an.cancel()`s any daemon stragglers).
|
|
||||||
|
|
||||||
So mid-block there is NO error propagation from ria children
|
|
||||||
(unless user code explicitly `await portal.wait_for_result()`s)
|
|
||||||
— the two-nursery nesting only sequences "reap ria results
|
|
||||||
BEFORE blocking on daemon join". A single-nursery impl only
|
|
||||||
needs to preserve that sequencing, not any ASAP-cancel
|
|
||||||
behavior.
|
|
||||||
|
|
||||||
## Target design
|
|
||||||
|
|
||||||
### step A: single-nursery `run_in_actor()` (mechanical)
|
|
||||||
|
|
||||||
- `run_in_actor()` spawns via the DEFAULT (`_da_nursery`)
|
|
||||||
path — drop `nursery=self._ria_nursery`.
|
|
||||||
- rename `._cancel_after_result_on_exit` ->
|
|
||||||
`._ria_portals: dict[portal, Actor]` (need the subactor ref
|
|
||||||
for `cancel_on_completion`).
|
|
||||||
- move reaper start-up OUT of the backends into
|
|
||||||
`_open_and_supervise...`: immediately after EACH
|
|
||||||
`an._join_procs.set()` call-site (happy path :642, inner
|
|
||||||
error handler :661), start one
|
|
||||||
`cancel_on_completion(portal, subactor, errors)` task per
|
|
||||||
ria portal into `da_nursery`, then (happy path only)
|
|
||||||
`await` their completion BEFORE falling out of the
|
|
||||||
`try:`/`finally:` that raises `errors` — e.g. gather in a
|
|
||||||
dedicated inner `trio.open_nursery()` block replacing
|
|
||||||
today's `ria_nursery` join point.
|
|
||||||
- delete the membership branch + local reaper nursery from
|
|
||||||
`_trio.py`/`_mp.py` (keep the `soft_kill()` call; the
|
|
||||||
per-child local nursery collapses to just `soft_kill`).
|
|
||||||
- `_trio.py:310` `_children.pop()` etc. unchanged.
|
|
||||||
|
|
||||||
### step B: delete the plumbing
|
|
||||||
|
|
||||||
- `_open_and_supervise...`: drop the inner
|
|
||||||
`ria_nursery` + merge its `except BaseException` classify
|
|
||||||
logic into ONE handler on the (now single) nursery scope;
|
|
||||||
`ActorNursery.__init__` loses the `ria_nursery` param.
|
|
||||||
- `start_actor()` loses the `nursery:` escape-hatch param
|
|
||||||
(the :302-304 TODO).
|
|
||||||
- backends: no more `_cancel_after_result_on_exit` refs.
|
|
||||||
|
|
||||||
### step C: (separate PRs) deprecate + migrate + excise
|
|
||||||
|
|
||||||
- migrate in-repo `.run_in_actor()` usage to
|
|
||||||
`to_actor.run()`: tests 46 hits/9 files (test_cancellation
|
|
||||||
15, test_infected_asyncio 10, test_spawning 8, registrar 3,
|
|
||||||
adv_streaming 4, pubsub 2, rpc 1, runtime 1), examples 28
|
|
||||||
hits/13 files (debugging/* dominate), docs 20 hits/8 rst
|
|
||||||
files. NOTE: many sites also use deprecated
|
|
||||||
`Portal.result()`/`wait_for_result()` — these die with
|
|
||||||
`_expect_result_ctx`, so migration must land FIRST.
|
|
||||||
- add `DeprecationWarning` to `run_in_actor()` (+
|
|
||||||
`_submit_for_result`/`wait_for_result`).
|
|
||||||
- final excision: `run_in_actor()`, `_submit_for_result`,
|
|
||||||
`_expect_result_ctx`, `wait_for_result`/`result`,
|
|
||||||
`exhaust_portal`, `cancel_on_completion`, `NoResult`.
|
|
||||||
|
|
||||||
## Risk register
|
|
||||||
|
|
||||||
1. hard-killed ria child: today the backend-local
|
|
||||||
`nursery.cancel_scope.cancel()` discards a still-parked
|
|
||||||
reaper when the proc dies first; a da_nursery-hosted
|
|
||||||
reaper instead sees the transport break ->
|
|
||||||
`exhaust_portal` returns a `TransportClosed`-ish exc ->
|
|
||||||
NEW entry in `errors` that today gets discarded. Guard:
|
|
||||||
reap-gather block must cancel remaining reapers once all
|
|
||||||
ria procs are dead, or filter transport-death excs for
|
|
||||||
already-`cancel_called` children.
|
|
||||||
2. error-path ordering: inner handler today sets
|
|
||||||
`_join_procs` THEN `an.cancel()`; reapers race the
|
|
||||||
cancel-RPC. Keep that ordering when moving reaper spawn.
|
|
||||||
3. debugger interplay: `maybe_wait_for_debugger()` calls
|
|
||||||
(:654, :730) must stay BEFORE any reap/cancel issuance.
|
|
||||||
4. `errors` double-entry: local body error (:646) + child's
|
|
||||||
relayed exc (via reaper) can both land for the same
|
|
||||||
scenario -> BEG shape changes vs today? (today has the
|
|
||||||
same dual-write sites; keep behavior identical.)
|
|
||||||
5. mp backend parity: mirror every `_trio.py` edit in
|
|
||||||
`_mp.py` (identical block).
|
|
||||||
|
|
||||||
## Step-A first-probe findings (2026-07-02, WIP in tree)
|
|
||||||
|
|
||||||
Step A is IMPLEMENTED (uncommitted):
|
|
||||||
`run_in_actor()` spawns via da_nursery; new
|
|
||||||
`_supervise._reap_ria_portals()` helper; reap awaited after
|
|
||||||
happy-path `_join_procs.set()`; error-path runs reap
|
|
||||||
CONCURRENT with `an.cancel()` in the shielded block;
|
|
||||||
backends stripped of the membership branch + per-child
|
|
||||||
reaper nursery (+ dead imports).
|
|
||||||
|
|
||||||
Probe history (trio backend):
|
|
||||||
- `tests/test_to_actor.py` + `tests/test_spawning.py`:
|
|
||||||
20/20 PASS — incl. all `run_in_actor()` result
|
|
||||||
round-trips + `test_remote_error` (single erroring child,
|
|
||||||
body re-raise -> inner error path).
|
|
||||||
- FIRST attempt ran the error-path reap CONCURRENT with
|
|
||||||
`an.cancel()` (mimicking the old backend-side race):
|
|
||||||
`test_cancellation.py::test_multierror` (2 erroring ria
|
|
||||||
children, body re-raises one) DEADLOCKED. Root cause per
|
|
||||||
the sequencing fix below: reap + cancel must NOT race at
|
|
||||||
this layer (suspected `._children` pop-during-iteration
|
|
||||||
and/or double-cancel RPC wedge; not fully root-caused
|
|
||||||
since the fix removes the race wholesale).
|
|
||||||
- FIX (2nd attempt, current impl): error path SEQUENCES:
|
|
||||||
(1) snapshot ria `(portal, subactor)` pairs (backend
|
|
||||||
`finally`s pop `._children` as procs reap), (2)
|
|
||||||
`await an.cancel()`, (3) bounded reap over the snapshot.
|
|
||||||
Bound was first 3s -> blew the `fail_after` deadline in
|
|
||||||
`test_cancel_while_childs_child_in_sync_sleep` (hard-
|
|
||||||
killed grandchild never relays => reaper parks the full
|
|
||||||
bound). Tightened to 0.5s: anything collectable is
|
|
||||||
already queued in the local ctx (relayed BEFORE the
|
|
||||||
cancel); a parked reaper self-cleans (`trio.Cancelled`
|
|
||||||
results are never stashed).
|
|
||||||
- RESULT: `tests/test_cancellation.py` FULLY GREEN
|
|
||||||
(20 passed, 1 xfailed, 77s); full-suite gate run kicked
|
|
||||||
off same session (see final report/next session).
|
|
||||||
|
|
||||||
Remaining risk: on slow CI a relayed-but-undelivered error
|
|
||||||
racing the 0.5s bound could drop an `errors` entry
|
|
||||||
(BEG-shape flake); if observed, scale the bound via the
|
|
||||||
`cpu_perf_headroom()`-style approach or peek
|
|
||||||
`Portal._final_result_msg`/ctx queue state instead of
|
|
||||||
time-bounding.
|
|
||||||
|
|
||||||
## Step-B outcome (2026-07-02, done in tree)
|
|
||||||
|
|
||||||
Step A landed as `5cd190c5` (code) + `99310269` (docs).
|
|
||||||
Step B implemented on top (uncommitted):
|
|
||||||
|
|
||||||
- `._ria_nursery` is GONE — the inner
|
|
||||||
`async with (collapse_eg(), trio.open_nursery() as
|
|
||||||
ria_nursery)` layer in
|
|
||||||
`_open_and_supervise_one_cancels_all_nursery` is deleted;
|
|
||||||
`da_nursery` is now the single nursery for ALL subactors.
|
|
||||||
- `ActorNursery.__init__` drops the `ria_nursery` param +
|
|
||||||
the `self._ria_nursery` attr; `start_actor()` drops its
|
|
||||||
`nursery=` escape-hatch param (uses `self._da_nursery`
|
|
||||||
directly).
|
|
||||||
- `._cancel_after_result_on_exit` STAYS — it's the
|
|
||||||
ria-child discriminator for `_reap_ria_portals()`.
|
|
||||||
|
|
||||||
Deliberately NOT done (deferred to its own higher-risk PR,
|
|
||||||
flagged with a TODO at the outer `except`): merging the two
|
|
||||||
error handlers into one. Rationale — collapsing the empty
|
|
||||||
nursery is provably behavior-preserving (a zero-task
|
|
||||||
`trio.open_nursery()` only adds a checkpoint), whereas the
|
|
||||||
inner `except BaseException` (swallow-into-`errors`) and
|
|
||||||
outer `except (...)` (re-raise, safety-net for the inner
|
|
||||||
handler's own non-shielded awaits) have DIFFERENT
|
|
||||||
semantics; merging changes error/cancel propagation and
|
|
||||||
wants isolated review + its own gate. Both handlers are
|
|
||||||
kept, now nested directly under the single nursery.
|
|
||||||
|
|
||||||
Why the collapse is safe: post-step-A NOTHING spawns into
|
|
||||||
`ria_nursery` (its only reader, `run_in_actor`'s
|
|
||||||
`nursery=self._ria_nursery`, was removed in A; the stored
|
|
||||||
attr was never read again). So the layer was pure dead
|
|
||||||
weight.
|
|
||||||
|
|
||||||
Gate (trio backend, all 0-failure):
|
|
||||||
- targeted set (`test_cancellation test_spawning test_local
|
|
||||||
test_rpc test_to_actor`) = 49 passed, 1 xfailed.
|
|
||||||
- tail set (`test_reg_err_types remote_exc_relay
|
|
||||||
resource_cache ringbuf root_infect_asyncio root_runtime
|
|
||||||
runtime shm task_broadcasting trioisms trionics/`) = 63
|
|
||||||
passed, 1 skipped, 5 xfailed.
|
|
||||||
- full-suite head ~73% (subdirs + `test_2way`..`test_pubsub`)
|
|
||||||
= 303 passed before the known-flaky `test_dynamic_pub_sub`
|
|
||||||
TooSlowError stall (pre-existing; same hang in the step-A
|
|
||||||
full run). Suite ran slow this session (~13min vs 555s
|
|
||||||
cold, likely thermal from back-to-back runs), never
|
|
||||||
completing within an 800s bound — but split across the
|
|
||||||
above three runs EVERY module passed under step B.
|
|
||||||
|
|
||||||
## Step-B2 outcome (2026-07-02, done in tree)
|
|
||||||
|
|
||||||
Step B committed as `9201a2ed` (code) + `d2e812fb` (docs), then
|
|
||||||
branched to `drop_ria_nursery`. Step B2 (the deferred
|
|
||||||
handler-merge) implemented on top (uncommitted):
|
|
||||||
|
|
||||||
- the two nested handlers in
|
|
||||||
`_open_and_supervise_one_cancels_all_nursery` collapse to
|
|
||||||
ONE `except BaseException as _scope_err` + the existing
|
|
||||||
`finally`. The `outer_err`/`inner_err` locals go away.
|
|
||||||
|
|
||||||
Why it's safe (trace, not hope): the OLD inner handler records
|
|
||||||
`errors[actor.aid.uid]` as its FIRST statement (before any
|
|
||||||
await). So whenever an error path runs, `errors` is non-empty.
|
|
||||||
The OLD outer handler was only reachable via leakage from the
|
|
||||||
inner handler (it catches `BaseException`, so nothing from the
|
|
||||||
`yield` scope bypasses it) — and by then `errors` is already
|
|
||||||
populated, so the `finally`'s `raise` from `errors` ALWAYS
|
|
||||||
superseded the outer handler's own `raise`. i.e. the outer
|
|
||||||
`raise` was dead. The outer handler's other effects
|
|
||||||
(`_scope_error`, a 2nd debugger-wait, child-cancel) are
|
|
||||||
redundant with the merged handler + `finally`. So one handler
|
|
||||||
+ `finally` is observably equivalent.
|
|
||||||
|
|
||||||
Residual nuance (accepted): in the rare "`trio.Cancelled`
|
|
||||||
delivered during the non-shielded `maybe_wait_for_debugger`"
|
|
||||||
path, the merged form may leave `_cancel_called` False (cancel
|
|
||||||
happens after the wait), so `open_nursery`'s tb-hiding guard
|
|
||||||
(`not cancel_called and _scope_error`) can show a tb it
|
|
||||||
previously hid. More informative, not less; no test asserts on
|
|
||||||
it.
|
|
||||||
|
|
||||||
Gate (box ran ~2.7x slow this session, load-induced
|
|
||||||
`TooSlowError` flakiness on timing tests — NOT code; see
|
|
||||||
[[env_cpu_throttle_masquerades_as_regression]]):
|
|
||||||
- baseline (pre-B2 tip `9201a2ed`) full suite
|
|
||||||
(`-k 'not dynamic_pub_sub'`) = 300 passed + 1
|
|
||||||
`test_ext_types_over_ipc` `TooSlowError` that passes 6/6 in
|
|
||||||
isolation (4.89s).
|
|
||||||
- B2 error/cancel gate (`test_cancellation remote_exc_relay
|
|
||||||
inter_peer_cancellation advanced_faults oob_cancellation
|
|
||||||
to_actor spawning local rpc`) = 71 passed, 1 xfailed
|
|
||||||
(125s).
|
|
||||||
- B2 full-suite run: see `b2_full.log` (result appended on
|
|
||||||
completion). RECOMMEND a clean full-suite run on a
|
|
||||||
normal-speed box before this merges.
|
|
||||||
|
|
||||||
## Regression + fix: ria-reap hang (2026-07-02)
|
|
||||||
|
|
||||||
Human hit a full-suite hang on
|
|
||||||
`test_infected_asyncio.py::test_tractor_cancels_aio`. Bisected:
|
|
||||||
passes at pre-ria `a34aaf98` (0.59s), hangs at B2 `e617b498`
|
|
||||||
(90s+). Root-caused to the STEP-A reaper hoist (`5cd190c5`),
|
|
||||||
NOT B2 (`_reap_ria_portals` is byte-identical A->B2).
|
|
||||||
|
|
||||||
Bug: the test does `run_in_actor(asyncio_actor)` then a USER
|
|
||||||
`portal.cancel_actor()` and exits the block cleanly -> the
|
|
||||||
happy path's `await _reap_ria_portals()`, which waits UNBOUNDED
|
|
||||||
on `cancel_on_completion -> wait_for_result()`. The child was
|
|
||||||
cancelled out-of-band so no final result is relayed -> parked
|
|
||||||
forever. The OLD spawn-backend reaper was raced against
|
|
||||||
`soft_kill()` (per-child nursery `cancel_scope.cancel()` on
|
|
||||||
subproc death); the hoist dropped that race.
|
|
||||||
|
|
||||||
Fix: `_reap_ria_portals()` runs each `cancel_on_completion()`
|
|
||||||
in a local nursery alongside a `proc.poll()` death-watch that
|
|
||||||
cancels the parked reaper once the subproc exits — restoring
|
|
||||||
the old race, backend-agnostic (guarded by
|
|
||||||
`hasattr(proc, 'poll')` for a future `subint` handle).
|
|
||||||
|
|
||||||
Why POLL (`proc.poll()`) not the event-driven `wait_func`:
|
|
||||||
the mp waiter (`_spawn.proc_waiter`) does
|
|
||||||
`wait_readable(proc.sentinel)`, and `soft_kill()` is ALREADY
|
|
||||||
awaiting that same fd concurrently in the daemon nursery — a
|
|
||||||
2nd `wait_readable` on one fd raises `trio.BusyResourceError`.
|
|
||||||
(`trio.Process.wait()` IS multi-waiter-safe, but mp has no
|
|
||||||
async equivalent.) `proc.poll()` — the same liveness check
|
|
||||||
`soft_kill` itself falls back to — is the conflict-free common
|
|
||||||
denominator. Verified: poll-fix passes on BOTH trio and
|
|
||||||
mp_spawn.
|
|
||||||
|
|
||||||
Also added a per-test anti-hang guard: wrapped
|
|
||||||
`test_tractor_cancels_aio`'s `main()` in
|
|
||||||
`with trio.fail_after(9 * cpu_perf_headroom())` — the blessed
|
|
||||||
pattern (`pytest-timeout`'s global cap is intentionally off;
|
|
||||||
breaks trio under fork backends, see `pyproject` NOTE). So a
|
|
||||||
future recurrence FAILS FAST instead of hanging the suite.
|
|
||||||
(Several other tests in the file are still guardless —
|
|
||||||
`test_aio_simple_error`, `test_trio_error_cancels_intertask_chan`,
|
|
||||||
`test_aio_errors_and_channel_propagates_and_closes` — candidate
|
|
||||||
follow-up sweep.)
|
|
||||||
|
|
||||||
Lesson: the B2 focused gate OMITTED `test_infected_asyncio`
|
|
||||||
(and the full runs were clipped/slow), so the step-A hang
|
|
||||||
slipped through. Any future ria-touching change MUST gate
|
|
||||||
`test_infected_asyncio` explicitly.
|
|
||||||
|
|
||||||
Gate: `test_tractor_cancels_aio` green (trio 1.53s, mp 3.98s);
|
|
||||||
fix gate (`test_infected_asyncio test_cancellation test_to_actor
|
|
||||||
test_spawning`) = 74 passed, 3 xfailed, 0 failures.
|
|
||||||
|
|
||||||
## PAUSED (2026-07-02): re-assess the reaper's SCOPE
|
|
||||||
|
|
||||||
User's insight (compelling — likely the real root cause of
|
|
||||||
the hang, not just the missing proc-death race):
|
|
||||||
|
|
||||||
> the "hoisting" of 5cd190c5 was just not really done right
|
|
||||||
> — the hoist should have been into the `to_actor` scope,
|
|
||||||
> not `_supervise`.
|
|
||||||
|
|
||||||
The argument: `.run_in_actor()`'s result-waiting/reaping got
|
|
||||||
hoisted into `_supervise._reap_ria_portals` (nursery-machinery
|
|
||||||
scope), which has NO natural cancel-scope to bound a parked
|
|
||||||
`wait_for_result()` — hence the awkward proc-death race +
|
|
||||||
the poll-vs-`proc_waiter` dilemma. If the result-wait instead
|
|
||||||
lived in the `to_actor` one-shot scope
|
|
||||||
(`to_actor._invoke_in_subactor()`), it would sit right next to
|
|
||||||
the caller's `an` + a local `trio` task-nursery + cancel-scope
|
|
||||||
(the `trio.to_thread`-style model #477 actually wants) — so
|
|
||||||
bounding/cancelling the wait is trivial and the hang
|
|
||||||
dissolves from correct scoping rather than a bolt-on race.
|
|
||||||
|
|
||||||
Follow-on to re-evaluate on resume:
|
|
||||||
- should `_reap_ria_portals` exist AT ALL, or should
|
|
||||||
result-waiting move entirely into
|
|
||||||
`to_actor._invoke_in_subactor()`?
|
|
||||||
- reimplement legacy `run_in_actor()` on top of
|
|
||||||
`to_actor.run()` so `_reap_ria_portals` +
|
|
||||||
`_cancel_after_result_on_exit` can be DROPPED from
|
|
||||||
`_supervise` entirely (the true #477 simplification)?
|
|
||||||
- the poll-vs-event decision is MOOT under this re-scoping.
|
|
||||||
|
|
||||||
State at pause: `test_infected_asyncio` anti-hang guard
|
|
||||||
COMMITTED (`d1fb4a1a`, intentionally red w/o the fix — the
|
|
||||||
user's failing-test-first convention). The poll-based reap
|
|
||||||
fix in `_supervise.py` is UNCOMMITTED and likely SUPERSEDED
|
|
||||||
by the re-scoping — do NOT land it as-is.
|
|
||||||
|
|
||||||
## RESOLVED (2026-07-06): migrate everything, remove the API
|
|
||||||
|
|
||||||
The PAUSED re-assessment concluded decisively: rather than
|
|
||||||
re-scope `_reap_ria_portals` (or bolt any hack onto it), the
|
|
||||||
`run_in_actor()` API itself was REMOVED — its non-blocking
|
|
||||||
"result at teardown" semantic predates streaming and confused
|
|
||||||
more than it served. Every in-repo caller was migrated
|
|
||||||
per-file/-group (each its own commit, each gated):
|
|
||||||
|
|
||||||
- tests: `test_infected_asyncio` `test_runtime` `test_rpc`
|
|
||||||
`test_spawning` `test_pubsub` `test_registrar`
|
|
||||||
`test_cancellation` (3 groups) `test_advanced_streaming`.
|
|
||||||
- examples: 4 non-debugging + all 8 `debugging/` REPL scripts
|
|
||||||
(debugger suite byte-identical green, 28p/6s).
|
|
||||||
- docs: 8 rst pages + the `experimental/_pubsub` docstring.
|
|
||||||
|
|
||||||
Migration patterns (the `run_in_actor` shape -> successor):
|
|
||||||
|
|
||||||
- blocking result -> `to_actor.run(fn, an=an, ...)`
|
|
||||||
- fire-&-forget/forever -> bg `to_actor.run()` task in a local
|
|
||||||
`trio` task-nursery (or `start_actor`
|
|
||||||
+ bg `Portal.run()` when a portal
|
|
||||||
handle is needed)
|
|
||||||
- concurrent fan-out -> N bg `to_actor.run()` tasks / or
|
|
||||||
`gather_contexts([p.open_context(..)])`
|
|
||||||
- reap-all-error-collect -> the "collect don't cancel" pattern:
|
|
||||||
each one-shot catches + stashes its
|
|
||||||
`RemoteActorError`, group raised
|
|
||||||
after the task-nursery joins (see
|
|
||||||
`examples/debugging/multi_subactors.py`)
|
|
||||||
- mutual-rendezvous -> peers must OUTLIVE both dialogs:
|
|
||||||
`start_actor()` daemons + concurrent
|
|
||||||
`Portal.run()`s + explicit
|
|
||||||
`an.cancel()` (eager one-shot reap
|
|
||||||
races the slower peer's dial of the
|
|
||||||
winner's dead sockaddr; found via
|
|
||||||
`test_trynamic_trio` flake).
|
|
||||||
|
|
||||||
Semantic deltas (tests loosened accordingly):
|
|
||||||
|
|
||||||
- teardown-reap-all BEG-of-N is GONE: local task-nurseries are
|
|
||||||
cancel-on-first, raced siblings' `Cancelled`s are absorbed,
|
|
||||||
and the runtime's `collapse_eg()` unwraps every single-member
|
|
||||||
group at each actor boundary — a fully-raced nested tree
|
|
||||||
relays a bare (annotated) `RemoteActorError` chain.
|
|
||||||
- `test_multierror_fast_nursery`'s obsolete BEG-of-25 assertion
|
|
||||||
deleted; `test_concurrent_start_error_reaps_all` retains its
|
|
||||||
high-fan-out startup/cancel/reap stress under caller-scoped
|
|
||||||
semantics.
|
|
||||||
- `test_nested_multierrors` re-purposed separately as deep-tree
|
|
||||||
cancel-cascade stress w/ a race-tolerant shape walk.
|
|
||||||
|
|
||||||
Final excision (after zero callers remained): `run_in_actor()`,
|
|
||||||
`._cancel_after_result_on_exit`, `_reap_ria_portals()`,
|
|
||||||
`Portal._submit_for_result/._expect_result_ctx/
|
|
||||||
.wait_for_result()/.result()`, `exhaust_portal()`,
|
|
||||||
`cancel_on_completion()`, `NoResult` — net -402 lines. The
|
|
||||||
reap-hang class (unbounded `wait_for_result` in machinery
|
|
||||||
scope) dissolves structurally: the only result-wait left lives
|
|
||||||
in the caller's task inside its own cancel-scope; the
|
|
||||||
`d1fb4a1a` anti-hang guard test passes by construction. The
|
|
||||||
poll-vs-`proc_waiter` debate is moot as predicted.
|
|
||||||
|
|
||||||
## Follow-up sketch: `to_actor.open_one_shot()` (run-async parity)
|
|
||||||
|
|
||||||
If deferred-result parity is ever wanted, the design that needs
|
|
||||||
NO runtime coupling, NO returned `Portal` and NO cancel-relay
|
|
||||||
`trio.Event` machinery:
|
|
||||||
|
|
||||||
async with to_actor.open_one_shot(
|
|
||||||
fn, an=an, **kws,
|
|
||||||
) as one_shot:
|
|
||||||
... # concurrent caller work
|
|
||||||
val = await one_shot.wait() # optional; errors always
|
|
||||||
# propagate at scope exit
|
|
||||||
|
|
||||||
an `@acm` that opens a private task-nursery, `start_soon`s ONE
|
|
||||||
task running the existing blocking `run()` and stashes the
|
|
||||||
value in a slot + sets a done-`trio.Event` (a memo, not a
|
|
||||||
cancel relay). Cancellation = plain scope-cancel of the acm's
|
|
||||||
nursery (the parked `Portal.run()` unwinds via `Cancelled`, the
|
|
||||||
shielded `cancel_actor()` reap still runs); a child error
|
|
||||||
raises into the acm scope so an un-`wait()`ed one-shot can
|
|
||||||
never silently drop its error. i.e. the old reaper's job is
|
|
||||||
done by scoping, not machinery. ~40 lines, all in
|
|
||||||
`to_actor/_api.py`, zero `_supervise` involvement.
|
|
||||||
|
|
||||||
## Verification gate
|
|
||||||
|
|
||||||
- per-migration-commit module gates on `trio` (+ `mp_spawn`
|
|
||||||
spot-gates incl. `test_infected_asyncio` per the B2 lesson);
|
|
||||||
`tests/devx/test_debugger.py` for the REPL flows.
|
|
||||||
- full suite on `trio` + `mp_spawn` at branch tip + CI matrix
|
|
||||||
via draft PR #484.
|
|
||||||
|
|
@ -1,142 +0,0 @@
|
||||||
# Spawn-time boot-death (`rc=2`) under rapid same-name spawn against a registrar
|
|
||||||
|
|
||||||
## Symptom
|
|
||||||
|
|
||||||
Spawning N (≥4) sub-actors with the **same name** in tight
|
|
||||||
succession against a daemon registrar surfaces as
|
|
||||||
`ActorFailure: Sub-actor (...) died during boot (rc=2)
|
|
||||||
before completing parent-handshake`.
|
|
||||||
|
|
||||||
```
|
|
||||||
tests/discovery/test_multi_program.py
|
|
||||||
::test_dup_name_cancel_cascade_escalates_to_hard_kill[n_dups=4]
|
|
||||||
```
|
|
||||||
|
|
||||||
```
|
|
||||||
tractor._exceptions.ActorFailure:
|
|
||||||
Sub-actor ('doggy', '<uuid>') died during boot (rc=2)
|
|
||||||
before completing parent-handshake.
|
|
||||||
proc: <_ForkedProc pid=<n> returncode=None>
|
|
||||||
```
|
|
||||||
|
|
||||||
The `proc` repr shows `returncode=None` because the repr is
|
|
||||||
captured before `proc.wait()` returns; the actual
|
|
||||||
`os.WEXITSTATUS == 2` is reported via `result['died']` in the
|
|
||||||
race-helper.
|
|
||||||
|
|
||||||
## When it surfaces
|
|
||||||
|
|
||||||
- N=2 (`n_dups=2`): **always passes**.
|
|
||||||
- N=4 (`n_dups=4`): **consistent fail** under both `tpt-proto=tcp`
|
|
||||||
and `tpt-proto=uds`, MTF backend.
|
|
||||||
- N=8 (`n_dups=8`): **passes** (counter-intuitive — see "racing
|
|
||||||
windows").
|
|
||||||
- Non-MTF backends: not yet exercised systematically.
|
|
||||||
|
|
||||||
## What previously masked it
|
|
||||||
|
|
||||||
Pre the spawn-time `wait_for_peer_or_proc_death` race-helper
|
|
||||||
(in `tractor.spawn._spawn`), the parent's `start_actor` flow
|
|
||||||
ended with a bare:
|
|
||||||
|
|
||||||
```python
|
|
||||||
event, chan = await ipc_server.wait_for_peer(uid)
|
|
||||||
```
|
|
||||||
|
|
||||||
That awaits an unsignalled `trio.Event` on `_peer_connected[uid]`.
|
|
||||||
If the sub-actor process **dies during boot** (before its
|
|
||||||
runtime executes the parent-callback handshake that sets the
|
|
||||||
event), the wait parks forever. The dead proc becomes a zombie
|
|
||||||
because no one ever calls `proc.wait()` to reap it.
|
|
||||||
|
|
||||||
In test contexts the failure presented as a hang or a much
|
|
||||||
later `trio.TooSlowError` from an outer `fail_after`. In
|
|
||||||
production it'd present as a parent that never makes progress
|
|
||||||
past `start_actor`. The death itself was silently masked.
|
|
||||||
|
|
||||||
## What surfaces it now
|
|
||||||
|
|
||||||
`tractor.spawn._spawn.wait_for_peer_or_proc_death` (used by
|
|
||||||
`_main_thread_forkserver_proc`) races the handshake-wait
|
|
||||||
against `proc.wait()`. The race-helper raises `ActorFailure`
|
|
||||||
on death-first instead of parking, exposing the rc=2.
|
|
||||||
|
|
||||||
## Hypothesis: registrar-side same-name contention
|
|
||||||
|
|
||||||
The test spawns N actors with name `doggy` sequentially:
|
|
||||||
|
|
||||||
```python
|
|
||||||
for i in range(n_dups):
|
|
||||||
p: Portal = await an.start_actor('doggy')
|
|
||||||
portals.append(p)
|
|
||||||
```
|
|
||||||
|
|
||||||
Each spawned doggy:
|
|
||||||
|
|
||||||
1. Forks via the forkserver.
|
|
||||||
2. Boots its runtime in `_actor_child_main`.
|
|
||||||
3. Connects back to the parent for handshake.
|
|
||||||
4. Connects to the daemon registrar to call `register_actor`.
|
|
||||||
5. Enters its RPC msg-loop.
|
|
||||||
|
|
||||||
Step (4) is where the same-name contention lives. The
|
|
||||||
registrar's `register_actor` (in
|
|
||||||
`tractor.discovery._registry`) accepts duplicate names
|
|
||||||
(stores `(name, uuid) -> addr`), but its internal bookkeeping
|
|
||||||
may have a non-trivial check (e.g. `wait_for_actor` resolution,
|
|
||||||
`_addrs2aids` map updates) that errors out under specific
|
|
||||||
ordering between the existing entry and the incoming one.
|
|
||||||
|
|
||||||
`rc=2 == os.WEXITSTATUS == 2` corresponds to `sys.exit(2)`
|
|
||||||
in the doggy process — typically reached via an unhandled
|
|
||||||
exception that's translated to exit code 2 by Python's top-
|
|
||||||
level (e.g. `argparse` errors use 2; `SystemExit(2)` etc.).
|
|
||||||
So the doggy is hitting an explicit exit path during
|
|
||||||
`register_actor` or just-after.
|
|
||||||
|
|
||||||
The non-monotonic shape (N=2 OK, N=4 BAD, N=8 OK) suggests a
|
|
||||||
specific timing window — likely "the 3rd register-RPC arrives
|
|
||||||
while the 1st-or-2nd is in some intermediate state". With
|
|
||||||
N=8, the additional procs widen the registration spread
|
|
||||||
enough that no two land in the conflicting window.
|
|
||||||
|
|
||||||
## Where to dig next
|
|
||||||
|
|
||||||
- Add per-actor logging in `_actor_child_main` and
|
|
||||||
`register_actor` to surface the actual exception that
|
|
||||||
triggers the rc=2 exit. Currently the doggy dies before
|
|
||||||
the parent ever sees its stderr (forkserver doesn't
|
|
||||||
marshal child stdio back).
|
|
||||||
- Race-test the registrar's `register_actor` /
|
|
||||||
`unregister_actor` / `wait_for_actor` against same-name
|
|
||||||
concurrent calls in isolation (no spawn).
|
|
||||||
- Consider whether `register_actor` should be idempotent
|
|
||||||
under same-name re-register or should explicitly reject
|
|
||||||
same-name (and ideally with a clear `RemoteActorError`,
|
|
||||||
not `sys.exit(2)`).
|
|
||||||
|
|
||||||
## Test-suite handling
|
|
||||||
|
|
||||||
Currently:
|
|
||||||
|
|
||||||
- `tests/discovery/test_multi_program.py
|
|
||||||
::test_dup_name_cancel_cascade_escalates_to_hard_kill[n_dups=4]`
|
|
||||||
is `pytest.mark.xfail(strict=False, reason=...)` to keep
|
|
||||||
the suite green while this issue is investigated.
|
|
||||||
- `n_dups=2` and `n_dups=8` continue to validate the
|
|
||||||
cancel-cascade hard-kill escalation.
|
|
||||||
|
|
||||||
Once the underlying race is understood + fixed, drop the
|
|
||||||
xfail.
|
|
||||||
|
|
||||||
## Related work
|
|
||||||
|
|
||||||
- The cancel-cascade fix that introduced this regression
|
|
||||||
test:
|
|
||||||
`tractor/_exceptions.py:ActorTooSlowError`,
|
|
||||||
`tractor/runtime/_supervise.py:_try_cancel_then_kill`,
|
|
||||||
`tractor/runtime/_portal.py:Portal.cancel_actor(
|
|
||||||
raise_on_timeout=...)`.
|
|
||||||
- The spawn-time death-detection that exposed this:
|
|
||||||
`tractor/spawn/_spawn.py:wait_for_peer_or_proc_death`,
|
|
||||||
used by `tractor/spawn/_main_thread_forkserver.py`.
|
|
||||||
|
|
@ -1,273 +0,0 @@
|
||||||
# `test_register_duplicate_name` racy connect-failure on `daemon` fixture readiness
|
|
||||||
|
|
||||||
## Symptom
|
|
||||||
|
|
||||||
`tests/test_multi_program.py::test_register_duplicate_name`
|
|
||||||
fails intermittently under BOTH transports + ALL spawn
|
|
||||||
backends with connect-refused errors:
|
|
||||||
|
|
||||||
```
|
|
||||||
# under --tpt-proto=uds
|
|
||||||
FAILED tests/test_multi_program.py::test_register_duplicate_name
|
|
||||||
- ConnectionRefusedError: [Errno 111] Connection refused
|
|
||||||
( ^^^ this exc was collapsed from a group ^^^ )
|
|
||||||
|
|
||||||
# under --tpt-proto=tcp
|
|
||||||
FAILED tests/test_multi_program.py::test_register_duplicate_name
|
|
||||||
- OSError: all attempts to connect to 127.0.0.1:36003 failed
|
|
||||||
( ^^^ this exc was collapsed from a group ^^^ )
|
|
||||||
```
|
|
||||||
|
|
||||||
Distinct from the cancel-cascade `TooSlowError` flake
|
|
||||||
class — see
|
|
||||||
`cancel_cascade_too_slow_under_main_thread_forkserver_issue.md`.
|
|
||||||
This is a **connect-time race** before the daemon is
|
|
||||||
fully ready to `accept()`, not a teardown-cascade
|
|
||||||
slowness.
|
|
||||||
|
|
||||||
## Root cause: blind `time.sleep()` in `daemon` fixture
|
|
||||||
|
|
||||||
`tests/conftest.py::daemon` boots a sub-py-process via
|
|
||||||
`subprocess.Popen([python, '-c', 'tractor.run_daemon(...)'])`,
|
|
||||||
then **blindly sleeps** a fixed delay before yielding
|
|
||||||
`proc` to the test:
|
|
||||||
|
|
||||||
```python
|
|
||||||
# excerpt from tests/conftest.py::daemon
|
|
||||||
proc = subprocess.Popen([
|
|
||||||
sys.executable, '-c', code,
|
|
||||||
])
|
|
||||||
|
|
||||||
bg_daemon_spawn_delay: float = _PROC_SPAWN_WAIT # 0.6
|
|
||||||
if tpt_proto == 'uds':
|
|
||||||
bg_daemon_spawn_delay += 1.6
|
|
||||||
if _non_linux and ci_env:
|
|
||||||
bg_daemon_spawn_delay += 1
|
|
||||||
|
|
||||||
# XXX, allow time for the sub-py-proc to boot up.
|
|
||||||
# !TODO, see ping-polling ideas above!
|
|
||||||
time.sleep(bg_daemon_spawn_delay)
|
|
||||||
|
|
||||||
assert not proc.returncode
|
|
||||||
yield proc
|
|
||||||
```
|
|
||||||
|
|
||||||
Inherent fragility: the delay is "long enough on dev
|
|
||||||
boxes most of the time" but has no actual
|
|
||||||
synchronization with the daemon's `bind()` + `listen()`
|
|
||||||
completion. Under any of:
|
|
||||||
|
|
||||||
- Loaded box (CI parallelism, big rebuild in
|
|
||||||
background, low-cpu-freq)
|
|
||||||
- Cold first-run (`importlib` cache miss, JIT warmup)
|
|
||||||
- Higher-than-expected `tractor` import cost
|
|
||||||
- Filesystem latency (UDS sockfile create, slow
|
|
||||||
tmpfs)
|
|
||||||
|
|
||||||
...the sleep finishes BEFORE the daemon has bound its
|
|
||||||
listen socket → first test client call to
|
|
||||||
`tractor.find_actor()` / `wait_for_actor()` /
|
|
||||||
`open_nursery(registry_addrs=[reg_addr])`'s implicit
|
|
||||||
connect → `ConnectionRefusedError` (TCP) or
|
|
||||||
`FileNotFoundError`/`ConnectionRefusedError` (UDS).
|
|
||||||
|
|
||||||
## Reproducer
|
|
||||||
|
|
||||||
Easiest: run the suite under load.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# create CPU pressure on another core in parallel
|
|
||||||
stress-ng --cpu 2 --timeout 600s &
|
|
||||||
|
|
||||||
./py313/bin/python -m pytest \
|
|
||||||
tests/test_multi_program.py::test_register_duplicate_name \
|
|
||||||
--spawn-backend=main_thread_forkserver \
|
|
||||||
--tpt-proto=tcp -v
|
|
||||||
```
|
|
||||||
|
|
||||||
Reproduces ~30-50% of the time on a dev laptop. On a
|
|
||||||
quiet idle box, may need 5-10 runs to hit.
|
|
||||||
|
|
||||||
## Why the existing `_PROC_SPAWN_WAIT` tuning is
|
|
||||||
inadequate
|
|
||||||
|
|
||||||
Recent `bg_daemon_spawn_delay` rename
|
|
||||||
(de-monotonic-grow fix) just-shipped removed the
|
|
||||||
*accumulation* bug where each invocation made the
|
|
||||||
NEXT test's wait longer too. Net effect: every
|
|
||||||
invocation now uses the SAME `0.6 + 1.6` (UDS) or
|
|
||||||
`0.6` (TCP) sleep, no growth. Good — but does
|
|
||||||
NOTHING for the underlying race. Each individual
|
|
||||||
test still relies on a blind sleep that may or may
|
|
||||||
not be sufficient.
|
|
||||||
|
|
||||||
Bumping the constant higher pushes flake rate down
|
|
||||||
but never to zero AND adds dead time to every
|
|
||||||
non-flaking run. Not a fix, just a knob.
|
|
||||||
|
|
||||||
## Side effects
|
|
||||||
|
|
||||||
- **Inter-test cascade**: a single failure can cascade
|
|
||||||
via leaked subprocesses (the `daemon` fixture's
|
|
||||||
cleanup may not fully tear down a daemon that never
|
|
||||||
reached "ready"). The `_reap_orphaned_subactors`
|
|
||||||
session-end + `_track_orphaned_uds_per_test`
|
|
||||||
per-test fixtures handle most of this now, but the
|
|
||||||
affected test itself still fails.
|
|
||||||
- **Worsens under fork-spawn backends**: the daemon
|
|
||||||
has more init work
|
|
||||||
(`_main_thread_forkserver`-coordinator-thread
|
|
||||||
startup, etc.) so the sleep has to cover MORE.
|
|
||||||
|
|
||||||
## Fix design — replace blind sleep with active poll
|
|
||||||
|
|
||||||
The right primitive is **poll the daemon's bind
|
|
||||||
address until it accepts a connection or we time
|
|
||||||
out**, with the timeout being a hard ceiling rather
|
|
||||||
than a baseline. Two implementation paths:
|
|
||||||
|
|
||||||
### Path A — TCP/UDS connect-poll loop
|
|
||||||
|
|
||||||
Try `socket.connect(reg_addr)` in a tight loop with
|
|
||||||
short backoff (~50ms), succeed on the first non-error
|
|
||||||
return, fail-loud on a hard cap (e.g. 10s). Same
|
|
||||||
primitive works for both transports because both use
|
|
||||||
`socket.connect()` semantics.
|
|
||||||
|
|
||||||
Rough shape:
|
|
||||||
|
|
||||||
```python
|
|
||||||
def _wait_for_daemon_ready(
|
|
||||||
reg_addr,
|
|
||||||
tpt_proto: str,
|
|
||||||
timeout: float = 10.0,
|
|
||||||
poll_interval: float = 0.05,
|
|
||||||
) -> None:
|
|
||||||
deadline = time.monotonic() + timeout
|
|
||||||
while True:
|
|
||||||
if tpt_proto == 'tcp':
|
|
||||||
sock = socket.socket(socket.AF_INET)
|
|
||||||
target = reg_addr # (host, port)
|
|
||||||
else: # uds
|
|
||||||
sock = socket.socket(socket.AF_UNIX)
|
|
||||||
target = os.path.join(*reg_addr)
|
|
||||||
try:
|
|
||||||
sock.settimeout(poll_interval)
|
|
||||||
sock.connect(target)
|
|
||||||
except (
|
|
||||||
ConnectionRefusedError,
|
|
||||||
FileNotFoundError,
|
|
||||||
socket.timeout,
|
|
||||||
) as exc:
|
|
||||||
if time.monotonic() >= deadline:
|
|
||||||
raise TimeoutError(
|
|
||||||
f'Daemon never accepted on {target!r} '
|
|
||||||
f'within {timeout}s'
|
|
||||||
) from exc
|
|
||||||
time.sleep(poll_interval)
|
|
||||||
else:
|
|
||||||
sock.close()
|
|
||||||
return
|
|
||||||
```
|
|
||||||
|
|
||||||
Pros: trivial primitive, no tractor-runtime
|
|
||||||
dependency, works pre-yield in the fixture body,
|
|
||||||
fail-fast on truly-broken daemon.
|
|
||||||
Cons: doesn't actually do an IPC handshake, just
|
|
||||||
proves listen-side is up. A daemon that bound but
|
|
||||||
hasn't initialized its registrar table yet would
|
|
||||||
still race.
|
|
||||||
|
|
||||||
### Path B — `tractor.find_actor()` poll
|
|
||||||
|
|
||||||
Use the actual discovery API the test would call:
|
|
||||||
|
|
||||||
```python
|
|
||||||
async def _wait_for_daemon_ready_via_discovery(
|
|
||||||
reg_addr,
|
|
||||||
timeout: float = 10.0,
|
|
||||||
poll_interval: float = 0.05,
|
|
||||||
):
|
|
||||||
deadline = trio.current_time() + timeout
|
|
||||||
async with tractor.open_root_actor(
|
|
||||||
registry_addrs=[reg_addr],
|
|
||||||
# ephemeral root just for the probe
|
|
||||||
):
|
|
||||||
while True:
|
|
||||||
try:
|
|
||||||
async with tractor.find_actor(
|
|
||||||
'registrar', # daemon's own name
|
|
||||||
registry_addrs=[reg_addr],
|
|
||||||
) as portal:
|
|
||||||
if portal is not None:
|
|
||||||
return
|
|
||||||
except Exception:
|
|
||||||
pass
|
|
||||||
if trio.current_time() >= deadline:
|
|
||||||
raise TimeoutError(...)
|
|
||||||
await trio.sleep(poll_interval)
|
|
||||||
```
|
|
||||||
|
|
||||||
Pros: actually proves the discovery path works,
|
|
||||||
handles the "bound but not ready" case naturally.
|
|
||||||
Cons: requires booting an ephemeral root actor JUST
|
|
||||||
for the probe (overhead), more code, and runs in trio
|
|
||||||
which complicates the sync-fixture context. Need a
|
|
||||||
`trio.run()` wrapper.
|
|
||||||
|
|
||||||
### Recommended: Path A with optional handshake check
|
|
||||||
|
|
||||||
Path A is much simpler + handles 95% of the bug
|
|
||||||
class. If "bound-but-not-ready" turns out to still
|
|
||||||
race (it shouldn't — `tractor.run_daemon` doesn't
|
|
||||||
return from `bind()` until the registrar is
|
|
||||||
fully populated), escalate to Path B as a focused
|
|
||||||
follow-up.
|
|
||||||
|
|
||||||
## Workarounds (until fix lands)
|
|
||||||
|
|
||||||
1. **Bump `_PROC_SPAWN_WAIT`** higher (current: 0.6).
|
|
||||||
2.0–3.0 hides most flakes at the cost of adding
|
|
||||||
dead time to every test. Not a fix but reduces
|
|
||||||
blast radius while the proper poll lands.
|
|
||||||
2. **`pytest-rerunfailures`** with `reruns=1` on the
|
|
||||||
`daemon` fixture's tests specifically. Hides the
|
|
||||||
flake but doesn't address it.
|
|
||||||
3. **Mark known-affected tests as `xfail(strict=False)`**
|
|
||||||
under `--ci`. Lets CI go green at the cost of
|
|
||||||
silently hiding regressions.
|
|
||||||
|
|
||||||
(Recommend skipping all three — implement the active
|
|
||||||
poll instead.)
|
|
||||||
|
|
||||||
## Investigation next steps
|
|
||||||
|
|
||||||
1. Implement Path A as a `_wait_for_daemon_ready()`
|
|
||||||
helper in `tests/conftest.py`. Replace the
|
|
||||||
`time.sleep(bg_daemon_spawn_delay)` call with it.
|
|
||||||
2. Drop the `_PROC_SPAWN_WAIT` constant entirely
|
|
||||||
(active poll obsoletes blind sleep).
|
|
||||||
3. Run the suite 5-10 times to validate flake rate
|
|
||||||
drops to 0.
|
|
||||||
4. If flakes persist, profile whether the daemon
|
|
||||||
process exits with non-zero before the poll's
|
|
||||||
deadline hits — that'd be a different bug
|
|
||||||
(daemon startup crash) that the blind sleep was
|
|
||||||
masking.
|
|
||||||
5. Cross-check `tests/test_multi_program.py::test_*`
|
|
||||||
— multiple tests use the `daemon` fixture; all
|
|
||||||
should benefit from the same poll primitive.
|
|
||||||
|
|
||||||
## Related
|
|
||||||
|
|
||||||
- `tests/conftest.py::daemon` — the fixture under
|
|
||||||
fix
|
|
||||||
- `tests/conftest.py::_PROC_SPAWN_WAIT` — the
|
|
||||||
constant to drop
|
|
||||||
- `cancel_cascade_too_slow_under_main_thread_forkserver_issue.md`
|
|
||||||
— distinct flake class (cancel-cascade
|
|
||||||
`TooSlowError` at teardown, not connect-time race)
|
|
||||||
- `trio_wakeup_socketpair_busy_loop_under_fork_issue.md`
|
|
||||||
— different bug entirely; this race was masked
|
|
||||||
pre-WakeupSocketpair-patch by the busy-loop
|
|
||||||
hangs.
|
|
||||||
|
|
@ -1,102 +0,0 @@
|
||||||
# `trio` 0.29 -> 0.33 slows the depth=3 cancel-cascade
|
|
||||||
|
|
||||||
## Symptom
|
|
||||||
|
|
||||||
After locking to `trio==0.33.0` (commit `c7741bba`, was
|
|
||||||
`0.29.0`), this test reliably trips its `fail_after`
|
|
||||||
deadline on the **`trio`** backend:
|
|
||||||
|
|
||||||
```
|
|
||||||
FAILED tests/test_cancellation.py::test_nested_multierrors[start_method=trio-depth=3]
|
|
||||||
- AssertionError: assert False
|
|
||||||
where False = isinstance(
|
|
||||||
Cancelled(source='deadline', source_task=None, reason=None),
|
|
||||||
tractor.RemoteActorError,
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
A `fail_after_w_trace` hang-snapshot is captured for the
|
|
||||||
test each run (deadline-injected `Cancelled` wrapped into
|
|
||||||
the actor-nursery `BaseExceptionGroup`).
|
|
||||||
|
|
||||||
## Root cause (immediate)
|
|
||||||
|
|
||||||
The test budgets `fail_after(6)` for the `trio` backend.
|
|
||||||
That 6s was chosen (commit `32955db0`, while `trio==0.29`)
|
|
||||||
with the assertion that trio finishes "well under" 6s.
|
|
||||||
The `trio` 0.29 -> 0.33 bump slowed the depth=3 cascade
|
|
||||||
past that budget, so the 6s deadline now fires mid-cascade.
|
|
||||||
|
|
||||||
trio 0.33 added **cancel-reason tracking** — every
|
|
||||||
`Cancelled` now carries `(source=, reason=, source_task=)`.
|
|
||||||
The injected exc is `Cancelled(source='deadline')`, i.e.
|
|
||||||
trio itself naming our `fail_after(6)` scope as the cancel
|
|
||||||
origin. When that `Cancelled` collapses one branch of the
|
|
||||||
nursery BEG, the test's `isinstance(subexc,
|
|
||||||
RemoteActorError)` assertion fails. The healthy outcome is
|
|
||||||
`BEG = [RemoteActorError, RemoteActorError]`; the
|
|
||||||
`Cancelled` is purely an artifact of the deadline cutting
|
|
||||||
the cascade short.
|
|
||||||
|
|
||||||
## Measurements (standalone, this machine)
|
|
||||||
|
|
||||||
```
|
|
||||||
depth=1 trio ~3.15s PASS (keeps 6s budget)
|
|
||||||
depth=3 trio ~6.8-8.2s FAIL @ 6s (now bumped to 12s)
|
|
||||||
```
|
|
||||||
|
|
||||||
depth=1 still fits comfortably; only depth=3 (deeper
|
|
||||||
recursive spawn-and-error tree => more actors to reap)
|
|
||||||
exceeds the old budget. The ~2s/depth-level cost looks
|
|
||||||
like serialized per-actor reap / `terminate_after` waits.
|
|
||||||
|
|
||||||
## Mitigation applied
|
|
||||||
|
|
||||||
`test_nested_multierrors` now splits the `trio` budget:
|
|
||||||
|
|
||||||
```python
|
|
||||||
case ('trio', 1):
|
|
||||||
timeout = 6
|
|
||||||
case ('trio', 3):
|
|
||||||
timeout = 12 # was 6; see this doc
|
|
||||||
```
|
|
||||||
|
|
||||||
This stops the deadline from firing so the cascade
|
|
||||||
completes naturally to `[RAE, RAE]`.
|
|
||||||
|
|
||||||
## Also affected — same root cause, different test
|
|
||||||
|
|
||||||
`test_echoserver_detailed_mechanics[trio-raise_error=KeyboardInterrupt]`
|
|
||||||
(`tests/test_infected_asyncio.py`) tripped the *same*
|
|
||||||
slowdown via its much tighter `trio` budget of `1s`. The
|
|
||||||
single-aio-subactor teardown now takes ~1s, so the `1s`
|
|
||||||
`fail_after` raced the deadline (PASS at 0.99s / FAIL at
|
|
||||||
1.03s across back-to-back standalone runs). On a deadline-
|
|
||||||
fire the injected `Cancelled(source='deadline')` wraps the
|
|
||||||
mid-stream `KeyboardInterrupt` into a `BaseExceptionGroup`,
|
|
||||||
which is NOT a `KeyboardInterrupt` so the bare
|
|
||||||
`pytest.raises(KeyboardInterrupt)` fails. (The sibling
|
|
||||||
`raise_error=Exception` variant only "passes" by accident:
|
|
||||||
an `ExceptionGroup` *is-a* `Exception`, so its
|
|
||||||
`pytest.raises(Exception)` still matches even when wrapped.)
|
|
||||||
|
|
||||||
Mitigation: bump that `trio` budget `1 -> 4s` (matching the
|
|
||||||
forking-spawner case). Without a deadline-fire the KBI
|
|
||||||
propagates bare and the assertion passes.
|
|
||||||
|
|
||||||
## Open follow-up (the actual regression)
|
|
||||||
|
|
||||||
The budget bump is a band-aid — the underlying question is
|
|
||||||
**why** the depth=3 `trio` cancel-cascade went from <6s to
|
|
||||||
~7-8s across `trio` 0.29 -> 0.33. Candidate avenues:
|
|
||||||
|
|
||||||
- which scope owns the per-actor `terminate_after` wait,
|
|
||||||
and are the tree's reaps concurrent or serialized?
|
|
||||||
- did trio 0.33's abort/reschedule or cancel-reason
|
|
||||||
bookkeeping change checkpoint timing on the cancel path?
|
|
||||||
|
|
||||||
If/when the cascade speeds back up under-budget, depth=3
|
|
||||||
will start completing well under 12s — at which point the
|
|
||||||
budget can be tightened back toward 6s as a regression
|
|
||||||
tripwire. Related (different backend, same cascade class):
|
|
||||||
`cancel_cascade_too_slow_under_main_thread_forkserver_issue.md`.
|
|
||||||
|
|
@ -1,221 +0,0 @@
|
||||||
# trio `WakeupSocketpair.drain()` busy-loop in forked child (peer-closed missed-EOF)
|
|
||||||
|
|
||||||
## Reproducer
|
|
||||||
|
|
||||||
```bash
|
|
||||||
./py313/bin/python -m pytest \
|
|
||||||
tests/test_multi_program.py::test_register_duplicate_name \
|
|
||||||
--tpt-proto=tcp \
|
|
||||||
--spawn-backend=main_thread_forkserver \
|
|
||||||
-v --capture=sys
|
|
||||||
```
|
|
||||||
|
|
||||||
Subactor pegs a CPU core indefinitely; parent test
|
|
||||||
hangs waiting for the subactor.
|
|
||||||
|
|
||||||
## Empirical evidence (caught alive)
|
|
||||||
|
|
||||||
```
|
|
||||||
$ sudo strace -p <subactor-pid>
|
|
||||||
recvfrom(6, "", 65536, 0, NULL, NULL) = 0
|
|
||||||
recvfrom(6, "", 65536, 0, NULL, NULL) = 0
|
|
||||||
recvfrom(6, "", 65536, 0, NULL, NULL) = 0
|
|
||||||
... (no `epoll_wait`, no other syscalls, just this back-to-back)
|
|
||||||
```
|
|
||||||
|
|
||||||
Pattern: tight C-level `recvfrom` loop returning 0
|
|
||||||
each call. No `epoll_wait` between iterations →
|
|
||||||
**not trio's task scheduler**. Pure synchronous C
|
|
||||||
loop.
|
|
||||||
|
|
||||||
```
|
|
||||||
$ sudo readlink /proc/<subactor-pid>/fd/6
|
|
||||||
socket:[<inode>]
|
|
||||||
|
|
||||||
$ sudo lsof -p <subactor-pid> | grep ' 6u'
|
|
||||||
<cmd> <pid> goodboy 6u unix 0xffff... 0t0 <inode> type=STREAM (CONNECTED)
|
|
||||||
```
|
|
||||||
|
|
||||||
fd=6 is an **AF_UNIX socket** in CONNECTED state.
|
|
||||||
Even though the test uses `--tpt-proto=tcp`, this fd
|
|
||||||
is NOT a tractor IPC channel — it's an internal
|
|
||||||
trio socketpair.
|
|
||||||
|
|
||||||
## Root-cause: `WakeupSocketpair.drain()`
|
|
||||||
|
|
||||||
`/site-packages/trio/_core/_wakeup_socketpair.py`:
|
|
||||||
|
|
||||||
```python
|
|
||||||
class WakeupSocketpair:
|
|
||||||
def __init__(self) -> None:
|
|
||||||
self.wakeup_sock, self.write_sock = socket.socketpair()
|
|
||||||
self.wakeup_sock.setblocking(False)
|
|
||||||
self.write_sock.setblocking(False)
|
|
||||||
...
|
|
||||||
|
|
||||||
def drain(self) -> None:
|
|
||||||
try:
|
|
||||||
while True:
|
|
||||||
self.wakeup_sock.recv(2**16)
|
|
||||||
except BlockingIOError:
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
`socket.socketpair()` on Linux defaults to AF_UNIX
|
|
||||||
SOCK_STREAM. Both ends non-blocking. Normal flow:
|
|
||||||
|
|
||||||
1. Signal/wake event → `write_sock.send(b'\x00')`
|
|
||||||
queues a byte.
|
|
||||||
2. `wakeup_sock` becomes readable → trio's epoll
|
|
||||||
triggers.
|
|
||||||
3. Trio calls `drain()` to flush the buffer.
|
|
||||||
4. drain loops on `wakeup_sock.recv(64KB)`.
|
|
||||||
5. Eventually buffer empty → non-blocking socket
|
|
||||||
raises `BlockingIOError` → except → break.
|
|
||||||
|
|
||||||
**Bug surface — peer-closed missed-EOF**:
|
|
||||||
|
|
||||||
Non-blocking socket semantics:
|
|
||||||
- buffer has data → `recv` returns N>0 bytes (loop continues)
|
|
||||||
- buffer empty → `recv` raises `BlockingIOError`
|
|
||||||
- **peer FIN'd → `recv` returns 0 bytes (NEITHER exception NOR
|
|
||||||
break — infinite tight loop)**
|
|
||||||
|
|
||||||
`drain()` does not handle the `b''` return-value
|
|
||||||
(EOF) case. If `write_sock` has been closed (or the
|
|
||||||
process holding it is gone), every iteration returns
|
|
||||||
0 → infinite loop → 100% CPU on a single core.
|
|
||||||
|
|
||||||
## Why this triggers under `main_thread_forkserver`
|
|
||||||
|
|
||||||
Under `os.fork()` from the forkserver-worker thread:
|
|
||||||
|
|
||||||
1. Parent has a `WakeupSocketpair` instance with
|
|
||||||
`wakeup_sock=fdN`, `write_sock=fdM`. Both fds
|
|
||||||
open in parent.
|
|
||||||
2. Fork → child inherits BOTH fds (kernel-level fd
|
|
||||||
table dup).
|
|
||||||
3. `_close_inherited_fds()` runs in child →
|
|
||||||
closes everything except stdio. `wakeup_sock` and
|
|
||||||
`write_sock` of the parent's `WakeupSocketpair`
|
|
||||||
ARE closed in child.
|
|
||||||
4. Child's trio (running fresh) creates its OWN
|
|
||||||
`WakeupSocketpair` → NEW fd numbers (e.g. fd 6, 7).
|
|
||||||
5. **In `infect_asyncio` mode** the asyncio loop is
|
|
||||||
the host; trio runs as guest via
|
|
||||||
`start_guest_run`. trio still creates its
|
|
||||||
`WakeupSocketpair` in the I/O manager but its
|
|
||||||
role is different.
|
|
||||||
|
|
||||||
The race window: somewhere between (3) and (5), if a
|
|
||||||
`WakeupSocketpair` Python object reference inherited
|
|
||||||
via COW (from parent's pre-fork heap) survives long
|
|
||||||
enough that `drain()` is called on it AFTER its fds
|
|
||||||
were closed but BEFORE the child's NEW socketpair
|
|
||||||
takes over the recycled fd numbers — the recycled fd
|
|
||||||
will be one of the child's NEW socketpair ends, whose
|
|
||||||
peer might be FIN-flagged (e.g. parent-process
|
|
||||||
peer-end is closed).
|
|
||||||
|
|
||||||
Or simpler: the `wait_for_actor`/`find_actor` discovery
|
|
||||||
flow in `test_register_duplicate_name` triggers an
|
|
||||||
unusual code path where a stale `WakeupSocketpair`
|
|
||||||
gets `drain()`-called on a fd whose peer has already
|
|
||||||
closed.
|
|
||||||
|
|
||||||
## Why `drain()` shouldn't loop indefinitely on EOF
|
|
||||||
(upstream trio bug)
|
|
||||||
|
|
||||||
Even WITHOUT fork, `drain()` should treat `b''` as
|
|
||||||
EOF and break. The current code is correct for the
|
|
||||||
"buffer drained on a healthy socketpair" scenario but
|
|
||||||
incorrect for the "peer is gone" scenario. It's a
|
|
||||||
defensive-programming gap in trio.
|
|
||||||
|
|
||||||
A one-line patch upstream:
|
|
||||||
|
|
||||||
```python
|
|
||||||
def drain(self) -> None:
|
|
||||||
try:
|
|
||||||
while True:
|
|
||||||
data = self.wakeup_sock.recv(2**16)
|
|
||||||
if not data:
|
|
||||||
break # peer-closed; nothing more to drain
|
|
||||||
except BlockingIOError:
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
## Workarounds (until the underlying issue lands)
|
|
||||||
|
|
||||||
1. **Skip-mark on the fork backend**:
|
|
||||||
`tests/test_multi_program.py` →
|
|
||||||
`pytest.mark.skipon_spawn_backend('main_thread_forkserver',
|
|
||||||
reason='trio WakeupSocketpair.drain busy-loop, see ai/conc-anal/trio_wakeup_socketpair_busy_loop_under_fork_issue.md')`.
|
|
||||||
|
|
||||||
2. **Defensive monkey-patch in tractor's
|
|
||||||
forkserver-child prelude** — wrap
|
|
||||||
`WakeupSocketpair.drain` to handle `b''`:
|
|
||||||
|
|
||||||
```python
|
|
||||||
# in `_actor_child_main` or `_close_inherited_fds`'s
|
|
||||||
# post-fork prelude:
|
|
||||||
from trio._core._wakeup_socketpair import WakeupSocketpair
|
|
||||||
_orig_drain = WakeupSocketpair.drain
|
|
||||||
def _safe_drain(self):
|
|
||||||
try:
|
|
||||||
while True:
|
|
||||||
data = self.wakeup_sock.recv(2**16)
|
|
||||||
if not data:
|
|
||||||
return # peer closed
|
|
||||||
except BlockingIOError:
|
|
||||||
pass
|
|
||||||
WakeupSocketpair.drain = _safe_drain
|
|
||||||
```
|
|
||||||
|
|
||||||
Tracks upstream — remove once trio fixes.
|
|
||||||
|
|
||||||
3. **Upstream the fix**: 1-line PR to `python-trio/trio`
|
|
||||||
adding `if not data: break` to `drain()`.
|
|
||||||
|
|
||||||
## Investigation next steps
|
|
||||||
|
|
||||||
1. **Confirm via py-spy**: when caught alive, detach
|
|
||||||
strace first then
|
|
||||||
`sudo py-spy dump --pid <subactor> --locals`. The
|
|
||||||
busy thread should show `drain` from `WakeupSocketpair`
|
|
||||||
in the call chain.
|
|
||||||
2. **Identify which write-end peer is closed**: from
|
|
||||||
the inode of fd 6, look up the matching peer
|
|
||||||
inode via `ss -xp` and see whose process it
|
|
||||||
was/is.
|
|
||||||
3. **Verify the missed-EOF hypothesis**: hand-craft a
|
|
||||||
minimal `WakeupSocketpair` repro:
|
|
||||||
|
|
||||||
```python
|
|
||||||
from trio._core._wakeup_socketpair import WakeupSocketpair
|
|
||||||
ws = WakeupSocketpair()
|
|
||||||
ws.write_sock.close() # simulate peer-gone
|
|
||||||
ws.drain() # should hang forever
|
|
||||||
```
|
|
||||||
|
|
||||||
## Sibling bug
|
|
||||||
|
|
||||||
`tests/test_infected_asyncio.py::test_aio_simple_error`
|
|
||||||
hangs under the same backend with a DIFFERENT
|
|
||||||
fingerprint (Mode-A deadlock, both parties in
|
|
||||||
`epoll_wait`, no busy-loop). Distinct root cause —
|
|
||||||
see `infected_asyncio_under_main_thread_forkserver_hang_issue.md`.
|
|
||||||
|
|
||||||
Both share the broader theme: **trio internal-state
|
|
||||||
initialization isn't fully fork-safe under
|
|
||||||
`main_thread_forkserver`** for the more exotic
|
|
||||||
dispatch paths.
|
|
||||||
|
|
||||||
## See also
|
|
||||||
|
|
||||||
- [#379](https://github.com/goodboy/tractor/issues/379) — subint umbrella
|
|
||||||
- python-trio/trio#1614 — trio + fork hazards
|
|
||||||
- `trio._core._wakeup_socketpair.WakeupSocketpair`
|
|
||||||
source (the smoking gun)
|
|
||||||
- `ai/conc-anal/fork_thread_semantics_execution_vs_memory.md`
|
|
||||||
- `ai/conc-anal/infected_asyncio_under_main_thread_forkserver_hang_issue.md`
|
|
||||||
|
|
@ -1,54 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
session: (ad-hoc, not tracked via conf.toml)
|
|
||||||
timestamp: 2026-04-06T17:28:48Z
|
|
||||||
git_ref: 02b2ef1
|
|
||||||
scope: tests
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260406T172848Z_02b2ef1_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
User asked to extend `tests/test_resource_cache.py` with a test
|
|
||||||
that reproduces the edge case fixed in commit `02b2ef18` (per-key
|
|
||||||
locking+user tracking in `maybe_open_context()`). The bug was
|
|
||||||
originally triggered in piker's `brokerd.kraken` backend where the
|
|
||||||
same `acm_func` was called with different kwargs, and the old
|
|
||||||
global `_Cache.users` counter caused:
|
|
||||||
|
|
||||||
- teardown skipped for one `ctx_key` bc another key's users kept
|
|
||||||
the global count > 0
|
|
||||||
- re-entry hitting `assert not resources.get(ctx_key)` during the
|
|
||||||
teardown window
|
|
||||||
|
|
||||||
User requested a test that would fail under the old code and pass
|
|
||||||
with the fix.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Designed and implemented `test_per_ctx_key_resource_lifecycle`
|
|
||||||
which verifies per-`ctx_key` resource isolation by:
|
|
||||||
|
|
||||||
1. Holding resource `'a'` open in a bg task
|
|
||||||
2. Opening+closing resource `'b'` (same `acm_func`, different
|
|
||||||
kwargs) while `'a'` is still alive
|
|
||||||
3. Re-opening `'b'` and asserting cache MISS — proving `'b'` was
|
|
||||||
torn down independently despite `'a'` keeping its own user
|
|
||||||
count > 0
|
|
||||||
|
|
||||||
With the old global counter, phase 3 would produce a stale cache
|
|
||||||
HIT (leaked resource) or crash on the assert.
|
|
||||||
|
|
||||||
Also added a trivial `acm_with_resource(resource_id)` ACM helper
|
|
||||||
at module level.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tests/test_resource_cache.py` — add `acm_with_resource` ACM +
|
|
||||||
`test_per_ctx_key_resource_lifecycle` test fn
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None — committed as generated (pending user review).
|
|
||||||
|
|
@ -1,57 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
session: (ad-hoc, not tracked via conf.toml)
|
|
||||||
timestamp: 2026-04-06T19:31:25Z
|
|
||||||
git_ref: 85f9c5d
|
|
||||||
scope: tests
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260406T193125Z_85f9c5d_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
User asked to reproduce the exact `assert not resources.get(ctx_key)`
|
|
||||||
crash originally seen in piker's `brokerd.kraken` backend via
|
|
||||||
`open_cached_client('kraken')`. Key constraints from user:
|
|
||||||
|
|
||||||
- In piker, kwargs were the **same** (empty) so all callers
|
|
||||||
share one `ctx_key = (fid, ())`
|
|
||||||
- The root issue is `_Cache.locks` being indexed by `fid`
|
|
||||||
rather than `ctx_key`, plus the race window between
|
|
||||||
`values.pop()` and `resources.pop()` in `_Cache.run_ctx`
|
|
||||||
(the acm `__aexit__` has checkpoints in between)
|
|
||||||
- Mark the test `@pytest.mark.xfail` so it can be committed
|
|
||||||
against the unpatched code and later adjusted once the fix
|
|
||||||
from `9e49eddd` is applied
|
|
||||||
|
|
||||||
User pointed to piker's `open_cached_client('kraken')` usage
|
|
||||||
as the real-world pattern to model.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Added `test_moc_reentry_during_teardown` which deterministically
|
|
||||||
reproduces the teardown race:
|
|
||||||
|
|
||||||
1. A `cached_client()` acm (no params, like
|
|
||||||
`kraken.api.get_client()`) signals via `in_aexit` event
|
|
||||||
when its `__aexit__` starts, then sleeps to hold the
|
|
||||||
window open
|
|
||||||
2. `use_and_exit` task enters+exits the cached resource
|
|
||||||
3. `reenter_during_teardown` waits on `in_aexit` then
|
|
||||||
re-enters — landing exactly in the window where
|
|
||||||
`values` is popped but `resources` still exists
|
|
||||||
4. The old `assert not resources.get(ctx_key)` fires
|
|
||||||
5. `@pytest.mark.xfail(raises=AssertionError)` catches it
|
|
||||||
|
|
||||||
Test confirmed: `XFAIL` with the exact traceback at
|
|
||||||
`_mngrs.py:327`.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tests/test_resource_cache.py` — add
|
|
||||||
`test_moc_reentry_during_teardown` xfail test fn
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None — committed as generated (pending user review).
|
|
||||||
|
|
@ -1,52 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
session: (ad-hoc, not tracked via conf.toml)
|
|
||||||
timestamp: 2026-04-06T22:26:48Z
|
|
||||||
git_ref: f086222
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260406T222648Z_f086222_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
User applied the per-key locking patch (`f086222d`),
|
|
||||||
removed the `@pytest.mark.xfail` from
|
|
||||||
`test_moc_reentry_during_teardown`, and found the
|
|
||||||
test STILL fails — now with `RuntimeError` instead
|
|
||||||
of `AssertionError`. Asked to diagnose why the fix
|
|
||||||
doesn't actually resolve this race.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Traced the exact scheduling sequence across three
|
|
||||||
concurrent tasks to show that the per-`ctx_key`
|
|
||||||
locking change doesn't close the fundamental gap:
|
|
||||||
|
|
||||||
- `maybe_open_context`'s finally pops the lock and
|
|
||||||
sets `no_more_users` in the **exiting caller's
|
|
||||||
task**
|
|
||||||
- But the actual resource cleanup (`values.pop`,
|
|
||||||
acm `__aexit__`, `resources.pop`) runs in the
|
|
||||||
**`run_ctx` task** inside `service_tn`
|
|
||||||
- A re-entering task creates a fresh lock (old one
|
|
||||||
popped), acquires immediately, and hits stale
|
|
||||||
`resources[ctx_key]` while `run_ctx` is still in
|
|
||||||
`__aexit__`
|
|
||||||
|
|
||||||
Identified three possible fix strategies:
|
|
||||||
1. Let `run_ctx` own lock release/pop after
|
|
||||||
`resources.pop()`
|
|
||||||
2. Add a "teardown complete" event that new callers
|
|
||||||
wait on
|
|
||||||
3. Move `resources.pop()` into `run_ctx`'s inner
|
|
||||||
finally (before acm `__aexit__`)
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
No code changes — analysis only.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
N/A — diagnostic output, no code generated.
|
|
||||||
|
|
@ -1,32 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-04-06T22:26:48Z
|
|
||||||
git_ref: f086222
|
|
||||||
diff_cmd: git diff f086222~1..f086222
|
|
||||||
---
|
|
||||||
|
|
||||||
Here's the problem. The per-key locking doesn't fix this race because the **lock lifetime is decoupled from `run_ctx`'s lifetime**. Trace through what happens:
|
|
||||||
|
|
||||||
**`maybe_open_context` finally** (lines 468-495):
|
|
||||||
1. `users[ctx_key] -= 1` → 0
|
|
||||||
2. `no_more_users.set()` → wakes `run_ctx` (but it doesn't run yet, just becomes ready)
|
|
||||||
3. `_Cache.locks.pop(ctx_key)` → **lock is gone**
|
|
||||||
4. `maybe_open_context` exits
|
|
||||||
|
|
||||||
**`run_ctx`** now gets scheduled (lines 237-241):
|
|
||||||
5. Inner finally: `values.pop(ctx_key)` → values gone
|
|
||||||
6. `mng.__aexit__()` runs → `in_aexit.set()`, `await trio.sleep(10)` → **CHECKPOINT**
|
|
||||||
|
|
||||||
**`reenter_during_teardown`** wakes:
|
|
||||||
7. Enters `maybe_open_context` → no lock exists for `ctx_key` → creates **fresh** lock, acquires immediately
|
|
||||||
8. `values[ctx_key]` → `KeyError`
|
|
||||||
9. `resources.get(ctx_key)` → **still exists!** (step 6 hasn't reached `resources.pop()` in `run_ctx`'s outer finally yet)
|
|
||||||
10. `raise RuntimeError('Caching resources ALREADY exist?!')`
|
|
||||||
|
|
||||||
The core issue: `no_more_users.set()` (step 2) and `locks.pop()` (step 3) happen in the **exiting caller's task**, but the actual resource cleanup (`values.pop`, acm `__aexit__`, `resources.pop`) happens in the **`run_ctx` task** inside `service_tn`. There's no synchronization between "lock removed, new callers welcome" and "run_ctx has actually finished tearing down". The per-`ctx_key` lock change just made the lock more granular — it didn't close this gap.
|
|
||||||
|
|
||||||
The fix needs to ensure a new caller can't acquire a lock for `ctx_key` until `run_ctx` has fully exited (including `resources.pop()`). Either:
|
|
||||||
- **don't pop the lock in `maybe_open_context`** — let `run_ctx` release/pop it after `resources.pop()`
|
|
||||||
- **wait on a "teardown complete" event** in the cache-miss path when stale `resources` exist
|
|
||||||
- **pop `resources` before the acm `__aexit__`** (move `resources.pop()` into the inner finally alongside `values.pop()`)
|
|
||||||
|
|
@ -1,74 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
session: (ad-hoc, not tracked via conf.toml)
|
|
||||||
timestamp: 2026-04-13T19:21:16Z
|
|
||||||
git_ref: f851f28
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
User provided a detailed implementation plan for
|
|
||||||
a new `test_tpt_bind_addrs.py` test suite covering
|
|
||||||
`open_root_actor(tpt_bind_addrs=...)` — the three
|
|
||||||
runtime code paths in `_root.py:385-450`:
|
|
||||||
|
|
||||||
1. Non-registrar, no explicit bind -> random addrs
|
|
||||||
2. Registrar, no explicit bind -> registry_addrs
|
|
||||||
3. Explicit bind given -> `wrap_address()` + merge
|
|
||||||
|
|
||||||
Plan specified 6 test functions (~10 parametrized
|
|
||||||
variants), predicted a type-mixing bug at line 446,
|
|
||||||
and asked for an in-flight fix if confirmed.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Created `tests/discovery/test_tpt_bind_addrs.py`
|
|
||||||
with 9 collected test variants across 6 functions:
|
|
||||||
|
|
||||||
- `test_registrar_root_tpt_bind_addrs` (3 variants:
|
|
||||||
`bind-eq-reg`, `bind-subset-reg`,
|
|
||||||
`bind-disjoint-reg`)
|
|
||||||
- `test_non_registrar_root_tpt_bind_addrs`
|
|
||||||
(2 variants: `bind-same-bindspace`,
|
|
||||||
`bind-disjoint`)
|
|
||||||
- `test_non_registrar_default_random_bind`
|
|
||||||
(baseline, no explicit bind)
|
|
||||||
- `test_tpt_bind_addrs_as_maddr_str`
|
|
||||||
(multiaddr string input)
|
|
||||||
- `test_registrar_merge_binds_union`
|
|
||||||
(registrar + disjoint bind -> union)
|
|
||||||
- `test_open_nursery_forwards_tpt_bind_addrs`
|
|
||||||
(`open_nursery(**kwargs)` forwarding)
|
|
||||||
|
|
||||||
Confirmed and fixed the predicted bug at
|
|
||||||
`_root.py:446`: the registrar merge path mixed
|
|
||||||
`Address` objects (`tpt_bind_addrs`) with raw tuples
|
|
||||||
(`uw_reg_addrs`) inside `set()`, preventing
|
|
||||||
deduplication and causing double-bind `OSError`.
|
|
||||||
|
|
||||||
Fix: wrap `uw_reg_addrs` before the set union:
|
|
||||||
```python
|
|
||||||
# before (broken)
|
|
||||||
tpt_bind_addrs = list(set(
|
|
||||||
tpt_bind_addrs + uw_reg_addrs
|
|
||||||
))
|
|
||||||
# after (fixed)
|
|
||||||
tpt_bind_addrs = list(set(
|
|
||||||
tpt_bind_addrs
|
|
||||||
+ [wrap_address(a) for a in uw_reg_addrs]
|
|
||||||
))
|
|
||||||
```
|
|
||||||
|
|
||||||
All 9 tests pass after the fix.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tests/discovery/test_tpt_bind_addrs.py` (new)
|
|
||||||
- `tractor/_root.py:446` (bug fix, 1 line)
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
N/A — pending review.
|
|
||||||
|
|
@ -1,50 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
session: 76154e65-d8e1-4b5f-9275-0ea45ba7e98a
|
|
||||||
timestamp: 2026-04-13T20:50:48Z
|
|
||||||
git_ref: 269d939c
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260413T205048Z_269d939c_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Implement a `parse_endpoints()` API in
|
|
||||||
`tractor.discovery._multiaddr` that lets downstream
|
|
||||||
projects declare per-actor transport bind addresses
|
|
||||||
as a service table of actor-name -> multiaddr
|
|
||||||
strings (loaded from config, e.g. TOML `[network]`
|
|
||||||
section). Add type aliases `EndpointsTable` and
|
|
||||||
`ParsedEndpoints`, plus 7 unit tests covering TCP,
|
|
||||||
UDS, tuples, mixed input, unsupported protocols, and
|
|
||||||
edge cases.
|
|
||||||
|
|
||||||
A detailed implementation plan was provided
|
|
||||||
specifying insertion points, type signatures, test
|
|
||||||
names, and verification commands.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Add `parse_endpoints()` function with two supporting
|
|
||||||
type aliases to `_multiaddr.py`. The function
|
|
||||||
iterates a `dict[str, list[str|tuple]]` service
|
|
||||||
table and delegates each entry to the existing
|
|
||||||
`wrap_address()` helper, which already handles maddr
|
|
||||||
strings, raw tuples, and pre-wrapped `Address`
|
|
||||||
objects. Seven pure unit tests (no trio runtime)
|
|
||||||
validate all input variants and edge cases. All 22
|
|
||||||
multiaddr tests pass.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/discovery/_multiaddr.py` — add
|
|
||||||
`EndpointsTable`, `ParsedEndpoints` type aliases
|
|
||||||
and `parse_endpoints()` function after line 133
|
|
||||||
- `tests/discovery/test_multiaddr.py` — add
|
|
||||||
`parse_endpoints` import and 7 new test functions
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None — committed as generated.
|
|
||||||
|
|
@ -1,32 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-04-13T20:50:48Z
|
|
||||||
git_ref: 269d939c
|
|
||||||
diff_cmd: git diff 269d939c~1..269d939c
|
|
||||||
---
|
|
||||||
|
|
||||||
## Implementation output
|
|
||||||
|
|
||||||
### `tractor/discovery/_multiaddr.py`
|
|
||||||
|
|
||||||
> `git diff 269d939c~1..269d939c -- tractor/discovery/_multiaddr.py`
|
|
||||||
|
|
||||||
Type aliases `EndpointsTable` and `ParsedEndpoints`
|
|
||||||
plus `parse_endpoints()` helper that wraps each
|
|
||||||
entry via `wrap_address()`.
|
|
||||||
|
|
||||||
### `tests/discovery/test_multiaddr.py`
|
|
||||||
|
|
||||||
> `git diff 269d939c~1..269d939c -- tests/discovery/test_multiaddr.py`
|
|
||||||
|
|
||||||
Add import of `parse_endpoints` to existing import
|
|
||||||
block, then 7 new test functions.
|
|
||||||
|
|
||||||
### Test run output
|
|
||||||
|
|
||||||
```
|
|
||||||
22 passed, 1 warning in 0.05s
|
|
||||||
```
|
|
||||||
|
|
||||||
All 22 tests pass (15 existing + 7 new).
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
session: multiaddr-support-rename-prefer
|
|
||||||
timestamp: 2026-04-14T16:33:00Z
|
|
||||||
git_ref: befedc49
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260414T163300Z_befedc49_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Create a helper function that determines the best transport given
|
|
||||||
actor locality (distributed vs same host). Use PID/hostname
|
|
||||||
comparison for locality detection, apply at registry addr selection
|
|
||||||
only (not spawn-time).
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
New `prefer_addr()` + `_is_local_addr()` helpers
|
|
||||||
in `_api.py` using `socket.getaddrinfo()` and
|
|
||||||
`ipaddress` for PID/hostname locality detection.
|
|
||||||
Preference: UDS > local TCP > remote TCP.
|
|
||||||
Integrated into `query_actor()` and
|
|
||||||
`wait_for_actor()`. Also changed
|
|
||||||
`Registrar.find_actor()` to return full addr list
|
|
||||||
so callers can apply preference.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/discovery/_discovery.py` → `_api.py`
|
|
||||||
— renamed + added `prefer_addr()`,
|
|
||||||
`_is_local_addr()`; updated `query_actor()` and
|
|
||||||
`wait_for_actor()` call sites
|
|
||||||
- `tractor/discovery/_registry.py`
|
|
||||||
— `Registrar.find_actor()` returns
|
|
||||||
`list[UnwrappedAddress]|None`
|
|
||||||
|
|
@ -1,62 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-6
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-04-14T16:33:00Z
|
|
||||||
git_ref: befedc49
|
|
||||||
diff_cmd: git diff befedc49~1..befedc49
|
|
||||||
---
|
|
||||||
|
|
||||||
### `tractor/discovery/_api.py`
|
|
||||||
|
|
||||||
> `git diff befedc49~1..befedc49 -- tractor/discovery/_api.py`
|
|
||||||
|
|
||||||
Add `_is_local_addr()` and `prefer_addr()` transport
|
|
||||||
preference helpers.
|
|
||||||
|
|
||||||
#### `_is_local_addr(addr: Address) -> bool`
|
|
||||||
|
|
||||||
Determines whether an `Address` is reachable on the
|
|
||||||
local host:
|
|
||||||
|
|
||||||
- `UDSAddress`: always returns `True`
|
|
||||||
(filesystem-bound, inherently local)
|
|
||||||
- `TCPAddress`: checks if `._host` is a loopback IP
|
|
||||||
via `ipaddress.ip_address().is_loopback`, then
|
|
||||||
falls back to comparing against the machine's own
|
|
||||||
interface IPs via
|
|
||||||
`socket.getaddrinfo(socket.gethostname(), None)`
|
|
||||||
|
|
||||||
#### `prefer_addr(addrs: list[UnwrappedAddress]) -> UnwrappedAddress`
|
|
||||||
|
|
||||||
Selects the "best" transport address from a
|
|
||||||
multihomed actor's address list. Wraps each
|
|
||||||
candidate via `wrap_address()` to get typed
|
|
||||||
`Address` objects, then classifies into three tiers:
|
|
||||||
|
|
||||||
1. **UDS** (same-host guaranteed, lowest overhead)
|
|
||||||
2. **TCP loopback / same-host IP** (local network)
|
|
||||||
3. **TCP remote** (only option for distributed)
|
|
||||||
|
|
||||||
Within each tier, the last-registered (latest) entry
|
|
||||||
is preferred. Falls back to `addrs[-1]` if no
|
|
||||||
heuristic matches.
|
|
||||||
|
|
||||||
### `tractor/discovery/_registry.py`
|
|
||||||
|
|
||||||
> `git diff befedc49~1..befedc49 -- tractor/discovery/_registry.py`
|
|
||||||
|
|
||||||
`Registrar.find_actor()` return type broadened from
|
|
||||||
single addr to `list[UnwrappedAddress]|None` — full
|
|
||||||
addr list lets callers apply transport preference.
|
|
||||||
|
|
||||||
#### Integration
|
|
||||||
|
|
||||||
`query_actor()` and `wait_for_actor()` now call
|
|
||||||
`prefer_addr(addrs)` instead of `addrs[-1]`.
|
|
||||||
|
|
||||||
### Verification
|
|
||||||
|
|
||||||
All discovery tests pass (13/13 non-daemon).
|
|
||||||
`test_local.py` and `test_multi_program.py` also
|
|
||||||
pass (daemon fixture teardown failures are
|
|
||||||
pre-existing and unrelated).
|
|
||||||
|
|
@ -1,101 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-7[1m]
|
|
||||||
service: claude
|
|
||||||
session: subints-spawner-design-kickoff
|
|
||||||
timestamp: 2026-04-17T03:49:18Z
|
|
||||||
git_ref: 9703210
|
|
||||||
scope: docs
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260417T034918Z_9703210_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Drive the "first big boi, from GH issue" task seeded by
|
|
||||||
`ai/prompt-io/prompts/subints_spawner.md`: design, plan
|
|
||||||
and implement sub-interpreter (subint) spawn-backend
|
|
||||||
support per issue #379, including (1) modularizing
|
|
||||||
`tractor.spawn._spawn` into per-backend submods, (2) a new
|
|
||||||
`._subint` backend, and (3) harness parametrization via the
|
|
||||||
existing `--spawn-backend` / `start_method` pytest fixture
|
|
||||||
in `tractor._testing.pytest`.
|
|
||||||
|
|
||||||
Follow-up clarifications from the user (this turn):
|
|
||||||
1. Pin `<3.15` on this dev branch and feature-gate subint
|
|
||||||
tests — chose option (a).
|
|
||||||
2. Split Phase A (modularization) into its own PR first.
|
|
||||||
3. Defer the `fork()`-via-subint hack to a follow-up.
|
|
||||||
4. Harness flag is `pytest --spawn-backend <key>` CLI →
|
|
||||||
`start_method` fixture (prompt file updated to match).
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Produced a three-phase plan and a concrete Phase A (pure
|
|
||||||
modularization) file-split plan for user review; no code
|
|
||||||
written yet — the green-light to start Phase A was given
|
|
||||||
in this same turn conditional on logging this prompt-io
|
|
||||||
entry first.
|
|
||||||
|
|
||||||
Phases:
|
|
||||||
- **A — modularize** `tractor/spawn/_spawn.py` (847 LOC):
|
|
||||||
keep generic machinery in `_spawn.py`, extract
|
|
||||||
`trio_proc` → `spawn/_trio.py`, `mp_proc` →
|
|
||||||
`spawn/_mp.py`. No pin bump.
|
|
||||||
- **B — `_subint` backend**: bump `pyproject.toml`
|
|
||||||
`requires-python` upper to `<3.15`; add `'subint'` to
|
|
||||||
`SpawnMethodKey`; reuse existing UDS transport; shm
|
|
||||||
escape-hatch deferred.
|
|
||||||
- **C — harness**: drive the valid-backend tuple in
|
|
||||||
`tractor/_testing/pytest.py:345-349` from
|
|
||||||
`typing.get_args(SpawnMethodKey)`; skip subint tests on
|
|
||||||
Python < 3.14.
|
|
||||||
|
|
||||||
Key findings surfaced to the user:
|
|
||||||
- `pyproject.toml:12` currently pins `<3.14`; PEP 734
|
|
||||||
`concurrent.interpreters` only ships in 3.14 — the
|
|
||||||
load-bearing constraint.
|
|
||||||
- `_testing/pytest.py:345-349` hardcodes valid backends
|
|
||||||
as a string tuple (`'mp_spawn'`, `'mp_forkserver'`,
|
|
||||||
`'trio'`) — should be `get_args(SpawnMethodKey)`.
|
|
||||||
- `_testing/pytest.py:228` already imports
|
|
||||||
`try_set_start_method` from `tractor.spawn._spawn` —
|
|
||||||
keeping the `_spawn.py` path as the "core" module
|
|
||||||
avoids breaking external refs during Phase A.
|
|
||||||
|
|
||||||
Phase A commit breakdown (each green via `/run-tests`):
|
|
||||||
1. Drive `_testing/pytest.py` backend-tuple from
|
|
||||||
`get_args(SpawnMethodKey)` — prep.
|
|
||||||
2. Extract `trio_proc` → `spawn/_trio.py`; `_methods`
|
|
||||||
registry imports it.
|
|
||||||
3. Extract `mp_proc` → `spawn/_mp.py`; `_methods` imports
|
|
||||||
it.
|
|
||||||
4. Tidy `spawn/__init__.py` docstring for the new layout.
|
|
||||||
|
|
||||||
Workflow: Phase A runs in a new worktree via `/open-wkt
|
|
||||||
spawn_modularize` (branch `wkt/spawn_modularize`) and
|
|
||||||
lands as its own PR before Phase B/C returns to the
|
|
||||||
current `claude_bun_opus4.7_subint_spawner_backend`
|
|
||||||
branch.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
None this turn — design/planning only. The user updated
|
|
||||||
`ai/prompt-io/prompts/subints_spawner.md` themselves to
|
|
||||||
complete the truncated sentence on line 32 (harness-flag
|
|
||||||
reference).
|
|
||||||
|
|
||||||
Upcoming (Phase A, next turn):
|
|
||||||
- `tractor/spawn/_spawn.py` — trimmed to "core"
|
|
||||||
- `tractor/spawn/_trio.py` — new; holds `trio_proc()`
|
|
||||||
- `tractor/spawn/_mp.py` — new; holds `mp_proc()`
|
|
||||||
- `tractor/spawn/__init__.py` — docstring refresh
|
|
||||||
- `tractor/_testing/pytest.py` — backend tuple from
|
|
||||||
`get_args(SpawnMethodKey)`
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None — committed as generated. User completed the
|
|
||||||
truncated sentence on line 32 of
|
|
||||||
`ai/prompt-io/prompts/subints_spawner.md` themselves
|
|
||||||
*before* this prompt-io log was written; that edit was
|
|
||||||
the user's authoring, not an edit to AI output.
|
|
||||||
|
|
@ -1,117 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-7[1m]
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-04-17T03:49:18Z
|
|
||||||
git_ref: 9703210
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
No code was produced in this turn — this is a design/planning
|
|
||||||
exchange for subint spawner support per issue #379. Captured
|
|
||||||
verbatim below are the two substantive AI responses, which
|
|
||||||
together fix the phased plan (A: modularize, B: subint, C:
|
|
||||||
harness) and the concrete Phase A file split before any
|
|
||||||
implementation begins.
|
|
||||||
|
|
||||||
## Turn 1 — initial triage + gating questions
|
|
||||||
|
|
||||||
> Read: issue #379, current `spawn/_spawn.py` (847 lines),
|
|
||||||
> and pyproject pins.
|
|
||||||
>
|
|
||||||
> ## Task summary
|
|
||||||
> Design/plan/implement subint backend per #379, plus
|
|
||||||
> modularize `spawn/_spawn.py` into per-backend submods, plus
|
|
||||||
> harness flag for test parametrization.
|
|
||||||
>
|
|
||||||
> ## Key finding
|
|
||||||
> `pyproject.toml:12` pins `requires-python = ">=3.12, <3.14"`
|
|
||||||
> — but `concurrent.interpreters` / PEP 734 **only lands in
|
|
||||||
> 3.14**. This is the load-bearing design question before
|
|
||||||
> coding.
|
|
||||||
>
|
|
||||||
> ## Proposed phasing (incremental commits)
|
|
||||||
> - **Phase A — modularize** `_spawn.py`: extract `trio_proc`
|
|
||||||
> → `spawn/_trio.py`, `mp_proc` → `spawn/_mp.py`, keep
|
|
||||||
> generic helpers (`hard_kill`/`soft_kill`/`new_proc`
|
|
||||||
> dispatcher/`SpawnMethodKey`) in a slim core. Tests green
|
|
||||||
> at each step.
|
|
||||||
> - **Phase B — `_subint` backend**: extend `SpawnMethodKey`
|
|
||||||
> with `'subint'`; reuse UDS transport by default; shm is
|
|
||||||
> escape-hatch follow-up.
|
|
||||||
> - **Phase C — harness**: add backend-parametrize flag, skip
|
|
||||||
> subint when Python < 3.14.
|
|
||||||
>
|
|
||||||
> ## Gating questions before I start
|
|
||||||
> 1. **Python pin**: bump `<3.15` and feature-gate subint
|
|
||||||
> tests (a), require 3.14 outright (b), or backport shim
|
|
||||||
> (c)? I'd recommend (a).
|
|
||||||
> 2. **PR strategy**: one branch, commits per phase (current
|
|
||||||
> `claude_bun_opus4.7_subint_spawner_backend`)? Or split
|
|
||||||
> Phase A as its own PR first?
|
|
||||||
> 3. **`fork()`-via-subint hack** from the issue's "Our own
|
|
||||||
> thoughts" section — v1 or follow-up? I'd defer to
|
|
||||||
> follow-up.
|
|
||||||
> 4. **Prompt file line 32 is truncated** — what's the
|
|
||||||
> existing harness flag name you had in mind ("using the
|
|
||||||
> existing ___")?
|
|
||||||
>
|
|
||||||
> Which of these are already decided vs. open?
|
|
||||||
|
|
||||||
## User answers (for the raw record)
|
|
||||||
|
|
||||||
1. bump `<3.15`, feature-gate — option (a).
|
|
||||||
2. split Phase A as its own PR first.
|
|
||||||
3. defer `fork()`-via-subint hack.
|
|
||||||
4. harness flag is `--spawn-backend` CLI → `start_method`
|
|
||||||
fixture, per `tractor._testing._pytest`. Prompt file
|
|
||||||
updated accordingly.
|
|
||||||
|
|
||||||
## Turn 2 — concrete Phase A plan
|
|
||||||
|
|
||||||
> Good — prompt file now ends cleanly; harness flag
|
|
||||||
> confirmed as `--spawn-backend` CLI → `start_method`
|
|
||||||
> fixture (via `_testing/pytest.py:193,355`). Also noted
|
|
||||||
> `pytest.py:345-349` hardcodes valid backends as a string
|
|
||||||
> tuple — `typing.get_args(SpawnMethodKey)` should drive
|
|
||||||
> that list.
|
|
||||||
>
|
|
||||||
> ## Phase A — concrete plan (separate PR)
|
|
||||||
>
|
|
||||||
> **File split** in `tractor/spawn/`:
|
|
||||||
> - `_spawn.py` stays as "core": keeps `SpawnMethodKey`,
|
|
||||||
> `_spawn_method`, `proc_waiter`, `try_set_start_method`,
|
|
||||||
> `exhaust_portal`, `cancel_on_completion`, `hard_kill`,
|
|
||||||
> `soft_kill`, `new_proc` dispatcher, `_methods`
|
|
||||||
> registry. Kept at this path so `_testing/pytest.py:228`
|
|
||||||
> and other external imports don't break.
|
|
||||||
> - `_trio.py` ← `trio_proc()` (lines 448–671, ~224 lines)
|
|
||||||
> - `_mp.py` ← `mp_proc()` (lines 672–842, ~171 lines)
|
|
||||||
> - `_methods` dict imports the two backend fns from the
|
|
||||||
> new modules.
|
|
||||||
>
|
|
||||||
> **Commits** (each green via `/run-tests`):
|
|
||||||
> 1. Drive `_testing/pytest.py` backend-tuple from
|
|
||||||
> `get_args(SpawnMethodKey)` — tiny prep.
|
|
||||||
> 2. Extract `trio_proc` → `spawn/_trio.py`; `_methods`
|
|
||||||
> imports it.
|
|
||||||
> 3. Extract `mp_proc` → `spawn/_mp.py`; `_methods`
|
|
||||||
> imports it.
|
|
||||||
> 4. Tidy `spawn/__init__.py` docstring to describe new
|
|
||||||
> layout.
|
|
||||||
>
|
|
||||||
> No pyproject pin bump in Phase A (that's Phase B).
|
|
||||||
>
|
|
||||||
> **Workflow**: I'd run this in a new worktree via
|
|
||||||
> `/open-wkt spawn_modularize` (branch
|
|
||||||
> `wkt/spawn_modularize`), then open a PR before returning
|
|
||||||
> to the current `claude_bun_opus4.7_subint_spawner_backend`
|
|
||||||
> branch for Phase B/C.
|
|
||||||
>
|
|
||||||
> Green-light to `/open-wkt` and start Phase A?
|
|
||||||
|
|
||||||
## User final response
|
|
||||||
|
|
||||||
> all this first then yes, green light.
|
|
||||||
|
|
||||||
— log this `/prompt-io` entry first, then proceed with
|
|
||||||
Phase A in a worktree.
|
|
||||||
|
|
@ -1,86 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-7[1m]
|
|
||||||
service: claude
|
|
||||||
session: subints-spawner-phase-a-impl
|
|
||||||
timestamp: 2026-04-17T03:58:05Z
|
|
||||||
git_ref: 61a73ba
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260417T035800Z_61a73ba_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Follow-up from the design session logged in
|
|
||||||
`20260417T034918Z_9703210_prompt_io.md`: the user
|
|
||||||
greenlit Phase A after `/prompt-io` tracking, so
|
|
||||||
execute the Phase A "modularize `spawn._spawn`" plan
|
|
||||||
end-to-end in a new worktree — four logical steps
|
|
||||||
(pytest harness prep, `trio_proc` extraction,
|
|
||||||
`mp_proc` extraction, docstring refresh), each green
|
|
||||||
via `/run-tests`.
|
|
||||||
|
|
||||||
User directives during execution:
|
|
||||||
- **Option 3** for the test cadence ("continue A.2–A.4
|
|
||||||
first, then run the full suite once at the end of
|
|
||||||
Phase A").
|
|
||||||
- **One commit** for the whole phase ("can't we just
|
|
||||||
commit the whole patch in one commit?") instead of
|
|
||||||
the 3/4-commit split I initially proposed.
|
|
||||||
- **Don't pre-draft** commit messages — wait for the
|
|
||||||
user to invoke `/commit-msg` (captured as feedback
|
|
||||||
memory `feedback_no_auto_draft_commit_msgs.md`).
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Produced the cohesive Phase A modularization patch,
|
|
||||||
landed as commit `61a73bae` (subject: `Mv
|
|
||||||
trio_proc`/`mp_proc` to per-backend submods`). Five
|
|
||||||
files changed, +565 / -418 lines.
|
|
||||||
|
|
||||||
Key pieces of the patch (generated by claude,
|
|
||||||
reviewed by the human before commit):
|
|
||||||
- `tractor/spawn/_trio.py` — **new**; receives
|
|
||||||
`trio_proc()` verbatim from `_spawn.py`; imports
|
|
||||||
cross-backend helpers back from `._spawn`.
|
|
||||||
- `tractor/spawn/_mp.py` — **new**; receives
|
|
||||||
`mp_proc()` verbatim; uses `from . import _spawn`
|
|
||||||
for late-binding access to the mutable `_ctx` /
|
|
||||||
`_spawn_method` globals (design decision made
|
|
||||||
during impl, not the original plan).
|
|
||||||
- `tractor/spawn/_spawn.py` — shrunk 847 → 448 LOC;
|
|
||||||
import pruning; bottom-of-module late imports for
|
|
||||||
`trio_proc` / `mp_proc` with a one-line comment
|
|
||||||
explaining the circular-dep reason.
|
|
||||||
- `tractor/spawn/__init__.py` — docstring refresh
|
|
||||||
describing the new layout.
|
|
||||||
- `tractor/_testing/pytest.py` — the valid-backend
|
|
||||||
set now comes from `typing.get_args(SpawnMethodKey)`
|
|
||||||
so future additions (`'subint'`) don't need harness
|
|
||||||
edits.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
See `git diff 61a73ba~1..61a73ba --stat`:
|
|
||||||
|
|
||||||
```
|
|
||||||
tractor/_testing/pytest.py | 12 +-
|
|
||||||
tractor/spawn/__init__.py | 31 +++-
|
|
||||||
tractor/spawn/_mp.py | 235 ++++++++++++++++++++++++
|
|
||||||
tractor/spawn/_spawn.py | 413 +-------------------------------
|
|
||||||
tractor/spawn/_trio.py | 292 ++++++++++++++++++++++++++++
|
|
||||||
5 files changed, 565 insertions(+), 418 deletions(-)
|
|
||||||
```
|
|
||||||
|
|
||||||
Validation:
|
|
||||||
- import probe + `_methods` wiring check — OK
|
|
||||||
- spawn-relevant test subset — 37 passed, 1 skipped
|
|
||||||
- full suite — 350 passed, 14 skipped, 7 xfailed, 1
|
|
||||||
xpassed
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None — committed as generated by claude (no diff
|
|
||||||
between `.claude/git_commit_msg_LATEST.md` and the
|
|
||||||
committed body, as far as the assistant could
|
|
||||||
observe).
|
|
||||||
|
|
@ -1,138 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-7[1m]
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-04-17T03:58:05Z
|
|
||||||
git_ref: 61a73ba
|
|
||||||
diff_cmd: git diff 61a73ba~1..61a73ba
|
|
||||||
---
|
|
||||||
|
|
||||||
Code generated in this turn was committed verbatim as
|
|
||||||
`61a73bae` ("Mv `trio_proc`/`mp_proc` to per-backend
|
|
||||||
submods"). Per diff-ref mode, per-file code is captured
|
|
||||||
via the pointers below, each followed by a prose
|
|
||||||
summary of what the AI generated. Non-code output
|
|
||||||
(sanity-check results, design rationale) is included
|
|
||||||
verbatim.
|
|
||||||
|
|
||||||
## Per-file generated content
|
|
||||||
|
|
||||||
### `tractor/spawn/_trio.py` (new, 292 lines)
|
|
||||||
|
|
||||||
> `git diff 61a73ba~1..61a73ba -- tractor/spawn/_trio.py`
|
|
||||||
|
|
||||||
Pure lift-and-shift of `trio_proc()` out of
|
|
||||||
`tractor/spawn/_spawn.py` (previously lines 448–670).
|
|
||||||
Added AGPL header + module docstring describing the
|
|
||||||
backend; imports include local `from ._spawn import
|
|
||||||
cancel_on_completion, hard_kill, soft_kill` which
|
|
||||||
creates the bottom-of-module late-import pattern in
|
|
||||||
the core file to avoid a cycle. All call sites,
|
|
||||||
log-format strings, and body logic are byte-identical
|
|
||||||
to the originals — no semantic change.
|
|
||||||
|
|
||||||
### `tractor/spawn/_mp.py` (new, 235 lines)
|
|
||||||
|
|
||||||
> `git diff 61a73ba~1..61a73ba -- tractor/spawn/_mp.py`
|
|
||||||
|
|
||||||
Pure lift-and-shift of `mp_proc()` out of
|
|
||||||
`tractor/spawn/_spawn.py` (previously lines 672–842).
|
|
||||||
Same AGPL header convention. Key difference from
|
|
||||||
`_trio.py`: uses `from . import _spawn` (module
|
|
||||||
import, not from-import) for `_ctx` and
|
|
||||||
`_spawn_method` references — these are mutated at
|
|
||||||
runtime by `try_set_start_method()`, so late binding
|
|
||||||
via `_spawn._ctx` / `_spawn._spawn_method` is required
|
|
||||||
for correctness. Also imports `cancel_on_completion`,
|
|
||||||
`soft_kill`, `proc_waiter` from `._spawn`.
|
|
||||||
|
|
||||||
### `tractor/spawn/_spawn.py` (modified, 847 → 448 LOC)
|
|
||||||
|
|
||||||
> `git diff 61a73ba~1..61a73ba -- tractor/spawn/_spawn.py`
|
|
||||||
|
|
||||||
- removed `trio_proc()` body (moved to `_trio.py`)
|
|
||||||
- removed `mp_proc()` body (moved to `_mp.py`)
|
|
||||||
- pruned imports now unused in core: `sys`,
|
|
||||||
`is_root_process`, `current_actor`,
|
|
||||||
`is_main_process`, `_mp_main`, `ActorFailure`,
|
|
||||||
`pretty_struct`, `_pformat`
|
|
||||||
- added bottom-of-file late imports
|
|
||||||
`from ._trio import trio_proc` and
|
|
||||||
`from ._mp import mp_proc` with a one-line
|
|
||||||
comment explaining why (circular dep)
|
|
||||||
- `_methods` dict unchanged structurally; still binds
|
|
||||||
`'trio' → trio_proc`, `'mp_spawn' → mp_proc`,
|
|
||||||
`'mp_forkserver' → mp_proc`
|
|
||||||
|
|
||||||
### `tractor/spawn/__init__.py` (modified)
|
|
||||||
|
|
||||||
> `git diff 61a73ba~1..61a73ba -- tractor/spawn/__init__.py`
|
|
||||||
|
|
||||||
Docstring rewrite only — no code. New text describes
|
|
||||||
the per-backend `Layout` with `- ._spawn` (core),
|
|
||||||
`- ._trio` (default), `- ._mp` (two mp variants), and
|
|
||||||
reiterates the "no eager import" NOTE.
|
|
||||||
|
|
||||||
### `tractor/_testing/pytest.py` (modified)
|
|
||||||
|
|
||||||
> `git diff 61a73ba~1..61a73ba -- tractor/_testing/pytest.py`
|
|
||||||
|
|
||||||
Two-line logical change (plus a comment):
|
|
||||||
- `from typing import` grows `get_args`
|
|
||||||
- `pytest_generate_tests()` replaces the hardcoded
|
|
||||||
`('mp_spawn','mp_forkserver','trio')` tuple with
|
|
||||||
`get_args(SpawnMethodKey)` via lazy import
|
|
||||||
`from tractor.spawn._spawn import SpawnMethodKey`
|
|
||||||
inside the function body (matching the project's
|
|
||||||
existing lazy-import convention for the spawn
|
|
||||||
module)
|
|
||||||
|
|
||||||
## Non-code output (verbatim)
|
|
||||||
|
|
||||||
### Design rationale for the file split
|
|
||||||
|
|
||||||
From my Phase A plan turn (already captured in
|
|
||||||
`20260417T034918Z_9703210_prompt_io.md`):
|
|
||||||
- `_spawn.py` stays as the "core" rather than renamed
|
|
||||||
to `_core.py` so external imports
|
|
||||||
(`_testing/pytest.py:228` imports
|
|
||||||
`try_set_start_method` from `tractor.spawn._spawn`)
|
|
||||||
keep working without churn.
|
|
||||||
- Per-backend extraction chosen over alternatives
|
|
||||||
(e.g. splitting generic helpers further) because
|
|
||||||
the immediate motivation is hosting a 3rd
|
|
||||||
`_subint.py` sibling cleanly in Phase B.
|
|
||||||
|
|
||||||
### Sanity-check output (verbatim terminal excerpts)
|
|
||||||
|
|
||||||
Post-extraction import probe:
|
|
||||||
```
|
|
||||||
extraction OK
|
|
||||||
_methods: {'trio': 'tractor.spawn._trio.trio_proc',
|
|
||||||
'mp_spawn': 'tractor.spawn._mp.mp_proc',
|
|
||||||
'mp_forkserver': 'tractor.spawn._mp.mp_proc'}
|
|
||||||
```
|
|
||||||
|
|
||||||
Spawn-relevant test subset (`tests/test_local.py
|
|
||||||
test_rpc.py test_spawning.py test_multi_program.py
|
|
||||||
test_discovery.py`):
|
|
||||||
```
|
|
||||||
37 passed, 1 skipped, 14 warnings in 55.37s
|
|
||||||
```
|
|
||||||
|
|
||||||
Full suite:
|
|
||||||
```
|
|
||||||
350 passed, 14 skipped, 7 xfailed, 1 xpassed,
|
|
||||||
151 warnings in 437.73s (0:07:17)
|
|
||||||
```
|
|
||||||
|
|
||||||
No regressions vs. `main`. One transient `-x`
|
|
||||||
early-stop `ERROR` on
|
|
||||||
`test_close_channel_explicit_remote_registrar[trio-True]`
|
|
||||||
was flaky (passed solo, passed without `-x`), not
|
|
||||||
caused by this refactor.
|
|
||||||
|
|
||||||
### Commit message
|
|
||||||
|
|
||||||
Also AI-drafted (via `/commit-msg`) — the 40-line
|
|
||||||
message on commit `61a73bae` itself. Not reproduced
|
|
||||||
here; see `git log -1 61a73bae`.
|
|
||||||
|
|
@ -1,146 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-7[1m]
|
|
||||||
service: claude
|
|
||||||
session: trio-0.33-subproc-supervisor-retroactive
|
|
||||||
timestamp: 2026-06-01T23:14:29Z
|
|
||||||
git_ref: 0e3e008b
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260601T231429Z_0e3e008b_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
**RETROACTIVE LOG** — original session prompts not
|
|
||||||
preserved; reconstructed from the staged work product.
|
|
||||||
|
|
||||||
The work designs a `trio.Nursery.start()`-style wrapper
|
|
||||||
around `trio.run_process()` for SC-friendly subprocess
|
|
||||||
supervision. From the resulting code shape, the
|
|
||||||
prompting intent was:
|
|
||||||
|
|
||||||
1. Surface rc!=0 `CalledProcessError` DETERMINISTICALLY,
|
|
||||||
without the nursery-eg-wrapping that complicates
|
|
||||||
`collapse_eg()` usage and races the relay reader on
|
|
||||||
trio's `check=True`-driven cancel cascade.
|
|
||||||
2. ALWAYS isolate the parent controlling-tty so a
|
|
||||||
spawned child can't emit terminal control-seqs onto
|
|
||||||
the launching tty (clobbering scrollback). Default
|
|
||||||
`stdin=DEVNULL`; default `stdout=DEVNULL` unless
|
|
||||||
explicitly relayed/overridden; distinguish "caller
|
|
||||||
passed nothing" from "caller passed `None` for
|
|
||||||
inherit".
|
|
||||||
3. Optional live per-line relay of child std-streams to
|
|
||||||
the `tractor` log — STREAMED (not
|
|
||||||
buffered-until-exit) so long-lived daemon output is
|
|
||||||
visible during the run. Pick a custom log level that
|
|
||||||
shows at usual `info`/`devx` console levels but is
|
|
||||||
separately filterable.
|
|
||||||
4. Concurrent pipe-drain reader MANDATORY when piping
|
|
||||||
without `capture_*` — without it the child blocks on
|
|
||||||
`write()` once the OS pipe buffer fills (~64KiB),
|
|
||||||
causing deadlocks on output bursts.
|
|
||||||
5. Non-blocking `tn.start()` semantics: hand the live
|
|
||||||
`trio.Process` to the parent immediately;
|
|
||||||
supervise/relay run to completion in the supervisor
|
|
||||||
coro.
|
|
||||||
6. Hermetic `trio`-only unit tests (no actor-runtime)
|
|
||||||
covering each of: per-line relay, tty isolation,
|
|
||||||
no-deadlock on >64KiB unnewlined output, CPE
|
|
||||||
rebuild w/ stderr relay, CPE rebuild on the silent
|
|
||||||
drain+capture path.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Adds `tractor/trionics/_subproc.py` (296 LOC) +
|
|
||||||
`tests/trionics/test_subproc.py` (230 LOC) + a
|
|
||||||
re-export in `tractor/trionics/__init__.py`.
|
|
||||||
|
|
||||||
**`supervise_run_process()`** (public, re-exported)
|
|
||||||
- `check=False` is forced to `trio.run_process`; the
|
|
||||||
rc-check runs in the supervisor coro AFTER `own_tn`
|
|
||||||
unwinds (both the child AND the relay readers have
|
|
||||||
hit EOF + fully drained). A BARE
|
|
||||||
`subprocess.CalledProcessError` is rebuilt + raised
|
|
||||||
from there, with `.stderr` bytes passed in the
|
|
||||||
constructor AND attached as an `add_note()`'d
|
|
||||||
`|_.stderr:` block for legible teardown logs.
|
|
||||||
- `stdin=DEVNULL` always. `stdout` default chosen via a
|
|
||||||
`_UNSET` sentinel: `relay_stdout=True` → PIPE,
|
|
||||||
explicit `stdout=...` → as given, else `DEVNULL`.
|
|
||||||
`stderr` defaults to PIPE whenever we relay OR need
|
|
||||||
the CPE note (when `check=True`), else `DEVNULL`.
|
|
||||||
- `relay_level='io'` (custom level 21; sorts just
|
|
||||||
above stdlib `INFO`=20 so it shows at usual
|
|
||||||
`info`/`devx` levels and stays separately
|
|
||||||
filterable). `runtime`=15 would silently filter at
|
|
||||||
default levels, so it's rejected as a default.
|
|
||||||
- `task_status.started(trio_proc)` delivers the live
|
|
||||||
process immediately. The internal `own_tn`
|
|
||||||
supervises `trio.run_process` + any relay readers to
|
|
||||||
completion.
|
|
||||||
- `**run_process_kwargs` forward verbatim;
|
|
||||||
`stdin/stdout/stderr/check` are MANAGED keys
|
|
||||||
(override on conflict).
|
|
||||||
- Crash-handling deliberately NOT baked in — compose
|
|
||||||
`maybe_open_crash_handler()` on top at the call-site.
|
|
||||||
|
|
||||||
**`_relay_stream_lines()`** (internal helper)
|
|
||||||
- Three modes (combinable): `emit`-only (live per-line
|
|
||||||
relay), `accum`-only (silent drain+capture for a CPE
|
|
||||||
note), or both (live relay AND capture).
|
|
||||||
- Per-line split handles cross-chunk residuals via a
|
|
||||||
rolling `residual` bytes buffer; flushes any trailing
|
|
||||||
un-newline-term'd line at EOF.
|
|
||||||
- `async with stream:` ensures aclose at EOF/cancel
|
|
||||||
(mirrors trio's internal `_subprocess` drain idiom).
|
|
||||||
|
|
||||||
**`_add_stderr_note()`** (internal helper)
|
|
||||||
- `add_note()`s a `textwrap.indent(...)`'d
|
|
||||||
`|_.stderr:` block onto a `CalledProcessError` for
|
|
||||||
teardown logs.
|
|
||||||
|
|
||||||
**Tests** (5 hermetic, trio-only) — `_capture_relay`
|
|
||||||
fixture monkeypatches `_subproc.log.<level>` to a list:
|
|
||||||
- `test_stdout_relayed_per_line`: per-line stdout
|
|
||||||
relay carries each `line=N` to the records.
|
|
||||||
- `test_parent_tty_isolated`: `readlink /proc/self/fd/0`
|
|
||||||
and `fd/1` from the child show `pipe:` (fd1) +
|
|
||||||
`/dev/null` (fd0); NO `/dev/pts/*`.
|
|
||||||
- `test_no_deadlock_on_big_unnewlined_output`: 200KiB
|
|
||||||
of `x` with no newlines completes inside
|
|
||||||
`fail_after(2)` — exercises the concurrent drain.
|
|
||||||
- `test_stderr_relay_and_cpe_rebuild`: rc=3 with
|
|
||||||
`relay_stderr=True` raises bare CPE
|
|
||||||
(via `collapse_eg()`) with `b'boom' in cpe.stderr`,
|
|
||||||
the note attached, AND per-line live relay.
|
|
||||||
- `test_nonrelay_cpe_note`: rc=7 with no relay still
|
|
||||||
produces CPE with `.stderr` + note via the silent
|
|
||||||
drain+capture path.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/trionics/_subproc.py` — NEW. Public
|
|
||||||
`supervise_run_process()` + helpers
|
|
||||||
`_relay_stream_lines()` / `_add_stderr_note()` + the
|
|
||||||
`_UNSET` sentinel.
|
|
||||||
- `tests/trionics/test_subproc.py` — NEW. 5 hermetic
|
|
||||||
trio-only tests + `_capture_relay` monkeypatch
|
|
||||||
fixture.
|
|
||||||
- `tractor/trionics/__init__.py` — re-export
|
|
||||||
`supervise_run_process`.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
**RETROACTIVE**: this log is being written from the
|
|
||||||
staged diff, not from a live session. The code as
|
|
||||||
staged is the canonical artifact; any human edits the
|
|
||||||
user made during the originating design session are
|
|
||||||
already integrated and cannot be separated post-hoc.
|
|
||||||
The `.raw.md` sibling is a diff-pointer placeholder,
|
|
||||||
NOT a pre-edit transcript.
|
|
||||||
|
|
||||||
Future prompt-io entries for in-flight work should be
|
|
||||||
written DURING the design session per the skill
|
|
||||||
contract so the pre-edit `.raw.md` captures the
|
|
||||||
unedited model output for genuine provenance.
|
|
||||||
|
|
@ -1,106 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-7[1m]
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-06-01T23:14:29Z
|
|
||||||
git_ref: 0e3e008b
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
# RETROACTIVE — original model output not preserved
|
|
||||||
|
|
||||||
This `.raw.md` would normally contain the verbatim
|
|
||||||
pre-human-edit response from the design session that
|
|
||||||
produced the staged `_subproc.py` module + tests. That
|
|
||||||
session's transcript is not available, so this file
|
|
||||||
serves as a diff-pointer placeholder + transparency
|
|
||||||
note.
|
|
||||||
|
|
||||||
## Authoritative artifact
|
|
||||||
|
|
||||||
The committed code IS the artifact of record. Once the
|
|
||||||
companion commit lands, the unified diff is:
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/_subproc.py`
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/trionics/test_subproc.py`
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/__init__.py`
|
|
||||||
|
|
||||||
Before committing, substitute `--cached` for the
|
|
||||||
pre-commit form.
|
|
||||||
|
|
||||||
## What is NOT here
|
|
||||||
|
|
||||||
Because this is retroactive:
|
|
||||||
- No verbatim chain-of-thought / discussion prose from
|
|
||||||
the design session.
|
|
||||||
- No rejected alternatives the model considered before
|
|
||||||
arriving at the final shape (e.g. whether the
|
|
||||||
rc-check should live inside `own_tn` vs after it; the
|
|
||||||
`_UNSET` sentinel vs a `None`-means-DEVNULL
|
|
||||||
convention; `io` vs `info` as the default relay
|
|
||||||
level).
|
|
||||||
- No pre-edit code blocks as the model first emitted
|
|
||||||
them, separable from any user cleanup applied before
|
|
||||||
the diff was staged.
|
|
||||||
|
|
||||||
## Inferred design choices visible in the final code
|
|
||||||
|
|
||||||
(Documented here because they're the kind of decision
|
|
||||||
detail an unedited raw transcript would have captured.)
|
|
||||||
|
|
||||||
1. **Post-drain rc-check in the supervisor coro body,
|
|
||||||
AFTER `own_tn.__aexit__`.** Placing the
|
|
||||||
`CalledProcessError` raise here (not inside
|
|
||||||
`own_tn`) means the EG-unwrap happens at the OUTER
|
|
||||||
`tn.start()` boundary — callers do `collapse_eg()`
|
|
||||||
if they want bare. Doing the raise INSIDE `own_tn`
|
|
||||||
would cancel the still-draining relay reader
|
|
||||||
mid-flight and lose stderr lines.
|
|
||||||
|
|
||||||
2. **`_UNSET` sentinel for `stdout`.** A plain default
|
|
||||||
of `None` couldn't distinguish "use the safe
|
|
||||||
`DEVNULL` default" from "caller explicitly passed
|
|
||||||
`None` (inherit, presumably knowingly)". The
|
|
||||||
sentinel keeps the SAFE default while letting power
|
|
||||||
users opt into inherit.
|
|
||||||
|
|
||||||
3. **`relay_level='io'` (custom level 21).** Chosen to
|
|
||||||
sort just above stdlib `INFO`=20 so a default
|
|
||||||
`--ll info` shows the relay, but it remains a
|
|
||||||
distinct level so users can filter
|
|
||||||
`tractor.trionics:io` separately. Picking
|
|
||||||
`runtime`=15 would have made the relay invisible at
|
|
||||||
default verbosity (a footgun for daemon supervisors
|
|
||||||
whose whole point is "I want to see this output").
|
|
||||||
|
|
||||||
4. **Reader is MANDATORY, not opt-in cosmetic.** With
|
|
||||||
`stdout=PIPE` / `stderr=PIPE` we OWN the drain
|
|
||||||
responsibility — there's no `trio.capture_*` running
|
|
||||||
under the hood here. The ~64KiB OS pipe buffer
|
|
||||||
means a child writing more than that without us
|
|
||||||
reading hangs at `write()` — a deadlock that won't
|
|
||||||
show up in small-output tests, which is why the
|
|
||||||
200KiB-no-newline test is in the suite.
|
|
||||||
|
|
||||||
5. **`task_status.started(trio_proc)` BEFORE the
|
|
||||||
`own_tn` exits.** Without this, `tn.start()` would
|
|
||||||
block until the child exits — losing the "start a
|
|
||||||
long-lived daemon and continue with parent work"
|
|
||||||
use case. With it, the parent gets the live process
|
|
||||||
handle immediately and the supervise+relay tasks
|
|
||||||
run in the supervisor coro until the child exits.
|
|
||||||
|
|
||||||
6. **`__notes__` via `add_note()` for the CPE
|
|
||||||
`.stderr`.** The `.stderr` attribute is what
|
|
||||||
`subprocess` callers expect; the `add_note()` is
|
|
||||||
what trio's exception-rendering shows. Both wired so
|
|
||||||
programmatic AND human consumers see the stderr at
|
|
||||||
teardown.
|
|
||||||
|
|
||||||
## Honesty statement
|
|
||||||
|
|
||||||
This file's content is RECONSTRUCTED from the staged
|
|
||||||
code, not extracted from a verbatim model transcript.
|
|
||||||
The prompt-io skill's intent is for the `.raw.md` to
|
|
||||||
be a pre-edit fossil; that's not possible here. Future
|
|
||||||
work should write the prompt-io entry DURING the
|
|
||||||
design session.
|
|
||||||
|
|
@ -1,93 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5[1m]
|
|
||||||
service: claude
|
|
||||||
session: 0780a862-e19a-4f0a-86cd-c8afc0997757
|
|
||||||
timestamp: 2026-06-11T17:51:52Z
|
|
||||||
git_ref: 8526985c
|
|
||||||
scope: docs+code+config
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260611T175152Z_8526985c_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
> we need big boi docs; ours are way out of date and generally
|
|
||||||
> terrible. i'd like to use a sphinx theme in the vein and/or
|
|
||||||
> one-of/nearly-the-same-as used in one or all of the `msgspec`,
|
|
||||||
> `numpy`, `ray`, `xonsh`, `polars` projects.
|
|
||||||
>
|
|
||||||
> see the following oustanding but now very old issues to guide
|
|
||||||
> you: #175, #126, #123, #157
|
|
||||||
>
|
|
||||||
> we should try to target a 3 columned sphinx theme with,
|
|
||||||
> - document index-nav on left,
|
|
||||||
> - body content in middle,
|
|
||||||
> - diagrams (ideally in d2lang if possible) on RHS
|
|
||||||
>
|
|
||||||
> optimize for (if possible),
|
|
||||||
> - reusing examples code without duplication in docs,
|
|
||||||
> - generating new examples from todos throughout code base,
|
|
||||||
> - distilling the essence of SC across processes in the simplest
|
|
||||||
> and most friendly way possible.
|
|
||||||
>
|
|
||||||
> do this work in a /open-wkt and do you best without my guidance
|
|
||||||
> for the first major pass - we will refine asap once you are
|
|
||||||
> complete.
|
|
||||||
|
|
||||||
Session settings: `/effort max` + ultracode (multi-agent workflow
|
|
||||||
orchestration). Fully autonomous first pass; two orchestrated
|
|
||||||
agent fleets were used (6-agent recon survey, then 10-agent
|
|
||||||
content fan-out: 9 section writers + 1 examples smith), with the
|
|
||||||
orchestrator authoring the landing page, SC essay, sphinx
|
|
||||||
scaffold, d2 pipeline + diagram sources, CI workflow and all
|
|
||||||
integration/fix passes directly.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Complete sphinx docs revamp on branch `wkt/big_boi_docs`:
|
|
||||||
`pydata-sphinx-theme` 0.18 (3-column: left nav / content /
|
|
||||||
page-toc, with d2 diagrams + asides floated into the RHS margin
|
|
||||||
via custom CSS), sphinx 9.1, a local `.. d2::` directive
|
|
||||||
rendering `docs/diagrams/*.d2` sources with committed-SVG
|
|
||||||
fallback, a vendored `.. margin::` directive, ~25 new doc pages
|
|
||||||
(landing, start/, explain/, 12 guides, 10 api-ref pages,
|
|
||||||
project/), 5 new auto-tested examples + 3 modernized + 1
|
|
||||||
renamed, and a gh-pages deploy workflow (issue #123). All
|
|
||||||
example code is `literalinclude`d from `examples/` (zero
|
|
||||||
duplication, CI-verified). Build: green, 24 warnings all
|
|
||||||
pre-existing-docstring/NEWS sourced.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
See the branch diff (uncommitted at entry-write time):
|
|
||||||
|
|
||||||
> `git diff test_cpu_throttling..wkt/big_boi_docs`
|
|
||||||
> `git -C <wkt> status --short` (pre-commit working tree)
|
|
||||||
|
|
||||||
- `docs/conf.py` — full rewrite for pydata theme + ext stack
|
|
||||||
- `docs/_ext/d2diagrams.py` — new `.. d2::` sphinx directive
|
|
||||||
- `docs/_ext/marginalia.py` — new `.. margin::` directive
|
|
||||||
- `docs/_static/css/custom.css` — b&w skin + RHS margin floats
|
|
||||||
- `docs/diagrams/*.d2` (7) — diagram sources (sketch/grayscale)
|
|
||||||
- `docs/_diagrams/*.svg` (7) — committed rendered fallbacks
|
|
||||||
- `docs/index.rst` — new landing (replaces dead-API doc)
|
|
||||||
- `docs/start/*.rst` (3), `docs/explain/*.rst` (3),
|
|
||||||
`docs/guide/*.rst` (13), `docs/api/*.rst` (10),
|
|
||||||
`docs/project/*.rst` (3) — new content tree
|
|
||||||
- `docs/dev_tips.rst` — removed (ported to project/dev-tips)
|
|
||||||
- `examples/{typed_payloads,nested_actor_tree,
|
|
||||||
service_daemon_discovery,uds_transport_actor_tree,
|
|
||||||
streaming_broadcast_fanout}.py` — new, smoke-tested
|
|
||||||
- `examples/{a_trynamic_first_scene,
|
|
||||||
actor_spawning_and_causality,parallelism/single_func}.py` —
|
|
||||||
`.result()` -> `.wait_for_result()` modernization
|
|
||||||
- `examples/parallelism/concurrent_futures_primes.py` — renamed
|
|
||||||
from leading-underscore + trio-runner shim added
|
|
||||||
- `pyproject.toml` — `docs` dependency-group filled in
|
|
||||||
- `uv.lock` — relock for docs group
|
|
||||||
- `.github/workflows/docs.yml` — build + gh-pages deploy
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None yet — entry written pre-commit; the author reviews, stages
|
|
||||||
and commits manually (per repo workflow policy).
|
|
||||||
|
|
@ -1,49 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5[1m]
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-06-11T17:51:52Z
|
|
||||||
git_ref: 8526985c
|
|
||||||
diff_cmd: git diff test_cpu_throttling..wkt/big_boi_docs
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output pointers (diff-ref mode)
|
|
||||||
|
|
||||||
All generated content is code/config/docs committed alongside
|
|
||||||
this entry on branch `wkt/big_boi_docs`; per the prompt-io
|
|
||||||
diff-ref decision rule each file's verbatim content is the diff
|
|
||||||
itself rather than a copy here:
|
|
||||||
|
|
||||||
> `git diff test_cpu_throttling..wkt/big_boi_docs -- docs/`
|
|
||||||
> `git diff test_cpu_throttling..wkt/big_boi_docs -- examples/`
|
|
||||||
> `git diff test_cpu_throttling..wkt/big_boi_docs -- pyproject.toml uv.lock .github/`
|
|
||||||
|
|
||||||
## Generation notes (non-code output summary)
|
|
||||||
|
|
||||||
- Theme research (web, agent-verified 2026-06-11): msgspec=furo,
|
|
||||||
xonsh=furo, numpy/ray/polars=pydata-sphinx-theme (ray migrated
|
|
||||||
off sphinx-book-theme); sphinx-book-theme 1.2.0 hard-pins
|
|
||||||
pydata 0.16.1 (stale) -> chose pydata 0.18 + sphinx 9.1.
|
|
||||||
- d2 ecosystem: no production-grade pypi extension exists
|
|
||||||
(sphinxcontrib-d2lang 0.0.5 ignores returncodes, uuid4 output
|
|
||||||
names; sphinx-d2 is an empty stub) -> wrote local
|
|
||||||
`docs/_ext/d2diagrams.py` (~230 LOC) with D2_BIN env
|
|
||||||
discovery, mtime caching, committed-SVG fallback and
|
|
||||||
literal-block last resort.
|
|
||||||
- Diagrams authored in d2 (theme-id 1 "Neutral Grey" + sketch
|
|
||||||
mode + ELK layout, validated by render + headless-firefox
|
|
||||||
screenshot loop): actor_tree, context_handshake (real
|
|
||||||
msg-spec names Start/StartAck/Started/Yield/Stop/Return),
|
|
||||||
streaming_pipeline, runtime_stack, debug_lock,
|
|
||||||
error_propagation, infected_aio.
|
|
||||||
- API truth enforced from a 6-agent recon pass over the
|
|
||||||
reorganized package tree (runtime/, discovery/, spawn/, ipc/,
|
|
||||||
msg/, devx/, trionics/): docs teach `.wait_for_result()`,
|
|
||||||
registrar (not arbiter) naming, `@tractor.context` +
|
|
||||||
`open_context()` as the core model, `run_in_actor()` as
|
|
||||||
convenience only.
|
|
||||||
- All ~30 literalincluded example scripts verified present; 9
|
|
||||||
touched/new example files smoke-run green (exit 0, <16s).
|
|
||||||
- Final build: `sphinx-build -b html` succeeded; 24 residual
|
|
||||||
warnings, every one sourced from pre-existing library
|
|
||||||
docstring rst-isms or legacy NEWS.rst content (left untouched
|
|
||||||
by design; flagged for a follow-up docstring lint pass).
|
|
||||||
|
|
@ -1,65 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5[1m]
|
|
||||||
service: claude
|
|
||||||
session: 638d5a98-abd2-4217-a447-19f2330eb334
|
|
||||||
timestamp: 2026-06-25T23:25:06Z
|
|
||||||
git_ref: 0a3c48fc
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260625T232506Z_0a3c48fc_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Same `/code-review` follow-up session (PR #460). Finding #10:
|
|
||||||
the new `api/` autodoc reference pages surfaced 22 docutils
|
|
||||||
warnings sourced from informal reST in public docstrings. The
|
|
||||||
user opted to fix it on this branch,
|
|
||||||
|
|
||||||
> well we're on a clean main so why not just do these now too?
|
|
||||||
|
|
||||||
Goal: drive the docs build warning-free (24 -> 0) without any
|
|
||||||
code/behaviour change — docstring content only.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Surgical docstring-RST lint across 9 library modules + the one
|
|
||||||
offending `NEWS.rst` changelog entry,
|
|
||||||
|
|
||||||
- bullet lists given a blank line + base-column indent
|
|
||||||
(`Context`, `Context.cancel_called`/`.cancelled_caught`/
|
|
||||||
`.outcome`, `ActorNursery.cancel_called`, `query_actor`,
|
|
||||||
`open_crash_handler`, the `#318` `NEWS.rst` entry),
|
|
||||||
- the under-short `Behaviour:` underline in `Context.cancel`
|
|
||||||
demoted to a `**bold**` label,
|
|
||||||
- unbalanced/pluralized-role backticks fixed — closed the
|
|
||||||
`wait_for_actor` summary backtick; applied the `` `role`\ s ``
|
|
||||||
escaped-plural idiom in `gather_contexts`, `mk_pdb`,
|
|
||||||
`MsgCodec`, msg `Error`, `open_context_from_portal`,
|
|
||||||
- the `|_` method-tree in `ContextCancelled.canceller` made a
|
|
||||||
literal block (bare `|` was parsed as a substitution ref).
|
|
||||||
|
|
||||||
Verified: build `24 -> 0` warnings; `import tractor` clean under
|
|
||||||
`-W error::SyntaxWarning`; the `\ s` idiom renders as e.g.
|
|
||||||
"acms" (no backslash/space leak in HTML); `ruff` clean; diff
|
|
||||||
confirmed docstring-content-only.
|
|
||||||
|
|
||||||
Initial generation was delegated to a constrained subagent
|
|
||||||
(docstring-only edits + a rebuild-to-zero verification gate);
|
|
||||||
the orchestrator independently re-built, reviewed the full
|
|
||||||
diff, and added the `NEWS.rst` fix to reach zero.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/_context.py`, `tractor/_exceptions.py`,
|
|
||||||
`tractor/devx/debug/_post_mortem.py`,
|
|
||||||
`tractor/devx/debug/_repl.py`, `tractor/discovery/_api.py`,
|
|
||||||
`tractor/msg/_codec.py`, `tractor/msg/types.py`,
|
|
||||||
`tractor/runtime/_supervise.py`,
|
|
||||||
`tractor/trionics/_mngrs.py` — docstring reST fixes,
|
|
||||||
- `NEWS.rst` — blank line before a bullet list in the `#318`
|
|
||||||
entry.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None — committed as generated (`0a3c48fc`).
|
|
||||||
|
|
@ -1,35 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5[1m]
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-06-25T23:25:06Z
|
|
||||||
git_ref: 0a3c48fc
|
|
||||||
diff_cmd: git diff 0a3c48fc~1..0a3c48fc
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output pointers (diff-ref mode)
|
|
||||||
|
|
||||||
The generated patch is committed; the verbatim content is the
|
|
||||||
diff:
|
|
||||||
|
|
||||||
> `git diff 0a3c48fc~1..0a3c48fc`
|
|
||||||
|
|
||||||
## Generation notes (non-code, verbatim)
|
|
||||||
|
|
||||||
- Pure docstring-content edits; no signatures, logic, or
|
|
||||||
non-docstring lines touched (confirmed via `git diff` review).
|
|
||||||
- reST fix patterns applied: blank-line + base-column indent
|
|
||||||
for bullet lists ("Unexpected indentation" / "Definition
|
|
||||||
list ..." / "Block quote ..."); `**bold**` in place of an
|
|
||||||
under-length section underline ("Title underline too short");
|
|
||||||
closing/escaping backticks ("Inline interpreted text ...
|
|
||||||
without end-string"); literal-block for an ASCII tree whose
|
|
||||||
`|` chars tripped "Inline substitution_reference ...".
|
|
||||||
- The pluralized-role idiom is written `\\ s` in the Python
|
|
||||||
source (so the runtime docstring holds `` `role`\ s ``); a
|
|
||||||
bare `\ ` would raise a 3.13 invalid-escape SyntaxWarning.
|
|
||||||
Verified clean via `python -W error::SyntaxWarning -c
|
|
||||||
"import tractor"`.
|
|
||||||
- Verification gate: `sphinx-build` warning count 24 -> 2
|
|
||||||
(subagent, docstrings only) -> 0 after the orchestrator added
|
|
||||||
the `NEWS.rst` blank-line fix; rendered-HTML spot-check
|
|
||||||
confirmed no literal `\ s` leak; `ruff check` clean.
|
|
||||||
|
|
@ -1,64 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5[1m]
|
|
||||||
service: claude
|
|
||||||
session: 638d5a98-abd2-4217-a447-19f2330eb334
|
|
||||||
timestamp: 2026-06-25T23:25:06Z
|
|
||||||
git_ref: 3a5cfde0
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260625T232506Z_3a5cfde0_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Follow-up to a `/code-review` of PR #460 (this branch) which
|
|
||||||
surfaced lower-severity findings in the `.. d2::` sphinx
|
|
||||||
directive. The user's driving instructions across the session,
|
|
||||||
|
|
||||||
> yup do both *at least*, then report back.
|
|
||||||
|
|
||||||
(re: "implement #7 (+ optionally #8) on the branch") and,
|
|
||||||
|
|
||||||
> well we're on a clean main so why not just do these now too?
|
|
||||||
|
|
||||||
(re: also doing #9). The three findings being addressed,
|
|
||||||
|
|
||||||
- #7: a `d2` render that is *attempted and fails* (binary
|
|
||||||
present but errors on the source) silently degraded to the
|
|
||||||
stale committed SVG and the build still exited 0,
|
|
||||||
- #8: `parallel_*_safe = True` was declared while `run()`
|
|
||||||
writes the shared output SVG during the read phase (torn
|
|
||||||
write under `sphinx-build -j`),
|
|
||||||
- #9: output keyed only by `src.stem` so two `.d2` sources
|
|
||||||
with the same stem collide.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Reworked `docs/_ext/d2diagrams.py`,
|
|
||||||
|
|
||||||
- `render_svg()` now returns a `RenderResult` tristate
|
|
||||||
(`OK` / `FELL_BACK` / `NO_OUTPUT` / `FAILED`) so `run()` can
|
|
||||||
distinguish a graceful no-binary fallback from a real render
|
|
||||||
failure; `FAILED` emits a `reporter.error` (build fails under
|
|
||||||
`-W`),
|
|
||||||
- the render writes into a sibling temp-file then `os.replace()`
|
|
||||||
(atomic) so a failed/torn render can never clobber a good
|
|
||||||
committed SVG,
|
|
||||||
- a per-build `_seen_outputs` map (reset on `builder-inited`)
|
|
||||||
errors on a same-stem output collision.
|
|
||||||
|
|
||||||
Verified: a corrupted `.d2` errors under `-W` (exit 1) with the
|
|
||||||
committed SVG byte-unchanged; the collision guard fires on a
|
|
||||||
duplicate stem; `nix run nixpkgs#d2` render path + atomic swap
|
|
||||||
leave no temp residue; `ruff` clean.
|
|
||||||
|
|
||||||
## Response summary (cont.) — Files changed
|
|
||||||
|
|
||||||
- `docs/_ext/d2diagrams.py` — tristate render result, atomic
|
|
||||||
temp-file render, output-collision guard, doc-string policy
|
|
||||||
update.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None — committed as generated (`3a5cfde0`). The user noted
|
|
||||||
follow-up refinements may come in later commits.
|
|
||||||
|
|
@ -1,35 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5[1m]
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-06-25T23:25:06Z
|
|
||||||
git_ref: 3a5cfde0
|
|
||||||
diff_cmd: git diff 3a5cfde0~1..3a5cfde0
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output pointers (diff-ref mode)
|
|
||||||
|
|
||||||
The generated patch is committed; per the diff-ref decision
|
|
||||||
rule the verbatim content is the diff itself:
|
|
||||||
|
|
||||||
> `git diff 3a5cfde0~1..3a5cfde0 -- docs/_ext/d2diagrams.py`
|
|
||||||
|
|
||||||
## Generation notes (non-code, verbatim)
|
|
||||||
|
|
||||||
- `RenderResult` enum added; `render_svg()` return type changed
|
|
||||||
`bool -> RenderResult`. Mapping in `run()`: `FAILED` ->
|
|
||||||
`state_machine.reporter.error(...)`, `NO_OUTPUT` -> raw `.d2`
|
|
||||||
source as a `literal_block`, `OK`/`FELL_BACK` -> `image`.
|
|
||||||
- Atomicity via `tempfile.mkstemp(dir=out.parent, ...)` +
|
|
||||||
`os.replace(tmp, out)`; temp unlinked on any failure path.
|
|
||||||
- Collision guard: module-level `_seen_outputs: dict[str,str]`
|
|
||||||
keyed by output basename, cleared by a `builder-inited`
|
|
||||||
handler connected in `setup()`.
|
|
||||||
- `parallel_read_safe`/`parallel_write_safe` kept `True` but
|
|
||||||
now justified by the atomic swap (documented inline).
|
|
||||||
- Empirical verification performed before commit:
|
|
||||||
- broken `.d2` + `sphinx-build -W` -> exit 1, ERROR node
|
|
||||||
rendered, committed `actor_tree.svg` md5 unchanged,
|
|
||||||
- duplicate-stem orphan page -> "d2 output collision" error,
|
|
||||||
- `nix run nixpkgs#d2` forced re-render -> deterministic
|
|
||||||
(no git drift), no `.tmp` residue,
|
|
||||||
- `ruff check` clean.
|
|
||||||
|
|
@ -1,79 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
session: f6c84722-471a-4458-9a80-e453fea9029f
|
|
||||||
timestamp: 2026-07-02T15:42:55Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260702T154255Z_65bf9df5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Driver prompt file `ai/prompt-io/prompts/issue_477.md`:
|
|
||||||
|
|
||||||
> attempt to resolve
|
|
||||||
> https://github.com/goodboy/tractor/issues/477
|
|
||||||
> do it with /open-wkt.
|
|
||||||
|
|
||||||
(plus a hard stop-for-human-review deadline of 12:50PM
|
|
||||||
EST the same day)
|
|
||||||
|
|
||||||
Issue #477 asks to factor `ActorNursery.run_in_actor()`
|
|
||||||
(and possibly `Portal.run()`) out of the nursery
|
|
||||||
internals into a new `tractor.to_actor` wrapper
|
|
||||||
subpackage of "higher level one shot" single-remote-task
|
|
||||||
APIs, adopting the `trio.to_thread`/`anyio.to_process`
|
|
||||||
parlance, so that error collection/propagation moves up
|
|
||||||
into the caller's local `trio` scope and the nursery's
|
|
||||||
spawn machinery can eventually drop the
|
|
||||||
`._ria_nursery` coupling.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
First-cut `tractor.to_actor` subpkg delivering the
|
|
||||||
one-shot API composed purely from the existing
|
|
||||||
daemon-spawn + portal primitives (`start_actor()` +
|
|
||||||
`Portal.run()` + `Portal.cancel_actor()`), leaving the
|
|
||||||
legacy `.run_in_actor()` machinery untouched (formal
|
|
||||||
deprecation deferred until in-repo usage migrates):
|
|
||||||
|
|
||||||
- `to_actor.run(fn, **fn_kwargs) -> Any`: spawn a
|
|
||||||
subactor, schedule `fn` as its lone remote task, wait
|
|
||||||
on and return its result, ALWAYS reaping the subactor
|
|
||||||
(shield-safe `finally`). Remote errors raise in the
|
|
||||||
caller's task as boxed `RemoteActorError`s.
|
|
||||||
- placement variants: `portal=` reuses a running actor
|
|
||||||
(no spawn/reap), `an=` spawns from a caller-managed
|
|
||||||
actor-nursery, neither opens a call-scoped private
|
|
||||||
`open_nursery()` (implicitly booting the runtime,
|
|
||||||
configurable via `runtime_kwargs`).
|
|
||||||
- fail-fast validation before any spawn: non-streaming
|
|
||||||
async fn required; `portal=`/`an=` mutually
|
|
||||||
exclusive; `runtime_kwargs` rejected alongside any
|
|
||||||
placement opt.
|
|
||||||
- `run_in_actor()` TODO/docstring now cross-reference
|
|
||||||
the successor API.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/to_actor/__init__.py` — new subpkg,
|
|
||||||
re-exports `run`
|
|
||||||
- `tractor/to_actor/_api.py` — `run()` +
|
|
||||||
`_invoke_in_subactor()` + `_validate_one_shot_fn()`
|
|
||||||
- `tractor/__init__.py` — top-level `to_actor`
|
|
||||||
re-export
|
|
||||||
- `tractor/runtime/_supervise.py` — comment/docstring
|
|
||||||
pointers from `run_in_actor()` to the successor
|
|
||||||
- `tests/test_to_actor.py` — 11-test suite covering
|
|
||||||
all placement variants, error relay, the concurrent
|
|
||||||
worker-pool-ish pattern and arg validation
|
|
||||||
- `examples/parallelism/to_actor_one_shots.py` —
|
|
||||||
runnable demo (auto-collected by
|
|
||||||
`test_docs_examples.py`)
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None yet — pending human review (work paused before the
|
|
||||||
12:50PM EST deadline per the driver prompt).
|
|
||||||
|
|
@ -1,100 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-02T15:42:55Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
diff_cmd: git diff main..wkt/to_actor_subpkg
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw AI output (diff-ref mode)
|
|
||||||
|
|
||||||
All generated code is committed on the
|
|
||||||
`wkt/to_actor_subpkg` branch; per diff-ref mode each
|
|
||||||
file's verbatim content is reachable via the pointers
|
|
||||||
below rather than duplicated here.
|
|
||||||
|
|
||||||
## Generated files
|
|
||||||
|
|
||||||
> `git diff main..wkt/to_actor_subpkg -- tractor/to_actor/__init__.py`
|
|
||||||
|
|
||||||
New subpackage init: module docstring establishing the
|
|
||||||
`trio.to_thread`/`anyio.to_process` "run it over there"
|
|
||||||
parlance for actors, plus the single public re-export
|
|
||||||
`run as run` from `._api`.
|
|
||||||
|
|
||||||
> `git diff main..wkt/to_actor_subpkg -- tractor/to_actor/_api.py`
|
|
||||||
|
|
||||||
The one-shot invocation impl, composed entirely from the
|
|
||||||
lower level daemon-spawn + portal primitives as
|
|
||||||
prescribed by issue #477:
|
|
||||||
|
|
||||||
- `_validate_one_shot_fn()`: the `Portal.run()`
|
|
||||||
non-streaming-async-fn constraint checked up-front,
|
|
||||||
before any subactor is spawned.
|
|
||||||
- `_invoke_in_subactor()`: `an.start_actor()` ->
|
|
||||||
`Portal.run()` -> always-reap via
|
|
||||||
`Portal.cancel_actor()` in a `finally` (the cancel
|
|
||||||
req's bounded wait is internally shielded so the reap
|
|
||||||
also runs under caller-scope cancellation).
|
|
||||||
- `run()`: the public API. Placement options:
|
|
||||||
`portal=` (reuse a running actor, no spawn/reap),
|
|
||||||
`an=` (spawn from a caller-managed nursery), or
|
|
||||||
neither (private `open_nursery()` scoped to the call,
|
|
||||||
implicitly booting the runtime when needed, tunable
|
|
||||||
via pass-through `runtime_kwargs`). Spawn opts mirror
|
|
||||||
`ActorNursery.start_actor()`; `**fn_kwargs` are
|
|
||||||
relayed to the remote task. Errors raise in the
|
|
||||||
caller's task as boxed `RemoteActorError`s.
|
|
||||||
`runtime_kwargs` alongside any placement opt is a
|
|
||||||
hard `ValueError`, never silently ignored.
|
|
||||||
|
|
||||||
> `git diff main..wkt/to_actor_subpkg -- tractor/__init__.py`
|
|
||||||
|
|
||||||
Top-level `from . import to_actor as to_actor`
|
|
||||||
re-export.
|
|
||||||
|
|
||||||
> `git diff main..wkt/to_actor_subpkg -- tractor/runtime/_supervise.py`
|
|
||||||
|
|
||||||
Comment/docstring-only: the `run_in_actor()` deprecation
|
|
||||||
TODO now points at the implemented `.to_actor.run()`
|
|
||||||
successor (checkbox ticked) and the method docstring
|
|
||||||
gains a NOTE steering users to the new API; remaining
|
|
||||||
TODO items are the `DeprecationWarning` emission +
|
|
||||||
in-repo usage migration.
|
|
||||||
|
|
||||||
> `git diff main..wkt/to_actor_subpkg -- tests/test_to_actor.py`
|
|
||||||
|
|
||||||
11-test suite: private-nursery one-shot, implicit
|
|
||||||
runtime boot via `runtime_kwargs`, remote-error relay to
|
|
||||||
the caller's task (bare + caller-managed nursery),
|
|
||||||
caller-nursery spawn, portal reuse w/o implicit reap,
|
|
||||||
the concurrent worker-pool-ish pattern (local `trio`
|
|
||||||
nursery x shared `an`), and the four validation
|
|
||||||
rejections (sync fn, async-gen fn, `portal`+`an`
|
|
||||||
combo, `runtime_kwargs`+placement combo).
|
|
||||||
|
|
||||||
> `git diff main..wkt/to_actor_subpkg -- examples/parallelism/to_actor_one_shots.py`
|
|
||||||
|
|
||||||
Runnable example (auto-collected by
|
|
||||||
`test_docs_examples.py`): the fully-implicit one-shot
|
|
||||||
plus the concurrent worker-pool-ish prime-check pattern
|
|
||||||
against a shared caller-managed actor-nursery.
|
|
||||||
|
|
||||||
## Test runs (verbatim)
|
|
||||||
|
|
||||||
```
|
|
||||||
tests/test_to_actor.py .......... [100%]
|
|
||||||
============= 10 passed in 4.29s =============
|
|
||||||
```
|
|
||||||
|
|
||||||
Regression subset for touched modules
|
|
||||||
(`test_local.py test_rpc.py test_spawning.py
|
|
||||||
test_cancellation.py`):
|
|
||||||
|
|
||||||
```
|
|
||||||
38 passed, 1 xfailed, 24 warnings in 80.71s (0:01:20)
|
|
||||||
```
|
|
||||||
|
|
||||||
(warnings are pre-existing stdlib `os.fork()`
|
|
||||||
DeprecationWarnings from the mp spawn backends, not
|
|
||||||
introduced by this change)
|
|
||||||
|
|
@ -1,77 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
session: b8ec2ffe-1e47-4db5-8bc3-5bebc5feaaf6
|
|
||||||
timestamp: 2026-07-02T15:50:06Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260702T155006Z_65bf9df5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
From `ai/prompt-io/prompts/issue_473.md`:
|
|
||||||
|
|
||||||
> NOTE: you MUST pause this work at 12:50PM EST (BEFORE
|
|
||||||
> your weekly limit reset) for review by a human!
|
|
||||||
>
|
|
||||||
> resolve GH #473: https://github.com/goodboy/tractor/issues/474
|
|
||||||
> do it with /open-wkt.
|
|
||||||
|
|
||||||
(The prompt's issue-number/URL mismatch was resolved in
|
|
||||||
favor of #473 — file name, session name and prompt text
|
|
||||||
all say #473; the `/474` URL is a typo.)
|
|
||||||
|
|
||||||
GH #473: "Root-cause UDS-on-macOS —
|
|
||||||
`uds_transport_actor_tree` example fails on CI".
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Worked all four #473 next-step checkboxes in wkt
|
|
||||||
`uds_macos_473`:
|
|
||||||
|
|
||||||
1. **stderr surfacing**: `test_docs_examples.py` now
|
|
||||||
raises with the full subproc stderr (+stdout) on ANY
|
|
||||||
non-zero exit. The old last-line-'Error' check could
|
|
||||||
never fire for `tractor` crashes since root-actor
|
|
||||||
stderr always ends with the strict-EG collapse note
|
|
||||||
`( ^^^ this exc was collapsed from a group ^^^ )` —
|
|
||||||
proven against the real PR #460 macOS CI log (bare
|
|
||||||
`assert 1 == 0`, no traceback).
|
|
||||||
2. **root-cause (linux-provable layer)**: macOS-only
|
|
||||||
addr corruption in
|
|
||||||
`MsgpackUDSStream.get_stream_addrs()` — no
|
|
||||||
`SO_PASSCRED`/autobind on darwin means the accept
|
|
||||||
side's `getpeername()` is `''`, and the
|
|
||||||
`(str(), str())` arm took `peername` unconditionally →
|
|
||||||
`Path('')` garbage addrs on every accepted conn.
|
|
||||||
Proven + fixed via linux no-autobind simulation.
|
|
||||||
Possibly not the final macOS crasher (non-fatal on
|
|
||||||
linux-sim); the diagnostic patch guarantees the next
|
|
||||||
macOS CI run shows any remaining layer.
|
|
||||||
3. **CI matrix**: removed the `macos-latest`+`uds`
|
|
||||||
exclude.
|
|
||||||
4. **un-skip**: dropped the macOS+CI skip of the example.
|
|
||||||
|
|
||||||
Also: `start_listener()` bindspace mkdir hardened
|
|
||||||
(`parents=True, exist_ok=True`), example docstring
|
|
||||||
peer-pid mechanism corrected for macOS.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tests/test_docs_examples.py` — surface full stderr on
|
|
||||||
non-zero exit; remove macOS skip of the UDS example
|
|
||||||
- `tractor/ipc/_uds.py` — fix no-autobind
|
|
||||||
`get_stream_addrs()` arm; harden bindspace mkdir;
|
|
||||||
document autobind semantics
|
|
||||||
- `.github/workflows/ci.yml` — add macOS UDS leg (remove
|
|
||||||
matrix exclude)
|
|
||||||
- `examples/uds_transport_actor_tree.py` — platform-
|
|
||||||
correct peer-pid docs
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None yet — pending human review (hard-stop review
|
|
||||||
checkpoint at 12:50PM EST per prompt); commit staging and
|
|
||||||
any edits are the human's.
|
|
||||||
|
|
@ -1,101 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-02T15:50:06Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
diff_cmd: git diff main..wkt/uds_macos_473
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output — GH #473 UDS-on-macOS root-cause session
|
|
||||||
|
|
||||||
NOTE: code output is diff-referenced (not copied) per
|
|
||||||
prompt-io diff-ref mode; all generated code is on branch
|
|
||||||
`wkt/uds_macos_473` relative to `main` (65bf9df5).
|
|
||||||
|
|
||||||
## Diagnostic narrative (verbatim)
|
|
||||||
|
|
||||||
Root-cause work proceeded by linux-side simulation since no
|
|
||||||
macOS host is available:
|
|
||||||
|
|
||||||
1. Pulled the actual macOS CI failure log from PR #460 run
|
|
||||||
28343878933 (job 84115107992): the failure is a bare
|
|
||||||
`assert 1 == 0` on `proc.returncode` with NO stderr
|
|
||||||
surfaced — the harness only re-raised when the LAST
|
|
||||||
stderr line contained 'Error'.
|
|
||||||
|
|
||||||
2. Reproduced the stderr-swallow mechanism on linux: any
|
|
||||||
`tractor` root-actor crash ends stderr with the
|
|
||||||
strict-EG collapse note
|
|
||||||
`( ^^^ this exc was collapsed from a group ^^^ )` which
|
|
||||||
never matches 'Error' — so EVERY possible crash was
|
|
||||||
swallowed. (Verified by sabotaging the runtime dir via
|
|
||||||
an over-long `XDG_RUNTIME_DIR` → `OSError: AF_UNIX path
|
|
||||||
too long` → rc=1 + swallowed.)
|
|
||||||
|
|
||||||
3. Found + proved a macOS-only addr-corruption bug in
|
|
||||||
`MsgpackUDSStream.get_stream_addrs()`: the
|
|
||||||
`(str(), str())` match-arm unconditionally took
|
|
||||||
`peername`, but on no-autobind platforms (macOS lacks
|
|
||||||
linux's `SO_PASSCRED`-triggered autobind) the accept
|
|
||||||
side's `getpeername()` is `''` → `Path('')` garbage
|
|
||||||
laddr/raddr on EVERY accepted UDS conn. Simulated on
|
|
||||||
linux by nulling `SO_PASSCRED` (no autobind → same `''`
|
|
||||||
shape): pre-fix the example printed
|
|
||||||
`listener sock file: .`; post-fix it prints the real
|
|
||||||
registry sockpath. Non-fatal on linux-sim (rc=0), so
|
|
||||||
possibly not the final macOS crasher — the diagnostic
|
|
||||||
patch guarantees the next macOS CI run reveals any
|
|
||||||
remaining layer.
|
|
||||||
|
|
||||||
4. Falsified the missing-parent-dir theory:
|
|
||||||
`get_rt_dir()` already `mkdir(parents=True,
|
|
||||||
exist_ok=True)`s at import (and macOS TCP CI passes),
|
|
||||||
so `~/Library/Caches/TemporaryItems` absence cannot be
|
|
||||||
the crasher. Hardened `start_listener()`'s bindspace
|
|
||||||
mkdir anyway (custom `filedir` case + racing actors).
|
|
||||||
|
|
||||||
## Generated changes (diff pointers)
|
|
||||||
|
|
||||||
> `git diff main..wkt/uds_macos_473 -- tests/test_docs_examples.py`
|
|
||||||
|
|
||||||
- always raise with FULL subproc stderr (+stdout) on any
|
|
||||||
non-zero example exit; keep legacy last-line 'Error'
|
|
||||||
check for zero-rc cases; drop the macOS+CI skip of
|
|
||||||
`uds_transport_actor_tree.py` (GH #473 next-step).
|
|
||||||
|
|
||||||
> `git diff main..wkt/uds_macos_473 -- tractor/ipc/_uds.py`
|
|
||||||
|
|
||||||
- `get_stream_addrs()`: document the autobind semantics
|
|
||||||
(bytes = linux abstract-ns autobind artifact), add
|
|
||||||
no-autobind `(str, str)` arm picking the non-empty name
|
|
||||||
(`peername` connect-side, `sockname` accept-side) with
|
|
||||||
an empty-pair `ValueError` guard.
|
|
||||||
- `start_listener()`: `bs.mkdir(parents=True,
|
|
||||||
exist_ok=True)`.
|
|
||||||
|
|
||||||
> `git diff main..wkt/uds_macos_473 -- .github/workflows/ci.yml`
|
|
||||||
|
|
||||||
- remove the `macos-latest`+`uds` matrix exclude so
|
|
||||||
UDS-on-macOS is exercised by CI (GH #473 next-step).
|
|
||||||
|
|
||||||
> `git diff main..wkt/uds_macos_473 -- examples/uds_transport_actor_tree.py`
|
|
||||||
|
|
||||||
- docs nit: peer-pid mechanism is `SO_PEERCRED` on linux,
|
|
||||||
`LOCAL_PEERPID` on macOS.
|
|
||||||
|
|
||||||
## Verification (verbatim summary)
|
|
||||||
|
|
||||||
- macOS-shape sim (no autobind) + fix: example rc=0 with
|
|
||||||
correct listener sockpath.
|
|
||||||
- native linux post-fix: example rc=0, autobind arms
|
|
||||||
unchanged.
|
|
||||||
- sabotage smoke-test: diagnostic patch surfaces the full
|
|
||||||
EG traceback incl. collapse-note line.
|
|
||||||
- `pytest tests/ipc/ tests/test_2way.py tests/discovery/
|
|
||||||
--tpt-proto uds`: 61 passed, 1 `TooSlowError` flake
|
|
||||||
(test_simple_rpc) that passes solo in 2.2s — attributed
|
|
||||||
to a concurrent full-suite run (other session) loading
|
|
||||||
the host.
|
|
||||||
- full `tests/test_docs_examples.py` run pending at
|
|
||||||
raw-file write time (queued behind the concurrent
|
|
||||||
session's suite).
|
|
||||||
|
|
@ -1,83 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
session: b6b42e23-0454-4d9b-be1c-0a89d65aed1b
|
|
||||||
timestamp: 2026-07-02T15:56:26Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260702T155626Z_65bf9df5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
From `ai/prompt-io/prompts/issue_470.md`:
|
|
||||||
|
|
||||||
> attempt to resolve
|
|
||||||
> https://github.com/goodboy/tractor/issues/470
|
|
||||||
> do it with /open-wkt, ensure you /run-tests on all
|
|
||||||
> changes
|
|
||||||
|
|
||||||
(plus a hard pause-for-human-review deadline of
|
|
||||||
12:50PM EST.)
|
|
||||||
|
|
||||||
Issue #470 asks to trim the ~0.42s `import tractor`
|
|
||||||
cost — which dominates per-actor spawn latency on the
|
|
||||||
`trio` backend — by lazy-importing heavy/optional deps
|
|
||||||
(`pdbp`, `stackscope`, `multiaddr`, + audit of
|
|
||||||
`colorlog`/`bidict`/`wrapt`/`setproctitle`).
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Profiling showed the issue's dep-list only accounted
|
|
||||||
for ~20ms; the dominant cost (~244ms) was
|
|
||||||
`log.get_logger()`'s `get_caller_mod()` calling
|
|
||||||
`inspect.stack()` at module level in ~39 modules —
|
|
||||||
each call walks every stack frame (deep during nested
|
|
||||||
imports) and scans `sys.modules` per frame via
|
|
||||||
`inspect.getmodule()`.
|
|
||||||
|
|
||||||
Changes, in impact order:
|
|
||||||
|
|
||||||
1. `get_caller_mod()` -> `sys._getframe()` +
|
|
||||||
`f_globals['__name__']` `sys.modules` lookup
|
|
||||||
(~240ms saved).
|
|
||||||
2. Issue's lazy-import checklist: `bidict`,
|
|
||||||
`multiaddr`, `colorlog`, `wrapt` moved to
|
|
||||||
`TYPE_CHECKING`/function-local imports;
|
|
||||||
`platformdirs` function-local; `asyncio` +
|
|
||||||
`.to_asyncio` deferred out of the `devx.debug` +
|
|
||||||
`spawn._entry` eager paths (~15ms saved).
|
|
||||||
3. PEP 562 `__getattr__` on `tractor/__init__.py`
|
|
||||||
preserving public `tractor.to_asyncio` attr access.
|
|
||||||
|
|
||||||
Results: `import tractor` 0.42s -> ~0.145s (~65%);
|
|
||||||
sequential `start_actor` latency 0.40-0.44s ->
|
|
||||||
~0.179s/actor. `pdbp` (needs `_repl.py` class-base
|
|
||||||
restructure) + `platformdirs` (needs
|
|
||||||
`UDSAddress.def_bindspace` protocol rework) documented
|
|
||||||
as follow-ups.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/log.py` — `get_caller_mod()` perf fix +
|
|
||||||
lazy `colorlog`
|
|
||||||
- `tractor/__init__.py` — PEP 562 lazy `to_asyncio`
|
|
||||||
- `tractor/discovery/_addr.py` — `bidict` ->
|
|
||||||
`TYPE_CHECKING`
|
|
||||||
- `tractor/discovery/_multiaddr.py` — lazy `multiaddr`
|
|
||||||
- `tractor/ipc/_tcp.py`, `tractor/ipc/_uds.py` —
|
|
||||||
`Multiaddr` -> `TYPE_CHECKING`
|
|
||||||
- `tractor/runtime/_state.py` — lazy `platformdirs`
|
|
||||||
- `tractor/devx/_frame_stack.py` — lazy `pdbp` +
|
|
||||||
`wrapt`
|
|
||||||
- `tractor/devx/debug/_trace.py`,
|
|
||||||
`tractor/devx/debug/_tty_lock.py` — lazy `asyncio` +
|
|
||||||
`.to_asyncio`
|
|
||||||
- `tractor/spawn/_entry.py` — lazy
|
|
||||||
`run_as_asyncio_guest`
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None yet — pending user review at the 12:50PM EST
|
|
||||||
pause gate (test-suite results reported in-session).
|
|
||||||
|
|
@ -1,122 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-02T15:56:26Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
diff_cmd: git diff main..wkt/boot_latency_470
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw AI output — gh #470 `import tractor` latency trim
|
|
||||||
|
|
||||||
All generated code is committed on the
|
|
||||||
`wkt/boot_latency_470` branch; per diff-ref mode each
|
|
||||||
file's content is referenced via its diff instead of
|
|
||||||
copied verbatim.
|
|
||||||
|
|
||||||
## Profiling findings (verbatim analysis output)
|
|
||||||
|
|
||||||
Baseline: `import tractor` ~0.39-0.42s wall.
|
|
||||||
|
|
||||||
`python -X importtime` + `cProfile` traced the cost NOT
|
|
||||||
primarily to third-party deps (the issue's hypothesis)
|
|
||||||
but to `tractor/log.py:get_logger()` calling
|
|
||||||
`get_caller_mod()` -> `inspect.stack()` at module level
|
|
||||||
in ~39 tractor modules:
|
|
||||||
|
|
||||||
- `inspect.stack()` builds `FrameInfo` (incl. src-file
|
|
||||||
and line-context resolution) for EVERY frame on the
|
|
||||||
stack; during nested imports the stack is dozens of
|
|
||||||
importlib frames deep.
|
|
||||||
- each `FrameInfo` resolution calls
|
|
||||||
`inspect.getmodule()` which scans all of
|
|
||||||
`sys.modules` per frame (1.4M `ismodule()` calls in
|
|
||||||
one profiled import).
|
|
||||||
- aggregate: ~244ms of tractor-own module "self" time
|
|
||||||
vs ~20ms for ALL the issue-listed third-party deps
|
|
||||||
(`pdbp` ~10ms, `bidict` ~4.5ms, `multiaddr` ~3.5ms,
|
|
||||||
`wrapt`/`colorlog` ~1ms each); `trio` itself is
|
|
||||||
~70-100ms and unavoidable.
|
|
||||||
|
|
||||||
## Generated changes
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/log.py`
|
|
||||||
|
|
||||||
`get_caller_mod()` rewritten from `inspect.stack()` +
|
|
||||||
`inspect.getmodule()` to `sys._getframe(frames_up)` +
|
|
||||||
`frame.f_globals['__name__']` -> `sys.modules` lookup
|
|
||||||
(O(1) vs O(stack x sys.modules)). Unused `inspect`
|
|
||||||
imports dropped; `FrameType` imported from `types`.
|
|
||||||
Also `colorlog` lazy-imported inside
|
|
||||||
`get_console_log()`.
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/discovery/_addr.py`
|
|
||||||
|
|
||||||
`bidict` import moved under `TYPE_CHECKING`
|
|
||||||
(annotation-only use; `_address_types` is a plain dict
|
|
||||||
literal).
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/discovery/_multiaddr.py`
|
|
||||||
|
|
||||||
`from __future__ import annotations` added; `multiaddr`
|
|
||||||
import moved under `TYPE_CHECKING` + function-local
|
|
||||||
imports in `mk_maddr()`/`parse_maddr()`.
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/ipc/_tcp.py tractor/ipc/_uds.py`
|
|
||||||
|
|
||||||
`Multiaddr` imports moved under `TYPE_CHECKING`
|
|
||||||
(annotation-only in both transports).
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/runtime/_state.py`
|
|
||||||
|
|
||||||
`platformdirs` lazy-imported inside `get_rt_dir()`
|
|
||||||
(NOTE: still imported eagerly via
|
|
||||||
`UDSAddress.def_bindspace` class-var eval; see
|
|
||||||
follow-ups).
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/devx/_frame_stack.py`
|
|
||||||
|
|
||||||
`pdbp` + `wrapt` lazy-imported inside
|
|
||||||
`hide_runtime_frames()` / `api_frame()` respectively.
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/devx/debug/_trace.py tractor/devx/debug/_tty_lock.py`
|
|
||||||
|
|
||||||
`asyncio` moved to `TYPE_CHECKING` + call-site local
|
|
||||||
imports (`asyncio.current_task()` sites);
|
|
||||||
`tractor.to_asyncio.run_trio_task_in_future` imports
|
|
||||||
moved into the infected-aio runtime branches.
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/spawn/_entry.py`
|
|
||||||
|
|
||||||
`run_as_asyncio_guest` import moved into the
|
|
||||||
`infect_asyncio=True` branches of `_mp_main()` /
|
|
||||||
`_trio_main()`.
|
|
||||||
|
|
||||||
> `git diff main..wkt/boot_latency_470 -- tractor/__init__.py`
|
|
||||||
|
|
||||||
PEP 562 module `__getattr__` added so
|
|
||||||
`tractor.to_asyncio` attr-access still works (required
|
|
||||||
by `tests/test_child_manages_service_nursery.py` and
|
|
||||||
any downstream user) while keeping `asyncio` off the
|
|
||||||
eager import path.
|
|
||||||
|
|
||||||
## Measured results (verbatim)
|
|
||||||
|
|
||||||
- `import tractor`: 0.39-0.42s -> ~0.145s (~65% cut)
|
|
||||||
- `start_actor` spawn+boot+reg+cancel: ~0.40-0.44s ->
|
|
||||||
~0.179s/actor (n=5 sequential, warm parent)
|
|
||||||
- post-change eager-module check: only `pdbp` +
|
|
||||||
`platformdirs` of the issue's list remain eager.
|
|
||||||
|
|
||||||
## Known follow-ups (not implemented, deadline-bound)
|
|
||||||
|
|
||||||
- `pdbp` (~10ms): still eager via
|
|
||||||
`devx/debug/_repl.py` class bases
|
|
||||||
(`class PdbREPL(pdbp.Pdb)`) + `_tty_lock.py`
|
|
||||||
module-level `@pdbp.hideframe`; needs `_repl`
|
|
||||||
restructure + PEP 562 in `devx.debug.__init__`.
|
|
||||||
- `platformdirs` (~1.5ms): eager via
|
|
||||||
`UDSAddress.def_bindspace: ClassVar = get_rt_dir()`
|
|
||||||
class-body call; needs `Address`-protocol rework of
|
|
||||||
`def_bindspace` to a lazy accessor.
|
|
||||||
- `stackscope` + `setproctitle`: already lazy/absent —
|
|
||||||
no change needed.
|
|
||||||
|
|
@ -1,80 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
session: f4da6654-63f9-4641-b567-f200da46d697
|
|
||||||
timestamp: 2026-07-02T16:16:24Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
scope: tests
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260702T161624Z_65bf9df5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
> attempt to resolve
|
|
||||||
> https://github.com/goodboy/tractor/issues/474
|
|
||||||
> do it with /open-wkt.
|
|
||||||
|
|
||||||
Issue #474: "We need test suite for
|
|
||||||
`.trionics.start_or_cancel()`" — dig out the use case
|
|
||||||
from `modden` as a unit test (and provide motivation
|
|
||||||
for upstream `trio` to possibly provide better
|
|
||||||
porcelain around this case). The wrapper landed via
|
|
||||||
PR #464 with no tests.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
New `tests/trionics/test_taskc.py` (9 tests) covering
|
|
||||||
`start_or_cancel()`, authored in wkt
|
|
||||||
`start_or_cancel_tests_474`.
|
|
||||||
|
|
||||||
Behaviour was first probed empirically (trio 0.29):
|
|
||||||
the lossy `RuntimeError('child exited without calling
|
|
||||||
task_status.started()')` only fires when the child
|
|
||||||
exits pre-`.started()` WITHOUT propagating the ambient
|
|
||||||
`Cancelled` — i.e. when the child (or lib code it
|
|
||||||
calls) absorbs the cancel in a graceful-teardown
|
|
||||||
pattern; a well-behaved child surfaces `Cancelled`
|
|
||||||
straight out of `.start()`. The `modden`
|
|
||||||
`progman.open_wks()` use case was reconstructed from
|
|
||||||
`modden/runtime/progman.py` accordingly.
|
|
||||||
|
|
||||||
Tests (each `use_start_or_cancel` parametrization also
|
|
||||||
pins upstream trio's current lossy behaviour as
|
|
||||||
wart-documentation):
|
|
||||||
|
|
||||||
- `test_sibling_err_not_masked_by_startup_rte` — the
|
|
||||||
`modden` case: sibling error OOB-cancels the shared
|
|
||||||
nursery scope; with the wrapper ONLY the root-cause
|
|
||||||
`ValueError` escapes; bare `.start()` adds the lossy
|
|
||||||
RTE alongside.
|
|
||||||
- `test_pure_oob_cancel_not_morphed_to_rte` — plain
|
|
||||||
ancestor `cs.cancel()`: wrapper → clean exit; bare
|
|
||||||
→ eg-wrapped RTE.
|
|
||||||
- `test_genuine_startup_rte_still_raised` — no
|
|
||||||
cancellation → protocol-bug RTE re-raised same as
|
|
||||||
bare.
|
|
||||||
- `test_childs_own_rte_never_demoted_to_cancel` — a
|
|
||||||
child's own `RuntimeError('never got started!')` /
|
|
||||||
`RuntimeError(1234)` under ambient cancel is never
|
|
||||||
demoted to `Cancelled` (exact-msg-match + str-guard
|
|
||||||
regression cover).
|
|
||||||
- `test_started_value_and_args_passthru` — happy path:
|
|
||||||
positional args, `name=`, `.started()` value.
|
|
||||||
|
|
||||||
Verified: 9/9 pass; 0 flakes across 50 hammer runs;
|
|
||||||
two impl mutations (checkpoint removed; guard relaxed
|
|
||||||
to substring match) each caught by exactly the
|
|
||||||
targeted tests; `tests/trionics/` +
|
|
||||||
`tests/test_trioisms.py` subset green (23 passed,
|
|
||||||
5 xfailed); ruff clean; 69-col style.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tests/trionics/test_taskc.py` — new
|
|
||||||
`start_or_cancel()` unit-test suite (gh #474).
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
Pending review — session paused pre-commit per user
|
|
||||||
deadline; nothing committed as of this entry.
|
|
||||||
|
|
@ -1,107 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-02T16:16:24Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
diff_cmd: git diff main..wkt/start_or_cancel_tests_474
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output — gh #474 `start_or_cancel()` test suite
|
|
||||||
|
|
||||||
## Generated test code
|
|
||||||
|
|
||||||
> `git diff main..wkt/start_or_cancel_tests_474 -- tests/trionics/test_taskc.py`
|
|
||||||
|
|
||||||
Prose summary of the generated module
|
|
||||||
(`tests/trionics/test_taskc.py`):
|
|
||||||
|
|
||||||
- module docstring framing the `trio.Nursery.start()`
|
|
||||||
startup-cancellation wart, the wrapper's repair, and
|
|
||||||
the intent that `use_start_or_cancel=False` params
|
|
||||||
double as upstream-trio wart-documentation (break on
|
|
||||||
a trio upgrade → upstream may have shipped porcelain,
|
|
||||||
re-audit the wrapper); cites gh #474 / PR #464 and
|
|
||||||
`modden`'s `progman.open_wks()` as the source use
|
|
||||||
case.
|
|
||||||
- shared children: `absorbs_cancel_pre_started()` (the
|
|
||||||
graceful-teardown cancel-absorber which triggers the
|
|
||||||
lossy RTE path) + `raise_val_err()` (fast-erroring
|
|
||||||
sibling).
|
|
||||||
- `test_sibling_err_not_masked_by_startup_rte`
|
|
||||||
(parametrized `use_start_or_cancel`): asserts eg
|
|
||||||
contains exactly one `ValueError` and, wrapper-case,
|
|
||||||
NO residual RTE (`eg.split(ValueError)` remainder is
|
|
||||||
`None`); bare-case, the residual RTE carries trio's
|
|
||||||
exact "child exited without calling" wording.
|
|
||||||
- `test_pure_oob_cancel_not_morphed_to_rte`
|
|
||||||
(parametrized): wrapper-case runs clean and asserts
|
|
||||||
`cs.cancelled_caught`; bare-case asserts the
|
|
||||||
eg-wrapped RTE.
|
|
||||||
- `test_genuine_startup_rte_still_raised`
|
|
||||||
(parametrized): no-cancel protocol bug → RTE with
|
|
||||||
trio's wording from both call forms.
|
|
||||||
- `test_childs_own_rte_never_demoted_to_cancel`
|
|
||||||
(parametrized `rte_arg` in `'never got started!'`,
|
|
||||||
`1234`): child cancels the ambient scope then raises
|
|
||||||
its own RTE synchronously (no checkpoint between →
|
|
||||||
deterministically under-cancellation at catch time);
|
|
||||||
asserts the RTE survives with `args[0]` intact.
|
|
||||||
- `test_started_value_and_args_passthru`: `.started()`
|
|
||||||
value, positional args and the `name=` kwarg (via
|
|
||||||
`trio.lowlevel.current_task().name`) all forward.
|
|
||||||
|
|
||||||
## Non-code output (verbatim highlights)
|
|
||||||
|
|
||||||
Behaviour probe (trio 0.29, scratchpad scripts) — the
|
|
||||||
decision basis for the test shapes:
|
|
||||||
|
|
||||||
```
|
|
||||||
== B-sibling-err use_soc=False
|
|
||||||
start raised: RuntimeError('child exited without
|
|
||||||
calling task_status.started()')
|
|
||||||
top-level: ExceptionGroup([ValueError('sibling blew
|
|
||||||
up!'), RuntimeError('child exited without calling
|
|
||||||
task_status.started()')])
|
|
||||||
== B-cs-cancel use_soc=False
|
|
||||||
top-level: ExceptionGroup([RuntimeError('child
|
|
||||||
exited without calling task_status.started()')])
|
|
||||||
== B-sibling-err use_soc=True
|
|
||||||
start raised: Cancelled()
|
|
||||||
top-level: ExceptionGroup([ValueError('sibling blew
|
|
||||||
up!')])
|
|
||||||
== B-cs-cancel use_soc=True
|
|
||||||
start raised: Cancelled()
|
|
||||||
top-level: clean return
|
|
||||||
== own-rte-under-cancel (both) -> RTE('never got
|
|
||||||
started!') propagates unchanged
|
|
||||||
```
|
|
||||||
|
|
||||||
Key finding: with a WELL-BEHAVED (non-absorbing) child
|
|
||||||
an OOB ancestor cancel surfaces `Cancelled` directly
|
|
||||||
from `.start()` on trio 0.29 — the lossy RTE requires
|
|
||||||
the child to absorb its cancel pre-`.started()`, which
|
|
||||||
is what `modden`'s `open_from_wks` teardown did. Trio's
|
|
||||||
nursery-exit wait defers cancel delivery to children,
|
|
||||||
so all tested shapes are deterministic (0 flakes / 50
|
|
||||||
runs).
|
|
||||||
|
|
||||||
Mutation verification:
|
|
||||||
|
|
||||||
```
|
|
||||||
mutation 1 (checkpoint_if_cancelled removed):
|
|
||||||
FAILED test_sibling_err_not_masked_by_startup_rte[True]
|
|
||||||
FAILED test_pure_oob_cancel_not_morphed_to_rte[True]
|
|
||||||
mutation 2 (guard relaxed to 'started' substring,
|
|
||||||
isinstance dropped):
|
|
||||||
FAILED test_childs_own_rte_never_demoted_to_cancel[never got started!]
|
|
||||||
FAILED test_childs_own_rte_never_demoted_to_cancel[1234]
|
|
||||||
```
|
|
||||||
|
|
||||||
Final runs:
|
|
||||||
|
|
||||||
```
|
|
||||||
tests/trionics/test_taskc.py: 9 passed in 0.03s
|
|
||||||
hammer: 0/50 runs failed
|
|
||||||
tests/trionics/ + tests/test_trioisms.py:
|
|
||||||
23 passed, 5 xfailed in 3.02s
|
|
||||||
```
|
|
||||||
|
|
@ -1,78 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
session: f6c84722-471a-4458-9a80-e453fea9029f
|
|
||||||
timestamp: 2026-07-02T16:58:06Z
|
|
||||||
git_ref: a34aaf98
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260702T165806Z_a34aaf98_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Follow-up round in the same session as the
|
|
||||||
`tractor.to_actor` landing (see
|
|
||||||
`20260702T154255Z_65bf9df5_prompt_io.md`). After
|
|
||||||
committing that work the user green-lit the deferred
|
|
||||||
items:
|
|
||||||
|
|
||||||
> go go go on this with what time you have left, in
|
|
||||||
> particular see if you can get the _ria_nursery
|
|
||||||
> removal going!
|
|
||||||
|
|
||||||
then extended the deadline twice to iterate on the
|
|
||||||
discovered hang:
|
|
||||||
|
|
||||||
> continue on this up until a 12:58:30 deadline
|
|
||||||
|
|
||||||
and finally chose "Commit step A now" from the
|
|
||||||
next-steps prompt.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Step A of the `._ria_nursery` removal (issue #477): hoist
|
|
||||||
`.run_in_actor()` result-reaping out of the spawn
|
|
||||||
backends into the `ActorNursery` machinery so ria
|
|
||||||
children spawn via the default daemon nursery,
|
|
||||||
|
|
||||||
- new `_supervise._reap_ria_portals()` runs one
|
|
||||||
`_spawn.cancel_on_completion()` task per ria child
|
|
||||||
AFTER `._join_procs` is set; happy path awaits it
|
|
||||||
right after `._join_procs.set()`.
|
|
||||||
- error path SEQUENCES: snapshot ria
|
|
||||||
`(portal, subactor)` pairs -> `await an.cancel()` ->
|
|
||||||
0.5s-bounded reap. Two failed intermediates informed
|
|
||||||
this: a concurrent reap+cancel DEADLOCKED
|
|
||||||
`test_multierror`; a 3s bound blew
|
|
||||||
`test_cancel_while_childs_child_in_sync_sleep`'s
|
|
||||||
`fail_after` deadline.
|
|
||||||
- backends (`spawn/_trio.py`, `spawn/_mp.py`) lose the
|
|
||||||
`._cancel_after_result_on_exit` membership branch,
|
|
||||||
per-child reaper nursery + dead imports.
|
|
||||||
- design/probe-history doc:
|
|
||||||
`ai/conc-anal/ria_nursery_removal_plan.md` (from an
|
|
||||||
agent-verified machinery map).
|
|
||||||
|
|
||||||
Verification: `test_cancellation.py` fully green
|
|
||||||
(20 passed, 1 xfailed) incl. the previously-hung
|
|
||||||
`test_multierror`; `test_to_actor`+`test_spawning`
|
|
||||||
20/20; bounded full-suite gate SIGINT'd ~30s early at
|
|
||||||
303 passed / 0 failures (user opted to commit on that
|
|
||||||
signal, deferring the unbounded re-run to step-B
|
|
||||||
verification).
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/runtime/_supervise.py` — `_reap_ria_portals()`
|
|
||||||
+ two call-sites; `run_in_actor()` off the ria nursery
|
|
||||||
- `tractor/spawn/_trio.py` — reaper branch + import drop
|
|
||||||
- `tractor/spawn/_mp.py` — same as `_trio.py`
|
|
||||||
- `ai/conc-anal/ria_nursery_removal_plan.md` — plan +
|
|
||||||
probe history
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None yet — committed via the drafted
|
|
||||||
`.claude/git_commit_msg_ria_step_a.md` (user-driven
|
|
||||||
`git commit --edit`).
|
|
||||||
|
|
@ -1,55 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-02T16:58:06Z
|
|
||||||
git_ref: a34aaf98
|
|
||||||
diff_cmd: git diff a34aaf98..wkt/to_actor_subpkg
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw AI output (diff-ref mode)
|
|
||||||
|
|
||||||
Step-A code is committed on `wkt/to_actor_subpkg`
|
|
||||||
directly after `a34aaf98`; per diff-ref mode the verbatim
|
|
||||||
content is reachable via the pointers below.
|
|
||||||
|
|
||||||
## Generated files
|
|
||||||
|
|
||||||
> `git diff a34aaf98..wkt/to_actor_subpkg -- tractor/runtime/_supervise.py`
|
|
||||||
|
|
||||||
New `_reap_ria_portals(an, errors, ria_children=None)`
|
|
||||||
helper (one `_spawn.cancel_on_completion()` task per ria
|
|
||||||
child under `collapse_eg()` + a local nursery);
|
|
||||||
`run_in_actor()` drops `nursery=self._ria_nursery`; happy
|
|
||||||
path awaits the reap right after `._join_procs.set()`;
|
|
||||||
inner error handler snapshots ria pairs, runs
|
|
||||||
`await an.cancel()` then a `move_on_after(0.5)`-bounded
|
|
||||||
reap over the snapshot.
|
|
||||||
|
|
||||||
> `git diff a34aaf98..wkt/to_actor_subpkg -- tractor/spawn/_trio.py`
|
|
||||||
> `git diff a34aaf98..wkt/to_actor_subpkg -- tractor/spawn/_mp.py`
|
|
||||||
|
|
||||||
Both backends: the post-`_join_procs` block collapses to
|
|
||||||
a bare `soft_kill()` (membership branch, per-child reaper
|
|
||||||
nursery, reaper-cancel logging and the now-unused
|
|
||||||
`cancel_on_completion` imports all removed).
|
|
||||||
|
|
||||||
> `git diff a34aaf98..wkt/to_actor_subpkg -- ai/conc-anal/ria_nursery_removal_plan.md`
|
|
||||||
|
|
||||||
Agent-verified machinery map, 3-step design (A/B/C),
|
|
||||||
probe history (deadlock -> sequencing fix -> bound
|
|
||||||
tightening) and risk register.
|
|
||||||
|
|
||||||
## Test runs (verbatim)
|
|
||||||
|
|
||||||
```
|
|
||||||
tests/test_cancellation.py: 20 passed, 1 xfailed in 77.28s
|
|
||||||
tests/test_to_actor.py + tests/test_spawning.py: 20 passed
|
|
||||||
full-suite (SIGINT at 540s bound, ~30s short):
|
|
||||||
303 passed, 9 skipped, 1 xfailed, 2 xpassed in 539.42s
|
|
||||||
```
|
|
||||||
|
|
||||||
Failed intermediates (not in final diff): concurrent
|
|
||||||
reap+`an.cancel()` deadlocked `test_multierror`; a 3s
|
|
||||||
reap bound blew
|
|
||||||
`test_cancel_while_childs_child_in_sync_sleep`'s
|
|
||||||
`fail_after` deadline.
|
|
||||||
|
|
@ -1,60 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-8
|
|
||||||
service: claude
|
|
||||||
session: c7860302-6a33-4d92-821c-0807d68be464
|
|
||||||
timestamp: 2026-07-02T17:22:33Z
|
|
||||||
git_ref: 5cd190c5
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260702T172233Z_5cd190c5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Branched session (`to_actor_subpkg_POST_WEEKLY_CUTOFF_2OPUS`,
|
|
||||||
now on Opus 4.8) continuing the `._ria_nursery` removal after
|
|
||||||
step A committed + pushed (`5cd190c5`/`99310269`):
|
|
||||||
|
|
||||||
> ok continue where your superior left off please
|
|
||||||
|
|
||||||
then, after the commit-split discussion:
|
|
||||||
|
|
||||||
> yup committed and pushed so take a look ma fren.
|
|
||||||
|
|
||||||
i.e. green-lighting step-B prep against the committed step-A
|
|
||||||
tree.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Step B of the `._ria_nursery` removal (issue #477): delete
|
|
||||||
the now-vestigial secondary nursery,
|
|
||||||
|
|
||||||
- collapse the inner `async with (collapse_eg(),
|
|
||||||
trio.open_nursery() as ria_nursery)` layer in
|
|
||||||
`_open_and_supervise_one_cancels_all_nursery` — `da_nursery`
|
|
||||||
becomes the single nursery for ALL subactors.
|
|
||||||
- `ActorNursery.__init__` drops the `ria_nursery` param + the
|
|
||||||
`self._ria_nursery` attr; `start_actor()` drops its
|
|
||||||
`nursery=` escape-hatch param.
|
|
||||||
- `._cancel_after_result_on_exit` kept (ria-child
|
|
||||||
discriminator for `_reap_ria_portals()`).
|
|
||||||
|
|
||||||
Verified behavior-preserving via a first-principles argument
|
|
||||||
(zero-task nursery = a bare checkpoint) + the targeted gate
|
|
||||||
(`test_cancellation test_spawning test_local test_rpc
|
|
||||||
test_to_actor` = 49 passed, 1 xfailed on trio). The two
|
|
||||||
error handlers were deliberately NOT merged — that changes
|
|
||||||
propagation semantics and is deferred to its own PR (TODO
|
|
||||||
left at the outer `except`).
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/runtime/_supervise.py` — collapse the ria nursery
|
|
||||||
layer + drop the ctor/`start_actor` params + refresh the
|
|
||||||
now-stale nursery comments
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None yet — committed via the drafted
|
|
||||||
`.claude/git_commit_msg_ria_step_b.md` (user-driven
|
|
||||||
`git commit --edit`).
|
|
||||||
|
|
@ -1,51 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-8
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-02T17:22:33Z
|
|
||||||
git_ref: 5cd190c5
|
|
||||||
diff_cmd: git diff 5cd190c5..wkt/to_actor_subpkg
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw AI output (diff-ref mode)
|
|
||||||
|
|
||||||
Step-B code lives on `wkt/to_actor_subpkg` after `5cd190c5`;
|
|
||||||
per diff-ref mode the verbatim content is reachable via the
|
|
||||||
pointer below.
|
|
||||||
|
|
||||||
## Generated files
|
|
||||||
|
|
||||||
> `git diff 5cd190c5..wkt/to_actor_subpkg -- tractor/runtime/_supervise.py`
|
|
||||||
|
|
||||||
- `ActorNursery.__init__`: `ria_nursery` param removed;
|
|
||||||
`self._ria_nursery = ria_nursery` block deleted;
|
|
||||||
`_cancel_after_result_on_exit` comment refreshed.
|
|
||||||
- `start_actor()`: `nursery=` param removed; body uses
|
|
||||||
`self._da_nursery.start(...)` directly.
|
|
||||||
- `_open_and_supervise_one_cancels_all_nursery()`: the inner
|
|
||||||
`async with (collapse_eg(), trio.open_nursery() as
|
|
||||||
ria_nursery)` layer removed; `an = ActorNursery(actor,
|
|
||||||
da_nursery, errors)` constructed once under the single
|
|
||||||
`da_nursery`; the inner-try body de-indented one level;
|
|
||||||
both error handlers retained; the da-nursery lead comment
|
|
||||||
and the outer-`except` TODO refreshed to describe the
|
|
||||||
single-nursery reality + flag the (deferred) handler-merge.
|
|
||||||
|
|
||||||
> `git diff 5cd190c5..wkt/to_actor_subpkg -- ai/conc-anal/ria_nursery_removal_plan.md`
|
|
||||||
|
|
||||||
Added a "Step-B outcome" section (collapse rationale,
|
|
||||||
handler-merge deferral, safety argument, gate result).
|
|
||||||
|
|
||||||
## Test runs (verbatim)
|
|
||||||
|
|
||||||
```
|
|
||||||
targeted gate (trio):
|
|
||||||
tests/test_cancellation.py tests/test_spawning.py
|
|
||||||
tests/test_local.py tests/test_rpc.py tests/test_to_actor.py
|
|
||||||
-> 49 passed, 1 xfailed in 88.62s
|
|
||||||
|
|
||||||
signature checks:
|
|
||||||
ActorNursery.__init__ params: ['self', 'actor', 'da_nursery', 'errors']
|
|
||||||
start_actor has nursery param: False
|
|
||||||
|
|
||||||
full-suite gate: in progress (see stepB_full.log)
|
|
||||||
```
|
|
||||||
|
|
@ -1,68 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-8
|
|
||||||
service: claude
|
|
||||||
session: c7860302-6a33-4d92-821c-0807d68be464
|
|
||||||
timestamp: 2026-07-02T22:25:44Z
|
|
||||||
git_ref: 9201a2ed
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260702T222544Z_9201a2ed_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Continuing on branch `drop_ria_nursery` after step B
|
|
||||||
(`9201a2ed`). User green-lit the deferred error-handler merge:
|
|
||||||
|
|
||||||
> yes, i checked us out on a new branch for the ria-tn removal;
|
|
||||||
> work off the new wkt branch drop_ria_nursery.
|
|
||||||
|
|
||||||
and (re the migration) "nope, later we'll do this", plus:
|
|
||||||
|
|
||||||
> do ensure the test suite is green in the current state and
|
|
||||||
> those going forward ya?
|
|
||||||
|
|
||||||
and the standing reminder: no commits without a human ack.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Step B2 of the `._ria_nursery` removal (issue #477): merge the
|
|
||||||
two nested error handlers in
|
|
||||||
`_open_and_supervise_one_cancels_all_nursery` into one, now
|
|
||||||
that the 2ndary nursery (whose `__aexit__` the outer handler
|
|
||||||
originally guarded) is gone.
|
|
||||||
|
|
||||||
Trace-driven justification (see
|
|
||||||
`ai/conc-anal/ria_nursery_removal_plan.md` Step-B2 section):
|
|
||||||
the old inner handler records `errors[uid]` as its FIRST
|
|
||||||
action, so `errors` is always non-empty by the time control
|
|
||||||
could reach the outer handler — making the outer handler's
|
|
||||||
`raise` DEAD (always superseded by the `finally`'s
|
|
||||||
raise-from-`errors`). Collapsing to a single
|
|
||||||
`except BaseException as _scope_err` + the existing `finally`
|
|
||||||
is therefore behavior-preserving.
|
|
||||||
|
|
||||||
- removed the outer `try` + the
|
|
||||||
`except (Exception, BaseExceptionGroup, trio.Cancelled)`
|
|
||||||
handler; de-indented the inner handler one level.
|
|
||||||
- dropped the now-unused `outer_err`/`inner_err` locals
|
|
||||||
(single `_scope_err`).
|
|
||||||
- net ~30 lines lighter.
|
|
||||||
|
|
||||||
Gated hard: baseline (pre-B2 tip) = 300 passed + 1
|
|
||||||
load-induced `TooSlowError` flake (passes 6/6 in isolation);
|
|
||||||
B2 error/cancel gate (`test_cancellation remote_exc_relay
|
|
||||||
inter_peer_cancellation advanced_faults oob_cancellation
|
|
||||||
to_actor spawning local rpc`) = 71 passed, 1 xfailed; B2
|
|
||||||
full-suite run following.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/runtime/_supervise.py` — collapse the two handlers
|
|
||||||
into one; drop `outer_err`/`inner_err`
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None yet — committed via the drafted
|
|
||||||
`.claude/git_commit_msg_ria_b2.md` (user-driven
|
|
||||||
`git commit --edit`).
|
|
||||||
|
|
@ -1,55 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-4-8
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-02T22:25:44Z
|
|
||||||
git_ref: 9201a2ed
|
|
||||||
diff_cmd: git diff 9201a2ed..drop_ria_nursery
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw AI output (diff-ref mode)
|
|
||||||
|
|
||||||
Step-B2 code lives on `drop_ria_nursery` after `9201a2ed`; per
|
|
||||||
diff-ref mode the verbatim content is reachable via the pointer
|
|
||||||
below.
|
|
||||||
|
|
||||||
## Generated files
|
|
||||||
|
|
||||||
> `git diff 9201a2ed..drop_ria_nursery -- tractor/runtime/_supervise.py`
|
|
||||||
|
|
||||||
`_open_and_supervise_one_cancels_all_nursery`:
|
|
||||||
- removed the outer `try:` wrapper and the
|
|
||||||
`except (Exception, BaseExceptionGroup, trio.Cancelled) as
|
|
||||||
_outer_err:` safety-net handler.
|
|
||||||
- the former inner `except BaseException` is now THE handler,
|
|
||||||
renamed local `_inner_err` -> `_scope_err`, de-indented one
|
|
||||||
level; it sets `an._scope_error`, records `errors[uid]`,
|
|
||||||
waits on the debugger, `_join_procs.set()`, then a shielded
|
|
||||||
classify/log + snapshot-ria + `an.cancel()` + 0.5s-bounded
|
|
||||||
`_reap_ria_portals()`. No re-raise (the `finally` raises
|
|
||||||
from `errors`).
|
|
||||||
- `finally` block unchanged.
|
|
||||||
- dropped the `outer_err`/`inner_err` local decls at fn top.
|
|
||||||
|
|
||||||
(The diff is large — ~119+/149- — because de-indenting the
|
|
||||||
handler body one level rewrites every line in the block; the
|
|
||||||
logic delta is just "two handlers -> one".)
|
|
||||||
|
|
||||||
## Test runs (verbatim)
|
|
||||||
|
|
||||||
```
|
|
||||||
baseline (pre-B2, step-B tip 9201a2ed), full suite
|
|
||||||
(dynamic_pub_sub deselected):
|
|
||||||
1 failed, 300 passed, 9 skipped, 2 deselected, 1 xfailed,
|
|
||||||
2 xpassed in 1499.49s
|
|
||||||
-> the 1 failure = test_ext_types_over_ipc[...] trio.TooSlowError
|
|
||||||
(load-induced; passes 6/6 in isolation in 4.89s)
|
|
||||||
|
|
||||||
B2 error/cancel gate:
|
|
||||||
tests/test_cancellation test_remote_exc_relay
|
|
||||||
test_inter_peer_cancellation test_advanced_faults
|
|
||||||
test_oob_cancellation test_to_actor test_spawning test_local
|
|
||||||
test_rpc
|
|
||||||
-> 71 passed, 1 xfailed in 125.26s
|
|
||||||
|
|
||||||
B2 full-suite run: see b2_full.log
|
|
||||||
```
|
|
||||||
|
|
@ -1,81 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
session: 6db64ac6-6986-4505-9343-df4ee31e67db
|
|
||||||
timestamp: 2026-07-06T17:28:18Z
|
|
||||||
git_ref: ad42871e
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260706T172818Z_ad42871e_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Resuming the `drop_ria_nursery` (wkt) branch after the human's
|
|
||||||
review pause at `ba4af0ad`, with the directive:
|
|
||||||
|
|
||||||
> we need to resolve the remaining outstandings ... to finish
|
|
||||||
> this endeavour we ideally,
|
|
||||||
> - finish the ria-tn hoist into the machinery in `to_actor` if
|
|
||||||
> possible.
|
|
||||||
> - avoid supporting the `.run_in_actor()` non-blocking API
|
|
||||||
> going forward other then if we can re-wrap `to_actor.run()`
|
|
||||||
> per prior discussion with opus4.8.
|
|
||||||
> - get the test harness completely green locally and in CI -
|
|
||||||
> AND ESPECIALLY without any hangs due to the "the old
|
|
||||||
> spawn-backend reaper raced `soft_kill()`'s scope-cancel"
|
|
||||||
> - update all docs to reflect these changes once we're happy.
|
|
||||||
|
|
||||||
plus mid-flight additions:
|
|
||||||
|
|
||||||
> make sure both all the test and example code uses the naming
|
|
||||||
> `an: ActorNursery` for variable names
|
|
||||||
|
|
||||||
> where we at in terms of a potential hackaround design for
|
|
||||||
> supporting a to_actor.run_async() ... without requiring the
|
|
||||||
> same malarky ... with a `trio.Event` relay ... i'm totes fine
|
|
||||||
> with rejigging the iface to NOT return a Portal as well.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Completed the entire #477 `run_in_actor` removal on
|
|
||||||
`drop_ria_nursery` (16 commits this session), gated per-commit:
|
|
||||||
|
|
||||||
- ported the remaining `test_cancellation` groups
|
|
||||||
(`some_cancels_all`, `nested_multierrors`+`spawn_and_error`,
|
|
||||||
SIGINT + sync-sleep) — one-shots become concurrent
|
|
||||||
`to_actor.run()` tasks in local task-nurseries; BEG-shape
|
|
||||||
assertions loosened for cancel-on-first + the runtime's
|
|
||||||
`collapse_eg()` single-member unwrap (a fully-raced nested
|
|
||||||
tree relays a bare annotated `RemoteActorError` chain).
|
|
||||||
- fixed a pre-existing `UnboundLocalError` (`timeout` `match`
|
|
||||||
had no default arm for non-trio/MTF backends).
|
|
||||||
- ported `test_dynamic_pub_sub`, 4 non-debugging examples, all
|
|
||||||
8 `debugging/` examples (debugger suite byte-identical,
|
|
||||||
28p/6s; `multi_subactors` introduces the "collect don't
|
|
||||||
cancel" reap-all replacement pattern), 8 docs pages + the
|
|
||||||
`experimental/_pubsub` docstring.
|
|
||||||
- EXCISED the API + cluster: `run_in_actor`,
|
|
||||||
`_reap_ria_portals`, `_cancel_after_result_on_exit`,
|
|
||||||
`Portal._submit_for_result/_expect_result_ctx/
|
|
||||||
wait_for_result/result`, `exhaust_portal`,
|
|
||||||
`cancel_on_completion`, `NoResult` — net -402 lines. The
|
|
||||||
reap-hang class dissolves structurally (result-waits now only
|
|
||||||
in caller task-scope).
|
|
||||||
- found + fixed a real migration race: mutual-rendezvous peers
|
|
||||||
(`test_trynamic_trio`, `a_trynamic_first_scene.py`) flaked
|
|
||||||
because an eagerly-reaped one-shot dies while its peer still
|
|
||||||
dials the registry-resolved (dead) sockaddr — such peers now
|
|
||||||
pin lifetimes via `start_actor()` + concurrent `Portal.run()`
|
|
||||||
+ explicit `an.cancel()`.
|
|
||||||
- `an: ActorNursery` naming sweep across tests/examples (±82
|
|
||||||
lines, scoped renames, prose untouched).
|
|
||||||
- parked a `to_actor.open_one_shot()` design sketch (acm +
|
|
||||||
private task-nursery over blocking `run()`; done-Event as
|
|
||||||
memo not cancel-relay; no Portal) in the plan doc.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
See commits `d01a2123..ad42871e` on `drop_ria_nursery`
|
|
||||||
(tests, examples, docs, `tractor/{runtime,spawn,to_actor,msg}`
|
|
||||||
+ `_exceptions/_context/experimental`).
|
|
||||||
|
|
@ -1,39 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-fable-5
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-07-06T17:28:18Z
|
|
||||||
git_ref: ad42871e
|
|
||||||
diff_cmd: git diff ba4af0ad..ad42871e
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw AI output (diff-ref mode)
|
|
||||||
|
|
||||||
This session's output spans the 16 migration/excision commits
|
|
||||||
`d01a2123..ad42871e` on `drop_ria_nursery`; per diff-ref mode
|
|
||||||
the verbatim content is reachable via the pointer below.
|
|
||||||
|
|
||||||
## Generated files
|
|
||||||
|
|
||||||
> `git diff ba4af0ad..ad42871e`
|
|
||||||
|
|
||||||
Commit-wise (each `Gate:`-footed msg documents its own module
|
|
||||||
gate):
|
|
||||||
|
|
||||||
- `d01a2123` port `test_some_cancels_all`
|
|
||||||
- `697c6152` fix unbound `timeout` (non-trio/MTF `match` arm)
|
|
||||||
- `fa8799d5` port `test_nested_multierrors`
|
|
||||||
- `f11754ce` port SIGINT + sync-sleep cancel tests
|
|
||||||
- `cb6202e3` port `test_dynamic_pub_sub`
|
|
||||||
- `d8af5f12` port non-debugging examples
|
|
||||||
- `a3057cb2` port debugging examples (+ `test_debugger`
|
|
||||||
nested-nurseries final-shape expectations)
|
|
||||||
- `d6bed7c4` port docs (8 rst pages)
|
|
||||||
- `07e1669e` fix stale `@pub` docstring example
|
|
||||||
- `2a59cefb` REMOVE `run_in_actor()` + the ria reap cluster
|
|
||||||
(net -402 lines)
|
|
||||||
- `a297a32a` fix mutual-rendezvous premature-reap race
|
|
||||||
- `ad42871e` `an: ActorNursery` naming sweep
|
|
||||||
|
|
||||||
Plan/design record updated in
|
|
||||||
`ai/conc-anal/ria_nursery_removal_plan.md` (RESOLVED section +
|
|
||||||
the `to_actor.open_one_shot()` follow-up sketch).
|
|
||||||
|
|
@ -1,136 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-5
|
|
||||||
service: claude
|
|
||||||
session: 7b9c97c4-fff7-4ac4-97fb-35720453308e
|
|
||||||
timestamp: 2026-08-13T00:11:02Z
|
|
||||||
git_ref: 27c34aeb
|
|
||||||
scope: docs+code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260813T001102Z_27c34aeb_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
> draft hyper detailed implementation plans for [three]
|
|
||||||
> prospective new transport (tpt) backends for tractor's `.ipc`
|
|
||||||
> layer, from four GitHub issues: TIPC (gh #378) using built-in
|
|
||||||
> linux socket API w/ `trio` interfacing, leveraging TIPC's
|
|
||||||
> built-in discovery machinery; QUIC (gh #353) using the `iroh`
|
|
||||||
> lib, ideally with the py asyncio support (via ffi) rewritten
|
|
||||||
> for trio; wg (gh #482 and/or #443) with other shuttle-able
|
|
||||||
> tpts, using `pyroute2`, as much trio wrapping as possible
|
|
||||||
> where any other async support can be replaced.
|
|
||||||
|
|
||||||
With constraints: "be only slightly speculative"; realistic given
|
|
||||||
the linked info; the plans must be workable "by another
|
|
||||||
model/provider without much discrepancy on the design or lib
|
|
||||||
selections needed"; do it all in a new `/open-wkt` off main; and
|
|
||||||
be "as modular and modern-async-python-as-nearly-functional-style
|
|
||||||
as possible."
|
|
||||||
|
|
||||||
Key follow-up prompts that changed the design mid-session:
|
|
||||||
|
|
||||||
> wg requires binding a socket on both ends of the tunnel, the
|
|
||||||
> new support we added to `py-multiaddr` in their #108 enables
|
|
||||||
> declaring this in the maddr? […] so the
|
|
||||||
> `/ip4/10.0.0.1/udp/666/ip4/192.168.0.13/tcp/80` bullet example
|
|
||||||
> from #443 isn't correct for a wg tunnel maddr and would
|
|
||||||
> actually end up looking like,
|
|
||||||
> `/ip4/10.0.0.1/udp/666/wg/<pub-key>/ip4/192.168.0.13/tcp/80` no?
|
|
||||||
|
|
||||||
> right, we're likely going to need less `tuple`-formed
|
|
||||||
> `UnwrappedAddress` usage to make them all work and/or to extend
|
|
||||||
> the unwrapped form with a proto-str, likely the key from
|
|
||||||
> `multiaddrs` no?
|
|
||||||
|
|
||||||
> better encapsulating `UnwrappedAddress` for use externally is
|
|
||||||
> really way overdue; we should likely be encouraging (if not
|
|
||||||
> preventing unwrapped) wrapped addrs always much like other
|
|
||||||
> (std) libs, `ipaddress` comes to mind.
|
|
||||||
|
|
||||||
> so iirc netns mgmt becomes a lower-level runtime config-api
|
|
||||||
> rather then an actor-app-code API which can be dynamically
|
|
||||||
> changed once the actor is up ya?
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
A research-and-planning branch, `ng_tpts_planning` — **no runtime
|
|
||||||
code touched**. Five plan docs under `ai/tpt-backends/` plus a
|
|
||||||
corrected `wg` example set under `examples/multihost/wg_lan/`,
|
|
||||||
across 9 commits.
|
|
||||||
|
|
||||||
Three design conclusions came out of the planning that outlive
|
|
||||||
the branch:
|
|
||||||
|
|
||||||
1. **`wg` is a bindspace, not a `MsgTransport`.** The `/wg/`
|
|
||||||
maddr segment is *infix*: bearer (underlay ip+udp
|
|
||||||
`ListenPort`, bound by the kernel) → `/wg/u<key>` (an
|
|
||||||
identity, bound by nothing) → overlay (the only part tractor
|
|
||||||
binds). Verified empirically by installing
|
|
||||||
`baudco/py-multiaddr@wg_support` (py-multiaddr#108) in a
|
|
||||||
throwaway venv and round-tripping each candidate form; gh
|
|
||||||
#482's original suffix form parses but is semantically
|
|
||||||
inverted.
|
|
||||||
2. **Proto-key the `UnwrappedAddress` form**, spelled with the
|
|
||||||
`multiaddr` protocol names, dispatched via
|
|
||||||
`_address_types[addr[0]]`. Kills a whole collision class
|
|
||||||
(TIPC's `(str, int)` ≡ `TCPAddress`; iroh's `(str, str)`
|
|
||||||
swallowed by the UDS case) and is the recommended migration
|
|
||||||
*before* any new backend lands.
|
|
||||||
3. **netns is a runtime/boot-time config API, not an app-code
|
|
||||||
one** — `setns(2)` is per-thread and won't move
|
|
||||||
already-created sockets, so there is deliberately no
|
|
||||||
`await actor.enter_netns(...)`.
|
|
||||||
|
|
||||||
Also verified that `trio.SocketStream`/`SocketListener` are
|
|
||||||
address-family agnostic (no `AF_*` check anywhere), which is what
|
|
||||||
makes TIPC the cheapest of the three backends to add.
|
|
||||||
|
|
||||||
Four related issues were annotated with the results (#378, #353,
|
|
||||||
#482, #443); #443's body was rewritten to reflect the corrected
|
|
||||||
grammar, with no existing checkbox state changed.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `ai/tpt-backends/00_shared_backend_contract.md` — normative
|
|
||||||
backend duck-type contract, registration checklist, §1.1
|
|
||||||
proto-key conclusion
|
|
||||||
- `ai/tpt-backends/01_tipc_backend.md` — TIPC plan; service
|
|
||||||
addressing, `TIPC_TOP_SRV` push registry, instance-collision
|
|
||||||
hazard, step-0 probe
|
|
||||||
- `ai/tpt-backends/02_quic_iroh_backend.md` — `iroh` plan;
|
|
||||||
`uniffi`→`trio` bridge, listener/stream adapters, API-truth
|
|
||||||
table
|
|
||||||
- `ai/tpt-backends/03_wg_tunnel_bindspace.md` — `wg`-as-bindspace
|
|
||||||
plan; verified maddr grammar, 3-owner split, netns reality
|
|
||||||
- `ai/tpt-backends/README.md` — index
|
|
||||||
- `examples/multihost/wg_lan/wg_maddr.py` — frozen `msgspec`
|
|
||||||
tunnelled addr + pure parse/render helpers; impure
|
|
||||||
`verify_wg_peer()` kept separate
|
|
||||||
- `examples/multihost/wg_lan/host_a_srv.py` — host-A actor tree
|
|
||||||
- `examples/multihost/wg_lan/host_b_client.py` — host-B dialer
|
|
||||||
- `examples/multihost/wg_lan/README.md` — grammar, owner table,
|
|
||||||
setup, "what changed vs #482"
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
Substantial human steering rather than post-hoc editing; the
|
|
||||||
corrections were applied by the model in-session after being
|
|
||||||
challenged:
|
|
||||||
|
|
||||||
- rejected an initial claim that `wg` has "nothing to bind at the
|
|
||||||
tunnel layer" and supplied the correct composed maddr form,
|
|
||||||
which forced a rewrite of plan 03 §3.2 and a retraction in the
|
|
||||||
already-posted #443 comment
|
|
||||||
- rejected a supporting claim that `/ip4/../udp/443/quic-v1` was
|
|
||||||
"also composed"
|
|
||||||
- directed the proto-key/`ipaddress`-discipline conclusion and
|
|
||||||
the netns-as-runtime-config framing, both of which were then
|
|
||||||
folded back into the docs
|
|
||||||
- chose the commit boundaries and authored all commits; ran every
|
|
||||||
`git` mutation (commit, rebase, push) themselves
|
|
||||||
|
|
||||||
One model-initiated correction pre-publication: a self-review
|
|
||||||
downgraded two overconfident claims (the `uniffi`/asyncio thesis
|
|
||||||
and TIPC duplicate-binder behaviour) to explicitly-flagged
|
|
||||||
assumptions before the #353/#378 comments were posted.
|
|
||||||
|
|
@ -1,165 +0,0 @@
|
||||||
---
|
|
||||||
model: claude-opus-5
|
|
||||||
service: claude
|
|
||||||
timestamp: 2026-08-13T00:11:02Z
|
|
||||||
git_ref: 27c34aeb
|
|
||||||
diff_cmd: git diff main..ng_tpts_planning
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output — next-gen tpt-backend implementation plans
|
|
||||||
|
|
||||||
## Generated planning docs
|
|
||||||
|
|
||||||
> `git diff main..ng_tpts_planning -- ai/tpt-backends/`
|
|
||||||
|
|
||||||
Five markdown docs. `00_shared_backend_contract.md` is normative
|
|
||||||
and the other three are written against it so they can be worked
|
|
||||||
independently:
|
|
||||||
|
|
||||||
- **`00_shared_backend_contract.md`** — the backend duck-type
|
|
||||||
(`<Proto>Address(msgspec.Struct, frozen=True)` + module-level
|
|
||||||
`start_listener()`/`close_listener()` + a
|
|
||||||
`Msgpack<Proto>Stream(MsgpackTransport)`), the
|
|
||||||
`inspect.getmodule(self.addr)` reflection in
|
|
||||||
`Endpoint.start_listener()` that forces the Address class and
|
|
||||||
its listener fns to share a module, a 10-item registration
|
|
||||||
checklist, the dep policy, the test-harness shape, and §1.1's
|
|
||||||
proto-key conclusion (below).
|
|
||||||
- **`01_tipc_backend.md`** — service addressing via
|
|
||||||
`TIPC_ADDR_NAMESEQ` (bind/publish) and `TIPC_ADDR_NAME`
|
|
||||||
(connect/lookup), `TIPC_TOP_SRV` topology subscriptions as a
|
|
||||||
push-based registry, the `get_random()` instance-collision
|
|
||||||
hazard, and a step-0 capability-probe spike.
|
|
||||||
- **`02_quic_iroh_backend.md`** — `iroh` over
|
|
||||||
`aioquic`/`quiche`/`trio-asyncio`, a `_uniffi_trio.py` bridge
|
|
||||||
built on `TrioToken.run_sync_soon()`, `trio.abc.Listener`/
|
|
||||||
`HalfCloseableStream` adapters, and an API-truth table to fill
|
|
||||||
in during step 0.
|
|
||||||
- **`03_wg_tunnel_bindspace.md`** — `wg` as a *bindspace* rather
|
|
||||||
than a `MsgTransport`, a `TunnelledAddress` wrapper delegating
|
|
||||||
`.proto_key`/`.unwrap()` to `.inner`, `pyroute2` for layer B,
|
|
||||||
and `@acm`-managed netns/iface for layer C.
|
|
||||||
- **`README.md`** — index.
|
|
||||||
|
|
||||||
## Generated example code
|
|
||||||
|
|
||||||
> `git diff main..ng_tpts_planning -- examples/multihost/wg_lan/`
|
|
||||||
|
|
||||||
- `wg_maddr.py` — `WGTunnelledAddr(msgspec.Struct, frozen=True)`
|
|
||||||
carrying `bearer: tuple[str, int]`, `peer_pubkey: str`,
|
|
||||||
`inner: tuple[str, int]`, `inner_proto: Literal['tcp']`, plus a
|
|
||||||
`.maddr` property that re-renders the canonical form. Pure
|
|
||||||
helpers `mb_pubkey()`, `wg8_pubkey()`, `parse_wg_maddr()`, and
|
|
||||||
`_segments()` (with a marked stopgap for when the `wg` codec
|
|
||||||
isn't installed). `verify_wg_peer()` is impure **by design** and
|
|
||||||
kept out of the parse path.
|
|
||||||
- `host_a_srv.py` / `host_b_client.py` — the two-host runs; both
|
|
||||||
pass only `addr.inner` to `open_nursery()`/`open_root_actor()`.
|
|
||||||
- `README.md` — grammar, owner table, `#108`-branch install line,
|
|
||||||
tunnel setup, "what changed vs #482".
|
|
||||||
|
|
||||||
## Verified findings (non-code, verbatim)
|
|
||||||
|
|
||||||
### `trio` is address-family agnostic
|
|
||||||
|
|
||||||
Read against the installed `trio`. `SocketStream`/`SocketListener`
|
|
||||||
ctor checks are only "is a trio sock object" + `type ==
|
|
||||||
SOCK_STREAM`, plus an `OSError`-**suppressed** `SO_ACCEPTCONN`
|
|
||||||
probe. No `AF_*` check anywhere; `TCP_NODELAY`/`TCP_NOTSENT_LOWAT`
|
|
||||||
are set under `suppress(OSError)`. A TIPC `SOCK_STREAM` sock should
|
|
||||||
therefore drop straight into `trio.serve_listeners()` with the
|
|
||||||
existing `MsgpackTransport` framing, making TIPC mostly
|
|
||||||
table-registration boilerplate w/ zero new deps.
|
|
||||||
|
|
||||||
### the `wg` maddr grammar — `/wg/` is infix, not suffix
|
|
||||||
|
|
||||||
Installed `baudco/py-multiaddr@wg_support` (PR
|
|
||||||
multiformats/py-multiaddr#108) into a throwaway venv and
|
|
||||||
round-tripped every candidate form:
|
|
||||||
|
|
||||||
| maddr | `[p.name for p in m.protocols()]` |
|
|
||||||
| --- | --- |
|
|
||||||
| `/ip4/1.2.3.4/udp/51820/wg/u<k>` | `['ip4','udp','wg']` |
|
|
||||||
| `/ip4/../udp/../wg/u<k>/ip4/../tcp/..` | `['ip4','udp','wg','ip4','tcp']` |
|
|
||||||
| `/ip4/10.0.11.1/tcp/1616/wg/u<k>` | `['ip4','tcp','wg']` |
|
|
||||||
|
|
||||||
```
|
|
||||||
/ip4/192.168.1.50/udp/51820/wg/u<A_pub>/ip4/10.0.11.1/tcp/1616
|
|
||||||
\_______ bearer __________/\__ key __/\______ overlay ______/
|
|
||||||
```
|
|
||||||
|
|
||||||
Segments *before* `/wg/` are the bearer — the underlay
|
|
||||||
`(ip, udp-port)` that `wg(8)` itself listens on (`ListenPort`).
|
|
||||||
Segments *after* are the overlay endpoint, the only part tractor
|
|
||||||
binds. The third row above is #482's original suffix form: it
|
|
||||||
parses, but is semantically inverted.
|
|
||||||
|
|
||||||
Three parts, three owners — and only one is an `Endpoint`:
|
|
||||||
|
|
||||||
| part | bound by | in the runtime? |
|
|
||||||
| --- | --- | --- |
|
|
||||||
| bearer | kernel, via `wg-quick`/`pyroute2` | no |
|
|
||||||
| `/wg/u<key>` | nothing — an identity | no, verified out-of-band |
|
|
||||||
| overlay | `tractor`'s `IPCServer` | yes, as `.inner` |
|
|
||||||
|
|
||||||
### proto-key-tagged `UnwrappedAddress`
|
|
||||||
|
|
||||||
Shape-matching in `wrap_address()` does not survive four backends.
|
|
||||||
TIPC's natural unwrapped form is a `(str, int)`, indistinguishable
|
|
||||||
from `TCPAddress`; iroh's is a `(str, str)`, already swallowed by
|
|
||||||
the existing UDS case (`case (_, filename) if type(filename) is
|
|
||||||
str`). Ordering hacks and prefix-tagging only paper over it.
|
|
||||||
|
|
||||||
Recommended prerequisite for all three backends: carry an explicit
|
|
||||||
proto-key spelled with the `multiaddr` protocol name —
|
|
||||||
`('tcp', host, port)`, `('unix', path)`,
|
|
||||||
`('tipc', stype, inst, scope)` — so `wrap_address()` collapses to
|
|
||||||
`_address_types[addr[0]]` and the collision class stops existing.
|
|
||||||
This also makes the on-wire form agree with
|
|
||||||
`mk_maddr()`/`parse_maddr()` instead of being an independent
|
|
||||||
invention. It is a wire-format change (`SpawnSpec`,
|
|
||||||
`_root_mailbox`, `_registry_addrs`) plus every fixture and
|
|
||||||
downstream config, so it wants its own migration commit landed
|
|
||||||
before any new backend — and it is the moment to stop handing raw
|
|
||||||
tuples to users at all, making `Address` the public currency and
|
|
||||||
`UnwrappedAddress` an internal serialization detail (the
|
|
||||||
discipline `ipaddress` uses).
|
|
||||||
|
|
||||||
### netns is a runtime-level config API
|
|
||||||
|
|
||||||
`setns(2)` affects the calling thread only and does not move
|
|
||||||
already-created sockets. So a netns is a spawn/boot-time input
|
|
||||||
alongside `enable_transports`/`tpt_bind_addrs`, and there is
|
|
||||||
deliberately no `await actor.enter_netns(...)` — a mid-life API
|
|
||||||
would silently leave the IPC server bound in the old namespace.
|
|
||||||
Corollary for layer B: pass `netns=` down to `pyroute2` rather
|
|
||||||
than assuming a `trio.to_thread` worker inherits it.
|
|
||||||
|
|
||||||
### `examples/` collection would have failed CI
|
|
||||||
|
|
||||||
`tests/test_docs_examples.py` walks `examples/` recursively and
|
|
||||||
subproc-runs every collected file asserting `rc == 0`. Its filter
|
|
||||||
never checks the extension, so all four `wg_lan` files were
|
|
||||||
collected — including `README.md`, which would have been run as
|
|
||||||
`python README.md`. `'multihost' not in p[0]` was already in the
|
|
||||||
exclusion list with no directory using it. Moving the set under
|
|
||||||
`examples/multihost/wg_lan/` drops collection 24 → 20 with zero
|
|
||||||
test changes; confirmed via `pytest --collect-only`.
|
|
||||||
|
|
||||||
## Corrections applied during the session
|
|
||||||
|
|
||||||
The human corrected two claims that had been asserted without
|
|
||||||
verification, both since retracted in-place in the docs and in the
|
|
||||||
posted issue comments:
|
|
||||||
|
|
||||||
1. that `wg` has "nothing to bind at the tunnel layer, exactly one
|
|
||||||
bind" — wrong; a wg stack is genuinely composed, and the real
|
|
||||||
axis is *who owns* each layer's endpoint.
|
|
||||||
2. that `/ip4/../udp/443/quic-v1` was "also composed" — wrong;
|
|
||||||
that is one endpoint with a protocol qualifier, not a tunnel.
|
|
||||||
|
|
||||||
A self-review before publication also downgraded two
|
|
||||||
overconfident claims to explicitly-flagged assumptions: the
|
|
||||||
`uniffi`-uses-asyncio-only-as-executor thesis (contradicted that
|
|
||||||
plan's own "do not guess from memory" step 0) and TIPC's
|
|
||||||
duplicate-binder round-robin behaviour (unverified).
|
|
||||||
|
|
@ -1,27 +0,0 @@
|
||||||
# AI Prompt I/O Log — claude
|
|
||||||
|
|
||||||
This directory tracks prompt inputs and model
|
|
||||||
outputs for AI-assisted development using
|
|
||||||
`claude` (Claude Code).
|
|
||||||
|
|
||||||
## Policy
|
|
||||||
|
|
||||||
Prompt logging follows the
|
|
||||||
[NLNet generative AI policy][nlnet-ai].
|
|
||||||
All substantive AI contributions are logged
|
|
||||||
with:
|
|
||||||
- Model name and version
|
|
||||||
- Timestamps
|
|
||||||
- The prompts that produced the output
|
|
||||||
- Unedited model output (`.raw.md` files)
|
|
||||||
|
|
||||||
[nlnet-ai]: https://nlnet.nl/foundation/policies/generativeAI/
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
Entries are created by the `/prompt-io` skill
|
|
||||||
or automatically via `/commit-msg` integration.
|
|
||||||
|
|
||||||
Human contributors remain accountable for all
|
|
||||||
code decisions. AI-generated content is never
|
|
||||||
presented as human-authored work.
|
|
||||||
|
|
@ -1,39 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: moc-teardown-completion-20260804
|
|
||||||
timestamp: 2026-08-04T03:03:09Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260804T030309Z_65bf9df5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Patch Tractor's `maybe_open_context()` so the final consumer waits for
|
|
||||||
resource `__aexit__()` completion and receives cleanup errors. Reuse
|
|
||||||
`outcome.Outcome` for the exit result; use the smaller mutable
|
|
||||||
`_CtxExit` holder if that makes the implementation simpler. Add and run
|
|
||||||
the relevant existing unit tests, but do not commit or push the patch.
|
|
||||||
After reviewing the result, simplify `_CtxExit` back to an optional
|
|
||||||
exception because the success outcome carries no useful value.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Added an exception-backed completion handshake between
|
|
||||||
`_Cache.run_ctx()` and the final `maybe_open_context()` consumer.
|
|
||||||
Serialized consumer registration and final teardown under the per-key
|
|
||||||
lock, preserving that lock for queued entrants. Added deterministic
|
|
||||||
regressions for normal exit, cleanup errors, cancellation interactions,
|
|
||||||
service-nursery cancellation, and teardown re-entry.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/trionics/_mngrs.py` - publish and unwrap cached exit outcomes.
|
|
||||||
- `tests/test_resource_cache.py` - cover completion and cancellation.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The user directed the final simplification from `outcome.Outcome` to an
|
|
||||||
optional exception field. The patch remains uncommitted.
|
|
||||||
|
|
@ -1,36 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-04T03:03:09Z
|
|
||||||
git_ref: 65bf9df5
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Implemented cached-context exit completion in
|
|
||||||
`tractor.trionics.maybe_open_context()`.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/_mngrs.py`
|
|
||||||
|
|
||||||
The generated implementation adds `_CtxExit`, whose `done` event
|
|
||||||
publishes an `outcome.Outcome[None]`. `_Cache.run_ctx()` records either
|
|
||||||
`Value(None)` or `Error(exc)` after the resource exit attempt. The final
|
|
||||||
MOC consumer signals `no_more_users`, waits for completion under a
|
|
||||||
shielded cancel scope, removes the per-key lock, and unwraps the outcome
|
|
||||||
so ordinary cleanup failures are raised at the consumer boundary.
|
|
||||||
`trio.Cancelled`, `KeyboardInterrupt`, and `SystemExit` continue through
|
|
||||||
the service task rather than being converted into regular cleanup
|
|
||||||
errors.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_resource_cache.py`
|
|
||||||
|
|
||||||
The generated regressions cover successful exit blocking, cleanup-error
|
|
||||||
delivery, final-user cancellation, cancellation combined with a cleanup
|
|
||||||
error, and service-nursery cancellation. The existing teardown re-entry
|
|
||||||
test now uses explicit events instead of a ten-second cleanup sleep and
|
|
||||||
asserts that the replacement resource is a fresh cache miss.
|
|
||||||
|
|
||||||
Verification:
|
|
||||||
|
|
||||||
`env PYTHONPATH="$PWD" /home/goodboy/repos/tractor/py313/bin/python -m pytest tests/test_resource_cache.py`
|
|
||||||
|
|
||||||
Result: `16 passed in 8.37s`.
|
|
||||||
|
|
@ -1,30 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_0799212ebffe42arY96czXn89F
|
|
||||||
timestamp: 2026-08-11T23:38:33Z
|
|
||||||
git_ref: 7cbd64ee
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260811T233833Z_7cbd64ee_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Open a new isolated worktree in the local Tractor repository and draft a fix
|
|
||||||
for `BroadcastReceiver` reporting that a lagged one-slot consumer dropped
|
|
||||||
zero values when one value had actually been displaced.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Corrected the off-by-one lag count while preserving cursor recovery and added
|
|
||||||
deterministic narrow- and wider-window regressions for exact loss reporting.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/trionics/_broadcast.py` - exact broadcast overrun count.
|
|
||||||
- `tests/test_task_broadcasting.py` - lag count and recovery regression.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - generated output follows the user's diagnosed edge case.
|
|
||||||
|
|
@ -1,50 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-11T23:38:33Z
|
|
||||||
git_ref: 7cbd64ee
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
The user asked for a Tractor fix in a new isolated worktree after a live piker
|
|
||||||
failure reported:
|
|
||||||
|
|
||||||
```text
|
|
||||||
tractor.trionics._broadcast.Lagged:
|
|
||||||
Task `piker.brokers.ib.broker.handle_order_requests` overrun and
|
|
||||||
dropped `0` values
|
|
||||||
```
|
|
||||||
|
|
||||||
Inspection showed the lag exception was valid but its count was off by one.
|
|
||||||
`BroadcastReceiver.receive_nowait()` treats `seq` as a deque index. With a
|
|
||||||
one-entry queue, index zero is the only retained value and `seq == 1` already
|
|
||||||
means one value was displaced. The old `seq - maxlen` calculation therefore
|
|
||||||
reported zero instead of one.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/_broadcast.py`
|
|
||||||
|
|
||||||
Adjusted the lag count to `seq - maxlen + 1` and documented why the first
|
|
||||||
invalid deque index must be included. The existing Tokio-style cursor reset
|
|
||||||
remains unchanged.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_task_broadcasting.py`
|
|
||||||
|
|
||||||
Added a deterministic parameterized regression covering a one-slot queue
|
|
||||||
with one dropped value and a three-slot queue with two dropped values. The
|
|
||||||
test keeps the root receiver idle while a child subscriber synchronously
|
|
||||||
drains each produced value, asserts the exact `Lagged` message, and proves the
|
|
||||||
next receive resumes at the oldest retained item.
|
|
||||||
|
|
||||||
Verification output:
|
|
||||||
|
|
||||||
```text
|
|
||||||
.. [100%]
|
|
||||||
2 passed in 0.04s
|
|
||||||
|
|
||||||
.......... [100%]
|
|
||||||
10 passed in 4.65s
|
|
||||||
```
|
|
||||||
|
|
||||||
The targeted import resolved to the new Tractor worktree. Python compilation
|
|
||||||
and `git diff --check` passed. Adversarial review found no actionable issues;
|
|
||||||
zero-capacity channels remain a pre-existing untested edge outside this fix.
|
|
||||||
|
|
@ -1,31 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_0799212ebffe42arY96czXn89F
|
|
||||||
timestamp: 2026-08-12T01:23:24Z
|
|
||||||
git_ref: 06c4af17
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260812T012324Z_06c4af17_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Iteratively refine Tractor PR 490. For item one, correct broadcast statistics
|
|
||||||
queue counts and Trio event checks, verify and review the exact change, then
|
|
||||||
return a complete commit plan before proceeding.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Converted subscriber cursor indexes into clamped retained queue counts,
|
|
||||||
removed deprecated event truthiness, and added deterministic state and
|
|
||||||
deprecation regressions.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/trionics/_broadcast.py` - accurate queue and waiter statistics.
|
|
||||||
- `tests/test_task_broadcasting.py` - retained-count and event regression.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - generated output follows the requested first iterative item.
|
|
||||||
|
|
@ -1,37 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-12T01:23:24Z
|
|
||||||
git_ref: 06c4af17
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
After opening draft Tractor PR 490, the user requested an iterative pass over
|
|
||||||
additional broadcast subsystem findings. The first item was to correct
|
|
||||||
`BroadcastState.statistics()` queued counts and its deprecated Trio event
|
|
||||||
truthiness check, then stop for a complete commit plan.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/_broadcast.py`
|
|
||||||
|
|
||||||
Changed `queued_len_by_task` from raw deque cursor indexes to retained,
|
|
||||||
receivable counts. Caught-up `-1` reports zero, valid indexes report index plus
|
|
||||||
one, and lagged cursors clamp to the current retained queue length. Replaced
|
|
||||||
`trio.Event` truthiness with an explicit `is not None` branch.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_task_broadcasting.py`
|
|
||||||
|
|
||||||
Added a deterministic statistics regression using actual sends and receives.
|
|
||||||
It verifies caught-up and one-queued states, drives a root receiver beyond a
|
|
||||||
three-slot retention window to prove clamping, and installs a real
|
|
||||||
`trio.Event` while treating deprecations as errors.
|
|
||||||
|
|
||||||
Verification output:
|
|
||||||
|
|
||||||
```text
|
|
||||||
........... [100%]
|
|
||||||
11 passed in 5.76s
|
|
||||||
```
|
|
||||||
|
|
||||||
Python compilation and `git diff --check` passed. Initial adversarial review
|
|
||||||
caught unclamped lagged cursors and an ineffective event test; both were
|
|
||||||
fixed. Final review found no actionable issues.
|
|
||||||
|
|
@ -1,33 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_0799212ebffe42arY96czXn89F
|
|
||||||
timestamp: 2026-08-12T03:06:08Z
|
|
||||||
git_ref: 1095e7f7
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260812T030608Z_1095e7f7_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
For Tractor PR 490 item two, make shared underlying receive failures wake and
|
|
||||||
terminate every broadcast subscriber without losing retained values. Review,
|
|
||||||
verify and return a complete commit plan before continuing.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Published ordinary receive failures as terminal broadcast state, introduced
|
|
||||||
a public chained peer exception, kept control-flow exits transient while
|
|
||||||
waking peers, documented the contract, and added deterministic regressions.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/trionics/_broadcast.py` - terminal failure and peer wake protocol.
|
|
||||||
- `tractor/trionics/__init__.py` - public peer exception export.
|
|
||||||
- `docs/api/trionics.rst` - failure-delivery API contract.
|
|
||||||
- `tests/test_task_broadcasting.py` - terminal and transient failure tests.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - generated output follows the requested second iterative item.
|
|
||||||
|
|
@ -1,49 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-12T03:06:08Z
|
|
||||||
git_ref: 1095e7f7
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
The user requested the second iterative refinement for Tractor PR 490: ensure
|
|
||||||
non-EOC failures from a shared underlying broadcast receiver do not leave peer
|
|
||||||
subscribers blocked forever, then stop for a complete commit plan.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/_broadcast.py`
|
|
||||||
|
|
||||||
Added shared terminal failure publication for ordinary `Exception` values.
|
|
||||||
The receive owner gets the original exception; peers may drain retained
|
|
||||||
values and then get a fresh `BroadcastReceiveError` chained from the original.
|
|
||||||
Late subscribers observe the same terminal state without retrying the failed
|
|
||||||
underlying receiver. Process-control and cancellation-like `BaseException`
|
|
||||||
values wake peers but are re-raised without becoming durable channel state.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/__init__.py`
|
|
||||||
|
|
||||||
Exported `BroadcastReceiveError` as the public peer-delivery exception.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- docs/api/trionics.rst`
|
|
||||||
|
|
||||||
Documented `BroadcastReceiveError` and the owner-versus-peer delivery
|
|
||||||
contract, including retained-value draining and late subscribers.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_task_broadcasting.py`
|
|
||||||
|
|
||||||
Added deterministic bounded regressions. One scripts a successful receive
|
|
||||||
followed by `RuntimeError`, proving the root drains retained data, all current
|
|
||||||
and late receivers observe terminal failure, and the source is not retried.
|
|
||||||
The second scripts a custom `BaseException`, proving peers wake and take over
|
|
||||||
the next source receive without retaining control-flow state.
|
|
||||||
|
|
||||||
Verification output:
|
|
||||||
|
|
||||||
```text
|
|
||||||
............. [100%]
|
|
||||||
13 passed in 5.62s
|
|
||||||
```
|
|
||||||
|
|
||||||
Python compilation and `git diff --check` passed. Iterative adversarial review
|
|
||||||
drove independent peer exception wrappers, ordinary-versus-control-flow
|
|
||||||
classification, bounded test completion, public docs, and the final catch-all
|
|
||||||
peer wake. Final review found no issues.
|
|
||||||
|
|
@ -1,33 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_0799212ebffe42arY96czXn89F
|
|
||||||
timestamp: 2026-08-12T15:00:27Z
|
|
||||||
git_ref: c2a6ccef
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260812T150027Z_c2a6ccef_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
For Tractor PR 490 item three, prevent subscriber closure from waking another
|
|
||||||
receiver's shared event or stranding peers. Preserve close-safe source-read
|
|
||||||
ownership handoff, then review, verify and return a complete commit plan.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Introduced receiver-local wait/source cancellation, owner-specific handoff,
|
|
||||||
and close precedence over shielded source values/errors/EOC. Clarified that
|
|
||||||
private scope cancellation means explicit close while outer task cancellation
|
|
||||||
remains `trio.Cancelled` for both source-read and peer-wait scopes, with
|
|
||||||
deterministic receiver-close regressions.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/trionics/_broadcast.py` - receiver-local close and ownership scopes.
|
|
||||||
- `tests/test_task_broadcasting.py` - peer close and owner handoff regressions.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - generated output follows the requested third iterative item.
|
|
||||||
|
|
@ -1,51 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-12T15:00:27Z
|
|
||||||
git_ref: c2a6ccef
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
The user requested the third iterative refinement for Tractor PR 490: closing
|
|
||||||
one broadcast subscriber must not set another receiver owner's shared event
|
|
||||||
and create a runnable hot loop, then stop for a complete commit plan.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/_broadcast.py`
|
|
||||||
|
|
||||||
Added receiver-local wait cancellation and source-read ownership scopes.
|
|
||||||
Closing a non-owner waiting behind another source reader cancels only that
|
|
||||||
receiver's private wait and maps it to `ClosedResourceError`; the shared event
|
|
||||||
remains untouched. Closing the active source owner cancels only its private
|
|
||||||
source-read scope, wakes peers after cleanup, and lets one peer take ownership.
|
|
||||||
|
|
||||||
Source outcomes are captured inside the owner scope and classified only after
|
|
||||||
checking close/cancel state. A cancellation-shielding source therefore cannot
|
|
||||||
publish a returned value, ordinary error, or EOC after its owner was closed.
|
|
||||||
The private scope's `cancel_called` bit is asserted to imply receiver closure;
|
|
||||||
outer task cancellation remains `trio.Cancelled` and is not translated into
|
|
||||||
`ClosedResourceError`. Owner-key comments document that only the receiver
|
|
||||||
identified by `recv_ready[0]` may cancel the shared source-read scope. The
|
|
||||||
same explicit-close invariant is enforced symmetrically for private peer-wait
|
|
||||||
scope cancellation.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_task_broadcasting.py`
|
|
||||||
|
|
||||||
Added deterministic bounded regressions for both close positions. The
|
|
||||||
non-owner test places two peers behind an active source read, closes one and
|
|
||||||
proves only that peer exits while the shared event stays unset. The owner test
|
|
||||||
closes a source owner whose receive shields cancellation and parameterizes a
|
|
||||||
returned value, `RuntimeError`, and `EndOfChannel`; each discarded outcome
|
|
||||||
hands the next source receive to the waiting root without terminal-state or
|
|
||||||
EOC publication.
|
|
||||||
|
|
||||||
Verification output:
|
|
||||||
|
|
||||||
```text
|
|
||||||
................. [100%]
|
|
||||||
17 passed in 5.84s
|
|
||||||
```
|
|
||||||
|
|
||||||
Python compilation and `git diff --check` passed. Iterative adversarial review
|
|
||||||
caught a waiting non-owner hang, cancellation-shielded source returns, and
|
|
||||||
shielded source exceptions. All were fixed. Final review found no actionable
|
|
||||||
issues.
|
|
||||||
|
|
@ -1,34 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_0799212ebffe42arY96czXn89F
|
|
||||||
timestamp: 2026-08-12T21:31:17Z
|
|
||||||
git_ref: 51185487
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260812T213117Z_51185487_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
For Tractor PR 490 item four, expose `raise_on_lag` through the public IPC and
|
|
||||||
asyncio linked-channel subscription wrappers. Review, verify and return a
|
|
||||||
complete commit plan before applying the API downstream in piker.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Added public per-subscription lag policy to both wrappers, preserved first-call
|
|
||||||
root policy, documented the semantics, and covered forwarding plus real fan-out
|
|
||||||
paths.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/_streaming.py` - `MsgStream` lag policy forwarding.
|
|
||||||
- `tractor/to_asyncio.py` - linked-channel lag policy forwarding.
|
|
||||||
- `docs/guide/streaming.rst` - IPC fan-out policy docs.
|
|
||||||
- `docs/guide/asyncio.rst` - linked-channel fan-out policy docs.
|
|
||||||
- `tests/test_task_broadcasting.py` - wrapper policy regression.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - generated output follows the requested fourth iterative item.
|
|
||||||
|
|
@ -1,53 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-12T21:31:17Z
|
|
||||||
git_ref: 51185487
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
The user requested the fourth iterative refinement for Tractor PR 490: expose
|
|
||||||
subscriber lag policy through the public `MsgStream.subscribe()` and
|
|
||||||
`LinkedTaskChannel.subscribe()` wrappers, then stop for a complete commit
|
|
||||||
plan. This enables piker to replace private receiver mutation.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/_streaming.py`
|
|
||||||
|
|
||||||
Added `raise_on_lag: bool = True` to `MsgStream.subscribe()`. The first call
|
|
||||||
passes the policy to the irreversibly allocated root broadcaster and its
|
|
||||||
child; later calls configure each child independently while retaining the
|
|
||||||
root's first-call policy.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/to_asyncio.py`
|
|
||||||
|
|
||||||
Added equivalent lag-policy forwarding to `LinkedTaskChannel.subscribe()`.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- docs/guide/streaming.rst`
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- docs/guide/asyncio.rst`
|
|
||||||
|
|
||||||
Documented strict versus warn/drop/resume behavior, independent child policy,
|
|
||||||
and first-call root policy for both wrapper types.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_task_broadcasting.py`
|
|
||||||
|
|
||||||
Added a parameterized wrapper-level regression using minimal receive-compatible
|
|
||||||
handles. It verifies a first non-raising subscription configures root and
|
|
||||||
child, then a later strict child does not mutate the sticky root policy.
|
|
||||||
|
|
||||||
Verification output:
|
|
||||||
|
|
||||||
```text
|
|
||||||
................... [100%]
|
|
||||||
19 passed in 5.71s
|
|
||||||
|
|
||||||
.................... [100%]
|
|
||||||
20 passed in 6.88s
|
|
||||||
|
|
||||||
. [100%]
|
|
||||||
1 passed in 0.86s
|
|
||||||
```
|
|
||||||
|
|
||||||
The second and third runs cover actual `MsgStream` and infected-asyncio
|
|
||||||
`LinkedTaskChannel` fan-out respectively. Python compilation and
|
|
||||||
`git diff --check` passed. Adversarial review found no actionable issues.
|
|
||||||
|
|
@ -1,36 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: unavailable
|
|
||||||
timestamp: 2026-08-13T18:19:01Z
|
|
||||||
git_ref: a2e0df4b
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260813T181901Z_a2e0df4b_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Continue Tractor PR 490 after the paired piker EMS consumer commit. Clean
|
|
||||||
cancelled-task diagnostics, define or reject zero-buffer broadcast behavior,
|
|
||||||
review and verify the change, then stop at a complete commit plan.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Bound cancellation diagnostics to receiver progress, terminal state and
|
|
||||||
resource lifetime; made EOC durable across peers; released wrapper-owned root
|
|
||||||
broadcasters without breaking graceful EOC or subclass overrides; and rejected
|
|
||||||
non-positive fan-out retention capacity.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/trionics/_broadcast.py` - diagnostic lifecycle, durable EOC and
|
|
||||||
buffer validation.
|
|
||||||
- `tractor/_streaming.py` - safe `MsgStream` root broadcaster cleanup.
|
|
||||||
- `tractor/to_asyncio.py` - linked-channel root broadcaster cleanup.
|
|
||||||
- `tests/test_task_broadcasting.py` - cancellation, EOC, wrapper and capacity
|
|
||||||
regressions.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - generated output follows the requested fifth iterative item.
|
|
||||||
|
|
@ -1,58 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-13T18:19:01Z
|
|
||||||
git_ref: a2e0df4b
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
The user asked to continue after committing the paired piker EMS consumer
|
|
||||||
fix. The next isolated Tractor PR 490 item was to clean cancelled-task
|
|
||||||
diagnostics and define zero-buffer broadcast behavior, then review, test and
|
|
||||||
stop at a complete commit plan.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/trionics/_broadcast.py`
|
|
||||||
|
|
||||||
Made `BroadcastState.cancelled` transient: receiver progress and close clear
|
|
||||||
that receiver's diagnostic, terminal EOC and shared receive failure clear all
|
|
||||||
stale cancelled tasks, and durable EOC prevents peers from re-entering the
|
|
||||||
closed source. `broadcast_receiver()` now rejects non-positive retention
|
|
||||||
capacity before creating an unusable zero-length deque.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/_streaming.py`
|
|
||||||
|
|
||||||
Made explicit `MsgStream.aclose()` release its internally allocated root
|
|
||||||
broadcaster while preserving graceful receive-internal EOC teardown. Used a
|
|
||||||
task-local marker so the public zero-argument `aclose()` signature and valid
|
|
||||||
subclass overrides remain compatible.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/to_asyncio.py`
|
|
||||||
|
|
||||||
Made `LinkedTaskChannel.aclose()` release its internally allocated root
|
|
||||||
broadcaster before closing the underlying Trio receive channel.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_task_broadcasting.py`
|
|
||||||
|
|
||||||
Added synchronized regressions for transient child cancellation diagnostics,
|
|
||||||
cross-receiver terminal cleanup, durable EOC peer wakeups, root broadcaster
|
|
||||||
cleanup through both public wrappers, `MsgStream.aclose()` subclass
|
|
||||||
compatibility, and zero-buffer rejection.
|
|
||||||
|
|
||||||
Verification output:
|
|
||||||
|
|
||||||
```text
|
|
||||||
........................... [100%]
|
|
||||||
27 passed in 5.89s
|
|
||||||
|
|
||||||
. [100%]
|
|
||||||
1 passed in 1.22s
|
|
||||||
|
|
||||||
. [100%]
|
|
||||||
1 passed in 0.88s
|
|
||||||
```
|
|
||||||
|
|
||||||
The integration runs cover real `MsgStream` actor fan-out and infected-asyncio
|
|
||||||
`LinkedTaskChannel` fan-out. Ruff, Python compilation and `git diff --check`
|
|
||||||
passed. Repeated adversarial review found and resolved root close re-entrancy,
|
|
||||||
cross-receiver terminal retention, durable-EOC and subclass-compatibility
|
|
||||||
issues; final review reported no findings.
|
|
||||||
|
|
@ -1,39 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: pr475-review-fixes-20260817
|
|
||||||
timestamp: 2026-08-17T23:18:25Z
|
|
||||||
git_ref: 359fe75c
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260817T231825Z_359fe75c_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Continue the `/code-review-changes` pass for PR #475 in its isolated
|
|
||||||
worktree. Address the seven accepted manual-review findings in
|
|
||||||
`tractor/ipc/_types.py` and `tractor/ipc/_uds.py`, preserve the existing
|
|
||||||
Windows capability behavior, verify the result, and prepare the work for
|
|
||||||
human-controlled commit and review-reply steps. Do not publish replies,
|
|
||||||
stage, commit, or push without the required explicit authorization.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Restored project quote, docstring, multiline-expression, and
|
|
||||||
`match/case` conventions while retaining the Windows-safe UDS guard.
|
|
||||||
Removed unnecessary structural and comment churn, then verified the
|
|
||||||
focused transport, discovery, and lazy-import paths plus the missing
|
|
||||||
`AF_UNIX` behavior.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/ipc/_types.py` - restore project style and guarded
|
|
||||||
socket-family dispatch.
|
|
||||||
- `tractor/ipc/_uds.py` - format the UDS capability gate
|
|
||||||
consistently.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - the generated patch remains uncommitted and awaits human
|
|
||||||
review.
|
|
||||||
|
|
@ -1,45 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-17T23:18:25Z
|
|
||||||
git_ref: 359fe75c
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Applied the seven accepted manual-review fixes for PR #475 while
|
|
||||||
preserving the Windows transport capability behavior.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/ipc/_types.py`
|
|
||||||
|
|
||||||
The generated changes restore the project's single-quote docstring and
|
|
||||||
string conventions, remove the unnecessary helper divider, simplify the
|
|
||||||
transport-registry comments, and restore `match/case` socket-family
|
|
||||||
dispatch. The UDS case retains a `HAS_UDS` guard that short-circuits
|
|
||||||
before `socket.AF_UNIX` is evaluated on unsupported hosts. Nearby error
|
|
||||||
messages are wrapped without changing their content.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/ipc/_uds.py`
|
|
||||||
|
|
||||||
The generated change reformats the `HAS_UDS` conjunction according to
|
|
||||||
the project's multiline boolean-expression convention and simplifies
|
|
||||||
the adjacent capability comment.
|
|
||||||
|
|
||||||
Verification:
|
|
||||||
|
|
||||||
`/home/goodboy/repos/tractor/py313/bin/pytest -q tests/test_lazy_imports.py tests/discovery tests/ipc/test_server.py`
|
|
||||||
|
|
||||||
Result: `66 passed, 2 xpassed in 60.62s`.
|
|
||||||
|
|
||||||
`ruff check --no-cache --output-format=json tractor/ipc/_types.py tractor/ipc/_uds.py`
|
|
||||||
|
|
||||||
Result: no findings.
|
|
||||||
|
|
||||||
`git diff --check`
|
|
||||||
|
|
||||||
Result: no whitespace errors.
|
|
||||||
|
|
||||||
An explicit missing-`AF_UNIX` probe set `HAS_UDS = False`, removed the
|
|
||||||
socket constant, and exercised an unsupported socket family. It raised
|
|
||||||
the expected `NotImplementedError` instead of `AttributeError`.
|
|
||||||
|
|
||||||
No review replies, commits, or pushes were published.
|
|
||||||
|
|
@ -1,69 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: intercepted-claude-7b9c97c4-fff7-4ac4-97fb-35720453308e
|
|
||||||
timestamp: 2026-08-18T02:17:29Z
|
|
||||||
git_ref: d9a6e2e9
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T021729Z_d9a6e2e9_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
> Intercept Claude session
|
|
||||||
> `7b9c97c4-fff7-4ac4-97fb-35720453308e`, pick up where it
|
|
||||||
> stopped in its open worktree, finish the tunnelled-address change
|
|
||||||
> and commit plan, and prepare any outstanding context for another
|
|
||||||
> provider.
|
|
||||||
|
|
||||||
The recovered final prompt specifically called out the `uds` versus
|
|
||||||
`unix` boundary decision, absent concrete `Address.namespace`
|
|
||||||
implementations, the corrected namespace test, and the passing
|
|
||||||
focused and wider suites.
|
|
||||||
|
|
||||||
During review, the human further required that tunnelled-maddr work
|
|
||||||
delegate to `multiaddr`'s encapsulation APIs, challenged the premature
|
|
||||||
transport-shaped listener hooks and directed their removal, corrected
|
|
||||||
the long-term bearer provisioning model, and confirmed the intended
|
|
||||||
split between discovery metadata and bindspace lifecycle code.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Recovered the transcript and matched it to `wkts/addr_unpacking`,
|
|
||||||
audited the staged implementation, and completed the interrupted
|
|
||||||
verification and commit-plan work. The audit removed premature
|
|
||||||
transport-shaped listener hooks, widened the namespace identifier
|
|
||||||
type, updated stale import documentation, and removed an
|
|
||||||
invalid-escape warning from the maddr diagram. It also preserved the
|
|
||||||
layer-C design where tractor provisions the kernel-owned tunnel
|
|
||||||
bearer without treating it as a message transport.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/discovery/_tunnel.py` - tunnel specs, address wrapper, and
|
|
||||||
peeling helpers.
|
|
||||||
- `tractor/discovery/_addr.py` - wrapped-address recognition and
|
|
||||||
namespace typing.
|
|
||||||
- `tractor/discovery/__init__.py` - public tunnel API exports.
|
|
||||||
- `tests/discovery/test_tunnelled_addr.py` - delegation and boundary
|
|
||||||
regression coverage.
|
|
||||||
- `ai/tpt-backends/03_wg_tunnel_bindspace.md` - distinguish
|
|
||||||
tractor-owned bindspace provisioning from kernel socket ownership.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
Substantial human-directed editing occurred over several review turns:
|
|
||||||
|
|
||||||
- required use of `multiaddr`'s `.encapsulate()`/`.decapsulate()`
|
|
||||||
family rather than a hand-rolled tunnel peeler
|
|
||||||
- rejected the premature `start_listener()`/`close_listener()` hooks
|
|
||||||
and directed their removal from this foundational change
|
|
||||||
- corrected the documentation so tractor retains ownership of future
|
|
||||||
bindspace provisioning while the kernel owns the bearer socket
|
|
||||||
- reviewed and accepted the placement of declarative tunnel metadata
|
|
||||||
under `tractor.discovery`, with lifecycle code kept separate
|
|
||||||
|
|
||||||
The final source lines were applied through the coding agents, but
|
|
||||||
these design corrections and deletion decisions came from the human
|
|
||||||
review and materially shaped the patch.
|
|
||||||
|
|
@ -1,66 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T02:17:29Z
|
|
||||||
git_ref: d9a6e2e9
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output - tunnelled-address handoff completion
|
|
||||||
|
|
||||||
Recovered Claude Code session
|
|
||||||
`7b9c97c4-fff7-4ac4-97fb-35720453308e` and continued its
|
|
||||||
interrupted `wkts/addr_unpacking` changes.
|
|
||||||
|
|
||||||
## Generated code
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/discovery/_tunnel.py`
|
|
||||||
|
|
||||||
Added frozen `WGTunnelSpec` and `TunnelledAddress` structs. The
|
|
||||||
wrapper delegates transport identity, validity, bindspace, and wire
|
|
||||||
serialization to its overlay while retaining tunnel metadata locally.
|
|
||||||
Added pure helpers to peel nested wrappers and enumerate their tunnel
|
|
||||||
specs. The module documents why wrappers must be peeled before
|
|
||||||
`Endpoint` selects the overlay transport backend.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/discovery/_addr.py`
|
|
||||||
|
|
||||||
Extended `is_wrapped_addr()` to recognize `TunnelledAddress` without
|
|
||||||
registering tunnels as message transports, and widened the namespace
|
|
||||||
identifier type to cover named network namespaces.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/discovery/__init__.py`
|
|
||||||
|
|
||||||
Exported the tunnel address API from `tractor.discovery` and updated
|
|
||||||
the eager-import documentation.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/discovery/test_tunnelled_addr.py`
|
|
||||||
|
|
||||||
Added focused coverage for delegation, serialization, rewrapping,
|
|
||||||
namespace fallback, nested peeling order, and frozen structs.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- ai/tpt-backends/03_wg_tunnel_bindspace.md`
|
|
||||||
|
|
||||||
Clarified that tractor owns the eventual bindspace lifecycle and may
|
|
||||||
provision the WireGuard iface, routes, and kernel UDP listener through
|
|
||||||
netlink/`pyroute2`. Kernel socket ownership does not make the bearer an
|
|
||||||
application `MsgTransport` endpoint.
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
Focused tests:
|
|
||||||
|
|
||||||
```text
|
|
||||||
9 passed in 0.03s
|
|
||||||
```
|
|
||||||
|
|
||||||
Discovery and IPC suites:
|
|
||||||
|
|
||||||
```text
|
|
||||||
67 passed, 2 xpassed
|
|
||||||
```
|
|
||||||
|
|
||||||
The audit removed premature module-level listener hooks. Runtime
|
|
||||||
integration must peel the wrapper explicitly at bind and dial
|
|
||||||
boundaries rather than make `._tunnel` impersonate a transport
|
|
||||||
backend.
|
|
||||||
|
|
@ -1,43 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: pr481-review-fixes-p1-20260818
|
|
||||||
timestamp: 2026-08-18T03:15:32Z
|
|
||||||
git_ref: 4151b956
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T031532Z_4151b956_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Address the approved review findings on PR #481, but work
|
|
||||||
iteratively: implement and verify one finding at a time, prepare a
|
|
||||||
separate `/commit-plan` after each fix, and stop for the human commit
|
|
||||||
before starting the next finding. Begin with the P1 per-child
|
|
||||||
lifecycle issue. Also publish the already-approved review findings
|
|
||||||
against the reviewed PR head before editing.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Published the approved non-approving review at head `4151b956`, then
|
|
||||||
implemented only the P1 lifecycle fix. Owned one-shot actors now use
|
|
||||||
a child-specific cancellation and process-reap handshake, including
|
|
||||||
hard escalation for unacknowledged cancellation and deterministic
|
|
||||||
bookkeeping removal before `to_actor.run()` returns.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/runtime/_supervise.py` - coordinate child-specific cancel
|
|
||||||
and reap.
|
|
||||||
- `tractor/spawn/_trio.py` - wait on the Trio child's reap request.
|
|
||||||
- `tractor/spawn/_mp.py` - wait on the multiprocessing child's reap
|
|
||||||
request.
|
|
||||||
- `tractor/spawn/_spawn.py` - publish monitor completion centrally.
|
|
||||||
- `tractor/to_actor/_api.py` - await owned-child process reaping.
|
|
||||||
- `tests/test_to_actor.py` - cover cleanup, escalation, and startup
|
|
||||||
ordering.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
None - the generated P1 patch remains uncommitted for human review.
|
|
||||||
|
|
@ -1,74 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T03:15:32Z
|
|
||||||
git_ref: 4151b956
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Implemented only the P1 lifecycle finding from the approved PR #481
|
|
||||||
review, preserving the requested one-fix-at-a-time commit boundary.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/runtime/_supervise.py`
|
|
||||||
|
|
||||||
Added per-child reap request/completion events to `ActorNursery`, a
|
|
||||||
shielded child-specific cancel-and-reap operation, late-registration
|
|
||||||
latching for nursery teardown, and cancellation escalation that waits
|
|
||||||
for debugger release before using non-ignorable process termination.
|
|
||||||
The nursery-wide cancellation path snapshots child records before
|
|
||||||
checkpointing so concurrent one-shot cleanup cannot invalidate its
|
|
||||||
iteration.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/spawn/_trio.py`
|
|
||||||
|
|
||||||
Changed Trio child monitors to wait on their per-child reap requests.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/spawn/_mp.py`
|
|
||||||
|
|
||||||
Changed multiprocessing child monitors to wait on their per-child reap
|
|
||||||
requests.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/spawn/_spawn.py`
|
|
||||||
|
|
||||||
Ensured every backend publishes child-reap completion after its process
|
|
||||||
monitor exits.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/to_actor/_api.py`
|
|
||||||
|
|
||||||
Changed owned one-shot cleanup to await child-specific process joining
|
|
||||||
and bookkeeping removal instead of treating the cancel RPC as reaping.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_to_actor.py`
|
|
||||||
|
|
||||||
Added regressions for immediate caller-managed nursery cleanup, failed
|
|
||||||
cancel acknowledgement escalation, and child registration after a
|
|
||||||
latched nursery-wide teardown request.
|
|
||||||
|
|
||||||
Verification:
|
|
||||||
|
|
||||||
`pytest -q tests/test_to_actor.py tests/test_cancellation.py tests/test_spawning.py tests/discovery/test_multi_program.py`
|
|
||||||
|
|
||||||
Result: `46 passed, 1 xfailed, 3 xpassed`.
|
|
||||||
|
|
||||||
`pytest -q tests/test_to_actor.py --tpt-proto uds`
|
|
||||||
|
|
||||||
Result: `13 passed`.
|
|
||||||
|
|
||||||
`pytest -q tests/test_to_actor.py --spawn-backend mp_spawn --tpt-proto tcp`
|
|
||||||
|
|
||||||
Result: `13 passed`.
|
|
||||||
|
|
||||||
One broad verification run was mistakenly launched in parallel with
|
|
||||||
the UDS and `mp_spawn` actor suites. It timed out
|
|
||||||
`test_remote_error_from_caller_nursery`; the node passed immediately
|
|
||||||
in isolation and the complete broad selection then passed serially.
|
|
||||||
The failure was classified as concurrent test-session interference,
|
|
||||||
not accepted as a passing boundary result.
|
|
||||||
|
|
||||||
Ruff, Python compilation, and `git diff --check` passed for the changed
|
|
||||||
boundary. Ruff's existing `_trio.py` F401 finding was reproduced at the
|
|
||||||
unmodified PR head and excluded from attribution to this patch.
|
|
||||||
|
|
||||||
No source files were staged, committed, pushed, or used for review
|
|
||||||
replies. The previously approved top-level review was published before
|
|
||||||
the fix at reviewed head `4151b956`.
|
|
||||||
|
|
@ -1,50 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: tractor-addr-unpacking-followup
|
|
||||||
timestamp: 2026-08-18T07:50:31Z
|
|
||||||
git_ref: dd02c7c0
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T075031Z_dd02c7c0_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
The human requested the complete tunnelled-maddr parsing/composition
|
|
||||||
slice as an unattended batch, with every numbered requirement finished
|
|
||||||
and atomic commit plans prepared at the end. Existing human decisions
|
|
||||||
required native `multiaddr` encapsulation APIs, no hand-written peeler,
|
|
||||||
and preservation of tractor's future bindspace lifecycle ownership.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Implemented strict WG key codecs and native single/nested tunnel maddr
|
|
||||||
parsing and composition, integrated them into discovery APIs, migrated
|
|
||||||
the multihost example off its duplicate parser, corrected package
|
|
||||||
dependency metadata, and added focused and end-to-end parser
|
|
||||||
regressions. Verified the complete tractor suite and built both package
|
|
||||||
artifacts.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/discovery/` - WG codecs, parser/composer, wrapper typing,
|
|
||||||
public exports, and discovery dispatch.
|
|
||||||
- `tests/discovery/` - key, grammar, nesting, round-trip, and public
|
|
||||||
boundary regressions.
|
|
||||||
- `examples/multihost/wg_lan/` - production parser migration and
|
|
||||||
updated usage documentation.
|
|
||||||
- `pyproject.toml`, `uv.lock` - reproducible WG codec and multibase
|
|
||||||
dependencies for checkout and package installs.
|
|
||||||
- `ai/tpt-backends/03_wg_tunnel_bindspace.md` - current layer-A state
|
|
||||||
and future bindspace ownership.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human selected the five-step scope and batch execution model,
|
|
||||||
required delegation to `multiaddr`'s encapsulation APIs, rejected
|
|
||||||
transport-shaped listener placeholders in the prerequisite commit, and
|
|
||||||
clarified that tractor will eventually provision the kernel-owned
|
|
||||||
bearer through its bindspace layer. The agent implemented and tested
|
|
||||||
those decisions; no direct manual source edits were observed during
|
|
||||||
this batch.
|
|
||||||
|
|
@ -1,61 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T07:50:31Z
|
|
||||||
git_ref: dd02c7c0
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output - native WireGuard maddr integration
|
|
||||||
|
|
||||||
The human requested completion of the five-step tunnelled-maddr slice:
|
|
||||||
port the proven WireGuard parser, delegate to `py-multiaddr`'s native
|
|
||||||
tunnel APIs, integrate public parse and composition entry points, add
|
|
||||||
regressions, and return atomic commit plans after completing the batch.
|
|
||||||
|
|
||||||
## Generated code
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/discovery/_tunnel.py tractor/discovery/_multiaddr.py tractor/discovery/_addr.py tractor/discovery/__init__.py`
|
|
||||||
|
|
||||||
Added strict WireGuard standard-base64/multibase key codecs and native
|
|
||||||
WG maddr parsing/composition. Nested stacks peel the last `/wg/`
|
|
||||||
repeatedly with `.decapsulate_code()`, isolate segments through
|
|
||||||
`.split()`/`.join()`, and compose recursively with `.encapsulate()`.
|
|
||||||
Public discovery parsing, wrapping, endpoint-table parsing, and maddr
|
|
||||||
composition now preserve `TunnelledAddress` metadata locally.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- pyproject.toml uv.lock`
|
|
||||||
|
|
||||||
Declared `py-multibase` directly and pinned the unreleased
|
|
||||||
py-multiaddr#108 WG codec revision in distribution metadata. Enabled
|
|
||||||
Hatch direct-reference metadata so editable, wheel, and sdist builds
|
|
||||||
use the same dependency contract.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/discovery/test_multiaddr.py tests/discovery/test_tunnelled_addr.py`
|
|
||||||
|
|
||||||
Added key-codec, single/nested WG round-trip, malformed key, invalid
|
|
||||||
bearer/overlay, missing codec, missing bearer, `wrap_address()`, and
|
|
||||||
`parse_endpoints()` coverage while retaining plain TCP/UDS regressions.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- examples/multihost/wg_lan ai/tpt-backends/03_wg_tunnel_bindspace.md`
|
|
||||||
|
|
||||||
Removed the duplicate example parser, migrated callers to production
|
|
||||||
`TunnelledAddress`, retained only explicit `wg(8)` verification, and
|
|
||||||
updated dependency and future bindspace ownership documentation.
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
- focused discovery files: `45 passed`
|
|
||||||
- discovery and IPC suites: `81 passed, 2 xpassed`
|
|
||||||
- full suite: `443 passed, 9 skipped, 7 xfailed, 4 xpassed`
|
|
||||||
- collection: `462 tests`
|
|
||||||
- Ruff: clean
|
|
||||||
- sdist and wheel builds: successful
|
|
||||||
|
|
||||||
## Review corrections
|
|
||||||
|
|
||||||
A review caught that `[tool.uv.sources]` alone would not constrain
|
|
||||||
built-package consumers to a WG-capable py-multiaddr revision. The
|
|
||||||
dependency was moved into PEP 621 metadata and the parser now converts
|
|
||||||
missing-codec failures into an actionable tractor error without
|
|
||||||
misclassifying Unix paths containing a `wg` directory.
|
|
||||||
|
|
@ -1,36 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
|
|
||||||
timestamp: 2026-08-18T19:30:01Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T193001Z_bf06b4f8_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Fix cancellation during an indeterminate transport write without
|
|
||||||
allowing a second RPC msg to corrupt the stream. Keep the transport
|
|
||||||
fix separate from the higher-level `to_actor` remediation and explain
|
|
||||||
the length-prefixed protocol rather than using unexplained "framed
|
|
||||||
send" terminology.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Close a msgpack transport stream when cancellation interrupts its
|
|
||||||
length-prefixed `send_all()` operation. The stream can no longer be
|
|
||||||
safely reused because Trio cannot report how many bytes were written.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/ipc/_transport.py` - close an interrupted send stream.
|
|
||||||
- `tests/ipc/test_each_tpt.py` - cover cancellation during the write.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human required this transport edge-case fix to land as its own
|
|
||||||
behavioral commit with a detailed message. During staged review, the
|
|
||||||
human also rejected the unexplained "framed send" wording and asked
|
|
||||||
for terminology tied directly to the actual transport operation.
|
|
||||||
|
|
@ -1,19 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T19:30:01Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Prospective review found that cancellation can interrupt
|
|
||||||
`MsgpackTransport.send()` after `send_all()` writes only part of its
|
|
||||||
length-prefixed msg. Sending a cancellation request afterward can
|
|
||||||
append another msg to the indeterminate stream and desynchronize the
|
|
||||||
peer decoder.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/ipc/_transport.py tests/ipc/test_each_tpt.py`
|
|
||||||
|
|
||||||
Close the stream under a cancellation shield when `send_all()` is
|
|
||||||
cancelled. Cover the behavior with a fake stream that checkpoints
|
|
||||||
inside the write and records forced closure.
|
|
||||||
|
|
@ -1,37 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
|
|
||||||
timestamp: 2026-08-18T19:30:02Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T193002Z_bf06b4f8_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Distill repeated `Actor._contexts.pop()` machinery into a wrapper like
|
|
||||||
the RPC-task registration helper so future teardown sites do not keep
|
|
||||||
reconstructing the context-registry key independently. Preserve the
|
|
||||||
existing lifecycle-specific cleanup behavior.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Add idempotent `Actor._drop_context()` registry removal keyed from the
|
|
||||||
context's own channel and CID. Use it for caller context teardown and
|
|
||||||
the strict callee-side RPC deregistration path.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/runtime/_runtime.py` - own context-registry removal.
|
|
||||||
- `tractor/runtime/_rpc.py` - use the helper for callee teardown.
|
|
||||||
- `tractor/_context.py` - use the helper after caller teardown.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human identified the repeated registry-pop code and requested a
|
|
||||||
central primitive analogous to `_register_rpc_task()`. The agent first
|
|
||||||
suggested an async helper that also closed receive channels; the final
|
|
||||||
design was narrowed to registry removal only so each lifecycle owner
|
|
||||||
retains its existing closure, debugger, shielding, and error policy.
|
|
||||||
|
|
@ -1,18 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T19:30:02Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Repeated teardown sites reconstruct the `Actor._contexts` registry
|
|
||||||
key from a portal channel and context ID before popping it. Add an
|
|
||||||
idempotent actor-owned helper deriving the key from the context itself,
|
|
||||||
then route caller and callee context teardown through that helper.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/runtime/_runtime.py tractor/runtime/_rpc.py tractor/_context.py`
|
|
||||||
|
|
||||||
Keep receive-channel closure and cancellation shielding in each
|
|
||||||
lifecycle owner so the helper centralizes registry machinery without
|
|
||||||
changing their teardown ordering.
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
|
|
||||||
timestamp: 2026-08-18T19:30:03Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T193003Z_bf06b4f8_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Cancel a remote task when its caller is cancelled after `Start`
|
|
||||||
publication but before startup acknowledgement. Keep cancellation
|
|
||||||
bounded, prevent its private `_cancel_task` RPC from recursively
|
|
||||||
cancelling itself and preserve public target kwargs unchanged.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Add private portal startup policy, use it for non-recursive context
|
|
||||||
cancellation and clean caller-side startup state under a shield.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/runtime/_portal.py` - separate private startup policy.
|
|
||||||
- `tractor/_context.py` - disable recursion for cancellation RPCs.
|
|
||||||
- `tractor/runtime/_runtime.py` - clean cancelled task startup.
|
|
||||||
- `tests/test_context_stream_semantics.py` - control cancellation
|
|
||||||
between `Start` publication and acknowledgement.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human required this cancellation behavior to remain a distinct
|
|
||||||
commit from general startup failures and from the public `to_actor`
|
|
||||||
API. The human also requested that its runtime comment describe the
|
|
||||||
actual length-prefixed transport guarantee and concrete `_cancel_task`
|
|
||||||
operation rather than referring to an unnamed wrapper.
|
|
||||||
|
|
@ -1,20 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T19:30:03Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Cancellation while `Actor.start_remote_task()` waits for `StartAck`
|
|
||||||
can strand its caller-side context and leave the remote task running.
|
|
||||||
Make one bounded cleanup request, remove local startup state and close
|
|
||||||
its receive channel.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/runtime/_runtime.py tractor/runtime/_portal.py tractor/_context.py tests/test_context_stream_semantics.py`
|
|
||||||
|
|
||||||
Separate private startup-cancellation policy from public target kwargs
|
|
||||||
using `Portal._run_from_ns()`. Have `Context.cancel()` disable recursive
|
|
||||||
startup cancellation for its own `_cancel_task` RPC. Exercise
|
|
||||||
cancellation after `Start` publication and prove the caller-owned actor
|
|
||||||
remains reusable without leaked contexts.
|
|
||||||
|
|
@ -1,36 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
|
|
||||||
timestamp: 2026-08-18T19:30:04Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T193004Z_bf06b4f8_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Release caller-side context state for every remote-task startup failure,
|
|
||||||
not only local cancellation. Preserve the remote error, avoid unsafe
|
|
||||||
follow-up sends and prove pre-publication serialization failures leave
|
|
||||||
a reused portal healthy.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Extend remote-task startup cleanup across send, acknowledgement and
|
|
||||||
validation errors. Track completed publication, perform only safe
|
|
||||||
best-effort cancellation and deterministically remove local state.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/runtime/_runtime.py` - clean every startup failure path.
|
|
||||||
- `tests/test_context_stream_semantics.py` - cover authorization and
|
|
||||||
serialization failures before context entry.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human accepted the discovered edge-case fixes but required general
|
|
||||||
startup cleanup to land separately from cancellation cleanup, transport
|
|
||||||
integrity and the public API. This boundary preserves that behavioral
|
|
||||||
distinction and its dedicated commit-message rationale.
|
|
||||||
|
|
@ -1,19 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T19:30:04Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
`Actor.start_remote_task()` inserts a context before sending `Start`,
|
|
||||||
but startup errors other than cancellation escape without removing or
|
|
||||||
closing that caller state. Serialization errors, acknowledgement
|
|
||||||
timeouts, malformed acknowledgements and remote authorization errors
|
|
||||||
can therefore leak context-registry entries.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/runtime/_runtime.py tests/test_context_stream_semantics.py`
|
|
||||||
|
|
||||||
Cover the complete send, acknowledgement and validation phase with
|
|
||||||
exceptional cleanup. Attempt remote cancellation only when publication
|
|
||||||
is known complete or protocol-safe, and always release local state.
|
|
||||||
|
|
@ -1,52 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
|
|
||||||
timestamp: 2026-08-18T19:30:05Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260818T193005Z_bf06b4f8_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Replace abandoned `Portal.run()` one-shots with a static linked-context
|
|
||||||
endpoint. Follow Trio positional-call semantics, use partials for target
|
|
||||||
keywords, preserve Python 3.14 Placeholder behavior, keep target lookup
|
|
||||||
behind the RPC allowlist and support private, nursery and portal
|
|
||||||
placement.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Use `Portal.open_context()` and `Context.wait_for_result()` for one-shot
|
|
||||||
tasks. Normalize every partial layer, validate signatures locally and
|
|
||||||
send target namespace/function components separately to the authorized
|
|
||||||
remote resolver. Retain the client-side function in its `NamespacePath`
|
|
||||||
so `to_tuple()` does not re-import it. Owned actors enable the declaring
|
|
||||||
`_api.__name__` directly; caller-owned portals opt in through the public
|
|
||||||
`to_actor.MODULE` alias.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/to_actor/_api.py` - implement linked one-shot calls.
|
|
||||||
- `tractor/to_actor/__init__.py` - export `MODULE`.
|
|
||||||
- `tractor/msg/ptr.py` - retain refs created by `from_ref()`.
|
|
||||||
- `tests/test_to_actor.py` - cover the public API and authorization.
|
|
||||||
- `examples/parallelism/to_actor_one_shots.py` - use positional inputs.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human rejected nested target-kwargs configuration and selected
|
|
||||||
Trio-style positional inputs plus `functools.partial()`. During staged
|
|
||||||
review the human required a Python 3.14 compatibility comment rather
|
|
||||||
than removing Placeholder support, requested separate namespace and
|
|
||||||
function inputs, preserved `_get_rpc_func(ns: str, funcname: str)`
|
|
||||||
authorization, renamed `RPC_MODULE` to `MODULE`, rejected global module
|
|
||||||
exposure and deferred speculative nursery/module-list helpers to the
|
|
||||||
`open_taskman()` design line. The human also required this public API
|
|
||||||
to land only after its lower-level safety dependencies. In final staged
|
|
||||||
review, the human required `_invoke_from_portal()` to use
|
|
||||||
`NamespacePath.to_tuple()` with the already-held function ref and
|
|
||||||
required internal actor setup to use `_api.__name__` directly, keeping
|
|
||||||
`to_actor.MODULE` solely as the public importer-facing alias.
|
|
||||||
|
|
@ -1,24 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-18T19:30:05Z
|
|
||||||
git_ref: bf06b4f8
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Implement `to_actor.run()` with Trio-style positional target arguments,
|
|
||||||
`functools.partial` keyword and Python 3.14 Placeholder binding, and a
|
|
||||||
static context endpoint that links remote results, errors and caller
|
|
||||||
cancellation.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/to_actor/_api.py tractor/to_actor/__init__.py`
|
|
||||||
|
|
||||||
Resolve target functions through `Actor._get_rpc_func()` so module
|
|
||||||
authorization remains authoritative. Automatically expose the helper
|
|
||||||
module for actors owned by `to_actor.run()` and document explicit
|
|
||||||
exposure for a caller-owned portal.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/test_to_actor.py examples/parallelism/to_actor_one_shots.py`
|
|
||||||
|
|
||||||
Cover placement modes, argument binding, nested partials, caller-linked
|
|
||||||
cancellation, remote errors and module authorization.
|
|
||||||
|
|
@ -1,34 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
|
|
||||||
timestamp: 2026-08-19T02:07:57Z
|
|
||||||
git_ref: b38efed7
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260819T020757Z_b38efed7_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Resolve the remaining P3 review finding before landing PR #481:
|
|
||||||
`runtime_kwargs={}` must not be silently accepted alongside either
|
|
||||||
`an=` or `portal=` merely because the dict is falsey. Keep this as its
|
|
||||||
own final review-remediation commit.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Treat any non-`None` `runtime_kwargs` value as provided when validating
|
|
||||||
placement. Cover both placement APIs with empty and configured dicts,
|
|
||||||
proving the error is raised locally before actor startup.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/to_actor/_api.py` - validate option presence explicitly.
|
|
||||||
- `tests/test_to_actor.py` - cover four invalid option combinations.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
No direct line edits. The human accepted the P3 finding, required it to
|
|
||||||
remain separate from the five P2 behavioral commits and prioritized it
|
|
||||||
before the final PR #484 integration rebase and PR #481 landing steps.
|
|
||||||
|
|
@ -1,25 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-19T02:07:57Z
|
|
||||||
git_ref: b38efed7
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Fix the final PR #481 review finding: `runtime_kwargs` is mutually
|
|
||||||
exclusive with both caller placement options whenever it is provided,
|
|
||||||
including an empty dict.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/to_actor/_api.py tests/test_to_actor.py`
|
|
||||||
|
|
||||||
Use an explicit `is not None` check rather than dict truthiness. Expand
|
|
||||||
the validation regression across `an=` and `portal=`, each with empty
|
|
||||||
and configured runtime kwargs, so every invalid combination fails
|
|
||||||
before actor runtime startup.
|
|
||||||
|
|
||||||
Verification:
|
|
||||||
|
|
||||||
- Trio/TCP: `23 passed`
|
|
||||||
- Trio/UDS: `23 passed`
|
|
||||||
- `mp_spawn`/TCP: `23 passed`
|
|
||||||
- Ruff and `git diff --check`: clean
|
|
||||||
|
|
@ -1,56 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
|
|
||||||
timestamp: 2026-08-19T18:46:40Z
|
|
||||||
git_ref: 481ba003
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260819T184640Z_481ba003_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Rebase PR #484 onto final PR #481, migrate every affected one-shot call
|
|
||||||
to the new positional target API and continue through downstream tests,
|
|
||||||
examples and documentation review.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Converted stale target keyword calls to target partials so previously
|
|
||||||
named inputs remain explicit while placement/runtime controls stay
|
|
||||||
direct. Updated error expectations for local signature validation and
|
|
||||||
linked remote error propagation, then corrected docs which still
|
|
||||||
described the removed one-shot implementation. Linked spawning and
|
|
||||||
context lifecycle prose to the corresponding API methods and detailed
|
|
||||||
context guide.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `docs/api/core.rst` - describe linked one-shot context execution.
|
|
||||||
- `docs/guide/rpc.rst` - update placement and target call semantics.
|
|
||||||
- `docs/guide/spawning.rst` - document positional target inputs.
|
|
||||||
- `examples/debugging/multi_nested_subactors_error_up_through_nurseries.py` - migrate nested actor target inputs.
|
|
||||||
- `examples/debugging/root_cancelled_but_child_is_in_tty_lock.py` - preserve named recursive target inputs with partials.
|
|
||||||
- `tests/test_advanced_streaming.py` - migrate streaming target inputs.
|
|
||||||
- `tests/test_cancellation.py` - migrate calls and tighten errors.
|
|
||||||
- `tests/test_infected_asyncio.py` - bind asyncio target options.
|
|
||||||
- `tests/test_rpc.py` - migrate RPC target argument binding.
|
|
||||||
- `tests/test_runtime.py` - preserve named runtime target inputs.
|
|
||||||
- `tests/test_spawning.py` - preserve named spawning target inputs.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human selected the stack order and final PR #481 base, asked the
|
|
||||||
agent to continue after each diagnostic step and required a complete
|
|
||||||
commit plan after independently force-pushing the rebased history.
|
|
||||||
After reviewing the migration, the human required every formerly named
|
|
||||||
target input to remain visibly named through `functools.partial()`
|
|
||||||
rather than becoming positional. These were human-directed agent edits;
|
|
||||||
the human also required plain `start_actor()` and `open_context()`
|
|
||||||
references in the spawning and RPC guides to link to their API methods
|
|
||||||
and the detailed context guide, then clarified that `to_actor.run()`
|
|
||||||
already uses the full context API while `Portal.run()` should share
|
|
||||||
linked lifecycle machinery without necessarily delegating through
|
|
||||||
`Portal.open_context()` or adding a `Started` message. The human made
|
|
||||||
no direct source-line edits.
|
|
||||||
|
|
@ -1,30 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-19T18:46:40Z
|
|
||||||
git_ref: 481ba003
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Migrate PR #484's downstream one-shot calls to PR #481's final
|
|
||||||
`tractor.to_actor.run()` contract after the stack rebase.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- docs examples tests`
|
|
||||||
|
|
||||||
Pass target arguments positionally and bind target keyword-only inputs
|
|
||||||
with `functools.partial()`. Keep placement and runtime controls as
|
|
||||||
direct `to_actor.run()` keywords. Update the invalid-target-argument
|
|
||||||
test to expect local signature binding before actor startup and require
|
|
||||||
direct `RemoteActorError` propagation from linked one-shots.
|
|
||||||
|
|
||||||
Update API and guide prose to describe positional target inputs,
|
|
||||||
linked `Portal.open_context()` execution and per-child reaping instead
|
|
||||||
of the removed `Portal.run()` and target-`**kwargs` conventions.
|
|
||||||
|
|
||||||
Verification:
|
|
||||||
|
|
||||||
- core and migrated runtime batches: `97 passed`
|
|
||||||
- discovery and related lifecycle batch: `33 passed, 1 skipped`
|
|
||||||
- changed executable examples: `9 passed`
|
|
||||||
- mapped debugger cases: `12 passed, 6 skipped`
|
|
||||||
- Ruff, compilation and `git diff --check`: clean
|
|
||||||
|
|
@ -1,37 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: tractor-addr-unpacking-followup
|
|
||||||
timestamp: 2026-08-19T21:31:44Z
|
|
||||||
git_ref: f81fc5e5
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260819T213144Z_f81fc5e5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
The human requested runtime boundary integration with the established
|
|
||||||
per-step implementation and commit-plan workflow.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Kept `TunnelledAddress` available to callers while peeling it at the
|
|
||||||
last outbound boundary before transport lookup and dialing. Added a
|
|
||||||
regression which captures both transport arguments and confirms plain
|
|
||||||
TCP behavior is unchanged.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/ipc/_chan.py` - peel tunnel annotations before outbound
|
|
||||||
transport dispatch and connection.
|
|
||||||
- `tests/ipc/test_channel_tunnel_boundary.py` - verify plain and
|
|
||||||
tunnelled channel inputs deliver only TCP overlays.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human chose the runtime-boundary slice, required the existing
|
|
||||||
per-step commit-plan flow, and previously established that wrappers
|
|
||||||
must retain bindspace metadata without impersonating transports. The
|
|
||||||
agent implemented those constraints; no direct manual source edits were
|
|
||||||
observed during this step.
|
|
||||||
|
|
@ -1,25 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-19T21:31:44Z
|
|
||||||
git_ref: f81fc5e5
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output - outbound tunnel boundary
|
|
||||||
|
|
||||||
The human requested the next tunnelled-address slice using the same
|
|
||||||
per-step commit-plan flow. Existing design decisions require retaining
|
|
||||||
tunnel metadata until the narrow IPC transport boundary and never
|
|
||||||
teaching exact-type transport tables about tunnel wrappers.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/ipc/_chan.py tests/ipc/test_channel_tunnel_boundary.py`
|
|
||||||
|
|
||||||
Extended channel address inputs to accept tunnel declarations, then
|
|
||||||
called `strip_tunnels()` immediately before exact-type transport lookup
|
|
||||||
and `connect_to()`. Added plain/tunnel parameterized coverage proving
|
|
||||||
both operations receive the identical TCP overlay while the original
|
|
||||||
wrapper retains its tunnel spec.
|
|
||||||
|
|
||||||
Verification included focused IPC tests, Ruff, discovery/IPC suites,
|
|
||||||
and the full tractor suite.
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: tractor-addr-unpacking-followup
|
|
||||||
timestamp: 2026-08-19T21:31:45Z
|
|
||||||
git_ref: f81fc5e5
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260819T213145Z_f81fc5e5_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
The human requested completion of inbound runtime peeling using the
|
|
||||||
same per-step implementation and commit-plan workflow.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Preserved tunnel declarations through listener configuration, peeled
|
|
||||||
them immediately before `Endpoint` construction, and used the overlay
|
|
||||||
for backend-specific random listener allocation after registry
|
|
||||||
discovery. Added a real listener regression for the reflection and
|
|
||||||
exact-type boundary.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/ipc/_server.py` - accept wrapper declarations and peel at
|
|
||||||
`Endpoint` construction.
|
|
||||||
- `tractor/_root.py` - allocate random transport addresses from the
|
|
||||||
contacted registry's overlay.
|
|
||||||
- `tests/ipc/test_server_tunnel_boundary.py` - verify a real listener
|
|
||||||
stores only TCP while preserving the source annotation.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human selected the runtime-boundary work and previously corrected
|
|
||||||
the architecture so tractor retains future bindspace provisioning
|
|
||||||
ownership while `Endpoint` sees only application transports. The agent
|
|
||||||
implemented and tested that direction; no direct manual source edits
|
|
||||||
were observed during this step.
|
|
||||||
|
|
@ -1,25 +0,0 @@
|
||||||
---
|
|
||||||
model: gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-19T21:31:45Z
|
|
||||||
git_ref: f81fc5e5
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
# Raw output - inbound tunnel boundary
|
|
||||||
|
|
||||||
The human requested runtime boundary integration while preserving the
|
|
||||||
future tractor-owned bindspace lifecycle.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tractor/ipc/_server.py tractor/_root.py tests/ipc/test_server_tunnel_boundary.py`
|
|
||||||
|
|
||||||
Broadened listener declarations to carry tunnel wrappers until
|
|
||||||
`_serve_ipc_eps()` and peeled immediately before `Endpoint`
|
|
||||||
construction. Also peeled a contacted tunnelled registry before
|
|
||||||
backend-specific random listener allocation. Added a real TCP listener
|
|
||||||
regression proving `Endpoint` stores only the resolved overlay while
|
|
||||||
the original declaration retains bindspace metadata.
|
|
||||||
|
|
||||||
Verification included `465` collected tests, `84` passing
|
|
||||||
discovery/IPC tests with two xpasses, Ruff, and the full suite with
|
|
||||||
`447` passes.
|
|
||||||
|
|
@ -1,37 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
|
|
||||||
timestamp: 2026-08-19T23:48:23Z
|
|
||||||
git_ref: 557065d8
|
|
||||||
scope: tests
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260819T234823Z_557065d8_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Investigate PR #481's red CI run, explain the missing T-800 and
|
|
||||||
debugger-output failures, and proceed with fixes in the PR #481
|
|
||||||
worktree.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Updated stale teardown assertions to match #481's direct hard-reap
|
|
||||||
path and observable process-lifetime invariants. Made nested debugger
|
|
||||||
checks consume the complete pexpect transcript rather than only the
|
|
||||||
last prompt latch.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tests/devx/test_debugger.py` - assert EOF/dead-process teardown and
|
|
||||||
accumulate nested debugger output across prompt boundaries.
|
|
||||||
- `tests/devx/test_tooling.py` - assert cancel-timeout hard-reap
|
|
||||||
escalation instead of the bypassed T-800 backend marker.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human reported the still-red PR #481 CI, supplied a failing job URL,
|
|
||||||
required work in `/wkts/pr481_review_fixes` and directed the agent to
|
|
||||||
continue immediately. No direct source-line edits were made by the
|
|
||||||
human.
|
|
||||||
|
|
@ -1,26 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
timestamp: 2026-08-19T23:48:23Z
|
|
||||||
git_ref: 557065d8
|
|
||||||
diff_cmd: git diff HEAD~1..HEAD
|
|
||||||
---
|
|
||||||
|
|
||||||
Diagnose and fix the stale debugger and reaper assertions failing PR
|
|
||||||
#481's Unix CI jobs.
|
|
||||||
|
|
||||||
> `git diff HEAD~1..HEAD -- tests/devx/test_debugger.py tests/devx/test_tooling.py`
|
|
||||||
|
|
||||||
Replace the old T-800 backend-log requirement with the new bounded
|
|
||||||
cancel-ack escalation evidence. Prove debugger teardown with EOF and a
|
|
||||||
dead child process instead of requiring optional `KeyboardInterrupt`
|
|
||||||
text. Accumulate all pexpect prompt chunks for nested error propagation
|
|
||||||
so expected tracebacks are not lost when `child.before` advances.
|
|
||||||
|
|
||||||
Verification:
|
|
||||||
|
|
||||||
- exact failed debugger/reaper nodes: `4 passed`
|
|
||||||
- debugger/tooling TCP: `39 passed, 6 skipped`
|
|
||||||
- debugger/tooling UDS: `39 passed, 6 skipped`
|
|
||||||
- full TCP suite: `478 passed, 9 skipped, 7 xfailed, 3 xpassed`
|
|
||||||
- full UDS rerun: `476 passed, 11 skipped, 8 xfailed, 2 xpassed`
|
|
||||||
|
|
@ -1,43 +0,0 @@
|
||||||
---
|
|
||||||
model: openai/gpt-5.6-sol
|
|
||||||
service: opencode
|
|
||||||
session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
|
|
||||||
timestamp: 2026-08-19T23:48:24Z
|
|
||||||
git_ref: 557065d8
|
|
||||||
scope: code
|
|
||||||
substantive: true
|
|
||||||
raw_file: 20260819T234824Z_557065d8_prompt_io.raw.md
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prompt
|
|
||||||
|
|
||||||
Investigate and fix PR #481's macOS TCP clustering and stream-overrun
|
|
||||||
failures without sacrificing IPC frame integrity or structured
|
|
||||||
concurrency.
|
|
||||||
|
|
||||||
## Response summary
|
|
||||||
|
|
||||||
Changed cancellation during `send_all()` from actor-wide stream closure
|
|
||||||
to shielded complete-frame publication followed by immediate pending
|
|
||||||
cancellation. Prevented failed overrun error shipment from promoting a
|
|
||||||
secondary transport closure over the context-local primary condition.
|
|
||||||
|
|
||||||
## Files changed
|
|
||||||
|
|
||||||
- `tractor/ipc/_transport.py` - complete in-flight frames before
|
|
||||||
delivering sender cancellation.
|
|
||||||
- `tractor/_context.py` - absorb transport closure while reporting an
|
|
||||||
overrun on an already-closing channel.
|
|
||||||
- `tests/ipc/test_each_tpt.py` - prove complete framing, cancellation
|
|
||||||
delivery and channel reuse.
|
|
||||||
- `tests/test_context_stream_semantics.py` - prove overrun reporting
|
|
||||||
tolerates a closed transport.
|
|
||||||
|
|
||||||
## Human edits
|
|
||||||
|
|
||||||
The human reported PR #481's red CI, asked for diagnosis and directed
|
|
||||||
the agent to proceed in the dedicated PR #481 worktree. During final
|
|
||||||
review, the human required preservation of the original far-end
|
|
||||||
cancellation rationale and fuller documentation of frame shielding,
|
|
||||||
shared-channel ownership and cancellation-delay tradeoffs. These were
|
|
||||||
human-directed agent edits; the human made no direct source-line edits.
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue