docs: define C-first kernel charter

README.md

@@ -1,23 +1,28 @@
 # FlowKernel
 
-> A long-horizon systems research repository exploring lifecycle-aware,
+> A planned C-first experimental kernel researching lifecycle-aware,
 > continuity-preserving, and AI-assisted resource scheduling.
 
 **Evidence state: Planned. Implementation has not started.**
 
-FlowKernel（流核）研究一个长期问题：操作系统能否不仅观察任务消耗了多少资源，还能理解
-任务所处的生命周期、真实进展和连续运行价值，并据此改进长期资源策略。
+FlowKernel（流核）的长期目标是构建一个以 freestanding C 为可信核心的实验性操作系统内核，
+研究操作系统能否不仅观察任务消耗了多少资源，还能理解任务所处的生命周期、真实进展和
+连续运行价值，并据此改进长期资源策略。
 
 本仓库现在只保存研究问题、架构假设、实验路线和证据规则。它不是一个已经可运行的内核，
 也不把路线图描述成已实现能力。
 
-## 核心原则
+## 实现契约
 
-> AI may propose policy; deterministic mechanisms retain enforcement authority.
+> C owns mechanism and enforcement; AI may only propose bounded policy.
 
+- **The trusted core is C-first.** 内核主体使用受限的 freestanding C；只有启动、中断入口和
+  上下文切换等硬件边界允许隔离、可枚举的最小汇编，不引入第二套策略逻辑。
+- **Lifecycle is an explicit state machine.** Spring Boot 只提供生命周期问题的启发；内核使用
+  自己的构造、绑定、启动、运行、降级、停止和回收状态，不移植应用框架。
 - **AI is advisory.** AI 负责识别状态、评估长期策略并提出动作建议。
-- **Enforcement remains deterministic.** Linux scheduler、cgroup、`sched_ext`、eBPF
-  等确定性机制负责约束和执行。
+- **Enforcement remains deterministic.** C 状态机、Guard 和有限动作执行器负责约束和执行；
+  模型缺席、超时或失效时，确定性基线仍能独立运行。
 - **Safety invariants are not learned policies.** 权限、硬资源上限、最低保障、紧急资源和
   迁移前有效检查点等约束不能交给奖励函数自行领悟。
 - **Mechanism and policy stay separated.** 学习系统可以调整策略，但不重写上下文切换、
@@ -27,7 +32,15 @@ FlowKernel（流核）研究一个长期问题：操作系统能否不仅观察
 
 ## 研究对象
 
-第一阶段不从零编写完整操作系统，而是在 Linux 提供的可控边界上研究：
+最终研究对象是自研的 C-first 实验内核，但不会一开始追求驱动、文件系统、网络和多节点
+能力齐全。工程上分成两个可比较边界：
+
+- **FlowKernel target：** 用受限 freestanding C 建立最小可启动内核、显式生命周期状态机、
+  确定性调度基线、C Guard 和可回退动作执行器；
+- **Linux reference lab：** 使用 Linux、cgroup、`sched_ext` 和 eBPF 作为传统对照组、观测
+  实验台与早期假设验证工具，不把实验台结果冒充 FlowKernel 内核能力。
+
+在这两个边界上逐步研究：
 
 - 进程、容器和长周期 Agent workload 的生命周期建模；
 - CPU、内存、I/O、网络和加速器资源预算；
@@ -42,13 +55,17 @@ FlowKernel（流核）研究一个长期问题：操作系统能否不仅观察
 ```mermaid
 flowchart TD
     state["System and workload state"] --> observe["Lifecycle observer"]
-    observe --> attention["State selection / attention"]
-    attention --> policy["Rule, planner, or learned policy"]
-    policy --> proposal["Bounded action proposal"]
-    proposal --> guard["Deterministic safety guard"]
-    guard --> control["cgroup / sched_ext / eBPF / controller"]
-    control --> runtime["Linux and hardware"]
-    runtime --> state
+    observe --> lifecycle["Deterministic C lifecycle machine"]
+    lifecycle --> baseline["Rule baseline"]
+    lifecycle --> attention["Slow-path state selection"]
+    attention --> policy["External or isolated learned advisor"]
+    policy --> proposal["Typed, bounded action proposal"]
+    baseline --> guard["C safety guard"]
+    proposal --> guard
+    guard --> control["Bounded C executor"]
+    control --> runtime["Scheduler / memory / I/O substrate"]
+    runtime --> hardware["Hardware"]
+    hardware --> state
 ```
 
 微秒到毫秒级的 **Fast Path** 继续使用确定性算法。AI 只进入秒级到分钟级的
