//! Golden-bytes agreement for the worker protocol across the three
//! implementations. Every entry of the shared fixture must deserialize in
//! Rust exactly as in Python (wire.py) and TypeScript (protocol-v2.ts);
//! the fixture is how the three are known to agree.
use klbr_runtime::{
protocol::{
validate_envelope_target, Capability, Envelope, HelloBinding, NegotiationError,
TargetStamp, RELAY_PROTOCOL_VERSION, VERSION,
},
target::{NamespaceGeneration, NamespaceId, TargetId, TargetIdentity},
};
use serde_json::json;
use std::path::PathBuf;
fn fixtures_path() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.parent()
.expect("manifest has parent")
.join("tests/runtime-fixtures/envelopes.json")
}
fn load_fixture() -> Vec<serde_json::Value> {
let raw = std::fs::read_to_string(fixtures_path()).expect("shared envelope fixture");
serde_json::from_str(&raw).expect("fixture parses")
}
fn stamp() -> TargetStamp {
TargetStamp {
target_id: TargetId::parse("linux-build").unwrap(),
namespace_id: NamespaceId::parse("main").unwrap(),
namespace_generation: NamespaceGeneration::parse("ns-gen-remote-1").unwrap(),
}
}
fn resolved_identity() -> TargetIdentity {
TargetIdentity::new(
"mayer",
"chernobog.internal",
"Linux",
"aarch64",
"/home/mayer/.local/bin/python3.11",
"3.11.9",
"/srv/work/tangled",
Some("env-bundle-9f86d081".parse().unwrap()),
1,
)
.unwrap()
}
fn hello_binding() -> HelloBinding {
HelloBinding {
stamp: stamp(),
identity: Some(resolved_identity()),
}
}
fn reported_identity() -> klbr_runtime::protocol::WorkerIdentity {
let binding = hello_binding();
let identity = binding.identity.clone();
serde_json::from_value(json!({
"protocol_version": VERSION,
"relay_protocol_version": RELAY_PROTOCOL_VERSION,
"target": {
"stamp": {
"target_id": "linux-build",
"namespace_id": "main",
"namespace_generation": "ns-gen-remote-1"
},
"identity": identity,
},
"runtime": {
"platform": "Linux",
"arch": "aarch64",
"interpreter_path": "/home/mayer/.local/bin/python3.11",
"interpreter_version": "3.11.9",
"environment_fingerprint": "env-bundle-9f86d081",
"capabilities": [
{"capability": "shell", "shell": "/bin/zsh"},
{"capability": "file_system"},
{"capability": "imports"},
{"capability": "closures", "dill_available": false},
{"capability": "skill_manifest", "revision": "skills-2026-09-11"},
{"capability": "relay_framing", "version": 1}
]
}
}))
.unwrap()
}
#[test]
fn golden_fixture_deserializes_including_identity_entries() {
let entries = load_fixture();
assert_eq!(
entries.len(),
11,
"the shared fixture drives all three consumers"
);
let mut hello_remote = 0;
let mut execute_remote = 0;
for entry in &entries {
let envelope: Envelope = serde_json::from_value(entry.clone())
.unwrap_or_else(|e| panic!("fixture entry must deserialize: {e}: {entry}"));
if let klbr_runtime::protocol::Message::Hello { identity, .. } = &envelope.message {
if identity.is_some() {
hello_remote += 1;
// A golden remote hello must pass the host-side validation
// it will face in production.
identity
.as_ref()
.unwrap()
.validate(Some(&hello_binding()))
.expect("golden remote identity validates");
}
}
if envelope.target.is_some() {
execute_remote += 1;
validate_envelope_target(&envelope, Some(&stamp()))
.expect("golden remote stamp validates");
}
}
assert_eq!(hello_remote, 1, "exactly one golden remote hello");
assert_eq!(execute_remote, 1, "exactly one golden remote execute");
}
#[test]
fn golden_remote_stamp_rejects_a_forged_local_claim() {
// The golden remote EXECUTE envelope (index 10) carries the stamp; the
// same bytes under a LOCAL host expectation are a forged identity.
let envelope: Envelope = serde_json::from_value(load_fixture()[10].clone()).unwrap();
let err = validate_envelope_target(&envelope, None).expect_err("forged stamp is fatal");
assert!(err
.to_string()
.contains("must not claim a remote target stamp"));
// A LOCAL golden envelope claiming nothing stays fine.
let local: Envelope = serde_json::from_value(load_fixture()[1].clone()).unwrap();
validate_envelope_target(&local, None).expect("local golden envelope validates");
}
#[test]
fn remote_launch_requires_a_reported_binding() {
let mut reported = reported_identity();
reported.target = None;
let err = reported
.validate(Some(&hello_binding()))
.expect_err("binding required");
assert_eq!(
err.downcast_ref::<NegotiationError>(),
Some(&NegotiationError::TargetBindingMissing)
);
}
#[test]
fn each_identity_field_mismatch_is_its_own_typed_error() {
// platform
let mut reported = reported_identity();
reported.runtime.platform = "Darwin".into();
let err = reported.validate(Some(&hello_binding())).err().unwrap();
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::RuntimeMismatch {
field: "platform",
..
})
),
"{err}"
);
// interpreter
let mut reported = reported_identity();
reported.runtime.interpreter_path = "/usr/bin/python3".into();
let err = reported.validate(Some(&hello_binding())).err().unwrap();
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::RuntimeMismatch {
field: "interpreter_path",
..
})
),
"{err}"
);
// workspace cwd
let mut reported = reported_identity();
if let Some(binding) = reported.target.as_mut() {
binding.identity.as_mut().unwrap().cwd = "/home/mayer".into();
}
let err = reported.validate(Some(&hello_binding())).err().unwrap();
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::BindingMismatch { field: "cwd", .. })
),
"{err}"
);
// namespace generation
let mut reported = reported_identity();
if let Some(binding) = reported.target.as_mut() {
binding.stamp.namespace_generation = NamespaceGeneration::parse("ns-gen-other").unwrap();
}
let err = reported.validate(Some(&hello_binding())).err().unwrap();
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::BindingMismatch {
field: "namespace_generation",
..
})
),
"{err}"
);
}
#[test]
fn version_mismatches_stay_fatal_and_typed() {
let mut reported = reported_identity();
reported.protocol_version = 2;
let err = reported.validate(Some(&hello_binding())).err().unwrap();
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::WorkerProtocolVersionMismatch {
reported: 2,
supported: 1
})
),
"{err}"
);
let mut reported = reported_identity();
reported.relay_protocol_version = 7;
let err = reported.validate(Some(&hello_binding())).err().unwrap();
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::RelayProtocolVersionMismatch {
reported: 7,
supported: 1
})
),
"{err}"
);
}
#[test]
fn advertised_but_unusable_capability_is_expressible_and_checkable() {
let identity = reported_identity().runtime;
let closures = identity
.capabilities
.iter()
.find(|c| matches!(c, Capability::Closures { .. }))
.unwrap();
// Advertised but unusable: the host sees exactly that, before admission.
assert!(!closures.is_usable());
assert_eq!(
closures.unusable_reason(),
Some("dill is not importable in the worker namespace")
);
let required = Capability::Closures {
dill_available: true,
};
assert!(
!identity.supports(&required),
"an unusable advertised capability is not support"
);
let shell = Capability::Shell {
shell: Some("/bin/zsh".into()),
};
assert!(identity.supports(&shell));
// A newer relay framing is advertised-but-unusable against this host.
let newer = Capability::RelayFraming {
version: RELAY_PROTOCOL_VERSION + 1,
};
assert!(!newer.is_usable());
assert!(newer
.unusable_reason()
.unwrap()
.contains("newer than the host supports"));
}
#[test]
fn incomplete_runtime_identity_is_typed_not_crashy() {
let reported = serde_json::from_value::<klbr_runtime::protocol::WorkerIdentity>(json!({
"protocol_version": VERSION,
"relay_protocol_version": RELAY_PROTOCOL_VERSION,
"runtime": {
"platform": "",
"arch": "aarch64",
"interpreter_path": "/usr/bin/python3",
"interpreter_version": "3.11.9",
"capabilities": []
}
}))
.unwrap();
let err = reported.validate(None).err().unwrap();
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::RuntimeIncomplete { field: "platform" })
),
"{err}"
);
}
#[test]
fn unknown_fields_stay_rejected_in_the_extended_shapes() {
let bad_hello = json!({
"version": VERSION,
"session_id": "s",
"generation": "g",
"message": {
"kind": "hello",
"token": "t",
"role": "workbench",
"revision": null,
"slots": [],
"bogus": true
}
});
assert!(
serde_json::from_value::<Envelope>(bad_hello).is_err(),
"unknown hello fields stay rejected"
);
let bad_stamp = json!({
"target_id": "t",
"namespace_id": "n",
"namespace_generation": "g",
"extra": 1
});
assert!(
serde_json::from_value::<TargetStamp>(bad_stamp).is_err(),
"unknown stamp fields stay rejected"
);
}
#[test]
fn a_stamp_echo_without_measured_identity_is_never_admitted() {
// The python echo frame carries ONLY the stamp: the binding check
// passes at the relay, but it is not evidence about the target, so the
// host-facing check refuses it instead of merging it into identity.
let unmeasured = HelloBinding {
stamp: stamp(),
identity: None,
};
let reported = serde_json::from_value::<klbr_runtime::protocol::WorkerIdentity>(json!({
"protocol_version": VERSION,
"relay_protocol_version": RELAY_PROTOCOL_VERSION,
"target": unmeasured,
"runtime": {
"platform": "Linux",
"arch": "aarch64",
"interpreter_path": "/home/mayer/.local/bin/python3.11",
"interpreter_version": "3.11.9",
"capabilities": []
}
}))
.unwrap();
let err = reported
.validate(Some(&hello_binding()))
.expect_err("unmeasured is fatal");
assert!(
matches!(
err.downcast_ref::<NegotiationError>(),
Some(NegotiationError::TargetIdentityUnmeasured)
),
"{err}"
);
assert!(err.to_string().contains("not evidence about the target"));
}