Plan 05: Universal Streaming & Context Cancellation

Goal: Introduce streaming byte I/O (io.Reader/io.Writer equivalent) and a cancellation/deadline context into the host runtime capabilities. Inspiration: Go's io.Reader, io.Writer, and context.Context.

1. Problem Statement & Root Cause

Currently in runtime/kyna_host/include/kyna/execution/runtime_capabilities.hpp:

1. Whole-Buffer Slurping: FileSystemPort::read returns std::optional<std::string> and FileSystemPort::write accepts std::string. Reading a 2GB file requires allocating a 2GB contiguous heap string.
2. Synchronous Network & HTTP: Network and server requests block OS threads completely. There is no cancellation token or timeout capability passed through compiler or runtime pipelines.

2. Target Architecture

2.1 The Streaming Ports (IReader & IWriter)

1namespace kyna::host {
2 
3class IReader {
4public:
5  virtual ~IReader() = default;
6  // Reads up to `size` bytes into `buffer`. Returns bytes read (0 = EOF).
7  virtual size_t read(uint8_t* buffer, size_t size) = 0;
8};
9 
10class IWriter {
11public:
12  virtual ~IWriter() = default;
13  // Writes `size` bytes from `buffer`. Returns bytes written.
14  virtual size_t write(const uint8_t* buffer, size_t size) = 0;
15};
16 
17class ICloser {
18public:
19  virtual ~ICloser() = default;
20  virtual void close() = 0;
21};
22 
23using ReadCloser = std::shared_ptr<IReader>;
24using WriteCloser = std::shared_ptr<IWriter>;
25 
26} // namespace kyna::host

2.2 Context Propagation & Cancellation

1namespace kyna::host {
2 
3class Context {
4public:
5  virtual ~Context() = default;
6  virtual bool isCancelled() const = 0;
7  virtual std::optional<std::chrono::system_clock::time_point> deadline() const = 0;
8  virtual void cancel() = 0;
9 
10  static std::shared_ptr<Context> Background();
11  static std::pair<std::shared_ptr<Context>, std::function<void()>>
12  WithTimeout(const std::shared_ptr<Context>& parent, std::chrono::milliseconds timeout);
13};
14 
15} // namespace kyna::host

3. Implementation Steps

• Step 1: Add IReader and IWriter to runtime_capabilities.hpp
• Step 2: Implement File Stream Adapters
  • Implement FileStreamReader and FileStreamWriter under runtime/kyna_host/src/capabilities/.
• Step 3: Introduce Context to Compilation & Evaluation Pipelines
  • Pass const Context& to Analyzer::analyze and Interpreter::eval so long-running operations can be cancelled safely.
• Step 4: Expose Stream APIs to the Standard Library
  • Expose openFileStream(path, mode) returning stream handles to Kyna scripts.

4. Verification Plan

1. Unit Tests:
   • Write stream chunking tests verifying that a 10MB file can be processed in 64KB chunks with constant memory usage.
   • Write cancellation tests verifying that an infinite loop or heavy compilation aborts when the timeout fires.