refactor(framework): inline fkst-common 进 runtime_contract(#362)

CLAUDE.md

@@ -362,7 +362,7 @@ git branch 直接看出 谱系:
 - worktree 与 ref namespace 一致;**不**用 detached HEAD(事实源唯一 + 演化痕迹要 branch ref 才 grep-able)
 
 ### Tagging
-- Semver `v<MAJOR>.<MINOR>.<PATCH>`;三 crate 独立 versioning(`fkst-supervisor / fkst-framework / fkst-common`);`git tag -s vX.Y.Z`(GPG signed)
+- Semver `v<MAJOR>.<MINOR>.<PATCH>`;双 crate 独立 versioning(`fkst-supervisor / fkst-framework`),runtime contract 位于 `crates/fkst-framework/src/runtime_contract/`;`git tag -s vX.Y.Z`(GPG signed)
 
 ### Commit message —— Conventional Commits
 - 格式:`<type>(<scope>): <subject>`,`<type>` ∈ `feat / fix / refactor / docs / test / chore / perf / build / ci / revert`

Cargo.toml

@@ -1,7 +1,6 @@
 [workspace]
 resolver = "2"
 members = [
-    "crates/fkst-common",
     "crates/fkst-supervisor",
     "crates/fkst-framework",
 ]

conformance/host_runtime_paths.sh

@@ -46,12 +46,12 @@ allowed_runtime_literal() {
   case "$hit" in
     conformance/tier_boundary.sh:*) return 0 ;;
     conformance/root_cleanliness_guard.sh:*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'RuntimeLayout::new(".fkst/runtime")'*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'=> "worktrees",'*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'=> "codex-permits",'*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'=> "evolve-requests",'*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'=> "pipeline",'*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'=> "mailbox",'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'RuntimeLayout::new(".fkst/runtime")'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'=> "worktrees",'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'=> "codex-permits",'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'=> "evolve-requests",'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'=> "pipeline",'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'=> "mailbox",'*) return 0 ;;
     crates/fkst-framework/src/sdk_git.rs:*) return 0 ;;
     conformance/run_all.sh:*) return 0 ;;
     scripts/check_source_english.sh:*) return 0 ;;
