fix(sdk): reserved-leaf path for runtime-key primitives so prefix keys don't collide (#86)

with_lock/once/cache_* wrote their backing file at the key path, so prefix-related keys (a/b/c and a/b/c/d) collided with ENOTDIR — permanently dead-lettering consensus convergence (found via dogfood #614). Backing files now live at <base>/<key>/=lock|=mark|=value (= is forbidden in keys). with_lock also reserves the cache namespace. verify.sh green. ⟦AI:FKST⟧

Author: ElonSG

README.md

@@ -141,11 +141,11 @@ Lua 单元测试由 `fkst-framework test` 执行。runner 只发现 package root
 
 `fkst.test.mock_command(pattern, result)` 劫持 test mode 中的 `exec_sync`、codex SDK 与 git SDK 外部命令调用；渲染命令行按前缀或子串匹配，mock 按注册顺序一次性消费。`result` 是 `{ stdout = "", stderr = "", exit_code = 0 }` 形状，`stderr` 与 `exit_code` 可省略。未 mock 的外部命令 fail closed 且不启动真实进程。`fkst.test.command_calls()` 返回已记录调用，包含渲染命令、program、args、stdin、stdout、stderr 与 exit_code。`setup_worktree` 在 test mode 也通过 git mock runner，但 mock 不合成 worktree 副作用。
 
-production Lua SDK 包含 `once(key, fn) -> boolean`。它是 best-effort per-key de-bounce scratch marker，不是 durable state。`key` 必须是非空相对 filesystem path，`/` 表示目录；每个 segment 非空、匹配 `[A-Za-z0-9._-]+`，且不是 `.` 或 `..`；禁止 leading / trailing `/`、`//`、反斜杠、NUL 与绝对路径。framework 直接使用校验后的 key，在 `<RT>/locks/once/<key>` 上获取 exclusive flock，再检查 `<RT>/marks/<key>`。`locks/once/` 是 once 内部锁的保留子目录，不属于 `with_lock` 用户锁命名空间。marker 已存在时返回 `false` 且不调用 `fn`；marker 不存在时调用 `fn`，成功后写入 marker 并返回 `true`；`fn` 失败时错误原样传播且不写 marker，后续调用会重试。
+production Lua SDK 包含 `once(key, fn) -> boolean`。它是 best-effort per-key de-bounce scratch marker，不是 durable state。`key` 必须是非空相对 filesystem path，`/` 表示目录；每个 segment 非空、匹配 `[A-Za-z0-9._-]+`，且不是 `.` 或 `..`；禁止 leading / trailing `/`、`//`、反斜杠、NUL 与绝对路径。framework 直接使用校验后的 key，在 `<RT>/locks/once/<key>/=lock` 上获取 exclusive flock，再检查 `<RT>/marks/<key>/=mark`。`locks/once/` 是 once 内部锁的保留子目录，不属于 `with_lock` 用户锁命名空间。marker 已存在时返回 `false` 且不调用 `fn`；marker 不存在时调用 `fn`，成功后写入 marker 并返回 `true`；`fn` 失败时错误原样传播且不写 marker，后续调用会重试。
 
-`once` 的可观察性来自 engine log 和 runtime scratch：skip / run 决策会写入可 grep 的 `once decision=... key=...` 结构化日志；marker 内容只提供 `key` 与 `marked_at` 的人工可读提示，不参与判重；LIVE lock holder 可用 `lsof <RT>/locks/once/<key>` 查看。
+`once` 的可观察性来自 engine log 和 runtime scratch：skip / run 决策会写入可 grep 的 `once decision=... key=...` 结构化日志；marker 内容只提供 `key` 与 `marked_at` 的人工可读提示，不参与判重；LIVE lock holder 可用 `lsof <RT>/locks/once/<key>/=lock` 查看。
 
-production Lua SDK 还包含 `cache_set(key, value[, ttl_seconds])`、`cache_get(key) -> string | nil` 与 `cache_expire(key)`。它们是 best-effort scratch KV primitive，不是 durable state。`key` 使用同一 runtime key 合约，framework 直接读写 `<RT>/cache/<key>`，所以 `<RT>/cache` 是人工可浏览的目录树；`cache_set` 原子覆盖写入带 expiry metadata 的 string value，`ttl_seconds` 缺省或 nil 表示不过期，正数表示按 wall-clock deadline 过期；`cache_get` 命中时返回 string，缺失、过期、malformed 或 unreadable 时返回 nil，过期文件会 best-effort lazy evict；`cache_expire` 显式删除 key，缺失视为成功。`<RT>` 被清空或换 host 后，`cache_get` 返回 nil，调用者必须从 durable source 重新推导；需要 read-compare-write 原子性时由调用者外层使用 `with_lock`。
+production Lua SDK 还包含 `cache_set(key, value[, ttl_seconds])`、`cache_get(key) -> string | nil` 与 `cache_expire(key)`。它们是 best-effort scratch KV primitive，不是 durable state。`key` 使用同一 runtime key 合约，framework 读写 `<RT>/cache/<key>/=value`，所以 `<RT>/cache` 是人工可浏览的目录树；reserved leaf `=value` 不会与有效 key 冲突，因为 `=` 不在合法 key segment 字符集内。`cache_set` 原子覆盖写入带 expiry metadata 的 string value，`ttl_seconds` 缺省或 nil 表示不过期，正数表示按 wall-clock deadline 过期；`cache_get` 命中时返回 string，缺失、过期、malformed 或 unreadable 时返回 nil，过期文件会 best-effort lazy evict；`cache_expire` 显式删除 key，缺失视为成功。`<RT>` 被清空或换 host 后，`cache_get` 返回 nil，调用者必须从 durable source 重新推导；需要 read-compare-write 原子性时由调用者外层使用 `with_lock`。
 
 production Lua SDK 包含 `graph_json() -> string`。它是显式授权的只读 composed graph introspection：只有当前 Department 的 `M.spec.graph_json = true` 时可调用。调用时按当前 fixed package roots input set 与 host root 重新扫描并验证 graph，返回稳定排序的 `fkst.graph.v1` JSON string，供 package/host 渲染 topology view。输出包含 raiser / queue / department nodes、消息流 edges、department `consumes` / `produces` / `ephemeral` / `stall_window` / materialized `retry` metadata；node `id` 与 edge endpoint 使用 `kind:canonical_name` 形态；不包含 runtime state、queue capacity、`lua` path 或 `owner_root`。
 

SPEC.md

@@ -73,9 +73,9 @@
 - 固定 Lua SDK surface 锚点是 `fixed-lua-sdk-surface`；允许 surface 是 `pipeline`、`source`、`raise`、`spawn_codex_sync`、`spawn_codex`、`fkst.codex_runs`、`exec_sync`、`await_all`、`with_lock`、`once`、`cache_set`、`cache_get`、`cache_expire`、`graph_json`、`t`、`git_log_count`、`git_log_grep`、`count_worktrees`、`list_orphan_worktrees`、`setup_worktree`、`file`、`json.decode`、`log.info`、`log.warn`、`log.error`、`now`。
 - `t(key[, vars])` is the fixed key-catalog localization primitive. It reads owner-root `locales/<locale>.lua` and `locales/en.lua`, resolves `<locale>` from `FKST_OUTPUT_LANG`, falls back to `en` for missing locale or key with a structured warning, and interpolates `{name}` placeholders from scalar vars. Catalog files are flat Lua tables with stable string keys and literal UTF-8 string values. `en` is the reference locale; conformance requires every non-`en` catalog to cover all `en` keys, rejects decode-helper-hidden literals in `locales/`, and rejects machine protocol tokens in catalog keys or values. Locale catalogs are the sanctioned exception to the source-files-English rule for prose literals; machine tokens remain code and must not be catalog content.
 - `graph_json() -> string` 是显式授权的只读 introspection surface；只有当前 Department 的 `M.spec.graph_json = true` 时可调用。它按当前 fixed package roots input set 与 host root 重新扫描并验证 composed graph，返回稳定 JSON 字符串，schema 为 `fkst.graph.v1`。输出只包含 topology fact：raiser / queue / department nodes、raiser→queue / queue→department / department→queue edges，以及 department 的 `consumes`、`produces`、`ephemeral`、`stall_window` 和 materialized `retry` metadata；node `id` 与 edge endpoint 使用 `kind:canonical_name` 形态以区分同名 raiser / queue / department；不输出 `lua` path、`owner_root`、queue capacity 或 runtime state。排序必须确定性。
-- `with_lock(name, fn)`、`once(key, fn)`、`cache_set(key, value[, ttl_seconds])`、`cache_get(key)` 与 `cache_expire(key)` 共用 runtime key 合约：key / name 必须是非空相对 filesystem path，`/` 表示目录；每个 segment 非空、最长 255 bytes、匹配 `[A-Za-z0-9._-]+`，且不是全点 segment（如 `.` / `..` / `...`）；禁止 leading / trailing `/`、`//`、反斜杠、NUL 与绝对路径。校验后的 key 可直接 join 到 `<RT>/{locks,marks,cache}/<key>`，形成可人工浏览的目录树，不再做 byte hex 编码。
-- `once(key, fn)` 在 `<RT>/locks/once/<key>` 上持有 exclusive flock 后检查 `<RT>/marks/<key>`；`locks/once/` 是 once 内部锁的保留子目录，不属于 `with_lock` 用户锁命名空间。marker 已存在时返回 `false` 且不调用 `fn`，不存在时调用 `fn`，成功后写入 marker 并返回 `true`，失败时传播错误且不写 marker。
-- `cache_set(key, value[, ttl_seconds])`、`cache_get(key)` 与 `cache_expire(key)` 读写 `<RT>/cache/<key>`。`cache_set` 原子覆盖写入 byte-exact string value 与可选 expiry metadata；`ttl_seconds` 缺省或 nil 表示不过期，正数表示按 wall-clock deadline 过期。`cache_get` 命中时返回 string，缺失、过期、malformed 或 unreadable 时返回 nil，过期文件会 best-effort lazy evict；`cache_expire` 显式删除 key，缺失视为成功。cache 是 host-local best-effort scratch，不是 durable state；调用者需要 read-compare-write 原子性时必须外层使用 `with_lock`。
+- `with_lock(name, fn)`、`once(key, fn)`、`cache_set(key, value[, ttl_seconds])`、`cache_get(key)` 与 `cache_expire(key)` 共用 runtime key 合约：key / name 必须是非空相对 filesystem path，`/` 表示目录；每个 segment 非空、最长 255 bytes、匹配 `[A-Za-z0-9._-]+`，且不是全点 segment（如 `.` / `..` / `...`）；禁止 leading / trailing `/`、`//`、反斜杠、NUL 与绝对路径。校验后的 key 保持为 `<RT>/{locks,marks,cache}/<key>/` 目录路径，engine 在该目录下写 reserved leaf file（`=lock` / `=mark` / `=value`）；`=` 不在合法 key segment 字符集内，因此不会与有效 key 冲突。
+- `with_lock(name, fn)` 在 `<RT>/locks/<name>/=lock` 上持有 exclusive flock；`once(key, fn)` 在 `<RT>/locks/once/<key>/=lock` 上持有 exclusive flock 后检查 `<RT>/marks/<key>/=mark`；`locks/once/` 是 once 内部锁的保留子目录，不属于 `with_lock` 用户锁命名空间。marker 已存在时返回 `false` 且不调用 `fn`，不存在时调用 `fn`，成功后写入 marker 并返回 `true`，失败时传播错误且不写 marker。
+- `cache_set(key, value[, ttl_seconds])`、`cache_get(key)` 与 `cache_expire(key)` 读写 `<RT>/cache/<key>/=value`。`cache_set` 原子覆盖写入 byte-exact string value 与可选 expiry metadata；`ttl_seconds` 缺省或 nil 表示不过期，正数表示按 wall-clock deadline 过期。`cache_get` 命中时返回 string，缺失、过期、malformed 或 unreadable 时返回 nil，过期文件会 best-effort lazy evict；`cache_expire` 显式删除 key，缺失视为成功。cache 是 host-local best-effort scratch，不是 durable state；调用者需要 read-compare-write 原子性时必须外层使用 `with_lock`。
 - Department 默认以可靠方式消费队列；`M.spec.ephemeral = {"queue"}` 可将本 Department 对指定 consumed queue 的订阅降级为非可靠。`M.spec.retry = false` 只表示失败不重试；`M.spec.retry = { ... }` 可覆盖 `max_attempts`、`base`、`cap` 的任意子集，缺失字段从全局默认补齐。`M.spec.stall_window` 是可靠投递 lease 与续租窗口，不是 framework child 无输出 kill deadline。可靠订阅启动必须有 `FKST_DURABLE_ROOT`，缺失 fail-closed。可靠 source event 必须带 `SourceRef{kind,reference}`；cron 由 raiser 名派生，file_watch 由绝对路径派生，Department `RAISED` 进入可靠 queue 时继承上游 source_ref，缺失则 publish fail-closed 且上游 delivery 不 ack。可靠 consumer 由 Fanout wake + 定时 tick 调用 redb store `lease`，spawn framework 后仅在 exit 0 且 RAISED publish 成功时 `ack`；非零退出、codex timeout、spawn error 或 RAISED publish 失败调用 `retry`，到 max attempts 写 redb dead 表并 best-effort publish `dead_letter`。当前 delivery 来自 `dead_letter` 时抑制再次发送 `dead_letter`。该机制不是新 source kind，不提供 exactly-once；语义是 at-least-once-until-ack，`Fanout::send` 在可靠路径只作进程内唤醒。
 - `spawn_codex_sync` 与 `spawn_codex` 接受 `timeout` opt，默认 3600 秒，作为 codex 子进程整体 wall-clock cap；stdout/stderr 输出只被捕获，不延长 timeout。`spawn_codex` handle 只能由 `await_all` join；单 handle 等待使用 `await_all({handle})`；first-result fanout 与 sleep timer 不是固定 Lua SDK surface。
 - `fkst.codex_runs()` is a read-only bounded observability surface over engine codex run records. It returns running and recent codex runs with `role`, `started_at`, `status` (`running` / `done` / `failed`), bounded `output_tail`, and optional `exit_code`; it does not expose runtime paths or unbounded stdout/stderr.

crates/fkst-common/src/lib.rs

@@ -11,5 +11,8 @@ pub use config::Config;
 pub use durable_layout::{DurableLayout, DURABLE_ROOT_ENV};
 pub use error::FkstError;
 pub use event::Event;
-pub use runtime_layout::{RuntimeKind, RuntimeLayout};
+pub use runtime_layout::{
+    runtime_key_file, RuntimeKind, RuntimeLayout, RUNTIME_LOCK_LEAF, RUNTIME_MARK_LEAF,
+    RUNTIME_VALUE_LEAF,
+};
 pub use validation::validate_runtime_key;

crates/fkst-common/src/runtime_layout.rs

@@ -4,6 +4,9 @@ use anyhow::{anyhow, Result};
 use std::path::{Component, Path, PathBuf};
 
 pub const RUNTIME_ROOT_ENV: &str = "FKST_RUNTIME_ROOT";
+pub const RUNTIME_LOCK_LEAF: &str = "=lock";
+pub const RUNTIME_MARK_LEAF: &str = "=mark";
+pub const RUNTIME_VALUE_LEAF: &str = "=value";
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 // runtime path categories are explicit and bounded before path construction.
@@ -62,6 +65,10 @@ impl RuntimeLayout {
     }
 }
 
