Kairo v0.2.0

Kairo v0.2.0

Kairo v0.2.0 adds the Stage 7 backend mapping scaffold (generic NVMe Streams/FDP/ZNS hooks with safe no-op fallback), followed by a Stage 7.5 hardening pass that audits every hook point, introduces a kairo_backend_caps abstraction, and refactors the benchmark.

The release also includes the Stage 6 placement/lifetime metadata layer, Stage 6.5 experiment harness hardening, foundation stack repairs, and CI/polish improvements across the repo.

Positioning

• internal RFC/POC
• experimental Linux kernel patch stack
• benchmark-driven validation
• AI KV-cache workload modeling for generic NVMe SSDs
• 9-patch RFC/POC series plus compile-targeted 4-patch foundation subset
• not intended for LKML submission at this stage

Highlights

Stage 7 — Generic NVMe Backend Mapping Scaffold

The 0008 patch introduces a neutral backend placement layer that converts Stage 6 lifetime/placement metadata into backend classes:

• \�num kairo_backend_class\ — SHORT_LIVED, SESSION_LOCAL, MODEL_LOCAL, RECOMPUTABLE, PERSISTENT
• \struct kairo_backend_hint\ with Streams/FDP/ZNS mapping fields and flags
• Feature-detected NVMe hooks (all return false until real detection is wired)
• Benchmark --backend-mode none|generic|streams|fdp|zns\ with mapping output fields
• 10 backend mapping scaffold counters added to 0009 sysfs patch
• Experiment script \scripts/run_stage7_backend_mapping_experiment.sh\ with 5 canonical cases
• Parser \scripts/parse_stage7_backend_summary.py\ with CSV and pretty-printed output

Stage 7.5 — NVMe Hook Audit and Mapping Hardening

A hardening pass over the Stage 7 scaffold:

• Hook-point analysis: each 0008 hook classified as \COMPILE-TARGET\ or \CONCEPTUAL-HOOK\ with compile-risk annotations across all 6 kernel files touched (blk_types.h, blk-mq.h, nvme.h, nvme.h driver, core.c, zns.c)
• **\struct kairo_backend_caps**: unified capability abstraction replacing three per-feature _supported()\ helpers; single
  vme_kairo_get_backend_caps()\ replaces
  vme_kairo_streams_supported(),
  vme_kairo_fdp_supported(),
  vme_kairo_zns_supported()\
• 0008 rewritten into sections A–H: organized by file and abstraction layer with annotation comments at each hook point
• Benchmark refactor: 5 individual backend helpers consolidated into \kairo_compute_backend_model()\ returning \struct kairo_backend_model\
• **\docs/stage7_5_nvme_hook_audit.md**: detailed analysis of each hook point against real Linux 6.8 kernel symbols
• **\kernel/integration/linux-6.8/audit_nvme_hooks.sh**: checks a real Linux 6.8 tree for candidate symbols and confirms Kairo symbols are absent from stock
• **\scripts/validate_stage7_backend_mapping.py**: Python validator that checks 0008 sections, docs, and benchmark for required patterns
• Validator integrated into \scripts/validate_patch_stack.sh\

Stage 6 — Placement and Lifetime Metadata

The 0007 patch adds model/session/lifetime placement metadata that the benchmark drives and the backend mapping layer consumes:

• \�num kairo_lifetime_class\ (SHORT, SESSION, MODEL, PERSISTENT)
• \struct kairo_placement_hint\ with model_id, session_id, cache_pool_id, placement_group, recompute_ok
• Benchmark --lifetime, --recompute-ok, --cache-pool-id, --placement-group, --cache-pools, --placement-groups\
• 9 scaffold placement counters in sysfs

Stage 6.5 — Experiment Harness Hardening

• \scripts/run_stage6_placement_experiment.sh: hardened harness with <file-path> \ interface and structured
  esults/stage6//\ output
• \scripts/parse_stage6_placement_summary.py: parser with counter delta columns, --csv\ and --pretty\ output
• \scripts/collect_kairo_counters.sh: unified counter coverage for both naming sets

Foundation Stack Repairs

Multiple rounds of foundation patch repair and validation hardening:

