Skip to content

refactor(platform_compat): carve the remaining helpers into owner modules - #22044

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/linecap-s03-platform-compat-p2
Oct 19, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/linecap-s03-platform-compat-p2

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: src/kiro_crew/platform_compat.py moves 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.py into 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

  • No behaviour change: no probe, refusal, message, log line, timeout or default changes. Every moved unit is byte-identical except comment and docstring wording.
  • No change to kiro_crew._facade_mirror, to the twelve owners' existing code, or to which names kiro_crew.platform_compat offers.
  • No new behaviour test.

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:

Owner Takes Lines
platform_compat_links.py (new) links and junctions, the first linked ancestor, the extended-length prefix fold, the pinned directory, the opens that never follow a link at the final name 845
platform_compat_metrics.py (new) resident and peak memory, heap trimming and the malloc arena cap, open descriptors, CPU time, subtree samples, host memory, CPU load and memory pressure 1,357
platform_compat_files.py permission changes that never raise, rmtree_force, the log-tail and lock-sweep opens, owner access on a copied tree, the remote-volume, executable-file and read-only checks 356 -> 709
platform_compat_runtime.py interpreter discovery, the launcher hops, strftime, the open-file limit 616 -> 807
platform_compat_winproc.py the Windows Job object and main-thread resume 540 -> 835
platform_compat_wintree.py the tree pending check and the owned-spawn capture 676 -> 821
platform_compat.py the mirror glue 3,726 -> 799

The 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_mirror carries a patch through the facade to every moved reader, as it does for #21000's owners. The owning spec lists the final owners, the macOS darwin filter names the two new files, the facade's line-cap row is deleted, and the rows and citations that named platform_compat.py for moved code now name the owner.

Backwards compatibility

Compatible: every name kiro_crew.platform_compat bound before this PR still resolves to the same object (test/campaign_facade_inventories/kiro_crew.platform_compat.json freezes its 223 names for test_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 through kiro_crew.platform_compat. That is the design #21000 used for its owners; a hot call site can bind the helper once.

Each public def this PR moves stays importable from kiro_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.
  • Path re-points (L30), each proved by a mutation that turns its test red:
    • test/link_screen_sites.py, regenerated by test/gen_link_screen_sites.py: the ensure_owner_rwx_dirs site is now in platform_compat_files.py (181 sites, as before);
    • test_jsonl_util.py: the /proc/meminfo kernel pseudo-file row names platform_compat_metrics.py;
    • test_spawn_audit.py: the find_python_interpreter BENIGN_SPAWNS key and its comment name platform_compat_runtime.py.
  • The two universal pins refactor(platform_compat): carve the lower layers into owner modules #21000 joined over the facade and every owner (test_sel_hard_exit_flush.py, test_docs_mock_pid_convention.py) need no edit: an undrained os._exit or a kill_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):

  • 1,030 related and tree-scanning test files at -n 3 (a superset of the 730 run_scoped_tests selects; the one file outside it ran separately): every test passed except the three link-screen tests the regenerated row fixes and test_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;
  • mypy clean (3,095 files); flake8, isort and black clean; docs lint passed; flake-pattern ratchet passed; line-cap check 0 failures;
  • brand, comment-history, harness-parity and subprocess-encoding checks clean;
  • semgrep (CI configs) over every changed Python file: 0 results, 0 errors;
  • installed-wheel smoke: the wheel ships every owner, and each imports from site-packages;
  • per-file coverage, projected from refactor(platform_compat): carve the lower layers into owner modules #21000's CI coverage (moved code is byte-identical): every owner at or above 83%;
  • the diff measures 341,419 bytes; git diff and git diff --minimal add the same lines in every changed file (platform_compat.py: 174 each).

scripts/local-gate.py --dry-run selects 730 backend and 377 frontend (cross-surface) files, past the 600-file local cap, so the floor above ran instead. No file under website/ 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

src/kiro_crew/platform_compat.py: 3726 -> 799 lines; moved 83.47% (python-ast)

Changed units (5): the facade's TYPE_CHECKING manifest (407 lines) and _CARVED_OWNERS (14 lines), which are glue that lists the two new owners, and three docstrings: find_python_interpreter and is_executable_file ("KiroCrew" to "Kiro Crew", which the brand gate requires) and pinned_dir_flags, whose "imports THIS module" now says pinned_fs imports kiro_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_metrics and platform_compat_files log as logging.getLogger("kiro_crew.platform_compat"); platform_compat_links does not log.

Class __module__: PR2 moves no exception or enum class. PinnedDirectory, HeapTrimMaintainer, the NamedTuple rows and the private ctypes structures keep their owner's __module__; no test, log or caller reads it.

Prose citations (L29): docs/guides/windows-install.md (_VMStatistics64 lives in platform_compat_metrics), docs/architecture/resource-protection.md (apply_job_limits in platform_compat_winproc.py), two comments in scripts/check_lockdown_before_publish.py (fchmod_safe and chmod_safe in platform_compat_files.py), and the execv_target_available docstring in platform_compat_runtime.py (is_executable_file is in platform_compat_files).

CI path references

  • .github/workflows/macos-on-demand.yml: the darwin filter lists src/kiro_crew/platform_compat_links.py and src/kiro_crew/platform_compat_metrics.py beside the other owners. No logic change.
  • .github/workflows/cross-platform.yml and .github/workflows/ci.yml already match the new owners through the platform_compat_*.py globs refactor(platform_compat): carve the lower layers into owner modules #21000 added; no edit.

Related Issues

Part of #20192

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

Contribution License Agreement

Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).

