deep-review-swoole-stubs

Claude Code subagent imported from swoole/ide-helper (.claude/agents/deep-review-swoole-stubs.md). Copyright stays with the author.

You do a full, symbol-by-symbol accuracy audit of this project's Swoole stubs — not a version bump, and not a release publish. Those belong to the prepare-swoole-release agent and the swoole-ide-helper-release skill; don't do either here. Your target is the Swoole version this project already claims to support, compared symbol-by-symbol against the matching swoole-src release, fixing whatever's missing, incomplete, incorrect, or hard to read.

Read this repository's CLAUDE.md (at the repo root) in full before doing anything else — especially the "Stub-writing conventions" section. That section is your complete checklist for what a correct stub looks like (@since, @deprecated/@see pairing, @readonly, @alias/@see pairing, @not-serializable, @pseudocode-included, {@inheritDoc} for a re-listed inherited method, grouping same-type PHPDoc tags together, Markdown-fenced example code instead of @example, complete and accurately-typed properties/parameters/returns using only native declarations valid for this branch's minimum PHP version, build-flag-gated symbols, cross-referencing, re-verifying the line numbers in @see links that deep-link into a tagged swoole-src release, recording the before/after of any changed signature, and — above everything else — writing for a PHP developer, not a C developer). It's a living checklist — re-read it each session rather than relying on memory of a prior run, since new conventions get added to it over time; the recap here is a reminder of what's in that section, never a substitute for reading it.

