Repository navigation
refactor(platform_compat): carve the lower layers into owner modules - #21000
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Before merge, confirm the macOS on-demand and Windows lanes passed on this head. The moved Darwin and Win32 branches only run there, and the main CI does not run them. [DESIGN-REVIEWED] c30ff5a Description read[DESCRIPTION-READ] 89c78ccd0f0c5e2e0a591484408133a1756c7e5d4021f1130261436358ec97da 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 Verify the claim that the rewritten What this change shipsInventory (8 items) — 8 justifiedIntent: bring
[FIRST-PRINCIPLES-REVIEWED] c30ff5a Description read[DESCRIPTION-READ] 3c84647b303adfc901d9fcc0248889726197e9aa9cb7d3c318fe071cc4308417 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: |
|
|
Answers to the two whole-design punchlines on First Principles: does the rewritten
An independent review re-checked it on 1,566,348 real pairs, 108 hand-written edge cases (relative imports, aliases, nested patch strings, multi-line from-imports) and 200,000 fuzz texts, also with 0 disagreements. Design: do the Windows and macOS shards pass? Windows does: Backend Tests (Windows) 1-8, Backend Tests (IPv6, windows-latest), E2E Gateway Boot (windows-latest), Pod Boot Canary (Windows) and Windows Fail-Closed Sandbox Contract are all green on this head. The on-demand macOS suite matched this diff's darwin paths, but it was skipped on the pool cap ("at least 4 live lane run(s) already hold the macOS pool"). It needs |
|
bda3e15 to
761f6f6
Compare
|
Rebased: main moved in This head also carries:
The moved code is unchanged from |
|
Answers to the whole-design punchlines on Design: are the Windows and macOS lanes green? Yes. On this head these all pass:
First Principles: does the rewritten |
761f6f6 to
7f106e2
Compare
|
Rebased: main changed The new function is ported unchanged into its owner, |
e98cdb1 to
5cb8dc9
Compare
|
Rebased: main changed
This head supersedes |
|
|
platform_compat.py is 11,211 lines, far past the 2,000-line cap. This first of two PRs moves its lower layers, unchanged, into twelve sibling owner modules: the native flags and Win32 layouts, the kernel process table, the interpreter and process image, the no-replace rename and TCC pruning, path and binary trust, liveness, identity, ports, descendant walks, Windows process handles, owned Windows trees, and termination. platform_compat.py drops to 3,721 lines. platform_compat.py stays the import and patch surface. It installs kiro_crew._facade_mirror, so a patch through kiro_crew.platform_compat reaches every carved owner that binds the name, as it reached the one module before. The lock and owner-only modules keep their single-owner forwarding. Every owner logs as kiro_crew.platform_compat. The facade-mirror guards' corpus scan answers its per-file mention test from one pass over each file's text instead of one regex per spelling, so the census stays well inside the per-test timeout now that platform_compat adds 283 spellings. It selects exactly what it selected before. Part of #20192
5cb8dc9 to
c30ff5a
Compare
|
Rebased: main changed The conflict was one cite line. Main renamed |
|
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved on the watch holder's request. Every check on the head passes; the triage cron held it on a size, path, checklist or lane-note rule. Any standing lane note stays on the record.
Problem / Motivation
Goal:
src/kiro_crew/platform_compat.pymoves its lower layers, unchanged, into twelve focused owner modules, with every import path, patch target and behaviour kept, as the first of two steps that bring it under the 2,000-line cap.platform_compat.pyis 11,211 lines. Kiro Crew is adopting a hard rule that no hand-written file exceeds 2,000 lines (#20192), and this file changes about 14 times a week. Moving it in one PR would make a diff of about 1.05 MB, past the 1 MB cap the Design, UX and Security Scope review lanes enforce. So the move is split into two stacked PRs of at most 900 KB each. This PR moves everything above the file-permission helpers, plus the/procreaders and the process alarm and clocks that code reads.Why it matters
Every POSIX call in the codebase routes through this one module, so it is where cross-platform bugs are fixed, and an 11k-line file buries each fix among unrelated platforms and process families. Every feature PR that touches it also trips the line-cap guard. Splitting it mechanically keeps feature work unblocked and makes each family — the macOS process table, liveness, identity, ports, the Windows process trees, termination — reviewable on its own.
Not a goal
kiro_crew._facade_mirror(refactor: add a mirror-aware facade helper for module splits #20337).What changed (motivation → approach → change)
platform_compat.pyalready forwarded the file locks and the owner-only helpers to two modules, but those owners read the platform flags and lock modules back from it at call time, and no owner could import another. Its code is one reference graph, and tests patch names it only imports (IS_WINDOWSat 757 sites,time,ctypes,sys). So any split that keeps the code unchanged needs owners that import each other, plus a facade whose patches reach every owner. That is the campaign's shared mirror,kiro_crew._facade_mirror, assandbox.pyalready uses it.platform_compat_native.pyplatform_compat_proctable.pylibproc/sysctl, Linux/proc, file holders andflockownersplatform_compat_runtime.pyplatform_compat_files.pyplatform_compat_trust.pyplatform_compat_liveness.pyplatform_compat_identity.pyplatform_compat_ports.pyplatform_compat_descendants.pyplatform_compat_winproc.pyplatform_compat_wintree.pyplatform_compat_kill.pyos.killpg/kill_pid/kill_process_treecall,pgroup_existsincluded, because the kill-chokepoint ratchet exempts this one fileHow the facade works:
logging.getLogger("kiro_crew.platform_compat")(L25).platform_compat_<role>.pysiblings, not a package. The Cross-Platform Portability gate excludes them by name with one added pathspec row,:(exclude)src/kiro_crew/platform_compat_*.py, beside itsplatform_compat.pyexclude, so the moved POSIX primitives stay unscanned as they were. Itssrc/kiro_crew/**/*.pypathspec matches no top-level module today either (cross-platform gate never scans top-level src/kiro_crew modules (pathspec '**' needs a sub-directory) #21019). The owning spec records this.platform_compat.py(11,216 -> 3,722 lines on main) keeps its BASE imports (# noqa: F401where its own code no longer reads one), binds the moved names its remaining code reads one per line (# noqa: E402), and installs_facade_mirror.install(..., excluded=(), forwards=<the lock and owner-only table>). A write through the facade lands on every carved owner that binds the same object; the lock and owner-only modules keep their single-owner forwarding.kill_pid(patched with unpacked keyword arguments) and the three helperstest_skill_discoverreads fromvars(platform_compat).test/facade_mirror_scan.py, which the mirror guards use to find every test that patches through a mirrored facade, answers its per-file mention test from one pass over each text instead of one regex per spelling. platform_compat adds 283 spellings, and the old scan pushed the census past CI's 120 s per-test timeout; the new one selects exactly the same files (Master grant). Only plain module names (dotted ASCII identifiers) take that path; any other name still runs main's patterns, and main's alias-of-parent check (_alias_chain, test: route alias-of-parent facade patches to the syntax tree (#21652) #21786) applies on both paths.Backwards compatibility
Compatible: every name
kiro_crew.platform_compatbound at BASE still resolves to the same object (test/campaign_facade_inventories/kiro_crew.platform_compat.jsonfreezes its 222 names fortest_campaign_facades_base_public_names),__all__is identical (279 names), and every patch through the facade still reaches every reader (test_facade_mirror_guards,test_platform_compat_refactor_facade).Each public
defthis PR moves stays importable fromkiro_crew.platform_compat(served or bound by the facade). One line per owner names all 128 of them:Reader: src/kiro_crew/platform_compat.py:darwin_child_pids,darwin_established_tcp_count,darwin_footprint_tree_mb,darwin_kinfo_proc,darwin_libproc_available,darwin_pgroup_members,darwin_pid_is_zombie,darwin_process_argv,darwin_process_environ,darwin_process_facts,darwin_process_path,flock_owner_pid,linux_pgroup_members,parent_pid,pids_holding_file,proc_child_map,proc_cpu_jiffies_for_pids,proc_phys_footprint_bytes_for_pid,read_proc_stat,read_proc_status_int -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_proctable and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:arm_process_alarm,awake_now,boottime_now,cancel_wheel_applies_in_flight,ensure_line_buffered_stdout,ensure_utf8_console,execv_target_available,exit_after_failed_restart_exec,hard_exit,is_bundled_interpreter,is_windows_on_arm,isolated_python_argv,keep_for_reexec,kept_for_reexec,process_age_secs,process_alarm_available,process_start_boot_secs,reexec_launcher,reexec_python_module -- 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:publish_dir_noreplace,rename_noreplace,tcc_protected_dirs_for_walk,tcc_prune_walk_dirs -- 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:aws_bin_declined_on_ownership,env_key_allowed,group_write_admits_another_account,open_with_default_app,reveal_in_file_manager,short_path_name,tool_outside_trusted_dirs,traversed_components,traversed_components_and_links,trusted_aws_bin,trusted_git_bin,trusted_system_bin,trusted_system_bin_quiet,trusted_system_path,windows_documents_dir,windows_powershell_profile_paths -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_trust and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:is_thread_group_leader,live_thread_group_leaders,pgroup_of,pgroup_of_leader,pid_exists,pid_is_zombie,pid_liveness,process_thread_count -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_liveness and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:effective_uid,get_ppid,get_process_start_id,get_process_start_identity,is_exec_supervisor_of_this_process,linux_process_name,own_process_start_time,process_argv_fingerprint,process_argv_matches_exact,process_can_read_under_sandbox,process_cgroups_match,process_command_line,process_cwd,process_executable_path,process_image_name,process_incarnation_id,process_is_sandboxed,process_matches,process_namespaces_match,process_owner_uid,process_start_id_for_source,process_start_time -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_identity and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:address_covers_loopback,find_listening_pids,find_port_listeners,get_tcp_peer_pid,listening_pid_tool,listening_pid_tool_available,loopback_owner_pids,probe_port_listeners,process_owns_loopback_listener -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_ports and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:attributed_descendants,created_after,process_descendant_identities,process_descendants -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_descendants and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Reader: src/kiro_crew/platform_compat.py:close_process_handle,descendant_termination_handles,descendant_termination_handles_async,duplicate_asyncio_process_handle,open_process_termination_handle -- 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:create_windows_cleanup_owned_process,finish_windows_cleanup_owned_spawn,process_handle_active,release_windows_tree_reservation,reserve_windows_tree_cleanup,retry_pending_windows_process_trees,terminate_process_handle,terminate_windows_asyncio_tree,terminate_windows_process_tree_owned -- 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)Reader: src/kiro_crew/platform_compat.py:kill_and_reap,kill_pid,kill_pid_async,kill_pid_pinned,kill_popen_tree,kill_process_group,kill_process_tree,kill_process_tree_async,kill_process_tree_pinned,pgroup_exists,terminate_and_reap,terminate_and_reap_sync -- chat -- each is the same object at
kiro_crew.platform_compat.<name>, defined in platform_compat_kill and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)Tests
test/test_platform_compat_refactor_facade.py(Master grant):_CARVEDmerged into_OWNERS,_MOVEDrows per owner,_BOUND_HEREpassed tocheck_forwarded_and_bound_are_disjoint(the test is renamed to say so), a_CARVED_IMPORTSedge table passed tocheck_owner_dependency_direction,mirrored=/carved=on the two shared-bindings checks, and two parity tests: the mirror indexes exactly_CARVED_OWNERSwith no divergence, and the lock and owner-only modules stay out of it.test/campaign_facade_inventories/kiro_crew.platform_compat.json: the facade's frozen inventory (222 BASE public names and the 5 names it re-binds from other modules), whichtest_campaign_facades_base_public_namesloads.test_kill_chokepoint_ratchet.py:PRIMITIVE_HOMEisplatform_compat_kill.py, which holds all ten exempt calls; the count stays 67;test_spawn_audit.py(12BENIGN_SPAWNSkeys),test_windows_kill_probe_audit.py(2GATED_PROBESkeys),test_internal_python_isolation.py(1 row),test_jsonl_util.py(kernel pseudo-file rows);test_sel_hard_exit_flush.py's_PATHS,_EXEMPTkey and restart-exec test readplatform_compat_runtime.py, wherehard_exitlives.platform_compat.pyat BASE read the facade plus everyplatform_compat_*.pyowner, by glob, with their assertions unchanged:test_sel_hard_exit_flush.py_MODULES(every hard exit drains the audit queue): an undrainedos._exitplanted in the facade, or inplatform_compat_wintree.py, turns it red;test_docs_mock_pid_convention.py_public_kill_helpers()(every public kill/reap helper is named in the doc): adef kill_probe_x()planted in the facade, or inplatform_compat_wintree.py, turns it red.Their docstrings name the family instead of the one file.
test/facade_mirror_scan.py(Master grant):_mentionsreads each text once for itsfrom ... importlists (_from_imports) and once per text and leaf for<parent>.<leaf>and relative spellings (_leaf_parts), and_Bindingslooks spellings up by dotted prefix. Equivalence, old against new over the whole test tree (4,501 files, all four mirrored facades): 0 disagreements; the same 1,205 (file, spelling) mentions, the same 920-file family, and identicalneeds_syntax_tree, text-patched names, routed patch names and 57,967 patch events (sha256 digests in the move report). With CI's coverage flags and--timeout=120, the census takes 32 s, the namespace-write scan 14 s and thecreate_truescan 3 s run together (41 s, 37 s and 22 s each alone); with the old scan the census took about 155 s..github/file-line-cap-baseline.txtkeeps main'splatform_compat.pyrow as it is, because the file stays over the cap until the second step, which deletes the row;.github/subprocess-encoding-baseline.txtdrops itsplatform_compat.pyrow (see below).Local gate floor. The related set, mypy and semgrep ran on a tree that differs from this head only by the liveness module's summary line and the rebase onto main (
git range-diffshows=); the tree scans, integration and wheel smoke ran one step earlier, before the six__module__pins (whose own tests ran after them); the mirror guards, the line cap and the re-pointed pins re-ran at this head:run_scoped_testsbackend set: every test that references a changed file): 48,320 passed, 0 failed, 5 xfailed;--timeout=120: 13,363 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: 514 each;test/facade_mirror_scan.py: 81 each).scripts/local-gate.py --dry-runselects 630 backend and 363 frontend (cross-surface) files, past the 600-file local cap, so the floor above ran instead (SD14). No file underwebsite/changed.The three
subprocess.check_output(..., text=True)calls the encoding baseline counted (probe_port_listeners,process_command_line,process_owner_uid) carry the gate's# subprocess-encoding: localemarker with its reason (darwinpsandlsofwrite their output in the user's locale). The markers record a deliberate locale decode that matches BASE, and they replace the 3-count baseline row.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 (17, 417 lines), each glue or a gate-required wording edit:
_EXPORTS_BY_OWNER(now_FORWARDS_BY_OWNERplus a derived table), theTYPE_CHECKINGmanifest,_ReExportModule,_owner,_index_exports,if not TYPE_CHECKING: __getattr__,_EXPORTS, the class swap;process_command_line("Used to", "KiroCrew"),ensure_utf8_console("KiroCrew"),process_matches,process_owner_uid,process_thread_count,parent_pid,address_covers_loopback("Used to"),_darwin_process_cpu_nanos,_darwin_process_cwd("no longer").Outside the replaced machinery, 97.1% of the moved lines are byte-identical by AST. Comment-only edits (the encoding markers, three comments that name where code now lives, a brand fix in a comment) do not change the AST.
Observable difference (L24, reported to the Master): reading a forwarded lock or owner-only name through
kiro_crew.platform_compatafter a test deletes it from its owner raisesAttributeErrornamingkiro_crew.platform_compatinstead of the owner module.hasattr,getattrwith a default,dir()and the unknown-name message are unchanged, and no test or caller reads that text.Logger names (L25): every carved owner that logs uses
logging.getLogger("kiro_crew.platform_compat"), the BASE logger, because tests and log filters read that name.Class
__module__: the six moved exception and enum classes (WindowsCleanupCapacityError,_WindowsTreeOverflow,WindowsTreeDrainPending,_DarwinLibprocUnavailable,ProcessIdentitySource,_ProcessStartOrder) keep__module__ == "kiro_crew.platform_compat", set right after each class, so tracebacks, logs and pickles render the BASE path; a test pins it and that the list is complete. Every other moved class keeps its owner's__module__:NamedTuplerows (their repr omits the module), the privatectypesstructures and_PendingWindowsTreeCleanup, which nothing renders; no test, log or caller reads their module.Prose citations (L29):
docs/guides/windows-install.md(_ThreadEntry32lives inplatform_compat_native) anddocs/system-specs/modules/app-kit-platform.md(platform_compat_wintree.py), and theBUNDLED_BACKEND_DIST_DIRNAMEcomment insrc/kiro_crew/platform_compat_runtime.py, which names the test that pins it:test_platform_compat.py->test/test_platform_compat_pinned_tools.py, whereTestIsBundledInterpreterlives on main.References not edited (cost, L50):
website/electron/gateway-env.js:16saysplatform_compat.py republishes the same invariant; the republish (_ensure_utf8_process_environment) is defined insrc/kiro_crew/platform_compat_runtime.pyand runs on import ofkiro_crew.platform_compat.CI path references
.github/workflows/macos-on-demand.yml: thedarwinfilter lists the twelve new owner files aftersrc/kiro_crew/platform_compat.py. No logic change..github/workflows/ci.yml: thewindowspath filter lists'src/kiro_crew/platform_compat_*.py'aftersrc/kiro_crew/platform_compat.py, so a fork PR that edits the moved Windows code still runs Backend Tests (Windows). No logic change..github/workflows/cross-platform.yml: one pathspec row,':(exclude)src/kiro_crew/platform_compat_*.py', after theplatform_compat.pyexclude, so the gate exempts the moved code as it exemptedplatform_compat.py. No logic change.Related Issues
Part of #20192
Follow-up: #21320 (the comment citation listed under References not edited)
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).