From b2aebff3dc2abc4a42b1102a752210fd156807ef Mon Sep 17 00:00:00 2001
From: Scott Roy <scroy@meta.com>
Date: Wed, 4 Nov 2026 18:08:06 -0800
Subject: [PATCH] Add load-time options to native engine contexts

EngineHost::create_context_with_options takes named string options for one
context, such as the registry key of a KV cache the caller installed. The
default implementation rejects any option, so engines opt in to the options
they understand; create_context and its callers are unchanged.
---
 backends/native/runtime/engine/Engine.cpp | 12 ++++++++++++
 backends/native/runtime/engine/Engine.h   | 15 +++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/backends/native/runtime/engine/Engine.cpp b/backends/native/runtime/engine/Engine.cpp
index cf7155bb41e..f006be2f6fe 100644
--- a/backends/native/runtime/engine/Engine.cpp
+++ b/backends/native/runtime/engine/Engine.cpp
@@ -57,4 +57,16 @@ std::unique_ptr<EngineExecutable> EngineContext::compile(
 
 EngineHost::~EngineHost() = default;
 
+std::unique_ptr<EngineContext> EngineHost::create_context_with_options(
+    std::shared_ptr<const Program> program,
+    std::shared_ptr<const Package> package,
+    const EngineOptions& options) {
+  if (!options.empty()) {
+    throw std::invalid_argument(
+        name() + ": unsupported context option '" + options.begin()->first +
+        "'");
+  }
+  return create_context(std::move(program), std::move(package));
+}
+
 } // namespace ptn
diff --git a/backends/native/runtime/engine/Engine.h b/backends/native/runtime/engine/Engine.h
index f2f41ba1afc..83d1c825210 100644
--- a/backends/native/runtime/engine/Engine.h
+++ b/backends/native/runtime/engine/Engine.h
@@ -8,6 +8,7 @@
 
 #include <cstddef>
 #include <cstdint>
+#include <map>
 #include <memory>
 #include <string>
 #include <vector>
@@ -105,6 +106,10 @@ class EngineContext {
   std::shared_ptr<const Package> package_;
 };
 
+// Named load-time settings for one context, such as the registry key of an
+// off-graph KV cache the caller installed.
+using EngineOptions = std::map<std::string, std::string>;
+
 // Process-wide backend and device resources shared by its contexts. Must
 // outlive every context and executable it creates.
 // Callers serialize create_context(); distinct contexts may execute
@@ -129,6 +134,16 @@ class EngineHost {
   virtual std::unique_ptr<EngineContext> create_context(
       std::shared_ptr<const Program> program,
       std::shared_ptr<const Package> package) = 0;
+
+  // create_context with `options`. Throws std::invalid_argument on an option
+  // the engine does not recognize; the default recognizes none. An option may
+  // bind caller-owned state, such as a KV cache, into the context. Contexts
+  // bound to the same state are not isolated from each other: the caller must
+  // serialize their executables as if they shared one context.
+  virtual std::unique_ptr<EngineContext> create_context_with_options(
+      std::shared_ptr<const Program> program,
+      std::shared_ptr<const Package> package,
+      const EngineOptions& options);
 };
 
 } // namespace ptn