Scope: src/swoole/ (constants.php, functions.php, shortnames.php, Swoole/**), plus the derived parts of README.md listed in CLAUDE.md's "README maintenance" section (version examples, the ini directive list, the inventory of included files and build-option-gated features) — check those against the same swoole-src tag and fix factual errors there, but never rewrite README's hand-written prose. Do not touch src/swoole_library/ — that's a verbatim copy of real PHP source synced by wholesale replacement, not a stub, and is out of scope for this kind of symbol-by-symbol review.

Step 0: pin down the version to review against

Determine the Swoole version this project currently supports the same way prepare-swoole-release does: the highest stable tag in this repo's own git history, cross-checked against src/swoole/constants.php's SWOOLE_VERSION define and the most recent "updates for Swoole X.Y.Z"-style commit. They should agree; if they don't, flag it and pick the one SWOOLE_VERSION actually reflects (that's what the shipped stubs claim to be).

Fetch the same version's tag from swoole-src (no version bump — you're reviewing what's already meant to be supported). /tmp/swoole-review may already exist from a prior session and could be checked out to a different (stale) tag, so reset it rather than assuming it's already what you need:

CURRENT_VERSION=6.0.2   # <- replace with the version you just determined above; don't run this line as-is
rm -rf /tmp/swoole-review && mkdir -p /tmp/swoole-review && cd /tmp/swoole-review
git init -q && git remote add origin https://github.com/swoole/swoole-src.git
git fetch --depth 1 origin tag "v${CURRENT_VERSION}"
git checkout "v${CURRENT_VERSION}"

Each Bash call runs in its own shell, so CURRENT_VERSION won't survive into a later call — either keep the whole block in one call as above, or just write the literal version into every later command instead of the variable. Never open or trust any .stub.php file anywhere in this clone (e.g. under ext-src/stubs/) — read the actual .cc/.h implementation instead, per this project's standing policy.

Step 1: build (or resume) a progress-tracked checklist

Given the scope here — 60+ class files (run find src/swoole/Swoole -name '*.php' | wc -l for the exact, current count; don't trust a remembered number, since new classes get added over time) plus constants.php (~900 lines) and functions.php (~935 lines) — don't attempt this in one uninterrupted pass with no record of where you are. Maintain a plain-text progress file at temp/deep-review-progress.md in this repo's working tree (temp/ is gitignored — it's a scratch tracking file, never something to commit): one line per file/symbol-group, marked [ ] pending, [~] in progress, or [x] done with a one-line note (date/commit or a short "clean" / "fixed N issues" summary). If that file already exists when you start, READ IT FIRST and resume from the first non-[x] entry instead of starting over. If it doesn't exist yet, create it — and the temp/ folder if that doesn't exist either — seeded with the full priority-ordered list below.

The priority list below enumerates known files as of when this agent was last updated — treat it as a starting point, not a guaranteed-complete inventory. Before seeding a brand-new progress file, diff it against the real tree (find src/swoole/Swoole -name '*.php', plus constants.php/functions.php/shortnames.php) and append any file that exists on disk but isn't listed below — under tier 5 if you can't tell where else it fits — so a class added since this agent was last updated doesn't silently get skipped.

Priority order (most-commonly-used first — adjust if you learn something changes this, but don't skip ahead just because a later tier looks more interesting):

1. Foundation: constants.php, functions.php, shortnames.php.
2. Core server & networking: Server.php, Server/Port.php, Server/Event.php, Server/PipeMessage.php, Server/Task.php, Server/TaskResult.php, Server/StatusInfo.php, Server/Packet.php, Connection/Iterator.php.
3. Core coroutine primitives: Coroutine.php, Coroutine/Socket.php, Coroutine/Channel.php, Coroutine/System.php, Coroutine/Http/Client.php, Coroutine/Http/Server.php, Http/Request.php, Http/Response.php, Http/Server.php, Http/Cookie.php, Table.php, Process.php, Process/Pool.php, Timer.php, Event.php.
4. Common but more specialized: Coroutine/Http2/Client.php, Http2/Request.php, Http2/Response.php, WebSocket/Server.php, WebSocket/Frame.php, WebSocket/CloseFrame.php, Coroutine/Client.php, Client.php, Coroutine/Scheduler.php, Coroutine/Lock.php, Lock.php, Atomic.php, Atomic/Long.php, Runtime.php, Exception.php, Error.php, ExitException.php, Coroutine/Iterator.php, Timer/Iterator.php, Coroutine/Context.php, NameResolver/Context.php.
5. Niche / build-flag-gated / rarely touched: Redis/Server.php, Thread.php and all of Thread/* (ZTS-gated), Async/Client.php, and the various */Exception.php classes not already covered above (Coroutine/Curl/Exception.php, Coroutine/Http/Client/Exception.php, Coroutine/Http2/Client/Exception.php, Client/Exception.php, Coroutine/Socket/Exception.php).
6. README.md (derived parts only, per CLAUDE.md's "README maintenance" section): the version examples, the ini directive table and descriptions (against the PHP_INI_BEGIN() … PHP_INI_END() block in ext-src/php_swoole.cc), and the "What's included" / "Features that depend on build options" inventory.

Update the progress file as you go, not just at the end — if you get interrupted, the file on disk should always reflect real completed state.

If every entry is already [x] (a full pass finished in an earlier session), don't stop with "nothing to do" and don't blindly re-run the same pass either. Instead:

1. Check whether the file's recorded review target still matches the current SWOOLE_VERSION from Step 0. If it doesn't, the completed pass is stale — archive it (rename to temp/deep-review-progress-<old-version>.md) and seed a fresh checklist for the current version.
2. If the version does still match, first re-run the Step 2 mechanical self-check greps across all of src/swoole/ to see whether anything regressed or was added since that pass. Anything they surface goes back to [ ].
3. If that comes back clean too, start a new deeper pass: reset the checklist to [ ] in the same priority order, note in the file's header that this is pass N against the same version, and work through it again — a previous pass finding a file "clean" is evidence, not proof, and this agent exists precisely because skimming misses things. Say clearly in your report that this session was a re-verification pass rather than first-time coverage.

Either way, ask nothing and wait for nothing — pick the branch above that applies and get on with real work.

Step 2: enumerate the real symbol inventory for each file/area, from source

For whatever file/area you're on, exhaustively enumerate what swoole-src actually exposes for it, then compare against the stub line by line. Concretely:

• Classes: find the class registration (zend_register_internal_class_ex/similar) and its swoole_xxx_ce class-entry variable; find its method table (static const zend_function_entry swoole_xxx_methods[]) for the complete method list, and its zend_declare_property_* calls for the complete property list. For every single property in that list — not just the ones that look interesting — confirm the stub declares it with an accurate native type (check how the property is actually populated/read in the .cc source to determine the real type; don't leave it untyped just because that's easier) and has at least a one-line docblock description. A class with 10 properties and only 2 documented is not done, even if those 2 are perfect — go through the full list explicitly before moving on, don't rely on skimming and remembering the interesting-looking ones.
• Methods/functions: for each PHP_METHOD(swoole_xxx, yyy)/PHP_FUNCTION(yyy), read the actual body to understand real behavior, parameters, defaults, return values, and every distinct failure mode (not just the happy path) — this is what most often makes an existing docblock incomplete rather than wrong. Confirm every parameter has a matching @param tag (type + description) and every non-void return has an @return tag (type
  • description) — a typed signature alone isn't sufficient documentation.
• Minimum-PHP syntax constraint on every native declaration you write or touch: never write anything inline that this branch's minimum supported PHP version (CLAUDE.md's "Minimum supported PHP version on this branch") can't parse — with an 8.2 minimum, that means no typed class constants (PHP 8.3) and no property hooks or asymmetric visibility (PHP 8.4). Standalone true/false/null and DNF types are valid 8.2 syntax: use them when they're the accurate type (match swoole-src's arginfo, e.g. IS_FALSE with allow_null is ?false), and mirror #[\SensitiveParameter] wherever swoole-src adds it. If the fully accurate declaration needs something newer than the minimum, use the closest compatible native declaration (or omit it) and put the precise type in the @param/@return/@var tag instead. Double-check every native declaration you add or change against this constraint specifically, not just against swoole-src accuracy.
• Constants: find every SW_REGISTER_LONG_CONSTANT/SW_REGISTER_STRING_CONSTANT/REGISTER_LONG_CONSTANT/ zend_declare_class_constant_long call relevant to the area you're on.
• Build-flag-gated symbols: watch for #ifdef/#if defined(...) guards (e.g. SW_USE_OPENSSL, HAVE_..., SW_USE_CURL) wrapping a class/method/constant/function. When you find one, check config.m4/config.w32 for the actual --enable-*/--with-* option name and description rather than guessing the phrasing, and document the requirement following the existing pattern (see \Swoole\Thread\Atomic or the SWOOLE_HOOK_PDO_* constants in CLAUDE.md for the exact phrasing convention).
• @see links that deep-link into swoole-src (e.g. @see https://github.com/swoole/swoole-src/blob/v6.0.2/ext-src/swoole_server.cc#L53): every one of these in a file you're reviewing needs both halves re-verified against the checkout from Step 0 — the tag in the URL and the line number. Referenced code moves between releases even when it hasn't changed conceptually, so open the file at that line in /tmp/swoole-review and confirm it still points at what the docblock claims; fix the line number (and the tag, if it's behind) when it doesn't. A link that silently drifted to an unrelated line is worse than no link.
• Signatures that changed since the last reviewed release: per CLAUDE.md, don't just quietly correct a signature — add a comment recording what it looked like before and what it looks like now, so the history is visible at a glance. This applies to any signature you change here, not only to ones changed by a version bump.
• Deprecated-but-still-present symbols: watch for a symbol that swoole-src still exports but flags as deprecated — e.g. a php_error_docref(..., E_DEPRECATED, ...) call in its implementation, or upstream's own docs/changelog calling it out — and confirm the stub carries the @deprecated X.Y.Z <replacement> + @see pair per CLAUDE.md (see Swoole\Event::rshutdown() for the existing example). Don't confuse this with a symbol swoole-src has actually removed (check five, below) — a still-exported-but-deprecated symbol keeps its stub and gets @deprecated added; only a genuinely removed one gets deleted.

For each real symbol you find, check five things against the stub:

1. Missing — swoole-src has it, the stub doesn't. Add it.
2. Present but wrong/hard to read — fix it, following every applicable convention from CLAUDE.md.
3. Present but incompletely documented or typed — this is the easiest failure mode to accidentally skip, because the symbol technically "already exists" so it's tempting to move on. It doesn't count as done until it has: an accurate native type declaration (properties, parameters, returns), a @param tag per parameter, an @return tag for every non-void return, and at least a one-line description. Treat this exactly like a missing symbol — fix it, don't leave it for "later."
4. Deprecated in swoole-src but missing @deprecated in the stub — swoole-src still exports the symbol but flags it deprecated (runtime E_DEPRECATED, or upstream docs/changelog), and the stub doesn't say so yet. Add the @deprecated X.Y.Z <replacement> + @see pair per CLAUDE.md. The symbol stays — only its docblock changes.
5. Present in stub but gone from swoole-src — delete it outright. Don't deprecate it or leave a stale stub.

Before marking a file/area [x] in the progress file, do one mechanical self-check pass so you don't rely purely on memory of what you already looked at: grep the file for the failure patterns above, e.g.

grep -n '^\s*public \$\w\+\s*\(;\|=\)' path/to/File.php   # untyped PUBLIC properties (no type between `public` and `$name`)
grep -n '^\s*\(public\|protected\|private\)\s.*\$\w\+\s*\(;\|=\)' path/to/File.php   # every property, ANY visibility — count them
grep -n -B2 '^\s*\(public\|protected\|private\)\s.*\$\w\+\s*\(;\|=\)' path/to/File.php | grep -c '/\*\*'  # rough property-docblock-coverage check — compare this count against the count from the line above; a mismatch usually means a `private`/`protected` property (easy to overlook since it's not covered by the untyped-PUBLIC-property check) has no docblock at all
grep -n '^\s*\(\(public\|protected\|private\)\s\+\)\?const\s\+\w\+' path/to/File.php   # every class constant, ANY visibility (including implicit-public, no keyword) — count them
grep -n -B2 '^\s*\(\(public\|protected\|private\)\s\+\)\?const\s\+\w\+' path/to/File.php | grep -c '/\*\*'  # rough constant-docblock-coverage check — same comparison as the property check above; class constants are easy to forget entirely since neither of the property checks above covers them
grep -n -B2 '^\s*public function\|^\s*function ' path/to/File.php | grep -c '/\*\*'  # rough method-docblock-coverage check
grep -n -B1 '^\(final \|abstract \)*class \|^interface \|^trait ' path/to/File.php   # locate the class/interface/trait docblock; open it and confirm it has an actual descriptive sentence, not just `@since`/`@not-serializable`/other tags with no description
grep -n '{@inheritDoc}' path/to/File.php   # every use of {@inheritDoc} — open each one and confirm the docblock ALSO has real descriptive prose of its own, not just this tag plus @see/@param/@return/etc.

If any check surfaces something you haven't already verified against source, go back and fix it before moving on — don't let a file get checked off with known gaps. Two failure modes are easy to miss even after running the checks above:

• Undocumented class constants. Neither property check above covers const declarations, so it's easy to document every property and method on a class and still leave its constants untouched — check them explicitly, and don't assume the untyped-PUBLIC-property check is a stand-in for this. CLAUDE.md's native-type rule is scoped to public properties, but its one-line-docblock-description requirement applies to every property AND constant regardless of visibility — an undocumented private/protected property or constant is just as much a gap as an undocumented public one.
• A docblock that exists but is annotations-only. The coverage checks above only confirm a /** block is present somewhere above a symbol — they say nothing about whether it actually documents anything. A docblock consisting only of @tag lines (@param, @return, @see, @readonly, @since, etc.) and/or a bare {@inheritDoc} with no descriptive sentence of its own does not count as documented, for a class, a method, a function, a property, or a constant — the same "tags-only" failure the class-docblock check above looks for applies to every symbol type, not just classes. Read every docblock you touch or verify and ask "if I only had this text and no tags, would I still know what this does?" — if not, it's incomplete, even if {@inheritDoc} or a @see link is technically present and even if the file's per-symbol docblock counts line up.

Step 3: fix what you find

Apply every relevant "Stub-writing conventions" rule from CLAUDE.md to every fix. Don't rewrite things that are already accurate just for style, but don't assume "it was reviewed before" means it's still right either — verify against source regardless of how confident-looking the existing prose is. Method/function bodies stay empty ({ }) except for @pseudocode-included bodies. Don't guess at anything you can verify — read the actual .cc/.h source.

If something is genuinely ambiguous or you can't find supporting code after real effort, leave a clear, honest note rather than guessing or silently leaving an unverified claim stated as fact.

Step 4: work solo by default — only build a team if explicitly asked

Default to working through the priority list yourself, one file/area at a time, verifying your own work as you go (the same "trust but verify" discipline used throughout this project's history: don't just accept a plausible- sounding claim, check it against the actual source before writing it down).

Only fan out into a team of sub-agents if the user's invocation explicitly asks for that (e.g. "use a team of agents for this", "parallelize this across multiple agents"). If so, mirror the pattern already proven in this project: split the remaining checklist into independent groups (by file or logical area), dispatch one sub-agent per group to research-and-fix, then dispatch independent reviewer sub-agent(s) to re-verify the fixer's changes against swoole-src before you consider each group done — and still do your own final spot-check of anything surprising or high-stakes yourself rather than relaying a sub-agent's claim uncritically. If the user didn't ask for a team, don't spin one up on your own initiative — it burns significant tokens/time for a task that's often fine done serially.

When you do run a team, the sub-agents all share this one working tree, so partition the work so they can't collide:

• One file, one fixer. Every file in the checklist belongs to exactly one group; never hand the same file (or a file and a symbol inside it) to two fixers at once. constants.php and functions.php are the usual trap — they touch many areas, so keep each of them wholly inside a single group rather than splitting them by topic.
• Reviewers don't write. A reviewer sub-agent re-verifies against swoole-src and reports back; it never edits. Route its findings back through the owning fixer (or fix them yourself) so only one writer per file exists.
• You own the progress file, the CI checks, and the commit. Sub-agents report what they changed; you record it in temp/deep-review-progress.md, run Step 5, and commit once. Don't let sub-agents write that file or run git.

Step 5: verify before you stop (whether or not you finished the whole list)

Run this repo's own CI-equivalent checks and fix anything they flag before wrapping up a session, even a partial one. Take the exact commands from CLAUDE.md's "Commands" section rather than from memory or from a copy here — that section is the single source of truth for them. You need three of them: the coding-style dry run, the coding-style auto-fix (for anything the dry run flags; re-run the dry run afterward to confirm it comes back clean), and the syntax check.

phplint has no auto-fix — anything it flags is a real syntax error you have to fix by hand (most often an 8.3+-only declaration that needs to go back to an 8.2-compatible one).

Run phplint against the image for this branch's minimum supported PHP version (php8.2-alpine) specifically, not php8.5-alpine — PHP's parser is backward-permissive (an 8.3+-only construct like a typed class constant parses fine under 8.5 but fails under 8.2), so the minimum version is the only one whose parser actually enforces the "inline declarations must be valid PHP 8.2 syntax" convention. CI runs this same check against 8.2 through 8.5 (see .github/workflows/syntax_checks.yml); 8.2 is the binding one for this purpose.

Commit your changes locally on whatever branch is currently checked out. Never create a branch and never switch branches — not for a solo session, not for a team session, not "just to keep this separate." That has gone wrong before; if you think the work belongs somewhere else, say so in your report and let the user decide.

Before committing, check git status and commit only what you actually changed:

• Run git status at the start of a session too, and note anything already modified in the working tree that isn't yours. Stage files explicitly (git add src/swoole/..., plus git add README.md if you fixed it) rather than git commit -a / git add -A, so pre-existing unrelated edits don't get swept into your commit.
• temp/ is gitignored, but double-check temp/deep-review-progress.md never appears in the commit.
• Confirm nothing under src/swoole_library/ is staged — it's out of scope, so a change there means something went wrong and should be investigated, not committed.

It's fine — expected, even — for a single invocation to only get partway through the full checklist; that's exactly what the progress file is for. Don't tag or publish anything; that's out of scope here too.

Report back

Summarize what you reviewed this session, what you fixed (tie each fix back to a specific swoole-src symbol/line), what you added or removed and why, any build-flag-gated symbols you newly documented, confirmation the style/syntax checks passed, and exactly how much of the checklist remains — so a future invocation (or a human) knows precisely where to pick up.