• Foundation/0004 hunk headers regenerated for post-0003 file state
• Corrupt context lines (tab-prefixed instead of space+tab) repaired
• Shellcheck issues fixed: SC2034 (unused local variable shadowing), SC2155 (declare-and-assign masking return codes)
• Foundation invariant checks and validation script hardening
• Patch 0008 had incorrect
  r_streams\ check (--enable\ → \

Kairo v0.1.0

Kairo v0.1.0

Kairo v0.1.0 marks the first public snapshot of the project as a full internal RFC/POC for AI KV-cache-aware Linux block I/O on generic NVMe SSDs.

This release moves the repo beyond a single scheduler idea and into a broader multi-patch kernel architecture backed by a measurable benchmark and validation harness. The focus remains local, benchmark-driven validation of whether Linux block-layer changes can reduce decode-read tail latency under mixed AI inference-like storage pressure.

Positioning

• internal RFC/POC
• experimental kernel patch series
• benchmark-driven prototype
• generic NVMe SSD focus
• AI inference-like KV-cache workload modeling
• not intended for LKML submission at this stage

Highlights

Full Kairo patch series scaffold

The kernel/patches/ directory now carries a nine-patch Kairo RFC/POC series:

• 0001-rfc-kairo-mq-deadline-decode-priority.patch
• 0002-rfc-kairo-request-classification.patch
• 0003-rfc-kairo-io-uring-hint-plumbing.patch
• 0004-rfc-kairo-large-block-coalescing.patch
• 0005-rfc-kairo-prefetch-deadline-hints.patch
• 0006-rfc-kairo-ephemeral-cache-semantics.patch
• 0007-rfc-kairo-placement-lifetime-hints.patch
• 0008-rfc-kairo-nvme-zns-fdp-mapping.patch
• 0009-rfc-kairo-sysfs-debug-counters.patch

The series now spans:

• mq-deadline decode-read prioritization
• shared request classification helpers
• experimental io_uring / RWF_KAIRO_* hint plumbing
• large-block merge bias for KV-style reads
• prefetch-specific urgency modeling
• ephemeral and recomputable cache semantics
• model/session/lifetime placement hints
• generic NVMe Streams/FDP/ZNS mapping hooks
• sysfs and debug observability counters

Measurable validation path

Kairo now includes a stronger local validation harness for Linux 6.8.x:

• kernel/integration/linux-6.8/ patch apply and block-build helpers
• scripts/validate_kairo_runtime.sh for runtime counter validation
• scripts/run_ab_experiment.sh for baseline vs Kairo comparison
• scripts/run_multisession_experiment.sh for session/model fan-out pressure
• scripts/collect_kairo_counters.sh and expanded block-stat collection

The main proof points remain:

• decode_avg_us
• decode_p50_us
• decode_p95_us
• decode_p99_us
• write_MBps
• Kairo dispatch-counter deltas showing whether the Kairo path was actually hit

Benchmark upgrade

bench/kairo_bench.c now behaves more like an AI KV-cache storage harness than a generic mixed-I/O toy.

New benchmark modes:

• decode-only
• mixed
• prefetch-pressure
• eviction-pressure
• multisession

New workload controls include:

• --sessions
• --models
• --evict-threads
• --prefill-region-pct
• --decode-region-pct

The benchmark summary now reports workload shape and ioprio setup status, including:

• mode
• sessions
• models
• evict_threads
• ioprio_decode_ok
• ioprio_decode_fail
• ioprio_prefetch_ok
• ioprio_prefetch_fail
• ioprio_write_ok
• ioprio_write_fail

Documentation added

This release adds architecture-facing project docs that explain the broader Kairo direction:

• docs/patch_series.md
• docs/full_architecture_status.md
• docs/roadmap.md
• docs/tested_kernel_matrix.md

These documents map the Kairo vision to concrete patch areas and separate the implemented proof point from the more aggressive RFC/POC scaffolds.

Current state

What is relatively strong today:

• repo structure and architecture direction
• benchmark and experiment harness
• 0001 decode-priority path as the current kernel proof point
• validation and observability workflow

What is still intentionally RFC/POC-level:

• deeper request metadata plumbing across the stack
• prefetch deadline policy tuning
• ephemeral semantics behavior in real kernels
• generic NVMe backend mapping hooks
• full runtime validation of later patches beyond 0001

Suggested next steps

• validate 0002 to 0005 against a concrete Linux 6.8.x source tree
• boot a patched kernel and confirm expanded Kairo sysfs counters are visible
• run scripts/run_ab_experiment.sh and scripts/run_multisession_experiment.sh on a generic NVMe SSD
• populate docs/tested_kernel_matrix.md with boot/runtime results
• use the new counters to confirm whether decode, prefetch, merge, and hinted-request paths are actually active

Key commits in this release

• bffefe3 poc: validate Kairo mq-deadline patch against Linux 6.8
• cf011ab supernova: add Kairo validation and A/B experiment harness
• c2e14cd supernova: expand Kairo into full KV-cache-aware kernel patch series