llm-runner 0.2.1: session_ref helper for contract section 14.1

Every module that keeps state for a runner session needs the same reference,
so the derivation lives in the contract crate instead of being reimplemented.
The JCS object is built by hand: its three keys are already in JCS order, and
building it this way keeps the bytes independent of serde_json map ordering,
which a workspace build can change. Tests check it against the pinned vectors,
and the new vector file is listed with the others. The contract now says the
reference is a correlation key, not proof of identity.

Author: ualtinok

Cargo.lock

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.1
+
+- Add `session_ref(harness, project_root, session)`, the session reference from contract section 14.1, so every module that keeps state for a runner session derives the same value. It is checked against `test-vectors/llm-runner-v1/session-ref.json`.
+
 ## 0.1.1
 
 - Clarify that compaction conformance accepts runner-driven recovery or an interrupted run resumed by a sender's new send; runtime rules are unchanged.

crates/cortexkit-role-llm-runner/CHANGELOG.md

@@ -1128,7 +1128,11 @@ real process kill.
   provider, a backup or move participant) derives the same `session_ref`
   from the same bind identity, without asking the runner.
   `test-vectors/llm-runner-v1/session-ref.json` pins the derivation,
-  including a trailing slash and non-ASCII escaping.
+  including a trailing slash and non-ASCII escaping, and the crate's
+  `session_ref` function implements it.
+- [pinned] `session_ref` is a correlation key, not proof of identity: a
+  direct caller chooses its own bind fields. Authorization still rests on
+  the daemon-stamped principal and scope.
 
 ## 15. Conformance suite (planned)
 

crates/cortexkit-role-llm-runner/CONTRACT.md

@@ -11,7 +11,7 @@
 # suite.
 [package]
 name = "cortexkit-role-llm-runner"
-version = "0.2.0"
+version = "0.2.1"
 edition.workspace = true
 license.workspace = true
 repository.workspace = true
@@ -22,3 +22,4 @@ publish = true
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+sha2 = "0.10"

crates/cortexkit-role-llm-runner/Cargo.toml

@@ -30,8 +30,11 @@ pub mod read;
 pub mod retract;
 pub mod run;
 pub mod send;
+pub mod session_ref;
 pub mod subscribe;
 
+pub use session_ref::session_ref;
+
 /// The role name as `role.describe` reports it.
 pub const ROLE: &str = "llm-runner";
 
@@ -278,6 +281,7 @@ pub(crate) mod vectors {
         "run-result.json",
         "send.json",
         "session-change.json",
+        "session-ref.json",
         "subscribe.json",
     ];
 

crates/cortexkit-role-llm-runner/src/lib.rs

@@ -0,0 +1,105 @@
+//! The session reference (contract section 14.1).
+//!
+//! Every module that keeps state for a runner session derives the same short
+//! reference from the route bind's identity, so they agree without asking the
+//! runner. The reference is a correlation key, not proof of identity: a direct
+//! caller chooses its own bind fields.
+
+use sha2::{Digest, Sha256};
+
+/// The first 16 bytes of SHA-256 over the RFC 8785 (JCS) encoding of
+/// `{"harness", "project_root", "session"}`, as 32 lowercase hex characters.
+///
+/// Pass the three fields exactly as the route bind carried them. In particular
+/// `project_root` must not be canonicalised: a runner keys its durable state by
+/// those bytes, so a resolved symlink or a dropped trailing slash names a
+/// different session.
+pub fn session_ref(harness: &str, project_root: &str, session: &str) -> String {
+    // JCS orders members by key; these three keys are already in that order, and
+    // JCS string escaping matches serde_json's string encoding (quote,
+    // backslash and control characters only). Building the object by hand keeps
+    // the bytes independent of serde_json's map ordering, which a workspace build
+    // can change through the `preserve_order` feature.
+    let jcs = format!(
+        r#"{{"harness":{},"project_root":{},"session":{}}}"#,
+        json_string(harness),
+        json_string(project_root),
+        json_string(session),
+    );
+    let digest = Sha256::digest(jcs.as_bytes());
+    digest[..16]
+        .iter()
+        .map(|byte| format!("{byte:02x}"))
+        .collect()
+}
+
+fn json_string(value: &str) -> String {
+    serde_json::to_string(value).expect("a string always serializes")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::session_ref;
+    use serde::Deserialize;
+
+    #[derive(Deserialize)]
+    struct Vectors {
+        cases: Vec<Case>,
+    }
+
+    #[derive(Deserialize)]
+    struct Case {
+        name: String,
+        bind: Bind,
+        jcs: String,
+        session_ref: String,
+    }
+
+    #[derive(Deserialize)]
+    struct Bind {
+        harness: String,
+        project_root: String,
+        session: String,
+    }
+
+    #[test]
+    fn matches_the_pinned_vectors() {
+        let vectors: Vectors = serde_json::from_str(include_str!(
+            "../../../test-vectors/llm-runner-v1/session-ref.json"
+        ))
+        .unwrap();
+        assert!(vectors.cases.len() >= 4);
+        for case in vectors.cases {
+            let Bind {
+                harness,
+                project_root,
+                session,
+            } = &case.bind;
+            assert_eq!(
+                format!(
+                    r#"{{"harness":{},"project_root":{},"session":{}}}"#,
+                    super::json_string(harness),
+                    super::json_string(project_root),
+                    super::json_string(session)
+                ),
+                case.jcs,
+                "{}: JCS bytes",
+                case.name
+            );
+            assert_eq!(
+                session_ref(harness, project_root, session),
+                case.session_ref,
+                "{}",
+                case.name
+            );
+        }
+    }
+
+    #[test]
+    fn project_root_bytes_are_not_normalised() {
+        assert_ne!(
+            session_ref("runner", "/tmp/project/", "s1"),
+            session_ref("runner", "/tmp/project", "s1")
+        );
+    }
+}