# Runtime Adapter 契约

`runtime_adapter.py` 是 Runtime Manager 与具体运行环境之间的可执行契约。

当前 Compose 环境使用 `SharedJupyterAdapter`。它把共享 Jupyter Server 作为
首期 Provider，并在 MySQL 中为每个 `Workspace` 建立并复用一个逻辑
Runtime。每个打开的 Notebook 在该 Runtime 中建立独立 Jupyter Session，
每个 Session 绑定自己的 Kernel。
后续 Docker/Kubernetes Provider 必须实现同一 Protocol，公共锁接口和
`runtime_instances` 状态模型保持不变。

核心约束：

- `ensure_running` 对同一作用域必须幂等；
- Runtime 的唯一复用作用域是 Workspace，不能按用户重复创建；
- Runtime 的期望状态、实际状态和租约写入 MySQL；
- Notebook 对应独立 Jupyter Session/Kernel，其创建和终止只能由 Runtime
  Manager 调用；
- Provider 不能依赖 Platform API 的进程内状态；
- `proxy_base_path` 与 Jupyter 内部 `base_url` 必须一致。
- Provider 调用必须携带内部服务凭据，不能通过关闭 XSRF 检查规避认证；
- Workspace 的目录、文件权限必须同时满足 Platform 原子写入和 Jupyter
  读写，当前 Compose 环境使用共享 Unix 组完成。

Jupyter 浏览器代理、访问票据和 WebSocket 约束见
`jupyter-proxy-v1.md`。