@@ -58,21 +75,22 @@ flowchart TD
 
 | 阶段 | 研究目标 | 当前状态 |
 | --- | --- | --- |
-| R0 | 建立传统调度器、静态规则和工作负载基线 | Planned |
-| R1 | 单机生命周期观测与手写策略 | Planned |
-| R2 | `sched_ext`、cgroup 与容器控制实验 | Planned |
-| R3 | 状态筛选、Attention 与可解释观测 | Planned |
-| R4 | 模仿学习、强化学习与确定性 Guard | Planned |
-| R5 | 多节点放置、检查点、迁移与恢复 | Planned |
-| R6 | 故障注入、公平性、连续性与奖励投机验证 | Planned |
-| R7 | 面向 Agent、模型训练和推理的专项 workload | Planned |
+| R0 | 固定 C 工具链、启动契约、传统策略和 workload 对照基线 | Planned |
+| R1 | 最小可启动 C 内核与显式生命周期状态机 | Planned |
+| R2 | 确定性调度、资源回收、C Guard 与故障回退 | Planned |
+| R3 | 生命周期观测、状态筛选、Attention 与可解释性 | Planned |
+| R4 | 模仿学习、强化学习与受限动作提案 | Planned |
+| R5 | workload 连续性、检查点、迁移与恢复 | Planned |
+| R6 | 多核/多节点、故障注入、公平性和长期稳定性 | Planned |
+| R7 | Agent、模型训练和推理 workload 的对照验证 | Planned |
 
 阶段编号表示依赖关系，不代表承诺日期。每一阶段只有形成可重复实验和对照证据后，才会
 从 `Planned` 更新为 `Validated`。
 
 ## 文档
 
 - [概念起源](docs/conceptual-origin.md)
+- [C-first 内核契约](docs/c-first-kernel-contract.md)
 - [愿景与边界](docs/vision.md)
 - [研究问题](docs/research-questions.md)
 - [架构假设](docs/architecture-hypotheses.md)
@@ -95,10 +113,12 @@ flowchart TD
 
 ## 当前不做
 
-- 不宣称正在构建可替代 Linux 的通用操作系统；
+- 不宣称当前已有可运行内核，也不宣称正在替代 Linux；
+- 不用“C 代码少”替代内存安全、并发安全、状态机和故障恢复设计；
+- 不在最小闭环前同时铺开驱动、文件系统、网络栈、多核和分布式控制；
 - 不让模型直接控制中断、时间片、内存页或内核权限；
 - 不把所有 `if/else` 机械替换为强化学习；
-- 不预选模型、算法、编程语言或分布式控制平面；
+- 不预选模型、强化学习算法或分布式控制平面；
 - 不在没有基线、随机种子和失败证据时发布性能结论。
 
 ## License

docs/architecture-hypotheses.md

@@ -2,10 +2,20 @@
 
 以下内容是待实验验证的候选结构，不是最终架构承诺。
 
+## H0：可信核心应当 C-first、最小且可旁路 AI 运行
+
+FlowKernel target 的内核主体使用受限 freestanding C。启动、中断入口和上下文切换允许
+架构必需的最小汇编，但策略逻辑不能越过 C 接口边界。内核必须在模型完全缺席时依靠
+确定性基线完成启动、运行、停止和资源回收。
+
+预期收益是控制流、ABI、内存布局和故障边界可直接审查；需要验证的代价是 C 未定义行为、
+手工所有权、并发与中断安全所带来的验证成本。
+
 ## H1：机制与策略应严格分离
 
