[nareshns2004]

Rebuilding as kptk: kernel performance analysis toolkit

Replace the scaffold scripts with kptk, a stdlib-only Python package that records Linux kernel counters and explains why a workload is slow. Every finding includes the counters behind it and a concrete fix

Package (src/kptk/):

• record: low-overhead recorder that saves raw /proc and /sys text to .jsonl.gz (~1.4 ms/sample); numa_maps and smaps_rollup are read less often
• perf_event: ctypes bindings for perf_event_open(2) using the fork/attach/enable_on_exec handshake, with multiplexing correction
• parsers: pure parsers for procfs, sysfs and external tool output
• analysis: cpu (run-queue delay, PSI, preemption), memory (faults, direct reclaim, swap), numa (placement vs thread residency, SLIT), cache (IPC, LLC MPKI), hugepages (THP fallback, compaction stalls), plus the findings engine and time windowing
• topology: CPU/NUMA/cache layout, THP/hugetlb state, sysctl audit
• report/compare: Markdown/JSON reports with a USE table and sparklines; A/B comparison with a permutation test
• synth: synthetic two-socket scenarios for kptk demo
• cli: inspect, record, profile, analyze, compare, demo; --fail-on gives an exit code usable as a CI gate

Added:

• C microbenchmarks: false_sharing, mem_latency, page_fault_cost, wakeup_latency
• docs: architecture, metric reference, kernel mechanics, design ADRs, worked examples
• samples: real laptop recording and synthetic NUMA-misplacement scenario, each with its generated report
• pyproject.toml with the kptk entry point, Makefile targets, GitHub Actions CI (ruff, mypy, pytest, bench build, CLI smoke test),
  Apache-2.0 LICENSE, CHANGELOG
• new tests for parsers, analysis, CLI, perf_event and recording/topology (42 passed, 1 skipped)

Removed the old flat src/*.py modules, placeholder C benchmarks, YAML configs, shell scripts and old tests; kptk replaces them.

BREAKING CHANGE: the old src/*.py entry points are gone; use the kptk CLI.