{"id":51319539,"url":"https://github.com/manishklach/kairo-io","last_synced_at":"2026-07-01T11:31:33.343Z","repository":{"id":366385434,"uuid":"1276094045","full_name":"manishklach/kairo-io","owner":"manishklach","description":"Linux-kernel RFC/POC for AI KV-cache-aware block I/O, decode-read prioritization, and generic NVMe SSD scheduling.","archived":false,"fork":false,"pushed_at":"2026-06-21T15:42:09.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T16:24:38.501Z","etag":null,"topics":["agentic-ai","ai-inference","benchmarking","block-layer","io-uring","kernel-scheduler","kv-cache","linux-kernel","llm-inference","mq-deadline","nvme","performance-engineering","poc","rfc","ssd","storage-systems","systems-research","zns","zoned-storage"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/manishklach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-21T14:32:33.000Z","updated_at":"2026-06-21T15:42:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/manishklach/kairo-io","commit_stats":null,"previous_names":["manishklach/kv-io"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/manishklach/kairo-io","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manishklach%2Fkairo-io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manishklach%2Fkairo-io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manishklach%2Fkairo-io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manishklach%2Fkairo-io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manishklach","download_url":"https://codeload.github.com/manishklach/kairo-io/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manishklach%2Fkairo-io/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35005409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-inference","benchmarking","block-layer","io-uring","kernel-scheduler","kv-cache","linux-kernel","llm-inference","mq-deadline","nvme","performance-engineering","poc","rfc","ssd","storage-systems","systems-research","zns","zoned-storage"],"created_at":"2026-07-01T11:31:30.297Z","updated_at":"2026-07-01T11:31:33.336Z","avatar_url":"https://github.com/manishklach.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kairo\n\n[![License](https://img.shields.io/badge/license-GPL--2.0-blue)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/manishklach/kairo-io?display_name=tag\u0026label=release)](https://github.com/manishklach/kairo-io/releases)\n[![Last Commit](https://img.shields.io/github/last-commit/manishklach/kairo-io)](https://github.com/manishklach/kairo-io/commits/main)\n[![Status](https://img.shields.io/badge/status-RFC%2FPOC-orange)](.)\n\n**Kernel AI Runtime I/O for KV-cache-aware Linux storage**\n\nKairo is a Linux-kernel RFC/POC exploring a missing systems layer for AI inference: **storage I/O that understands KV-cache traffic, decode-critical reads, prefetch pressure, recomputable cache data, model/session locality, and backend placement intent.**\n\nModern AI inference is no longer just a GPU problem. Long-context models, agentic workloads, multi-session serving, KV-cache reuse, and flash-backed memory tiers are creating new storage traffic patterns that traditional block schedulers were not designed to distinguish. Today, much of this traffic still reaches the kernel as ordinary reads and writes.\n\nKairo asks a simple question:\n\n\u003e What if the Linux storage stack could understand AI inference I/O as a first-class workload?\n\nThis repository explores that question through kernel patches, benchmark tooling, tracepoint scaffolding, and Linux 6.8.x integration scripts.\n\n---\n\n## Why Kairo Exists\n\nAI inference increasingly depends on memory objects that are:\n\n* too large to keep entirely in HBM or DRAM,\n* too valuable to treat as cold storage,\n* latency-sensitive during decode,\n* often session-scoped or model-scoped,\n* frequently recomputable or short-lived,\n* and increasingly backed by NVMe SSDs or flash memory tiers.\n\nTraditional storage systems mostly see:\n\n```text\nread\nwrite\ndiscard\nflush\n```\n\nAI runtimes know much more:\n\n```text\ndecode-critical read\nprefetch read\nprefill write\neviction cleanup\nsession-local KV cache\nmodel-local KV cache\nrecomputable cache\nshort-lived placement group\n```\n\nKairo explores how that higher-level intent could flow into the Linux block layer and, eventually, into generic NVMe backend placement mechanisms.\n\n---\n\n## Core Idea\n\nKairo introduces a research path for classifying and scheduling AI inference I/O:\n\n```text\nAI runtime / benchmark\n    -\u003e hint path\n    -\u003e request classification\n    -\u003e mq-deadline scheduling policy\n    -\u003e semantic and placement metadata\n    -\u003e generic backend mapping scaffold\n    -\u003e tracepoint observability\n```\n\nThe current implementation focuses on:\n\n* decode-read prioritization under mixed read/write pressure,\n* prefetch-aware scheduling,\n* prefill-write and eviction demotion accounting,\n* model/session/cache-pool/lifetime metadata,\n* generic backend mapping scaffolds for Streams/FDP/ZNS-style placement,\n* structured benchmark experiments,\n* sysfs counters,\n* and kernel tracepoint observability scaffolding.\n\n---\n\n## Project Status\n\nKairo is currently an **internal RFC/POC**.\n\nIt is not intended for LKML submission at this stage.\n\nThe repo contains two parallel tracks:\n\n### 1. Compile-targeted Linux 6.8.x foundation stack\n\nLocated under:\n\n```text\nkernel/patches/foundation/\n```\n\nThis is the smaller kernel-core subset intended for local Linux 6.8.x apply/build experiments.\n\nIt covers:\n\n* request classification,\n* `ioprio` fallback mapping,\n* `mq-deadline` decode priority,\n* prefetch deadline handling,\n* prefill-write demotion accounting,\n* eviction/discard accounting,\n* and sysfs tunables/counters.\n\n### 2. Broader RFC/POC architecture series\n\nLocated under:\n\n```text\nkernel/patches/\n```\n\nThis preserves the full Kairo architecture direction, including:\n\n* request classification,\n* decode-read priority,\n* prefetch/prefill/evict scheduling,\n* request-shape and merge instrumentation,\n* `io_uring` / `RWF_*` hint plumbing,\n* ephemeral and recomputable cache semantics,\n* model/session/lifetime placement metadata,\n* generic NVMe backend mapping hooks,\n* tracepoint observability,\n* recompute-aware eviction policy,\n* KV-cache residency heatmap tracking,\n* and KV admission control for flash-backed storage.\n\n## Current Validation Snapshot\n\nKairo includes a WSL-friendly validation runner:\n\n```bash\n./scripts/run_wsl_validation_snapshot.sh\n```\n\nThis checks repository consistency, benchmark build, experiment harness\ndry-runs, and optional user-space benchmark smoke tests. It does not claim\npatched-kernel runtime validation.\n\nLatest snapshots:\n\n* [docs/validation_snapshot.md](docs/validation_snapshot.md) — WSL repo consistency + dry-runs\n* [docs/qemu_validation.md](docs/qemu_validation.md) — QEMU stock-kernel module/sysfs validation (44/44 simulated counters)\n\n---\n\n## Why This Matters\n\nKairo targets a real emerging systems problem:\n\n\u003e AI inference workloads are beginning to use storage as an active memory tier, but the kernel still lacks AI-aware request semantics.\n\nWithout richer I/O classification, the block layer cannot easily distinguish:\n\n```text\nA decode-critical KV-cache read\nfrom\nA background prefill write\nfrom\nA recomputable cache eviction\nfrom\nAn ordinary durable application write\n```\n\nThat distinction matters because decode latency can dominate perceived inference latency. If decode reads are delayed behind background writes, eviction cleanup, or poorly shaped prefetch traffic, the storage tier becomes part of the inference tail-latency problem.\n\nKairo explores whether Linux can expose a better path.\n\n---\n\n## Architecture\n\n```text\n+------------------------------------------------------------------+\n| AI Runtime / Synthetic Benchmark                                 |\n|                                                                  |\n|  - decode reads                                                   |\n|  - prefetch reads                                                 |\n|  - prefill writes                                                 |\n|  - eviction / discard                                             |\n|  - model, session, cache-pool, lifetime metadata                  |\n+------------------------------------------------------------------+\n                         |\n                         v\n+------------------------------------------------------------------+\n| User-Space Hint Path                                             |\n|                                                                  |\n|  - ioprio fallback                                                |\n|  - O_DIRECT                                                       |\n|  - io_uring / RWF_* scaffold                                      |\n|  - semantic hints: ephemeral, recomputable, avoid-pagecache       |\n+------------------------------------------------------------------+\n                         |\n                         v\n+------------------------------------------------------------------+\n| Kairo Block-Layer Metadata                                       |\n|                                                                  |\n|  - request classification                                         |\n|  - decode / prefetch / prefill / evict classes                    |\n|  - model_id / session_id / cache_pool_id                          |\n|  - lifetime_class / recompute_ok                                  |\n|  - backend placement intent                                       |\n+------------------------------------------------------------------+\n                         |\n                         v\n+------------------------------------------------------------------+\n| Kairo-Aware Scheduling                                           |\n|                                                                  |\n|  - decode-critical read priority                                  |\n|  - prefetch deadline and budget handling                          |\n|  - prefill-write demotion                                         |\n|  - eviction/discard demotion                                      |\n|  - starvation accounting                                          |\n+------------------------------------------------------------------+\n                         |\n                         v\n+------------------------------------------------------------------+\n| Generic NVMe Backend Mapping Scaffold                            |\n|                                                                  |\n|  - backend class mapping                                          |\n|  - no-op fallback                                                 |\n|  - Streams/FDP/ZNS-style hook locations                           |\n|  - no physical placement claimed yet                              |\n+------------------------------------------------------------------+\n                         |\n                         v\n+------------------------------------------------------------------+\n| Observability                                                    |\n|                                                                  |\n|  - sysfs counters                                                 |\n|  - benchmark summaries                                            |\n|  - tracepoint scaffold                                            |\n|  - bpftrace/ftrace analysis scripts                               |\n+------------------------------------------------------------------+\n```\n\n---\n\n## Kernel Patch Tracks\n\n### Compile-targeted foundation stack\n\n```text\nkernel/patches/foundation/\n  0001-kairo-request-classification.patch\n  0002-kairo-mq-deadline-decode-priority.patch\n  0003-kairo-prefetch-prefill-evict-policy.patch\n  0004-kairo-mq-deadline-sysfs-counters.patch\n```\n\nUse this path for local Linux 6.8.x apply/build experiments.\n\n### Full RFC/POC architecture series\n\n```text\nkernel/patches/\n  0001-rfc-kairo-mq-deadline-decode-priority.patch\n  0002-rfc-kairo-request-classification.patch\n  0003-rfc-kairo-io-uring-hint-plumbing.patch\n  0004-rfc-kairo-large-block-coalescing.patch\n  0005-rfc-kairo-prefetch-deadline-hints.patch\n  0006-rfc-kairo-ephemeral-cache-semantics.patch\n  0007-rfc-kairo-placement-lifetime-hints.patch\n  0008-rfc-kairo-nvme-zns-fdp-mapping.patch\n  0009-rfc-kairo-sysfs-debug-counters.patch\n  0010-rfc-kairo-request-classification-real.patch\n  0011-rfc-kairo-write-antistarvation-deadline.patch\n  0012-rfc-kairo-nvme-tag-reservation.patch\n  0013-rfc-kairo-mq-deadline-dispatch-O1.patch\n  0014-rfc-kairo-io-uring-sqe-hint-flag.patch\n  0015-rfc-kairo-merge-bias-real.patch\n  0016-rfc-kairo-bpf-dispatch-hook.patch\n  0017-rfc-kairo-tracepoints-observability.patch\n  0018-rfc-kairo-adaptive-latency-controller.patch\n  0020-rfc-kairo-model-session-fairness.patch\n  0022-rfc-kairo-foundation-tracepoints-linux-6.8.patch\n  0023-rfc-kairo-decode-latency-histogram.patch\n  0024-rfc-kairo-controller-feedback-wiring.patch\n  0025-rfc-kairo-fairness-accounting-sysfs.patch\n  0026-rfc-kairo-blkcg-ai-io-controller.patch\n  0027-rfc-kairo-io-uring-kv-region-hints.patch\n  0028-rfc-kairo-recompute-aware-eviction.patch\n  0029-rfc-kairo-kv-residency-heatmap.patch\n  0030-rfc-kairo-kv-admission-control.patch\n```\n\nThis broader series is the architecture map. Not every patch in this track is compile-targeted yet, and numbering intentionally has gaps where intermediate local RFC ideas were not retained in the repo.\n\n---\n\n## Current Stages\n\n| Stage | Scope | Patch / Track | State |\n| --- | --- | --- | --- |\n| Foundation | Linux 6.8.x compile-targeted subset | foundation `0001`-`0005` | locally apply/build validated |\n| Stage 6 | model/session/lifetime placement experiments | `0007`, `0009` | implemented in benchmark and harness |\n| Stage 7 | generic NVMe backend mapping scaffold | `0008`, `0009` | implemented as generic mapping scaffold |\n| Stage 7.5 | NVMe hook audit and risk classification | `0008` rewrite + audit docs/scripts | implemented |\n| Stage 8 | observability and trace scaffolding | `0017` | scaffolded in broad RFC/POC series |\n| Stage 9 | WSL validation snapshot packaging | tooling only | implemented |\n| Stage 10 | adaptive latency controller | `0018` | partially implemented, partially conceptual |\n| Stage 11 | Linux 6.8 foundation tracepoints | foundation `0005`, broad `0022` | compile-targeted foundation path |\n| Stage 12 | model/session fairness scheduler | `0020` | conceptual scheduler scaffold |\n| Stage 13 | decode latency histogram | `0023` | histogram scaffold + experiment tooling |\n| Stage 14 | controller feedback wiring | `0024` | partial compile-target helpers + conceptual dispatch hook |\n| Stage 15 | fairness accounting and sysfs wiring | `0025` | conceptual wiring + experiment tooling |\n| Stage 16 | blk-cgroup AI I/O controller | `0026` | conceptual blkcg scaffold + experiment tooling |\n| Stage 17 | io_uring KV region hints | `0027` | conceptual io_uring region scaffold + experiment tooling |\n| Stage 18 | recompute-aware eviction scheduler | `0028` | conceptual eviction class/score scaffold + experiment tooling |\n| Stage 19 | KV residency heatmap | `0029` | conceptual hot/warm/cold/evictable tracking + experiment tooling |\n| Stage 20 | flash-backed KV admission control | `0030` | conceptual admission policy scaffold + experiment tooling |\n\nFor the detailed tracker, use:\n\n* [docs/full_architecture_status.md](docs/full_architecture_status.md)\n* [docs/implementation_stages.md](docs/implementation_stages.md)\n* [docs/tested_kernel_matrix.md](docs/tested_kernel_matrix.md)\n\n---\n\n## Advanced Feature Map\n\n| Area | Implemented Today | Still Experimental / Conceptual |\n| --- | --- | --- |\n| Decode-read prioritization | foundation stack + broad RFC patches | broader multi-stage tuning is still benchmark-driven |\n| Request classification | base classification (`0002`) plus real request-init path (`0010`) | full runtime hint plumbing beyond current paths |\n| Prefetch / prefill / evict policy | foundation stack policy and accounting | scheduler refinements under later stages |\n| Write anti-starvation | `0011` scaffolded in broad RFC/POC series | runtime validation on patched kernel pending |\n| Tag reservation | `0012` broad series patch | patched-kernel validation pending |\n| O(1) dispatch path | `0013` broad series patch | patched-kernel validation pending |\n| Merge bias / request shaping | `0004` foundation instrumentation + `0015` broad-series merge path | impact on real NVMe traffic still unvalidated |\n| `io_uring` hints | `0014` SQE flag and `0027` region-hint scaffold | end-to-end kernel plumbing remains experimental |\n| Recompute-aware eviction | `0028` eviction class/score scaffold | dispatch-path eviction integration remains conceptual |\n| KV residency heatmap | `0029` heat class/tracking scaffold | fixed-array linear scan is RFC-only; no periodic decay timer wired |\n| KV admission control | `0030` admission policy scaffold | decode-p99 feedback and per-cgroup budgets remain conceptual |\n| Ephemeral / recomputable semantics | user/kernel hint scaffolds | no production ABI claimed |\n| Placement / lifetime metadata | benchmark-visible and metadata-visible | physical device placement not claimed |\n| Generic NVMe backend mapping | benchmark-visible generic mapping scaffold | real Streams/FDP/ZNS placement unvalidated |\n| Tracepoints and tracing tools | Stage 8/11 trace scaffolds, parsers, `bpftrace` helpers | stable ABI and patched-kernel availability not claimed |\n| Adaptive controller | Stage 10 control policy and sysfs scaffold | decode latency observation path remains incomplete |\n| Fairness and tenant isolation | Stage 12/15 fairness scaffolds | real scheduler enforcement remains conceptual |\n| blk-cgroup AI controller | Stage 16 experiment scaffold | cgroup interface and dispatch hooks remain conceptual |\n\n---\n\n## Benchmark\n\nThe benchmark lives at:\n\n```text\nbench/kairo_bench.c\n```\n\nIt models AI inference-like I/O using:\n\n* decode workers,\n* prefetch workers,\n* prefill/write workers,\n* eviction workers,\n* multi-session mode,\n* model/session/cache-pool/lifetime metadata,\n* backend-mode modeling,\n* and latency/throughput summaries.\n\nBuild:\n\n```bash\nmake\n```\n\nor:\n\n```bash\ngcc -O2 -Wall -pthread -Iinclude -o kairo_bench bench/kairo_bench.c\n```\n\n---\n\n## Temporary Hint Mapping\n\nThe current foundation path uses `ioprio` as a practical local signal:\n\n```text\nRT prio 0 read   -\u003e decode-critical read\nRT prio 1 read   -\u003e prefetch read\nBE prio 7 write  -\u003e prefill/background write\ndiscard/zeroes   -\u003e eviction cleanup\n```\n\nThis is intentionally temporary. The broader RFC path also explores `io_uring` and `RWF_*` hint propagation.\n\n---\n\n## Running Experiments\n\n### Baseline\n\n```bash\n./scripts/run_baseline.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Kairo POC\n\n```bash\n./scripts/set_mq_deadline.sh nvme0n1\n./scripts/run_kairo_poc.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### A/B comparison\n\n```bash\n./scripts/run_ab_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Multisession workload\n\n```bash\n./scripts/run_multisession_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 6 placement/lifetime experiment\n\n```bash\n./scripts/run_stage6_placement_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 7 backend mapping experiment\n\n```bash\n./scripts/run_stage7_backend_mapping_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 8 trace experiment\n\n```bash\n./scripts/run_stage8_trace_experiment.sh /mnt/nvme/kairo.test nvme0n1 --trace-mode none\n```\n\nOn an unpatched kernel, trace experiments should still run and report tracepoint availability honestly.\n\n### Stage 10 adaptive controller experiment\n\n```bash\n./scripts/run_stage10_latency_controller_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 11 foundation trace experiment\n\n```bash\n./scripts/run_stage11_foundation_trace_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 12 fairness experiment\n\n```bash\n./scripts/run_stage12_fairness_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 13 decode histogram experiment\n\n```bash\n./scripts/run_stage13_latency_histogram_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 14 controller feedback experiment\n\n```bash\n./scripts/run_stage14_controller_feedback_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 15 fairness accounting experiment\n\n```bash\n./scripts/run_stage15_fairness_accounting_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 16 blk-cgroup AI controller experiment\n\n```bash\n./scripts/run_stage16_blkcg_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 17 io_uring KV region experiment\n\n```bash\n./scripts/run_stage17_io_uring_region_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 18 recompute-aware eviction experiment\n\n```bash\n./scripts/run_stage18_recompute_eviction_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 19 KV heatmap experiment\n\n```bash\n./scripts/run_stage19_kv_heatmap_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n### Stage 20 KV admission control experiment\n\n```bash\n./scripts/run_stage20_kv_admission_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\n---\n\n## Success Metrics\n\nPrimary metric:\n\n```text\ndecode_p99_us under mixed prefill-write pressure\n```\n\nSecondary metrics:\n\n```text\ndecode_p95_us\ndecode_avg_us\ndecode_read_MBps\nprefetch_read_MBps\nwrite_MBps\neviction behavior\nstarvation escapes\nbackend mapping counters\ntracepoint event counts\n```\n\nThe goal is not just higher throughput. The key question is whether decode-critical I/O can be protected when background AI cache traffic competes for the same storage path.\n\n---\n\n## Linux 6.8 Foundation Validation\n\nUse the Linux 6.8 integration harness:\n\n```bash\n./kernel/integration/linux-6.8/apply_foundation_stack.sh /path/to/linux-6.8.x\n./kernel/integration/linux-6.8/validate_foundation_stack.sh /path/to/linux-6.8.x\n./kernel/integration/linux-6.8/build_foundation_objects.sh /path/to/linux-6.8.x\n```\n\nSmoke check:\n\n```bash\n./kernel/integration/linux-6.8/smoke_foundation_stack.sh /path/to/linux-6.8.x --check-only\n```\n\nNVMe hook audit:\n\n```bash\n./kernel/integration/linux-6.8/audit_nvme_hooks.sh /path/to/linux-6.8.x --stdout\n```\n\nTracepoint audit:\n\n```bash\n./kernel/integration/linux-6.8/audit_tracepoints.sh /path/to/linux-6.8.x --stdout\n```\n\n---\n\n## Validation Path\n\nTracked validation lives in:\n\n* [docs/tested_kernel_matrix.md](docs/tested_kernel_matrix.md)\n* [docs/full_architecture_status.md](docs/full_architecture_status.md)\n* [docs/validation_snapshot.md](docs/validation_snapshot.md)\n* [docs/qemu_validation.md](docs/qemu_validation.md)\n* [docs/kernel_foundation_stack.md](docs/kernel_foundation_stack.md)\n* [docs/kernel_foundation_invariants.md](docs/kernel_foundation_invariants.md)\n\nPrimary validation entry points:\n\n```bash\n# WSL repo consistency + dry-run validation\n./scripts/run_wsl_validation_snapshot.sh\n\n# QEMU stock-kernel module/sysfs validation (44/44 simulated counters)\n./scripts/run_kairo_qemu_validation.sh --kernel ~/linux-6.8/arch/x86_64/boot/bzImage --mem 2048\n```\n./scripts/validate_kairo_runtime.sh /mnt/nvme/kairo.test nvme0n1\n./scripts/run_ab_experiment.sh /mnt/nvme/kairo.test nvme0n1\n```\n\nCurrent status, at a high level:\n\n```text\nFoundation patch apply:       locally validated on Linux 6.8.x path\nFoundation symbol validation: locally validated\nmq-deadline object build:     locally validated\nblk-mq object build:          not yet cleanly validated in matrix\nBoot validation:              pending\nRuntime sysfs visibility:     pending\nBenchmark counter movement:     pending\nStage 8-20 harnesses:         implemented, but mostly dry-run/user-space validated\nFull RFC series compile:      not claimed\n```\n\nKairo intentionally separates what is implemented, what is scaffolded, and what is validated. This repo is an internal RFC/POC and benchmark-driven prototype, not a claim that the full Stage 10-17 kernel path has been boot-tested or benchmark-validated on patched generic NVMe SSDs.\n\n---\n\n## Documentation\n\nKey docs:\n\n* [docs/architecture.md](docs/architecture.md)\n* [docs/implementation_stages.md](docs/implementation_stages.md)\n* [docs/full_architecture_status.md](docs/full_architecture_status.md)\n* [docs/patch_series.md](docs/patch_series.md)\n* [docs/kernel_foundation_stack.md](docs/kernel_foundation_stack.md)\n* [docs/kernel_foundation_invariants.md](docs/kernel_foundation_invariants.md)\n* [docs/stage6_model_session_lifetime.md](docs/stage6_model_session_lifetime.md)\n* [docs/stage7_generic_nvme_backend_mapping.md](docs/stage7_generic_nvme_backend_mapping.md)\n* [docs/stage7_5_nvme_hook_audit.md](docs/stage7_5_nvme_hook_audit.md)\n* [docs/stage8_kernel_observability.md](docs/stage8_kernel_observability.md)\n* [docs/stage10_adaptive_latency_controller.md](docs/stage10_adaptive_latency_controller.md)\n* [docs/stage11_foundation_tracepoints.md](docs/stage11_foundation_tracepoints.md)\n* [docs/stage12_model_session_fairness.md](docs/stage12_model_session_fairness.md)\n* [docs/stage13_decode_latency_histogram.md](docs/stage13_decode_latency_histogram.md)\n* [docs/stage14_controller_feedback_wiring.md](docs/stage14_controller_feedback_wiring.md)\n* [docs/stage15_fairness_accounting_sysfs.md](docs/stage15_fairness_accounting_sysfs.md)\n* [docs/stage16_blkcg_ai_io_controller.md](docs/stage16_blkcg_ai_io_controller.md)\n* [docs/stage17_io_uring_kv_region_hints.md](docs/stage17_io_uring_kv_region_hints.md)\n* [docs/stage18_recompute_aware_eviction.md](docs/stage18_recompute_aware_eviction.md)\n* [docs/stage19_kv_residency_heatmap.md](docs/stage19_kv_residency_heatmap.md)\n* [docs/stage20_kv_admission_control.md](docs/stage20_kv_admission_control.md)\n* [docs/validation_snapshot.md](docs/validation_snapshot.md)\n* [docs/tested_kernel_matrix.md](docs/tested_kernel_matrix.md)\n\n---\n\n## Repository Layout\n\n```text\nbench/                         Synthetic KV-cache I/O benchmark\ndocs/                          Architecture and validation documentation\ninclude/                       User-space Kairo hint definitions\nkernel/patches/                Broad RFC/POC kernel patch series\nkernel/patches/foundation/     Compile-targeted Linux 6.8.x foundation stack\nkernel/integration/linux-6.8/  Apply/build/audit helpers for Linux 6.8.x\nscripts/                       Benchmark, validation, parsing, and tracing tools\nscripts/bpftrace/              bpftrace helpers for Kairo tracepoint experiments\n```\n\n---\n\n## What Kairo Is Not\n\nKairo is not:\n\n* a production kernel subsystem,\n* a stable userspace ABI,\n* an LKML-ready patch series,\n* a vendor-specific SSD integration,\n* or a claim of physical NVMe placement today.\n\nKairo is a research-grade kernel/storage prototype for exploring what AI-aware Linux storage could become.\n\n---\n\n## Design Principles\n\nKairo follows several principles:\n\n```text\nGeneric before vendor-specific.\nObservable before opaque.\nBenchmark-driven before claims.\nNo-op fallback before unsafe behavior.\nFoundation stack separate from architecture scaffolds.\nExplicit validation status instead of overclaiming.\n```\n\n---\n\n## License\n\nKairo is licensed under [GPL-2.0-only](LICENSE) to stay aligned with the Linux kernel-facing patch workflow in this RFC/POC repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanishklach%2Fkairo-io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanishklach%2Fkairo-io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanishklach%2Fkairo-io/lists"}