worktree-runtime 0.1.0a4__tar.gz → 0.1.1__tar.gz

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/Cargo.lock

@@ -743,7 +743,7 @@ dependencies = [
 
 [[package]]
 name = "worktree_runtime_core"
-version = "0.1.0-alpha.4"
+version = "0.1.1"
 dependencies = [
  "chrono",
  "fs2",
@@ -760,7 +760,7 @@ dependencies = [
 
 [[package]]
 name = "worktree_runtime_pyo3"
-version = "0.1.0-alpha.4"
+version = "0.1.1"
 dependencies = [
  "chrono",
  "pyo3",

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/worktree_runtime_core", "crates/worktree_runtime_pyo3"]
 
 [workspace.package]
-version = "0.1.0-alpha.4"
+version = "0.1.1"
 edition = "2021"
 rust-version = "1.85"
 license = "LicenseRef-Proprietary"
@@ -18,7 +18,7 @@ sha1 = "0.10"
 fs2 = "0.4"
 tempfile = "3.10"
 wait-timeout = "0.2"
-pyo3 = { version = "0.29", features = ["extension-module", "abi3-py310"] }
+pyo3 = { version = "0.29", features = ["abi3-py310"] }
 chrono = "0.4"
 
 [profile.release]

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: worktree-runtime
-Version: 0.1.0a4
-Classifier: Development Status :: 3 - Alpha
+Version: 0.1.1
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: License :: Other/Proprietary License
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/AGENTS.md

@@ -38,13 +38,18 @@ do not treat pytest as the SSOT.
 - **Config precedence**: `NOVELER_WORKTREE_BASE` and
   `config/worktree.yaml` overrides are honored only when `CI` or
   `GITHUB_ACTIONS` is set (`worktree_base_resolver.rs`). Outside CI the
-  base is `~/.adaptive-task/worktrees/<project_id>`. Parse failures in
-  `pyproject.toml` / `config/worktree.yaml` log a warning and fall back to
-  defaults; they are not distinguishable from "file absent" to callers.
-- **project_id**: `resolve_project_id` returns the declared value unchecked;
-  `resolve_project_id_checked` rejects invalid ids; every function that
-  turns an id into a directory name (`resolve_state_dir_name`) validates it
-  and falls back to `noveler`.
+  base is `~/.adaptive-task/worktrees/<project_id>`. A missing
+  `config/worktree.yaml` is the default path. A file that exists but cannot
+  be read or parsed raises `WORKTREE_CONFIG_UNREADABLE` from the resolvers
+  that load it (`resolve_worktree_base`, `resolve_worktree_dir`,
+  `resolve_known_worktree_bases`) when CI consults it.
+- **project_id**: a missing `pyproject.toml` or a missing
+  `tool.adaptive-task.project_id` is `noveler`. An existing file that is not
+  valid TOML raises `WORKTREE_PROJECT_CONFIG_UNREADABLE`. A declared id that
+  fails `^[a-z][a-z0-9_-]{0,63}$` raises `ProjectIdInvalidError`
+  (`PROJECT_ID_INVALID`) from `resolve_project_id` and
+  `resolve_state_dir_name`; it is not used as a directory name. An empty id
+  stays `noveler`.
 - **Logging**: `log::debug!` / `log::warn!` for diagnostics; the two
   `eprintln!` breadcrumbs (`failopen_message`, `suspicious_extra_message`)
   are frozen by tests and stay on stderr.

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/application/binding_lifecycle.rs

@@ -57,11 +57,13 @@ impl From<BindingStoreError> for RegisterBindingError {
     }
 }
 
-fn session_state_subpath(repo_root: &Path) -> PathBuf {
-    let pid = resolve_project_id(Some(&repo_root.to_string_lossy()));
-    PathBuf::from(resolve_state_dir_name(Some(&pid)))
+fn session_state_subpath(
+    repo_root: &Path,
+) -> Result<PathBuf, crate::infrastructure::project_id_resolver::ProjectResolveError> {
+    let pid = resolve_project_id(Some(&repo_root.to_string_lossy()))?;
+    Ok(PathBuf::from(resolve_state_dir_name(Some(&pid))?)
         .join("state")
-        .join("adaptive-task")
+        .join("adaptive-task"))
 }
 
 pub fn register_binding(
@@ -95,7 +97,16 @@ pub fn register_binding(
     let state_path = if let Some(sp) = state_path {
         normalize_path(sp)
     } else {
-        let subpath = session_state_subpath(&repo);
+        let subpath = session_state_subpath(&repo).map_err(|err| match err {
+            crate::infrastructure::project_id_resolver::ProjectResolveError::Invalid {
+                message,
+                reason_code,
+            } => RegisterBindingError::Validation {
+                reason_code,
+                message,
+            },
+            other => RegisterBindingError::Store(other.into()),
+        })?;
         normalize_path(&PathBuf::from(&worktree).join(&subpath).to_string_lossy())
     };
     let binding = WorktreeBinding::new(WorktreeBindingFields {
@@ -117,7 +128,7 @@ pub fn register_binding(
             message: validation.message,
         });
     }
-    let store = WorktreeBindingStore::new(&repo);
+    let store = WorktreeBindingStore::new(&repo)?;
     store.upsert(&binding)?;
     Ok(binding)
 }
@@ -126,18 +137,18 @@ pub fn load_binding(
     session_id: &str,
     repo_root: &str,
 ) -> Result<Option<WorktreeBinding>, BindingStoreError> {
-    WorktreeBindingStore::new(repo_root).load(session_id)
+    WorktreeBindingStore::new(repo_root)?.load(session_id)
 }
 
 pub fn list_bindings(repo_root: &str) -> Result<Vec<WorktreeBinding>, BindingStoreError> {
-    WorktreeBindingStore::new(repo_root).list()
+    WorktreeBindingStore::new(repo_root)?.list()
 }
 
 pub fn remove_binding(
     session_id: &str,
     repo_root: &str,
 ) -> Result<Option<WorktreeBinding>, BindingStoreError> {
-    WorktreeBindingStore::new(repo_root).remove(session_id)
+    WorktreeBindingStore::new(repo_root)?.remove(session_id)
 }
 
 /// Rebuild a binding from legacy `metadata.json` and persist it. `Ok(None)`
@@ -164,7 +175,7 @@ fn recover_binding_from_metadata(
     metadata_root: &Path,
     repo_root: &Path,
 ) -> Result<Option<WorktreeBinding>, BindingStoreError> {
-    let state_subpath = session_state_subpath(repo_root);
+    let state_subpath = session_state_subpath(repo_root)?;
     let metadata = metadata_root
         .join(state_subpath)
         .join("sessions")
@@ -310,7 +321,7 @@ fn build_env_fallback_binding(
         .map(|s| s.to_string())
         .unwrap_or_default();
     let state_path = PathBuf::from(&normalized_worktree)
-        .join(session_state_subpath(&repo))
+        .join(session_state_subpath(&repo).ok()?)
         .to_string_lossy()
         .to_string();
     Some(WorktreeBinding::new(WorktreeBindingFields {

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/domain/audit.rs

@@ -1,9 +1,9 @@
 //! Audit record value objects, schema constants, and pure assembly/parse.
-use serde::{Deserialize, Serialize};
+use serde::Serialize;
 use serde_json::Value;
 
 pub const RECORD_CAP_BYTES: usize = 4096;
-pub const SCHEMA_VERSION: &str = "v1";
+pub const SCHEMA_VERSION: &str = "v2";
 pub const VALID_KINDS: &[&str] = &["worktree_remove", "branch_delete"];
 pub const VALID_INVOKERS: &[&str] = &[
     "canonical_wrapper",
@@ -23,7 +23,7 @@ pub fn is_secret_pattern(text: &str) -> bool {
         || lower.contains("password")
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize)]
 pub struct AuditRecord {
     pub schema_version: String,
     pub timestamp: String,
@@ -35,7 +35,7 @@ pub struct AuditRecord {
     pub host: String,
     pub invoker: String,
     pub branch: String,
-    pub worktree_path: String,
+    pub worktree: String,
     pub outcome: String,
     pub elapsed_ms: Option<i64>,
     pub correlation_id: Option<String>,
@@ -50,7 +50,7 @@ pub struct AuditRecord {
 pub struct AuditEventInput<'a> {
     pub kind: &'a str,
     pub branch: &'a str,
-    pub worktree_path: &'a str,
+    pub worktree: &'a str,
     pub invoker: &'a str,
     pub outcome: &'a str,
     pub session_id: Option<&'a str>,
@@ -78,7 +78,7 @@ pub fn assemble_record(input: AuditEventInput<'_>, runtime: AuditRuntimeFields<'
         "schema_version": SCHEMA_VERSION, "timestamp": runtime.timestamp, "kind": input.kind,
         "session_id": input.session_id, "pid": runtime.pid, "parent_pid": runtime.parent_pid,
         "cwd": runtime.cwd, "host": runtime.host, "invoker": input.invoker, "branch": input.branch,
-        "worktree_path": input.worktree_path, "outcome": input.outcome,
+        "worktree": input.worktree, "outcome": input.outcome,
         "elapsed_ms": input.elapsed_ms, "correlation_id": input.correlation_id,
         "truncated": false, "extra": extra_value,
     })
@@ -128,7 +128,11 @@ pub fn parse_record(payload: &Value) -> Option<AuditRecord> {
     let kind = obj.get("kind")?.as_str()?.to_string();
     let invoker = obj.get("invoker")?.as_str()?.to_string();
     let branch = obj.get("branch")?.as_str()?.to_string();
-    let worktree_path = obj.get("worktree_path")?.as_str()?.to_string();
+    let worktree = obj
+        .get("worktree")
+        .or_else(|| obj.get("worktree_path"))?
+        .as_str()?
+        .to_string();
     let outcome = obj.get("outcome")?.as_str()?.to_string();
     let pid = obj.get("pid")?.as_i64()?;
     let schema_version = obj
@@ -172,7 +176,7 @@ pub fn parse_record(payload: &Value) -> Option<AuditRecord> {
         host,
         invoker,
         branch,
-        worktree_path,
+        worktree,
         outcome,
         elapsed_ms,
         correlation_id,

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/domain/binding.rs

@@ -1,11 +1,17 @@
 //! Worktree binding records and validation primitives (product vocabulary).
 use super::paths::normalize_path;
-use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
 pub const CURRENT_SCHEMA_VERSION: i64 = 2;
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+/// A session ↔ worktree record.
+///
+/// `schema_version` is the version of the payload this value was *read
+/// from* (`from_dict` accepts v1 keys). It is informational: the struct is
+/// always held in v2 vocabulary and [`WorktreeBinding::to_dict`] always
+/// writes [`CURRENT_SCHEMA_VERSION`], so persisting a v1 record upgrades it
+/// on disk. Do not write `self.schema_version` back out.
+#[derive(Debug, Clone)]
 pub struct WorktreeBinding {
     pub session_id: String,
     pub worktree: String,
@@ -14,6 +20,7 @@ pub struct WorktreeBinding {
     pub git_common_dir: String,
     pub main_worktree: String,
     pub commit_ish: String,
+    /// Schema version of the source payload (see the type docs).
     pub schema_version: i64,
 }
 
@@ -75,6 +82,8 @@ impl WorktreeBinding {
         }))
     }
 
+    /// Serialize in the current (v2) vocabulary; always writes
+    /// [`CURRENT_SCHEMA_VERSION`], whatever `self.schema_version` says.
     pub fn to_dict(&self) -> Value {
         serde_json::json!({
             "session_id": self.session_id,

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/domain/paths.rs

@@ -100,23 +100,18 @@ pub fn home_dir(home: Option<&str>) -> PathBuf {
     if let Some(h) = home {
         return expanduser(h);
     }
-    if cfg!(windows) {
-        if let Ok(userprofile) = env::var("USERPROFILE") {
-            if !userprofile.is_empty() {
-                return expanduser(&userprofile);
+    let keys: &[&str] = if cfg!(windows) {
+        &["USERPROFILE", "HOME"]
+    } else {
+        &["HOME", "USERPROFILE"]
+    };
+    for key in keys {
+        if let Ok(value) = env::var(key) {
+            if !value.is_empty() {
+                return expanduser(&value);
             }
         }
     }
-    if let Ok(home_env) = env::var("HOME") {
-        if !home_env.is_empty() {
-            return expanduser(&home_env);
-        }
-    }
-    if let Ok(userprofile) = env::var("USERPROFILE") {
-        if !userprofile.is_empty() {
-            return expanduser(&userprofile);
-        }
-    }
     PathBuf::from(".")
 }
 

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/infrastructure/audit_dir.rs

@@ -6,7 +6,8 @@ use crate::infrastructure::env_keys::{
 use crate::infrastructure::project_id_resolver::{resolve_project_id, resolve_state_dir_name};
 use std::path::PathBuf;
 
-pub fn resolve_adaptive_task_shared_audit_dir() -> PathBuf {
+pub fn resolve_adaptive_task_shared_audit_dir(
+) -> Result<PathBuf, crate::infrastructure::project_id_resolver::ProjectResolveError> {
     let shared_env = std::env::var(ADAPTIVE_TASK_SHARED_DIR_ENV)
         .ok()
         .map(|v| v.trim().to_string())
@@ -20,7 +21,7 @@ pub fn resolve_adaptive_task_shared_audit_dir() -> PathBuf {
         .unwrap_or_default();
     if !shared_env.is_empty() {
         let base = expanduser(&shared_env);
-        return base.join("audit");
+        return Ok(base.join("audit"));
     }
     let project_root = std::env::var(NOVELER_PROJECT_ROOT_ENV)
         .unwrap_or_default()
@@ -32,7 +33,7 @@ pub fn resolve_adaptive_task_shared_audit_dir() -> PathBuf {
         std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."))
     };
     let root = std::fs::canonicalize(&base).unwrap_or(base);
-    let state_dir_name =
-        resolve_state_dir_name(Some(&resolve_project_id(Some(&root.to_string_lossy()))));
-    root.join(state_dir_name).join("shared").join("audit")
+    let project_id = resolve_project_id(Some(&root.to_string_lossy()))?;
+    let state_dir_name = resolve_state_dir_name(Some(&project_id))?;
+    Ok(root.join(state_dir_name).join("shared").join("audit"))
 }

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/infrastructure/audit_reader.rs

@@ -11,8 +11,10 @@ pub fn read_records(
     since: Option<chrono::DateTime<chrono::Utc>>,
     until: Option<chrono::DateTime<chrono::Utc>>,
 ) -> Vec<AuditRecord> {
-    let audit_dir = resolve_adaptive_task_shared_audit_dir();
     let mut out: Vec<AuditRecord> = Vec::new();
+    let Ok(audit_dir) = resolve_adaptive_task_shared_audit_dir() else {
+        return out;
+    };
     // Rotated archives first (oldest first), then the current file, so the
     // history is complete even after rotation.
     let mut files = list_archives(&audit_dir);
@@ -57,7 +59,7 @@ fn read_file_into(
             }
         }
         if let Some(wp) = worktree_path {
-            if record.worktree_path != wp {
+            if record.worktree != wp {
                 continue;
             }
         }

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/infrastructure/audit_writer.rs

@@ -40,7 +40,15 @@ pub fn suspicious_extra_message(keys: &[&str]) -> String {
 }
 
 pub fn record_event(input: AuditEventInput) -> Result<(), AuditWriteError> {
-    let audit_dir = resolve_adaptive_task_shared_audit_dir();
+    let audit_dir = match resolve_adaptive_task_shared_audit_dir() {
+        Ok(dir) => dir,
+        Err(err) => {
+            return Err(AuditWriteError {
+                stage: "project_id",
+                message: err.to_string(),
+            });
+        }
+    };
     if let Err(exc) = std::fs::create_dir_all(&audit_dir) {
         return Err(fail("mkdir", exc.to_string()));
     }
@@ -99,7 +107,9 @@ pub fn record_event(input: AuditEventInput) -> Result<(), AuditWriteError> {
 }
 
 pub fn reap_rotation_sentinel() {
-    let audit_dir = resolve_adaptive_task_shared_audit_dir();
+    let Ok(audit_dir) = resolve_adaptive_task_shared_audit_dir() else {
+        return;
+    };
     reap_stale_sentinel(&audit_dir.join(AUDIT_FILENAME));
 }
 

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/infrastructure/binding_store.rs

@@ -7,7 +7,9 @@
 use crate::domain::binding::{WorktreeBinding, CURRENT_SCHEMA_VERSION};
 use crate::domain::paths::normalize_path;
 use crate::infrastructure::git_adapter::git_output;
-use crate::infrastructure::project_id_resolver::{resolve_project_id, store_relative_path};
+use crate::infrastructure::project_id_resolver::{
+    resolve_project_id, store_relative_path, ProjectResolveError,
+};
 use fs2::FileExt;
 use serde_json::{json, Value};
 use std::fmt;
@@ -27,6 +29,8 @@ pub enum BindingStoreError {
         path: PathBuf,
         source: std::io::Error,
     },
+    /// The store path could not be built because project id resolution failed.
+    Project(ProjectResolveError),
 }
 
 impl BindingStoreError {
@@ -34,6 +38,10 @@ impl BindingStoreError {
         match self {
             BindingStoreError::Corrupt { .. } => "WORKTREE_BINDING_STORE_CORRUPT",
             BindingStoreError::Io { .. } => "WORKTREE_BINDING_STORE_IO",
+            BindingStoreError::Project(ProjectResolveError::Invalid { .. }) => "PROJECT_ID_INVALID",
+            BindingStoreError::Project(ProjectResolveError::Unreadable { .. }) => {
+                "WORKTREE_PROJECT_CONFIG_UNREADABLE"
+            }
         }
     }
 }
@@ -55,12 +63,19 @@ impl fmt::Display for BindingStoreError {
                 path.display(),
                 source
             ),
+            BindingStoreError::Project(err) => write!(f, "{err}"),
         }
     }
 }
 
 impl std::error::Error for BindingStoreError {}
 
+impl From<ProjectResolveError> for BindingStoreError {
+    fn from(err: ProjectResolveError) -> Self {
+        BindingStoreError::Project(err)
+    }
+}
+
 pub fn resolve_store_root(candidate: &Path) -> PathBuf {
     let git_common_dir = match git_output(
         candidate,
@@ -109,15 +124,15 @@ impl Drop for StoreLock {
 }
 
 impl WorktreeBindingStore {
-    pub fn new(main_worktree: impl AsRef<Path>) -> Self {
+    pub fn new(main_worktree: impl AsRef<Path>) -> Result<Self, BindingStoreError> {
         let normalized = normalize_path(&main_worktree.as_ref().to_string_lossy());
         let resolved = resolve_store_root(Path::new(&normalized));
-        let project_id = resolve_project_id(Some(&resolved.to_string_lossy()));
-        let path = resolved.join(store_relative_path(Some(&project_id)));
-        Self {
+        let project_id = resolve_project_id(Some(&resolved.to_string_lossy()))?;
+        let path = resolved.join(store_relative_path(Some(&project_id))?);
+        Ok(Self {
             main_worktree: resolved,
             path,
-        }
+        })
     }
 
     pub fn lock_path(&self) -> PathBuf {

{worktree_runtime-0.1.0a4 → worktree_runtime-0.1.1}/crates/worktree_runtime_core/src/infrastructure/git_adapter.rs

@@ -57,15 +57,6 @@ pub enum GitInvokeError {
     Exit { code: i32, stderr: String },
 }
 
-impl GitInvokeError {
-    /// `true` for failures of the git installation itself rather than of the
-    /// repository state (`Exit`). Callers use this to separate
-    /// "git is unavailable" from "not a repository / detached HEAD".
-    pub fn is_infrastructure(&self) -> bool {
-        !matches!(self, GitInvokeError::Exit { .. })
-    }
-}
-
 impl fmt::Display for GitInvokeError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {

worktree_runtime-0.1.1/crates/worktree_runtime_core/src/infrastructure/project_id_resolver.rs

@@ -0,0 +1,177 @@
+//! Project identifier resolution from pyproject.toml.
+use crate::domain::paths::{normalize_path, validate_project_id, LEGACY_PROJECT_ID};
+use crate::infrastructure::env_keys::NOVELER_REPO_ROOT_ENV;
+use crate::infrastructure::git_adapter::git_repo_root;
+use std::collections::HashMap;
+use std::fmt;
+use std::io::ErrorKind;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+
+pub const PROJECT_CONFIG_UNREADABLE: &str = "WORKTREE_PROJECT_CONFIG_UNREADABLE";
+
+/// A declared project id could not be used. Missing files and a missing
+/// `project_id` key are not errors; they stay [`LEGACY_PROJECT_ID`].
+#[derive(Debug, Clone)]
+pub enum ProjectResolveError {
+    Invalid {
+        message: String,
+        reason_code: String,
+    },
+    Unreadable {
+        message: String,
+    },
+}
+
+impl ProjectResolveError {
+    pub fn reason_code(&self) -> &str {
+        match self {
+            ProjectResolveError::Invalid { reason_code, .. } => reason_code,
+            ProjectResolveError::Unreadable { .. } => PROJECT_CONFIG_UNREADABLE,
+        }
+    }
+
+    pub fn message(&self) -> &str {
+        match self {
+            ProjectResolveError::Invalid { message, .. }
+            | ProjectResolveError::Unreadable { message } => message,
+        }
+    }
+}
+
+impl fmt::Display for ProjectResolveError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}: {}", self.reason_code(), self.message())
+    }
+}
+
+impl std::error::Error for ProjectResolveError {}
+
+pub(crate) const PROJECT_ID_TABLE_KEY: &str = "adaptive-task";
+const PROJECT_ID_FIELD: &str = "project_id";
+
+fn read_pyproject_project_id(normalized_root: &str) -> Result<String, ProjectResolveError> {
+    if normalized_root.is_empty() {
+        return Ok(LEGACY_PROJECT_ID.to_string());
+    }
+    let pyproject = Path::new(normalized_root).join("pyproject.toml");
+    let content = match std::fs::read_to_string(&pyproject) {
+        Ok(c) => c,
+        Err(err) if err.kind() == ErrorKind::NotFound => return Ok(LEGACY_PROJECT_ID.to_string()),
+        Err(err) => {
+            return Err(ProjectResolveError::Unreadable {
+                message: format!(
+                    "pyproject.toml at {} could not be read: {err}",
+                    pyproject.display()
+                ),
+            });
+        }
+    };
+    let data: toml::Value = match content.parse() {
+        Ok(d) => d,
+        Err(err) => {
+            return Err(ProjectResolveError::Unreadable {
+                message: format!(
+                    "pyproject.toml at {} could not be parsed: {err}",
+                    pyproject.display()
+                ),
+            });
+        }
+    };
+    let Some(project_id) = data
+        .get("tool")
+        .and_then(|t| t.get(PROJECT_ID_TABLE_KEY))
+        .and_then(|a| a.get(PROJECT_ID_FIELD))
+        .and_then(|v| v.as_str())
+    else {
+        return Ok(LEGACY_PROJECT_ID.to_string());
+    };
+    if project_id.is_empty() {
+        return Ok(LEGACY_PROJECT_ID.to_string());
+    }
+    validate_project_id(project_id).map_err(|(message, reason_code)| ProjectResolveError::Invalid {
+        message,
+        reason_code,
+    })
+}
+
+static PROJECT_ID_CACHE: Mutex<Option<HashMap<String, String>>> = Mutex::new(None);
+
+fn cached_project_id(normalized_root: &str) -> Result<String, ProjectResolveError> {
+    let mut cache = PROJECT_ID_CACHE.lock().unwrap();
+    let cache = cache.get_or_insert_with(HashMap::new);
+    if let Some(val) = cache.get(normalized_root) {
+        return Ok(val.clone());
+    }
+    let val = read_pyproject_project_id(normalized_root)?;
+    cache.insert(normalized_root.to_string(), val.clone());
+    Ok(val)
+}
+
+pub fn clear_cache() {
+    let mut cache = PROJECT_ID_CACHE.lock().unwrap();
+    *cache = None;
+}
+
+pub(crate) fn resolve_root(repo_root: Option<&str>) -> String {
+    let root = repo_root
+        .filter(|s| !s.is_empty())
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| std::env::var(NOVELER_REPO_ROOT_ENV).unwrap_or_default());
+    if root.is_empty() {
+        git_repo_root(None)
+    } else {
+        root
+    }
+}
+
+pub fn resolve_project_id(repo_root: Option<&str>) -> Result<String, ProjectResolveError> {
+    let root = resolve_root(repo_root);
+    if root.is_empty() {
+        return Ok(LEGACY_PROJECT_ID.to_string());
+    }
+    cached_project_id(&root)
+}
+
+/// Directory name for a project's state root. An id that fails
+/// `^[a-z][a-z0-9_-]{0,63}$` is [`ProjectResolveError::Invalid`] and is never
+/// turned into a path. An empty id stays `.{LEGACY_PROJECT_ID}`.
+pub fn resolve_state_dir_name(project_id: Option<&str>) -> Result<String, ProjectResolveError> {
+    let raw = match project_id {
+        Some(pid) if !pid.is_empty() => pid.to_string(),
+        Some(_) => return Ok(format!(".{LEGACY_PROJECT_ID}")),
+        None => resolve_project_id(None)?,
+    };
+    let pid = validate_project_id(&raw).map_err(|(message, reason_code)| {
+        ProjectResolveError::Invalid {
+            message,
+            reason_code,
+        }
+    })?;
+    Ok(format!(".{pid}"))
+}
+
+pub fn store_relative_path(project_id: Option<&str>) -> Result<PathBuf, ProjectResolveError> {
+    Ok(PathBuf::from(resolve_state_dir_name(project_id)?)
+        .join("state")
+        .join("worktree-runtime")
+        .join("bindings.json"))
+}
+
+pub fn state_dir(repo_root: Option<&str>) -> Result<String, ProjectResolveError> {
+    let root = resolve_root(repo_root);
+    if root.is_empty() {
+        return Ok(String::new());
+    }
+    let normalized_root = normalize_path(&root);
+    let project_id = resolve_project_id(Some(&normalized_root))?;
+    let state_name = resolve_state_dir_name(Some(&project_id))?;
+    Ok(PathBuf::from(&normalized_root)
+        .join(&state_name)
+        .to_string_lossy()
+        .to_string())
+}
+
+pub use crate::infrastructure::github_policy_loader::{
+    resolve_github_policy, resolve_main_branches,
+};