Repository navigation
refactor(platform_compat): carve the remaining helpers into owner modules - #22044
Conversation
…ules The second step of the platform_compat.py split. The facade keeps only the mirror glue and the bindings its contract needs (799 lines, from 3,726), and the rest of its code moves whole into owner modules: - platform_compat_links: links and junctions, the first linked ancestor, the extended-length prefix fold, the pinned directory and the opens that never follow a link at the final name; - platform_compat_metrics: process and host memory, CPU, open descriptors, subtree samples, heap trimming and the malloc arena cap; - platform_compat_files, _runtime, _winproc, _wintree: the permission, tail-open and filesystem checks, interpreter discovery, the launcher hops, strftime and the open-file limit, the Windows Job object and main-thread resume, and the tree pending check and owned spawn capture. Every name kiro_crew.platform_compat bound still resolves to the same object, and kiro_crew._facade_mirror carries every patch through the facade to the moved readers. Moved units are byte-identical except the brand spelling the added-line gate requires and one docstring that now says pinned_fs imports the facade. The recipe ran on the monolith at PR 1's merge parent and was three-way merged onto main, so nothing PR 1 merged is re-cut. The spec, the macOS darwin filter, the link-screen inventory, the jsonl and spawn-audit rows and four citations follow the moved code; the platform_compat.py line-cap row is deleted. Part of #20192
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Before merge, check that the slower lookup of moved names (about 2.3 µs instead of 0.1 µs) doesn't land in a hot call path, such as the metrics helpers called in monitoring loops. [DESIGN-REVIEWED] eec0b47 Description read[DESCRIPTION-READ] 730f5b5a47a440c4a9363e3f295ea99a0ea157eff46862025c961ccdc8ad7959 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check the hot loops that read What this change shipsInventory (7 items) — 7 justifiedIntent: bring
[FIRST-PRINCIPLES-REVIEWED] eec0b47 Description read[DESCRIPTION-READ] f9ddb0ed90c17e7f940fd29e30345b6933185d0d7b9994f0786713fea265dcfd That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Every review lane on the head is clean (only runner notices and PR Scope size warnings); held by the triage cron on size, path or checklist rules alone. Approved on the watch holder's request.
Problem / Motivation
Goal:
src/kiro_crew/platform_compat.pymoves its remaining helpers, unchanged, into owner modules and ends at 799 lines, with every import path, patch target and behaviour kept, which brings it under the 2,000-line cap.Kiro Crew is adopting a hard rule that no hand-written file exceeds 2,000 lines (#20192). #21000 carved the lower layers of
platform_compat.pyinto twelve owners and left a 3,726-line facade that still held the file-permission, link and no-reparse helpers, the process and host metrics, the Windows Job object helpers and a few runtime helpers. This PR is the second and last step.Why it matters
Every POSIX call in the codebase routes through this module, and it changes about 14 times a week. While the facade stays over the cap, every feature PR that touches it trips the line-cap guard, and the link handling, the metrics and the Windows job code stay buried in one file instead of each living beside its own family.
Not a goal
kiro_crew._facade_mirror, to the twelve owners' existing code, or to which nameskiro_crew.platform_compatoffers.What changed (motivation → approach → change)
The facade now holds only the mirror glue and the bindings its contract needs. Everything else moved whole, with the comment block above it, into the owner that matches its family:
platform_compat_links.py(new)platform_compat_metrics.py(new)platform_compat_files.pyrmtree_force, the log-tail and lock-sweep opens, owner access on a copied tree, the remote-volume, executable-file and read-only checksplatform_compat_runtime.pystrftime, the open-file limitplatform_compat_winproc.pyplatform_compat_wintree.pyplatform_compat.pyThe same recipe as #21000 did the move. It ran on the monolith at #21000's merge parent and was three-way merged onto main (base: its phase-1 output, which equals main byte for byte; ours: main; theirs: phase 2), so no code #21000 merged is re-cut.
kiro_crew._facade_mirrorcarries a patch through the facade to every moved reader, as it does for #21000's owners. The owning spec lists the final owners, the macOSdarwinfilter names the two new files, the facade's line-cap row is deleted, and the rows and citations that namedplatform_compat.pyfor moved code now name the owner.Backwards compatibility
Compatible: every name
kiro_crew.platform_compatbound before this PR still resolves to the same object (test/campaign_facade_inventories/kiro_crew.platform_compat.jsonfreezes its 223 names fortest_campaign_facades_base_public_names),__all__is unchanged, and every patch through the facade still reaches every reader (test_facade_mirror_guards,test_platform_compat_refactor_facade).Performance: the 146 names the facade held as its own module globals are now served by
MirroredModule.__getattr__, about 2.3 µs against 0.1 µs for each attribute read throughkiro_crew.platform_compat. That is the design #21000 used for its owners; a hot call site can bind the helper once.Each public
defthis PR moves stays importable fromkiro_crew.platform_compat(served or bound by the facade). One line per destination owner names all 48 of them:Reader: src/kiro_crew/platform_compat.py:first_linked_ancestor,is_link_or_junction,lstat_is_name_surrogate,open_create_no_reparse,open_file_no_reparse,pin_directory,pinned_dir_flags,pinned_directory,strip_extended_length_prefix,symlink_or_junction,unlink_link_or_junction,win_fd_is_link,win_open_no_reparse -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_links and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:chmod_safe,ensure_owner_rwx_dirs,fchmod_safe,is_executable_file,is_readonly_filesystem,open_lock_file_for_sweep,open_log_file_for_tail,path_volume_is_remote,rmtree_force -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_files and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:find_python_interpreter,nofile_soft_limit,python_launcher_hops,raise_nofile_soft_limit,strftime -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_runtime and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:count_open_fds,host_available_mib,host_total_mib,limit_malloc_arenas,log_malloc_arena_cap,macos_vm_statistics,memory_pressure_level,memory_pressure_name,proc_cpu_nanos_for_pid,proc_cpu_seconds,proc_peak_rss_bytes,proc_rss_bytes,proc_rss_bytes_for_pid,proc_rss_tree_mb_for_pid,proc_subtree_sample,system_cpu_percent,system_memory,trim_heap_if_needed -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_metrics and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:apply_job_limits,resume_process_main_thread -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_winproc and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:windows_tree_cleanup_pending -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_wintree and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Tests
test/test_platform_compat_refactor_facade.py: the owner tables (_OWNERS,_MOVED,_BOUND_HERE,_CARVED_IMPORTS) gain the two new owners and the moved rows, generated by the recipe for phase 2.test/link_screen_sites.py, regenerated bytest/gen_link_screen_sites.py: theensure_owner_rwx_dirssite is now inplatform_compat_files.py(181 sites, as before);test_jsonl_util.py: the/proc/meminfokernel pseudo-file row namesplatform_compat_metrics.py;test_spawn_audit.py: thefind_python_interpreterBENIGN_SPAWNSkey and its comment nameplatform_compat_runtime.py.test_sel_hard_exit_flush.py,test_docs_mock_pid_convention.py) need no edit: an undrainedos._exitor akill_probe_x()planted in the new links or metrics owner turns each red.Local gate floor (the 1,030-file run, mypy and the wheel smoke ran before the last docstring, comment and row edits; the re-gate, semgrep, the lints and the line-cap check ran after them):
-n 3(a superset of the 730run_scoped_testsselects; the one file outside it ran separately): every test passed except the three link-screen tests the regenerated row fixes andtest_gateway_lock_diagnosis::test_flock_is_held_by_a_fork_orphan, which passed alone 3/3 and in the re-gate; the 50-file re-gate after the last edits: 3,551 passed, 0 failed;KIROCREW_INTEGRATION=1 pytest -n 2 test/integration: 62 passed, 1 failed,test_owner_only_boot.py::test_a_fresh_boot_leaves_nothing_readable_by_others, which fails the same way on main on this host (umask 022) and passes in CI;git diffandgit diff --minimaladd the same lines in every changed file (platform_compat.py: 174 each).scripts/local-gate.py --dry-runselects 730 backend and 377 frontend (cross-surface) files, past the 600-file local cap, so the floor above ran instead. No file underwebsite/changed.Manual verification
N/A — a pure move: the floor above, the move audit and the base-name and patch-reach contracts prove the behaviour is unchanged.
Move audit
Changed units (5): the facade's
TYPE_CHECKINGmanifest (407 lines) and_CARVED_OWNERS(14 lines), which are glue that lists the two new owners, and three docstrings:find_python_interpreterandis_executable_file("KiroCrew" to "Kiro Crew", which the brand gate requires) andpinned_dir_flags, whose "imports THIS module" now sayspinned_fsimportskiro_crew.platform_compat. Outside the glue, the only edited lines are those three docstrings' wording and the same brand fix in the comment above_WINDOWS_RUNNABLE_HOOK_SUFFIXES.Logger names (L25):
platform_compat_metricsandplatform_compat_fileslog aslogging.getLogger("kiro_crew.platform_compat");platform_compat_linksdoes not log.Class
__module__: PR2 moves no exception or enum class.PinnedDirectory,HeapTrimMaintainer, theNamedTuplerows and the privatectypesstructures keep their owner's__module__; no test, log or caller reads it.Prose citations (L29):
docs/guides/windows-install.md(_VMStatistics64lives inplatform_compat_metrics),docs/architecture/resource-protection.md(apply_job_limitsinplatform_compat_winproc.py), two comments inscripts/check_lockdown_before_publish.py(fchmod_safeandchmod_safeinplatform_compat_files.py), and theexecv_target_availabledocstring inplatform_compat_runtime.py(is_executable_fileis inplatform_compat_files).CI path references
.github/workflows/macos-on-demand.yml: thedarwinfilter listssrc/kiro_crew/platform_compat_links.pyandsrc/kiro_crew/platform_compat_metrics.pybeside the other owners. No logic change..github/workflows/cross-platform.ymland.github/workflows/ci.ymlalready match the new owners through theplatform_compat_*.pyglobs refactor(platform_compat): carve the lower layers into owner modules #21000 added; no edit.Related Issues
Part of #20192
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).