From 23378e928934c7c305098d5033b14e0a50afada7 Mon Sep 17 00:00:00 2001 From: Linson Date: Mon, 28 Sep 2026 01:12:14 +0530 Subject: [PATCH 1/3] rfc/193: work-interval hint scaffolding (flag + doc + test) Upstream issue incoai/splash#193. Default off, no behavior change. --- dev/tests/test_rfc_193_work_interval.py | 24 +++++++++++++++++++ docs/rfc/193-work-interval.md | 32 +++++++++++++++++++++++++ runtime/engine/Rfc193WorkInterval.hpp | 12 ++++++++++ 3 files changed, 68 insertions(+) create mode 100644 dev/tests/test_rfc_193_work_interval.py create mode 100644 docs/rfc/193-work-interval.md create mode 100644 runtime/engine/Rfc193WorkInterval.hpp diff --git a/dev/tests/test_rfc_193_work_interval.py b/dev/tests/test_rfc_193_work_interval.py new file mode 100644 index 000000000..1bc0ad119 --- /dev/null +++ b/dev/tests/test_rfc_193_work_interval.py @@ -0,0 +1,24 @@ +"""RFC 193 scaffolding test: work-interval flag defaults off.""" + +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] + + +class Rfc193WorkIntervalTest(unittest.TestCase): + def test_header_defaults(self): + header = ROOT / "runtime/engine/Rfc193WorkInterval.hpp" + self.assertTrue(header.is_file()) + text = header.read_text() + self.assertIn("kEnabledDefault = false", text) + self.assertIn("SPLASH_ENGINE_WORK_INTERVAL", text) + + def test_doc_exists(self): + doc = ROOT / "docs/rfc/193-work-interval.md" + self.assertTrue(doc.is_file()) + self.assertIn("issues/193", doc.read_text()) + + +if __name__ == "__main__": + unittest.main() diff --git a/docs/rfc/193-work-interval.md b/docs/rfc/193-work-interval.md new file mode 100644 index 000000000..049fca4ab --- /dev/null +++ b/docs/rfc/193-work-interval.md @@ -0,0 +1,32 @@ +# RFC 193 — P-core work-interval hint + host-gap hiding + +Upstream issue: https://github.com/incoai/splash/issues/193 + +Source: bonsai `CBv2EngineWorkInterval.swift` (`AudioWorkIntervalCreate` +P-core hint, `MLXFAST_ENGINE_WORK_INTERVAL`, prompt-forward renew). + +## Problem + +Host gap between verify-block build and GPU submit shows up as idle +(`Engine.cpp`, `Scheduler.*`, `NativeRuntime.*`, `Bootstrap.mm`). +Bonsai reports 11.4→3.1 ms verify build / 2.0→0.6 ms idle from a +scheduling hint alone; Splash lists host-gap hiding as out-of-scope +(`PLAN.md:26`) with no measurement. + +## Proposal + +1. `runtime/engine/Rfc193WorkInterval.hpp` declares the flag + env var + (`SPLASH_ENGINE_WORK_INTERVAL`). +2. Follow-up scopes an opt-in P-core / QoS hint to the + prompt-forward-submit + verify-build window only; renew on + `promptForwardBegan/Submitted`. + +## Contracts + +- Scheduling hint only; no numerics / protocol / memory-plan change; + must not starve UI/audio. + +## Validation + +- `benchmark-decode-profile` verify-build ms + GPU idle ms B1–B4 + (alternating, medians ≥31); ABBA neutral required. Easiest to revert. diff --git a/runtime/engine/Rfc193WorkInterval.hpp b/runtime/engine/Rfc193WorkInterval.hpp new file mode 100644 index 000000000..408af2522 --- /dev/null +++ b/runtime/engine/Rfc193WorkInterval.hpp @@ -0,0 +1,12 @@ +#pragma once + +// RFC 193 scaffolding: P-core work-interval hint for verify dispatch. +// See docs/rfc/193-work-interval.md and +// https://github.com/incoai/splash/issues/193. + +namespace splash::engine::rfc193 { + +inline constexpr bool kEnabledDefault = false; +inline constexpr const char* kEnvVar = "SPLASH_ENGINE_WORK_INTERVAL"; + +} // namespace splash::engine::rfc193 From b5871361abdb7f21f6816f48ababa44ac3ec2420 Mon Sep 17 00:00:00 2001 From: Linson Date: Mon, 28 Sep 2026 01:22:01 +0530 Subject: [PATCH 2/3] host/193: work-interval scope contract (constexpr + static_assert) IntervalScope/WorkIntervalConfig/renewAllowed with bounded renews. Host-only by design (no .metal change applies). Upstream issue incoai/splash#193, PR incoai/splash#201. --- dev/tests/test_rfc_193_work_interval.py | 7 +++++++ docs/rfc/193-work-interval.md | 8 +++++++ runtime/engine/Rfc193WorkInterval.hpp | 28 +++++++++++++++++++++++++ 3 files changed, 43 insertions(+) diff --git a/dev/tests/test_rfc_193_work_interval.py b/dev/tests/test_rfc_193_work_interval.py index 1bc0ad119..73b2da5d5 100644 --- a/dev/tests/test_rfc_193_work_interval.py +++ b/dev/tests/test_rfc_193_work_interval.py @@ -19,6 +19,13 @@ def test_doc_exists(self): self.assertTrue(doc.is_file()) self.assertIn("issues/193", doc.read_text()) + def test_scope_contract(self): + header = (ROOT / "runtime/engine/Rfc193WorkInterval.hpp").read_text() + for symbol in ("IntervalScope", "WorkIntervalConfig", + "renewAllowed", "static_assert"): + with self.subTest(symbol=symbol): + self.assertIn(symbol, header) + if __name__ == "__main__": unittest.main() diff --git a/docs/rfc/193-work-interval.md b/docs/rfc/193-work-interval.md index 049fca4ab..459e9cc9e 100644 --- a/docs/rfc/193-work-interval.md +++ b/docs/rfc/193-work-interval.md @@ -26,6 +26,14 @@ scheduling hint alone; Splash lists host-gap hiding as out-of-scope - Scheduling hint only; no numerics / protocol / memory-plan change; must not starve UI/audio. +## Code change (landed) + +`runtime/engine/Rfc193WorkInterval.hpp` now carries the scope contract +(`IntervalScope`, `WorkIntervalConfig{enabled, maxRenewsPerWindow}`, +`renewAllowed()`) as `constexpr` with `static_assert` cases. Host-only +by design — a scheduling hint takes no kernel. `clang++ -fsyntax-only` +clean. + ## Validation - `benchmark-decode-profile` verify-build ms + GPU idle ms B1–B4 diff --git a/runtime/engine/Rfc193WorkInterval.hpp b/runtime/engine/Rfc193WorkInterval.hpp index 408af2522..490e3cb0b 100644 --- a/runtime/engine/Rfc193WorkInterval.hpp +++ b/runtime/engine/Rfc193WorkInterval.hpp @@ -4,9 +4,37 @@ // See docs/rfc/193-work-interval.md and // https://github.com/incoai/splash/issues/193. +#include + namespace splash::engine::rfc193 { inline constexpr bool kEnabledDefault = false; inline constexpr const char* kEnvVar = "SPLASH_ENGINE_WORK_INTERVAL"; +// Scoped scheduling hint: raised around prompt-forward submit and the +// verify-block build, renewed on promptForwardBegan/Submitted, dropped +// immediately after. Scheduling-only — never held across a blocking wait, +// so UI/audio threads cannot starve. +enum class IntervalScope : std::uint8_t { + Idle = 0, + PromptForwardSubmit = 1, + VerifyBlockBuild = 2, +}; + +struct WorkIntervalConfig final { + bool enabled = kEnabledDefault; + // Renew points inside one measured window; bounded so a stuck submitter + // cannot pin the hint on. + std::uint32_t maxRenewsPerWindow = 2; +}; + +[[nodiscard]] constexpr bool renewAllowed(std::uint32_t renewsSoFar, + const WorkIntervalConfig& config) noexcept { + return config.enabled && renewsSoFar < config.maxRenewsPerWindow; +} + +static_assert(!renewAllowed(0, WorkIntervalConfig{})); +static_assert(renewAllowed(0, WorkIntervalConfig{true, 2})); +static_assert(!renewAllowed(2, WorkIntervalConfig{true, 2})); + } // namespace splash::engine::rfc193 From e9f784c93ee815b515143926a8ac2c2bfdb2fad6 Mon Sep 17 00:00:00 2001 From: Linson Date: Mon, 28 Sep 2026 01:44:04 +0530 Subject: [PATCH 3/3] fix/193: ruff format test_rfc_193 (no logic change) --- dev/tests/test_rfc_193_work_interval.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/dev/tests/test_rfc_193_work_interval.py b/dev/tests/test_rfc_193_work_interval.py index 73b2da5d5..8aa2d2ec9 100644 --- a/dev/tests/test_rfc_193_work_interval.py +++ b/dev/tests/test_rfc_193_work_interval.py @@ -21,8 +21,12 @@ def test_doc_exists(self): def test_scope_contract(self): header = (ROOT / "runtime/engine/Rfc193WorkInterval.hpp").read_text() - for symbol in ("IntervalScope", "WorkIntervalConfig", - "renewAllowed", "static_assert"): + for symbol in ( + "IntervalScope", + "WorkIntervalConfig", + "renewAllowed", + "static_assert", + ): with self.subTest(symbol=symbol): self.assertIn(symbol, header)