1001. 1001 fields.sort();
1002. 1002 format!(
1003. 1003 "title: {title} | type: {entity_type} | fields: {}",
1004. 1004 fields.join(",")
1005. 1005 )
1006. 1006}
1007. 1007
1008. 1008fn items_digest(payload: &Value) -> String {
1009. 1009 let title = payload.get("title").and_then(Value::as_str).unwrap_or("");
1010. 1010 let labels: Vec<String> = payload
1011. 1011 .get("items")
1012. 1012 .and_then(Value::as_array)
1013. 1013 .map(|items| {
1014. 1014 items
1015. 1015 .iter()
1016. 1016 .filter_map(|item| {
1017. 1017 item.get("label")
1018. 1018 .or_else(|| item.get("title"))
1019. 1019 .and_then(Value::as_str)
1020. 1020 .map(str::to_string)
1021. 1021 })
1022. 1022 .collect()
1023. 1023 })
1024. 1024 .unwrap_or_default();
1025. 1025 format!("title: {title} | items: {}", labels.join(","))
1026. 1026}
1027. 1027
1028. 1028fn default_digest(semantic_type: &str, payload: &Value) -> String {
1029. 1029 let title = payload
1030. 1030 .get("title")
1031. 1031 .and_then(Value::as_str)
1032. 1032 .unwrap_or(semantic_type);
1033. 1033 let mut keys: Vec<&str> = payload
1034. 1034 .as_object()
1035. 1035 .map(|obj| obj.keys().map(String::as_str).collect())
1036. 1036 .unwrap_or_default();
1037. 1037 keys.sort();
1038. 1038 format!("title: {title} | keys: {}", keys.join(","))
1039. 1039}
1040. 1040
1041. 1041/// Schema-driven identity digest (docs/design/68-context-engine.md §10):
1042. 1042/// which fields make a presentation distinguishable from another of the
1043. 1043/// same `semantic_type`. Dispatches by shape (the same grouping `SHAPES`
1044. 1044/// already uses — a `table`-shaped type and a `chart`-shaped type get
1045. 1045/// digested the same way as their siblings), with `entity` and the
1046. 1046/// checklist/timeline/itinerary family called out explicitly per the
1047. 1047/// design. Never a character-count truncation: each branch names the
1048. 1048/// fields that carry identity for its shape instead of cutting the payload
1049. 1049/// short.
1050. 1050pub fn identity_digest(semantic_type: &str, payload: &Value) -> String {
1051. 1051 match emit_tool_for(semantic_type) {
1052. 1052 Some("emit_metric_card") => canonical_compact(payload),
1053. 1053 Some("emit_research_card") => research_digest(payload),
1054. 1054 Some("emit_table_card") => table_digest(payload),
1055. 1055 Some("emit_chart_card") => chart_digest(payload),
1056. 1056 Some("emit_timeline_card") => items_digest(payload),
1057. 1057 _ if semantic_type == "entity" => entity_digest(payload),
1058. 1058 _ => default_digest(semantic_type, payload),
1059. 1059 }
1060. 1060}
1061. 1061
1062. 1062#[cfg(test)]
1063. 1063#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
1064. 1064mod tests {
1065. 1065 use super::*;
1066. 1066
1067. 1067 /// Real trigger: "Vak wants to use emit_metric_card — this needs your
1068. 1068 /// approval" under a card that had already rendered. Cards are Vak's own
1069. 1069 /// display channel, so every shape is open in every mode, through the
1070. 1070 /// engine `Core` builds — the one the capability preflight reads too.
1071. 1071 #[test]
1072. 1072 fn every_card_tool_is_allowed_in_every_mode_without_a_rule() {
1073. 1073 let dir = tempfile::tempdir().unwrap();
1074. 1074 let engine = crate::build_engine_with(&vak_config::Config::default(), &[]).unwrap();
1075. 1075 let args = serde_json::json!({});
1076. 1076 assert!(!SHAPES.is_empty());
1077. 1077 for shape in SHAPES {
1078. 1078 for mode in [
1079. 1079 vak_permission::Mode::ReadOnly,
1080. 1080 vak_permission::Mode::WorkspaceWrite,
1081. 1081 vak_permission::Mode::FullAccess,
1082. 1082 ] {
1083. 1083 assert!(
1084. 1084 matches!(
1085. 1085 engine.evaluate(shape.name, &args, mode, dir.path()),
1086. 1086 vak_permission::Decision::Allow
1087. 1087 ),
1088. 1088 "{} in {mode:?}",
1089. 1089 shape.name
1090. 1090 );
1091. 1091 }
1092. 1092 }
1093. 1093 assert_eq!(presenting_tool_names().len(), SHAPES.len());
1094. 1094 }
1095. 1095
1096. 1096 #[test]
1097. 1097 fn every_shape_has_a_unique_tool_name() {
1098. 1098 let names: std::collections::HashSet<&str> = SHAPES.iter().map(|s| s.name).collect();
1099. 1099 assert_eq!(names.len(), SHAPES.len(), "tool names must be unique");
1100. 1100 }
1101. 1101
1102. 1102 #[test]
1103. 1103 fn every_shape_has_at_least_one_semantic_type() {
1104. 1104 for shape in SHAPES {
1105. 1105 assert!(
1106. 1106 !shape.semantic_types.is_empty(),
1107. 1107 "{} has no semantic types",
1108. 1108 shape.name
1109. 1109 );
1110. 1110 }
1111. 1111 }
1112. 1112
1113. 1113 #[test]
1114. 1114 fn no_semantic_type_is_claimed_by_two_shapes() {
1115. 1115 let mut seen = std::collections::HashMap::new();
1116. 1116 for shape in SHAPES {
1117. 1117 for &t in shape.semantic_types {
1118. 1118 if let Some(prev) = seen.insert(t, shape.name) {
1119. 1119 panic!(
1120. 1120 "semantic_type `{t}` claimed by both {prev} and {}",
1121. 1121 shape.name
1122. 1122 );
1123. 1123 }
1124. 1124 }
1125. 1125 }
1126. 1126 }
1127. 1127
1128. 1128 #[tokio::test]
1129. 1129 async fn a_valid_call_is_acked_and_rebuilds_into_a_card() {
1130. 1130 let tool = EmitCardTool::all()
1131. 1131 .into_iter()
1132. 1132 .find(|t| t.name() == "emit_chart_card")
1133. 1133 .unwrap();
1134. 1134 let args = serde_json::json!({
1135. 1135 "semantic_type": "chart",
1136. 1136 "payload": {
1137. 1137 "chart_type": "line",
1138. 1138 "accessible_summary": "flat line",
1139. 1139 "series": [{"name": "s1", "points": [{"x": 1, "y": 2.0}]}]
1140. 1140 }
1141. 1141 });
1142. 1142 let out = tool
1143. 1143 .execute(&args, &ToolContext::new(std::env::temp_dir()))
1144. 1144 .await;
1145. 1145 assert!(!out.is_error, "expected Ok, got: {}", out.content);
1146. 1146 assert!(out.content.contains("already on screen"), "{}", out.content);
1147. 1147 assert!(
1148. 1148 !out.content.contains("semantic_type"),
1149. 1149 "ack must not echo the card"
1150. 1150 );
1151. 1151 let card = rebuild_call(
1152. 1152 "emit_chart_card",
1153. 1153 &args,
1154. 1154 &vak_delivery::built_in_skill_registry(),
1155. 1155 )
1156. 1156 .expect("the call's own arguments must rebuild into a card");
1157. 1157 assert_eq!(card.semantic_type, "chart");
1158. 1158 }
1159. 1159
1160. 1160 #[tokio::test]
1161. 1161 async fn an_invalid_payload_is_a_repairable_tool_error_not_a_silent_drop() {
1162. 1162 let tool = EmitCardTool::all()
1163. 1163 .into_iter()
1164. 1164 .find(|t| t.name() == "emit_chart_card")
1165. 1165 .unwrap();
1166. 1166 let args = serde_json::json!({
1167. 1167 "semantic_type": "chart",
1168. 1168 "payload": {"chart_type": "line", "series": []}
1169. 1169 });
1170. 1170 let out = tool
1171. 1171 .execute(&args, &ToolContext::new(std::env::temp_dir()))
1172. 1172 .await;
1173. 1173 assert!(
1174. 1174 out.is_error,
1175. 1175 "validator-rejected card must be an error the model sees"
1176. 1176 );
1177. 1177 assert!(out.content.contains("Fix the arguments"), "{}", out.content);
1178. 1178 }
1179. 1179
1180. 1180 #[tokio::test]
1181. 1181 async fn a_card_far_larger_than_the_tool_output_line_limit_still_rebuilds() {
1182. 1182 let long = "x".repeat(6000);
1183. 1183 let args = serde_json::json!({
1184. 1184 "semantic_type": "research.synthesis",
1185. 1185 "payload": {
1186. 1186 "sources": [{"title": "S", "url": "https://example.com"}],
1187. 1187 "takeaways": [{"text": long, "citation_indices": [1]}]
1188. 1188 }
1189. 1189 });
1190. 1190 let card = rebuild_call(
1191. 1191 "emit_research_card",
1192. 1192 &args,
1193. 1193 &vak_delivery::built_in_skill_registry(),
1194. 1194 )
1195. 1195 .expect("size must not matter: the card comes from the call arguments");
1196. 1196 assert_eq!(card.semantic_type, "research.synthesis");
1197. 1197 }
1198. 1198
1199. 1199 #[tokio::test]
1200. 1200 async fn execute_rejects_a_semantic_type_outside_its_own_shape() {
1201. 1201 let tool = EmitCardTool::all()
1202. 1202 .into_iter()
1203. 1203 .find(|t| t.name() == "emit_chart_card")
1204. 1204 .unwrap();
1205. 1205 let args = serde_json::json!({
1206. 1206 "semantic_type": "recipe.card",
1207. 1207 "payload": {}
1208. 1208 });
1209. 1209 let ctx = ToolContext::new(std::env::temp_dir());
1210. 1210 let out = tool.execute(&args, &ctx).await;
1211. 1211 assert!(out.is_error, "a chart tool must refuse a recipe type");
1212. 1212 }
1213. 1213
1214. 1214 #[tokio::test]
1215. 1215 async fn every_registered_semantic_type_across_all_shapes_renders() {
1216. 1216 let skills = vak_delivery::built_in_skill_registry();
1217. 1217 let mut failures = Vec::new();
1218. 1218 for tool in EmitCardTool::all() {
1219. 1219 for (name, semantic_type, payload) in conformance_cases()
1220. 1220 .into_iter()
1221. 1221 .filter(|(name, _, _)| *name == tool.name())
1222. 1222 {
1223. 1223 let args = serde_json::json!({"semantic_type": semantic_type, "payload": payload});
1224. 1224 let ctx = ToolContext::new(std::env::temp_dir());
1225. 1225 let out = tool.execute(&args, &ctx).await;
1226. 1226 if out.is_error {
1227. 1227 failures.push(format!(
1228. 1228 "{semantic_type} ({name}): rejected: {}",
1229. 1229 out.content
1230. 1230 ));
1231. 1231 continue;
1232. 1232 }
1233. 1233 let card = rebuild_call(name, &args, &skills);
1234. 1234 if card.as_ref().map(|c| c.semantic_type.as_str()) != Some(semantic_type) {
1235. 1235 failures.push(format!(
1236. 1236 "{semantic_type} ({name}): did not rebuild into a card"
1237. 1237 ));
1238. 1238 }
1239. 1239 }
1240. 1240 }
1241. 1241 assert!(
1242. 1242 failures.is_empty(),
1243. 1243 "{} registered types failed:\n{}",
1244. 1244 failures.len(),
1245. 1245 failures.join("\n")
1246. 1246 );
1247. 1247 }
1248. 1248
1249. 1249 #[test]
1250. 1250 fn prose_that_reads_as_a_card_gets_a_nudge_naming_the_offered_tool() {
1251. 1251 let recipes = vak_delivery::built_in_recipes();
1252. 1252 let offered: Vec<String> = EmitCardTool::all()
1253. 1253 .iter()
1254. 1254 .map(|t| t.name().to_string())
1255. 1255 .collect();
1256. 1256 let table = "Weekly moves:\n\n| Index | Change |\n|---|---|\n| Nifty | -0.22% |\n| Sensex | -0.65% |\n";
1257. 1257 let nudge = presentation_check_nudge(table, &offered, &recipes)
1258. 1258 .expect("a markdown table reads as a data grid");
1259. 1259 assert_eq!(
1260. 1260 nudge.tool, "emit_table_card",
1261. 1261 "the loop loads this for the redo"
1262. 1262 );
1263. 1263 assert!(
1264. 1264 nudge.text.contains("emit_table_card") && nudge.text.contains("data.grid"),
1265. 1265 "{}",
1266. 1266 nudge.text
1267. 1267 );
1268. 1268 // no admitted tool => no nudge (never tell the model to call something it lacks)
1269. 1269 assert!(presentation_check_nudge(table, &[], &recipes).is_none());
1270. 1270 }
1271. 1271
1272. 1272 #[test]
1273. 1273 fn a_request_that_reads_as_a_card_predicts_its_tool_and_small_talk_predicts_none() {
1274. 1274 let recipes = vak_delivery::built_in_recipes();
1275. 1275 let request = "Compare these:\n\n| Index | Change |\n|---|---|\n| Nifty | -0.22% |\n";
1276. 1276 assert!(predicted_card_tools(request, &recipes).contains("emit_table_card"));
1277. 1277 assert!(predicted_card_tools("hi there, how are you?", &recipes).is_empty());
1278. 1278 }
1279. 1279
1280. 1280 #[test]
1281. 1281 fn ordinary_conversation_gets_no_nudge() {
1282. 1282 let recipes = vak_delivery::built_in_recipes();
1283. 1283 let offered: Vec<String> = EmitCardTool::all()
1284. 1284 .iter()
1285. 1285 .map(|t| t.name().to_string())
1286. 1286 .collect();
1287. 1287 for text in [
1288. 1288 "Sure, happy to help. What would you like to do next?",
1289. 1289 "The capital of France is Paris.",
1290. 1290 "I renamed the variable and the build passes.",
1291. 1291 ] {
1292. 1292 assert!(
1293. 1293 presentation_check_nudge(text, &offered, &recipes).is_none(),
1294. 1294 "{text}"
1295. 1295 );
1296. 1296 }
1297. 1297 }
1298. 1298
1299. 1299 #[test]
1300. 1300 fn every_emit_tool_is_reachable_from_its_types() {
1301. 1301 for shape in SHAPES {
1302. 1302 for t in shape.semantic_types {
1303. 1303 assert_eq!(emit_tool_for(t), Some(shape.name));
1304. 1304 }
1305. 1305 }
1306. 1306 }
1307. 1307
1308. 1308 #[test]
1309. 1309 fn identity_digest_for_metric_is_the_whole_compact_payload() {
1310. 1310 let payload = serde_json::json!({"label": "Uptime", "value": 99.9, "unit": "%"});
1311. 1311 let digest = identity_digest("metric", &payload);
1312. 1312 // The whole card, canonical and compact — every field survives.
1313. 1313 assert!(digest.contains("\"label\":\"Uptime\""), "{digest}");
1314. 1314 assert!(digest.contains("\"value\":99.9"), "{digest}");
1315. 1315 assert!(digest.contains("\"unit\":\"%\""), "{digest}");
1316. 1316 }
1317. 1317
1318. 1318 #[test]
1319. 1319 fn identity_digest_for_research_synthesis_is_takeaways_and_sources() {
1320. 1320 let payload = serde_json::json!({
1321. 1321 "sources": [{"title": "Reuters", "url": "https://example.com/a"}],
1322. 1322 "takeaways": [{"text": "Markets fell", "citation_indices": [1]}]
1323. 1323 });
1324. 1324 let digest = identity_digest("research.synthesis", &payload);
1325. 1325 assert!(digest.contains("Markets fell"), "{digest}");
1326. 1326 assert!(digest.contains("Reuters"), "{digest}");
1327. 1327 assert!(digest.contains("https://example.com/a"), "{digest}");
1328. 1328 // Not the raw snippet field, which the design excludes.
1329. 1329 assert!(!digest.contains("snippet"), "{digest}");
1330. 1330 }
1331. 1331
1332. 1332 #[test]
1333. 1333 fn identity_digest_for_table_is_title_columns_row_count_and_first_row() {
1334. 1334 let payload = serde_json::json!({
1335. 1335 "title": "Q3 Budget",
1336. 1336 "columns": [{"key": "dept", "label": "Department"}, {"key": "spend", "label": "Spend"}],
1337. 1337 "rows": [{"dept": "Eng", "spend": 100}, {"dept": "Sales", "spend": 50}]
1338. 1338 });
1339. 1339 let digest = identity_digest("table", &payload);
1340. 1340 assert!(digest.contains("Q3 Budget"), "{digest}");
1341. 1341 assert!(
1342. 1342 digest.contains("dept") && digest.contains("spend"),
1343. 1343 "{digest}"
1344. 1344 );
1345. 1345 assert!(digest.contains("rows: 2"), "{digest}");
1346. 1346 assert!(digest.contains("Eng"), "{digest}");
1347. 1347 assert!(
1348. 1348 !digest.contains("Sales"),
1349. 1349 "digest must not include every row: {digest}"
1350. 1350 );
1351. 1351 }
1352. 1352
1353. 1353 #[test]
1354. 1354 fn identity_digest_for_chart_is_title_series_points_and_summary() {
1355. 1355 let payload = serde_json::json!({
1356. 1356 "title": "Revenue",
1357. 1357 "chart_type": "line",
1358. 1358 "accessible_summary": "rising trend",
1359. 1359 "series": [{"name": "actual", "points": [{"x": 1, "y": 2.0}, {"x": 2, "y": 3.0}]}]
1360. 1360 });
1361. 1361 let digest = identity_digest("chart", &payload);
1362. 1362 assert!(digest.contains("Revenue"), "{digest}");
1363. 1363 assert!(digest.contains("actual(2)"), "{digest}");
1364. 1364 assert!(digest.contains("rising trend"), "{digest}");
1365. 1365 }
1366. 1366
1367. 1367 #[test]
1368. 1368 fn identity_digest_for_entity_is_title_type_and_fields() {
1369. 1369 let payload = serde_json::json!({
1370. 1370 "title": "Paris",
1371. 1371 "type": "city",
1372. 1372 "population": "2.1M",
1373. 1373 "country": "France"
1374. 1374 });
1375. 1375 let digest = identity_digest("entity", &payload);
1376. 1376 assert!(digest.contains("Paris"), "{digest}");
1377. 1377 assert!(digest.contains("type: city"), "{digest}");
1378. 1378 assert!(digest.contains("population=2.1M"), "{digest}");
1379. 1379 assert!(digest.contains("country=France"), "{digest}");
1380. 1380 }
1381. 1381
1382. 1382 #[test]
1383. 1383 fn identity_digest_for_checklist_timeline_itinerary_is_title_and_item_labels() {
1384. 1384 let payload = serde_json::json!({
1385. 1385 "title": "Trip",
1386. 1386 "items": [{"label": "Fly to Paris"}, {"label": "Check into hotel"}]
1387. 1387 });
1388. 1388 for semantic_type in ["checklist", "timeline", "itinerary"] {
1389. 1389 let digest = identity_digest(semantic_type, &payload);
1390. 1390 assert!(digest.contains("Trip"), "{semantic_type}: {digest}");
1391. 1391 assert!(digest.contains("Fly to Paris"), "{semantic_type}: {digest}");
1392. 1392 assert!(
1393. 1393 digest.contains("Check into hotel"),
1394. 1394 "{semantic_type}: {digest}"
1395. 1395 );
1396. 1396 }
1397. 1397 }
1398. 1398
1399. 1399 #[test]
1400. 1400 fn identity_digest_for_anything_else_is_title_plus_top_level_keys() {
1401. 1401 let payload =
1402. 1402 serde_json::json!({"title": "Custom", "status": "ready", "artifact_path": "a.html"});
1403. 1403 let digest = identity_digest("ui.preview", &payload);
1404. 1404 assert!(digest.contains("Custom"), "{digest}");
1405. 1405 assert!(digest.contains("status"), "{digest}");
1406. 1406 assert!(digest.contains("artifact_path"), "{digest}");
1407. 1407 }
1408. 1408
1409. 1409 #[test]
1410. 1410 fn presentation_info_rebuilds_a_validated_call_into_a_ledger_ready_record() {
1411. 1411 let skills = vak_delivery::built_in_skill_registry();
1412. 1412 let args = serde_json::json!({
1413. 1413 "semantic_type": "chart",
1414. 1414 "payload": {
1415. 1415 "title": "Revenue",
1416. 1416 "chart_type": "line",
1417. 1417 "accessible_summary": "flat",
1418. 1418 "series": [{"name": "s1", "points": [{"x": 1, "y": 2.0}]}]
1419. 1419 }
1420. 1420 });
1421. 1421 let info = presentation_info("emit_chart_card", &args, &skills)
1422. 1422 .expect("a valid call must rebuild");
1423. 1423 assert_eq!(info.semantic_type, "chart");
1424. 1424 assert_eq!(info.title, "Revenue");
1425. 1425 assert!(
1426. 1426 info.identity_digest.contains("s1(1)"),
1427. 1427 "{}",
1428. 1428 info.identity_digest
1429. 1429 );
1430. 1430 assert!(info.schema_version > 0);
1431. 1431 assert!(!info.skill_id.is_empty());
1432. 1432 }
1433. 1433
1434. 1434 #[test]
1435. 1435 fn presentation_info_is_none_for_an_invalid_call() {
1436. 1436 let skills = vak_delivery::built_in_skill_registry();
1437. 1437 let args = serde_json::json!({"semantic_type": "chart", "payload": {"series": []}});
1438. 1438 assert!(presentation_info("emit_chart_card", &args, &skills).is_none());
1439. 1439 }
1440. 1440}
1441. 1441