@@ -211,13 +211,13 @@ self_test() {
   write_fixture_file "$ok" raisers/inbox_watch.lua 'source { type = "file_watch", glob = config.runtime_glob("evolve_inbox") }'
   write_fixture_file "$ok" fkst/paths.lua 'local KIND_DIRS = { logs = "logs" }'
   write_fixture_file "$ok" scripts/host-helper.sh 'printf "%s\n" "$FKST_RUNTIME_ROOT"'
-  write_fixture_file "$ok" crates/fkst-common/src/lib.rs 'pub fn runtime_root() -> Option<String> { std::env::var("FKST_RUNTIME_ROOT").ok() }'
+  write_fixture_file "$ok" crates/fkst-framework/src/runtime_contract/mod.rs 'pub fn runtime_root() -> Option<String> { std::env::var("FKST_RUNTIME_ROOT").ok() }'
 
   write_fixture_file "$runtime_bad" departments/evolve/main.lua 'local p = ".evolve-requests/inbox"'
   write_fixture_file "$runtime_bad" departments/evolve/policy.lua 'local mode = "dogfood-tracked"'
   write_fixture_file "$runtime_bad" raisers/inbox_watch.lua 'source { type = "file_watch", glob = ".evolve-requests/inbox/*.md" }'
   write_fixture_file "$runtime_bad" scripts/host-helper.sh 'printf "%s\n" ".fkst/runtime/worktrees"'
-  write_fixture_file "$runtime_bad" crates/fkst-common/src/lib.rs 'pub const BAD_RUNTIME_ROOT: &str = ".fkst/runtime";'
+  write_fixture_file "$runtime_bad" crates/fkst-framework/src/runtime_contract/mod.rs 'pub const BAD_RUNTIME_ROOT: &str = ".fkst/runtime";'
   write_fixture_file "$runtime_bad" crates/fkst-framework/src/known_good.rs 'const BAD_HEALTH_LOCK: &str = ".framework.lock";'
   write_fixture_file "$runtime_bad" fkst/paths.lua 'local DEFAULT_RUNTIME_ROOT = ".fkst/runtime"'
   write_fixture_file "$runtime_bad" scripts/bad-record.sh 'printf "%s\n" "record://pipeline"'
@@ -238,15 +238,15 @@ self_test() {
   write_fixture_file "$branch_bad" departments/evolve/main.lua 'local branch = "develop"'
   write_fixture_file "$branch_bad" raisers/inbox_watch.lua 'local branch = "auto-refact-dev"'
   write_fixture_file "$branch_bad" scripts/host-helper.sh 'printf "%s\n" "self-evo"'
-  write_fixture_file "$branch_bad" crates/fkst-common/src/lib.rs 'pub const BAD_BRANCH: &str = "develop";'
+  write_fixture_file "$branch_bad" crates/fkst-framework/src/runtime_contract/mod.rs 'pub const BAD_BRANCH: &str = "develop";'
   write_fixture_file "$sentinel_bad" departments/evolve/main.lua 'local sentinel = "⟦AI:FKST⟧"'
   write_fixture_file "$sentinel_bad" raisers/inbox_watch.lua 'local sentinel = "⟦AI:FKST⟧"'
   write_fixture_file "$sentinel_bad" scripts/host-helper.sh 'printf "%s\n" "⟦AI:FKST⟧"'
-  write_fixture_file "$sentinel_bad" crates/fkst-common/src/lib.rs 'pub const BAD_SENTINEL: &str = "⟦AI:FKST⟧";'
+  write_fixture_file "$sentinel_bad" crates/fkst-framework/src/runtime_contract/mod.rs 'pub const BAD_SENTINEL: &str = "⟦AI:FKST⟧";'
   write_fixture_file "$sentinel_comment_bad" departments/evolve/main.lua '-- ⟦AI:FKST⟧'
   write_fixture_file "$sentinel_comment_bad" raisers/inbox_watch.lua '-- ⟦AI:FKST⟧'
   write_fixture_file "$sentinel_comment_bad" scripts/host-helper.sh '# ⟦AI:FKST⟧'
-  write_fixture_file "$sentinel_comment_bad" crates/fkst-common/src/lib.rs '//! ⟦AI:FKST⟧'
+  write_fixture_file "$sentinel_comment_bad" crates/fkst-framework/src/runtime_contract/mod.rs '//! ⟦AI:FKST⟧'
   write_fixture_file "$excluded_test" departments/evolve/main_test.lua 'local p = ".evolve-requests/inbox"'
   write_fixture_file "$excluded_test" departments/evolve/test_support.lua '-- ⟦AI:FKST⟧'
   write_fixture_file "$excluded_test" scripts/host-helper_test.sh '# ⟦AI:FKST⟧'
@@ -260,7 +260,7 @@ self_test() {
     'runtime:departments/evolve/policy.lua:' \
     'runtime:raisers/inbox_watch.lua:' \
     'runtime:scripts/host-helper.sh:' \
-    'runtime:crates/fkst-common/src/lib.rs:' \
+    'runtime:crates/fkst-framework/src/runtime_contract/mod.rs:' \
     'runtime:crates/fkst-framework/src/known_good.rs:' \
     'runtime:fkst/paths.lua:' \
     'forbidden_runtime_namespace:scripts/bad-record.sh:' \
@@ -282,17 +282,17 @@ self_test() {
     'branch:departments/evolve/main.lua:' \
     'branch:raisers/inbox_watch.lua:' \
     'branch:scripts/host-helper.sh:' \
-    'branch:crates/fkst-common/src/lib.rs:'
+    'branch:crates/fkst-framework/src/runtime_contract/mod.rs:'
   expect_guard_failure_contains "$sentinel_bad" sentinel \
     'sentinel:departments/evolve/main.lua:' \
     'sentinel:raisers/inbox_watch.lua:' \
     'sentinel:scripts/host-helper.sh:' \
-    'sentinel:crates/fkst-common/src/lib.rs:'
+    'sentinel:crates/fkst-framework/src/runtime_contract/mod.rs:'
   expect_guard_failure_contains "$sentinel_comment_bad" sentinel \
     'sentinel:departments/evolve/main.lua:' \
     'sentinel:raisers/inbox_watch.lua:' \
     'sentinel:scripts/host-helper.sh:' \
-    'sentinel:crates/fkst-common/src/lib.rs:'
+    'sentinel:crates/fkst-framework/src/runtime_contract/mod.rs:'
 }
 
 case "${1:-}" in

conformance/no_legacy_surface_guard.sh

@@ -42,10 +42,10 @@ allowed_hit() {
     share/fkst/departments/review/reviewer_architect_prompt.txt:*) return 0 ;;
     share/fkst/departments/review/reviewer_quality_prompt.txt:*) return 0 ;;
     share/fkst/departments/verify/prompt.txt:*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'old)'*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'old) ='*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'self.old.take()'*) return 0 ;;
-    crates/fkst-common/src/runtime_layout.rs:*'Some(old)'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'old)'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'old) ='*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'self.old.take()'*) return 0 ;;
+    crates/fkst-framework/src/runtime_contract/runtime_layout.rs:*'Some(old)'*) return 0 ;;
     crates/fkst-framework/src/known_good.rs:*old_known_good*) return 0 ;;
     share/fkst/departments/promoter/main.lua:*old_known_good*) return 0 ;;
     share/fkst/departments/promoter/main_test.lua:*old_known_good*) return 0 ;;

