Skip to content

ci(sync-io): gate pathlib reads and writes inside async def - #22902

Merged
iamwhatever merged 1 commit into
mainfrom
fix/22086-pathlib-io-sync-gate
Oct 22, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/22086-pathlib-io-sync-gate

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A new async def that reads or writes a file through pathlib on the event loop fails CI, the same way a new stat or resolve already does.

scripts/check_sync_io_in_async.py gates filesystem calls inside an async def (#22084), but its fs family left out Path.read_text(), read_bytes(), .open(), write_text(...) and write_bytes(...). Each runs the same blocking open(2), and nothing requires a stat before it. So a new on-loop read or write still lands green.

Why it matters

The gateway runs one event loop. A read or write on an NFS or FUSE mount that stopped answering blocks every endpoint until the kernel gives up. A stall past dashboard.loop_stall_exit_after_secs makes the loop watchdog kill the process. The Design lane on #22084 named this gap, and #22086 tracks it.

Not a goal

  • Offloading the 20 existing read/write sites. They go into the fs baseline once, which can only shrink.
  • iterdir(), glob(), mkdir(), unlink() and other pathlib calls the issue does not name.
  • Calls one frame down from an async def. The gate stays lexical, as it is for every family.

What changed (motivation → approach → change)

Pathlib reads and writes were missing from the fs family, so they kept arriving unflagged.

PATH_METHODS now records each method's family and the positional-argument count Path itself takes. A call matches only at that count:

Method Positional args matched Kept out
.read_text() / .read_bytes() / .open() 0 (keywords allowed) reader.read_text(blob), z.open(name)
.write_text(data) / .write_bytes(data) exactly 1 w.write_text(), w.write_bytes(k, b)
existing stats and resolves 0, as before unchanged

The module docstring now lists the five methods and drops the paragraph that called them a gap. The backend-lint row in docs/ci/ci-and-reviews.md names them too.

.github/sync-io-in-async-fs-baseline.txt records the sites this finds on main today, with the gate's own writer: 20 calls in 9 files (17 read_text, 3 write_bytes, no zero-argument .open()). The ledger goes from 138 calls in 57 files to 158 in 61.

Backwards compatibility

Breaking: a new pathlib read or write inside an async def, in a file a change touches, now fails the gate. Writer sweep on origin/main @ 86e61e6: the gate's scan finds 20 such sites in 9 files, and every one is in the fs baseline, so the gate passes on main as it stands. An open PR that adds such a call goes red until it offloads the call or marks it with # on-loop-io-ok: <reason>.

Removes nothing: the diff only widens what the fs family matches and raises its ledger by the sites that widening finds.

Ratchet note (a-ratchet-may-only-tighten): the fs baseline grows here, on purpose. No new on-loop IO is added: every added or raised entry is a call already on main that the wider matcher now sees, and the counts equal a full-tree scan. The rule allows a count that moves to the new true value. #22086 asks to record these sites in the fs baseline with the gate's own writer. Offloading all 20 sites here would touch 9 more source files, past this change's size budget.

Tests

test/test_sync_io_in_async_gate.py and the script's --test corpus (52 flagged, 33 clean probes):

  • test_pathlib_reads_and_writes_are_matched_by_their_own_arity flags all five methods at their own arity and nothing at the wrong one (read_text(k), open(k), write_text(), write_text(k, s)).
  • New flagged probes: each method, plus keyword forms (read_text(encoding=...), open(mode='w'), write_text(s, encoding=...)).
  • New clean probes: wrong arity for each, a read handed to to_thread, a write in a nested def. The old clean probe "a read is not gated" is now a flagged probe.
  • The existing byte-identical refresh test covers the updated fs baseline.

On origin/main's gate the five calls in the new test produce no findings. prove.py --base origin/main: PROVEN. Determinism: the whole file passed 5/5 repeated runs and one shuffled order (seed 7), 129 tests each.

Manual verification

python3 scripts/check_sync_io_in_async.py --report on this head lists 158 fs calls in 61 files, and the gate passes for both ledgers.

Screenshots / video

N/A: CI script only, no user-visible UI change.

Related Issues

Closes #22086

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 21, 2026 20:54
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 34c40845a9185eb489ebe3ea21e93f6108362c29 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 34c40845a9185eb489ebe3ea21e93f6108362c29 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change only widens a CI matcher, and the rise in the baseline is the true count of sites already on main. A revert undoes it cleanly.

Notes

  • An arity-only match on any receiver will flag an awaited async API with the same name and shape, such as await apath.read_text() on anyio.Path or await conn.open(). Consider skipping calls that sit directly under await, rather than making each author add an on-loop-io-ok marker for these false positives.

[DESIGN-REVIEWED] 34c4084

Description read

[DESCRIPTION-READ] 2b6f5e4cf4e3b13be5b1ab43920b99d73f4bcd256736d659ef68e7b94b4954e6

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 34c40845a9185eb489ebe3ea21e93f6108362c29 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Every item comes from #22086, and the probe that was flipped was already labelled "follow-up work" by the paragraph this change removes.

What this change ships

Inventory (5 items) — 5 justified

Intent: a new async def that reads or writes a file through pathlib on the event loop should fail CI, the same way an on-loop stat already does. This is an ADDITION that closes a gap the gate's own docstring recorded.

  1. Inside an async def, .read_text(), .read_bytes() and .open() with no positional argument now fail the gate — justified
  2. Inside an async def, .write_text(data) and .write_bytes(data) with exactly one positional argument now fail the gate — justified
  3. The fs baseline gains 20 existing sites in 9 files (138→158 calls, 57→61 files) — justified
  4. The gate's docstring drops the "gap, not a guarantee" paragraph, and the backend-lint row in the CI doc names the five methods — justified
  5. The self-test's clean probe "a read is not gated" is now a flagged probe, and new wrong-arity clean probes are added — justified

[FIRST-PRINCIPLES-REVIEWED] 34c4084

Description read

[DESCRIPTION-READ] 098933371aa49ef0ce3b25b0edaea9ee69253bac56b68f034dd3e3e1e78cf4ae

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 34c40845a9185eb489ebe3ea21e93f6108362c29 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 34c4084

Verdict parsed from the review's SHA-scoped output markers for commit 34c40845a9185eb489ebe3ea21e93f6108362c29.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 34c40845a9185eb489ebe3ea21e93f6108362c29: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 34c40845a9185eb489ebe3ea21e93f6108362c29 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 34c4084

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 34c40845a9185eb489ebe3ea21e93f6108362c29: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 21, 2026
@iamwhatever
iamwhatever force-pushed the fix/22086-pathlib-io-sync-gate branch from 806e026 to 34c4084 Compare October 21, 2026 21:59
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/ci/ci-and-reviews.md since this head went green (86e61e6 -> d0622d0); CI re-running.

🤖 AI-assisted comment 🤖

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 21, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Review-ready on head 34c4084.

  • pr_status.py 22902 --reviewers gpt,opus exited 0: 105 checks, 0 running, 0 failing; label readiness: passed.
  • Mergeable, not draft, no unresolved threads. GPT, Opus, UX, Design and First Principles lanes all pass on this head.
  • green_age.py reports main moved in docs/ci/ci-and-reviews.md since this head went green. That edit is in a different section, there is no conflict, and per the rebase rule this head is not rebased again.
  • Closes sync-io gate: add pathlib reads and writes to the fs family #22086. Awaiting a maintainer review; nothing else is pending from the author side.

🤖 AI-assisted comment 🤖

@iamwhatever
iamwhatever enabled auto-merge (squash) October 22, 2026 07:20

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving 34c4084.

Matching on the positional-argument count Path itself takes (PATH_METHODS, _family) is enough to keep reader.read_text(blob), z.open(name) and w.write_bytes(k, b) out without knowing the receiver type.

Checked for false positives on this head merged onto current main:

  • check_sync_io_in_async.py --test: 52 flagged / 33 clean probes, all right. The gate passes both ledgers.
  • --report finds 158 fs calls in 61 files, which equals the committed fs baseline, so main has added no sites since this branch was cut.
  • I read each of the 20 newly matched non-test sites (worktree_ops_sync.py, apps/routes.py, agent_config.py, handlers/core.py, hooks_scripts.py, mcp.py ×7, mcp_probe.py ×4, backend_record.py, install_repair.py). Every one is a real pathlib read or write inside an async def; none is another API. There are no zero-argument .open() matches, and no async path library in the tree to produce an awaited false positive.

test/test_sync_io_in_async_gate.py passes (129). Removing each new method, changing either write arity, or dropping the arity check turns named tests or self-test probes red.

Non-blocking: positional spellings such as p.open("w"), p.read_text("utf-8") or p.write_text(s, "utf-8") are not matched, because the arity is off by one. They are rare in this tree. Worth a line in the docstring as a known gap.

@iamwhatever
iamwhatever merged commit da3c2a7 into main Oct 22, 2026
106 checks passed
@iamwhatever
iamwhatever deleted the fix/22086-pathlib-io-sync-gate branch October 22, 2026 08:18
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

sync-io gate: add pathlib reads and writes to the fs family

2 participants