-Linux 和确定性控制器提供有限动作：调整 quota/weight、限流、退避、暂停、恢复、检查点、
-迁移和放置。规则或学习系统只在动作集合内提出建议，不能绕过执行层。
+FlowKernel 的 C 执行器提供有限动作：调整预算或权重、限流、退避、暂停、恢复、检查点、
+迁移和放置。Linux reference lab 使用 cgroup、`sched_ext`、eBPF 和确定性控制器表达相同的
+对照动作。规则或学习系统只在动作集合内提出建议，不能绕过 Guard 和执行层。
 
 预期收益是策略可以独立迭代、回放和回滚；需要验证的代价是跨层状态同步与控制延迟。
 
@@ -14,7 +24,7 @@ Linux 和确定性控制器提供有限动作：调整 quota/weight、限流、
 Fast Path 处理即时机制，Slow Path 处理长期策略。Slow Path 超时或失效时，Fast Path 仍需
 独立维持系统运行。
 
-首个原型不会让模型参与每个 CPU 时间片决策。
+首个原型不会让模型参与每个 CPU 时间片决策，也不会把模型服务设为启动依赖。
 
 ## H3：workload 是比裸进程更合适的早期对象
 
@@ -33,7 +43,8 @@ migration_constraints
 minimum_guarantees
 ```
 
-容器、cgroup 和应用侧探针可以提供较完整的实验边界，但必须测量探针开销和错误信号。
+FlowKernel 内核事件和静态任务描述提供目标侧观测；容器、cgroup 和应用侧探针提供 Linux
+对照侧观测。两边都必须测量探针开销、错误信号和语义差异。
 
 ## H4：学习策略之前必须有规则基线
 
@@ -51,7 +62,7 @@ static rules
 
 ## H5：安全 Guard 拥有最终否决权
 
-Guard 至少负责：
+C Guard 至少负责：
 
 - 拒绝超出硬资源上限或权限边界的动作；
 - 保留内核、控制器和关键任务的紧急资源；
@@ -60,7 +71,7 @@ Guard 至少负责：
 - 在有效 checkpoint 不存在时拒绝迁移；
 - 在策略超时、异常或不可用时切回确定性规则。
 
-这些约束通过代码、模型检查或可重复测试验证，不通过 reward 间接表达。
+这些约束通过 C 代码审查、静态分析、模型检查或可重复测试验证，不通过 reward 间接表达。
 
 ## H6：Attention 只负责“看什么”
 

docs/c-first-kernel-contract.md

@@ -0,0 +1,124 @@
+# C-first 内核契约
+
+**Evidence state: Designed. No implementation has been validated.**
+
+本文定义 FlowKernel 未来实现必须遵守的语言、生命周期与学习策略边界。它是研究契约，
+不是已经存在可运行内核的证明。
+
+## 1. C-first 的准确含义
+
+FlowKernel 的可信核心以 **freestanding C** 实现。初始实现采用经过工具链固定的 C11 子集，
+不依赖宿主 libc、C++ runtime、语言虚拟机或垃圾回收器。
+
+“C-first”不等于“所有字节都必须由 C 编译器生成”。启动入口、中断门、上下文切换和少量
+原子指令等架构必需部分可以使用最小汇编，但必须满足以下约束：
+
+- 汇编只承担 C 无法可靠表达的硬件接口，不包含调度或学习策略；
+- 每个汇编入口都有 C 侧契约、保存寄存器说明和独立测试；
+- 汇编规模和调用边界可枚举、可审查，不允许演变成第二套内核逻辑；
+- 链接脚本、启动镜像和工具链版本属于可复现实验输入。
+
+C 提供直接且可固定的 ABI 与内存布局控制，但 C 本身不会自动带来可靠性。越界访问、生命周期
+错误、整数溢出、未定义行为、数据竞争和中断重入仍是首要风险。因此初始可信核心还必须：
+
+- 禁止隐式内存分配、无界递归、可变长数组和无法审计的宏技巧；
+- 为资源句柄定义单一所有者、借用范围和显式释放点；
+- 对所有外部长度、索引、状态和枚举做边界校验；
+- 将中断上下文、可睡眠上下文和持锁上下文写入接口契约；
+- 同时使用编译器警告、静态分析、sanitizer 宿主测试、模拟器和故障注入；
+- 把 warning 当作失败，固定工具链和编译参数，保存可重放构建证据。
+
+## 2. 生命周期不是框架移植
+
+Spring Boot 提供的是问题来源：对象和服务需要被发现、构造、装配、启动、运行、停机和
+回收。FlowKernel 借用这套生命周期思维，但不把 Spring 容器、反射或依赖注入机制搬入
+内核。
+
+初始候选状态机是：
+
+```text
+RESET
+  -> BOOTSTRAP
+  -> DISCOVER
+  -> CONSTRUCT
+  -> BIND
+  -> START
+  -> RUNNING
+  -> QUIESCE
+  -> STOP
+  -> RECLAIM
+```
+
+异常只能进入显式的 `DEGRADED`、`RECOVERING` 或 `FAILED` 路径。每个状态转换必须声明：
+
+1. 前置条件；
+2. 唯一执行所有者；
+3. 资源预算和超时；
+4. 成功后的不变量；
+5. 失败后的补偿、回滚或隔离动作；
+6. 可审计的转换原因和结果。
+
+`if`、`for` 和 `while` 足以表达控制流，却不足以自动形成正确系统。可靠性来自状态、所有权、
+预算、退出条件和失败闭环都被显式定义，而不是来自语法数量少。
+
+## 3. 确定性基线永远先于强化学习
+
+FlowKernel 首先实现一条不依赖模型也能完整运行的确定性路径：
+
+```text
+observed snapshot
+  -> deterministic lifecycle machine
+  -> rule baseline
+  -> C safety guard
+  -> bounded executor
+  -> measured result
+```
+
+强化学习只能作为 Slow Path 的策略顾问加入：
+
+```text
+versioned snapshot
+  -> external or isolated policy advisor
+  -> typed action proposal
+  -> C safety guard
+  -> accept / clamp / reject
+```
+
+学习策略不得：
+
+- 直接写内核指针、页表、寄存器、中断状态或任意调度结构；
+- 在中断、上下文切换、锁和基本内存分配路径中同步推理；
+- 绕过动作 allowlist、资源上限、速率限制和权限检查；
+- 删除、替换或关闭确定性基线；
+- 以 reward 代替 no-starvation、最低保障和恢复所有权等硬不变量。
+
+策略超时、崩溃、输出非法、版本不兼容、置信度不足或 Guard 拒绝时，系统必须在有界时间内
+继续执行确定性基线。模型服务不可用不能成为内核不可用的原因。
+
+## 4. Linux 的角色
+
+Linux、cgroup、`sched_ext` 和 eBPF 继续作为：
+
+- 传统策略对照组；
+- workload 与指标采集实验台；
+- 在自研内核机制成熟前验证生命周期假设的参考实现；
+- 用于比较开销、正确性和收益的外部基线。
+
+它们不是 FlowKernel 最终可信核心的实现语言或永久执行底座。任何在 Linux 实验台得到的结论
+都必须标注环境，不能直接声称已在 FlowKernel 内核中成立。
+
+## 5. 首个可实现边界
+
+首个内核里程碑不追求通用操作系统功能齐全，只要求形成可验证的最小闭环：
+
+- 可重复启动、停止和异常退出；
+- 固定平台上的时钟、中断和最小上下文切换；
+- 静态任务与资源描述；
+- 明确的生命周期状态机；
+- 一条确定性调度与资源回收基线；
+- 可拒绝非法建议的 C Guard；
+- 串行审计记录和宿主侧可重放测试；
+- 模型完全缺席时仍能正常运行。
+
+文件系统、网络栈、驱动生态、多核扩展、在线强化学习和分布式控制都不能挤进这个最小闭环。
+每增加一个机制，都必须先说明它回答哪个研究问题，以及失败时如何回到上一个稳定状态。

docs/conceptual-origin.md

@@ -7,18 +7,22 @@
 
 问题最初来自应用工程中反复出现的生命周期管理：Spring Bean 由容器创建、装配、启动和
 销毁，业务服务与容器 workload 也经历启动、健康、退避、恢复和终止。继续向下观察时，
-进程、cgroup 和操作系统资源同样存在状态转换、所有权和回收边界。
+内核子系统、任务和资源同样存在构造、绑定、启动、运行、降级、停止与回收边界。
 
 这些层次都可以抽象出一个控制循环：
 
 ```text
 Observe -> Represent -> Decide -> Guard -> Act -> Measure
 ```
 
-应用代码通常使用状态机、阈值和 `if/else` 完成 `Decide`。Kubernetes 等控制器使用期望
-状态与实际状态之间的差异驱动收敛。操作系统则通过确定性机制调度进程并分配资源。
-FlowKernel 的问题由此形成：当 workload 具有较长生命周期、可观测进展、检查点和恢复
-成本时，资源策略是否仍应只依赖瞬时占用与固定阈值？
+应用代码通常使用状态机、阈值、`if`、`for` 和 `while` 完成 `Decide`。Kubernetes 等
+控制器使用期望状态与实际状态之间的差异驱动收敛。操作系统则通过确定性机制调度任务并
+分配资源。FlowKernel 的问题由此形成：当 workload 具有较长生命周期、可观测进展、
+检查点和恢复成本时，资源策略是否仍应只依赖瞬时占用与固定阈值？
+
+控制语句少不等于系统天然简单。Spring Boot 真正提供的启发是把阶段、依赖、启动顺序、
+失败传播和关闭回收写成显式契约。FlowKernel 将这套思维重建为内核自己的状态机，不引入
+Spring runtime、反射或应用层依赖注入。
 
 ## 相似不等于等价
 
@@ -30,25 +34,28 @@ FlowKernel 的问题由此形成：当 workload 具有较长生命周期、可
 - 学习策略包含统计误差、分布漂移和不可解释输出。
 
 因此，FlowKernel 不是把应用框架或 Kubernetes 机械下沉到内核，也不让模型接管底层
-机制。跨层观察只用于提出问题，不能替代分层设计和逐层证据。
+机制。跨层观察只用于提出问题，不能替代 C 可信核心、最小汇编边界、分层设计和逐层证据。
 
 ## 研究假设的形成
 
 手写规则擅长表达明确不变量，但在高维观测、长期依赖和多目标权衡下可能快速膨胀。由此
-产生一个受限假设：学习方法可以尝试承担部分 Slow Path 的 `Decide`，而确定性机制继续
-负责权限、硬资源上限、最低保障、动作幅度和故障回退。
+产生一个受限假设：学习方法可以尝试承担部分 Slow Path 的 `Propose`，而确定性机制继续
+负责裁决、权限、硬资源上限、最低保障、动作幅度和故障回退。
 
 ```text
 human-defined state and actions
   -> rule baseline
   -> bounded policy proposal