…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
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 19, 2026 03:29
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision eec0b478f4b4cabb392d101d3a8bcdd22d163244 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of eec0b478f4b4cabb392d101d3a8bcdd22d163244 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of eec0b478f4b4cabb392d101d3a8bcdd22d163244 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check the hot loops that read platform_compat.proc_rss_bytes and the other metrics helpers through the facade: each read now takes about 2.3 µs through __getattr__, where it took about 0.1 µs.

What this change ships

Inventory (7 items) — 7 justified

Intent: bring platform_compat.py under the 2,000-line cap (an AGENTS.md invariant) by moving its helpers, unchanged, into owner modules. This is a FIX for a violated invariant, not an ADDITION.

  1. The link, junction and no-reparse helpers move into the new platform_compat_links.py — justified
  2. The process and host metrics helpers move into the new platform_compat_metrics.py — justified
  3. The file-permission, runtime, Windows Job object and tree-pending helpers move into the four owners that already exist — justified
  4. platform_compat.py shrinks to the mirror glue, and its row leaves the line-cap baseline — justified
  5. The macOS on-demand path filter now names the two new owners — justified
  6. Specs, docs and script comments that cited the moved code now name its owner — justified
  7. The facade owner tables, the link-screen sites and the spawn-audit and jsonl path rows are re-pointed to the owners — justified

[FIRST-PRINCIPLES-REVIEWED] eec0b47

Description read

[DESCRIPTION-READ] f9ddb0ed90c17e7f940fd29e30345b6933185d0d7b9994f0786713fea265dcfd

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] eec0b47

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

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] eec0b47

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

@bolichen97
bolichen97 enabled auto-merge (squash) October 19, 2026 03:35
Comment thread src/kiro_crew/platform_compat_links.py Dismissed
Comment thread src/kiro_crew/platform_compat_links.py Dismissed
Comment thread src/kiro_crew/platform_compat_links.py Dismissed
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 19, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • PASS punchline: does the slower lookup of moved names land in a hot call path (metrics helpers in monitoring loops)?

checked: no. Measured on Linux at this head: a served lookup such as platform_compat.proc_rss_bytes costs 1.4 µs, against 21.5 µs for the proc_rss_bytes() call itself and 18.0 µs for host_available_mib(), so it adds under 7% to one sample. A name the facade still binds (is_link_or_junction, 197 read sites) stays a 0.1 µs dict hit.
Every facade read of a moved metrics helper is one lookup per sample, not per iteration: metrics/process_gauges.py gauge callbacks, adaptive/controller.py, dashboard/handlers_system.py requests, diag/recorder.py, mcp_gateway/pool.py, subagent_parts/host_memory.py and session_pid_rss.py samplers. The loops inside the helpers (proc_subtree_sample walking a subtree, the /proc readers) read their own owner's globals, so they never pass through the facade.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • PASS punchline: the hot loops that read the metrics helpers through the facade now pay about 2.3 µs per read

checked: none of them is a hot loop. Measured on Linux at this head, a served facade lookup costs 1.4 µs while the call it precedes costs 21.5 µs (proc_rss_bytes()) or 18.0 µs (host_available_mib()), because each call reads /proc.
The callers read the helper once per sample: gauge callbacks (metrics/process_gauges.py), the adaptive controller, dashboard system handlers, the diag recorder, the gateway pool and the subagent host-memory samplers. Iteration happens inside the moved helpers, which read their owner's own globals and never the facade. A caller that does turn hot can bind the helper once, as the description says.

@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 19, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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.

@bolichen97
bolichen97 merged commit 72188eb into main Oct 19, 2026
107 checks passed
@bolichen97
bolichen97 deleted the refactor/linecap-s03-platform-compat-p2 branch October 19, 2026 05:50
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 19, 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.

3 participants