conformance/operational_tunable_defaults.sh

@@ -71,7 +71,7 @@ operational_tunable_read_paths() {
   (
     cd "$repo"
     git grep -hoE 'tunables/[A-Za-z0-9_./-]+\.txt' -- \
-      share/fkst scripts/fkst-config.sh crates/fkst-framework/src crates/fkst-supervisor/src crates/fkst-common/src \
+      share/fkst scripts/fkst-config.sh crates/fkst-framework/src crates/fkst-supervisor/src \
       ':(exclude)share/fkst/**/*_test.lua' \
       ':(exclude)share/fkst/**/test_support.lua' \
       ':(exclude)share/fkst/fkst/package_asset_test.lua' \
@@ -152,7 +152,7 @@ make_self_test_fixture() {
 
   mkdir -p "$root/scripts" "$root/share/fkst/fkst" "$root/share/fkst/tunables" \
     "$root/share/fkst/departments/sample" "$root/crates/fkst-framework/src" \
-    "$root/crates/fkst-supervisor/src" "$root/crates/fkst-common/src"
+    "$root/crates/fkst-supervisor/src"
   cp "$src/scripts/fkst-config.sh" "$root/scripts/fkst-config.sh"
   cp "$src/share/fkst/fkst/package_asset.lua" "$root/share/fkst/fkst/package_asset.lua"
   cp "$src/share/fkst/fkst/tunable.lua" "$root/share/fkst/fkst/tunable.lua"
@@ -162,7 +162,7 @@ make_self_test_fixture() {
     operational_defaults_script_fixture.txt \
     operational_defaults_framework_fixture.txt \
     operational_defaults_supervisor_fixture.txt \
-    operational_defaults_common_fixture.txt
+    operational_defaults_framework_contract_fixture.txt
   do
     write_file "$root" "share/fkst/tunables/$fixture_tunable" "1"
   done
@@ -178,8 +178,8 @@ return { budget = budget }'
   write_file "$root" crates/fkst-supervisor/src/main.rs \
     'pub const OPERATIONAL_DEFAULTS_SUPERVISOR_FIXTURE: &str = "tunables/operational_defaults_supervisor_fixture.txt";
 fn main() {}'
-  write_file "$root" crates/fkst-common/src/lib.rs \
-    'pub const OPERATIONAL_DEFAULTS_COMMON_FIXTURE: &str = "tunables/operational_defaults_common_fixture.txt";'
+  write_file "$root" crates/fkst-framework/src/runtime_contract/mod.rs \
+    'pub const OPERATIONAL_DEFAULTS_FRAMEWORK_CONTRACT_FIXTURE: &str = "tunables/operational_defaults_framework_contract_fixture.txt";'
 
   git -C "$root" init -q
   git -C "$root" add .
@@ -250,7 +250,7 @@ share operational_defaults_share_fixture.txt
 script operational_defaults_script_fixture.txt
 framework operational_defaults_framework_fixture.txt
 supervisor operational_defaults_supervisor_fixture.txt
-common operational_defaults_common_fixture.txt
+framework_contract operational_defaults_framework_contract_fixture.txt
 CASES
 
   printf 'operational tunable defaults self-test ok\n'

conformance/tier_boundary.sh

@@ -13,7 +13,7 @@ supervisor_files="$(find crates/fkst-supervisor/src -type f -name '*.rs' | sort)
 line_count="$(wc -l < crates/fkst-supervisor/src/main.rs | tr -d ' ')"
 [[ "$line_count" -le 150 ]] || fail "Tier I supervisor has $line_count lines, limit is 150"
 
-forbidden='mlua|notify|fkst_common::config|fkst_common::validation|RaiserDecl|DepartmentDecl|QueueDecl|Fanout|parse_raised|spawn_framework|tokio::sync::mpsc|\.evolve-requests|departments/|raisers/|known_good|known-good|refs/known-good|KNOWN_GOOD_HEALTH|git update-ref|git checkout|HealthGate|KnownGoodRef|checkout-known-good'
+forbidden='mlua|notify|runtime_contract::config|runtime_contract::validation|RaiserDecl|DepartmentDecl|QueueDecl|Fanout|parse_raised|spawn_framework|tokio::sync::mpsc|\.evolve-requests|departments/|raisers/|known_good|known-good|refs/known-good|KNOWN_GOOD_HEALTH|git update-ref|git checkout|HealthGate|KnownGoodRef|checkout-known-good'
 if grep -R -E -n "$forbidden" crates/fkst-supervisor/src >/dev/null; then
   grep -R -E -n "$forbidden" crates/fkst-supervisor/src >&2
   fail "Tier I imports or mentions event runtime surface"

crates/fkst-framework/Cargo.toml

@@ -9,7 +9,6 @@ name = "fkst-framework"
 path = "src/main.rs"
 
 [dependencies]
-fkst-common = { path = "../fkst-common" }
 mlua = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }

crates/fkst-framework/src/host_conformance.rs

@@ -1,8 +1,9 @@
 use crate::path_resolver::PackageRoots;
 use crate::supervise;
 use anyhow::{Context, Result};
-use fkst_common::validation::validate;
-use fkst_common::{RuntimeKind, RuntimeLayout};
+use crate::runtime_contract::config::Config;
+use crate::runtime_contract::validation::validate;
+use crate::runtime_contract::runtime_layout::{RuntimeKind, RuntimeLayout};
 
 pub(crate) struct HostConformanceOptions {
     pub(crate) roots: PackageRoots,
@@ -127,7 +128,7 @@ impl HostConformanceSuite {
         }
     }
 
-    fn check_department_non_empty(&self, cfg: &fkst_common::config::Config) -> HostCheck {
+    fn check_department_non_empty(&self, cfg: &Config) -> HostCheck {
         if cfg.department.is_empty() {
             HostCheck::fail(
                 "department-non-empty",
@@ -141,7 +142,7 @@ impl HostConformanceSuite {
         }
     }
 
-    fn check_schema_validation(&self, cfg: &fkst_common::config::Config) -> HostCheck {
+    fn check_schema_validation(&self, cfg: &Config) -> HostCheck {
         match validate(cfg, self.options.roots.host_root()) {
             Ok(warnings) => {
                 if warnings.is_empty() {

crates/fkst-framework/src/known_good.rs

@@ -1,7 +1,7 @@
 //! Known-good swap owner for CAS, candidate checkout, health observation, and rollback witnesses.
 
 use anyhow::{Context, Result};
-use fkst_common::{RuntimeKind, RuntimeLayout};
+use crate::runtime_contract::runtime_layout::{RuntimeKind, RuntimeLayout};
 use nix::fcntl::{flock, FlockArg};
 use std::fs::{File, OpenOptions};
 use std::io::{Read, Seek, SeekFrom, Write};

crates/fkst-framework/src/main.rs

@@ -25,6 +25,7 @@ mod known_good;
 mod mlua_init;
 mod path_resolver;
 mod raise;
+mod runtime_contract;
 mod sdk_basic;
 mod sdk_codex;
 mod sdk_fs;

crates/fkst-framework/src/runtime_contract/mod.rs

@@ -0,0 +1,8 @@
+pub(crate) mod config;
+pub(crate) mod error;
+pub(crate) mod event;
+pub(crate) mod runtime_layout;
+pub(crate) mod validation;
+
+#[cfg(test)]
+mod validation_test;

crates/fkst-common/src/validation.rs → crates/fkst-framework/src/runtime_contract/validation.rs

@@ -1,7 +1,7 @@
 //! Schema validation on config load. Refuse-to-start on any violation.
 
-use crate::config::{Config, RaiserDecl};
-use crate::error::FkstError;
+use super::config::{Config, RaiserDecl};
+use super::error::FkstError;
 
 /// Validate cross-references and per-decl invariants.
 ///
@@ -205,7 +205,7 @@ fn queue_feedback_departments(cfg: &Config, qname: &str) -> Vec<String> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::config::{DepartmentDecl, LimitsDecl, QueueDecl};
+    use super::super::config::{DepartmentDecl, LimitsDecl, QueueDecl};
     use tempfile::tempdir;
 
     fn touch(root: &std::path::Path, name: &str) -> std::path::PathBuf {

crates/fkst-common/tests/validation.rs → crates/fkst-framework/src/runtime_contract/validation_test.rs

@@ -1,7 +1,7 @@
-// crate-level integration tests own behavior coverage while runtime modules keep runtime code.
+// Runtime contract tests own behavior coverage while runtime modules keep runtime code.
 
-use fkst_common::config::{Config, DepartmentDecl, LimitsDecl, QueueDecl, RaiserDecl};
-use fkst_common::validation::validate;
+use super::config::{Config, DepartmentDecl, LimitsDecl, QueueDecl, RaiserDecl};
+use super::validation::validate;
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use tempfile::tempdir;

crates/fkst-framework/src/sdk_codex.rs

@@ -4,7 +4,7 @@
 //! locks exclusive non-blocking. If none available, block on the first one. Permit
 //! holds for the duration of the codex subprocess; released on file drop after exit.
 
-use fkst_common::{RuntimeKind, RuntimeLayout};
+use crate::runtime_contract::runtime_layout::{RuntimeKind, RuntimeLayout};
 use mlua::{AnyUserData, Lua, Result, Table, UserData};
 use nix::fcntl::{flock, FlockArg};
 use std::collections::HashSet;

crates/fkst-framework/src/sdk_git.rs

@@ -6,7 +6,7 @@
 //! - count_worktrees()          -- count linked worktrees excluding main checkout
 //! - list_orphan_worktrees(pfx) -- list <runtime>/worktrees/<pfx>* linked worktree paths
 
-use fkst_common::{RuntimeKind, RuntimeLayout};
+use crate::runtime_contract::runtime_layout::{RuntimeKind, RuntimeLayout};
 use mlua::{Function, Lua, Result};
 use nix::fcntl::{flock, FlockArg};
 use std::os::fd::AsRawFd;

crates/fkst-framework/src/self_test.rs

@@ -1,8 +1,8 @@
 //! Framework-local startup self-test.
 
 use anyhow::{Context, Result};
-use fkst_common::config::{Config, DepartmentDecl, LimitsDecl, QueueDecl, RaiserDecl};
-use fkst_common::validation::validate;
+use crate::runtime_contract::config::{Config, DepartmentDecl, LimitsDecl, QueueDecl, RaiserDecl};
+use crate::runtime_contract::validation::validate;
 use std::collections::HashMap;
 use std::path::PathBuf;
 use std::time::{SystemTime, UNIX_EPOCH};

crates/fkst-framework/src/supervise/consumer.rs

@@ -6,9 +6,9 @@ use super::event_fanout::Fanout;
 use super::raised::parse_raised;
 use super::source_runner::parse_duration;
 use super::spawner::spawn_framework;
-use fkst_common::config::DepartmentDecl;
-use fkst_common::Event;
-use fkst_common::{RuntimeKind, RuntimeLayout};
+use crate::runtime_contract::config::DepartmentDecl;
+use crate::runtime_contract::event::Event;
+use crate::runtime_contract::runtime_layout::{RuntimeKind, RuntimeLayout};
 use std::path::PathBuf;
 use tokio::sync::mpsc;
 use tokio::task::JoinHandle;

crates/fkst-framework/src/supervise/event_fanout.rs

@@ -7,7 +7,7 @@
 //! subscriber. Slow consumer drops affect only that subscriber. Unknown queues
 //! warn and drop the event.
 
-use fkst_common::Event;
+use crate::runtime_contract::event::Event;
 use std::collections::HashMap;
 use std::sync::Arc;
 use tokio::sync::mpsc;

crates/fkst-framework/src/supervise/graph_scan.rs

@@ -9,8 +9,8 @@
 //! `M.spec.fanout`. Host graph defaults are read before graph materialization.
 
 use anyhow::{anyhow, bail, Context, Result};
-use fkst_common::config::{Config, DepartmentDecl, LimitsDecl, QueueDecl, RaiserDecl};
-use fkst_common::{RuntimeKind, RuntimeLayout};
+use crate::runtime_contract::config::{Config, DepartmentDecl, LimitsDecl, QueueDecl, RaiserDecl};
+use crate::runtime_contract::runtime_layout::{RuntimeKind, RuntimeLayout};
 use mlua::{Lua, LuaSerdeExt, Table, Value as LuaValue};
 use serde::Deserialize;
 use std::collections::{HashMap, HashSet};

crates/fkst-framework/src/supervise/mod.rs

@@ -1,6 +1,6 @@
 use anyhow::Result;
-use fkst_common::config::{Config, RaiserDecl};
-use fkst_common::validation::validate;
+use crate::runtime_contract::config::{Config, RaiserDecl};
+use crate::runtime_contract::validation::validate;
 use std::path::PathBuf;
 use tracing::{error, info, warn};
 

crates/fkst-framework/src/supervise/raised.rs

@@ -9,7 +9,7 @@
 //! `log.info("RAISED: foo")` from being mistaken for the actual protocol.
 
 use base64::Engine;
-use fkst_common::Event;
+use crate::runtime_contract::event::Event;
 use serde::Deserialize;
 use serde_json::Value;
 use tracing::warn;