-  -> deterministic guard
-  -> Linux enforcement
+  -> deterministic C guard
+  -> bounded C executor
 ```
 
 这里的“可以尝试”不是技术承诺。如果规则在效果、稳定性、可解释性或成本上更优，研究
 结论应当保留规则，而不是为了使用 AI 强行进入下一阶段。
 
+Linux、cgroup、`sched_ext` 和 eBPF 保留为 reference lab，用于观测、对照和快速验证候选
+动作；它们不是最终 FlowKernel target 的永久执行底座。
+
 ## 为什么先做 R0
 
 项目必须先建立传统调度、静态规则和可复现 workload 基线，才能回答三个基本问题：
@@ -57,13 +64,14 @@ human-defined state and actions
 2. 新策略是否真正优于更简单的方法；
 3. 收益是否足以覆盖推理、状态同步和故障处理成本。
 
-只有这些问题获得证据后，FlowKernel 才会从概念来源进入实现研究。应用层项目可以提供
-workload、故障模式和资源边界样本，但它们只是问题来源与候选控制组，不是操作系统研究
-已经成立的证明。
+R0 还必须先固定受限 C 子集、工具链、启动契约和传统对照环境。只有这些问题获得证据后，
+FlowKernel 才会从概念来源进入最小内核实现。应用层项目可以提供 workload、故障模式和
+资源边界样本，但它们只是问题来源与候选控制组，不是操作系统研究已经成立的证明。
 
 ## 与其他文档的关系
 
 - [愿景与边界](vision.md) 定义研究对象、Fast Path 和 Slow Path；
+- [C-first 内核契约](c-first-kernel-contract.md) 定义语言、生命周期、Guard 和回退边界；
 - [架构假设](architecture-hypotheses.md) 列出等待验证的结构；
 - [前人工作与阅读地图](prior-art.md) 约束新颖性判断；
 - [证据规则](evidence-policy.md) 规定状态声明和实验门槛。