+pub fn runtime_key_file(base: &Path, key: &str, leaf: &str) -> PathBuf {
+    base.join(key).join(leaf)
+}
+
 fn reject_traversal(path: &Path) -> Result<()> {
     if path.as_os_str().is_empty() {
         return Err(anyhow!("runtime root must not be empty"));

crates/fkst-framework/src/sdk_cache.rs

@@ -1,6 +1,8 @@
 //! SDK: best-effort host-local scratch key-value cache.
 
-use fkst_common::{validate_runtime_key, RuntimeKind};
+use fkst_common::{
+    runtime_key_file, validate_runtime_key, RuntimeKind, RUNTIME_LOCK_LEAF, RUNTIME_VALUE_LEAF,
+};
 use mlua::{Lua, Result};
 use nix::fcntl::{flock, FlockArg};
 use std::fs::{File, OpenOptions};
@@ -71,7 +73,11 @@ fn cache_set(
     let _lock = acquire_cache_lock(host_root, key)?;
     let layout =
         runtime_context::layout_from_host_root(host_root).map_err(mlua::Error::external)?;
-    let target = layout.runtime_dir(RuntimeKind::Cache).join(key);
+    let target = runtime_key_file(
+        &layout.runtime_dir(RuntimeKind::Cache),
+        key,
+        RUNTIME_VALUE_LEAF,
+    );
     let parent = target.parent().ok_or_else(|| {
         mlua::Error::external(anyhow::anyhow!(
             "cache target '{}' has no parent",
@@ -104,7 +110,11 @@ fn cache_get(host_root: &Path, key: String, clock: &Clock) -> Result<Option<Vec<
     let _lock = acquire_cache_lock(host_root, key)?;
     let layout =
         runtime_context::layout_from_host_root(host_root).map_err(mlua::Error::external)?;
-    let target = layout.runtime_dir(RuntimeKind::Cache).join(key);
+    let target = runtime_key_file(
+        &layout.runtime_dir(RuntimeKind::Cache),
+        key,
+        RUNTIME_VALUE_LEAF,
+    );
     match std::fs::read(&target) {
         Ok(raw) => match decode_entry(&raw) {
             Some((Some(expires_at), _)) if clock() >= expires_at => {
@@ -123,17 +133,19 @@ fn cache_expire(host_root: &Path, key: String) -> Result<()> {
     let _lock = acquire_cache_lock(host_root, key)?;
     let layout =
         runtime_context::layout_from_host_root(host_root).map_err(mlua::Error::external)?;
-    let target = layout.runtime_dir(RuntimeKind::Cache).join(key);
+    let target = runtime_key_file(
+        &layout.runtime_dir(RuntimeKind::Cache),
+        key,
+        RUNTIME_VALUE_LEAF,
+    );
     remove_cache_file(&target)
 }
 
 fn acquire_cache_lock(host_root: &Path, key: &str) -> Result<File> {
     let layout =
         runtime_context::layout_from_host_root(host_root).map_err(mlua::Error::external)?;
-    let path = layout
-        .runtime_dir(RuntimeKind::Locks)
-        .join("cache")
-        .join(key);
+    let cache_locks = layout.runtime_dir(RuntimeKind::Locks).join("cache");
+    let path = runtime_key_file(&cache_locks, key, RUNTIME_LOCK_LEAF);
     let parent = path.parent().ok_or_else(|| {
         mlua::Error::external(anyhow::anyhow!(
             "cache lock target '{}' has no parent",

crates/fkst-framework/src/sdk_git.rs

@@ -6,7 +6,9 @@
 //! - count_worktrees()          -- count linked worktrees excluding main checkout
 //! - list_orphan_worktrees(pfx) -- list <runtime>/worktrees/<pfx>* linked worktree paths
 
-use fkst_common::{validate_runtime_key, RuntimeKind, RuntimeLayout};
+use fkst_common::{
+    runtime_key_file, validate_runtime_key, RuntimeKind, RuntimeLayout, RUNTIME_LOCK_LEAF,
+};
 use mlua::{Function, Lua, Result};
 use nix::fcntl::{flock, FlockArg};
 use std::os::fd::AsRawFd;
@@ -64,10 +66,15 @@ fn register_with_lock(lua: &Lua, host_root: PathBuf) -> Result<()> {
                     "with_lock name '{name}' uses reserved lock namespace 'once'"
                 )));
             }
+            if name == "cache" || name.starts_with("cache/") {
+                return Err(mlua::Error::external(anyhow::anyhow!(
+                    "with_lock name '{name}' uses reserved lock namespace 'cache'"
+                )));
+            }
             let layout = runtime_context::layout_from_host_root(&host_root)
                 .map_err(mlua::Error::external)?;
             let locks = layout.runtime_dir(RuntimeKind::Locks);
-            let path = locks.join(name);
+            let path = runtime_key_file(&locks, name, RUNTIME_LOCK_LEAF);
             let parent = path.parent().ok_or_else(|| {
                 mlua::Error::external(anyhow::anyhow!(
                     "with_lock target '{}' has no parent",

crates/fkst-framework/src/sdk_mark.rs

@@ -1,6 +1,8 @@
 //! SDK: `once(key, fn) -> boolean` best-effort per-key debounce marker.
 
-use fkst_common::{validate_runtime_key, RuntimeKind};
+use fkst_common::{
+    runtime_key_file, validate_runtime_key, RuntimeKind, RUNTIME_LOCK_LEAF, RUNTIME_MARK_LEAF,
+};
 use mlua::{Function, Lua, Result};
 use nix::fcntl::{flock, FlockArg};
 use std::os::fd::AsRawFd;
@@ -21,10 +23,8 @@ fn once(host_root: &Path, key: String, f: Function) -> Result<bool> {
     let key = validate_runtime_key(&key).map_err(mlua::Error::external)?;
     let layout =
         runtime_context::layout_from_host_root(host_root).map_err(mlua::Error::external)?;
-    let lock_path = layout
-        .runtime_dir(RuntimeKind::Locks)
-        .join("once")
-        .join(key);
+    let once_locks = layout.runtime_dir(RuntimeKind::Locks).join("once");
+    let lock_path = runtime_key_file(&once_locks, key, RUNTIME_LOCK_LEAF);
     let lock_parent = lock_path.parent().ok_or_else(|| {
         mlua::Error::external(anyhow::anyhow!(
             "once lock target '{}' has no parent",
@@ -42,7 +42,11 @@ fn once(host_root: &Path, key: String, f: Function) -> Result<bool> {
 
     flock(lock_file.as_raw_fd(), FlockArg::LockExclusive).map_err(mlua::Error::external)?;
 
-    let marker = layout.runtime_dir(RuntimeKind::Marks).join(key);
+    let marker = runtime_key_file(
+        &layout.runtime_dir(RuntimeKind::Marks),
+        key,
+        RUNTIME_MARK_LEAF,
+    );
     if marker.exists() {
         sdk_log::info(&format!("once decision=skip-marked key={key}"));
         drop(lock_file);